@spree/docs 0.1.179 → 0.1.181

package/dist/api-reference/seller-api/authentication.md

@@ -0,0 +1,109 @@
+---
+title: "Authenticate Seller API requests with JWTs and the seller header"
+sidebarTitle: "Authentication"
+description: "Authenticate Spree Seller API requests with a seller-audience JWT and select which seller to act as using the X-Spree-Seller-Id header."
+---
+
+The Seller API has exactly one authentication method: a **JWT issued to a signed-in seller**. There is deliberately no secret API key on this branch — a credential that could act as a seller without a seller signing in is exactly what the separate token audience exists to prevent.
+
+## Two things every request needs
+
+1. `Authorization: Bearer <token>` — the JWT returned by login.
+2. `X-Spree-Seller-Id: <seller_id>` — which seller the signed-in user is acting as.
+
+The only authenticated endpoint that does not need the second is `GET /api/v3/seller/me`, because that is what tells the panel which seller to name.
+
+## Signing in
+
+```typescript
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({ baseUrl: 'https://store.example.com' })
+
+const { token, user, sellers } = await client.auth.login({
+  email: 'seller@example.com',
+  password: 'password123',
+})
+```
+
+The response carries three things: the access token, the team member who signed in, and **every seller this user may act for**.
+
+> **NOTE:** The refresh token is **not** in the response body. It is set as an HttpOnly cookie scoped to `/api/v3/seller/auth`, so a session issued for the seller panel cannot be redeemed on any other surface.
+
+### Membership is required, not just credentials
+
+A marketplace's own staff share the same user class as sellers. Authenticating is therefore not enough: a user who runs no seller is refused with `401`, because issuing a token would hand out an audience its holder can do nothing with.
+
+## Choosing a seller
+
+A person may run more than one seller — so capability is per seller, and a request that names none has no tenant at all.
+
+```typescript
+client.setToken(token)
+client.setSeller(sellers[0].id)
+
+// Every subsequent call now carries both headers
+const { data: products } = await client.products.list()
+```
+
+Sending a seller ID the caller has no role on resolves to nothing, so it reads as **"no such seller"** rather than "denied" — which is also what stops the header being used to enumerate the marketplace's sellers.
+
+> **WARNING:** A request with a valid token but no `X-Spree-Seller-Id` header — or one naming a seller the caller does not belong to — is rejected with `403`. There is no fallback to a default seller.
+
+## Token audiences
+
+Every Spree JWT carries an audience, and each surface accepts only its own:
+
+| Surface | Audience | Accepted by |
+|---|---|---|
+| Storefront | `store_api` | Store API |
+| Back office | `admin_api` | Admin API |
+| Seller panel | `seller_api` | Seller API |
+
+An admin token presented to the Seller API is a `401`, and a seller token presented to the Admin API is likewise refused. The refresh endpoint narrows by audience too, so a refresh token minted elsewhere cannot be exchanged for a seller session.
+
+## Refreshing a session
+
+```typescript
+const { token } = await client.auth.refresh()
+client.setToken(token)
+```
+
+No request body and no `Authorization` header — the cookie alone authenticates the call, and a fresh refresh cookie is rotated in.
+
+Membership is re-checked here, so a user whose last seller role was revoked mid-session is refused at their next refresh rather than continuing until the access token happens to expire.
+
+## Signing out
+
+```typescript
+await client.auth.logout()
+```
+
+Revokes the refresh token server-side and clears the cookie.
+
+## Accepting an invitation
+
+Someone invited onto a seller's team arrives through an emailed link carrying an invitation ID and a token. Both acceptance endpoints are unauthenticated — the link **is** the credential.
+
+```typescript
+// Read the invitation to decide what to ask for
+const invitation = await client.auth.lookupInvitation(invitationId, token)
+
+// Accept, and land in the panel already signed in
+const { token: jwt, sellers } = await client.auth.acceptInvitation(invitationId, token, {
+  password: 'password123',
+  password_confirmation: 'password123',
+  first_name: 'Robin',
+  last_name: 'Ellis',
+})
+```
+
+The invited email address is never taken from the request — it always comes from the invitation itself, which is what stops the link being redirected to another address.
+
+`password` sets a new password when no account exists for that address; when one does, the same field is how the person proves the account is theirs.
+
+> **NOTE:** A wrong token is indistinguishable from an unknown invitation: both answer `404`. So does an invitation onto the marketplace's own staff rather than a seller.
+
+## Rate limiting
+
+Sign-in, refresh, provider discovery, and invitation acceptance are all rate limited, and answer `429` with a `rate_limit_exceeded` code when a client exceeds the window.

