@spree/docs 0.1.48 → 0.1.50

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

@@ -61,7 +61,7 @@ Create a subscriber class in `app/subscribers/` that inherits from `Spree::Subsc
 ```ruby app/subscribers/my_app/order_completed_subscriber.rb
 module MyApp
   class OrderCompletedSubscriber < Spree::Subscriber
-    subscribes_to 'order.complete'
+    subscribes_to 'order.completed'
 
     def handle(event)
       order_id = event.payload['id']
@@ -82,17 +82,17 @@ The `Spree::Subscriber` class provides a clean DSL for declaring subscriptions:
 ```ruby
 class MySubscriber < Spree::Subscriber
   # Subscribe to a single event
-  subscribes_to 'order.complete'
+  subscribes_to 'order.completed'
 
   # Subscribe to multiple events
-  subscribes_to 'order.complete', 'order.cancel', 'order.resume'
+  subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
 
   # Subscribe to all events matching a pattern
   subscribes_to 'order.*'  # All order events
   subscribes_to '*.*'      # All events (use sparingly!)
 
   # Run synchronously instead of via background job
-  subscribes_to 'order.complete', async: false
+  subscribes_to 'order.completed', async: false
 end
 ```
 
@@ -103,11 +103,11 @@ When subscribing to multiple events, use the `on` DSL to route events to specifi
 ```ruby app/subscribers/my_app/order_audit_subscriber.rb
 module MyApp
   class OrderAuditSubscriber < Spree::Subscriber
-    subscribes_to 'order.complete', 'order.cancel', 'order.resume'
+    subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
 
-    on 'order.complete', :log_order_completed
-    on 'order.cancel', :log_order_canceled
-    on 'order.resume', :log_order_resumed
+    on 'order.completed', :log_order_completed
+    on 'order.canceled', :log_order_canceled
+    on 'order.resumed', :log_order_resumed
 
     private
 
@@ -144,7 +144,7 @@ When your subscriber receives an event, you get a `Spree::Event` object with:
 ```ruby
 def handle(event)
   event.id         # => "550e8400-e29b-41d4-a716-446655440000" (UUID)
-  event.name       # => "order.complete"
+  event.name       # => "order.completed"
   event.store_id   # => 1 (ID of the store where the event originated)
   event.payload    # => { "id" => 1, "number" => "R123456", ... }
   event.metadata   # => { "spree_version" => "5.1.0" }
@@ -153,7 +153,7 @@ def handle(event)
   # Helper methods
   event.store        # => Spree::Store instance (lazy loaded)
   event.resource_type # => "order" (extracted from name)
-  event.action        # => "complete" (extracted from name)
+  event.action        # => "completed" (extracted from name)
 end
 ```
 
@@ -421,7 +421,7 @@ For critical operations that must complete before the request finishes, use sync
 
 ```ruby
 class CriticalOrderHandler < Spree::Subscriber
-  subscribes_to 'order.complete', async: false
+  subscribes_to 'order.completed', async: false
 
   def handle(event)
     # This runs immediately, blocking the request
@@ -458,7 +458,7 @@ RSpec.describe MyApp::OrderCompletedSubscriber do
   let(:order) { create(:completed_order_with_totals) }
   let(:event) do
     Spree::Event.new(
-      name: 'order.complete',
+      name: 'order.completed',
       payload: order.event_payload
     )
   end
@@ -477,9 +477,9 @@ end
 Use the `emit_webhook_event` matcher (if available) or stub the events:
 
 ```ruby
-it 'publishes order.complete event' do
+it 'publishes order.completed event' do
   expect(Spree::Events).to receive(:publish).with(
-    'order.complete',
+    'order.completed',
     hash_including('id' => order.id)
   )
 
@@ -506,7 +506,7 @@ Here's a complete example of a subscriber that sends alerts when inventory is lo
 ```ruby app/subscribers/my_app/inventory_alert_subscriber.rb
 module MyApp
   class InventoryAlertSubscriber < Spree::Subscriber
-    subscribes_to 'stock_item.update'
+    subscribes_to 'stock_item.updated'
 
     LOW_STOCK_THRESHOLD = 10
 

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

@@ -12,17 +12,74 @@ Spree handles uploads, processing, and delivery for product media. Images are au
 
 ## Product Media
 
-Product media uses the `Spree::Asset` model, which provides:
+A media record carries:
 
-- **Multiple media per product** with ordering
-- **Media types** — `image`, `video`, `external_video`
+- **Position** for ordering within the gallery
+- **Media type** — `image`, `video`, or `external_video` (defaults to `image`)
 - **Alt text** for accessibility and SEO
 - **Focal point** coordinates for smart cropping
 - **Preprocessed named variants** for fast delivery
