Recipe Sharing

Audience: User, Org Admin, Support, Developer Related: Overview · Editing And Cache · Email · Data Retention

Blackcap supports email-ready PDF sharing and Blackcap-to-Blackcap share links. Share lifecycle states include pending, completed/fully used, expired, rejected, and revoked behavior as applicable.

Recipe deletion dependencies consider an active pending share, not an expired or fully used share. Share management, retention, recipient rules, notifications, thumbnails, and accepted-recipe ownership are organization-aware.

Blackcap Pi has two sharing workflows:

1. Email-ready recipe PDFs for sending a readable copy to someone.
2. Blackcap-to-Blackcap recipe sharing for importing one or more recipes into another Blackcap organization.

Both workflows are available from authenticated recipe screens where the user has the required recipe/share permissions.

📄 Email-ready PDF sharing

The email PDF workflow creates a share-friendly PDF that is separate from the e-ink optimized recipe render. It is meant for people who just need a readable copy, not a Blackcap import.

Shared PDFs can include:

• recipe title
• recipe image/thumbnail when available
• description
• ingredients
• instructions/steps
• notes

The email form supports:

• one or more recipients
• optional personal message
• optional sender name
• configurable shared PDF page size: Letter, A4, or Legal
• organization-scoped recipe share orientation: Portrait or Landscape
• organization-scoped Preferred Recipe Units: As Written, US Units, or Metric
• cleanup of temporary shared PDF files after sending

Email delivery uses the configured SMTP/email settings. For bulk recipient scenarios, prefer sending individual notification messages or BCC behavior supported by the share service so providers are less likely to reject the message as recipient-list spam.

Share PDF orientation is intentionally share-only. It affects email-ready PDF layout, not the normal Recipe Library cache, default-display recipe render, kiosk render, Let’s Cook render, or display preview path. Preferred Recipe Units do affect the share PDF content and should use the same effective recipe body used by recipe rendering and shopping-list generation.

On landscape/full-width share PDFs, the ingredients section may split into two balanced columns when that improves readability. Instructions and notes remain full-width below the ingredient section.

🔗 Blackcap-to-Blackcap sharing

The newer recipe sharing workflow creates a tokenized share link. Compatible Blackcap installs can review the share and import the recipe data into their own organization.

Current implementation supports:

• sharing one recipe or a group of recipes
• outbound share links owned by the sender organization
• share status: active, revoked, expired, exhausted, or similar lifecycle states
• optional expiration
• optional recipient restrictions by email/target
• optional maximum import/consumption limits
• same-platform local recipient detection
• pending recipient notifications in Shared with Me
• accept/import and dismiss/reject flows
• outbound share management and revocation
• import/consumption audit rows

The same-platform organization-to-organization path is implemented for local Blackcap users/organizations. If a recipient email matches a user on the same Blackcap install, Blackcap can create local pending-share notifications instead of relying only on an email link.

External Blackcap-to-Blackcap import is implemented through tokenized manifest/payload endpoints for compatible Blackcap installs. Treat it as a same-app protocol: the receiving Blackcap instance must understand the payload schema version produced by the sender.

📨 Notification behavior

When notification email is enabled, Blackcap sends recipients a review/import link for the shared recipe or recipe group. Same-platform recipients can also see the share in their Shared with Me area.

Notification email is informational. Access still depends on the share token, share status, recipient restrictions, expiration, and remaining import count.

✅ Accept, reject, and revoke

Recipients can review a pending share and import it into their active organization context. They can also dismiss/reject a share they do not want.

Senders can revoke active outbound shares. Revocation prevents future imports, but it does not delete copies that recipients already imported.

A recipient import creates organization-owned recipe rows in the receiving organization. This is a copy, not a live reference back to the sender.

📦 What gets copied on import

A successful Blackcap-to-Blackcap import copies the recipe snapshot needed for the recipient organization to own and use the recipe:

• recipe title and metadata
• editable recipe content
• ingredients/instructions/notes captured in the payload
• selected recipe type and layout behavior
• normal recipe image/thumbnail when available
• source/share provenance metadata so the import can be understood later

Recipe IDs are organization-scoped. If the sender and recipient both have a recipe with the same friendly ID, that is safe as long as every lookup includes organization context.

🚫 What does not get copied

Imports do not copy sender-owned operational or security data:

• sender users, roles, or permissions
• sender organization settings
• provider credentials, SMTP settings, OAuth tokens, or connection secrets
• shopping lists or recipe cart state
• background job/cache history
• sender audit log history
• personal Made It photos/ratings
• system/platform resources

The recipient may build its own cache/render artifacts after import.

🔐 Token and security model

Share links use public identifiers plus secret tokens. Tokens are not stored as raw public secrets in ordinary share rows. Blackcap stores token hashes and encrypted token copies only where needed for authorized copy/reuse flows.

At a high level, share access checks include:

• share exists and is active
• token matches the stored hash
• share is not expired or exhausted
• recipient restrictions allow the requester/importing user
• importing user has permission to import into their active organization
• all resulting recipe writes are scoped to the recipient organization

Direct recipe IDs alone are not trusted for cross-organization access.

🏢 Organization scoping expectations

Recipe sharing is organization-aware:

• outbound shares belong to the sender organization
• pending notifications belong to recipient users/organizations
• import/consumption rows are scoped to the receiving organization
• imported recipe content is written to the receiving organization
• system admins do not see every organization's share/business data by default; they must intentionally switch organization context for support