package/dist/api-reference/seller-api/errors.md

@@ -0,0 +1,130 @@
+---
+title: "Seller API error responses, status codes, and handling"
+sidebarTitle: "Errors"
+description: "Reference for the Spree Seller API error response format, HTTP status codes, and what a 403 versus a 404 means on the seller branch."
+---
+
+The Seller API uses the same error format as the rest of the Spree v3 API. Every error response carries a machine-readable `code` and a human-readable `message`.
+
+## Error response format
+
+```json
+{
+  "error": {
+    "code": "record_not_found",
+    "message": "Product not found"
+  }
+}
+```
+
+Validation errors include a `details` field with per-field messages:
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Validation failed",
+    "details": {
+      "name": ["can't be blank"]
+    }
+  }
+}
+```
+
+Permission errors name the key the caller was missing:
+
+```json
+{
+  "error": {
+    "code": "access_denied",
+    "message": "Missing permission: write_products",
+    "details": {
+      "required_permission": "write_products"
+    }
+  }
+}
+```
+
+## Status codes
+
+| Status | Meaning on the seller branch |
+|---|---|
+| `200` | Success |
+| `201` | Resource created |
+| `204` | Success, no body — deletes and logout |
+| `401` | No token, an expired one, or a token minted for another surface |
+| `403` | Authenticated, but no seller named — or the acting seller's role lacks the permission |
+| `404` | The record does not exist **for this seller** |
+| `422` | Validation failed, or a workflow refused the request |
+| `429` | Rate limit exceeded |
+
+## 403 versus 404 — the distinction that matters
+
+This is the most important thing to understand about the seller branch, because the two codes answer different questions.
+
+**`403` means "you have not told me who you are acting as, or you may not do this."** It comes from one of two places:
+
+- No `X-Spree-Seller-Id` header, or one naming a seller the caller has no role on.
+- The acting seller's role lacks the permission key the action requires.
+
+**`404` means "no such record, for you."** Every lookup is rooted in the acting seller, so an ID belonging to another seller — or to the marketplace operator — is simply not found.
+
+```json
+{
+  "error": {
+    "code": "record_not_found",
+    "message": "Product not found"
+  }
+}
+```
+
+This is deliberate. Answering `403` for another seller's product would confirm the record exists, which is how a seller could probe the marketplace's catalog one ID at a time. The seller is never told the difference between "this belongs to someone else" and "this does not exist".
+
+## Common error codes
+
+| Code | Status | When |
+|---|---|---|
+| `authentication_failed` | 401 | Bad credentials, or a user who runs no seller |
+| `invalid_refresh_token` | 401 | The refresh cookie is missing, expired, or for another audience |
+| `access_denied` | 403 | No seller named, or a missing permission key |
+| `record_not_found` | 404 | The record does not belong to the acting seller |
+| `validation_error` | 422 | Model validation failed; see `details` |
+| `processing_error` | 422 | A workflow refused — for example, submitting for review with requirements outstanding |
+| `parameter_missing` | 400 | A required parameter was absent |
+| `rate_limit_exceeded` | 429 | Too many requests to an auth endpoint |
+
+## Handling errors with the SDK
+
+The SDK throws a `SpreeError` carrying the code, status, and details:
+
+```typescript
+import { SpreeError } from '@spree/seller-sdk'
+
+try {
+  await client.products.create({ name: '' })
+} catch (error) {
+  if (error instanceof SpreeError) {
+    if (error.status === 422) {
+      // error.details → { name: ["can't be blank"] }
+      showFieldErrors(error.details)
+    } else if (error.status === 403) {
+      showMessage("You don't have permission to do that.")
+    }
+  }
+}
+```
+
+## Requirements that block submission
+
+Submitting for review with something required still outstanding returns `422` with a message naming what is blocking. The seller's status is unchanged — nothing partial happens.
+
+```json
+{
+  "error": {
+    "code": "processing_error",
+    "message": "Add a billing address"
+  }
+}
+```
+
+Read the checklist from `GET /api/v3/seller/onboarding` to see each requirement's `status` and whether it is `blocking`.

package/dist/api-reference/seller-api/introduction.md

@@ -0,0 +1,85 @@
+---
+title: "Spree Seller API introduction and SDK quick start"
+sidebarTitle: "Introduction"
+description: "Overview of the Spree Seller API — the marketplace seller panel for managing a seller's own catalog, team, stock locations, and onboarding."
+---
+
+import { Since } from '/snippets/since.mdx';
+
+
+The Seller API is a REST API for the **marketplace seller panel** — where a seller runs their own shop inside someone else's marketplace. It powers a seller's catalog, their team, their stock locations, and the onboarding checklist the marketplace asks them to complete.
+
+All routes are prefixed with `/api/v3/seller`. During development the API is available under `http://localhost:3000/api/v3/seller`. For production, replace `http://localhost:3000` with your Spree application URL.
+
+## A branch of its own, not a narrowing of the Admin API
+
+Sellers never call the Admin API. Every Seller API endpoint is scoped server-side to the seller the request acts as, which makes cross-seller access impossible by construction rather than by rule: a product ID belonging to another seller answers `404`, not `403`.
+
+The store is **derived from the seller**, never sent alongside it, so no header a seller controls can widen what they reach.
+
+| | Seller API | Admin API |
+|---|---|---|
+| **Purpose** | Run one seller's shop | Run the whole marketplace |
+| **Audience** | Marketplace sellers and their staff | The marketplace operator's staff |
+| **Authentication** | Seller JWT only (`seller_api` audience) | Secret API key (`sk_…`) or admin JWT |
+| **Tenancy** | Scoped to the acting seller | Scoped to the store |
+| **Server-to-server credential** | None, by design | Secret API keys |
+
+The marketplace operator manages sellers — approving them, reviewing what they submit, setting commission — through the Admin API's own [seller endpoints](../admin-api/introduction.md), not through this API.
+
+## Using the SDK
+
+We recommend `@spree/seller-sdk` for interacting with the Seller API. It provides typed clients, automatic retries, and handles the seller header for you.
+
+### Installation
+
+```bash
+npm install @spree/seller-sdk
+# or
+yarn add @spree/seller-sdk
+# or
+pnpm add @spree/seller-sdk
+```
+
+### Quick start
+
+```typescript
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+  baseUrl: 'http://localhost:3000',
+})
+
+// Sign in, then pick which seller to act as
+const { token, sellers } = await client.auth.login({
+  email: 'seller@example.com',
+  password: 'password123',
+})
+
+client.setToken(token)
+client.setSeller(sellers[0].id)
+
+const { data: products } = await client.products.list({ limit: 25 })
+```
+
+## What a seller can do
+
+
+  - **Catalog** — List, create, update, and delete the products they own outright.
+  - **Profile** — Maintain presentation, contact details, addresses, and tax registration.
+  - **Team** — Invite colleagues, list the team, and revoke access.
+  - **Onboarding** — Read the marketplace's checklist and submit against each requirement.
+  - **Stock locations** — Manage where they keep stock, and so where returns are sent.
+  - **Uploads** — Presign direct uploads for the documents onboarding asks for.
+
+
+## What a seller cannot do
+
+Some fields are readable but never writable, because they belong to the marketplace rather than the seller:
+
+- **`status`** — the seller lifecycle belongs to the operator's workflows. A seller says they are ready via `POST /api/v3/seller/onboarding/submit_for_review`; the operator decides.
+- **`slug`** — renaming a storefront address would break every link pointing at it.
+- **Settlement and commission terms** — what the marketplace charges is the marketplace's to set.
+- **Tax category, delivery profile, and promotionability on products** — marketplace-wide merchandising settings.
+
+Sending these fields is not an error; they are simply ignored.