+- **`variant_ids`** — which product variants the media represents. An empty array means it represents the product as a whole.
 
-Each media item has a `media_type` field that defaults to `image`. The `variant_ids` field indicates which product variants the media is associated with — an empty array means the media belongs to the product as a whole.
+### Product-level Gallery 
 
-> **NOTE:** `Spree::Image` is a backward-compatible subclass of `Spree::Asset` that sets `media_type` to `image`. New code should use `Spree::Asset` directly.
+In Spree 5.5 the **product** is the default owner of media. Before 5.5, every image was pinned to a specific variant (usually the master), and sharing the same image across variants meant re-uploading the file. From 5.5 onward, an image lives on the product, and any subset of variants can reference it through `variant_ids` — without duplicating the underlying file.
+
+#### Uploading a product-level image
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({ baseUrl, secretKey })
+
+// `signed_id` comes from a direct upload; see the Active Storage docs for
+// generating one client-side.
+const media = await client.products.media.create('prod_86Rf07xd4z', {
+  signed_id: signedBlobId,
+  alt: 'Front view',
+  position: 1,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "signed_id": "<signed-blob-id>",
+    "alt": "Front view",
+    "position": 1
+  }'
+```
+
+
+#### Sharing a single image across variants
+
+Pass a `variant_ids` array on the same media endpoint to link/unlink variants. The server replaces the asset's link set on every call — empty array clears all links, omitting the field leaves them untouched.
+
+
+```typescript Admin SDK
+await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
+  variant_ids: ['variant_redM', 'variant_redL'],
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "variant_ids": ["variant_redM", "variant_redL"] }'
+```
+
+
+Variants belonging to a different product are silently dropped — the API rejects cross-product tampering at the model layer. Reordering happens once on the product gallery; every linked variant inherits the new order.
+
+#### Storefront gallery resolution
+
+The Store API's `media` field on a product returns its gallery — product-level media when present, falling back to legacy variant-pinned images during the transition. On a variant, `media` returns the assets linked to that variant via `variant_ids`, falling back to direct variant uploads.
+
+This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](../upgrades/5.4-to-5.5.md) to re-home legacy variant-pinned data when convenient.
 
 ### Named Variant Sizes 
 
@@ -134,8 +191,9 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 | `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
 | `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
 | `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
-| `original_url` | string \| null | Full-size image URL |
+| `original_url` | string \| null | Full-size image URL (inline disposition) |
 | `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
+| `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only.  |
 
 ## Image Processing
 

package/dist/developer/upgrades/5.3-to-5.4.md

@@ -79,9 +79,9 @@ If you previously added Subscribers for Events, eg. `order.completed` with code
 ```ruby
 module MyApp
   class OrderAuditSubscriber < Spree::Subscriber
-    subscribes_to 'order.complete'
+    subscribes_to 'order.completed'
 
-    on 'order.complete', :log_order_completed
+    on 'order.completed', :log_order_completed
 
     private
 

package/dist/developer/upgrades/5.4-to-5.5.md

@@ -19,6 +19,24 @@ description: This guide covers upgrading a Spree 5.4 application to Spree 5.5.
   bin/rake spree:install:migrations && bin/rails db:migrate
   ```
 
+### Migrate legacy variant-pinned media
+
+In 5.5 the [product is the default owner of media](../core-concepts/media.md#product-level-gallery). Existing variant-pinned images keep rendering, but new admin uploads attach to the product. To consolidate both into a single gallery, run:
+
+```bash
+bin/rails spree:media:migrate_master_images_to_product_media
+```
+
+The task enqueues one `Spree::Media::MigrateProductAssetsJob` per product onto the `images` queue — make sure your job runner is processing that queue. Each job is idempotent, so re-running the task is safe; it skips products that no longer have variant-pinned assets.
+
+For larger catalogs, tune the batching with `BATCH_SIZE`:
+
+```bash
+bin/rails spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
+```
+
+> **WARNING:** Run the task locally and on production. It does not block storefront rendering — new uploads attach to the product immediately — but until the enqueued jobs finish, old assets remain pinned to variants.
+
 ### Run the channels upgrade
 
 Spree 5.5 promotes `Order#channel` from a free-text string column to a real `Spree::Channel` FK. **Run this rake task immediately after `db:migrate`** — it seeds the channel rows your existing stores need and backfills `spree_orders.channel_id` from the legacy string column:

package/package.json

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