@spree/docs 0.1.192 → 0.1.194

package/dist/developer/core-concepts/products.md

@@ -716,6 +716,115 @@ The API automatically returns the correct price based on the current currency an
 
 See the [Pricing](pricing.md) guide for details on Price Lists, Price Rules, and market-specific pricing.
 
+## Digital products
+
+**A digital product is an ordinary product whose variant delivers without shipping — its [delivery profile](fulfillments.md) is a digital one, so buying it grants the customer a download instead of dispatching a parcel.** Nothing about the catalog model changes — you still have a product, its variants, and its prices. What that variant hands over is usually a **digital asset** it carries (an e‑book, a design file) or a value a provider mints on demand (a license key) — but the file is the optional deliverable, not what makes the product digital.
+
+Two ideas are worth separating up front, because they are independent:
+
+- **Being digital** is a delivery decision. A variant is digital when its [delivery profile](fulfillments.md) is a digital one — that variant needs no shipping address, and a cart made up entirely of digital variants skips the delivery step at checkout.
+- **Carrying downloadable files** is a catalog decision. Any variant can own digital assets — including a physical one, so a boxed product can ship a warranty PDF or a setup guide alongside the goods.
+
+Most digital products are both: a digital variant that carries the files it delivers. But the two are decoupled on purpose, so "ships nothing" and "hands over a file" can be mixed as a merchant needs.
+
+```mermaid
+erDiagram
+    Product ||--|{ Variant : "has"
+    Variant ||--o{ DigitalAsset : "carries"
+    DigitalAsset ||--o{ DigitalLink : "granted as"
+    LineItem ||--o{ DigitalLink : "purchased in"
+    DigitalAsset {
+        string provider_type "blank = uploaded file"
+        int authorized_clicks "nullable, falls back to store"
+        int authorized_days "nullable, falls back to store"
+    }
+    DigitalLink {
+        string token "the download credential"
+        int access_counter "downloads spent"
+    }
+```
+
+### Assets live on the variant
+
+A digital asset (`Spree::DigitalAsset`) belongs to a variant and holds either an uploaded file or a reference to a provider that produces the deliverable on demand (see [Where the file comes from](#where-the-file-comes-from) below). Uploaded files go to **private storage** — they are only ever served through a short‑lived, signed link, never a public URL.
+
+You attach assets to a variant from the product's **Digital files** card in the dashboard, or through the Admin API nested under the product:
+
+
+```typescript Admin SDK
+// 1. Ask for a private-storage upload slot, then PUT the file to the returned URL.
+const { direct_upload, signed_id } = await adminClient.directUploads.create({
+  private: true, // digital files are only ever served through a signed link
+  blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },
+})
+await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })
+
+// 2. Attach the uploaded blob to the product's default variant.
+await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', {
+  signed_id,
+  authorized_clicks: 5, // optional — omit to inherit the store default
+  authorized_days: 30,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/digital_assets' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "signed_id": "eyJfcmFpbHMi...", "authorized_clicks": 5, "authorized_days": 30 }'
+```
+
+
+> **WARNING:** Digital files must be uploaded to **private storage**. The Admin API refuses a blob that landed on the public service — attaching never moves a file between services, so a public upload would stay publicly readable while looking attached. Request the direct upload with `private: true`.
+
+Replacing an asset's file keeps every download link that was already issued working: links resolve through the asset, not the underlying blob, so a merchant can swap a corrected file mid‑sale without breaking anyone's access.
+
+### A purchase grants download links
+
+When an order is placed, digital assets fulfill themselves. The digital fulfillment provider runs automatically (it needs no address and no manual action) and, for each purchased unit, creates one **download link** (`Spree::DigitalLink`) per asset on the variant. Buy three copies of a two‑file bundle and the buyer gets six links. Re‑running fulfillment is idempotent — it never duplicates links.
+
+A download link is the customer's **grant**: a globally unique token, a counter of downloads spent, and its own copy of the allowance. The token *is* the credential — it identifies the store on its own, which is why an emailed link works without any API key.
+
+Customers reach their files two ways:
+
+- **By email.** On order placement, `Spree::DigitalAssetMailer` sends a "your files are ready" message with the links — a message of its own, separate from the order confirmation, so it can be re‑sent from the order page later.
+- **From their account.** A signed‑in customer sees every link they have ever been granted, across all their orders, through the customer downloads endpoint.
+
+> **NOTE:** The files-ready email is only sent when the order actually has digital links and the store has consumer transactional emails enabled. A store that delivers files through its own storefront or webhooks can leave it off.
+
+### Downloading, and the allowance
+
+A download is a `GET` against the link's token. Every download runs the same guarded sequence, and the customer's allowance is only spent once a deliverable is actually in hand:
+
+1. **The grant must be live** — attempts remaining, and not past its expiry.
+2. **The signed‑URL window must be open** — clamped to whatever is shorter, the store's link lifetime or the link's own remaining days.
+3. **The deliverable is produced** — see providers below. This step is allowed to fail.
+4. **The download is charged** — the counter is incremented under a lock.
+5. **The file is handed over** — a redirect to a signed URL, or an inline body.
+
+The ordering is deliberate: producing the deliverable comes *before* charging the click, so a provider outage or a missing file returns an honest error and **costs the customer nothing**. Two allowances govern access, both falling back to store settings when the asset leaves them blank:
+
+| Field | Meaning | Store default |
+| --- | --- | :---: |
+| `authorized_clicks` | How many times the file may be downloaded | `5` |
+| `authorized_days` | How long after purchase the link stays valid | `7` |
+
+Store‑wide defaults and their on/off switches live at **Settings → Store**; the separate `digital_asset_link_expire_time` preference caps how long a single signed URL lives (default 5 minutes, never more than an hour) because that URL is a bearer credential. When a customer runs out of downloads or a file was replaced mid‑flight, an admin can restore access by resetting the link from the order page, which zeroes the counter and restarts the clock.
+
+Each successful download publishes an event you can subscribe to:
+
+| Event | Published when |
+| --- | --- |
+| `digital_link.downloaded` | A customer successfully downloads a file (after the click is charged) |
+
+### Where the file comes from
+
+By default a digital asset delivers its uploaded file. But the last step — "hand something over" — is pluggable through a **digital asset provider**, so the deliverable can instead be minted on demand: a license key from your billing system, an entitlement from internal software, or a signed link to a file on your own host. The purchase, the grant, the allowance, and the email are identical either way; only the production of the deliverable changes.
+
+A blank `provider_type` on an asset means the built‑in file provider — the uploaded‑file behavior described above. Registering your own provider adds it as a source on the Digital files card, so a merchant can pick it when adding an asset.
+
+> **TIP:** To build one, see the [Build a Custom Digital Asset Provider](../how-to/custom-digital-asset-provider.md) how‑to. It covers the `#deliver` contract, per‑asset settings, and registration.
+
 ## Categories
 
 There are two ways to group products, and they answer different questions.
@@ -934,6 +1043,7 @@ See [Sales Channels](channels.md) for the full channel lifecycle, including defa
 - [Pricing](pricing.md) — Price Lists, Price Rules, and market-specific pricing
 - [Inventory](inventory.md) — Stock management and backorders
 - [Media](media.md) — Image management
+- [Build a Custom Digital Asset Provider](../how-to/custom-digital-asset-provider.md) — Deliver a license key or external file instead of an uploaded one
 - [Translations](translations.md) — Translating product content
 - [Search & Filtering](search-filtering.md) — Full-text search and Ransack filtering
 - [Store SDK Products](../sdk/store/products.md) — Listing, fetching, filtering, and categories via `client.products`

package/dist/developer/how-to/custom-digital-asset-provider.md

@@ -76,7 +76,7 @@ setting :region, :select, in: %w[us eu], default: 'us'
 setting :auto_revoke, :boolean, default: false
 ```
 
-Field types are `:string`, `:number`, `:boolean`, and `:select` (pass `in:` for the choices). The merchant's answers are stored on the asset and read back through `digital_asset.provider_settings`, a plain hash keyed by the setting name:
+Field types are `:string`, `:number`, `:boolean`, and `:select` (pass `in:` for the choices). Your declarations become the provider's `settings_schema`, which the admin `providers` endpoint exposes so the dashboard can render the form. The merchant's answers are stored on the asset — under one key, `metadata['provider']`, so they never collide with other developer metadata — and read back through `digital_asset.provider_settings`, a plain hash keyed by the setting name:
 
 ```ruby
 digital_asset.provider_settings['pool_name'] # => "winter-sale"
@@ -94,6 +94,8 @@ end
 
 Once registered, the provider appears as a source on the product's **Digital files** card: the **Add** button becomes a menu offering **Upload a file** alongside each registered provider. Picking your provider creates an asset with its `provider_type` set and no file attached.
 
+> **NOTE:** Registration is what makes a `provider_type` valid. An asset validates that its `provider_type` names a registered provider, so an unregistered or misspelled class name is rejected with a 422 rather than failing at download time. A blank `provider_type` is always the built-in `File` provider.
+
 ## The download contract
 
 Every download follows the same order, and a provider only participates in the last step:
@@ -130,4 +132,5 @@ Spree::DigitalDelivery.new(inline_value: 'ABCD-1234-EFGH', content_type: 'text/p
 ## Related documentation
 
 - [Digital products](/use-case/digital-products/capabilities) — what the feature does for merchants
-- [Build a Custom Delivery Rate Provider](/v6/developer/how-to/custom-delivery-rate-provider) — a provider strategy that *does* use an integration, for contrast
+- [Products](../core-concepts/products.md#digital-products) — how digital assets, links, and downloads fit together
+- [Build a Custom Delivery Rate Provider](custom-delivery-rate-provider.md) — a provider strategy that *does* use an integration, for contrast

package/dist/developer/how-to/sell-digital-products.md

@@ -3,18 +3,75 @@ title: Sell Digital Products
 description: Digital goods in Spree — a digital delivery profile, instant fulfillment without a shipping address, and delivering files or entitlements after payment.
 ---
 
-Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. In Spree 6 that behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt.
+Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. In Spree 6 that behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt. This guide walks through selling an uploaded file end to end.
+
+For the concepts behind each piece — assets, links, allowances, providers — see [Products → Digital products](../core-concepts/products.md#digital-products). This page is the practical walkthrough.
 
 ## What you will build
 
-- **Digital delivery profile** — products that require no shipping address and complete checkout without a delivery step.
-- **Instant fulfillment** — the digital fulfillment provider fulfills on payment rather than on dispatch.
-- **Delivery of the goods** — attaching files or granting entitlements, and notifying the customer.
-- **Mixed carts** — physical and digital items in one order, split into separate fulfillments automatically.
+- **A digital variant** — one whose delivery profile requires no shipping address, so a fully digital cart completes checkout without a delivery step.
+- **A downloadable file on it** — uploaded to private storage and attached as a digital asset.
+- **Automatic delivery** — a download link granted on order placement, and an email that sends it.
+- **Mixed carts** — physical and digital items in one order, handled without extra work.
+
+## 1. Make the product digital
+
+A variant is digital when its [delivery profile](../core-concepts/fulfillments.md) is a digital one. A store ships with a built-in **Digital** delivery profile; assign it to the product and the product's variants stop asking for a shipping address.
+
+
+```typescript Admin SDK
+// Assign the store's digital delivery profile to the product.
+const { data: profiles } = await adminClient.deliveryProfiles.list()
+const digital = profiles.find((p) => p.kind === 'digital')
+
+await adminClient.products.update('prod_86Rf07xd4z', {
+  delivery_profile_id: digital.id,
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "delivery_profile_id": "dp_digital" }'
+```
+
+
+> **NOTE:** A product's delivery profile is auto-assigned when it is created — from its product type's template, or the store default. You only set it explicitly to change it. Selling from the dashboard, this is the **Shipping profile** field on the product page.
+
+## 2. Attach the file
+
+Upload the file to **private storage** and attach it to the variant as a digital asset. Private storage matters: a digital file is only ever served through a short-lived signed link, so the Admin API refuses a blob that landed on the public bucket.
+
+```typescript Admin SDK
+// Request a private upload slot, PUT the file, then attach the blob.
+const { direct_upload, signed_id } = await adminClient.directUploads.create({
+  private: true,
+  blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },
+})
+await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })
+
+await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', { signed_id })
+```
+
+Leave `authorized_clicks` and `authorized_days` off to inherit the store's download limits, or set them per file to mix evergreen downloads with time-limited ones. See [the allowance](../core-concepts/products.md#downloading-and-the-allowance) for how the limits resolve.
+
+> **TIP:** You can attach a file to a **physical** variant too — a manual or warranty PDF that ships alongside the goods. Carrying files and being digital are independent: the physical variant still needs an address, and it also grants a download link.
+
+## 3. Let the order deliver itself
+
+There is no step three to configure. When the order is placed, the digital fulfillment provider runs automatically — it needs no address and no manual dispatch — and grants the buyer one download link per file, per purchased unit. `Spree::DigitalAssetMailer` then emails the links as a message of its own, so it survives a replaced order-confirmation template and can be re-sent from the order page.
+
+The customer downloads by following the link's token; each download is counted against the allowance and publishes a `digital_link.downloaded` event. If they exhaust their downloads or you replace the file mid-sale, an admin restores access by resetting the link from the order page.
+
+> **NOTE:** To deliver something other than an uploaded file — a license key minted on demand, an entitlement from your own system — the delivery step is pluggable. See [Build a Custom Digital Asset Provider](custom-digital-asset-provider.md).
+
+## 4. Mixed carts work on their own
+
+A cart with both physical and digital items needs nothing special. Spree splits the order into separate fulfillments per delivery profile, so the physical items collect an address and ship while the digital items skip straight to granting links. The delivery step only appears when at least one item actually needs shipping; an all-digital cart never sees it.
 
-## Outline
+## Related documentation
 
-1. Create a digital delivery profile and assign products
-2. Configure the digital fulfillment provider
-3. Deliver files or entitlements on fulfillment
-4. Handle mixed physical and digital orders
+- [Products → Digital products](../core-concepts/products.md#digital-products) — the concepts: assets, links, allowances, providers
+- [Build a Custom Digital Asset Provider](custom-digital-asset-provider.md) — deliver a key or external file instead of an upload
+- [Fulfillments](../core-concepts/fulfillments.md) — delivery profiles, providers, and how orders are fulfilled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.192",
+  "version": "0.1.194",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",