This keeps a single self-hosted Pi safe today and prepares the same data model for future hosted deployments.

📁 Recipe file import/export

Recipe Sharing also owns generic recipe-file exchange. This keeps file-based import/export alongside the existing email PDF and Blackcap share-link flows instead of creating a separate recipe migration page.

Current file format support:

• Paprika Recipe Format (.paprikarecipes and .paprikarecipe)
• Schema.org Recipe JSON-LD (.jsonld and .json)
• Cooklang Recipe (.cook, plus multi-recipe .zip files containing .cook entries)

Export to File

The existing share popup includes an Export to File tab. This popup is used for both single-recipe share actions and grouped/multi-recipe share actions, so file export automatically supports:

• one selected recipe
• multiple selected recipes from the existing group share flow

Supported exports are recipe-content focused and can include one or more selected recipes:

• Paprika exports a .paprikarecipes ZIP archive. For one recipe the archive contains one .paprikarecipe entry; for a group export it contains one .paprikarecipe entry per selected recipe. Each inner .paprikarecipe entry is gzip-compressed JSON.
• Schema.org JSON-LD exports a .jsonld file. A single-recipe export is a Recipe object with @context; a multi-recipe export uses an @graph containing one Recipe object per selected recipe.
• Cooklang exports a single .cook file for one recipe or a .zip containing one .cook file per selected recipe.

Exported data includes human-readable ingredients, directions, notes, servings/time metadata, source/source URL, nutrition text when available, recipe category/type when available, and image references when the format supports them. Paprika exports also include the primary recipe image as base64 photo data when available.

Import from File

The Tools → Recipe Sharing page has four tabs:

1. Import from Link
2. Import from File
3. Shared With Me
4. Share Links

The Import from File tab is intentionally generic so additional file formats can be added without redesigning the page.

The import flow is:

1. Choose the file format.
2. Browse for one or more recipe files that use that selected format.
3. Load the selected file(s) into memory for preview.
4. Review all recipes found across all selected files.
5. Optionally edit each selected recipe name and description.
6. Optionally adjust each recipe layout and recipe type. Layout defaults to the receiving organization default and recipe type defaults to Dinner.
7. Uncheck any recipes that should not be imported.
8. Import the selected recipes.

Preview does not create recipes, write extracted files to recipe cache locations, or queue render/cache jobs. The file(s) must still be present in the browser file input when the user imports; refreshing the page requires choosing them again.

Current import support includes:

• one or more Paprika .paprikarecipe files, each containing one gzip-compressed recipe JSON document
• one or more Paprika .paprikarecipes ZIP archives, each containing one or many .paprikarecipe entries
• Schema.org JSON-LD .jsonld or .json files containing one Recipe object or a graph/list of Recipe objects
• Cooklang .cook files containing one recipe
• Cooklang .zip files containing one or many .cook entries
• duplicate warnings by file-format UID, source URL, recipe name + source, or recipe name
• exact file-format UID or source URL matches update the existing recipe on import, using the current preview values for name, description, layout, and recipe type

A successful file import creates normal Blackcap recipe rows through the recipe service layer, saves editable recipe content, stores file-import metadata in the recipe payload, copies safe embedded image data when present, queues search index rebuild, and queues the normal recipe cache/render build.

Imported embedded images, such as Paprika photo data, are treated as user-supplied source images. Soft recipe archive/delete should preserve those source images until permanent purge so Database Admin restore can regenerate thumbnails when possible.

Paprika is a trademark of its owner. Blackcap is not affiliated with or endorsed by Paprika.

Share-link history and local thumbnails

The Share Links tab defaults to Active and can show Expired and Completed records that still exist. Active means the link remains consumable; Completed means consumption closed the link; Expired also includes revoked, uncompleted links. Historical rows do not show active actions.

When another Blackcap environment imports a shared recipe, the protected payload carries a bounded base64 package of the sender’s local thumbnail/image when available. The consuming organization decodes that package into its own recipe cache, generates its own normal thumbnail, and does not depend on the source environment URL after import. A protected image URL remains as compatibility fallback for older payloads. Missing image data is non-fatal and the normal cache build remains the fallback.

The imported recipe also preserves the sender organization’s canonical manually_edited and edited_at values. The existence of editable recipe content alone does not mark an imported recipe as edited.

The scheduled purge policy removes recipe-share audit records after 7 days by default. It does not generally purge expired/completed recipe_shares rows, so those rows remain available to history filters while they exist.

Share-link history behavior

The navigation/page name remains 📥 Recipe Sharing. Its outbound-history tab is named Share Links and supports Active, Expired, and Completed views. A link is visible in Completed as soon as the sender records at least one successful consumption. A partially consumed multi-use link may therefore remain in Active while also appearing in Completed; management actions remain available only from Active. Completing a link does not automatically delete its recipe_shares row. Share audit rows follow the configured seven-day default purge policy, while share rows are removed only by explicit lifecycle cleanup such as purging their source recipe/organization.

Actionable share dependencies

Only a share that can still be consumed blocks permanent recipe deletion. Expired, completed, fully consumed, revoked, invalidated, or failed shares are historical and non-blocking. Share validation, Recipe Sharing status, and recipe dependency evaluation use the same UTC-aware lifecycle helper.