@spree/docs 0.1.180 → 0.1.182

package/dist/developer/core-concepts/companies-and-catalogs.md

@@ -0,0 +1,81 @@
+---
+title: Companies & Catalogs
+description: How Spree models B2B buyer organizations — a multi-level company tree with members and an address book — and the catalogs that decide what each audience sees and pays.
+---
+
+## Overview
+
+A business customer in Spree is a **tree of company nodes**, not a flat account. One node can stand alone — a company with a few members and addresses — or grow into a group: subsidiaries, divisions, regional units, each with its own buyers and ship-to sites.
+
+```mermaid
+erDiagram
+    Company ||--o{ Company : "parent of"
+    Company ||--o{ CompanyMembership : "has many"
+    Company ||--o{ CompanyAddress : "has many"
+    Company ||--o{ CompanyInvitation : "has many"
+    Company ||--o{ TaxIdentifier : "legal entities only"
+    Company ||--o{ TaxExemptionCertificate : "legal entities only"
+
+    Company {
+        string name
+        string kind "company | division"
+        string external_id
+    }
+    CompanyMembership {
+        string role "cosmetic label"
+    }
+    CompanyAddress {
+        string label
+        boolean default_billing
+        boolean default_shipping
+    }
+    CompanyInvitation {
+        string email
+        string token
+        datetime expires_at
+    }
+```
+
+Three ideas carry the whole model:
+
+- **The tree is structure.** `Spree::Company` is self-referential (`parent_id`), store-scoped, and shallow — depth is capped at five levels. How many ship-to sites a node has never dictates how many nodes exist; addresses are just an address book.
+- **Nodes are typed, and the type decides tax.** A `company` node is a legal entity; a `division` is an organizational unit. Tax registrations and exemption certificates exist only on legal entities, and a purchase's tax always resolves through the node's `legal_entity` — for a `company` that is the node itself, and for a `division` it is its nearest `company` ancestor, whose registrations then cover the division's purchases. The walk stops at that first `company` node whether or not it holds any registration, so a subsidiary with no VAT number of its own has none — it never borrows its parent's.
+- **Membership is standing over a subtree.** A `CompanyMembership` joins a customer to a node, and that standing covers the node and everything below it. Any authorization question — "may this customer act for node N?" — is a membership check on N and its ancestors, never an equality check on one node.
+
+## Members and invitations
+
+People join by email, from either side — staff in the dashboard or an existing member on the storefront. An email that matches a store customer becomes a membership immediately; an unknown email becomes a `Spree::CompanyInvitation` — a plaintext-token record with a 30-day expiry, whose invite email links to the storefront acceptance page. Accepting either registers a new account (through the standard customer-creation flow, with the invited email) or binds the invitation to the signed-in customer, and lands as a membership either way.
+
+Memberships stay always-active and always customer-backed: the pending state lives on the invitation, never as a status on the membership.
+
+**In open source, every member can do everything within their standing** — buy, see the subtree's purchases, manage addresses and members. There are no company roles; the `role` string on a membership is a cosmetic label. Finer control (roles, approvals, spending limits) is an Enterprise layer that enforces through the storefront access policy class (`Spree::Dependencies.storefront_access_policy_class`) and the checkout `validate` hooks — injection points that are deliberate no-ops in OSS.
+
+## Purchases
+
+Carts and orders carry a `company_id` pointing at any node — buying *for* a division means pointing at it. A buyer with exactly one membership resolves to it automatically; a buyer with several names the node on their cart (the `company_id` param on cart update, validated against their standing). The node is frozen onto the order at completion, like every other order attribute, so a placed order's tax treatment stays explainable no matter how the tree changes later.
+
+Exemption certificates and the company's tax registration always resolve through `company.legal_entity` — see [Taxes, Discounts & Fees](/docs/developer/core-concepts/taxes-discounts-fees) for how they reach the tax provider.
+
+## Catalogs
+
+A `Spree::Catalog` narrows what an audience sees and — through an optional price list — what they pay.
+
+```mermaid
+erDiagram
+    Catalog ||--o{ CatalogProduct : "assortment"
+    Catalog ||--o{ CatalogAssignment : "audiences"
+    Catalog }o--o| PriceList : "optional pricing"
+    CatalogAssignment }o--|| Company : "or"
+    CatalogAssignment }o--|| CustomerGroup : "or"
+    CatalogAssignment }o--|| Market : "or"
+    CatalogAssignment }o--|| Channel : "or"
+```
+
+- **Assortment** — a positioned product join, and the switch between a catalog's two modes. A *curated* assortment restricts: the audience sees only what's in it. An *empty* assortment is a pricing-only overlay: the attached price list applies and nothing is hidden — which is how "everyone sees the public store, this company just gets special prices" is expressed. An explicit import action copies the price list's products into the assortment when a restrictive catalog should start from the priced range.
+- **Audiences** — assignments to a channel, a customer group, a market, or a company node. A company assignment covers the node's **subtree**: assign the group-wide catalog once at the root, and a branch adds its own extra catalog without re-assigning the shared one.
+- **Visibility** — a buyer resolving to a company node sees the union of the effective catalogs on the node and its ancestors; otherwise their customer group's catalogs apply; otherwise every channel listing (narrowed to the channel's default catalog when one is set). Any effective catalog with an empty assortment lifts the restriction — the union then includes the whole range. Gated storefront access runs first — a login-gated guest never reaches this resolution.
+- **Pricing** — the effective catalogs' price lists are checked nearest node first (the purchase node's own assignments before its parent's), then the ordinary rule-matched price lists, then base prices. A price list attached to a catalog applies *because the catalog applies* — its own rules are not consulted, and it is excluded from generic rule matching so a rule-less list cannot leak to every shopper.
+
+## Storefront self-service
+
+The Store API ships a full company directory for members: their memberships with ancestor paths (`GET /store/account/companies`), node details and renaming, the address book, members and invitations, and the subtree's completed orders. Authorization on every endpoint is **standing plus the access policy** — never roles, never CanCanCan. The deliberate trade-off: within a company, OSS trusts every member; merchants who need restraint layer the Enterprise governance on the same injection points, with no schema changes.

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

@@ -64,7 +64,7 @@ erDiagram
 | `name` | Product name | Yes |
 | `description` | Full product description | Yes |
 | `slug` | URL-friendly identifier (e.g., `spree-tote`) | Yes |
-| `status` | `draft`, `active`, or `archived` | No |
+| `status` | `draft`, `active`, or `archived`. A marketplace adds `proposed` and `rejected` — see Seller submissions below | No |
 | `available_on` | Date the product becomes available for sale | No |
 | `discontinue_on` | Date the product is no longer available | No |
 | `meta_title` | Custom SEO title | Yes |
@@ -221,6 +221,144 @@ spree api delete /products/prod_xxx
 
 > **TIP:** Operating on many products at once? The Admin API has bulk actions — `bulkStatusUpdate`, `bulkAddToCategories`, `bulkAddTags`, `bulkDestroy`, and more. See the [Admin API endpoint index](../../api-reference/admin-api/endpoints.md).
 
+## Seller submissions 
+
+On a marketplace, a seller lists a product but does not publish one. They submit it, and the marketplace decides. This adds two statuses to the three above — both hidden from the storefront, since only `active` is visible.
+
+> **INFO:** This applies to products that belong to a seller. A marketplace's own catalog is unaffected: an operator publishing their own product sets `status` directly and answers to nobody.
+
+### The lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft
+    draft --> proposed : seller submits
+    proposed --> active : operator approves
+    proposed --> rejected : operator sends back
+    rejected --> proposed : seller revises and resubmits
+    proposed --> draft : seller withdraws
+    proposed --> archived : seller withdraws
+    active --> draft : seller takes it down
+    active --> archived : seller withdraws it
+```
+
+Withdrawing a submission before anyone has ruled on it closes the open row as `withdrawn`, so a `pending` row always means the marketplace still owes an answer. A product that was already rejected keeps that decision at the head of its trail instead.
+
+| Status | Meaning | Storefront |
+|---|---|:---:|
+| `draft` | The seller is still working on it | Hidden |
+| `proposed` | Submitted, waiting on the marketplace | Hidden |
+| `rejected` | Sent back with a reason, awaiting changes | Hidden |
+| `active` | Approved and on sale | **Visible** |
+| `archived` | Withdrawn | Hidden |
+
+A seller can always take their own listing down — that is not a review decision. Putting one up is.
+
+### The submission record
+
+Each submission and each decision on it is a `Spree::ProductSubmission` row. The product's `status` stays the operational truth; these rows are how it got there.
+
+```mermaid
+erDiagram
+    Product ||--o{ ProductSubmission : "has many"
+    AdminUser ||--o{ ProductSubmission : "submitted"
+    AdminUser ||--o{ ProductSubmission : "reviewed"
+
+    ProductSubmission {
+        string status
+        bigint product_id
+        bigint submitted_by_id
+        bigint reviewed_by_id
+        datetime reviewed_at
+        text review_note
+        json metadata
+    }
+```
+
+| Column | Description |
+|---|---|
+| `status` | `pending`, `approved`, `rejected`, or `withdrawn` |
+| `submitted_by_id` | The seller's staff member who asked |
+| `reviewed_by_id` | The marketplace's staff member who decided |
+| `reviewed_at` | When the decision was made |
+| `review_note` | Why it was sent back — this is what the seller reads |
+
+Rows accumulate rather than overwrite, so a seller sent back three times leaves three rows. The latest row for a product is the live one; the ones before it are the trail.
+
+> **WARNING:** Never store a rejection reason on the product itself. A seller can write their own product's `metadata`, so a note kept there is erased the next time they save.
+
+An approval with no `reviewed_by_id` and `metadata.auto_approved` set means the store approves listings automatically — never a decision whose author was lost. Turn that on with the `auto_approve_seller_products` store preference.
+
+### Submitting, as a seller
+
+Status is not writable on the seller branch. A seller moves a product with an explicit action:
+
+
+```typescript Seller SDK
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+  baseUrl: 'https://marketplace.example.com',
+  sellerId: 'sel_xxx',
+})
+
+await client.products.submit('prod_xxx')   // draft or rejected → proposed
+await client.products.draft('prod_xxx')    // take it back down
+await client.products.archive('prod_xxx')  // withdraw it
+
+// Why it was sent back
+const product = await client.products.get('prod_xxx', 'submission')
+product.submission?.review_note
+```
+
+```bash CLI
+spree api patch /seller/products/prod_xxx/submit
+spree api patch /seller/products/prod_xxx/draft
+spree api patch /seller/products/prod_xxx/archive
+```
+
+
+### Deciding, as the marketplace
+
+
+```typescript Admin SDK
+await client.products.approve('prod_xxx')
+await client.products.reject('prod_xxx', { reason: 'Please add a photo showing scale.' })
+
+// The review queue
+const pending = await client.products.list({ filter: { status_eq: 'proposed' } })
+
+// Who decided, and when
+const product = await client.products.get('prod_xxx', { expand: ['submission'] })
+product.submission?.reviewed_by_name
+```
+
+```bash CLI
+spree api patch /products/prod_xxx/approve
+spree api patch /products/prod_xxx/reject -d '{"reason": "Please add a photo showing scale."}'
+```
+
+
+> **NOTE:** The seller sees the note and when the decision was made, but never who made it.
+
+### Leaving review is a decision
+
+A product in `proposed` or `rejected` cannot have its status changed by an ordinary update — that would put it on sale with nobody's name against it. The refusal lives in the product update workflow, so every caller inherits it, and bulk status updates skip those products and report how many they left behind.
+
+### Events
+
+Each transition publishes an event you can subscribe to:
+
+| Event | Published when |
+|---|---|
+| `product.proposed` | A seller submits for review |
+| `product.approved` | The marketplace accepts it |
+| `product.rejected` | The marketplace sends it back |
+| `product.drafted` | A seller takes a listing down |
+| `product.archived` | A seller withdraws it |
+
+The submission row itself also publishes `product_submission.created` and `product_submission.updated`, carrying the status, the note and the product. See [Events](events.md).
+
 ## Product Filters
 
 Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:

package/package.json

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