diff --git a/README.md b/README.md index 0e8cac8..1c029ec 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ bun type-check # TypeScript type checking Skills are plain markdown files in `use-crystallize/skills/` — no build step required. Each skill has a `SKILL.md` with YAML frontmatter and an optional `references/` directory with supporting docs. -Available skills: `agent-tenants`, `bookable-resources`, `content-json`, `content-model`, `data-creation`, `information-architecture`, `js-api-client`, `mass-operations`, `mutation`, `payments`, `permissions`, `plugins`, `pricing`, `query`, `responsive-images`, `subscriptions`, `taxonomy`, `vector-ranking` — the directory itself is the authoritative list. +Available skills: `agent-tenants`, `agentic-commerce`, `bookable-resources`, `content-json`, `content-model`, `data-creation`, `information-architecture`, `js-api-client`, `mass-operations`, `media`, `mutation`, `payments`, `permissions`, `plugins`, `pricing`, `query`, `responsive-images`, `seo-geo`, `storefront`, `subscriptions`, `taxonomy`, `vector-ranking` — the directory itself is the authoritative list. ## Using the Claude Plugin diff --git a/use-crystallize/mcp-servers/crystallize/bin/eval-reference-selection.cases.json b/use-crystallize/mcp-servers/crystallize/bin/eval-reference-selection.cases.json index 16ea4ee..afd5cad 100644 --- a/use-crystallize/mcp-servers/crystallize/bin/eval-reference-selection.cases.json +++ b/use-crystallize/mcp-servers/crystallize/bin/eval-reference-selection.cases.json @@ -42,8 +42,8 @@ }, { "task": "upload product images from external URLs and attach them to items", - "skills": ["mutation"], - "expected": ["mutation/media"] + "skills": ["mutation", "media"], + "expected": ["media/import"] }, { "task": "my bulk task is stuck in running, and how many operations can one file hold?", @@ -89,5 +89,40 @@ "task": "create a custom role with the API and assign it to a user", "skills": ["permissions"], "expected": ["permissions/role-api"] + }, + { + "task": "upload a product video and wait until it has been transcoded", + "skills": ["media"], + "expected": ["media/video"] + }, + { + "task": "revalidate product and category pages when an item is published", + "skills": ["storefront"], + "expected": ["storefront/caching-and-revalidation"] + }, + { + "task": "build the cart and checkout on the server with the Shop API", + "skills": ["storefront"], + "expected": ["storefront/cart-checkout"] + }, + { + "task": "add Product JSON-LD with offers, prices and units to our product pages", + "skills": ["seo-geo"], + "expected": ["seo-geo/json-ld"] + }, + { + "task": "publish llms.txt and Markdown versions of our product pages for AI crawlers", + "skills": ["seo-geo"], + "expected": ["seo-geo/llms-and-markdown"] + }, + { + "task": "expose our catalogue and cart as an MCP server so AI agents can shop", + "skills": ["agentic-commerce"], + "expected": ["agentic-commerce/mcp-server"] + }, + { + "task": "let an AI assistant sign in on behalf of a customer and place an order", + "skills": ["agentic-commerce"], + "expected": ["agentic-commerce/oauth"] } ] diff --git a/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-catalogue.ts b/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-catalogue.ts index 3be7e27..3503a65 100644 --- a/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-catalogue.ts +++ b/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-catalogue.ts @@ -17,9 +17,10 @@ export const createQueryCatalogueToolWrapper = ({ tenantMatcher, queryExecutor } "Execute a GraphQL query against the Crystallize Catalogue API. " + "If you haven't already, call the `skills` tool first — it provides query examples and best practices " + "that will help you write correct queries. " + - "The Catalogue API is a storefront API for fetching items, products, and content to build frontends. " + - "Use this for reading specific items by path or ID, traversing the catalogue tree, " + - "and accessing detailed component data with full type support.", + "For storefront reads, prefer the Discovery API. The Catalogue API is the synchronous fallback: " + + "use it for a specific customer's price-list prices (`priceFor(customerIdentifiers)`, server-side only) " + + "and for reads that must be in sync with what was just published, since Discovery is updated asynchronously. " + + "It can also read specific items by path or ID and traverse the catalogue tree.", inputSchema: z.object({ tenant: tenantSchema, query: querySchema, diff --git a/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-discovery.ts b/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-discovery.ts index 279f06f..db7db43 100644 --- a/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-discovery.ts +++ b/use-crystallize/mcp-servers/crystallize/src/core/mcp/tools/query-discovery.ts @@ -18,7 +18,8 @@ export const createQueryDiscoveryToolWrapper = ({ tenantMatcher, queryExecutor } "that will help you write correct queries. " + "The Discovery API is a storefront API for searching, browsing, filtering, and faceting items and products " + "to build frontends. It uses a shape-typed schema where each shape in the tenant becomes a GraphQL type. " + - "Use this for searching, filtering, listing items, and aggregating data for storefront use cases.", + "This is the default for every storefront catalogue read: items by path, listings, search, filtering and facets. " + + "It is updated asynchronously after a publish; for a read that must be in sync, or a specific customer's price, use the Catalogue API.", inputSchema: z.object({ tenant: tenantSchema, query: querySchema, diff --git a/use-crystallize/skills/agent-tenants/SKILL.md b/use-crystallize/skills/agent-tenants/SKILL.md index 2824a68..058d54e 100644 --- a/use-crystallize/skills/agent-tenants/SKILL.md +++ b/use-crystallize/skills/agent-tenants/SKILL.md @@ -1,16 +1,20 @@ --- name: agent-tenants description: > - Get a Crystallize tenant as an AI agent, for a user who has no Crystallize account, and hand it over - to them before it expires. Use when the user has no tenant or no access token and wants the agent to - set one up, asks for a sandbox or demo tenant, or wants an agent-made tenant handed over, claimed or - kept. Trigger on "create a tenant", "new tenant", "set up Crystallize for me", "I don't have a + Get a Crystallize tenant as an AI agent, for a user who has no Crystallize account, hand it over + to them before it expires, and get any new tenant ready to serve a storefront. Use when the user has no + tenant or no access token and wants the agent to set one up, asks for a sandbox or demo tenant, or wants + an agent-made tenant handed over, claimed or kept. Also use when setting up languages, the default + language, VAT types, price variants, stock locations, pipelines, markets or webhooks on a new tenant, + asking "which API creates X" (Core or the legacy PIM API), running the first Discovery ignite, debugging + "There is no ignited Tenant", getting storefront credentials, or wiring publish webhooks for cache + revalidation. Trigger on "create a tenant", "new tenant", "set up Crystallize for me", "I don't have a Crystallize account", "sign up", "provision", "agent tenant", "/agents/tenants", "hand over the tenant", "claim the tenant", "invite me", "createInviteToken", "tenantAdmin", "get-access", "tenant - expires", "tenant deleted". + expires", "tenant deleted", "tenant setup", "igniteDiscoApi", "createWebhook". metadata: author: Crystallize - version: "1.0" + version: "1.1" --- # Crystallize Agent Tenants @@ -40,9 +44,11 @@ send them one link. 3 Invite createInviteToken(role: "tenantAdmin") → invite token 4 Hand off the App's /get-access?token=… link → the human joins as tenantAdmin 5 Check the tenant's members on the PIM API → a human tenantAdmin = claimed +6 Serve publish, igniteDiscoApi, credentials → a storefront can read it ``` -Only step 1 is specific to agents. Steps 2 to 5 are the API a human tenant admin already uses. +Only step 1 is specific to agents. Steps 2 to 6 are the API a human tenant admin already uses, and step 6 applies +to every new tenant. | Used for | Host | | ------------------------- | ------------------------------------- | @@ -232,6 +238,25 @@ Variables: `{ "id": "6adbb89b790dd26b73debb6b" }` (the `tenant.id` from step 1). only member is the agent: `role: "tenantAdmin"`, `firstName: "Agent"`, `email: null`, `kind: "agent"`. Once they join, a second member appears with `role: "tenantAdmin"` and `kind: "human"`, with their name and email. +## 6 · Get it ready to serve + +A built tenant is not yet one a storefront can read. Do this before you hand over, or tell the user what is left: + +1. **Settings first.** Languages, the default language, VAT types, price variants, stock locations and pipelines + are split between the Core API and the legacy PIM API (same token headers). A fresh tenant already has `en`, a + `No Tax` VAT type, a `default` price variant in EUR and a `default` stock location. +2. **Publish** the items. Discovery indexes only published content, and `publishItem` returns before the item is + published. +3. **Ignite Discovery** once with `igniteDiscoApi(stacks: opensearch)` on the Core API. Until then Discovery answers + HTTP 404 with "There is no ignited Tenant" in a plain JSON body. Ignite again after new shapes, components, stock + locations or vocabularies. +4. **Credentials.** The storefront's server needs the static token if Discovery or Catalogue is restricted, and an + access token pair to mint Shop API tokens (one scoped to the tenant is enough). Core stays out of the request path. +5. **Publish webhooks** (`concern: "items"`, plural) if the storefront caches Discovery reads. + +Every setting with its API and call, the `getMany` answer shapes, the ignite, the credentials table and a webhook +example are in [references/tenant-setup.md](references/tenant-setup.md). The storefront side is in [[storefront]]. + ## Rules | Topic | Rule | @@ -278,5 +303,6 @@ GraphQL calls answer HTTP 200 with the error inside the result union (`__typenam | An invite with no `expiresAt`, or one past the tenant's | A link that still looks valid after the tenant is gone | Pass the tenant's `expiresAt` | | Giving the link without the deadline | The user opens it on day four and finds nothing | Always state the date and time with the link | | Saying "it's yours, nothing to transfer" after provisioning | The user never opens the invite, and the tenant is deleted | The tenant is the agent's until a human `tenantAdmin` joins | +| Handing over without publishing and igniting | The storefront gets "There is no ignited Tenant" or no hits | Publish, `igniteDiscoApi(stacks: opensearch)`, then hand over (step 6) | Related: [[permissions]] for roles and access tokens once the human owns the tenant. diff --git a/use-crystallize/skills/agent-tenants/references/tenant-setup.md b/use-crystallize/skills/agent-tenants/references/tenant-setup.md new file mode 100644 index 0000000..023cc3f --- /dev/null +++ b/use-crystallize/skills/agent-tenants/references/tenant-setup.md @@ -0,0 +1,143 @@ +# Tenant setup: which API creates what + +Getting a tenant ready to serve a storefront, whether you provisioned it as an agent or a human gave you an access +token. The settings are split across the **Core API** (`https://api.crystallize.com/@{tenant}`) and the **legacy PIM +API** (`https://pim.crystallize.com/graphql`, most calls take `tenantId`, the id and not the identifier). Both take +the same access token pair. + +## What a fresh tenant has + +| Setting | On a new tenant | +| --------------- | ---------------------------------------------------------------------------------------------------- | +| Languages | `en`, the default. It can't be removed: "Cannot add, remove or modify system languages (en)" | +| VAT types | One, `No Tax` at 0 %. A seed that matches VAT types by percent reuses it | +| Price variants | `default`, in EUR. Its identifier can't be renamed and the variant can't be removed; change its name | +| Stock locations | `default` | +| Pipelines | None. `pipeline.getMany` answers `edges: null`, not `[]` | +| Shapes | None on an agent tenant (see SKILL.md step 2) | +| Discovery index | None. Discovery answers "There is no ignited Tenant" until the first ignite | + +A tenant that sells only in Norwegian keeps `en` and makes `no` the default. + +## Setting → API → call + +| Setting | API | Call | +| ----------------------------------- | ---- | ------------------------------------------------------------------------------------------------ | +| Languages | Core | `createTenantLanguage(input: { code, name })`, `updateTenantLanguage`, `deleteTenantLanguage` | +| Default language and currency | PIM | `tenant { update(id, input: { defaults: { language, currency } }) }`, after the language exists | +| VAT types | PIM | `vatType { create(input: { tenantId, name, percent }) }`; `update(id, input: { name, percent })` | +| Price variants | PIM | `priceVariant { create(input: { tenantId, identifier, name, currency }) }` | +| Stock locations | PIM | `stockLocation { create(input: { tenantId, identifier, name }) }` | +| Order pipelines and stages | PIM | `pipeline { create(input: { tenantId, name, stages }) }`, `addStage`, `updateStage` | +| Markets | PIM | `market { create(input: { tenantId, identifier, name, customerIdentifiers }) }` | +| Subscription plans | PIM | `subscriptionPlan { create }` (see [[subscriptions]]) | +| Custom views (tenant frontends) | PIM | `tenant { setPreferences(tenantId, input: { frontends: [{ name, url }] }) }` | +| Customer groups | Core | `createCustomerGroup` (see [[mutation]]) | +| Booking policies | Core | `createBookingPolicy` (see [[bookable-resources]]) | +| Webhooks | Core | `createWebhook(input)` ([below](#webhooks-for-cache-revalidation)) | +| Discovery index | Core | `igniteDiscoApi(stacks: opensearch)` ([below](#the-first-ignite)) | +| Static auth token, signature secret | Core | read `tenant { staticAuthToken signatureSecret }`; rotate with `regenerateTenantSecrets` | + +Traps: + +- **`UpdateVatTypeInput` rejects `tenantId`**, while `CreateVatTypeInput` requires it. A seed that sends the same + input to both fails on update. +- **The default language can be changed on an empty tenant**: `createTenantLanguage`, then PIM `tenant.update` with + `defaults.language`. Do it before content exists. The default language is the one Discovery returns relations in. +- The Core API now also has `updateTenant(input: { defaults })` and `createPriceVariant`. The PIM calls above are + the ones the builds used. +- **`getMany` answers differ.** `pipeline.getMany` and `market.getMany` return a connection + (`edges { node { id name stages { id name } } }`), and `edges` is `null` on an empty tenant. `priceVariant.getMany` + and `stockLocation.getMany` return plain lists. VAT types are read from `tenant { get(id) { vatTypes { … } } }`. +- **Pipeline and stage ids are what the Shop API returns** on orders (`pipelines { identifier stage }`). A + storefront that shows stage names reads `pipeline.getMany` at build time and writes the id → name map into its + data, not on every request. + +## The first ignite + +A tenant has no Discovery index until `igniteDiscoApi` runs once. Until then Discovery answers **HTTP 404 with a +plain JSON body**, not a GraphQL `errors` array: + +```json +{ "success": false, "message": "There is no ignited Tenant for …" } +``` + +A probe that looks only at `errors` misses it. Ignite from Core and pass the stack: + +```graphql +mutation { + igniteDiscoApi(stacks: opensearch) +} +``` + +It took about a minute on a new tenant. Ignite again after you add: + +- shapes or components (a new field can need a second ignite minutes later; check `__type(name: "")` on + Discovery before shipping code that queries it), +- stock locations (their `Stock` fields appear only after a re-ignite), +- vector vocabularies (see [[vector-ranking]]). + +Ignite indexes what is **published**. Publish first, then ignite. A component made discoverable after publishing +needs the items published again; a re-ignite alone re-indexes the old documents. Querying new fields is covered in +[[query]]. + +## Storefront credentials + +What the storefront's server needs, and where it comes from. The API for each storefront task is in [[storefront]]. + +| API | Credential | Where to get it | +| --------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Discovery | None while open (the default). The static token when **Settings → API access** restricts it | `tenant { staticAuthToken }` on Core, or the App | +| Catalogue | Open, static token or token pair, per **Settings → API access** | As above | +| Shop API | A JWT from `POST https://shop-api.crystallize.com/{tenant}/auth/token` with `{ scopes, expiresIn }` | Minted on the server with an access token pair, scoped to the tenant or not (see [[permissions]]) | +| Core | A tenant-scoped pair, for seeds, imports and webhook receivers only. Never in the storefront request path | A dedicated integration user (see [[permissions]]) | + +- **A tenant-scoped token mints Shop API tokens for its own tenant only.** Another tenant's `/auth/token` answers + 400 "User is not a member of tenant X", even for a member: check the token's scope before its membership. Once a + human owns the tenant, they create a tenant-scoped token on a dedicated user. +- **An open Discovery is public.** Everything it indexes, every price variant and every market's price list + included, is readable by anyone. Restrict it, or keep confidential terms out of it. +- The Shop API JWT is per tenant, not per shopper. Keep it on the server, cache it, and refresh it before it + expires. + +## Webhooks for cache revalidation + +A storefront that caches Discovery reads clears its cache when items are published. The publish webhook is a Core +setting: + +```graphql +mutation CreateWebhook($url: String!, $secret: String!) { + createWebhook( + input: { + name: "storefront-revalidate-publish" + concern: "items" + event: "publish" + method: POST + url: $url + headers: [{ name: "x-revalidate-secret", value: $secret }] + preserveDefaultPayload: true + graphqlQueryTarget: next + graphqlQuery: "query ($id: ID!, $language: String!) { item(id: $id, language: $language) { ... on Item { id shapeIdentifier tree { path } } } }" + } + ) { + ... on Webhook { + id + } + ... on BasicError { + errorName + message + } + } +} +``` + +- **The concern is `items`, plural.** `createWebhook` accepts any `concern` and `event` string without validation: + `item`, `product` or `nope` are all accepted, and they never fire. Add a second webhook with `event: "unpublish"`. +- **The default payload has no path**: `{ id, type, tenantId, language, userId, webhookId }`. Add a `graphqlQuery` + (it gets `$id` and `$language`; `graphqlQueryTarget: next` runs it against the Core API) and keep + `preserveDefaultPayload: true` so the receiver gets both. +- **Debug through the invocations**: `webhooks { ... on WebhookConnection { edges { node { name concern event + lastInvocation { start response { status } } } } } }`, or the `webhookInvocations` query. A webhook that never + shows an invocation has the wrong concern or event. +- The receiver is a server route in the storefront that checks the secret header and clears the cache tag for the + item (see [[storefront]]). Key the setup script on the webhook `name`, so a rerun updates instead of duplicating. diff --git a/use-crystallize/skills/agentic-commerce/SKILL.md b/use-crystallize/skills/agentic-commerce/SKILL.md new file mode 100644 index 0000000..c0fdd4d --- /dev/null +++ b/use-crystallize/skills/agentic-commerce/SKILL.md @@ -0,0 +1,207 @@ +--- +name: agentic-commerce +description: > + Let AI agents shop a Crystallize store: a shopper-facing MCP server (search, product detail, cart, checkout) on + Discovery and the Shop API, typed-spec filters parsed from the shopper's words, "Did you mean" suggestions, + baskets handed off by cartId, checkout as a destructive tool, OAuth sign-in for the shopper, MCP Apps product + cards with host detection, WebMCP tools and agentic forms in the store's own pages, and an on-site shopping + assistant, all ranked by the shopper's taste. Use when building an MCP server or connector for a shop, making a + store usable from Claude, ChatGPT, Gemini in Chrome or another agent, adding agent checkout or a hand-off to the + browser, declaring WebMCP tools, or building a chat assistant on the catalogue. Trigger on "MCP server", "MCP + connector", "shopping agent", "agentic commerce", "agent checkout", "AI assistant", "chat assistant", + "conversational commerce", "tools for Claude", "ChatGPT apps", "MCP Apps", "ui://", "structuredContent", + "updateModelContext", "callServerTool", "WebMCP", "navigator.modelContext", "document.modelContext", + "toolname", "agentic forms", "useWebMCP", "OAuth for MCP", "protected resource metadata", "DCR", "CIMD", + "PKCE", "cartId", "hand-off", "destructiveHint", "readOnlyHint", "Did you mean". +metadata: + author: Crystallize + version: "1.0" +--- + +# Agentic Commerce on Crystallize + +Agents shop a store in three places: a **remote MCP server** that Claude, ChatGPT and other hosts connect to; **WebMCP** +tools in the shopper's own browser tab; and an **on-site assistant** in the store. All three run on the same +code as the storefront: Discovery for the catalogue and ranking, the Shop API for baskets, orders and bookings. No +Core, no extra state. + +This is the active half. Being found and quoted (JSON-LD, llms.txt, Markdown twins, crawlers) is in [[seo-geo]]; +the storefront it runs inside is [[storefront]]. + +> Built and running on two Crystallize stores, Tools Universe (18 tools, typed ETIM specs, rentals) and a +> camera store (15 tools, typed lens and camera specs), September–November 2026, on Next.js 16 and the MCP TypeScript SDK +> with `@modelcontextprotocol/ext-apps`. WebMCP is designed but not shipped by either: it is an early preview +> behind a Chrome flag. + +## Three surfaces, one code path + +| | Remote MCP server | WebMCP | On-site assistant | +| ------------------ | ----------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------- | +| Agent | Claude, ChatGPT, VS Code, any MCP host | The agent in the shopper's browser (Gemini in Chrome, extensions) | Your own model loop, in the store's UI | +| Where it runs | `app/api/mcp/route.ts`, stateless Streamable HTTP | The store's pages | `app/api/assistant/route.ts`, streaming | +| Who the shopper is | OAuth access token (optional, lazy) | The page's session (cookies) | The page's session | +| Basket | `cartId` passed between calls, a hand-off link to pay | The page's cart cookie | The page's cart cookie | +| Results | MCP Apps cards, else Markdown with links | The page updates as the agent works | The store's own product cards | + +Use **the same tool names and arguments** on all three (snake_case: `search_products`, `get_product`, +`add_to_cart`, `view_cart`, `checkout`), so an agent that knows one surface knows the others. Call the same +server-side functions the storefront's actions call. + +## What an agent needs from the model + +- **Typed specs.** Numbers with units, booleans and selections, not a label/value table. Discovery indexes each as + its own filter field: a numeric in a nested piece is `___number`, a boolean is + `<…>_`, and each selection option is its own field `<…>__` filtered with + `exists: true`. "18V impact driver over 200 Nm" then becomes three hard filters instead of a fuzzy text match + where 12 V and 150 Nm score almost as well. See [[content-model]] and [[query]]. +- **One unit per numeric** where possible: Discovery range filters ignore the unit. +- **Unset booleans read `false`.** An agent filter for "without Bluetooth" must not match products that just + don't say. +- **Taxonomy topics** for product types, brands, platforms, trades, in every language: they are what the parser + matches words against, from Discovery facets. +- **A taste vector** per shopper for ranking: rebuilt from Shop API order history per call, sent as + `context.userTaste`, with `{ signal: relevance }` added when there is a text term ([[vector-ranking]]). + +## The MCP server, in short + +- Stateless: every request builds a fresh server; nothing is stored. Every tool takes `lang`, which sets market, + currency, VAT and links. +- **`lang` picks only a public market.** A contract market comes from the signed-in shopper's session on the + server, never from a tool argument: a market identifier works as a key to its price list, so an agent that can + pass one can read the contract price ([[pricing]]). +- **Search parses the shopper's words** into typed-spec, platform, brand and type filters, generated from the + content model, not from a word list; what is left goes to fuzzy text. When filters plus leftover words find + nothing, rerun without the words. +- **"Did you mean"**: up to four suggestions, each with the exact arguments to run it, when the words missed, + matched far too much, or a spec was too strict. +- **Server instructions** tell the model to show products only through tool calls, never as prose lists or + hand-built links. +- Annotations on every tool: reads are `readOnlyHint: true`; `checkout` is `destructiveHint: true`. + +Tool list, the parser and the instructions: [references/mcp-server.md](references/mcp-server.md). + +## Checkout rules + +- **Prefer the hand-off.** The basket tools return a `checkoutUrl` that opens the basket in the shopper's browser, + where they review and pay. `checkout` places the order directly, and is only called when the shopper explicitly + asks. +- **`checkout` is destructive** (`destructiveHint: true`), so hosts ask before running it. +- **Signed-in limits.** Invoice and quote checkout only for a signed-in trade buyer, after the same credit check + the storefront does. A guest card order needs the shopper's email and name: the tool asks for them rather than + inventing them. +- **The same Shop API flow** as the storefront: `setCustomer`, `setMeta`, `place`, `confirmCartBooking`, + `createFromCart` with pipelines and payments, `confirmCartBooking` again once `cart.orderId` is set. See + [[storefront]] `references/cart-checkout.md`. +- **A real payment never happens inside the conversation** in these builds: card orders in the demos are recorded + as paid. A production store hands off to its payment page ([[payments]]). + +## Baskets without sessions + +A conversation has no cookies. `add_to_cart` without a `cartId` creates a basket and returns its id; later basket +calls pass it back. The hand-off route adopts it in the browser: + +```ts +// app/mcp/cart/route.ts: `checkoutUrl` = /mcp/cart?id=…&lang=…&as=… +export async function GET(request: NextRequest) { + const q = request.nextUrl.searchParams; + const lang = isLang(q.get("lang") ?? "") ? (q.get("lang") as Lang) : "en"; + const id = q.get("id"); + const jar = await cookies(); + const { cart } = id + ? await shop<{ cart: { id: string; state: string } | null }>( + `query($id: UUID!) { cart(id: $id) { id state } }`, + { id }, + ).catch(() => ({ cart: null })) + : { cart: null }; + if (cart?.state === "cart") { + // A signed-in conversation's link carries a signed note (`as`) of the shopper, bound to this cart. + const claims = q.get("as") ? await readHandoff(q.get("as")!, siteUrl(request)) : null; + if (claims?.cart === cart.id) signInAs(jar, claims.sub); // keeps the company's prices and invoice checkout + jar.set("cart", cart.id, { httpOnly: true, sameSite: "lax", path: "/", maxAge: 60 * 60 * 24 * 30 }); + } + return Response.redirect(new URL(`/${lang}/cart`, siteUrl(request)), 303); +} +``` + +Two more hand-off routes: `/mcp/view?skus=…` (the store's own cards for a list of SKUs, for hosts without MCP +Apps) and `/mcp/buy?sku=…` (add one variant to this browser's basket). Keep `/mcp/*` hand-off routes out of the +language proxy and disallowed in robots.txt. + +## Sign-in + +Search, product detail and the basket work without an account. Tools that act for a shopper (`whoami`, +`my_orders`, `recommendations`, bookings) need an OAuth access token: the route answers **401 with +`WWW-Authenticate: resource_metadata=…`** for those tools only, and the host starts sign-in. Once signed in, every +ranking uses the shopper's taste, prices follow their price lists and VAT display, and baskets belong to their +customer. + +The Crystallize MCP server's own OAuth tokens work only on Core, so a shop still needs an identity provider for +shoppers. The demos run a small stateless authorization server where "signing in" picks a demo customer: +[references/oauth.md](references/oauth.md). + +## Product cards (MCP Apps) + +Tools that return products point at a UI resource (`_meta.ui.resourceUri`); hosts that support MCP Apps render it +as cards under the tool call, with **Add to basket** buttons that call the same tools. The text result depends on +the host: hosts that render cards get a short "N cards rendered, don't repeat them" text, the others get +Markdown with a link to `/mcp/view` and an Add-to-basket link per product. Claude's hosted apps render cards but +identify as `Claude-User` rather than declaring the capability. Details: +[references/mcp-apps.md](references/mcp-apps.md). + +## WebMCP (early preview) + +WebMCP lets a page declare its own tools to the browser's agent. **Early preview: Chromium 146+ behind +`chrome://flags/#enable-webmcp-testing`**, under a draft Community Group spec; no major browser supports it +natively yet. The declarative form attributes are ignored elsewhere, so they are safe to ship now; imperative tools +feature-detect first. Add `toolname`/`tooldescription` to the search and add-to-basket forms, never +`toolautosubmit` on a financial form, and register imperative tools (filters, product, cart) with read-only and +consequential hints. Prerequisites: labelled native controls, live-region errors and security headers. +[references/webmcp.md](references/webmcp.md). + +## On-site assistant + +A streaming model loop over the store's own tools, answered as NDJSON to a drawer: text deltas, tool status, and +product rails rendered as the store's own cards. Small, fast model by default, low effort, prompt caching on the +rules and taxonomy, the last round without tools so the reply always ends in words. +[references/on-site-assistant.md](references/on-site-assistant.md). + +## Pitfalls + +| Symptom | Cause | Fix | +| ---------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- | +| Agent recommends 12 V when asked for 18 V | Specs searched as text | Parse the words into typed-spec filters | +| "Without X" returns products that don't mention X | Unset booleans read `false` | Treat `false` as not stated; filter on `true` or on the option field | +| Model lists products in prose under rendered cards | Text result repeats the cards | Detect UI hosts; thin text result; server instructions | +| Model builds its own `/mcp/view` links or tables | Instructions don't forbid it | "The only way to show products is a tool call" | +| Hosts never prompt for sign-in | Auth error returned from inside a tool handler | 401 with `WWW-Authenticate` from the HTTP route, before the SDK | +| Basket lost between calls | Cookie-based cart in a conversation | `cartId` in every basket tool; hand-off link to adopt it | +| Signed-in basket re-priced as a guest in the browser | Hand-off link without the shopper | A signed, cart-bound `as` note on `checkoutUrl` | +| Order placed without the shopper asking | `checkout` not marked destructive, or described as the default | `destructiveHint: true`; describe the `checkoutUrl` as the default | +| Taste ranking ignores the query | `rankBy` without `relevance` | Add `{ signal: relevance }` when there is a term | +| Cards show no images | Media host missing from the resource CSP | `resourceDomains: [site, "https://media.crystallize.com"]` | +| OAuth consent popup can't report back | `Cross-Origin-Opener-Policy: same-origin` on the OAuth pages | Exclude the OAuth routes from COOP | + +## Live examples + +- [tools-universe.superfast.shop/en/mcp](https://tools-universe.superfast.shop/en/mcp): connect Claude to the + store; the 18 tools, typed-spec parsing in four languages, rentals, OAuth demo sign-in, MCP Apps cards. The MCP + endpoint is `/api/mcp`. +- [photo-store-vector.superfast.shop/llms.txt](https://photo-store-vector.superfast.shop/llms.txt): a store with an + MCP server, lens-spec parsing and a per-shopper vector ranking. +- More, by capability (`ai-agent`, `agent-checkout`): [superfast.shop/demos.json](https://superfast.shop/demos.json). + +## References + +| File | Read it when | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| [references/mcp-server.md](references/mcp-server.md) | Building the MCP endpoint, its tools, instructions, spec parser, "Did you mean" | +| [references/oauth.md](references/oauth.md) | Shopper sign-in: lazy 401, RFC 9728/8414 metadata, DCR, CIMD, PKCE | +| [references/mcp-apps.md](references/mcp-apps.md) | Product cards, host detection, the resource CSP, `updateModelContext` | +| [references/webmcp.md](references/webmcp.md) | Browser-side tools and agentic forms (early preview) | +| [references/on-site-assistant.md](references/on-site-assistant.md) | A chat assistant in the store on the same tools | + +## Related skills + +[[storefront]] for the Discovery and Shop API code these tools call, and the checkout flow; [[seo-geo]] for the +passive half; [[vector-ranking]] for taste and `rankBy`; [[content-model]] and [[taxonomy]] for typed specs and +topics; [[payments]] for the payment page the hand-off leads to; [[bookable-resources]] for bookings. diff --git a/use-crystallize/skills/agentic-commerce/references/mcp-apps.md b/use-crystallize/skills/agentic-commerce/references/mcp-apps.md new file mode 100644 index 0000000..bfa790c --- /dev/null +++ b/use-crystallize/skills/agentic-commerce/references/mcp-apps.md @@ -0,0 +1,144 @@ +# Product cards with MCP Apps + +[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) let a tool point at an HTML resource that the +host renders in a sandboxed iframe under the tool call. For a store, that means product cards with packshots, +key specs, price with its VAT label, stock and **Add to basket**, instead of a Markdown list. Claude (web, +desktop, mobile), ChatGPT, VS Code and Goose render them. + +Crystallize's own MCP server has a `product-overview` app (`ui://crystallize/product-overview.html`); it is a +good starting point for the markup. + +## One resource, many views + +One HTML document renders every result the server produces: product carousels, a product detail with its +variants and spec sheet, the basket with quantity steppers, domain views (platforms, rentals, campaigns). The +tool's `structuredContent` says which (`kind: "products"`, `kind: "cart"`, …). + +```ts +import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server"; + +export const UI_RESOURCE_URI = "ui://my-store/cards.html"; + +registerAppResource( + server, + "My Store cards", + UI_RESOURCE_URI, + { description: "Interactive product cards, product detail and basket views.", mimeType: RESOURCE_MIME_TYPE }, + async () => ({ + contents: [ + { + uri: UI_RESOURCE_URI, + mimeType: RESOURCE_MIME_TYPE, + text: appHtml(site), + // The client script comes from the store, images from the Crystallize CDN. + _meta: { + ui: { csp: { resourceDomains: [site, "https://media.crystallize.com"] }, prefersBorder: false }, + }, + }, + ], + }), +); + +// Every tool that returns products or the basket: +registerAppTool(server, "search_products", { /* … */ _meta: { ui: { resourceUri: UI_RESOURCE_URI } } }, handler); +``` + +- **The resource CSP lists the store's origin and the media host**, nothing else. With a custom media domain, + list that instead. Missing it means cards without images. +- **Serve the ext-apps client bundle from the store's origin** (`public/mcp-app.js`), refreshed by a script when + the package is upgraded, rather than from a third-party CDN. +- Ask Discovery for chat-sized images: `variants(types: "webp", maxWidth: 500)`. + +## The app + +The app talks to the host through the ext-apps `App` client. Buttons call **the same tools the model uses**, links +open through the host, and basket changes are reported back to the model: + +```js +const app = new App({ name: "My Store", version: "1.0.0" }, {}, { autoResize: true }); + +app.ontoolinput = ({ arguments: args }) => { + if (args?.cartId) state.cartId = args.cartId; + if (args?.lang) state.lang = args.lang; +}; +app.ontoolresult = (result) => show(result?.structuredContent, result); +app.onhostcontextchanged = (ctx) => applyCtx(ctx); // theme and host style variables + +const call = (name, args) => app.callServerTool({ name, arguments: args }); + +async function tellModel(c) { + await app.updateModelContext({ + content: [ + { + type: "text", + text: `Basket ${c.cartId}: ${c.count} items, ${c.total}. Pass cartId=${c.cartId} to basket tools. Checkout: ${c.checkoutUrl}`, + }, + ], + structuredContent: { cartId: c.cartId, count: c.count, total: c.total, checkoutUrl: c.checkoutUrl }, + }); +} + +// Add to basket: the same tool the model calls, with the cartId the app has seen. +el.addEventListener("click", async () => { + const res = await call("add_to_cart", { sku, cartId: state.cartId ?? undefined, lang: state.lang }); + state.cartId = res.structuredContent?.cartId ?? state.cartId; + await tellModel(res.structuredContent); +}); + +// Links open through the host; fall back to a new window. +app.openLink({ url }).catch(() => window.open(url, "_blank")); + +await app.connect(); +``` + +- **Use the host's style variables** (`--color-text-primary`, `--font-*`, `--border-radius-*`) for text outside the + cards, with `light-dark()` fallbacks, so the app follows the host's light or dark theme. Keep the store's own look + inside the cards. +- Show "Did you mean" suggestions as chips that call `search_products` with their arguments. +- A **Checkout in store** button opens the `checkoutUrl` hand-off ([../SKILL.md](../SKILL.md)). + +## Host detection: what the text result says + +The text result of a product tool is what the model reads. If the host renders cards and the text also lists the +products, the model repeats them in prose. If the host doesn't render cards and the text is thin, the shopper sees +nothing. So detect the host per call: + +```ts +import { getUiCapability } from "@modelcontextprotocol/ext-apps/server"; + +const isUi = (tool?: ServerContext) => { + // 2026-07-28 clients send their capabilities on every request. + const declared = Boolean(getUiCapability(server.server.getClientCapabilities())); + // Claude's hosted apps (web, desktop, mobile, Cowork) render cards but identify as Claude-User. + const ua = tool?.http?.req?.headers.get("user-agent") ?? ""; + const ui = declared || /^Claude-User\b/i.test(ua); + if (process.env.MCP_DEBUG) console.log(`[mcp] ui=${ui} declared=${declared} ua=${ua || "?"}`); + return ui; +}; +``` + +Then, in the result: + +- **Cards on screen**: one paragraph that says so and gives the model just enough to reason and point: + "Results for impact driver · 18 V: 6 product cards rendered for the user with pictures, key specs, prices, + stock and Add-to-basket buttons. Do not repeat them — reply with one or two sentences (your pick and why). + Shown: Name [variant] (SKU, 18 V · 226 Nm, €199, in stock); …". Add the "Did you mean" labels and their + arguments. +- **No cards**: Markdown whose first line links to `/mcp/view?skus=…` ("See these with pictures →"), then each + product as `**[name](url)**`, SKU, key specs, price, availability and `[Add to basket](buyUrl)`. No Markdown + images: most hosts don't render them, or render them huge. +- **Both** carry the same `structuredContent`, which the app renders. + +2025-era clients in stateless mode don't send capabilities, and get the Markdown. `MCP_DEBUG=1` logs the detection +per call; check it with each host you support. + +## Image blocks + +`get_product` also returns the packshot as an `image` content block (WebP, about 500 px). Claude shows it inline +even without MCP Apps. Fetch it with a short timeout and skip it above about 1.5 MB. + +## The view page for hosts without cards + +`/mcp/view?lang=…&skus=…` renders the storefront's own product cards in the tool's order, with a title. It is the +link the Markdown fallback starts with, so a shopper on any host is one click from pictures and prices. It is +`noindex` and disallowed in robots.txt. diff --git a/use-crystallize/skills/agentic-commerce/references/mcp-server.md b/use-crystallize/skills/agentic-commerce/references/mcp-server.md new file mode 100644 index 0000000..2b4399d --- /dev/null +++ b/use-crystallize/skills/agentic-commerce/references/mcp-server.md @@ -0,0 +1,385 @@ +# A shopper-facing MCP server on Discovery and the Shop API + +A Model Context Protocol server inside the storefront, at `/api/mcp`. Claude (web, desktop, mobile, Claude Code), +ChatGPT, VS Code and other MCP hosts connect to it as a custom connector. It reads only Discovery and the Shop +API, keeps no state, and calls the same functions as the storefront's server actions. + +This is a shopper's server, not the Crystallize MCP server (which is for developers working on a tenant). + +Code is trimmed from two working stores on `@modelcontextprotocol/server` and +`@modelcontextprotocol/ext-apps`, Next.js 16. + +## Layout + +| Piece | Where | +| ----------------------------------------------- | -------------------------------------------------------------------- | +| Endpoint (Streamable HTTP, stateless) | `app/api/mcp/route.ts` | +| Tools, resources, prompt, server instructions | `lib/mcp/server.ts` | +| Question → filters (typed specs, brands, types) | `lib/mcp/understand.ts`, a pure module with unit tests | +| "Did you mean" suggestions | `lib/mcp/suggest.ts`, pure, unit-tested | +| Search, cards, detail, basket views | `lib/mcp/catalogue.ts` | +| Basket and order operations without cookies | `lib/mcp/shop.ts`, the same Shop API calls as the server actions | +| MCP App (cards) | `lib/mcp/ui.ts`, client bundle served from the store | +| OAuth | `lib/mcp/{auth,env,metadata}.ts`, `app/oauth/*`, `app/.well-known/*` | +| Hand-off pages | `app/mcp/{view,buy,cart}` | +| Spec model for the parser | A JSON file generated from the content model | + +Keep `/api/*`, `/oauth/*`, `/.well-known/*` and `/mcp/{view,buy,cart}` out of the language proxy. + +## The endpoint + +Stateless Streamable HTTP: every request builds a fresh server from a factory, so it runs on serverless functions. +The route parses the body itself, so it can answer 401 for protected tools before the SDK sees the request +(see [oauth.md](oauth.md)), and adds CORS, because hosts call from their own origins: + +```ts +import { createMcpHandler, type AuthInfo } from "@modelcontextprotocol/server"; + +export const maxDuration = 60; + +const handler = createMcpHandler((ctx) => buildServer({ authInfo: ctx.authInfo, site: siteUrl(ctx.requestInfo) }), { + onerror: (error) => console.error("[mcp]", error), +}); + +const CORS: Record = { + "Access-Control-Allow-Origin": "*", + "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS", + "Access-Control-Allow-Headers": + "Content-Type, Authorization, Accept, Mcp-Session-Id, MCP-Protocol-Version, Last-Event-ID", + "Access-Control-Expose-Headers": "Mcp-Session-Id, WWW-Authenticate", + "Access-Control-Max-Age": "86400", +}; + +async function serve(req: Request): Promise { + let parsedBody: unknown; + if (req.method === "POST") { + const text = await req.text(); + try { + parsedBody = text ? JSON.parse(text) : undefined; + } catch { + return withCors( + Response.json( + { jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null }, + { status: 400 }, + ), + ); + } + req = new Request(req.url, { method: req.method, headers: req.headers, body: text }); // the body was consumed + } + const authInfo = await bearer(req); // verified access token, or undefined; an invalid one answers 401 + if (!authInfo && callsProtectedTool(parsedBody)) return challenge(req, "Sign in to use this tool"); + return withCors(await handler.fetch(req, { authInfo, parsedBody })); +} + +export const POST = serve; +export const GET = serve; +export const DELETE = serve; +export const OPTIONS = () => new Response(null, { status: 204, headers: CORS }); +``` + +## Tools + +Every tool takes `lang`, which sets market, currency, price variant, VAT, names and links. Without it, a signed-in +shopper gets their own market and everyone else the default. + +| Tool | Does | Annotations | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| `search_products` | Free text plus `category`, `brand`, `topics`, structured `specs`, stock and price bounds. Words become filters (below). Cards, facets, suggestions | `readOnlyHint` | +| `show_products` | Cards for an explicit list of SKUs, in order: the model's own shortlist | `readOnlyHint` | +| `get_product` | One product by SKU or path (any language): every variant with SKU, price, volume price, stock; the typed spec sheet; the packshot as an image block | `readOnlyHint` | +| `similar_products` | `nearestTo` in a vector vocabulary | `readOnlyHint` | +| `list_categories`, `list_brands` | The taxonomy with counts, in the market's language, with the ids the search accepts | `readOnlyHint` | +| Domain tools | Whatever the catalogue needs: battery platforms and what fits a tool, rentals and availability, campaigns | `readOnlyHint` for reads | +| `add_to_cart` | Adds a variant by SKU; creates a basket when there is no `cartId`; returns the basket with `cartId` and `checkoutUrl` | not read-only, not destructive | +| `update_cart_line` | Sets a quantity; 0 removes the line (and cancels a booking) | `idempotentHint` | +| `view_cart` | Lines, bookings, totals, `checkoutUrl` | `readOnlyHint` | +| `suggest_add_ons` | Accessories and consumables for what is in the basket | `readOnlyHint` | +| `checkout` | Places the order, with the storefront's checkout flow | **`destructiveHint`** | +| `whoami`, `my_orders`, `recommendations` | Signed in only: the shopper, their orders, their personal ranking | `readOnlyHint` | + +Register tools that return products as MCP App tools ([mcp-apps.md](mcp-apps.md)): + +```ts +const langArg = z + .enum(["en", "no", "sv", "nl"]) + .optional() + .describe("Market and language: en (EUR), no (NOK), sv (SEK), nl (EUR). Prices, names and links follow it."); +const cartIdArg = z + .string() + .uuid() + .optional() + .describe("Basket id from an earlier add_to_cart call, so items land in the same basket."); + +registerAppTool( + server, + "search_products", + { + title: "Search products", + description: + "Search the catalogue. Put the user's words in `query` as they are: numbers with units ('18V', 'over 60 Nm', 'under 2 kg'), option and yes/no names, brands and product types become hard filters on the typed specs and the taxonomy; the remaining words are a typo-tolerant text search. Returns product cards, facets and 'Did you mean' suggestions with ready-made arguments.", + inputSchema: z.object({ + query: z.string().min(1).max(160).optional(), + category: z.string().optional(), + brand: z.string().optional(), + topics: z + .array(z.string()) + .max(4) + .optional() + .describe(`Taxonomy filters. Valid ids — ${topicHint(vocab)}.`), + specs: z + .array( + z.object({ + field: z.string().describe("'.', e.g. 'drilling.torqueHard', 'power.voltage'."), + gte: z.number().optional(), + lte: z.number().optional(), + equals: z.union([z.boolean(), z.number(), z.string(), z.array(z.string())]).optional(), + unit: z.string().optional(), + }), + ) + .max(6) + .optional() + .describe(`Typed spec filters, all of which must hold. Groups and fields — ${SPEC_HINT}.`), + inStockOnly: z.boolean().optional(), + priceMin: z.number().optional(), + priceMax: z.number().optional(), + limit: z.number().int().min(1).max(24).optional(), + lang: langArg, + cartId: cartIdArg, + }), + annotations: { readOnlyHint: true, openWorldHint: false }, + _meta: { ui: { resourceUri: UI_RESOURCE_URI } }, + }, + async (args, tool) => { + /* resolve arguments, understand the words, search, suggest — below */ + }, +); + +server.registerTool( + "checkout", + { + title: "Place order", + description: + "Place the basket as an order. mode: card (anyone; a guest needs email and name), invoice or quote (signed-in trade buyers). Prefer giving the user the checkoutUrl unless they explicitly ask you to order now.", + inputSchema: z.object({ + cartId: z.string().uuid(), + mode: z.enum(["card", "invoice", "quote"]).optional(), + email: z.string().email().optional().describe("Guest checkout only."), + name: z.string().max(80).optional().describe("Guest checkout only."), + reference: z.string().max(80).optional().describe("Order reference / PO number."), + lang: langArg, + }), + annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, + }, + async ({ cartId, mode, email, name, reference, lang }) => { + const ctx = await ctxFor(lang); + const r = await placeOrder(ctx, cartId, mode ?? (ctx.session?.trade ? "invoice" : "card"), { + email, + name, + reference, + }); + if (!r.ok) return textResult(r.error, undefined, true); // e.g. "A guest order needs the shopper's email and name. Ask the user." + return textResult(`Order **${r.orderId}** placed: ${money(r.gross, ctx.lang)}.`, { + kind: "order", + orderId: r.orderId, + }); + }, +); +``` + +- **Errors are answers the model can act on**, with `isError: true`: "Unknown brand "milwauke". Brands: …", "Invalid + specs filter: …, valid fields: …". Validate arguments against the vocabulary and say what is valid. +- **The tool description lists the spec fields** (generated, compact: `drilling: torqueHard Nm, hammerMode y/n, + toolHolder [sds-plus|sds-max]`), and the topic ids. The model then knows what it can ask for. +- **The vocabulary read must not take the server down.** Catch it and fall back to empty lists. + +## Server instructions + +Instructions go to the model with the tool list. The ones that changed behaviour most (from both stores): + +``` +Language and market: every tool takes lang. Pick it from the user's language or country and keep it for the whole +conversation; prices, VAT rate, product names and links follow it. + +Specifications are typed numbers, yes/no and options, and search_products filters on them: write the user's words +into query as they are. Never filter or compare specs from memory; the result titles name the filters that were +applied. + +Imprecise questions: search results may carry "Did you mean" suggestions. When the question was vague, matched +nothing or matched far too much, offer two to four of them as a one-line question and run the one the user picks +(the arguments are given). When the result already answers the question, just answer. + +Showing products: whenever you recommend, compare or shortlist products — even ones you already have from an +earlier call — call a tool so the interactive cards render: search_products for a new query, or show_products with +the SKUs for your own picks. Never answer a product question with a prose list alone. + +Presenting results: the only way to show products is a tool call. Never build /mcp/view links or product tables +yourself. Hosts that support MCP Apps draw each result as cards; your reply then adds one or two sentences — the +pick and why — and must not repeat names, prices, SKUs or stock. If a result says "cards rendered", you are on such +a host. Otherwise start your reply with the result's "See ... with pictures →" link and present each product as +**[name](url)**, SKU, price, availability and [Add to basket](buyUrl); never use markdown images. + +Basket: add_to_cart returns a cartId. Pass it to later basket calls so everything lands in one basket. Give the +user the checkoutUrl to finish in the store; only call checkout when they explicitly ask you to place the order. + +Sign-in: search, details and the basket work without an account. whoami, my_orders and recommendations need the +shopper to sign in (the host will prompt). +``` + +Start with one paragraph on what the store sells and to whom, and add domain rules (versions, compatibility, +rentals) as the catalogue needs. + +## Typed specs from the shopper's words + +A free-text search for "18V 5Ah" or "125 mm angle grinder" is a fuzzy token match where "12V", "8.0 Ah" and a 125 +mm cutting disc score almost as well. Turn the words into the filters the index has, **generated from the content +model**, not from a word list: + +1. Generate a spec model at build time: every spec field's type, units, decimals and options, and its labels in + every content language. One store generates it from its seed model, another from shared spec definitions. +2. **Numbers with units** ("18V", "5,0 Ah", "over 60 Nm", "under 2 kg", "100–200 mm", "minst 8 Ah") go to the fields + that carry the unit. When several do (mm, kg, Nm), the field-label words in the question decide ("blade diameter + 190 mm"), then the spec families of the product type it names, then the shared pieces; what is still open is an + OR across the candidates. +3. **A bare value is a ±3 % band** (18 V is not 20 V); comparators in every language ("over", "minst", "meer + dan", "under", "høyst") make it a bound. +4. **Options and yes/no** match their labels in any language ("SDS-plus", "M class", "brushless", "with hammer + mode"); a negation ("uten Bluetooth", "without") flips them. +5. **Brands, product types, platforms** match the catalogue's own translated taxonomy (Discovery facets per + language). +6. **What is left** goes to Discovery's fuzzy text search, ranked with `relevance` plus the house and taste terms. + If the filters plus leftover words find nothing, rerun without the words: the filters alone are the better + answer. +7. Offer a structured `specs` argument too, for models that want to be explicit; explicit arguments win. + +Discovery's filter names for typed fields, and the filter for one parsed constraint: + +```ts +export const optionId = (key: string) => + key.replace(/-([a-z0-9])/g, (_, c: string) => (/\d/.test(c) ? `_${c}` : c.toUpperCase())); +const base = (key: string) => key.replace(/\./g, "_"); + +/** "specs.drilling.torqueHard" → specs_drilling_torqueHard_number; option "sds-plus" → specs_drilling_toolHolder_sdsPlus */ +export function filterName(field: Field, option?: string) { + if (field.type === "number") return `${base(field.key)}_number`; + if (field.type === "option") return `${base(field.key)}_${optionId(option ?? "")}`; + return base(field.key); +} + +function partFilter(p: Part): Record { + const f = p.field; + if (f.type === "boolean") return { [filterName(f)]: { equals: p.bool !== false } }; + if (f.type === "option") { + const opts = (p.options ?? []).map((o) => ({ [filterName(f, o)]: { exists: !p.negate } })); + return opts.length === 1 ? opts[0] : p.negate ? { AND: opts } : { OR: opts }; + } + return { + [filterName(f)]: { range: { ...(p.gte != null && { gte: p.gte }), ...(p.lte != null && { lte: p.lte }) } }, + }; +} + +/** A bare number: about this value, ±3 % (at least half a step of the field's precision). */ +function about(v: number, field: Field) { + const step = 10 ** -(field.decimals ?? 0); + const tol = Math.max(v * 0.03, step / 2); + return { gte: v - tol, lte: v + tol }; +} + +/** AND across constraints, OR across the parts of one (the same words on several fields). */ +export const constraintFilters = (constraints: Constraint[]) => + constraints.map((c) => (c.parts.length === 1 ? partFilter(c.parts[0]) : { OR: c.parts.map(partFilter) })); +``` + +Check the generated names against your tenant's Discovery schema (`ToolFilter`, `ProductFilter`, …): they follow +the component, piece and field identifiers. A field measured in several units (airflow in m³/h or l/s) can't be +range-filtered in one unit, because range filters ignore the unit: match each convertible unit and check the hits. + +## The search query + +```ts +const ranking = term ? { ...base, terms: [{ signal: "relevance", weight: 2 }, ...base.terms] } : base; +const data = await discovery( + `query McpTools($term: String!, $filters: ToolFilter, $facets: ToolFacet, $rankBy: RankByInput, $context: ContextInput, $limit: Int!, $skip: Int!) { + browse { tool(language: ${lang}, term: $term, options: { fuzzy: { fuzziness: SINGLE } }, filters: $filters, facets: $facets, + rankBy: $rankBy, context: $context, pagination: { limit: $limit, skip: $skip }) { + summary { totalHits facets } hits { score rankScore ${CARD} } } } }`, + { + term, + filters: { AND: [...constraintFilters(constraints), ...topicFilters] }, + facets: { topics: { key: "topics", limit: 200 } }, + rankBy: ranking, + ...(taste?.length ? { context: { userTaste: taste } } : {}), // omit, never null + limit, + skip, + }, +); +// With words, a hit scoring 0 only matched through a filter: noise. +const hits = term ? data.browse.tool.hits.filter((h) => (h.score ?? 0) > 0) : data.browse.tool.hits; +``` + +`rankBy`, `context` and the taste vector are covered in [[vector-ranking]]. When the shopper is signed in, rebuild +the taste from their Shop API order history per call (cached per customer), never from a stored profile. + +## "Did you mean" + +For imprecise questions, return up to four suggestions, each with the exact `search_products` arguments that run +it: + +- **Nothing matched**: a word is probably misspelt ("vinkelslipr", "milwauke") → the closest product type, brand or + platform (edit distance against the vocabulary); or a spec was too strict → the same search without it, or "at + least" instead of "about". +- **Far too much matched** ("drill") → the facets that split the result best: product types, brands, platforms, + trades. +- **Nothing in the corner the filters picked** → the words across the whole store. + +```ts +export type Suggestion = { + label: string; + why: "spelling" | "relax" | "narrow" | "widen"; + args: Record; +}; + +export function suggestionsMarkdown(list: Suggestion[]): string { + if (!list.length) return ""; + return ( + "\n\nDid you mean? Offer these to the user as a short question (if the question was imprecise), then call search_products with the chosen arguments:\n" + + list.map((s) => `- ${s.label} → \`${JSON.stringify(s.args)}\``).join("\n") + ); +} +``` + +Keep the base arguments (`lang`, `limit`) in each suggestion's `args`, and drop `cartId`. The cards widget shows +the suggestions as chips. + +## Results the model can't misuse + +- Every product carries its `url` (the storefront page in the market's language), `buyUrl` + (`/mcp/buy?sku=…&lang=…`) and, for lists, a `viewUrl` (`/mcp/view?skus=…`). +- `get_product` also returns the packshot as an `image` content block (WebP, about 500 px, under 1.5 MB). Hosts + show it inline even without MCP Apps. +- Prices say their currency and whether they are incl. or excl. VAT. +- Titles name the filters that were applied ("Results for impact driver · 18 V · ≥ 200 Nm"), so the model can + tell the user what it searched for. + +## Resources and prompts + +- `store://spec-fields`: every filterable spec field with type, units and options (the same text as the tool + description hint). +- `store://how-it-works`: Markdown on typed specs, ranking and prices. +- A prompt that guides a job to a basket (`kit-out` with a `job` argument; `shop-for` with a `need`). +- The MCP App resource ([mcp-apps.md](mcp-apps.md)). + +## Testing + +```bash +claude mcp add --transport http my-store http://localhost:3000/api/mcp +claude -p "Find an 18V impact driver over 200 Nm from the my-store server, priced for Norway" +npx @modelcontextprotocol/inspector # against the local endpoint +``` + +- **Unit tests** (`node:test`) on the pure modules: question → filters in every language, structured spec + arguments, multi-unit checks, "Did you mean". +- **A smoke test** against a running server: discovery documents, the 401 gate, searches in each language, + details, basket and hand-off, the UI resource, DCR + PKCE + consent + token + signed-in calls. Don't place real + orders from it; check that checkout asks a guest for their details. +- **Claude.ai and other hosted apps** need a public URL (a deployment, or a tunnel such as `cloudflared tunnel + --url http://localhost:3000`): add `https:///api/mcp` as a custom connector, with "Sign in when needed". diff --git a/use-crystallize/skills/agentic-commerce/references/oauth.md b/use-crystallize/skills/agentic-commerce/references/oauth.md new file mode 100644 index 0000000..31b2352 --- /dev/null +++ b/use-crystallize/skills/agentic-commerce/references/oauth.md @@ -0,0 +1,181 @@ +# Shopper sign-in for an MCP server + +The MCP specification makes the server an OAuth 2.1 resource server; something has to be the authorization +server. For a production store that is the shop's identity provider. The two demo stores run their own small, +stateless authorization server, where "signing in" means choosing which demo customer the assistant shops as. + +The Crystallize MCP server's own OAuth tokens work only on the Core API, so they can't identify a shopper to a +store. A shop still needs its own identity provider. + +## The flow + +``` +Host ── tools/call whoami (no token) ──▶ /api/mcp ── 401 + WWW-Authenticate: resource_metadata=… +Host ── GET /.well-known/oauth-protected-resource/api/mcp ──▶ authorization_servers: [site] +Host ── GET /.well-known/oauth-authorization-server ──▶ authorize / token / register, PKCE S256, CIMD +Host ── POST /oauth/register (DCR) or client_id = its metadata document URL (CIMD) +Browser ─ GET /oauth/authorize?… ──▶ consent page: pick a customer ──▶ POST /oauth/approve +Browser ─ 303 → redirect_uri?code=…&state=…&iss=… +Host ── POST /oauth/token (code + code_verifier) ──▶ access_token (1 h) + refresh_token (30 d, rotating) +Host ── retries with Bearer token ──▶ personalised answer +``` + +## Lazy authentication + +`initialize`, `tools/list` and the public tools never need a token, so the connector works at once. Only tools +that act for the shopper answer 401, and only a **transport-level** 401 makes a host start sign-in; a tool handler +can't produce one. So the gate runs in the route, on the parsed JSON-RPC body, before the SDK: + +```ts +export const PROTECTED_TOOLS = new Set(["whoami", "my_orders", "recommendations"]); + +function callsProtectedTool(body: unknown): boolean { + const messages = Array.isArray(body) ? body : [body]; + return messages.some( + (m) => + m && + typeof m === "object" && + (m as { method?: unknown }).method === "tools/call" && + PROTECTED_TOOLS.has(String((m as { params?: { name?: unknown } }).params?.name)), + ); +} + +function challenge(req: Request, description: string, error = "invalid_token", status = 401): Response { + const metadata = `${siteUrl(req)}/.well-known/oauth-protected-resource/api/mcp`; + return withCors( + Response.json( + { error, error_description: description }, + { + status, + headers: { + "WWW-Authenticate": `Bearer error="${error}", error_description="${description}", resource_metadata="${metadata}", scope="${SCOPE}"`, + }, + }, + ), + ); +} +``` + +An invalid or expired token is refused outright with the same challenge, so the client refreshes or re-authorises. +Public tools still personalise when a valid token comes along. + +## Discovery documents + +RFC 9728 protected-resource metadata at `/.well-known/oauth-protected-resource/api/mcp` (and at the bare +`/.well-known/oauth-protected-resource`), and RFC 8414 authorization-server metadata at +`/.well-known/oauth-authorization-server`: + +```ts +export function protectedResourceMetadata(req: Request) { + return { + resource: mcpUrl(req), + authorization_servers: [siteUrl(req)], + scopes_supported: [SCOPE], + bearer_methods_supported: ["header"], + resource_name: "My Store MCP", + resource_documentation: `${siteUrl(req)}/en/mcp`, + }; +} + +export function authorizationServerMetadata(req: Request) { + const issuer = siteUrl(req); + return { + issuer, + authorization_endpoint: `${issuer}/oauth/authorize`, + token_endpoint: `${issuer}/oauth/token`, + registration_endpoint: `${issuer}/oauth/register`, + scopes_supported: [SCOPE], + response_types_supported: ["code"], + response_modes_supported: ["query"], + grant_types_supported: ["authorization_code", "refresh_token"], + token_endpoint_auth_methods_supported: ["none"], + code_challenge_methods_supported: ["S256"], + client_id_metadata_document_supported: true, + authorization_response_iss_parameter_supported: true, + }; +} +``` + +Serve both with CORS and `Cache-Control: public, max-age=300`. For a production store, point +`authorization_servers` at the identity provider and drop the rest of this file. + +## A stateless authorization server (demo) + +Every artefact (the client registration, the code, the access and refresh tokens, the basket hand-off) is a signed +JWT (HS256, `jose`), each with its own `typ`, so nothing needs a database: + +- **Clients.** Dynamic Client Registration (RFC 7591) for public clients: the registration _is_ the `client_id`. + Client ID Metadata Documents: the `client_id` is an https URL; fetch it, check its `client_id` matches and the + redirect URI is listed, and show the host's name on the consent page. Claude supports both ("Register + automatically" and "Use Claude's published identity"). +- **Redirect URIs** are https, or http on loopback. Loopback redirects match with the port ignored (RFC 8252 + §7.3), which Claude Code needs. +- **Codes** live 5 minutes, bound to client, redirect URI, PKCE challenge (S256 only) and resource. +- **Access tokens** live 1 hour, with `aud` = the MCP URL; they are rejected anywhere else. +- **Refresh tokens** live 30 days and rotate on every use (a fresh `jti`). They can't be revoked individually: + fine for a demo, not for production. +- **The token endpoint** accepts form-encoded bodies (and JSON), verifies PKCE, checks `resource` matches, and for + CIMD clients checks the document still exists on refresh. + +```ts +export async function verifyAccessToken(token: string, issuer: string, resource: string): Promise { + try { + const { payload } = await jwtVerify(token, authSecret(), { issuer, audience: resource, typ: "at+jwt" }); + return { + token, + clientId: payload.cid as string, + scopes: String(payload.scope ?? SCOPE) + .split(" ") + .filter(Boolean), + expiresAt: payload.exp, + resource: new URL(resource), + extra: { shopper: payload.sub }, + }; + } catch (error) { + const expired = error instanceof joseErrors.JWTExpired; + throw new OAuthError(OAuthErrorCode.InvalidToken, expired ? "Token expired" : "Invalid token"); + } +} +``` + +The `sub` is the shopper; the tools turn it into the Shop API customer (for a trade buyer, the company), their +price-list markets and their taste. + +## The issuer URL + +The issuer, the resource identifier and every link handed to the model are built from one function, and must be +stable per deployment: + +```ts +export function siteUrl(req?: Request | null): string { + const explicit = process.env.MCP_SITE_URL?.replace(/\/$/, ""); + if (explicit) return explicit; + if (req) { + const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host"); + const proto = + req.headers.get("x-forwarded-proto")?.split(",")[0] ?? + (host && /^(localhost|127\.0\.0\.1|\[::1\])(:|$)/.test(host) ? "http" : "https"); + if (host) return `${proto}://${host}`; + } + if (process.env.VERCEL_PROJECT_PRODUCTION_URL) return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`; + return SITE_URL; +} +export const mcpUrl = (req?: Request | null) => `${siteUrl(req)}/api/mcp`; +``` + +The canonical production URL (for SEO) is deliberately not first: a local or preview server would then issue +tokens for production. Set `MCP_SITE_URL` to the tunnel's origin when testing through a tunnel. + +## Environment + +| Variable | Purpose | +| ----------------------------------------- | --------------------------------------------------------------------------- | +| `CRYSTALLIZE_ACCESS_TOKEN_ID` / `_SECRET` | The Shop API (baskets, orders, bookings). Discovery needs nothing when open | +| `MCP_AUTH_SECRET` | Signs the OAuth artefacts and basket hand-offs. A long random string | +| `MCP_SITE_URL` | The public origin for the issuer and links, when the request host isn't it | + +## Browser headers on the OAuth pages + +An MCP client may open the consent page in a popup and read the result through `window.opener` after the redirect +back. `Cross-Origin-Opener-Policy: same-origin` cuts that: exclude the OAuth routes from COOP ([[storefront]] +security headers). diff --git a/use-crystallize/skills/agentic-commerce/references/on-site-assistant.md b/use-crystallize/skills/agentic-commerce/references/on-site-assistant.md new file mode 100644 index 0000000..ab37f56 --- /dev/null +++ b/use-crystallize/skills/agentic-commerce/references/on-site-assistant.md @@ -0,0 +1,205 @@ +# An on-site shopping assistant + +A chat drawer in the store, answered by a streaming model loop over the store's own tools: Discovery for the +catalogue and ranking, the Shop API for the basket and order history. Results render as the store's own product +cards, ranked by the shopper's taste. Code is trimmed from a working store (`app/api/assistant/route.ts`, +`lib/assistant/*`), on the Anthropic TypeScript SDK. + +## The route + +`POST /api/assistant` takes the page's language and the conversation as plain text, and answers NDJSON: text +deltas, tool status, product rails and basket updates, then `done`. + +```ts +export const maxDuration = 60; + +// A small, fast model by default; override with an environment variable to trade speed for depth. +const MODEL = process.env.ASSISTANT_MODEL || "claude-haiku-5-5"; +/** Tool rounds per reply; the last one runs without tools so the model always closes with words. */ +const MAX_ITERATIONS = 5; + +const Body = z.object({ + lang: z.enum(LANGS), + messages: z + .array( + z.object({ + role: z.enum(["user", "assistant"]), + content: z.string().max(4000), + shown: z + .array(z.object({ sku: z.string(), name: z.string() })) + .max(60) + .optional(), + }), + ) + .min(1) + .max(60), +}); + +export type AssistantEvent = + | { type: "text"; delta: string } + | { type: "tool"; name: string; status: "start" | "done" | "error" } + | ProductsEvent // a rail of cards + | CartEvent // the basket changed + | { type: "error"; code: "config" | "busy" | "network" | "api" | "internal" | "long" } + | { type: "done" }; + +export async function POST(req: Request) { + const body = Body.parse(await req.json()); + const ctx = await assistantContext(body.lang); // session, taste, VAT mode, basket, orders, from cookies + const encoder = new TextEncoder(); + const stream = new ReadableStream({ + async start(controller) { + const emit = (e: AssistantEvent) => controller.enqueue(encoder.encode(JSON.stringify(e) + "\n")); + try { + await converse(ctx, toMessageParams(body.messages), emit, req.signal); + } catch (error) { + emit({ type: "error", code: errorCode(error) }); + } finally { + emit({ type: "done" }); + controller.close(); + } + }, + }); + return new Response(stream, { + headers: { + "Content-Type": "application/x-ndjson; charset=utf-8", + "Cache-Control": "no-store", + "X-Accel-Buffering": "no", + }, + }); +} +``` + +**The drawer keeps text only.** Products it showed ride along with each assistant turn as a note ("Shown to the +shopper as cards: Name [SKU]; …"), so "add the second one" still resolves without sending tool results back. +Merge two turns of the same role in a row (an answer that failed half-way), and drop leading assistant turns. + +## The loop + +```ts +async function converse( + ctx: AssistantContext, + messages: Anthropic.MessageParam[], + emit: (e: AssistantEvent) => void, + signal: AbortSignal, +) { + const client = new Anthropic(); + const system = await systemPrompt(ctx); + let retries = 0; + for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) { + const finalRound = iteration === MAX_ITERATIONS - 1; + const stream = client.messages.stream( + { + model: MODEL, + max_tokens: 4000, + system, + tools: TOOLS, + ...(finalRound ? { tool_choice: { type: "none" as const } } : {}), // end in words, not a rail + messages, + output_config: { effort: "low" }, // the tools do the thinking; keep the chat snappy + }, + { signal }, + ); + stream.on("text", (delta) => emit({ type: "text", delta })); + + let message: Anthropic.Message; + try { + message = await stream.finalMessage(); + retries = 0; + } catch (error) { + // With eager input streaming, a tool input that can't be parsed rejects here: re-issue the turn. + const unparseable = error instanceof SyntaxError || (error instanceof Error && /JSON/i.test(error.message)); + if (!unparseable || error instanceof Anthropic.APIError || signal.aborted || retries++ >= 2) throw error; + continue; + } + + if (message.stop_reason === "refusal") return; + const uses = message.content.filter((b): b is Anthropic.ToolUseBlock => b.type === "tool_use"); + if (!uses.length) return; + messages.push({ role: "assistant", content: message.content }); + + // Tools in one turn run together; writes (add to basket) run after the reads. + const reads = uses.filter((u) => u.name !== "add_to_basket"); + const writes = uses.filter((u) => u.name === "add_to_basket"); + const outcomes = new Map( + await Promise.all(reads.map(async (u) => [u.id, await runTool(ctx, u.name, u.input)] as const)), + ); + for (const u of writes) outcomes.set(u.id, await runTool(ctx, u.name, u.input)); + + const results: Anthropic.ToolResultBlockParam[] = []; + for (const use of uses) { + const outcome = outcomes.get(use.id)!; + for (const r of outcome.rails ?? []) if (r.items.length) emit(r); // cards go to the UI, not the model + if (outcome.cart) emit(outcome.cart); + results.push({ + type: "tool_result", + tool_use_id: use.id, + content: outcome.text, + ...(outcome.isError ? { is_error: true } : {}), + }); + } + messages.push({ role: "user", content: results }); + } +} +``` + +Map SDK errors to codes the drawer can explain: authentication → `config`, rate limit → `busy`, connection → +`network`, other API errors → `api`. + +## The system prompt: three blocks + +```ts +export async function systemPrompt(ctx: AssistantContext): Promise { + const tax = await taxonomy("en"); // keys are the same in every language: one cache entry + return [ + { type: "text", text: RULES }, // never changes + { + type: "text", + text: `Taxonomy (dimension: id (English label)).\n${taxonomyForPrompt(tax)}`, + cache_control: { type: "ephemeral" }, + }, + { type: "text", text: shopperBlock(ctx) }, // who is asking, in which language, basket, taste: last + ]; +} +``` + +The rules and the taxonomy are cached (the breakpoint after the taxonomy); the shopper block changes per request +and goes last. Rules that worked: + +- **Be terse.** At most one short sentence before a tool. After the cards, at most about 40 words: the pick and + why, naming at most one product. The cards show name, price, specs and stock; never repeat them. +- **Show products with tools, never in prose.** One tool call usually answers; two or three rails at most. Run + related searches in parallel. +- **Ask at most one clarifying question**, only when you can't sensibly search without it. Otherwise assume, say + so in a clause, and search. +- **Prices, specs and SKUs only from tool results.** Never invent products or compatibility. +- **Add to the basket only when the shopper clearly asks**, in the variant they asked for. +- **On a tool error, don't retry in the same reply**; say so in one sentence. +- **Answer in the shopper's language**, with the trade's own terms. +- Plain sentences; no lists, headings, tables or links. + +The shopper block: language, market, currency and VAT mode; the signed-in shopper, company and price lists; their +taste in words; recent orders; the basket. When the customer layer can't be read, say so and answer as for a +guest rather than failing the chat. + +## The tools + +The assistant's tools wrap the same functions as the MCP server and the server actions: `search_products`, +`similar_products`, `product_details`, `add_to_basket` (the cookie basket), plus taste tools a store can only offer +on-site: search with a composed taste vector ("shop as another trade"), "complete my kit" from what the shopper +owns, explain my profile. Results come back as text for the model and as rails of cards for the UI. + +## Lessons from other builds + +- **Small models show text written before a tool call** (a larger one hid it), and sometimes write the answer both + before and after the tools: dedupe in the UI. Ordering "answer text, then a closing visual tool" saves a step. +- **Cache the whole conversation, not only the system prompt, on every step, and use low effort.** One build went + from 13.6 s to about 9 s per answer, and first text from about 11 s to 4–6 s. +- **Grounding that is too strict makes the model refuse.** Forbid unsourced numbers and claims; allow it to + explain documented principles. +- **SDK history traps.** With the AI SDK (v7), `agent.generate().response.messages` holds only the last step: use + `result.responseMessages`, or earlier tool calls silently drop out of multi-turn history. With extended + thinking, thinking blocks are bound to the conversation: don't trim history, keep it append-only. +- **Live regions**: the conversation is `role="log"`, but don't announce it token by token; debounce, and show + "thinking" as `role="status"` text ([[storefront]] accessibility). +- **Render model output as elements**, never `innerHTML`. Keep conversations in `sessionStorage`. diff --git a/use-crystallize/skills/agentic-commerce/references/webmcp.md b/use-crystallize/skills/agentic-commerce/references/webmcp.md new file mode 100644 index 0000000..9f7e1b3 --- /dev/null +++ b/use-crystallize/skills/agentic-commerce/references/webmcp.md @@ -0,0 +1,95 @@ +# WebMCP: tools in the store's own pages + +> **Status: early preview.** WebMCP runs in Chromium 146.0.7672+ with `chrome://flags/#enable-webmcp-testing`, +> under a draft W3C Community Group spec, and no major browser supports it natively yet. Chrome-specific parts: +> `consequentialHint` from Chrome 154; `toolactivated`/`toolcancel` dispatched on `document.modelContext` from +> Chrome 156 (on `window` before that). Neither Crystallize store behind this skill ships WebMCP yet: what follows +> is the design from a Modern Web Guidance v1.0 audit of one of them, not tested code. Follow Chrome's MWG guides +> (`guides/webmcp/webmcp.md`, `agentic-forms.md`, `agentic-javascript-tools.md`) for the API itself. + +## How it relates to the MCP server + +| | Remote MCP server ([mcp-server.md](mcp-server.md)) | WebMCP | +| --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Agent | Claude, ChatGPT and other hosts, with no browser session | The agent inside the shopper's own tab (Gemini in Chrome, extensions, DevTools) | +| Shopper | OAuth token | The page's session: cookies, market, VAT mode, taste | +| Basket | `cartId` and a hand-off link | The page's cart cookie; no `cartId`, no OAuth | +| What the shopper sees | Cards in the chat | The page itself updating as the agent works | + +Both call the same code: the storefront's server actions (`addToCart`, `setQuantity`, the cart view, checkout, +booking availability) and the same search and ranking as the MCP tools. **Use the MCP server's tool names** +(snake_case, the same nouns), so an agent that knows one surface knows the other. + +## Prerequisites + +Fix these first; they are also what the tools' schemas are built from: + +- **Labelled native controls.** Quantity is ``, not a `` + between buttons. Variant options are radio inputs in a `fieldset`/`legend`. +- **Errors in live regions**, and returned to the agent as strings. +- **Security headers**, at least the companion headers and a Report-Only CSP: tools act with the shopper's session, + so an XSS becomes an agent acting as the shopper ([[storefront]] security headers). + +## Declarative: agentic forms + +Self-contained forms get `toolname` and `tooldescription`, and `toolparamdescription` on their fields. Browsers +without WebMCP ignore the attributes, so they are safe to ship now. + +| Form | Attributes | Notes | +| -------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Header search | `toolname="search_products"`, a `tooldescription` naming what can be searched, `toolautosubmit` (read-only) | `toolparamdescription` on `q` with examples. Wrap the form in ``. On `agentInvoked`, `respondWith` the results JSON instead of navigating | +| Add to basket | `toolname="add_to_cart"`, `toolautosubmit` (low-risk and reversible) | Wrap the variant `fieldset` and the quantity input in the form. `respondWith` the updated basket summary | +| Card checkout | `toolname="place_order"`, **no** `toolautosubmit` (financial) | The browser stops for the shopper to review. Style `form:tool-form-active` and `button:tool-submit-active` | +| Invoice, quote | `toolname="order_on_invoice"`, `toolname="request_quote"`, no autosubmit | `toolparamdescription` on the PO reference and project fields | + +```html + + +
+ +
+
+``` + +**Never `toolautosubmit` on a form that spends money.** Not declarative: facet sidebars made of links, and forms +with highly dependent fields (a rental booking where depot, period and start day depend on each other and on +fetched availability). + +## Imperative: tools registered in JavaScript + +For what isn't a form: filters, the current product, the cart. In React, register them with `useWebMCP` from +`use-webmcp-tool` (the package MWG mandates for React), in one client component mounted in the layout, using +`enabled` per route rather than conditional hooks. + +| Tool | Route | Does | Hint | +| ------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| `list_filters` | Category, brand pages | The facet groups and values with counts on this page | `readOnlyHint: true` | +| `filter_products` | Same | Navigates to the filtered URL, waits for the render, returns the active filters and the count | `readOnlyHint: true` | +| `get_product` | Product page | The current product: variants (SKU, price in the active VAT mode, stock) and typed specs, in the MCP tool's shape | `readOnlyHint: true` | +| `view_cart` | All | Basket lines and totals; opens the drawer | `readOnlyHint: true` | +| `update_cart_line` | All | Sets a quantity; 0 removes the line | none (reversible) | +| Booking availability, `book_…` | Bookable products | Wrap the availability and booking actions | read-only, then `consequentialHint: true` | +| `checkout` | Cart | Only if you want one tool rather than the checkout forms | `consequentialHint: true` | + +- **Feature-detect** (`'modelContext' in document`) before registering anything. +- **Validate input inside `execute`**, pass the `AbortSignal` on to `fetch`, and **return errors as values** + (`{ error }`) rather than throwing. +- **Register per page with an `AbortSignal`**, so tools disappear when the shopper navigates away. +- `consequentialHint` is not an enforcement mechanism: keep the in-page confirmation for orders. +- Add `webmcp-types` to `tsconfig` `types`. + +## Testing + +Test with the Chrome flag on, and in a Node test through `getTools()` / `executeTool()`. Your own on-site +assistant can later discover the page's tools the same way, for example to open the cart drawer. diff --git a/use-crystallize/skills/bookable-resources/SKILL.md b/use-crystallize/skills/bookable-resources/SKILL.md index 27b0d26..5f33388 100644 --- a/use-crystallize/skills/bookable-resources/SKILL.md +++ b/use-crystallize/skills/bookable-resources/SKILL.md @@ -14,7 +14,7 @@ description: > "pool", "units". metadata: author: Crystallize - version: "1.0" + version: "1.1" --- # Crystallize Bookable Resources @@ -57,8 +57,20 @@ Shop createFromCart the order. It only snapshots the reservatio Shop confirmCartBooking once the cart has its orderId (optionally also before payment) ``` -Everything a storefront does is on Discovery and the Shop API. **Core is for setup only** — policies, -pools and publishing are admin-time work, never called from a storefront at runtime. +## Which API does what + +| Task | API and endpoint | Who calls it | +| ------------------------------------------------------------ | ------------------------------------ | ------------------------------------- | +| The pool, unit meta and `policySnapshot` on a product page | Discovery (`bookable { … }`) | Storefront server, cached | +| Availability, `nearestAvailability`, `checkBooking` | Shop API `/cart` | Storefront server, after the product | +| Hold, change, release; `place`; `confirmCartBooking` | Shop API `/cart` | Storefront server, payment webhook | +| The order and its `reservations` snapshot | Shop API `/order` (`createFromCart`) | Payment webhook | +| Read or cancel any reservation, maintenance blocks, calendar | Shop API `/booking/admin` | Staff tools, server only | +| Policies, pools, `reapplyBookablePolicy`, publishing | Core API | Setup scripts and admin, never a page | + +Everything a storefront does is on Discovery and the Shop API, and every Shop API call runs on the +server (a server action or route): the Shop token never reaches the browser. **Core is for setup only.** +Discovery never serves availability. The API contract for the whole storefront is in [[storefront]]. ## Is this tenant bookable? @@ -83,7 +95,31 @@ for the policies to find out whether this session can manage them: A connection means yes. `FORBIDDEN` means the role lacks the `bookingPolicies` permission. That usually happens on a custom role created before bookings existed, and it is fixed on the role, not in the query. Putting a pool on a product is a second permission: `setBookable`, `reapplyBookablePolicy` -and `clearBookable` need `productBookable` on top of the right to edit the item. +and `clearBookable` need `productBookable` on top of the right to edit the item. One earlier build +(2026-09) got `ExperimentalFeaturesNotAvailableError` here instead: then booking is not enabled on that +tenant, whatever the role. + +## Storefront rules + +Learned on four storefront builds (machine rental, a hotel, design appointments, machine hire). Each is +detailed in [booking-flow](references/booking-flow.md). + +1. **Customer first, full flow, even for seeds.** A reservation records its customer only at + `bookSkuItem`/`hydrate`, and its order only from a `confirmCartBooking` after `createFromCart`. + Reservations seeded with `place` and a confirm, without a customer or an order, show "No customer / No + order" in the admin, and no cart call can repair them. +2. **The availability buckets are the admission test.** They already include the policy's buffers on + both sides, so a window is free when every bucket of `[start, end)` has room. +3. **Lay the day slots on the booking grid**, not on UTC midnight, or every hire looks a day longer. +4. **Write the refusal text yourself.** A refusal's `message` is only its type name; branch on + `__typename`. +5. **Validate bookable lines yourself.** A plain `addSkuItem` of any variant of a bookable product is + accepted, and nothing is reserved. +6. **Build the confirmation page from the order.** Its meta carries a `reservations` snapshot, with + `orderId` after the second confirm. `OrderFromCartInput` has no `meta`: set it on the cart before `place`. +7. **Enforce the cancellation window yourself after the order.** The cart cannot cancel an ordered + reservation, and `/booking/admin` `cancel` ignores the window. A "cancel my booking" page compares the + start with `policySnapshot.cancellationWindow` before it calls `cancel` on the server. ## Failure modes @@ -107,6 +143,9 @@ rest name themselves. | `InvalidRange` on a date far ahead | The window is past the policy's `advanceWindow` | Widen the policy, or cap the calendar at the shortest `advanceWindow` in the basket | | `CancellationWindowClosed` when removing a basket line | The window applies to holds that were never bought | Re-hydrate the cart without that line instead | | `Unexpected error.` from `addCartItem` or `removeCartItem` | They refuse a booking line | `hydrate` with the new quantity, or without the line | +| The calendar shows every hire one day longer | The `availability` range starts at UTC midnight, the periods at 07:00 local | Start the range where the periods start | +| "Next free slot" offers a time the shop is closed | `nearestAvailability` knows no opening hours and searches the whole pool | Use it as a hint; filter the starts to opening hours and units in code | +| `Field "product" of required type "ProductInput!"` | `addExternalItem` got a `variant` without `product` | Send `variant: { price, product: { id, path } }` | | `BookablePoolKindChangeError` | Capacity → units while a capacity pool is published | `clearBookable`, publish, cancel or wait out open reservations, then set units | | `BookingPolicyInUseError` on delete | Products still reference the policy (`stats.referencingProductCount`) | Move those products to another policy and publish them | @@ -119,7 +158,9 @@ rest name themselves. - [references/booking-admin.md](references/booking-admin.md) — Shop API `/booking/admin`: maintenance blocks, the reservation calendar and list, moving a reservation to another unit. - [references/modelling.md](references/modelling.md) — periods as variants, units as real machines, - what Discovery serves, and how a rental relates to the product it is a rental of. + multi-day hires, what Discovery serves, and how a rental relates to the product it is a rental of. -Related: [[mutation]] for the Core API mutations themselves, [[query]] for Discovery and the Shop API -query surface, [[pricing]] for what a booked variant costs. +Related: [[storefront]] for the API contract and the checkout request path, [[mutation]] for the Core API +mutations themselves, [[query]] for Discovery and the Shop API query surface, [[pricing]] for what a +booked variant costs, [[payments]] for the payment webhook that creates the order, and +[[agentic-commerce]] for bookings made by an agent. diff --git a/use-crystallize/skills/bookable-resources/references/booking-flow.md b/use-crystallize/skills/bookable-resources/references/booking-flow.md index cd80b05..6a9be71 100644 --- a/use-crystallize/skills/bookable-resources/references/booking-flow.md +++ b/use-crystallize/skills/bookable-resources/references/booking-flow.md @@ -37,11 +37,26 @@ slot reads `{ free: 0, bookable: true, reason: null }`: a calendar needs both. last visible day still fits. - **A run of open days does not prove the whole window is open.** Each slot is counted alone, so one unit can be free on Monday and another on Tuesday. Ask `checkBooking` before booking across several slots. +- **The slots already include the policy's buffers, on both sides of every booking.** A booking 10:00–11:00 + under a 15-minute buffer reads busy from 09:45 to 11:15 at 15-minute granularity: 09:45, because a new + booking ending at 10:00 would need its own buffer. So "this unit is free in every slot of + `[start, end)`" is the right admission test, and `bookSkuItem` refused exactly where the slots said busy. + (One build, 2026-10.) +- **Start the range on the booking grid, not on UTC midnight.** With `granularitySec: 86400` from UTC + midnight, a 07:00→07:00 Oslo hire falls into two slots, so every hire looks a day longer. Start the + range at the local period start (07:00) and the slots line up with the bookings. (Another build.) `nearestAvailability(productId, sku, around, durationSec, n, language)` answers "the next `n` windows of this length from this time" as `{ start, end }` — the right query behind a "next free slot" button. `n` defaults to 5, at most 100. It only walks forward, up to 30 days, in steps of `durationSec`: a 7-day -window is tried once a week, not every day. A `durationSec` under 260 is refused. +window is tried once a week, not every day. A `durationSec` under 260 is refused. The windows start at +the time of day of `around`. + +**`nearestAvailability` knows no opening hours and searches the whole pool.** For a four-hour job it +offered 16:00–20:00, and it takes no unit or region filter. Use it as a hint (jump the calendar to that +week), then filter the slot starts to opening hours and to the units the shopper can use in code. Opening +hours are not a booking concept; to make closed hours unbookable, `block` them on +[`/booking/admin`](booking-admin.md#take-a-unit-out-of-service). (Observed in one build.) `checkBooking(input: CartCheckBookingInput!)` is a dry run of one exact booking and returns `{ ok, reason }`, not a union. `reason` is `NotBookable`, `Conflict`, `InvalidRange` or `InvalidUnitId`: @@ -93,7 +108,9 @@ mutation Book($id: UUID, $input: CartBookingItemInput!) { `bookSkuItem` is `addSkuItem` with a window: the line is priced from the SKU like any other line. **Check `__typename`.** The four refusals are results, not GraphQL errors, so a client that only looks at -`errors` treats a refused booking as a success. +`errors` treats a refused booking as a success. **Their `message` is only the type name** +(`{ __typename: "ReservationConflict", message: "ReservationConflict" }`), apart from the cart-changed +conflict below, so the storefront writes its own text per `__typename` and per language. ### `quantity` is units out of the pool, not the length of the window @@ -111,7 +128,7 @@ So `quantity: 2` means _two machines_, or _two rooms_, for the same window — n nights". **Nothing in the booking inputs prices by duration.** A window twice as long costs the same unless the price says otherwise, and the price only comes from the SKU. -Two ways out, and the first is the one to reach for: +Three ways out, and the first is the one to reach for: 1. **Sell the duration as variants** — a day SKU, a weekend SKU, a week SKU — and book the SKU whose length matches the window. See [modelling.md](modelling.md). @@ -121,16 +138,34 @@ Two ways out, and the first is the one to reach for: `place` refuses a cart whose booked line went through `changeCartItemPricing` with `NotBookable`, even though the reservation itself survives it. A group discount works as a negative external line. (From the Boutique Universe build, a hotel on nightly rates.) +3. **When period prices matter** (a weekend and a week cost less than seven days), chain period SKUs on + one unit: a 10-day hire is a weekend SKU plus a week SKU, the cheapest cover computed in the storefront, + booked back to back with one `bookSkuItem` each on the same `unitId`. This needs zero buffers and + periods that meet (every period 07:00→07:00). Each line carries its real SKU and price, a customer's + price list applies per line, and the calendar is blocked exactly. (Observed in a machine-hire build.) + +`addExternalItem` needs the product on its variant: `variant: { price, product: { id, path } }`. +Without `product` it fails with `Field "product" of required type "ProductInput!" was not provided`. **A `unitId` and `quantity: 1` belong together.** To hold two named units, book twice — once per unit. **A bookable SKU with no window is a plain line.** `addSkuItem`, or a `hydrate` line with no `booking`, reserves nothing, and `place` and `createFromCart` let it through: the order exists and the calendar never -heard of it. Nothing warns you, so every line of a bookable product needs a `booking`. +heard of it. That holds for every variant of a bookable product, not only the one you booked. Nothing +warns you, so validate in the storefront that every line of a bookable product has a `booking`, unless +you add such a line on purpose. One build did: one window for a set of installation jobs, booked +on the first job's SKU, with the other jobs as plain lines tied to it by `meta`. **Put the customer on the cart before booking.** The reservation records who holds it at -`bookSkuItem`/`hydrate` time, and only when the cart's customer has an identifier. Nothing sets it later. -Create the cart with `hydrate(input: { customer, items: [] })`, or `setCustomer` before the first booking. +`bookSkuItem`/`hydrate` time, and only when the cart's customer has an identifier. Nothing sets it later: +`setCustomer` after `place` does not reach it. Create the cart with `hydrate(input: { customer, items: [] })`, +or `setCustomer` before the first booking. + +**Seed bookings through the full flow too.** A seed that books, places and confirms with no customer and +no order leaves reservations the admin shows as "No customer — admin-created / No order": 705 of them in +the Boutique Universe build. The cart cannot cancel them once placed, and `clearBookable` + `setBookable` +keep them. Cancel them on [`/booking/admin`](booking-admin.md) (`cancel`, `bulkCancel`), or better, seed +with a customer, `createFromCart` and the second confirm, as a shopper would. **On `ReservationConflict`, walk the other `freeUnitIds`.** Between the availability query and the booking someone else may have taken that unit. The exception is a `message` that says the cart changed: @@ -270,8 +305,19 @@ last one means a hold expired while payment was in flight; select its `missing` is all or nothing: the surviving holds stay `PENDING`, and the shopper has to pick another window for the lost one. -When payment is confirmed server-side by a gateway webhook, run the confirmation there rather than in the -browser round trip. +Every step here runs on the server: a server action for `place` and the first confirm, and the payment +gateway's webhook for `createFromCart` and the second confirm (see [[payments]]). The browser holds only +the cart id. The `cart.orderId` link took about 440 ms in one build and 500 ms in another, so the poll is +required, not defensive. + +**Order meta comes from the cart.** `OrderFromCartInput` takes no `meta`; `createFromCart` copies the +cart's meta onto the order. Write what the order needs (reference, the person who booked, the depot) +with the cart's `setMeta` before `place`. + +**Give rentals their own pipeline** when the tenant also takes ordinary orders: pass both in +`createFromCart`'s `pipelines` (ids, not names) — ordinary lines to an Orders pipeline, booked lines to a +Rentals pipeline. Do not set `placeNewOrders: true` on the first stage of more than one pipeline: every +new order then lands in all of them. (Tools Universe build.) **Do not call `fulfill`.** `createFromCart` already moves the cart to `ordered`, and the order id is the cart id. @@ -311,3 +357,13 @@ cart id. pinned unit only. The order's `meta` adds `reservations`, a JSON string with one record per reservation, real unit included, which outlives the reservation itself. A `reservations.unconfirmed` key, there only when something went wrong, lists the ids no longer held. Watch for it: the order is created either way. +- **The confirmation page needs no reservation lookup.** Each `reservations` record carries the id, + `unitId`, window, `state`, `frozenPolicy`, `customerId` and the line's meta, and `orderId` once the + second confirm has run. Read it from the order `createFromCart` returned, or from `order(id) { meta }`. + To verify `{ state: CONFIRMED, orderId }` server-side, `/booking/admin` `reservation(id)` reads any + reservation without its cart id. +- **Self-service cancellation is yours to gate.** The cart refuses to cancel an ordered reservation, and + `/booking/admin` `cancel` ignores the cancellation window (it cancelled an ordered reservation in one + build). A "cancel my booking" action therefore checks, on the server, that the start is at + least `policySnapshot.cancellationWindow` seconds away and that the session's customer owns the order, + then calls `cancel`, then refunds through the payment provider. diff --git a/use-crystallize/skills/bookable-resources/references/modelling.md b/use-crystallize/skills/bookable-resources/references/modelling.md index 60f12b9..6f48ee7 100644 --- a/use-crystallize/skills/bookable-resources/references/modelling.md +++ b/use-crystallize/skills/bookable-resources/references/modelling.md @@ -21,6 +21,15 @@ attribute — so the window is computed from data rather than from a hardcoded t Price tiers per period, currency per market and VAT all work as they do for any other variant — see [[pricing]]. +**Give each period variant its own image.** The admin's booking calendar shows the variant's image, not +the product's, so rate-plan variants without one show blank tiles. (Boutique Universe build.) + +A window is one interval, so it may span the night: a 10-hour installation job booked Monday 07:00 to +Tuesday 09:00 holds the team throughout. Counting working hours inside it is the storefront's job. + +For hires of arbitrary length, the variants can also be chained: see "`quantity` is units out of the +pool" in [booking-flow](booking-flow.md#quantity-is-units-out-of-the-pool-not-the-length-of-the-window). + ## Units are the real things A unit id should be the thing in the world: an asset tag, a room number, a registration number. Put @@ -92,6 +101,10 @@ Discovery carries the **static** bookable configuration on the item: at the `advanceWindow` without a Shop call. Product shapes can filter, facet and sort on `bookable_kind` and `bookable_poolSize`, as in `filters: { bookable_kind: { equals: "units" } }`. +A newly published bookable product on an already indexed shape appeared with its `bookable` pool about a +minute after publish, with no ignite (observed in one build). A **new** shape, and in one build even a new folder +on an existing shape, was not served until after `igniteDiscoApi` (another build); see [[query]]. + **Discovery never serves availability.** Listing pages can say "5 machines, 3 depots" from `poolSize` and the pool; anything about a date is a Shop API call. Design the page so the calendar loads after the product, not as part of the listing query — one `availability` call per visible card is a lot of calls. diff --git a/use-crystallize/skills/content-json/SKILL.md b/use-crystallize/skills/content-json/SKILL.md index d5f1d7f..07b6371 100644 --- a/use-crystallize/skills/content-json/SKILL.md +++ b/use-crystallize/skills/content-json/SKILL.md @@ -1,6 +1,9 @@ --- name: content-json description: Generate Crystallize rich text JSON, the node tree stored in `richText` components, paragraph bodies and image captions. Use when creating, converting or editing rich text for Crystallize, converting HTML or Markdown to Crystallize JSON, or debugging rich text that opens empty in the App. Also use when the user mentions "rich text JSON", "content nodes", "Crystallize content format" or the Content Transformer format. +metadata: + author: Crystallize + version: "1.0" --- # Crystallize Rich Text Content JSON @@ -143,20 +146,31 @@ Rich text input is `json`, `html`, or both, each a list. It is the same on a `ri The `html` conversion loses content. Send `json` for any of these: -| In `html` | What gets stored | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `` | Rows under a `table-body`, even with no `` in the HTML, so the App drops them all | -| `
` | A `type: null` node, not `quote`, which the App drops if it wraps a `

`. Same for any tag the format does not map, such as `` | -| `

` | `container`. With only text, the App loses the text. With inline content at the root, the App cannot open the field | -| `
`        | Line breaks are removed, so multi-line code becomes one line. Without an inner ``, the App loses the text                    |
-| ``        | `image` without `src` or `alt`                                                                                                     |
-| Attributes     | Only `id`, and `href` and `target` on ``, are kept                                                                              |
+| In `html`      | What gets stored                                                                                                                                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `
` | Rows under a `table-body`, even with no `` in the HTML (a `` becomes `table-head`), so the App drops them all. Discovery still serves them: see Reading It Back | +| `
` | A `type: null` node, not `quote`, which the App drops if it wraps a `

`. Same for any tag the format does not map, such as `` | +| `

` | `container`. With only text, the App loses the text. With inline content at the root, the App cannot open the field | +| `
`        | Line breaks are removed, so multi-line code becomes one line. Without an inner ``, the App loses the text                                                               |
+| ``        | `image` without `src` or `alt`                                                                                                                                                |
+| Attributes     | Only `id`, and `href` and `target` on ``, are kept                                                                                                                         |
 
 ## Reading It Back
 
 Rich text output on the Core and Catalogue APIs has `json`, `html` and `plainText`, with one `html` and one `plainText` string per `json` entry. On the Discovery API, a `richText` field and a paragraph's `body` take `format: json` (the default), `html` or `plainText`, and `html` comes back as one string.
 
 - **A `json` entry is a node or an array of nodes**, the second from `html` input with several top-level elements. Handle both when editing. Before rendering, flatten with `json.flat()`: `` from `@crystallize/reactjs-components` renders nothing for an array entry.
+- **Discovery serves `html`-written tables as semantic nodes.** A `
` with `` and ``, sent in + `html`, comes back from Discovery with `format: json` as `table` → `table-head` / `table-body` → `table-row` → + `table-head-cell` / `table-cell`, and with `format: html` as clean `
…` markup. So a storefront + that reads Discovery can render or convert these tables (for example to Markdown) without loss. The App is the part + that drops them: it expects `table-row` directly under `table` (see [Table with a header row](#table-with-a-header-row) + and "What the Crystallize App Keeps"). Write tables as `html` when only the storefront reads them, and as App-shaped + `json` when editors will open the field. Lists come back as `unordered-list` / `ordered-list` / `list-item` and bold + as `strong`. +- **Rich text inside a piece in a `componentMultipleChoice`** has been reported to come back from Discovery as an + array of arrays. A re-read on the same tenant (148 entries, 2026-11-12) gave one node per entry, so this is most + likely the array-entry case above (several top-level elements in one `html` string). Flatten either way. - **`Invalid crystallize-content-chunk:`** at the start of a Core API `html` or `plainText` string means that `json` entry is malformed, for example a `textContent` that is not a string. ## Examples diff --git a/use-crystallize/skills/content-model/SKILL.md b/use-crystallize/skills/content-model/SKILL.md index 60d1261..22d0681 100644 --- a/use-crystallize/skills/content-model/SKILL.md +++ b/use-crystallize/skills/content-model/SKILL.md @@ -1,9 +1,9 @@ --- name: content-model -description: Design content models in Crystallize using Shapes, Pieces, Components, and Grids, and decide when a classification is a Topic Map, a Selection or a document. Create product structures, define document types, design relationships between items, implement classification bridges, configure item relations with shape restrictions, model brand and product colours with the Colors component (hex, RGB, HSL, CMYK, Pantone, RAL, colour presets, swatches), and architect scalable data models. Use when modeling content, creating shapes or pieces, defining components, designing relationship patterns, implementing semantic bridges, configuring variant components, building a page builder, setting component validation, localization or Discovery flags, or choosing between a Colors component and a Selection for colour. For the topic tree itself use taxonomy, and for folder hierarchies use information-architecture. +description: Design content models in Crystallize using Shapes, Pieces, Components, and Grids, and decide when a classification is a Topic Map, a Selection or a document. Create product structures, define document types, design relationships between items, implement classification bridges, configure item relations with shape restrictions, model brand and product colours with the Colors component (hex, RGB, HSL, CMYK, Pantone, RAL, colour presets, swatches), and architect scalable data models. Use when modeling content, creating shapes or pieces, defining components, designing relationship patterns, implementing semantic bridges, configuring variant components, building a page builder, setting component validation, localization or Discovery flags, modelling typed technical specs with units, product identifiers (SKU, GTIN, MPN) or the SEO piece, or choosing between a Colors component and a Selection for colour. For the topic tree itself use taxonomy, and for folder hierarchies use information-architecture. metadata: author: Crystallize - version: "3.0" + version: "3.1" --- # Crystallize Content Model Skill @@ -71,27 +71,28 @@ Product variants have additional built-ins: `sku`, `images`, `videos`, `price`, **`variantComponents` require the same type discipline as product-level components** — apply the Component Selection Guide below. Measurable values (weight, voltage, length) → `numeric` with units. Controlled options (connection type, material) → `selection`. Free-form identifiers → `singleLine`. Do not default everything to `singleLine`. +**Typed specs are what the storefront, search engines and agents read.** A model with numerics, selections and switches (shared `power` and `physical` pieces, plus one family piece behind a `specs` choice) gets Discovery range and option filters, facets and `rankBy` fields, schema.org `additionalProperty` with UN/CEFACT unit codes, Markdown twins and agent filters from the same values. A label/value table gets none of them. Keep **one unit per numeric**, because range filters ignore the unit, and remember that an **unset switch reads `false`** in Discovery. See [Typed Specs, Units and Identifiers](references/typed-specs.md), and [[seo-geo]] for the JSON-LD. + +**Chunks on variants:** observed both ways. One build's variant chunks never published, another's published and were served by Discovery. Read one item back from Discovery before you rely on them. + **IMPORTANT:** Do NOT add components for price or stock - these are native properties managed through the product variant's built-in fields. Only create custom price/stock components for specific edge cases (e.g., tiered pricing models, subscription pricing, price modifiers for configurators). -**Product Identification:** The built-in `sku` field on product variants is the primary product identifier — use it for GTIN, EAN, ISBN, or any single identifier. Do NOT add a separate `gtin` or `ean` single-line component on the variant. If a product needs **multiple identifiers** (e.g., both ISBN-10 and ISBN-13, or a GTIN plus a legacy system ID), add a non-repeatable **identifiers chunk** with named fields to the shape: +**Product Identification:** the merchant's SKU, the GTIN and the manufacturer part number are **separate facts** (schema.org, Google Merchant Center and GS1 ask for each). A SKU used as the GTIN loses the merchant's own SKU, and a kit and the bare tool have different GTINs. + +- **Built-in `sku`** on the variant: the merchant's SKU. +- **`gtin` Single Line in `variantComponents`**: not translatable, discoverable, validated with a `pattern` for 8, 12, 13 or 14 digits. +- **`mpn` Single Line**: on the variant when it differs per variant. +- **National trade numbers** (NOBB, NRF, ISBN): one named Single Line each, never a key/value list. On the product, several can be grouped in a non-repeatable `identifiers` chunk; on variants keep them as plain Single Lines (chunks on variants are contested, see above). +- **One external system id**: the built-in `externalReference` on the item or variant. ``` -Product Shape: Book - └── identifiers (contentChunk) - ├── isbn-10 (Single Line) - ├── isbn-13 (Single Line) - └── legacy-id (Single Line) - -Product Shape: Consumer Electronics - └── identifiers (contentChunk) - ├── gtin (Single Line) - ├── ean (Single Line) - ├── upc (Single Line) - └── legacy-id (Single Line) +Product Shape: Power Tool + └── variantComponents + ├── gtin (Single Line, not translatable) + ├── mpn (Single Line, not translatable) + └── nobb-number (Single Line, not translatable) ``` -Each identifier gets its own named component — not a generic key/value pattern. This keeps the data typed, queryable, and self-documenting. Also useful during migrations to preserve old system identifiers alongside the new SKU. For a single external system ID, use the built-in `externalReference` on the item or variant. - See [Shapes Reference](references/shapes.md) and [Content Modelling Guide](references/content-modelling.md) for details. ## Component Selection Guide @@ -104,8 +105,8 @@ See [Shapes Reference](references/shapes.md) and [Content Modelling Guide](refer ### "I need to store numbers" -- **Numeric** → Measurable values with selectable units (e.g. `["g","mg","kg"]` for weight, `["cm","m","in"]` for dimensions). Configure units in `config.numeric.units`. -- **Properties Table** → Arbitrary key-value specs +- **Numeric** → Measurable values with a unit (`["kg"]`, `["mm"]`, `["V"]`). Configure units in `config.numeric.units`, one per component where you can: range filters ignore the unit. A unit list makes every empty value fail create, update and publish unless the component has `required: false` (see [Typed Specs](references/typed-specs.md#a-unit-list-makes-empty-values-fail)) +- **Properties Table** → Arbitrary key-value specs whose keys can't be known in advance. Not for known specs: it gives no filters, facets or structured data ### "I need to link to other items" @@ -117,7 +118,7 @@ See [Shapes Reference](references/shapes.md) and [Content Modelling Guide](refer ### "I need controlled options" - **Selection** → Dropdown/checkboxes with predefined options. Every option needs `key` and `value`; also set `label` (optional, but good practice — the App UI displays it; default: same text as `value`) -- **Switch** → Boolean flag (type: `boolean`) +- **Switch** → Boolean flag (type: `boolean`). Unset reads `false` in Discovery, so write only what is true - **Datetime** → Date/timestamp (type: `datetime`) - **Location** → Geographic coordinates @@ -206,14 +207,14 @@ For complete component reference with nesting rules, validation, and localizatio Leaving a config key out is a decision. This is what you get: -| Key | Left out | Set it when | -| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| `repeatable` on `contentChunk` | `true`: the chunk repeats | `false` for a group that occurs once | -| `allowDuplicates` on `componentMultipleChoice` | `true`: a choice can be picked several times | `false` when each choice may be picked once | -| `discoverable` | `true`: the component is indexed and returned by the Discovery API | `false` for internal data (ERP ids, notes, integration keys) | -| `required` | Not the same as `false`: an empty component is still held to its `min`, `pattern` and `units` | `false` on an optional field that has one of those rules | -| `multilingual` on a field | `singleLine`, `richText` and `colors` are stored per language; every other component is shared | `false` on `colors` that are universal, `true` on other fields that translate | -| `multilingual` on a chunk, choice or multiple choice | Structure is shared; each component inside follows its own setting | `true` to vary the structure per language. `false` forces everything inside to shared, so avoid it | +| Key | Left out | Set it when | +| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `repeatable` on `contentChunk` | `true`: the chunk repeats | `false` for a group that occurs once | +| `allowDuplicates` on `componentMultipleChoice` | `true`: a choice can be picked several times | `false` when each choice may be picked once | +| `discoverable` | `true` in the API, but builds found rich text, images and config-less components absent: set it | `true` explicitly on everything a storefront renders, `false` for internal data (ERP ids, notes) | +| `required` | Not the same as `false`: an empty component is still held to its `min`, `pattern` and `units` | `false` on an optional field that has one of those rules | +| `multilingual` on a field | `singleLine`, `richText` and `colors` are stored per language; every other component is shared | `false` on `colors` that are universal, `true` on other fields that translate | +| `multilingual` on a chunk, choice or multiple choice | Structure is shared; each component inside follows its own setting | `true` to vary the structure per language. `false` forces everything inside to shared, so avoid it | Details and the App's own defaults are in [Components Reference](references/components.md#multilingual--localization). @@ -312,7 +313,7 @@ Piece: "SEO" (not "SEO Metadata") 7. **Use chunks for grouping** - Related fields that repeat together 8. **Choose topics vs documents wisely** - Simple labels → topics, rich content → documents 9. **Plan localization early** - Set `multilingual` from the start -10. **Decide what Discovery sees** - Components are indexed by default. Set `discoverable: false` on internal fields +10. **Decide what Discovery sees** - Set `discoverable: true` explicitly on everything the storefront renders and `false` on internal fields. A component made discoverable after publishing stays empty in Discovery until the items are published again. Give every shape at least one discoverable component 11. **Apply design patterns** - Use established patterns for scalable models ## Anti-Patterns to Avoid @@ -327,7 +328,15 @@ Piece: "SEO" (not "SEO Metadata") ❌ **Mixing variant data with product data** - Use variant attributes (built-in) for size/color/sku -❌ **Adding GTIN/EAN/ISBN as a variant component** - The built-in `sku` field handles single product identifiers. For multiple identifiers, add a chunk with named single-line components (e.g., `isbn-10`, `isbn-13`, `gtin`, `ean`, `upc`, `legacy-id`) at the shape level, not on the variant. +❌ **Using the `sku` as the GTIN** - The built-in `sku` is the merchant's SKU. Put the GTIN in its own non-translatable `gtin` Single Line on the variant, and the MPN in an `mpn` Single Line, so structured data and merchant feeds get three separate facts. + +❌ **A hand-typed canonical URL field** - Canonicals and hreflang come from the item's generated paths (see [[information-architecture]]). A typed canonical goes stale on the first rename. + +❌ **Rich text for the SEO description** - It goes into ``, Open Graph and JSON-LD, which take plain text. Use a Single Line. + +❌ **Several units on one numeric** - Range filters compare the raw number, so `["m³/h", "l/s"]` mixes units in one filter. One unit per component, converted at import. + +❌ **Writing `false` for "unknown"** - An unset switch already reads `false`; a written `false` is a wrong fact. Write `true` for what an item has, and use a yes/no Selection when "no" must be stated. ❌ **Adding price or stock components to product shapes** - Products have native `price` and `stock` fields on variants. Only add custom pricing/stock components for specific edge cases (tiered pricing, subscription models, configurator price modifiers, bulk discounts) @@ -353,9 +362,9 @@ Piece: "SEO" (not "SEO Metadata") ❌ **Empty contentChunk (no components)** - A `contentChunk` with zero child components is meaningless and invalid. Always define at least 1 component inside a chunk. If you find yourself creating an empty chunk, reconsider the design. -❌ **`maxItems` as "unlimited"** - An Item Relation holds at most 75 items and 75 SKUs. A `maxItems` or `maxSkus` above 75 is rejected, so a high number like 999 fails. Leave it out for "as many as allowed". For more than 75, invert the relation or use a topic. +❌ **`maxItems` as "unlimited"** - An Item Relation component holds at most 75 items and 75 SKUs. The limit is per component, not per item: an item can hold more relations spread over components or chunk rows. A `maxItems` or `maxSkus` above 75 is rejected, so a high number like 999 fails. Leave it out for "as many as allowed". For more than 75, invert the relation or use a topic (at most 250 topics per item). -❌ **Internal fields left discoverable** - Discovery indexes every component unless it says `discoverable: false`, and the Discovery API is typically public. +❌ **Internal fields left discoverable** - Discovery indexes every component unless it says `discoverable: false`, and the Discovery API is open by default: when open, everything it serves is public. See [Content Modelling Guide](references/content-modelling.md) for detailed anti-patterns and migration strategies. @@ -402,10 +411,11 @@ Before presenting the mass operations JSON, verify: 8. **`datetime` config has no `format` field in mass operations** — the schema rejects it. A datetime created this way uses the default `date` format. `format` is only accepted by the `createShape` and `updateShape` mutations. 9. **`files` config**: if `acceptedContentTypes` is provided, each entry needs `contentType` (required). In mass operations, any `files` config must include `maxFileSize` with both `size` and `unit`. 10. **Naming conventions** — all identifiers use lowercase-with-hyphens (no camelCase, no underscores) -11. **Reusable SEO piece** — create an SEO piece and reference it from multiple shapes +11. **Reusable SEO piece** — one `seo` piece (`title` and `description` as Single Lines, `image`), discoverable, with no canonical URL field, referenced from every shape with a page. See [Pieces Reference](references/pieces.md#standard-seo-piece) 12. **Localization strategy** — translatable for marketing text, non-translatable for universal data (codes, dimensions) 13. **Colors components** — set `customColorSpaces` or `colorPresets`, or editors have nothing to enter in the App. Set `multilingual: false` when the values are universal -14. **`discoverable: false`** on internal fields +14. **`discoverable`** set explicitly: `true` on everything the storefront renders, `false` on internal fields +15. **Typed specs** — one unit per numeric, `required: false` or no unit list on optional numerics, `sku`, `gtin` and `mpn` as separate fields. See [Typed Specs](references/typed-specs.md#checklist) ## References @@ -418,5 +428,6 @@ Before presenting the mass operations JSON, verify: - [Shape Consolidation](references/shape-consolidation.md) - When and how to merge similar shapes - [Shapes Reference](references/shapes.md) - Shape types, variantComponents, and creation process - [Pieces Reference](references/pieces.md) - Reusable field sets, standard SEO piece +- [Typed Specs, Units and Identifiers](references/typed-specs.md) - Why typed specs, units and UN/CEFACT codes, unit lists that break writes, booleans, SKU/GTIN/MPN - [Taxonomies Reference](references/taxonomies.md) - Topic Maps and Grids - [[taxonomy]] — Use this skill to design topic maps (hierarchical taxonomies with `displayColor`, `pathIdentifier`, nesting). Topics are a built-in field on every item, so a shape does not reference them. diff --git a/use-crystallize/skills/content-model/references/components.md b/use-crystallize/skills/content-model/references/components.md index eb160dd..2181576 100644 --- a/use-crystallize/skills/content-model/references/components.md +++ b/use-crystallize/skills/content-model/references/components.md @@ -14,7 +14,7 @@ Choosing the right component for each piece of **additional** data determines ho | Formatted content with headings, links, lists, bold | **Rich Text** | | Long-form editorial with mixed media sections | **Paragraph Collection** | -- **Single Line** → structured, unformatted, indexable. Ideal for labels, codes, and short metadata. Note: item `name` and variant `sku` are built-in fields, not Single Line components — but additional identifiers (GTIN, EAN, UPC, MPN) beyond the built-in SKU are valid Single Line components. +- **Single Line** → structured, unformatted, indexable. Ideal for labels, codes, and short metadata. Note: item `name` and variant `sku` are built-in fields, not Single Line components. The `sku` is the merchant's own SKU; the GTIN (EAN, UPC) and the MPN are separate facts, each a Single Line of its own, on the variant. See [Typed Specs, Units and Identifiers](typed-specs.md#identifiers). - **Rich Text** → formatted text block. Stored as structured JSON, and the APIs return it as `json`, `html` and `plainText`. Supports headings, lists, links, bold, italic, inline code. Use for product descriptions, marketing copy, specification text. - **Paragraph Collection** → repeating sections, each with: title (single line) + body (rich text) + media (images/video). Use for blog posts, editorial storytelling, landing page content blocks, any content that alternates text and media. @@ -25,24 +25,30 @@ Choosing the right component for each piece of **additional** data determines ho | A measurable value with a unit (weight, length, power) | **Numeric** | | Arbitrary key-value specs (varied, not fixed) | **Properties Table** | -- **Numeric** → stores a number with one or more selectable units (e.g. g, mg, kg for weight; cm, m, in for length). Editors pick which unit applies when entering a value. Preferred when the metric is known and fixed — enables Discovery API filtering and sorting. Create one Numeric component per metric (e.g., `weight`, `length`, `power`). - - **Units config**: define the list of valid unit options in `config.numeric.units` as a string array — e.g. `["g", "mg", "kg"]`, `["cm", "m", "in"]`, `["W", "kW"]`. Editors can then select from these units when entering values. Leave empty if the unit is fixed/implied. - - **Example**: `{ "id": "weight", "name": "Weight", "type": "numeric", "config": { "numeric": { "units": ["g", "mg", "kg"] } } }` -- **Properties Table** → key-value pairs in table format. Use when keys are arbitrary or user-defined. Does NOT enable typed filtering in Discovery. Use for: technical specification sheets where keys vary per product. +- **Numeric** → stores a number with a unit. Preferred when the metric is known and fixed — enables Discovery API filtering, sorting and ranking. Create one Numeric component per metric (e.g., `weight`, `length`, `power`). + - **Units config**: the valid units go in `config.numeric.units` as a string array. Several units (`["g", "mg", "kg"]`) let editors pick one per value, but range filters then compare numbers in different units, so prefer one unit per component (`["kg"]`) and convert at import. Leave the list out if the unit is implied, or if the value is optional (see below). + - **Example**: `{ "id": "weight", "name": "Weight", "type": "numeric", "config": { "numeric": { "units": ["kg"], "decimalPlaces": 2 } } }` +- **Properties Table** → key-value pairs in table format. Use when keys are arbitrary or user-defined. Does NOT enable typed filtering in Discovery, and gives no ranking signal, structured data or agent filter (see [Typed Specs](typed-specs.md#why-typed-specs)). Use only for specification sheets whose keys truly can't be known in advance. - **Fixed keys (configured in shape)**: Keys are predefined in the shape definition. Editors fill in values for preset keys. Useful when you know the specification names upfront but prefer a table layout over individual Numeric components. - **Fluid/Dynamic keys (defined at content entry)**: Editors define both keys AND values when adding content. Useful for flexible technical specifications where key names vary by product category or are unpredictable. **Rule of thumb**: If you always know the key name upfront → use Numeric. If the keys vary per item → use Properties Table. +> **Keep one unit per Numeric.** Range filters compare the raw number and ignore the unit, so a component whose +> items use different units can't be filtered. Choose unit strings that map to UN/CEFACT codes for schema.org: see +> [Typed Specs, Units and Identifiers](typed-specs.md#numerics-and-units). + > **A unit list makes a Numeric effectively required, unless you set `required: false`.** Content for a > numeric with `units` has to name one ("No unit provided for numeric item component `voltage`. Need to > specify one of the following units: V"), even when the list holds a single unit — and a numeric input > cannot carry a unit without a number, since `number` is non-null. So with `required` left out, every item -> of that shape needs a value, on create **and** on every update that sends components. Two builds hit -> this: a `vehicle` document for an electric car with no displacement, and a variant component that only -> oils and chemicals fill, which made `updateProduct` fail on a filter for a component none of its variants -> had. If the value is genuinely optional, set `required: false` on the numeric: an empty component then -> skips the unit check, and a filled one must still name a unit. +> of that shape needs a value, on create **and** on every update, even one that doesn't send the component. +> Nine builds hit this, on create, update, upsert and publish: a `vehicle` document for an electric car with no +> displacement, a variant component that only oils and chemicals fill, and an empty piece of unit-bound +> numerics that blocked `publishItem`. If the value is genuinely optional, set `required: false` on the +> numeric: an empty component then skips the unit check, and a filled one must still name a unit. Otherwise +> drop the `units` list (the unit is still stored per value). The failures and workarounds are in +> [Typed Specs](typed-specs.md#a-unit-list-makes-empty-values-fail). Component definitions also take a **`description`**, which shows up as editor help. It is the natural place for a mapping to an industry standard — one build stored the ETIM feature code there @@ -56,7 +62,7 @@ for a mapping to an industry standard — one build stored the ETIM feature code | Product demos, tutorials, promo videos | **Videos** | | Downloadable files (PDFs, ZIPs, etc.) | **Files** | -- **Images** → auto-transcoded to responsive sizes (Avif, WebP), served via Crystallize CDN. See [[responsive-images]] for rendering them efficiently — `srcset`, `sizes`, format choice and why not to use a framework image optimizer. Supports multiple images per component (galleries, carousels). Each image gets `url`, `variants` (with width/height/size), `altText`, `caption`. Note: product variant images are built-in — use an Images component for product-level lifestyle photos, document hero images, or other non-variant media. +- **Images** → auto-transcoded to responsive sizes (Avif, WebP), served via Crystallize CDN. Discovery can't limit an images field to its first entry, so a listing card that shows one photo still carries the whole gallery with every rendition: add a one-image `cover` component (`max: 1`) for cards, and keep the gallery for the product page. See [[responsive-images]] for rendering them efficiently — `srcset`, `sizes`, format choice and why not to use a framework image optimizer. Supports multiple images per component (galleries, carousels). Each image gets `url`, `variants` (with width/height/size), `altText`, `caption`. Note: product variant images are built-in — use an Images component for product-level lifestyle photos, document hero images, or other non-variant media. - **Videos** → auto-transcoded for web/mobile streaming, CDN-delivered. Upload or embed. - **Files** → upload files for download. Use for manuals, datasheets, certificates, whitepapers. @@ -95,7 +101,7 @@ for a mapping to an industry standard — one build stored the ETIM feature code Use when the options are a fixed, small set that don't need their own content. If options need enrichment (images, descriptions), use Item Relations instead (Semantic Bridge pattern). - **API option structure**: `{ key: "red", value: "Red", label: "Red", isPreselected?: Boolean }` — `key` is used in queries/filters, `value` is the option's value, `label` is what the App UI displays to editors - **Set `label` on every option** when creating or updating a selection component. It is optional, but good practice: the App UI displays it. Default it to the same text as `value`. Supported by the Core API (Next and legacy) and mass operations. -- **Switch** → true/false toggle. Use for: "Featured", "On Sale", "Available in store", "Organic certified". +- **Switch** → true/false toggle. Use for: "Featured", "On Sale", "Available in store", "Organic certified". **An unset Switch reads `false` in Discovery**, so "no" and "not stated" look the same: write `true` for what an item has, never `false` for "unknown", and use a yes/no Selection when "no" must be stated. See [Typed Specs](typed-specs.md#booleans). - **Datetime** → date with optional time (type: `datetime`). Use for: launch date, preorder availability, expiration, event scheduling. - **Location** → latitude/longitude. Use for: store locator, pickup points, product origin. @@ -111,6 +117,7 @@ for a mapping to an industry standard — one build stored the ETIM feature code - **`customColorSpaces` decides what editors can type in the App.** With none set, the App shows no colour inputs at all, so a component with neither `customColorSpaces` nor `colorPresets` gives editors nothing to enter. Set it, usually to `["hex"]`. When it is set, the API rejects content in any other notation. When it is unset, the API accepts all of them. - **`colorPresets` with no `customColorSpaces` is how you hold editors to a brand palette.** Editors choose from the palette instead of typing hex values, which is the difference between a design system and 40 slightly different greys. This is an App rule: the API does not check content against the presets. - **`requireLabel: true`** forces every entry to be named ("Midnight Blue"). The label is what the storefront shows; the value is what it renders. + - **Discovery serves the entries as a plain list** (`palette { label hex rgb … }`), not wrapped the way the Core input is (`colors: { colors: [...] }`). **Content rules the API enforces**: `hex` is `#RRGGBB` or `#RRGGBBAA` (a short `#FFF` is rejected), `ral` is `RAL 1234`, `pantone` is `Pantone 485 C` or `485 C`, and each entry needs at least one of `hex`, `rgb`, `hsl`, `ral` or `pantone`, so a `cmyk`-only entry is rejected. @@ -152,9 +159,11 @@ These are **structural components** — they don't store data directly but organ overwrites the others. A chunk holding text that should be translated leaves `multilingual` out: the rows stay shared and each field follows its own setting. `multilingual: true` also gives each language its own rows. - - **A chunk on a variant may not publish.** One build found a variant's chunk sitting in the draft while - the published version and Discovery had `chunks: []`, where a `singleLine` on the same variant - published fine. If that happens, move the data to the product and identify each row by SKU. + - **A chunk on a variant may not publish (observed both ways; verify on your tenant).** One build found a + variant's chunk sitting in the draft while the published version and Discovery had `chunks: []`, where a + `singleLine` on the same variant published fine. Another found variant chunks published and served by + Discovery as typed fields on `ProductVariantFor`. Publish one item and read it back from Discovery + before relying on it. If it fails, move the data to the product and identify each row by SKU. - **Choice (componentChoice)** → select exactly ONE structure from a set. The editor picks which form applies, and only sees fields for that choice. Implements the **Polymorphic Choice** pattern. Use when a concept has multiple valid but mutually exclusive representations. - **Multiple Choice (componentMultipleChoice)** → select ONE OR MORE structures from a set. Similar to Choice but allows combining forms. Use when multiple structural forms can coexist on the same item. - **Common pattern**: Define each option as a **Piece** (reusable component group) for consistency across shapes @@ -721,7 +730,12 @@ Does the data need grouping/structure? ## Discoverability Rules -The **discoverable** flag determines whether a component is **indexed in the Discovery API at all**. It is **on by default**: a component is indexed unless it sets `discoverable: false`. This is not just about filtering — a component with `discoverable: false` will be completely absent from Discovery API responses. +The **discoverable** flag determines whether a component is **indexed in the Discovery API at all**. It is **on by default** in the API: a component is indexed unless it sets `discoverable: false`. This is not just about filtering — a component that is not discoverable is completely absent from Discovery API responses. + +**Set it explicitly anyway.** Builds found components missing from Discovery that nobody had turned off: rich text, `images` components (no `images` field on the type even after an ignite), and on one tenant a Single Line and a piece whose components were created with no config at all (verified 2026-11-12: absent from the Discovery type, while siblings with `discoverable: true` were there). Components added in the App start with their own explicit values. For a storefront that reads only Discovery, set `discoverable: true` on everything it renders, including text, rich text, images, selections and relations inside page-builder blocks, then ignite and check the type with `__type(name: "")`. + +- **Turning a component discoverable after publishing needs a republish.** An ignite re-indexes the old published documents, which don't have the field, so it stays empty until each item is published again. +- **Give every shape at least one discoverable component.** One build saw a shape with none get no Discovery type, which broke every search whose hits included one of its items ("Abstract type … was resolved to a type … that does not exist"). Another build saw the same error for minutes after an ignite on shapes that had discoverable components, so it may have been schema rollout (contested). Either way it costs nothing to avoid. **Discoverable left out, or `true`:** @@ -780,17 +794,14 @@ not collapse into one bucket. See "Colors vs Selection" above. **Typical use case**: System integrations. When you integrate with ERP, CRM, WMS, or other backend systems, you often need to store reference IDs and integration metadata on catalogue items. Mark these fields as non-discoverable so they're available in Core/PIM/Catalogue APIs for your integrations, but never exposed in the customer-facing Discovery API used by your website. -Remember: **non-discoverable does NOT mean "hidden"** — the data is still available in Core API, PIM API, and Catalogue API for authenticated backend use. Use permissions and access control for true security. The discoverable flag only controls whether data appears in the Discovery API (which is typically the public-facing search/filter API used on websites). +Remember: **non-discoverable does NOT mean "hidden"** — the data is still available in Core API, PIM API, and Catalogue API for authenticated backend use. Use permissions and access control for true security: when the Catalogue API is open, it serves non-discoverable components to anyone. The discoverable flag only controls whether data appears in the Discovery API, which is open by default, and when open everything it serves is public. ### Discovery vs Catalogue API -- **Discovery API** = fast search/filter engine with async indexing. Only includes discoverable component data. **Eventually consistent** — updates propagate after a short delay. -- **Catalogue API** = full content retrieval. Includes ALL component data regardless of discoverable flag. **Always in sync** — reflects changes immediately. - -**When to use each:** +- **Discovery API** = the storefront's catalogue API: item by path, listings, search, facets, translated paths, prices and stock. Only includes discoverable component data. **Eventually consistent**: a publish is asynchronous, and new shapes and components need an ignite. +- **Catalogue API** = full content retrieval, including non-discoverable components. It is a fallback, not a peer: on several tenants it returned `variants: []` for products that Discovery served. -- **Discovery API** — when you need fast search/filter/faceting and can tolerate eventual consistency (typically seconds to minutes). Works for listing pages AND product detail pages if real-time accuracy isn't critical. -- **Catalogue API** — when you need complete data or real-time accuracy. Essential for: admin interfaces, real-time inventory checks, editorial previews, integrations requiring guaranteed up-to-date data. +**When to use each:** model for Discovery. A storefront reads every catalogue page from Discovery, previews drafts with Discovery's `publicationState: draft`, and builds hreflang from Discovery. Catalogue is left for per-customer price display. Integrations and back-office tools that need non-discoverable data read the Core API. See [[storefront]] for the API contract and [[query]] for indexing behaviour. **Important**: Adding or removing discoverable components, and changing `searchable`, `filterable`, `sortable` or `facetable`, requires **re-igniting** the Discovery API (`igniteDiscoApi`) for the schema changes to take effect. Plan discoverability at shape design time to minimize re-ignitions. @@ -845,7 +856,7 @@ Numeric has no min or max value: range checks belong in your application. `decim | Component | Available validations | | ------------- | --------------------------------------------------------------------------------------------- | | **Selection** | Min/max selections, required/optional | -| **Switch** | No validations (always boolean true/false) | +| **Switch** | No validations. Unset reads `false` in Discovery | | **Datetime** | Required/optional | | **Location** | Required/optional | | **Colors** | Min/max number of entries, require label, restrict available colour spaces, required/optional | @@ -947,12 +958,12 @@ A **Piece** is a named collection of components that can be embedded into any sh ### Common Piece patterns -| Piece name | Components inside | Used in | -| ------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------ | -| SEO Metadata | meta-title (Single Line), meta-description (Rich Text), og-image (Images) | All product, document, folder shapes | -| CTA Block | headline (Single Line), body (Rich Text), button-label (Single Line), button-url (Single Line) | Landing pages, category folders | -| Environmental Data | carbon-footprint (Numeric, kg CO₂), recyclable (Switch), certifications (Item Relation) | Product shapes | -| Social Links | website (Single Line), instagram (Single Line), twitter (Single Line) | Author/brand document shapes | +| Piece name | Components inside | Used in | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| SEO | title (Single Line), description (Single Line), image (Images); see [Pieces Reference](pieces.md#standard-seo-piece) | All product, document, folder shapes | +| CTA Block | headline (Single Line), body (Rich Text), button-label (Single Line), button-url (Single Line) | Landing pages, category folders | +| Environmental Data | carbon-footprint (Numeric, kg CO₂), recyclable (Switch), certifications (Item Relation) | Product shapes | +| Social Links | website (Single Line), instagram (Single Line), twitter (Single Line) | Author/brand document shapes | ## Page Builder Pattern diff --git a/use-crystallize/skills/content-model/references/content-modelling.md b/use-crystallize/skills/content-model/references/content-modelling.md index 823d407..0513926 100644 --- a/use-crystallize/skills/content-model/references/content-modelling.md +++ b/use-crystallize/skills/content-model/references/content-modelling.md @@ -98,6 +98,7 @@ Grids → Homepage features, campaigns, seasonal collections - Product: Clothing Item - Variants: Size (XS-XXL), Color - Components: Material composition, care instructions, fit guide + - Variant components: body-size range as `fits-from` / `fits-to` numerics, so a range filter finds every size that fits - Relations: Brand (document), Collection (document), Materials (documents) **Topic Maps:** @@ -139,7 +140,8 @@ Grids → Homepage features, campaigns, seasonal collections - Product: Electronic Device - Variants: Configuration (storage, RAM, color) - - Components: Technical specs (table), connectivity, dimensions + - Components: Technical specs (typed numerics, selections and switches behind a `specs` choice, see [Typed Specs](typed-specs.md)), connectivity, dimensions + - Variant components: `gtin` (Single Line, not translatable), next to the built-in `sku` - Relations: Compatible Accessories (products), Brand (document) **Topic Maps:** @@ -321,6 +323,19 @@ Topic Maps: - Tags (flat) ``` +**Long-form Documents (handbooks, manuals, guides)** + +``` +Folder Shape: Handbook (its children are Chapter documents, in tree order) + ├── Intro (Rich Text) + └── SEO (Piece) + +Document Shape: Chapter + └── Blocks (Multiple Choice) → text, table, image, callout pieces +``` + +Each chapter is a child document, and tree order is chapter order: `browse.(filters: { parentPaths: { equals } }, sorting: { position: asc })` returns them in order, with no relation to maintain. One query then renders the web page, a Markdown twin and a PDF. + **Landing Pages with Sections** ``` @@ -429,7 +444,7 @@ Document Shape: Blog Post ├── Hero Image (Images) ├── Content (Paragraph Collection) ├── Author (Item Relations → author document, acceptedShapeIdentifiers: ["author"]) - ├── SEO (Piece → seo-metadata) + ├── SEO (Piece → seo) └── topics → Category topic map, Tags topic map ``` diff --git a/use-crystallize/skills/content-model/references/mass-operation-example.md b/use-crystallize/skills/content-model/references/mass-operation-example.md index 5ff7427..e2b63d6 100644 --- a/use-crystallize/skills/content-model/references/mass-operation-example.md +++ b/use-crystallize/skills/content-model/references/mass-operation-example.md @@ -38,8 +38,9 @@ A complete operations file following the 4-phase ordering described in [SKILL.md "identifier": "seo", "name": "SEO", "components": [ - { "id": "title", "name": "SEO Title", "type": "singleLine" }, - { "id": "description", "name": "SEO Description", "type": "singleLine" } + { "id": "title", "name": "Title", "type": "singleLine" }, + { "id": "description", "name": "Description", "type": "singleLine" }, + { "id": "image", "name": "Image", "type": "images" } ] }, { diff --git a/use-crystallize/skills/content-model/references/page-builder-pattern.md b/use-crystallize/skills/content-model/references/page-builder-pattern.md index e292359..0895321 100644 --- a/use-crystallize/skills/content-model/references/page-builder-pattern.md +++ b/use-crystallize/skills/content-model/references/page-builder-pattern.md @@ -338,11 +338,11 @@ Use `contentChunk` for inline-repeated groups. Use `itemRelations` when those it Beyond `layout`, other pieces serve as shared field groups embedded across shapes: -| Piece | Used by | Purpose | -| ---------------- | ---------------------------------------------- | ------------------------------------- | -| `call-to-action` | `banner` | Repeatable `{label, url}` CTA buttons | -| `meta` | `landing-page`, `category`, `product`, `story` | SEO title, description, image | -| `dimensions` | `product`, product variant | Physical measurements (W/H/D/weight) | +| Piece | Used by | Purpose | +| ---------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- | +| `call-to-action` | `banner` | Repeatable `{label, url}` CTA buttons | +| `seo` | `landing-page`, `category`, `product`, `story` | SEO title, description, image ([Pieces Reference](pieces.md#standard-seo-piece)) | +| `dimensions` | `product`, product variant | Physical measurements (W/H/D/weight) | --- @@ -390,6 +390,8 @@ category (folder shape) ← same blocks component as landing-page **Use `componentChoice` for media fields** (`background-media`, story `media`). It enforces the "image OR video" constraint at the data model level rather than relying on frontend logic. +**Offer an embed next to the upload for video.** A `videos` component holds uploaded files only. When the brand's videos live on YouTube or Vimeo, add a `youtube` (or `video-url`) Single Line as another choice, so editors don't re-upload hosted video. + **Use `contentChunk` with `repeatable: true` for inline lists** (USP items, CTA buttons, detail tabs). Use `itemRelations` when the items are independently managed content (products, stories, categories). ### Frontend Rendering @@ -427,7 +429,7 @@ selectedComponents.map((block) => { ### Schema Governance -**Centralise shared pieces** (`layout`, `meta`, `call-to-action`). If you need to add a new theme option (e.g. `"brand"`), you change it in one place and it propagates to all blocks automatically. +**Centralise shared pieces** (`layout`, `seo`, `call-to-action`). If you need to add a new theme option (e.g. `"brand"`), you change it in one place and it propagates to all blocks automatically. **Add blocks by extending `componentMultipleChoice` choices** — not by creating parallel block fields. A single `blocks` field keeps rendering logic, ordering, and multilingual handling unified. diff --git a/use-crystallize/skills/content-model/references/pieces.md b/use-crystallize/skills/content-model/references/pieces.md index 305ee8c..20df9e5 100644 --- a/use-crystallize/skills/content-model/references/pieces.md +++ b/use-crystallize/skills/content-model/references/pieces.md @@ -26,16 +26,31 @@ Use pieces for content that: ### Standard SEO Piece -A reusable piece for SEO metadata, commonly added to products, folders (landing pages), and documents (articles): +One SEO piece for the whole model, referenced from every product, folder and document shape that has a page: ```json { "identifier": "seo", "name": "SEO", "components": [ - { "id": "title", "name": "Title", "type": "singleLine" }, - { "id": "description", "name": "Description", "type": "richText" }, - { "id": "image", "name": "Image", "type": "images" } + { + "id": "title", + "name": "Title", + "type": "singleLine", + "config": { "singleLine": { "multilingual": true, "discoverable": true, "max": 70 } } + }, + { + "id": "description", + "name": "Description", + "type": "singleLine", + "config": { "singleLine": { "multilingual": true, "discoverable": true, "max": 160 } } + }, + { + "id": "image", + "name": "Image", + "type": "images", + "config": { "images": { "discoverable": true, "max": 1 } } + } ] } ``` @@ -51,19 +66,19 @@ Usage in a shape: } ``` -### SEO Metadata - -Standard SEO fields for all content: - -``` -SEO Metadata (Piece) -├── Meta Title (Single Line) -├── Meta Description (Rich Text, max 160 chars) -├── OG Image (Images, single) -├── OG Title (Single Line) -├── Canonical URL (Single Line) -└── No Index (Boolean) -``` +- **Plain text, not rich text.** The description goes into ``, Open Graph and JSON-LD, which + take plain text. A Single Line keeps editors from adding formatting that would be stripped or leak as markup. +- **No canonical URL field.** Canonicals and hreflang come from the item's generated paths (see + [[information-architecture]]). A typed canonical goes stale on the first rename, and nothing warns. +- **No separate OG title or OG image.** `title` and `image` serve both. Add a field only when editors really need a + different value for social sharing. +- **Discoverable, explicitly.** A storefront that reads only Discovery loses every field that isn't indexed, so set + `discoverable: true` on each component rather than relying on the default. +- **Always have a fallback.** Most items will leave the piece empty. Fall back in a fixed order, for example: the SEO + title, then the item name; the SEO description, then the item's lead text (a tagline or intro), then a sentence + built from typed specs; the SEO image, then the first product image. See [[seo-geo]]. +- **Indexing rules are the storefront's job.** A `noindex` switch is only worth adding when editors decide it per + item; search results and filtered views get `noindex` or a canonical from the storefront's own rules. ### Environmental Impact diff --git a/use-crystallize/skills/content-model/references/typed-specs.md b/use-crystallize/skills/content-model/references/typed-specs.md new file mode 100644 index 0000000..6ae13ff --- /dev/null +++ b/use-crystallize/skills/content-model/references/typed-specs.md @@ -0,0 +1,185 @@ +# Typed Specs, Units and Identifiers + +How to model technical specifications and product identifiers so that Discovery can filter and rank on them, and a +storefront can publish them as structured data without a second source of truth. + +## Why Typed Specs + +Every build that replaced label/value tables with typed components gained the same things from one model: + +- **Filters and facets.** A numeric becomes a range filter, a selection a set of option filters, a switch a boolean + filter. A properties table is one opaque value, so it gives none of them. +- **Ranking signals.** Numerics inside pieces inside a component choice are indexed and offered as `rankBy` fields + (`specs_abrasive_discDiameter_number`, `power_voltage_number`). See [[vector-ranking]]. +- **Structured data.** Each typed value becomes a schema.org `PropertyValue` in `additionalProperty`, with its unit + as a `unitCode`. See [[seo-geo]]. +- **Markdown twins and agent filters.** The same typed rows give the Markdown version of the page, and give an AI + agent a filter it can use ("18 V, under 2 kg"). See [[agentic-commerce]]. + +A properties table still has a place for keys that are truly unknown in advance. A real table in body text (a sizing +chart, a handbook table) is better as a rich-text table, which Discovery returns as semantic table nodes (see +[[content-json]]). + +## The Shape of a Spec Model + +Put the attributes every product has in shared pieces, and the attributes of one product family behind a single +`componentChoice`, one piece per family: + +``` +Product Shape: Tool + ├── power (Piece → power) shared by every family + │ ├── voltage (Numeric, V) + │ └── battery-capacity (Numeric, Ah) + ├── physical (Piece → physical) shared by every family + │ ├── weight (Numeric, kg) + │ └── length (Numeric, mm) + └── specs (componentChoice) exactly one family per product + ├── drilling (Piece → spec-drilling) + │ ├── max-drilling-diameter-steel (Numeric, mm) + │ ├── chuck (Selection) + │ └── hammer-function (Switch) + └── abrasive (Piece → spec-abrasive) + ├── disc-diameter (Numeric, mm) + └── no-load-speed (Numeric, 1/min) +``` + +- **Discovery has no "has this choice" filter.** To find every product of one family, combine `exists: true` over + the family's fields. Give each family at least one field every product in it fills. +- **Specs that differ per variant go in `variantComponents`**, which accept pieces and choices too (a `spec` choice + of the same family pieces, plus `physical`). Pieces used on variants are safest without content chunks: see the + chunk note in [Components Reference](components.md). +- Create the pieces and shapes in the 4-phase order in SKILL.md, because the shapes reference the pieces. + +## Numerics and Units + +### One unit per numeric + +Range filters compare the raw number and ignore the unit. A component with `["m³/h", "l/s"]` stores each item's +value in whichever unit the editor picked, and `airflow_number: { range: { gte: 100 } }` then mixes cubic metres per +hour with litres per second. Pick one unit per component and convert at import. If several units are unavoidable, +filter on a superset and check `Unit` on each hit. + +Discovery serves a numeric as two fields, the number and its unit, and filters on `_number`: + +```graphql +search(language: en, filters: { power_voltage_number: { range: { gte: 18 } } }) { + hits { ... on tool { power { voltage voltageUnit } } } +} +# → "power": { "voltage": 18, "voltageUnit": "V" } +``` + +### Units that map to schema.org + +A numeric with a unit is a schema.org `QuantitativeValue` (or a `PropertyValue` in `additionalProperty`) with +`value`, `unitText` (the unit as written) and `unitCode`, the UN/CEFACT Recommendation 20 code. The unit list has no +slot for the code, so the storefront maps it. Choose unit strings that map one-to-one: + +| Unit | Rec 20 | Unit | Rec 20 | Unit | Rec 20 | Unit | Rec 20 | +| ---- | ------ | ----- | ------ | ------- | ------ | ------- | ------ | +| `mm` | `MMT` | `V` | `VLT` | `Nm` | `NU` | `m/s²` | `MSK` | +| `cm` | `CMT` | `A` | `AMP` | `J` | `JOU` | `m³/h` | `MQH` | +| `m` | `MTR` | `Ah` | `AMH` | `kN` | `B47` | `dB(A)` | `2N` | +| `g` | `GRM` | `W` | `WTT` | `kPa` | `KPA` | `°` | `DD` | +| `kg` | `KGM` | `Wh` | `WHR` | `mbar` | `MBR` | `%` | `P1` | +| `l` | `LTR` | `lm` | `LUM` | `m/s` | `MTS` | `h` | `HUR` | +| `s` | `SEC` | `min` | `MIN` | `years` | `ANN` | | | + +- **`1/min` is two units.** It is `RPM` on a rotational speed and `C94` (reciprocal minute) on an impact or stroke + rate. Decide by field. +- **Leave a unit without an unambiguous code uncoded** (`l/s`, `m³/min`) rather than guessing. +- **Name bounds consistently.** A field id that starts or ends with `max` or `min` (`max-drilling-diameter`) maps to + `maxValue` or `minValue` instead of `value`. +- **Ranges are two numerics.** A body-size range ("62-68") is `fits-from` and `fits-to` numerics on the variant, so a + range filter finds every size that fits. A label like "62-68" means "up to 68", so `fits-from` starts just above + the previous size's upper bound. + +### decimalPlaces + +`decimalPlaces: 0` floors the value (13.5 l is stored as 13), and on one tenant it was rejected outright. Leave it +out for integers, and give anything measured in fractions (litres, kilograms) at least 1. + +### A unit list makes empty values fail + +Nine builds hit this, and it is the most common write failure in the findings. A numeric with a `units` list needs a +unit in its content, and a value cannot carry a unit without a number. So an item that has no value for it fails: + +- `createProduct`, `createDocument` and mass-operation creates, even when the operation doesn't send the component; +- `updateProduct` and upsert-updates of any product or variant without a value, even when its components are left + out or sent empty, and even when the create of the same item worked; +- publishing: an empty piece of unit-bound numerics blocks `publishItem` (`allowedUnits`), and the mass-operation + `item/publish` has no way around it. + +What worked, in order of preference: + +1. **Set `required: false` on a numeric that is genuinely optional** (see [Components Reference](components.md)). +2. **Drop the `units` list** on optional numerics. The unit is still stored with each value, so the storefront still + reads `Unit`. You lose the editor's unit picker. +3. **Write numerics with `updateComponent`, one component at a time**, after a minimal create. +4. **Publish with `publishItem(disableComponentValidation: true)`** on the Core API. It also hides real shape-limit + violations, so use it for the publish only. + +The write side is in [[mutation]] and [[mass-operations]]. + +## Booleans + +An unset Switch reads `false` in Discovery, not `null`. A storefront can't tell "no" from "not stated", and a +published `false` is a wrong fact in JSON-LD, a feed or an agent's filter. + +- Write `true` for the features an item has, and leave the rest unset. Never write `false` for "unknown". +- Treat `false` from Discovery as "not stated" when publishing facts. Show boolean specs only when `true`. +- When "no" must be stated (a product that is explicitly not waterproof), use a Selection with `yes` and `no`. + +## Selections and External Codes + +Every Selection option becomes a filter field of its own in Discovery (`specs_extraction_dustClass_m`, filtered with +`exists: true`). The naming is in [[query]]. + +An option carries only `key`, `value` and `label`, so it has no slot for an external code (an ETIM value `EV…`, a GS1 +code). Keep it in one of these places, and say which in the component `description`: + +- an option key convention (`ev000123-sds-plus`), +- a labels file generated from the model, shipped with the storefront, +- for codes on a classification, a topic's `meta` (see [[taxonomy]]). + +## Component Description + +Component definitions take a `description`, which the App shows as editor help. Use it for the standard the field +maps to (`ETIM EF000002 Nominal voltage`) and for field ownership (`Owner: ERP`, `Owner: PLM`). The model has no +first-class owner or source-system field. + +## Identifiers + +schema.org, Google Merchant Center and GS1 treat the merchant's SKU, the GTIN and the manufacturer's part number as +**separate facts**. A SKU used as the GTIN loses the merchant's own SKU, and a kit and the bare tool have different +GTINs. Model them apart: + +| Identifier | Where | schema.org | +| ---------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------- | +| Merchant SKU | the built-in variant `sku` | `sku` | +| GTIN (EAN, UPC) | `gtin` Single Line in `variantComponents`, not translatable | `gtin8`, `gtin12`, `gtin13`, `gtin14` | +| Manufacturer part number | `mpn` Single Line, on the variant when it differs per variant | `mpn` | +| National trade numbers (NOBB, NRF, ISBN) | Single Lines (grouped in an `identifiers` chunk on the product only) | `identifier` as a `PropertyValue` | +| One external system id | the built-in `externalReference` on the item or variant | none; keep it `discoverable: false` if private | + +```json +{ + "id": "gtin", + "name": "GTIN", + "type": "singleLine", + "description": "GS1 GTIN-8, -12, -13 or -14", + "config": { "singleLine": { "multilingual": false, "discoverable": true, "pattern": "^(\\d{8}|\\d{12,14})$" } } +} +``` + +- **Each identifier gets its own named component**, never a generic key/value list, so it stays typed and filterable. +- **Don't fill a gap with a guess.** An empty GTIN is "not registered", and the storefront says so or leaves it out. +- **A single line on a variant publishes and is served by Discovery** (`variants { sku gtin }`). + +## Checklist + +1. Measurable values are Numerics with one unit each, and the unit strings map to Rec 20. +2. Optional numerics with a unit list have `required: false`, or no unit list. +3. Booleans state only what is true. +4. Every field the storefront renders or filters on is `discoverable` (see [Components Reference](components.md)). +5. `sku`, `gtin` and `mpn` are separate fields. +6. Each family behind the `specs` choice has a field that every product in it fills. diff --git a/use-crystallize/skills/data-creation/SKILL.md b/use-crystallize/skills/data-creation/SKILL.md index 571511c..ebe4e88 100644 --- a/use-crystallize/skills/data-creation/SKILL.md +++ b/use-crystallize/skills/data-creation/SKILL.md @@ -10,7 +10,7 @@ description: > bulk imports and seeding. metadata: author: Crystallize - version: "1.0" + version: "1.1" --- # Crystallize Data Creation Skill @@ -148,7 +148,7 @@ When generating data, match component types exactly: | `datetime` | ISO 8601 date string. | | `images` | Array of image URLs/keys, or a single URL string for the value. | | `itemRelations` | Catalogue path (e.g., `/brands/nike`) — MUST be a path string starting with `/`, NOT a plain name. Convert names to paths: `Fender` → `/brands/fender`, `Nike` → `/brands/nike`. Check the "Available Catalogue Paths" section for valid paths. Paths that exist show GREEN; invalid paths show RED. | -| `selection` | MUST be an EXACT key from the options shown in `[options: ...]`. Do NOT invent values. E.g., if options are `["solid", "semi-hollow", "hollow", "acoustic"]`, use `"solid"` NOT `"solid-body"`. If options are `["6", "7", "8", "12"]`, use `"6"` NOT `"6-string"`. If no option fits, pick the closest match. | +| `selection` | MUST be an EXACT key from the options shown in `[options: ...]`. Do NOT invent values. E.g., if options are `["solid", "semi-hollow", "hollow", "acoustic"]`, use `"solid"` NOT `"solid-body"`. If options are `["6", "7", "8", "12"]`, use `"6"` NOT `"6-string"`. If no option fits, stop and ask the user. | | `contentChunk` | Use **dot notation** for sub-components (see below). | | `piece` | Use **dot notation** for sub-components (see below). | | `propertiesTable`, `paragraphCollection`, `componentChoice`, `componentMultipleChoice`, `colors` | **Skip** — do NOT generate values for these complex types. `colors` entries are structured colour objects, not strings; author them through the API instead. | @@ -165,18 +165,25 @@ A component with `required: true` must have a value, on create and again on publ For `contentChunk` and `piece` components that have sub-components listed in the shape definition, use **dot notation** to set each sub-component individually: ```json -// Shape: specifications (contentChunk) → sub-components: weight(numeric), material(singleLine), dimensions(singleLine) +// Shape: specifications (contentChunk) → sub-components: weight(numeric [units: kg]), material(singleLine), +// length, width, height (numeric [units: cm]) { "components": { - "specifications.weight": 3.4, + "specifications.weight": { "value": 3.4, "unit": "kg" }, "specifications.material": "Mahogany", - "specifications.dimensions": "40 x 15 x 5 inches" + "specifications.length": { "value": 102, "unit": "cm" }, + "specifications.width": { "value": 38, "unit": "cm" }, + "specifications.height": { "value": 13, "unit": "cm" } } } ``` Format: `"parentId.subComponentId": value`. Each sub-component gets its own column in the grid. +Measurements are one `numeric` per dimension, never a `"40 x 15 x 5 inches"` string: a string can't be +filtered, ranked or turned into structured data (see [[content-model]]). If the shape only has a text field for +dimensions, tell the user rather than packing numbers into it. + **SKIP truly complex types**: `propertiesTable`, `paragraphCollection`, `componentChoice`, `componentMultipleChoice`, `colors` — do NOT generate values for these. ## Product Image Handling (CRITICAL for spreadsheet imports) @@ -235,7 +242,7 @@ Before emitting a `json:itemData` block, verify: | Mistake | Fix | | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Putting `sku`/`price`/`stock` **inside** `components`. | They live at the **item level**, alongside `name` and `location`. | -| Inventing a `selection` key like `"solid-body"` when options list shows `"solid"`. | Use the exact configured key. If none fits, pick the closest existing one. | +| Inventing a `selection` key like `"solid-body"` when options list shows `"solid"`. | Use the exact configured key. If none fits, stop and ask: a near match states a wrong fact. | | Inventing a `numeric` unit like `"inches"` when units list shows `"in"`. | Use the exact configured unit string. | | Setting `itemRelations` to a plain name (`"Nike"`). | Always a path: `"/brands/nike"`. | | Leaving `location` as `/` when the spreadsheet has Category/Subcategory columns. | Combine the columns into a deep path like `/products/instruments/electric-guitars`. | @@ -274,3 +281,9 @@ The API input differs from `json:itemData` at almost every field: | Dot notation | `piece: { identifier, components: [...] }`, `contentChunk: { chunks: [[...]] }` | Created items stay unpublished until you publish them, and parent folders must exist first (`folder/upsert`, see [[information-architecture]]). + +**An item exists per language: create the language version before translating its components.** Write the +name in the new language first (`updateProduct(id, language: "fi", input: { name })`, or an upsert in that +language), then the components. `updateComponent(language: "fi")` on an item with no Finnish version fails +with a bare `TypeError … reading 'shortcuts'`, and running the two writes concurrently makes it a race. See +[[mutation]] for partial and translated writes. diff --git a/use-crystallize/skills/information-architecture/SKILL.md b/use-crystallize/skills/information-architecture/SKILL.md index cd2594e..d111439 100644 --- a/use-crystallize/skills/information-architecture/SKILL.md +++ b/use-crystallize/skills/information-architecture/SKILL.md @@ -1,9 +1,9 @@ --- name: information-architecture -description: Design folder hierarchies and navigation structures in Crystallize. Create category trees, organize products and content, plan URL structures, and build scalable information architectures. Use when designing storefront navigation, category pages, collection structures, content organization, mega menus, breadcrumbs, or site maps. Also use when the user mentions organizing their catalog, planning their store structure, restructuring navigation, placing an item in several folders with shortcuts, moving or renaming folders without breaking URLs, or asks how to organize products or content in Crystallize — even if they don't explicitly say "information architecture." +description: Design folder hierarchies and navigation structures in Crystallize. Create category trees, organize products and content, plan URL structures, and build scalable information architectures. Use when designing storefront navigation, category pages, collection structures, content organization, mega menus, breadcrumbs, or site maps. Also use when the user mentions organizing their catalog, planning their store structure, restructuring navigation, placing an item in several folders with shortcuts, moving or renaming folders without breaking URLs, translated paths per language, hreflang alternates, redirects from old paths, canonical URLs, slug collisions, or asks how to organize products or content in Crystallize — even if they don't explicitly say "information architecture." metadata: author: Crystallize - version: "1.1" + version: "1.2" --- # Crystallize Information Architecture Skill @@ -61,14 +61,66 @@ This skill focuses on hierarchical organization. For topic maps and taxonomic cl Crystallize generates every canonical path. No folder input takes a path or a slug, so these rules decide the URLs you get: -- **A path is the parent's path plus the slugified `name`.** `Men's Shoes` under `/shop` becomes `/shop/mens-shoes`: lower case, hyphens for spaces, and whatever cannot be reduced to ASCII letters, digits or hyphens is dropped. -- **Paths are per language.** Each language builds its own path from its own name and the parent's path in that language, so `/shop/men` can be `/boutique/hommes` in French. Create and translate parents first: a child whose parent has no path in that language gets a placeholder path (`/placeholder/missing-parent-translation/...`). `paths { hreflangs { language path } }` on the Catalogue API lists the published path of each language. -- **A collision never fails.** If another item already uses the path as a canonical path, alias or shortcut in that language, the new item silently gets a random suffix (`/shop/men-x7k2q`), so two same-named siblings both succeed. A path in another item's `history` counts as free, and publishing it removes it from that history. -- **Renaming or moving changes the path of the whole subtree.** A new `name` regenerates the path in that language. A new parent regenerates it in every language. +- **A path is the parent's path plus the slugified `name`.** `Men's Shoes` under `/shop` becomes `/shop/mens-shoes`: lower case, hyphens for spaces, and whatever cannot be reduced to ASCII letters, digits or hyphens is dropped. In practice: `æ` → `ae`, `ø` → `o`, `å` → `a`, other diacritics stripped, `&` → `and` (`Batteries & chargers` → `/batteries-and-chargers`), and dots and slashes dropped (`6.0 Ah` → `60-ah`, `5233/6234` → `52336234`). Source slugs do not survive an import either (`komplette-sett-2` → `komplette-sett`, `1-2` → `12`). +- **Join on `itemId` or `externalReference`, never on a path.** Paths are re-slugged, suffixed on collision and regenerated on rename, so a slug from the old platform or a path from another language is not a key. Keep the source system's id in `externalReference` (or the mass operation's `resourceIdentifier`) and look items up by that. +- **Paths are per language.** Each language builds its own path from its own name and the parent's path in that language, so `/shop/men` can be `/boutique/hommes` in French, and localised URLs need nothing more than translated names. The depth can differ too: an untranslated or renamed level changes the trail, so never derive one language's path from another's. Get every language's path by `itemId` instead (see [Paths per language, hreflang and redirects](#paths-per-language-hreflang-and-redirects)). +- **Translate parents first.** A child named in a language before its parent gets a placeholder path (`/missing-path-for-language//`), and it stays there after the parent is translated. Repair it by moving the item to a sibling folder and back with `moveItemTreeNode`, then publishing: moving it to the parent it already has is a no-op. Publishing a language in which an item has no content puts an empty document in that language's Discovery index (`name: "MISSING_NAME_FOR_LANGUAGE"`, `path: "/missing-path-for-language//"`), so a storefront that falls back to another language tests for content (`: { exists: true }`), not for hits. +- **A collision never fails.** If another item already uses the path as a canonical path, alias or shortcut in that language, the new item silently gets a random suffix (`/shop/men-x7k2q`), so two same-named siblings both succeed, and so does a rerun of a failed import that creates the same items again. A path in another item's `history` counts as free, and publishing it removes it from that history. +- **Paths are unique within a folder, not across the tree.** The same product name under `/women/` and `/men/` gives the same last segment twice (one store had 37 shared slugs in 787 products). Route on the full path, and never resolve a URL by its last segment with `limit: 1`; if the URL scheme drops the folders, add a disambiguator such as the style number. +- **Renaming or moving changes the path of the whole subtree.** A new `name` regenerates the path in that language, on folders, products and documents alike: an `updateProduct` or `updateDocument` that only sets `name` is a URL change too. A new parent regenerates it in every language. To keep a legacy URL, pick a name that slugifies to it and keep the display title in a component, or add an alias. - **Moves, renames and reorders are drafts until the item is published.** The published item keeps its old path and position until then. Publishing a moved or renamed folder is enough for what is under it: its published descendants follow in that language without being republished. - **Old paths are kept.** Publishing a changed path adds the previous one to `paths.history`, on the item and on each published descendant, up to the last 100 per language. - **An alias is the way to choose a path.** `item/paths/addAliases`, or `addItemTreeNodeAliases(input: { itemId, language, paths })` on the Core API, adds an extra path for one language. Unlike a generated path, a taken alias fails. It needs a publish too. +### Paths per language, hreflang and redirects + +A storefront reads paths from the Discovery API, like the rest of the catalogue (see [[storefront]] for the API contract, and [[seo-geo]] for sitemaps and the `` they go in). Discovery holds one document per item and language, keyed by `itemId`, so every cross-language and old-URL question is answered by `itemId`. + +**The item's path in every language: one aliased query.** Discovery has no `hreflangs` field. Ask for the item in each language in one request: + +```graphql +query PathsForItem($id: String!) { + en: search(language: en, filters: { itemId: { equals: $id } }) { + hits { + path + } + } + no: search(language: no, filters: { itemId: { equals: $id } }) { + hits { + path + } + } + # … one alias per tenant language +} +``` + +A language with no hit has no published version: leave it out of the alternates. Filter on `itemId`, not `id` (`id` is the document id, `--published`). For a sitemap, read one listing per language and join the rows on `itemId`; `updatedAt` on each hit is the `lastModified`. + +**hreflang values are BCP 47 tags, not tenant language codes.** Map them once: a tenant's `no` holds Norwegian Bokmål, which is `nb` (`no` is the macrolanguage). Emit `` for every language the item has, itself included, plus `hreflang="x-default"` pointing at the default language's URL. Put the language in the URL path (`/nb/…`), not a cookie, so crawlers see every language. + +**Folders that are separate items per language.** When each language has its own folder items instead of one translated folder, `itemId` doesn't join them. Use a language-independent key: the folder's topic path (the longest `/category/…` in `topicPaths`), or a shared `externalReference`. + +**Redirect old URLs from `history`.** Publishing a rename or move keeps the old path in the item's `history`. When a request path doesn't resolve, look it up as a history path, then send a 301 to the item's current path in that language: + +```graphql +query OldPath($path: String!) { + search(language: en, path: $path, pathResolutionMethod: [history]) { + hits { + itemId + pathResolutionMethod + } + } +} +``` + +Read the current path by `itemId` with the query above. Keep history paths out of the sitemap and out of hreflang, which list canonical paths only. `item/paths/addHistory` seeds old paths from a previous platform, and needs a publish. + +**Canonicals.** Every page declares one ``, built from the item's generated path, never from a URL typed into a component (it goes stale on the first rename; [[content-model]] has no canonical field for this reason). + +- **A shortcut path is a duplicate URL.** It serves the same item, so its canonical points at the item's canonical path, unless the market page is meant to rank on its own and carries market-specific content. +- **Filtered and sorted category views** (`?brand=…&sort=…`) point at the clean category path. +- **An alias** is a deliberate URL: decide whether it or the generated path is canonical, and redirect the other. + ## Best Practices ### 1. User-Centric Design @@ -101,6 +153,8 @@ Paths become URLs, so: - Use descriptive, keyword-rich names - Keep paths readable and logical - Avoid IDs or codes in paths +- Name each folder in its own language: the name is the slug, per language +- Plan the redirects and canonicals that renames and shortcuts need (see [Paths per language, hreflang and redirects](#paths-per-language-hreflang-and-redirects)) ### 5. Plan for Growth @@ -113,15 +167,17 @@ Ask: "Where will new products/categories go?" ``` / ├── shop/ -│ ├── category-1/ -│ ├── category-2/ -│ └── category-3/ +│ ├── clothing/ +│ ├── shoes/ +│ └── accessories/ ├── brands/ -├── sale/ -├── new-arrivals/ +├── sale/ # landing page listing the "sale" topic; holds no products +├── new-arrivals/ # landing page listing the "new" topic; holds no products └── about/ ``` +`sale/` and `new-arrivals/` are pages, not homes for products: each product stays in its one category folder and carries a topic, and the landing page lists that topic (see [Anti-Patterns](#anti-patterns)). + ### Fashion Store ``` @@ -140,7 +196,7 @@ Ask: "Where will new products/categories go?" ├── collections/ │ ├── summer-2024/ │ └── basics/ -└── sale/ +└── sale/ # topic-driven landing page ``` ### Electronics Store @@ -191,8 +247,7 @@ When customers need to browse by multiple dimensions (category AND brand): │ │ ├── adidas/ │ │ └── puma/ │ └── collections/ -│ ├── summer-2024/ -│ └── sale/ +│ └── summer-2024/ ├── brands/ # Brand landing pages └── about/ ``` @@ -265,8 +320,8 @@ Create them with `item/paths/addShortcuts` in a mass operation, where `position` ``` / ├── shop/ # B2C storefront -│ ├── category-1/ -│ └── category-2/ +│ ├── power-tools/ +│ └── hand-tools/ ├── wholesale/ # B2B section │ ├── price-lists/ │ └── bulk-orders/ @@ -356,7 +411,7 @@ Second-level → Dropdown/mega menu Third-level → Sub-navigation or sidebar ``` -Top-level folders are the children of the root item, so read the menu from `catalogue(path: "/")` with `subtree(type: folder)`, which keeps products and documents out. `createNavigationFetcher(client).byFolders('/', 'en', 3)` builds the nested query for you, but it reads every published child at each level: add `type` through its `perLevel` argument and filter out what is not a folder. +Top-level folders are the children of the root item. On the Discovery API, `search(language, filters: { type_in: [folder], depth: { range: { lte: 2 } } }, sorting: { position: asc })` returns the folders of the first two levels, with `path`, `depth` and `position`; group them by `parentId`. A wildcard path is not a "direct children" filter: `path: "/shop/*"` matches every depth below `/shop`. For one folder's children use `parentId: { equals }`, or `parentPaths: { equals }` for everything below it. `position` orders siblings within one folder only, so sort per parent rather than across depths. ### Breadcrumbs @@ -366,7 +421,7 @@ The folder path gives the shape of the trail, but it holds slugs, not display na /shop/men/shoes → Home > Shop > Men > Shoes ``` -Take the labels from the API. Discovery `breadcrumbs` answers one trail per location of the item, from the top-level folder down to the item, and each crumb carries `id`, `name`, `path`, `shape` and `isShortcut`. `breadcrumbs(withShortcuts: false)` keeps the canonical trail only. On the Catalogue API, walk `parent`. +Take the labels from the API. Discovery `breadcrumbs` answers one trail per location of the item, from the top-level folder down to the item itself (the last crumb is the page you are on), and each crumb carries `id`, `name`, `path`, `shape` and `isShortcut`. `breadcrumbs(withShortcuts: false)` keeps the canonical trail only. ### URL Routing @@ -377,7 +432,7 @@ Crystallize path: /shop/men/shoes Frontend URL: https://store.com/shop/men/shoes ``` -`catalogue(path:)` resolves canonical paths only by default, so a storefront that also serves shortcut, alias or old URLs passes `pathResolutionMethods` (`canonical`, `shortcut`, `alias`, `history` or `any`). The answer's `path` echoes the path you asked for, `pathResolutionMethod` says how it matched, and `paths { canonical }` is the real location. +Resolve the request path with Discovery `search(language, path: $path)`. It matches canonical, alias, shortcut and history paths by default, and each hit says how it matched in `pathResolutionMethod`. Pass `pathResolutionMethod: [canonical, shortcut, alias]` for the page lookup and handle `history` as a redirect (see [Paths per language, hreflang and redirects](#paths-per-language-hreflang-and-redirects)). On the Catalogue API, `catalogue(path:)` resolves canonical paths only unless you pass `pathResolutionMethods`, but a storefront should not need it for this. ### Topics (Cross-cutting) @@ -396,7 +451,7 @@ When a user already has a folder structure and wants to improve it: 1. **Audit the current tree** — Ask the user to describe (or export) their current folder hierarchy. Identify pain points: too deep, inconsistent naming, duplicated products, orphaned folders. 2. **Identify what's working** — Don't propose a full rewrite if only part of the tree is problematic. Preserve paths that are already indexed by search engines or bookmarked by customers. 3. **Propose incremental changes** — Restructuring everything at once is risky. Suggest changes in phases: rename and flatten first, then reorganize, then clean up. -4. **Consider URL redirects** — Changing folder paths changes URLs. Remind the user to set up redirects from old paths to new ones in their frontend to avoid broken links and SEO penalties. Crystallize keeps the old paths, so the frontend can drive this itself: when a path does not resolve, query `catalogue(language: "en", path: "/old/path", pathResolutionMethods: [history]) { paths { canonical } }` and redirect to the result. `item/paths/addHistory` seeds old paths from a previous platform, and needs a publish like any other path change. +4. **Consider URL redirects** — Changing folder paths changes URLs. Remind the user to set up redirects from old paths to new ones in their frontend to avoid broken links and SEO penalties. Crystallize keeps the old paths, so the frontend can drive this itself from `history` (see [Paths per language, hreflang and redirects](#paths-per-language-hreflang-and-redirects)). `item/paths/addHistory` seeds old paths from a previous platform, and needs a publish like any other path change. 5. **Move existing items, do not recreate them** — `folder/upsert` only reuses a folder it can find by `resourceIdentifier` or `itemId`, so for a folder made without one it creates a duplicate. Use `folder/update` (or `product/update`, `document/update`) with `itemId` and `tree: { parentId, position }`, or `moveItemTreeNode` on the Core API, then publish the moved item in each language. A folder cannot move under one of its own descendants. 6. **Do not delete or unpublish a folder to empty it** — Deleting a folder deletes everything under it, in the background and with no prompt. Unpublishing it takes everything under it offline in that language. Move what stays first. diff --git a/use-crystallize/skills/js-api-client/SKILL.md b/use-crystallize/skills/js-api-client/SKILL.md index 86bb4e8..2cc4f97 100644 --- a/use-crystallize/skills/js-api-client/SKILL.md +++ b/use-crystallize/skills/js-api-client/SKILL.md @@ -1,9 +1,9 @@ --- name: js-api-client -description: Use the @crystallize/js-api-client package to interact with Crystallize APIs in JavaScript/TypeScript. Use when setting up the Crystallize API client, configuring credentials (including the bearer token of a plugin), calling catalogueApi/discoveryApi/pimApi/nextPimApi/meApi or the Shop API callers (shopCartApi, shopOrderApi, shopCustomerApi, shopLockApi, shopSubscriptionContractApi, shopBookingApi), configuring Shop API token scopes, working with high-level helpers for catalogue fetching, cart management, Shop API orders (createFromCart, addPayments, setPayments, pipeline stages), Shop API customers, distributed locks, Core orders, customers, subscriptions, navigation, or using any helper from the @crystallize/js-api-client npm package (createCartManager, createShopOrderManager, createShopCustomerManager, createShopLock, createOrderManager, createCustomerManager, createBinaryFileManager, createSignatureVerifier, …). +description: Use the @crystallize/js-api-client package to interact with Crystallize APIs in JavaScript/TypeScript. Use when setting up the Crystallize API client for a storefront (discoveryApi for catalogue reads, Shop API callers for carts, orders and customers, server-side only) or for back-office scripts, configuring credentials (including the bearer token of a plugin), calling catalogueApi/discoveryApi/pimApi/nextPimApi/meApi or the Shop API callers (shopCartApi, shopOrderApi, shopCustomerApi, shopLockApi, shopSubscriptionContractApi, shopBookingApi), configuring Shop API token scopes, working with high-level helpers for catalogue fetching, cart management, Shop API orders (createFromCart, addPayments, setPayments, pipeline stages), Shop API customers, distributed locks, Core orders, customers, subscriptions, navigation, or using any helper from the @crystallize/js-api-client npm package (createCartManager, createShopOrderManager, createShopCustomerManager, createShopLock, createOrderManager, createCustomerManager, createBinaryFileManager, createSignatureVerifier, …). metadata: author: Crystallize - version: "2.1" + version: "2.2" --- # Crystallize JS API Client @@ -16,12 +16,16 @@ Before writing code, understand the context. Ask clarifying questions: 1. **What are you trying to do?** Read data, write data, manage carts, handle webhooks? 2. **Do you need raw GraphQL or a high-level helper?** Helpers reduce boilerplate for common workflows (orders, carts, navigation). Use raw GraphQL via API callers for custom queries or when helpers don't cover the use case. -3. **Which API?** Catalogue/Discovery for storefront reads, Core (`nextPimApi`) for back-office reads and writes, the - Shop API for checkout: carts (`/cart`), orders made from them (`/order`), customers (`/customer`), locks (`/lock`). - Orders and customers exist on both sides — pick the helper for the side you are on (see +3. **Which API?** Follow the storefront API contract ([[storefront]]): `discoveryApi` for every catalogue read; the + Shop API callers for everything about a shopper (carts, the customer's price, orders, payments, customers, + bookings, subscription contracts, locks); `catalogueApi` only for per-customer prices and reads that must be in sync with a publish; Core (`nextPimApi`) + only for the back office (seeds, imports, jobs, admin tools), never in a storefront's request path. Orders and + customers exist on both sides, so pick the helper for the side you are on (see [Shop API](#shop-api-carts-orders-customers-locks)). 4. **What auth do you have?** `staticAuthToken` is enough for read-only. PIM/Shop operations need `accessTokenId` + `accessTokenSecret`. A plugin passes its `backendToken` JWT as `bearerToken` — it becomes `Authorization: Bearer ` and works on the Core APIs only (see [Authentication](#authentication)). -5. **Is this server-side or client-side?** The client works in both, but credentials should only live server-side. +5. **Is this server-side or client-side?** The client works in both, but credentials live server-side only. In the + browser, only `discoveryApi` against an open Discovery works: the Shop API refuses other origins, and every other + caller needs a credential. ## Installation @@ -41,25 +45,29 @@ const api = createClient({ // For protected APIs, provide credentials: // accessTokenId: '…', // accessTokenSecret: '…', - // staticAuthToken: '…', // for read-only catalogue/discovery + // staticAuthToken: '…', // a restricted Discovery or Catalogue // bearerToken: '…', // JWT sent as `Authorization: Bearer ` (plugin backendToken) }); -// Call any GraphQL API with string queries -const { catalogue } = await api.catalogueApi( - `query Q($path: String!, $language: String!) { - catalogue(path: $path, language: $language) { - name - path +// Catalogue reads go to Discovery. Leave optional variables out: Discovery rejects an explicit null. +const { search } = await api.discoveryApi<{ search: { hits: { name: string; path: string }[] } }>( + `query ItemByPath($path: String!) { + search(language: en, filters: { path: { equals: $path } }, pagination: { limit: 1 }) { + hits { name path } } }`, - { path: "/shop", language: "en" }, + { path: "/shop/plants" }, ); // Close when using HTTP/2 option api.close(); ``` +`catalogueApi` is the synchronous fallback: a specific customer's price-list prices for display, and reads that must be in +sync with a publish, since Discovery is updated asynchronously (see [[query]]). +`createCatalogueFetcher`, `createNavigationFetcher` and `createProductHydrater` are built on the Catalogue API, so +they inherit that status: a storefront reads navigation and products from Discovery instead. + ## Configuration ```typescript @@ -74,7 +82,7 @@ createClient(configuration, options?) | `tenantId` | Optional tenant ID | | `accessTokenId` / `accessTokenSecret` | For PIM/Shop operations | | `sessionId` | Alternative to token-based auth | -| `staticAuthToken` | For read-only catalogue/discovery | +| `staticAuthToken` | A restricted Discovery or Catalogue (server-side only) | | `bearerToken` | JWT forwarded as `Authorization: Bearer ` (a plugin `backendToken`) | | `shopApiToken` | A Shop API token; auto-fetched when omitted | | `shopApiStaging` | Use staging Shop API | @@ -101,8 +109,8 @@ All callers share the same signature: | Caller | Purpose | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `catalogueApi` | Catalogue GraphQL | -| `discoveryApi` | Discovery GraphQL (search/browse) | +| `catalogueApi` | Catalogue GraphQL: synchronous fallback for per-customer prices and in-sync reads | +| `discoveryApi` | Discovery GraphQL: every storefront catalogue read | | `pimApi` | PIM GraphQL (legacy — prefer `nextPimApi`) | | `nextPimApi` | PIM Next GraphQL (scoped to tenant, recommended) | | `meApi` | Per-user GraphQL (`@me`) — call on behalf of the authenticated viewer | @@ -152,10 +160,24 @@ you use up front to get a single token. A `shopApiToken` passed in the configura except that a token with no `scopes` claim is trusted for any endpoint; with `doNotFetch: true` it is used as is and nothing is ever fetched. -**The fetch needs an access token pair or a session.** The token endpoint does not read a `bearerToken`, and it checks -who you are on `/@me`, which refuses a tenant-scoped access token. A bearer-only client, a `bearerToken` set next to an -access token pair (it is sent instead of the pair) and a tenant-scoped pair all fail with -`Could not fetch shop api token: …`. +**The fetch needs an access token pair or a session.** The token endpoint does not read a `bearerToken`. A bearer-only +client and a `bearerToken` set next to an access token pair (it is sent instead of the pair) fail with +`Could not fetch shop api token: …`. A tenant-scoped pair works for its own tenant; for any other the error ends in +"User is not a member of tenant X", even when the user is a member. + +**Token lifetime: two defaults.** The client asks for `expiresIn: 3600 * 12` (12 hours) unless `shopApiToken.expiresIn` +says otherwise; the API's own default, for a raw `POST …/auth/token` without `expiresIn`, is one day. The client posts +to `…/@{tenant}/…`; the `@` is optional on the Shop API, so raw calls to `…/{tenant}/…` reach the same place. + +**Server only.** The Shop API's CORS refuses origins other than Crystallize's and localhost, and the token reads any +customer's data, so keep every `shop*Api` caller and Shop helper in server code (route handlers, server actions, +webhooks). One client per process is enough: it caches the token and refreshes it. + +**The Catalogue credential rides along.** The Shop API reads products from the Catalogue with the request's +credentials. The Shop callers send the client's own credential header (by the priority under +[Authentication](#authentication)) next to `Authorization: Bearer `, so on a tenant whose Catalogue +requires a static token, give the client that `staticAuthToken`, or the pair when the Catalogue requires the pair. +`extraHeaders` never reaches the Shop callers. (Read from the 7.5.0 source.) ```typescript import { createCartManager, createClient, createShopOrderManager } from "@crystallize/js-api-client"; @@ -205,7 +227,11 @@ const read = await orders.fetch(order.id, { payments: { provider: true, transact - **`hydrate` takes a whole `context`.** Every `context` field above is required, or the client throws before calling. With no `context` at all, which only plain JavaScript allows, it sends the defaults: `en`, 30 days, `eur`, 0 decimals, the `default` price variant. The schema silently drops what it does not know, so `type`, `name`, `context.catalogue` and - `context.wishlist` never reach the API: use `shopCartApi` for those. + `context.wishlist` never reach the API: use `shopCartApi` for those. `context.catalogue` is not a credential: the API + takes `productVariantMaxAge` and `productVariantImages { maxCount, renditions { minWidth, maxWidth, formats } }` + there (introspected 2026-11-12). +- **`hydrate` replaces the cart's items** with the list you send: send the whole basket every time, and batch client + changes into one call. - The cart manager also has `addSkuItem(id, item)`, `removeItem(id, { sku, quantity })`, `setMeta(id, { meta, merge })` (`merge` is required) and `setCustomer(id, customer)`. The rest of `/cart` (`addExternalItem`, `bookSkuItem`, `markAsWishlist`, `remove`, `orderIntent`, `carts`) has no helper: call it through `shopCartApi`. @@ -233,6 +259,9 @@ const read = await orders.fetch(order.id, { payments: { provider: true, transact - `listByCustomer(identifier, { limit, skip })`, `setMeta(id, { meta, merge })`, `setCustomer(id, customer)` and `removeFromPipeline(id, pipeline)` complete the order manager. The `/order` `create` mutation (an order with no cart) has no helper: call it through `shopOrderApi`. +- **`listByCustomer` reads a lagging store**: new orders appear after seconds to minutes and a few never did. Read + what you just wrote with `fetch(id)`, and never use the listing to decide whether an order already exists (see + [[query]]). ```typescript import { createShopCustomerManager, createShopLock } from "@crystallize/js-api-client"; @@ -271,12 +300,26 @@ if (await lock.acquire(`order-${cartId}`, 30)) { - **Lock keys keep only `a-z`, `0-9` and `-`**: any other character is dropped, so `Order:1` and `rder1` are the same lock. -**Shop or Core?** An order made from a cart lives on the Shop API: create it with `createShopOrderManager` -(`createFromCart`) and keep recording its payments there. `createOrderManager` writes Core orders (`register`, -`update`, `setPayments`) — for orders that never had a cart (imports, POS, back office). A Core write on a Shop order -is pushed back to the Shop order as a whole and can overwrite payments just set through the Shop API. The same split -holds for customers (`createShopCustomerManager` vs `createCustomerManager`). The [payments skill](../payments/SKILL.md) -shows the whole checkout. +**Shop or Core?** Pick by who reads the order: + +- **A storefront, an account page or the Shop API lists it** (every cart checkout, and also POS sales, accepted quotes + and demo seeds): the Shop API. `createShopOrderManager.createFromCart` for a cart, raw `shopOrderApi` `create` for + an order without one, and every later write (payments, meta, stages) through the Shop API too. +- **Nobody reads it from the edge** (an import into the back office): `createOrderManager.register` on Core. Each + later Core `update` of such an order adds **another copy** to the Shop store, and a Core write on a Shop order + overwrites it whole, payments included. + +The order store table in [[mutation]] (`shop-api-order-mutations.md`, "The Order Store and Core") is the rule. The +same split holds for customers (`createShopCustomerManager` vs `createCustomerManager`). The +[payments skill](../payments/SKILL.md) shows the whole checkout. + +**Subscription contracts and bookings have no Shop helper.** `createSubscriptionContractManager` and +`createSubscriptionContractFetcher` are **Core** helpers. On a tenant whose contracts live on the Shop API (one store +per tenant, see [[subscriptions]]), call `shopSubscriptionContractApi` raw, with a client whose `shopApiToken.scopes` +are only `['subscription-contract', 'subscription-contract:admin']`, used for nothing else (a client unions the scopes +of every endpoint it calls into one token): a token carrying every scope answered "Unexpected error" on `create`. `shopBookingApi` posts to `/booking`, which answers 404; call `/booking/admin` with +your own `fetch` and a `booking:admin` token, and do holds and availability on `/cart` through `shopCartApi` +([[bookable-resources]]). **Upgrading to 7.5:** nothing changes for `createClient` users. A hand-built `ClientInterface` (a typed test mock) needs the five new callers. Cart and Shop customer `birthDate` is now sent as an ISO string. @@ -285,7 +328,7 @@ needs the five new callers. Cart and Shop customer `birthDate` is now sent as an | Auth Type | Header sent | Use Case | | ------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| `staticAuthToken` | `X-Crystallize-Static-Auth-Token: ` | Read-only catalogue/discovery | +| `staticAuthToken` | `X-Crystallize-Static-Auth-Token: ` | A restricted Discovery or Catalogue; also sent on Shop calls (Catalogue hydrate) | | `accessTokenId` + `accessTokenSecret` | `X-Crystallize-Access-Token-Id` + `X-Crystallize-Access-Token-Secret` | PIM/Shop operations | | `sessionId` | `Cookie: connect.sid=` | Alternative to token pair | | `bearerToken` | `Authorization: Bearer ` | Plugins forward `envelope.backendToken`, the only JWT accepted; Core and PIM APIs only | @@ -293,8 +336,10 @@ needs the five new callers. Cart and Shop customer `birthDate` is now sent as an **Priority** when multiple are set on the same client: `sessionId` > `bearerToken` > `staticAuthToken` > `accessTokenId`/`accessTokenSecret`. Only one is sent per request. Per-caller restrictions: -- `discoveryApi` sends `bearerToken` or `staticAuthToken`, but Discovery reads only the static token: a bearer token is - ignored. +- `discoveryApi` sends `bearerToken` or `staticAuthToken`, and **never the access token pair**. Discovery reads the + static token for a restricted tenant, and ignores a bearer token. Draft preview is a plain `discoveryApi` read with + `publicationState: draft`: on an open Discovery it needs no credential, which also means every draft is public. To + keep drafts private, restrict Discovery and give a server-only client the `staticAuthToken` (see [[query]]). - `catalogueApi` sends `bearerToken`, `staticAuthToken`, or `accessTokenId`/`accessTokenSecret`, but Catalogue reads only the credential the tenant requires, the static token or the pair: a bearer token is ignored. - `pimApi` and `nextPimApi` honor `sessionId`, `bearerToken`, and `accessTokenId`/`accessTokenSecret`. diff --git a/use-crystallize/skills/mass-operations/SKILL.md b/use-crystallize/skills/mass-operations/SKILL.md index 0bbad2e..e1c6d84 100644 --- a/use-crystallize/skills/mass-operations/SKILL.md +++ b/use-crystallize/skills/mass-operations/SKILL.md @@ -3,7 +3,7 @@ name: mass-operations description: Author, validate, run, and monitor Crystallize mass operation files — the JSON batch format executed by the mass-operations runner as a BulkTask. Use this skill whenever the user wants to bulk create, update, or upsert Crystallize data (products, folders, documents, variants, prices, stock, customers, orders, subscription contracts, shapes, pieces, topics, flows, price lists, paths, images), seed or migrate a tenant, import a catalog or customer/order backlog, fix or replay data outside API rate limits, publish or unpublish items at scale, or debug a failed or stuck bulk task. Trigger on mentions of "mass operation", "mass-operation", "bulk task", "bulkTask", "operations.json", "intent", "_ref", "createMassOperationBulkTask", "operationLogs", or on any request phrased as "import X into Crystallize", "update all products", "migrate this tenant" — even when the user does not name the mass operations feature itself. metadata: author: Crystallize - version: "1.0" + version: "1.1" --- # Crystallize Mass Operations @@ -114,6 +114,16 @@ and all `item/paths/*`. Everywhere else it is either rejected at runtime or sile `image/register` only looks it up and never stores it — the full table is in `references/intents.md` § "Where `resourceIdentifier` actually works". +**Use only letters, digits and `. - _ / @`.** The runtime error says the value may include +`;:+@( )._-"=`, but spaces, colons and parentheses are refused (`Invalid identifier … can only include …`), +and every affected operation fails with `Failed to instantiate command`. Write `folder/controls-2` or +`page-home`, not `folder:controls-2`, and sanitise SKUs such as `15 081 10` before using them as keys. + +**Only a mass operation can write `resourceIdentifier`.** Core create and update inputs have no such field +and Core `items` can't filter on it (it can read it). Write identity through `product|document|folder +/create|upsert` and mirror the same value into `externalReference`, which Core can filter on with +`items(filter: { externalReferences })`. See [[mutation]] for the Core side. + ### 5. Order operations as a dependency tree **A thing must exist before anything references it.** Execution is strictly sequential, so every @@ -137,9 +147,12 @@ content model. There is no deferred resolution and no second pass. Chain with `_ref` where there is no natural identifier, and with a shared `identifier` / `resourceIdentifier` where there is. -Shapes or pieces that reference each other in a cycle: create them first with `"components": []` -(`shape/create`, `piece/create`), then send the full definition with `shape/upsert` / `piece/upsert`. -`dump-content-model` writes files in this form. +Shapes and pieces that reference each other: create every one of them empty first, then fill them, +pieces before shapes. This is the 4-phase order in [[content-model]] (empty pieces, empty shapes, full +pieces, full shapes). The empty phase can be `piece/upsert` / `shape/upsert` without `components`, or +`piece/create` / `shape/create` with `"components": []`, which is the form `dump-content-model` writes. +Skip the empty phase for a shape or piece the tenant already has: an upsert replaces the whole +definition, so a run that stops after it leaves the existing one empty. **Nothing checks this for you.** The schema validates structure, not existence, so a file referencing something that isn't there yet uploads and starts happily — it fails partway through, after earlier @@ -180,6 +193,11 @@ even when individual operations failed — each failure is logged and the runner operation. There is no rollback. Per-operation `status` is `success`, `partial`, or `failure`, with `statusCode` `200`, `206`, or `500` respectively. +**The reason for a failure is nested.** The log's top-level `message` is only `Operation failed.`; read +`output.value.error.message`. Successful outputs are wrapped the same way: `output` is `{ value: { id } }`, +while `_ref` sees the unwrapped `{ id }`. Logs do not come back in file order, so match them to operations +by `resourceIdentifier` or the rendered id in `input`, never by position. + Three ways an operation can leave **no log entry at all**: - its converter returned no command (see `references/intents.md` § "Silent skips"), @@ -215,6 +233,26 @@ the ignition task like any other bulk task, treat `error` as blocking, and probe omitted `priceVariants`, `stockLocations`, `images`, `videos` and `attributes` reset to empty. To change one component use `item/updateComponent/*`. An upsert also re-applies `tree.parentId`, moving the item back if someone moved it. +- **An upsert in a second language empties shared relation components.** Item relations are not per + language, so a `product/upsert` in `en` that leaves out the relations set by the `no` run clears them for + every language. Write relations after the last language run (or send them in every run), then check + relation counts in Discovery. +- **Optional numerics with a `units` list fail the update path.** A `product/upsert` (or `update`) that hits + an existing product fails with `No unit provided for numeric item component …` for any variant that has + no value for such a component, even when the operation does not send it. On several tenants the create + of the same item passed, so the first run works and the rerun fails; on others the create failed too. + Workarounds that worked: drop the `units` list + from optional numerics (the unit is still stored per value), or patch only what changed with + `item/updateComponent/*` and `product/update` without `variants`. See [[content-model]] for the model side. +- **Validation differs per intent.** Upserts check relation minimums (`Need to provide at least 1 related + items for component brand`) and `item/updateComponent/item` checks nothing (`references/limits.md`). + `item/publish` has no `disableComponentValidation`, so an item with an empty unit-bound numeric never + publishes through it: use Core `publishItem(s)(…, disableComponentValidation: true)`, which also hides + shape-limit violations, so keep the normal publish validated. +- **Large products can fail to create.** A `product/upsert` create with 100 variants failed with a bare + `Operation failed.` for some products, deterministically, while siblings of the same size succeeded. + Create with up to 50 variants, then send the rest with a second `product/upsert` or + `product/variant/upsert`. - **At `version: "1.0.0"` there is no upsert return-shape trap for items.** The v1.0.0 converters normalise `product|document|folder /upsert` to a flat `{id}` and `piece|shape|customer /upsert` to `{identifier}`. The `{{#if x.id.id}}…{{else}}…{{/if}}` guard seen in the public docs is legacy `0.0.1` behaviour — @@ -258,7 +296,8 @@ the ignition task like any other bulk task, treat `error` as blocking, and probe and `order/register` is asynchronous, so a later operation in the same file can miss the order. Read `references/intents.md` § "Schema quirks worth knowing" before importing orders. - **`item/publish` is one item at a time and only a request.** `includeDescendants` validates and is - ignored, and `success` means accepted, not yet published. + ignored, and `success` means accepted, not yet published. A log entry with status `success` can still + hold the item in its result's `failure` list: read the result, then check the published version. - **Never guess an intent name.** The union in `references/intents.md` is exhaustive as of v6.17.0. - **Presigned URLs are short-lived.** Upload immediately after requesting one. diff --git a/use-crystallize/skills/mass-operations/references/intents.md b/use-crystallize/skills/mass-operations/references/intents.md index abc2c26..ef794d2 100644 --- a/use-crystallize/skills/mass-operations/references/intents.md +++ b/use-crystallize/skills/mass-operations/references/intents.md @@ -129,6 +129,11 @@ entity, or with a `fetch*` helper (`references/templating.md`). `image/register` skips the operation if an image already carries that `resourceIdentifier`, but it does not write the field and no public API sets it on an image, so that match does not happen in practice. +Observed otherwise on one tenant (2026-10): a re-run of `image/register` with an already-used +resourceIdentifier was skipped with no log entry, so its key was lost, and `{{ upload url rid }}` without the +operation-level `resourceIdentifier` returned the existing key. Treat this as unsettled: keep your own +url → key cache, and to recover a lost key run `image/register` with `{{ upload url rid }}` and no +operation-level `resourceIdentifier`, which logs the key. ## Which upserts are idempotent @@ -158,7 +163,8 @@ doesn't exist create a new record under a generated id, not yours. ## Properties exposed to `_ref` An operation's `_ref` output is the normalised result of the command it ran. The same value is stored -in `OperationLog.output`, which is the authoritative view. A failed or skipped operation stores `{}`. +in `OperationLog.output` under `value` (`{ value: { id } }`), which is the authoritative view. A failed or +skipped operation stores `{}`. **Verified** (at `version: "1.0.0"`): @@ -263,6 +269,9 @@ counting the whole subtree; **50 items** per `item/flow/stage/addItems`; **500 c - `product/variant/price/modify` is flat: on a tiered price it replaces the whole ladder with one price. - **`variant.topicIds` is silently dropped.** Also stripped by the schema, and _not_ re-attached. Assign variant topics another way. +- **The image showcase hotspot is spelled `hotpost`** in the mass-operation schema (`showcase[].hotpost { x, y }`), + where the Core API says `hotspot`. Use the schema's spelling here, or write showcases with Core `updateImage` or + item component content. See [[media]]. - **`item/updateComponent/item` runs with content validation disabled.** Component content is written without validation, so malformed content lands silently. `item/updateComponent/sku` does not disable it. diff --git a/use-crystallize/skills/mass-operations/references/lifecycle.md b/use-crystallize/skills/mass-operations/references/lifecycle.md index 28db885..fa5109c 100644 --- a/use-crystallize/skills/mass-operations/references/lifecycle.md +++ b/use-crystallize/skills/mass-operations/references/lifecycle.md @@ -264,8 +264,12 @@ will not return every log in one call. The filter also accepts two fields the do `product/`. Filtering on `status: failure` is the fastest triage. Each entry stores the original input payload, the command executed, the result, a `status` -(`success` / `partial` / `failure`), and a `statusCode`. On a failure `message` is generic: the reason is -in `output.error.message`. +(`success` / `partial` / `failure`), and a `statusCode`. On a failure `message` is only `Operation failed.`: +the reason is in `output.value.error.message`. `output` is wrapped in `value` on success too +(`{ value: { id } }`), and the resourceIdentifier sits deep inside `input.value.command…`. + +**Logs are not returned in file order.** Match an entry to its operation by the resourceIdentifier or the +rendered id in `input`, not by its position in the connection. | status | statusCode | When | | --------- | ---------- | ---------------------------------------------------------- | diff --git a/use-crystallize/skills/mass-operations/references/limits.md b/use-crystallize/skills/mass-operations/references/limits.md index b2063a1..54171b6 100644 --- a/use-crystallize/skills/mass-operations/references/limits.md +++ b/use-crystallize/skills/mass-operations/references/limits.md @@ -16,6 +16,7 @@ re-check anything load-bearing before depending on it. - [Component capacity](#component-capacity) - [String and number bounds](#string-and-number-bounds) - [Structural rules](#structural-rules) +- [Throughput](#throughput) ## How limits fail @@ -176,37 +177,37 @@ Ceilings on the `max` you may configure, and therefore on content. ## String and number bounds -| Field | Bound | -| ---------------------------------------------------- | ---------------------------------------------------- | -| **Default for every unqualified string** | min 1, **max 256** | -| Shape / piece identifier | **2–64**, charset as below | -| Flow identifier | **1–64**, charset as below | -| Identifier charset | `[A-Za-z0-9]` plus `; : + @ ( ) . _ - " =` and space | -| `resourceIdentifier` | 1–**256**, charset `[A-Za-z0-9]` plus `. - _ / @` | -| `externalReference` | 1–256 | -| Item / catalogue item name | **512** | -| Product variant name | **1024** | -| SKU | **512** | -| Variant attribute key / value | **128** / **2048** | -| Component name / description | 256 / 1024 | -| `singleLine` text, meta value, tree path | **1048576** | -| Meta key | 256 | -| Image alt text / URL | 1024 / 10240 | -| Order `additionalInformation` | 10240 | -| Language code | 2–20 | -| Currency code | 10 | -| Topic display colour | `#RGB`, `#RRGGBB` or `#RRGGBBAA` | -| Uploaded filename (basename of the `{{upload}}` URL) | 3–512 | -| Every `id` field | exactly 24 lowercase hex, or `{{ ... }}` | -| Price | −1e9 … 1e9 | -| Percent (order tax & discount) | −1000 … 1000 | -| Order cart item quantity | 0 … 1e6 | -| Item tree position | 1 … 100000 | -| Latitude / longitude | ±90 / ±180 | -| Focal point | x, y each 0 … 1 | -| **`product/variant/price/modify` price** | **minimum 1** — you cannot set 0 this way | -| **`product/variant/stock/modify` quantity** | **integer, 0 or more** | -| Stock (elsewhere) | integer, **fractional input silently truncated** | +| Field | Bound | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| **Default for every unqualified string** | min 1, **max 256** | +| Shape / piece identifier | **2–64**, charset as below | +| Flow identifier | **1–64**, charset as below | +| Identifier charset | `[A-Za-z0-9]` plus `; : + @ ( ) . _ - " =` and space | +| `resourceIdentifier` | 1–**256**, charset `[A-Za-z0-9]` plus `. - _ / @` (the error message lists more; spaces, `:` and `( )` are refused) | +| `externalReference` | 1–256 | +| Item / catalogue item name | **512** | +| Product variant name | **1024** | +| SKU | **512** | +| Variant attribute key / value | **128** / **2048** | +| Component name / description | 256 / 1024 | +| `singleLine` text, meta value, tree path | **1048576** | +| Meta key | 256 | +| Image alt text / URL | 1024 / 10240 | +| Order `additionalInformation` | 10240 | +| Language code | 2–20 | +| Currency code | 10 | +| Topic display colour | `#RGB`, `#RRGGBB` or `#RRGGBBAA` | +| Uploaded filename (basename of the `{{upload}}` URL) | 3–512 | +| Every `id` field | exactly 24 lowercase hex, or `{{ ... }}` | +| Price | −1e9 … 1e9 | +| Percent (order tax & discount) | −1000 … 1000 | +| Order cart item quantity | 0 … 1e6 | +| Item tree position | 1 … 100000 | +| Latitude / longitude | ±90 / ±180 | +| Focal point | x, y each 0 … 1 | +| **`product/variant/price/modify` price** | **minimum 1** — you cannot set 0 this way | +| **`product/variant/stock/modify` quantity** | **integer, 0 or more** | +| Stock (elsewhere) | integer, **fractional input silently truncated** | ## Structural rules @@ -228,6 +229,21 @@ Minimums and shape rules, not maximums. - At least one of `resourceIdentifier` / `id` / `itemId` / `topicId` is required where `checkResourceIdentifierOrId` applies. +## Throughput + +Figures observed on production tenants in 2026, for planning, not guarantees: + +| Work | Observed | +| -------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `product/upsert`, chunks of up to 40 products / 1,500 variants | about 700 variants per minute (11k variants in about 16 min) | +| `product/upsert` create | about 40 products per 1–2 minutes | +| `item/updateComponent/item` + `product/variant/upsert` | about 130–150 operations per minute | +| 160 operations (about 2 MB) per file | 46–122 s; three files in parallel ran at 15–20 RPS with no 429 | +| `image/register` with `{{ upload }}` | about 400 images per 3 minutes; 150-op files in about 10 s each when the source is fast | + +Downloading from the source dominates image runs. A rerun made of per-component updates costs far more +than the first upsert, so let each step skip what nobody changed. + ## Operational note A run that dies midway leaves the task stuck in `started`. Only `pending` tasks are picked up, so there diff --git a/use-crystallize/skills/mass-operations/references/templating.md b/use-crystallize/skills/mass-operations/references/templating.md index 4f41905..51b177f 100644 --- a/use-crystallize/skills/mass-operations/references/templating.md +++ b/use-crystallize/skills/mass-operations/references/templating.md @@ -166,7 +166,12 @@ Mechanics worth knowing: runner waits for them before the next operation. - Within one task, repeated calls with the same URL return the same key — so calling `upload` inline in several operations is safe. -- The filename is the last segment of the URL, so query strings and redirect URLs can produce odd names. +- The filename is the basename of the raw URL string, so query strings and redirect URLs can produce odd + names (`…?w=2400&fm=jpg` becomes `…tifw2400andfmjpg`). An extension-less URL (`…/4846/default`) gives a key + without an extension that registers but is **never processed**: `width`, `height` and `variants` stay + `null`. Append a query whose last segment is a file name, as a hint: + `…/4846/default?name=/brand-4846.jpg` gives the key `…/brand-4846.jpg` and a full set of renditions. Unique + file names also let you map keys back to sources by `key.split("/").at(-1)` rather than by log order. - The source must send `Content-Length` and an allowed image `Content-Type` (`references/limits.md`). - Image uploads are logged as their own entries with `"intent": "image/upload"` and statusCode 200/500, **separate** from the operation that called `upload`. A failed image does not fail its operation. diff --git a/use-crystallize/skills/media/SKILL.md b/use-crystallize/skills/media/SKILL.md new file mode 100644 index 0000000..a1f19b1 --- /dev/null +++ b/use-crystallize/skills/media/SKILL.md @@ -0,0 +1,183 @@ +--- +name: media +description: Import images, video and files into Crystallize and get them served — copyRemoteAsset from a supplier or manufacturer URL, presigned uploads (generatePresignedUploadRequest, form POST, registerImage), verifying that a copy landed, waiting for renditions before publishing, video upload and transcoding, alt text, captions and image topics per language (updateImage), showcases (hotspots, shop the look), replacing an image (registerImageRevision) and deleting media. Use when importing product images, debugging broken or missing images, images without renditions or with variants [] in Discovery, ImageNotFoundError, ImageAlreadyExistsError, copy tasks that fail silently, uploading images from a browser page, attaching video, tagging or classifying images, or adding hotspots. For rendering images (srcset, sizes, formats, LCP) use responsive-images. +metadata: + author: Crystallize + version: "1.0" +--- + +# Crystallize Media Skill + +Get images, video and files into the media library, onto items, and into Discovery. Every step is asynchronous, and +most failures are silent: a key is handed back before the file exists, renditions arrive minutes to an hour later, +and Discovery keeps whatever it saw when the item was published. Media import was the second most frequent problem +across twelve builds. + +Rendering what you imported (srcset, sizes, WebP vs AVIF, LCP, share images) is [[responsive-images]]. Modelling the +components that hold media is [[content-model]]. All mutations here are on the Core API, from scripts or your server. + +## Consultation Approach + +1. **Where do the files come from?** A URL Crystallize can fetch, bytes you hold, or a browser page (user uploads)? +2. **Images, video or files?** Video and files take the upload path only. +3. **How many?** Hundreds need throttling, task checks and a verification pass; thousands need a resumable script. +4. **Which languages?** Alt text, captions and image topics are written once per language. +5. **When will the items be published?** After the renditions exist, or Discovery serves them without renditions. + +## Choose the way in + +| You have | Use | +| --------------------------------------- | ---------------------------------------------------------------------------------- | +| A URL Crystallize can fetch | `copyRemoteAsset(sourceUrl:, type: image)`: Crystallize pulls it, as a bulk task | +| Bytes you hold, or a URL it can't fetch | `generatePresignedUploadRequest(type: MEDIA)` → form POST (it registers the image) | +| A file uploaded from a browser page | Presign on the server, POST from the browser, no Core token in the page | +| Video, whatever the source | The upload path: `copyRemoteAsset` takes images only | +| Files (PDF, CAD) | Upload with `type: STATIC`, then `{ key, title }` in a `files` component | +| Many images in a mass operation | `image/register` with `{{ upload url }}` ([[mass-operations]]) | + +**`copyRemoteAsset` can't fetch** a source that: + +- takes more than **30 s** to answer (the task ends in `error`: `Request timed out after 30 seconds`); +- has a URL longer than **256 characters** (`InvalidLengthError`, before any fetch; signed CDN URLs hit this); +- sends no `Content-Length` (streamed or chunked resizers, and Cloudflare when it compresses on `Accept-Encoding`); +- sits behind bot protection (Akamai, Imperva): the mutation succeeds and only the task says `error`; +- answers a compressed body or a `content-type` other than `image/jpeg`, `jpg`, `png`, `webp`, `tiff`, `tif` or `avif`. + +For those, download the file yourself and use the upload path. Don't work around a block a site has put up. Prefer a +resized source where the manufacturer offers one: 3-17 MB CMYK originals copied slowly and failed often, while the +same CDN's 1600 px WebP (0.5-1 MB) went in as is. + +Details, code and every error: [Importing images](references/import.md). + +## The pipeline that works + +1. **Import** with bounded concurrency (8-12). Keep a local `source URL → key` cache, so reruns are free and no image + is registered twice. +2. **Check every copy task.** `copyRemoteAsset` answers with a `targetKey` and a task id before the copy runs. Read + `bulkTasks(filter: { type: copyRemoteAsset, status: error })` (or `bulkTask(id:)` per task) until no task is + `pending` or `started`; `info.error` has the reason, `targetKey` what to retry. +3. **Verify that the file landed**: `image(key) { key }` plus a HEAD on the CDN URL. The record existing proves + nothing: a key can be registered whose file never arrives, and `image(key)` is `null` while a copy is pending or + failed. +4. **Wait for processing**: `image(key) { width variants { url } }`. `width` and `variants` stayed `null` for 15 minutes + to over an hour on large imports, while the CDN already served the file. Don't re-copy because `width` is still + `null`; one build did, and got 320 duplicate records. +5. **Write metadata** (alt text, caption, topics, showcases) per language with `updateImage`, **before publishing**: + `updateImage` re-indexes every item that uses the image. +6. **Write the keys onto the items** (`images` components, variant images). A key can be referenced as soon as it is + registered. +7. **Publish the items only after `variants` exist for every key.** Discovery snapshots image metadata at publish time: + an item published earlier keeps `width: null` and `variants: []` until it is published again + ([Discovery Indexing](../query/references/discovery-indexing.md)). + +Check the content of what you imported, too. Manufacturer CDNs serve "missing image" placeholders, logos and blank +images with HTTP 200, a redirect to a login page uploads HTML, and an extension-less URL gives a key that is never +processed. A size and content-hash check catches most of it, and one picture re-encoded per colour variant is +de-duplicated by hash (`resourceIdentifier: img-` in a mass operation). + +## Presigned uploads + +```graphql +mutation Presign($filename: String!, $contentType: String!) { + generatePresignedUploadRequest(filename: $filename, contentType: $contentType, type: MEDIA) { + ... on PresignedUploadRequest { + url + fields { + name + value + } + maxSize + lifetime + } + ... on BasicError { + errorName + message + } + } +} +``` + +Build a multipart form from `fields` **in the order given**, append the file **last**, and POST it to `url`. The key is +the `key` field. + +- **The POST registers the image by itself.** A `registerImage` afterwards answers `ImageAlreadyExistsError`: treat it + as success. It is still worth calling right after the POST, because it makes the key usable at once. +- **So a browser page can upload directly**: the server makes the presign (Core token), the page POSTs the form, and + no Core credential reaches the browser. This is the one Core-related call a storefront page makes, and it goes to + the storage URL, not to Core. +- A `400 RequestTimeout` from the POST is retried with a **fresh** presign (the failed try may leave an orphan key). +- Check the `content-type` you are uploading: a 302 to a login page uploaded HTML that `registerImage` accepted and + that never got a size. +- `maxSize` was 10 GiB for images and video. The decoded policy lasts a year, so presigns can be made in bulk. + +## Metadata per language + +`updateImage(key:, language:, input:)` writes `altText`, `caption` (`{ html: [...] }`), `focalPoint`, `meta`, +`topicIds` and `showcase` on the **library asset**: + +- **Alt text, caption and image topics are per language.** Two languages means two writes per image (652 writes for + 326 images ran in about two minutes at concurrency 8, with no rate limiting). +- Item images point at the asset, so there is **no per-item alt text** to keep in sync: Discovery's + `images { altText }` comes from the asset, after the next publish. +- `updateImage` **re-indexes every item that uses the image** (17k updates touched all 787 products in one build). + Write metadata before publishing products, not after. +- Variant **attributes** are not per language: an `en` update overwrote the `no` colour values. Variant **images** are + written per language. +- `targetFilename` on `copyRemoteAsset` sets the public file name (`…//helsingin-heikas-a1-floor-plan.jpg`): + name files for people and search engines. +- Image topics in Discovery come back as a flat hash of every ancestor path, not leaf paths. +- Classifying images with a vision model (image type, alt text in each language) worked on 697 images; cache by URL. + +## Showcases (hotspots) + +A showcase links a point on an image to products, SKUs or documents: "shop the look". Core writes `showcase` +(singular) on `updateImage` and on every `ImageInput`; Discovery reads `showcases` (plural). Coordinates are +**fractions 0-1**, `skus` is required (send `[]`), and labels go in `meta`. See +[Showcases](references/showcases.md). + +## Video + +Upload with `generatePresignedUploadRequest(contentType: "video/mp4" | "video/quicktime", type: MEDIA)`, then write +`{ key, title }` into a `videos` component or a variant's videos. The video is registered when an item first uses it, +transcoded to HLS and DASH in about a minute for a short clip, and an item published before `playlists` exist keeps +`playlists: []` in Discovery. See [Video](references/video.md). + +## Replacing and deleting + +- **Replace**: upload the new file, then `registerImageRevision(imageKey:, revisionKey:)` right after the POST. + Core and the Catalogue API show the revision at once and the ladder rebuilds in about 25 s, but Discovery keeps the + file each item was indexed with. Republishing the items fixed it on one tenant and did not on another, so the + reliable way is a **new image**: upload, write the new key onto the items, publish. +- **Delete**: `deleteImage(key:, force:)` refuses while any item version references the image, old versions included + (`AssetInUseError … referenced in 3 places`). Check the current versions, then `force: true`. `deleteVideo` refuses + while an item uses it; once the item is gone the video stays registered and can be reused. + +## Failure modes + +| Symptom | Cause | Fix | +| ---------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | +| Broken tiles in the library, broken images on items | `copyRemoteAsset` gave a key, the copy never landed | Read failed tasks; HEAD-check keys; re-import with `requestHeaders`, or upload | +| `image(key)` is `null` after a copy | Copy pending, or failed (timeout, length, no Content-Length) | Wait for the task; read `info.error` | +| `ImageNotFoundError` from `updateImage` right after a copy | The key exists before the file does | Wait for every copy task; retry "not found" after a delay | +| `ImageAlreadyExistsError` from `registerImage` | The copy or the presigned POST registered it already | Treat as success | +| `width: null`, `variants: null` for a long time | Renditions are queued (minutes to an hour) | Wait; verify by key + HEAD, not width; don't re-copy | +| `variants: []` in Discovery, renditions fine in Core | The item was published before the renditions existed | Publish the items again | +| `playlists: []` in Discovery | Published before transcoding finished | Wait for Core `video(key) { playlists }`, then publish | +| Alt text shows in one language only | Metadata is per language | `updateImage` once per language | +| A replaced image still shows the old file | Discovery keeps what it indexed | Republish, or register a new image and write its key | +| `AssetInUseError` on an image nothing current uses | Old item versions still reference it | `deleteImage(force: true)` after checking current versions | +| `copyRemoteAsset` rejects a video URL | `RemoteAssetType` is `image` only | Use the presigned upload path | + +## References + +- [Importing images](references/import.md) - `copyRemoteAsset` and its limits, task checks, presigned uploads, mass + operation registration, verification, renditions +- [Video](references/video.md) - Upload, registration on first use, transcoding, thumbnails, publishing order +- [Showcases](references/showcases.md) - Hotspot input and output, coordinates, labels per language, variant images + +## Related skills + +[[responsive-images]] renders the ladder. [[mutation]] covers the item writes that reference media keys, and +[[mass-operations]] the `image/register` path. [[content-model]] decides which components hold media and whether they +are discoverable (an `images` component left non-discoverable is absent from Discovery). Indexing behaviour is in +[Discovery Indexing](../query/references/discovery-indexing.md). diff --git a/use-crystallize/skills/media/references/import.md b/use-crystallize/skills/media/references/import.md new file mode 100644 index 0000000..da53574 --- /dev/null +++ b/use-crystallize/skills/media/references/import.md @@ -0,0 +1,218 @@ +# Importing images (Core API) + +You have a list of image URLs from a supplier, or files on disk, and they need to end up on products. There are +**two ways in**, and the one you pick decides what can go wrong afterwards. + +> Signatures were read from the live Core API schema (2026-09-29, rechecked 2026-11-12). The behaviours, what +> arrives late and what fails silently, are attributed to the builds that hit them. + +| You have | Use | +| ---------------------------------------- | ---------------------------------------------------------------- | +| A URL Crystallize can fetch | `copyRemoteAsset`: Crystallize pulls it, as a bulk task | +| Bytes you hold, or a URL it cannot fetch | `generatePresignedUploadRequest` → form POST (→ `registerImage`) | +| Video, whatever the source | The upload path ([Video](video.md)) | + +## Copying from a supplier URL + +```graphql +mutation Copy($sourceUrl: String!, $filename: String) { + copyRemoteAsset(sourceUrl: $sourceUrl, type: image, targetFilename: $filename) { + __typename + ... on BulkTaskCopyRemoteAsset { + id + targetKey + status + } + ... on BasicError { + errorName + message + } + } +} +``` + +`type` is `RemoteAssetType`, and today its only value is **`image`**. `requestHeaders: [HttpHeaderInput!]` (`{ name, +value }`) is there for sources that will not serve a bare request; a wrong input type name fails the whole mutation +as a validation error. `targetFilename` sets the public file name. + +**Each call took 10-15 s to answer** for 1 MB sources. Concurrency 12 copied about 2,900 images in 25 minutes on one +tenant and 10,743 in 547 s on another. + +### It is a bulk task, so the key comes back before the file does + +`targetKey` is handed to you immediately; the copy happens afterwards. The consequences, all found the hard way: + +- **A failed copy only shows on the task.** `bulkTask(id:) { ... on BulkTask { status info } }` ends in `error`, with + the reason in `info.error`. List every failure at once with + `bulkTasks(filter: { type: copyRemoteAsset, status: error })`; each carries the `targetKey`, which is how a rerun + finds what to copy again. +- **The source has to answer within 30 s.** A slow on-the-fly resizer failed 2,897 of 3,056 copies with + `Request timed out after 30 seconds`; an origin taking up to 107 s for 4-13 MB originals lost 5,677 of 10,563. + Copy from the manufacturer's CDN or resizer instead, and throttle. +- **`sourceUrl` is at most 256 characters** (`InvalidLengthError: sourceUrl length must be between 1 and 256 + characters`), checked before the fetch. Signed CDN URLs of about 300 characters all failed. +- **The response needs a `Content-Length`**: chunked resizers fail with `No content length in response`, and so does + Cloudflare when it compresses on `Accept-Encoding`. The body must be uncompressed (`content-encoding` other than + `identity` is refused), within the upload limit, with a `content-type` of exactly `image/jpeg`, `jpg`, `png`, + `webp`, `tiff`, `tif` or `avif`. +- **Bot protection fails only in the task.** Akamai and Imperva sources returned a key and a task id, and only + `bulkTask(id).status` said `error` later. A CDN that serves a normal browser but not Crystallize's fetcher gave every + image of one brand a key whose file 404s forever. +- **Do not call `registerImage` afterwards.** `copyRemoteAsset` already registers the image, and the second call + answers `ImageAlreadyExistsError`. +- **`updateImage` on a fresh key answers `ImageNotFoundError` for a while**, and `image(key)` is `null` while a copy + is pending or failed. Retry "not found" after a delay, or wait for **every** copy task rather than the last few. + +So after the copy tasks finish, **HEAD-check the keys**: all of them if the import is small, a sample if it is not. +For the ones that 404, try `requestHeaders` if you suspect the CDN is refusing the fetch, and otherwise download the +file yourself, convert it if needed (JPEG worked), and take the upload path below. Never work around a block a site +has put up on purpose. + +WebP sources work (some manufacturers publish nothing else), and PNG transparency is preserved. (Tools Universe.) + +## Uploading bytes yourself + +Ask for a presigned target, POST the file to it, register what landed. + +```graphql +mutation Upload($filename: String!, $contentType: String!) { + generatePresignedUploadRequest(filename: $filename, contentType: $contentType, type: MEDIA) { + __typename + ... on PresignedUploadRequest { + url + fields { + name + value + } + maxSize + lifetime + } + ... on BasicError { + errorName + message + } + } +} +``` + +`type` is `FileUploadType`: **`MEDIA`** for images and video, `STATIC` for files, `MASS_OPERATIONS` for an operations +file. Build a multipart form from `fields` **in the order given**, append the file **last**, and POST it to `url`. +The key is the `key` form field, of the form `/////`. + +```typescript +const form = new FormData(); +for (const { name, value } of presign.fields) form.append(name, value); +form.append("file", await fs.openAsBlob(path, { type: contentType }), filename); // Node 20+, streams the file +const res = await fetch(presign.url, { method: "POST", body: form }); // 201 on success +``` + +Then: + +```graphql +mutation Register($imageKey: String!) { + registerImage(imageKey: $imageKey) { + __typename + ... on Image { + key + url + width + height + } + ... on BasicError { + errorName + message + } + } +} +``` + +- **The upload registers the image by itself**, in the background. `registerImage` right after the POST makes the + key usable at once; when it answers `ImageAlreadyExistsError`, the upload got there first. Treat that as success. +- Right after `registerImage`, `width`/`height` are `null` and the media URL answers 404 for 5-20 s. It is fine to + reference the key in item writes immediately; poll the HEAD before anything reads the file. +- A `400 RequestTimeout` from S3 is retried with a **fresh** presign. +- Check the content type before uploading: a URL that 302s to a login page uploads HTML, which registers and never + gets a size. +- `maxSize` is 10 GiB and `lifetime` 3,600 s, while the decoded POST policy is valid for a year, so presigns can be + made in bulk ahead of time. +- Throughput: download (3 concurrent) + presign + POST + `registerImage` (8 concurrent) ran at about 34 images/s. +- In JS, `createBinaryFileManager(client).uploadImage(path)` does all three steps, and needs `tenantId` in the client + config ([[js-api-client]]). + +**From a browser page** (user content): make the presign on the server, hand the page `url` and `fields`, and let the +page POST the form. The POST registers the image, so the page needs no Core token, and your server records the key. + +## In a mass operation + +`image/register` with `{{ upload url rid }}` is the fast path: 691 images in five 150-operation files, about 10 s +each. The register log's `input.value.operation.key` is the key; cache it. Three traps: + +- `{{ upload }}` names the file after the URL's basename, so an extension-less URL (`…/product-images/4846/default`) + gives a key that registers but is **never processed**. Append a query whose last segment is a file name + (`…/default?name=/product-4846.jpg`). +- `image/register` with a resourceIdentifier that is already registered is **skipped silently**: no log, no key. +- Registered images get language `en` and no alt text: write metadata afterwards with `updateImage` per language. + +See [[mass-operations]]. + +## Verifying an import + +| Check | Proves | +| --------------------------------------- | -------------------------------------------- | +| The task's `status` is `complete` | The copy ran | +| `image(key) { key }` answers | The record exists, not that the file arrived | +| A HEAD on the CDN URL answers 200 | The file landed | +| `image(key) { width variants { url } }` | Processing finished: renditions exist | + +Verify the import by **key + HEAD**. Then, before the final publish, wait for **`variants`**: 45 minutes after one +import, 58 of 400 images still had `variants: null`, and it took about 70 minutes. After 326 copies, all had +`width: null` for 15 minutes while the CDN served them. A seed that waits for `width` right after the copy, and +re-copies what lacks it, makes duplicates (320 in one build). + +## Renditions and Discovery + +`Image.variants` is the generated ladder that [[responsive-images]] builds a `srcset` from, produced in a queue. +Discovery stores each item with the image metadata it saw when that item was indexed. Content published within +minutes of a bulk upload was served with `width/height: null` and `variants: []` for 280 of 614 images, while Core +had the full ladder shortly after. Re-writing the image components and republishing fixed all of them about 2 minutes +later. + +So: a storefront falls back to the original `url` when `variants` is empty, and an import publishes only after every +key has `variants`, or publishes again once they exist ([Discovery Indexing](../../query/references/discovery-indexing.md)). + +## Replacing an image + +`registerImageRevision(imageKey:, revisionKey:)` points the library entry at a new file: Core `image(key)` returns the +new `url` and `size`, and the ladder rebuilds in about 25 seconds. `revisionKey` is a file you have just uploaded; +call it right after the POST and skip `registerImage`, because once the upload has registered itself as an image the +revision is refused. + +**It reaches the read APIs at different times.** The Catalogue API serves the latest revision at once. Discovery +stores the file with each indexed document, so every item using the image keeps the original until it is indexed +again. One build fixed that by republishing; another (Tools Universe) still saw the old file after rewriting the image +component and republishing. The way that worked everywhere: upload the new file as a **new** image, write the new key +onto the items, and publish. + +## Deleting + +```graphql +mutation Delete($key: String!) { + deleteImage(key: $key, force: true) { + __typename + ... on DeleteCount { + removed + } + ... on AssetInUseError { + key + referrerCount + } + } +} +``` + +`deleteImage` refuses an image that **any** item version references, old ones included: `AssetInUseError … +referenced in 3 places` came back for an image every current draft and published version had moved away from. +`force: true` removes it anyway. Check the current versions yourself before forcing. (Car Parts Universe.) + +Clearing a variant's images with Core `updateProductVariant(sku, language, input: { images: [] })` leaves its +components alone, unlike the mass operation's `product/variant/update`. diff --git a/use-crystallize/skills/media/references/showcases.md b/use-crystallize/skills/media/references/showcases.md new file mode 100644 index 0000000..0f28cc0 --- /dev/null +++ b/use-crystallize/skills/media/references/showcases.md @@ -0,0 +1,93 @@ +# Showcases (hotspots) + +A showcase links a point on an image to products, SKUs or documents: the "shop the look" feature. (Fashion +Universe and four other builds, September to November 2026.) + +## Writing them (Core) + +`ImageShowcaseInput` (introspected 2026-11-12): + +```graphql +input ImageShowcaseInput { + hotspot: FocalPointInput # { x: Float!, y: Float! } + itemIds: [ID!] + skus: [String!]! # required: send [] for a showcase of items only + meta: [KeyValuePairInput!] +} +``` + +It is accepted as `showcase` (singular, a list) in two places: + +- `updateImage(key:, language:, input: { showcase })`, on the **library asset**, per language; +- every `ImageInput`: `images` components, paragraph images, and variant images through + `updateProductVariant(sku:, input: { images })`. + +```json +{ + "images": [ + { + "key": "", + "showcase": [ + { + "hotspot": { "x": 0.42, "y": 0.63 }, + "skus": ["SKU-1"], + "itemIds": [""], + "meta": [{ "key": "label_en", "value": "Basin mixer" }] + } + ] + } + ] +} +``` + +- **Coordinates are fractions of the image, 0-1**: not percent, not pixels. Keep percent in your source data for + review if you like, and divide by 100 when writing. +- **Labels are not part of a showcase**: put them in `meta`. On an `images` component that isn't multilingual, the + showcase list is stored once for all languages and keeps the meta of the **last** language written, so write + `label_` keys and read `meta(key: "label_")`. On library images (`updateImage` per language), a plain + `label` is per language. +- **A product's images are variant images**, so a showcase on a product image is written onto every variant that + carries that key, with the full `images` list (it replaces the list). +- Errors: `ImageShowcaseInvalidSkuError` (a SKU that doesn't exist yet: create the products first, or retry without + SKUs) and `ImageShowcaseInvalidIdError`. A just-registered key can answer `ImageNotFoundError` for a while. +- **The mass-operation schema spells the hotspot `hotpost`** (`@crystallize/schema` 6.17, image content → + `showcase[].hotpost { x, y }`). Write showcases with Core `updateImage` or component content instead. + +Core reads them back as `Image.showcase` (`{ hotspot itemIds skus meta }`). + +## Reading them (Discovery) + +Discovery serves **`showcases`** (plural): + +```graphql +{ + search(language: en, filters: { path: { equals: "/inspiration/bathroom" } }) { + hits { + ... on document { + hero { + url + showcases { + hotspot + meta + items { + name + path + } + variants { + sku + name + defaultPrice + } + } + } + } + } + } +} +``` + +`hotspot(key:)` and `meta(key:)` are `Hash` fields (`{ x, y }`). `items` resolves to full documents and products, and +`variants` to full variants, so one hotspot can carry a product (for the path) and a SKU (for the price) at once. + +New page-builder pieces that render showcases can need two ignites before Discovery serves them +([Discovery Indexing](../../query/references/discovery-indexing.md)). diff --git a/use-crystallize/skills/media/references/video.md b/use-crystallize/skills/media/references/video.md new file mode 100644 index 0000000..d18c24c --- /dev/null +++ b/use-crystallize/skills/media/references/video.md @@ -0,0 +1,71 @@ +# Video (Core API) + +`copyRemoteAsset` takes images only, so video always goes through the upload path. (Fashion Universe and Screen +Universe, September 2026.) + +## Upload and attach + +1. Download the file. MP4 and MOV upload as they are; an HLS-only source is remuxed first (`ffmpeg -i x.m3u8 -c copy + out.mp4`). +2. `generatePresignedUploadRequest(filename:, contentType: "video/mp4" | "video/quicktime", type: MEDIA)`. `maxSize` + is 10 GiB (S3's own limit for a single POST is 5 GB); 500 MB to 1 GB films are well within it. +3. POST the form: `fields` in order, the file last. Stream it (`fs.openAsBlob(path, { type: "video/mp4" })`, Node + 20+): 11 MB uploaded in 1.2 s, 62 MB in 9.5 s. +4. Write `{ key, title }` into a `videos` component, or a variant's videos: + +```graphql +mutation Attach($itemId: ID!, $language: String!) { + updateComponent( + itemId: $itemId + language: $language + component: { + componentId: "trailer" + videos: [{ key: "", title: "Trailer", thumbnails: [{ key: "", altText: "…" }] }] + } + ) { + __typename + ... on BasicError { + errorName + message + } + } +} +``` + +There is no `registerVideo`. **A video is registered when an item first uses it**: `video(key)` is `null` after the +upload until `{ key, title }` is written into a component. A `videos` component's `max` is enforced on create +(`Cannot provide more than 2 videos for component hero-video`). + +## Transcoding + +- A 32 s trailer had Core `video(key) { playlists }` within 32 s; a 10-minute, 62 MB file took 114 s. The output is + CMAF on `media.crystallize.com`: `…/cmaf/.m3u8` and `.mpd`. +- **The ladder goes up to 1080p, upscaling**: 480p and 360p sources both got 234p, 360p, 432p, 720p and 1080p + renditions (H.264). One earlier build saw the ladder capped at the source; check on your tenant. +- **Every rendition is 29.97 fps**: a 25 fps clip came back converted, which judders slightly. It isn't configurable + from the API. +- An audio group is always added: the source's audio when it has one, otherwise an `eng` program audio group. Keep a + silent stereo AAC track on silent sources if you want every file to have the same shape. + +## Thumbnails + +`thumbnails` stays `null` unless you write one. Upload a poster image and attach it, either with the video +(`VideoInput.thumbnails: [ImageInput]`, as above) or later with `updateVideo`. Discovery returns +` { thumbnails { url } }`. + +## Publishing order + +**Discovery doesn't pick up the playlists by itself.** An item published before transcoding finished kept +`playlists: []` in Discovery (checked for over four minutes) while Core had them, and publishing the item again fixed +it within 10 s. So: upload, attach, **wait for Core `video(key) { playlists }`**, then publish. + +## Deleting + +`deleteVideo` answers `AssetInUseError` while an item uses the video, so delete or change the item first. Once the +item is gone, `video(key)` still answers with its playlists, so a cached key can be attached to a new item and is +ready at once. + +## Files + +Files work the same way: upload with `type: STATIC`, then write `{ key, title }` into a `files` component. There is no +register step for them either. diff --git a/use-crystallize/skills/mutation/SKILL.md b/use-crystallize/skills/mutation/SKILL.md index 8ecaa43..0c0fe8a 100644 --- a/use-crystallize/skills/mutation/SKILL.md +++ b/use-crystallize/skills/mutation/SKILL.md @@ -1,96 +1,64 @@ --- name: mutation -description: Mutate data in Crystallize - create products, documents, and folders, update item components, manage product variants and SKUs, publish/unpublish items, handle customers and orders, manage carts and checkout flows, convert cart to order, create orders from checkout or directly (POS, imports), record payments, track fulfillment pipeline stages, upload images and media, and delete items. Use this skill when creating or updating any content in Crystallize, adding products to the catalogue, modifying descriptions or fields, setting up checkout, placing orders, managing stock, recording payments, tracking order fulfillment, or writing data through the Core API or Shop API. For bulk imports and tenant migrations use mass-operations; for provider checkout flows use payments. +description: Mutate data in Crystallize - create products, documents, and folders, update item components, manage product variants and SKUs, publish/unpublish items, handle customers and orders, manage carts and checkout flows, convert cart to order, create orders on the Shop API from a cart or directly (POS, accepted quotes, imports, demo seeds), record payments, track fulfillment pipeline stages, register webhooks, and delete items. Use this skill when creating or updating any content in Crystallize, adding products to the catalogue, modifying descriptions or fields, translating items, setting up checkout, placing orders, managing stock, recording payments, tracking order fulfillment, deciding whether a write belongs on the Shop API or the Core API, or writing data through the Core API or Shop API. For bulk imports and tenant migrations use mass-operations; for importing images and video use media; for provider checkout flows use payments. metadata: author: Crystallize - version: "2.0" + version: "3.0" --- # Crystallize Mutation Skill -Create, update, and manage data in Crystallize using GraphQL mutations. This skill covers all write operations across the Core API (admin/content management) and Shop API (cart/checkout). +Create, update and manage data in Crystallize with GraphQL mutations. Writes split along the same line as reads: +**everything a shopper does goes through the Shop API, from your server**, and catalogue and tenant management goes +through the Core API, from scripts and the back office. The full storefront contract is in [[storefront]]. ## Consultation Approach -Before writing mutations, understand the context. Ask clarifying questions: - -1. **What are you trying to create or update?** Products, documents, folders, customers, orders? -2. **Do you have the tenant identifier and access tokens?** Mutations require authentication. -3. **Where in the flow are you?** Content/catalog management → Core API. Cart/checkout/orders → Shop API. -4. **Do you need to update individual fields or create items from scratch?** `updateComponent` for fields, `create` for new items. -5. **Should changes be published immediately?** Creating an item doesn't publish it — that's a separate step. -6. **Are you doing a one-off change or a bulk import?** Single mutations vs mass operations. - -## Decision Tree - -``` -What do you need to do? -│ -├─ Create/update catalogue items (products, documents, folders) -│ ├─ Create new item → Core API: createProduct / createDocument / createFolder -│ ├─ Update a field on an item → Core API: updateComponent -│ ├─ Add/update product variants → Core API: addProductVariant / updateProductVariant -│ ├─ Publish/unpublish → Core API: publishItem / unpublishItem -│ └─ Delete an item → Core API: deleteItem -│ -├─ Manage customers -│ ├─ From a storefront → Shop API /customer: customer (create or update), addAddress -│ ├─ Create a person or a company → Core API: createCustomer (type: individual | organization) -│ └─ Update customer → Core API: updateCustomer(identifier:) -│ -├─ Manage orders -│ ├─ Create order from cart → Shop API /order: createFromCart -│ ├─ Create order directly (POS, import) → Shop API /order: create -│ ├─ Add/update payments → Shop API /order: addPayments / setPayments -│ ├─ Track order through pipeline → Shop API /order: addToStage -│ └─ Update order metadata → Shop API /order: setMeta (not Core updateOrder — see below) -│ -├─ Cart & checkout (storefront) -│ ├─ Create/hydrate a cart → Shop API: hydrate -│ ├─ Modify cart items → Shop API: addSkuItem / addCartItem / removeCartItem -│ ├─ Set customer & addresses → Shop API: setCustomer (addresses live on the customer) -│ └─ Convert cart to order → Shop API: place, then /order createFromCart -│ -├─ Media (images, video) -│ ├─ Import from a supplier URL → Core API: copyRemoteAsset (images only) -│ ├─ Upload your own bytes, or any video → Core API: generatePresignedUploadRequest → registerImage -│ ├─ Alt text, topics, hotspots → Core API: updateImage (per language) -│ └─ Replace an image → registerImageRevision, then republish the items that use it -│ -└─ Bulk operations - └─ Use a mass operation: see the mass-operations skill -``` - -## API Selection - -| Use Case | API | Why | -| ----------------------------------------- | -------------------------------- | ----------------------------------- | -| Creating/editing items, shapes, customers | **Core API** | Full read/write, admin-level access | -| Cart management, checkout | **Shop API `/cart`** | Edge-distributed cart lifecycle | -| Order creation, payments, pipelines | **Shop API `/order`** | Full order CRUD after checkout | -| Bulk shape + item creation | **Core API** via mass operations | Ordered multi-step creation | - -**Core is not a storefront API.** It is heavily rate limited and not meant for storefront traffic: carts, orders, customers and subscription contracts belong on the Shop API, which is edge-distributed and syncs to Core asynchronously. Keep Core for the back office — imports, seeding, scheduled jobs and admin tools, behind your own server. - -**Write an order in one store.** A Core write comes back to the Shop store. On an order born in Core, each edit adds **another copy** of it there: three `updateOrder` calls left three Shop orders with the same `coreId`, so a storefront that sums an order list counts the money several times. On an order born on the Shop API, a Core edit overwrites the Shop order whole. If a storefront reads orders, create and change them on the Shop API (`create`, `createFromCart`, `setMeta`, `addToStage`). Details in [Shop API Order Mutations](references/shop-api-order-mutations.md). - -## API Endpoints & Authentication - -| API | Endpoint | Auth Required | Use For | -| -------------- | ---------------------------------------------------- | ------------- | ------------------------- | -| Core | `https://api.crystallize.com/@{tenant}` | Yes | Items, shapes, customers | -| Shop /cart | `https://shop-api.crystallize.com/{tenant}/cart` | Yes (JWT) | Cart management, checkout | -| Shop /order | `https://shop-api.crystallize.com/{tenant}/order` | Yes (JWT) | Order CRUD, payments | -| Shop /customer | `https://shop-api.crystallize.com/{tenant}/customer` | Yes (JWT) | Storefront customers | +Before writing mutations, ask: + +1. **Who triggers the write: a shopper (storefront, account page, payment webhook) or the back office (seed, import, + admin tool)?** Shopper → Shop API. Back office → Core API (or a mass operation). +2. **Will a storefront read the result?** Orders and customers a storefront lists are created and changed on the + Shop API, so they stay one record in one store. +3. **Do you have the right token?** Core takes an access token pair. The Shop API takes a JWT minted for one tenant, + with a pair scoped to that tenant or unscoped. +4. **Is it a field edit or a rebuild?** `updateComponent` for one field; anything with `components` replaces the + whole set (see [What a partial write replaces](references/core-api.md#what-a-partial-write-replaces)). +5. **Should it go live?** Creating or updating an item doesn't publish it, and publishing is asynchronous. +6. **One-off or bulk?** Single mutations, or a mass operation ([[mass-operations]]). + +## The storefront API contract, for writes + +| Who writes | API | Runs | Examples | +| --------------------------------- | --------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- | +| A shopper, through the storefront | **Shop API** | Server actions, routes, payment webhooks | Cart, customer on the cart, `place`, orders, payments, customers, bookings, contracts, locks | +| The back office, scripts, imports | **Core API** | Scripts, jobs, admin tools behind login | Items, variants, components, publish, customers with hierarchies, media, webhooks | +| Tenant setup | **Legacy PIM** | Setup scripts | Pipelines, stock locations, VAT types, markets, subscription plans | +| Many items at once | Mass operations | Scripts | Imports, migrations | + +- **Core is never in the storefront's request path**: it is heavily rate limited and not meant for shopper traffic, + not even server-side behind a cache. The exceptions are webhook receivers and staff tools, which are back office. + The Shop API is edge-distributed and syncs to Core asynchronously, so the back office still sees every order. +- **The Shop API is server only.** Its CORS allows only Crystallize origins and localhost, so a browser call that + works in development fails on your own domain. The browser keeps the cart id in an httpOnly cookie. +- **Write an order in one store**, see [Orders: which store, which call](#orders-which-store-which-call). + +### Endpoints and tokens + +| API | Endpoint | Credential | +| --------------------------- | ----------------------------------------------------------------- | --------------------------------------------- | +| Core | `https://api.crystallize.com/@{tenant}` | Access token pair | +| Shop /cart | `https://shop-api.crystallize.com/{tenant}/cart` | JWT, `cart` scope | +| Shop /cart/admin | `https://shop-api.crystallize.com/{tenant}/cart/admin` | JWT, `cart` + `cart:admin` (promotions) | +| Shop /order | `https://shop-api.crystallize.com/{tenant}/order` | JWT, `order` | +| Shop /customer | `https://shop-api.crystallize.com/{tenant}/customer` | JWT, `customer` | +| Shop /subscription-contract | `https://shop-api.crystallize.com/{tenant}/subscription-contract` | JWT, `subscription-contract`, its own token | +| Shop /booking/admin | `https://shop-api.crystallize.com/{tenant}/booking/admin` | JWT, `booking:admin` | +| Shop /lock | `https://shop-api.crystallize.com/{tenant}/lock` | JWT, `lock` | +| PIM (legacy) | `https://pim.crystallize.com/graphql` | Access token pair; most calls take `tenantId` | ### Core API -``` -POST https://api.crystallize.com/@{tenant-identifier} -``` - -Note the `@` prefix before the tenant identifier. - ```bash curl -X POST 'https://api.crystallize.com/@your-tenant' \ -H 'Content-Type: application/json' \ @@ -99,16 +67,12 @@ curl -X POST 'https://api.crystallize.com/@your-tenant' \ -d '{"query": "mutation { ... }"}' ``` -Generate access tokens in the Crystallize App under Settings > Access Tokens. See the [permissions skill](../permissions/SKILL.md) for scoping tokens. +Note the `@` before the tenant identifier. Generate access tokens in the Crystallize App under Settings > Access +Tokens; see [[permissions]] for scoping them. ### Shop API -``` -POST https://shop-api.crystallize.com/{tenant-identifier}/cart -Authorization: Bearer YOUR_JWT_TOKEN -``` - -The `@` is optional on the Shop API. Get the JWT from your access token, with one scope per endpoint you call: +The `@` is optional on the Shop API. Mint the JWT on your server, with one scope per route you call: ```bash curl -X POST 'https://shop-api.crystallize.com/your-tenant/auth/token' \ @@ -118,51 +82,138 @@ curl -X POST 'https://shop-api.crystallize.com/your-tenant/auth/token' \ -d '{"scopes": ["cart", "order", "customer"], "expiresIn": 86400}' ``` -It answers `{ "success": true, "token": "..." }`. `scopes` is required and `expiresIn` is in seconds (one day by default). +It answers `{ "success": true, "token": "..." }`, sent as `Authorization: Bearer `. + +- **The access token must not be tenant-scoped**: the token endpoint checks it on `/@me`, which refuses tenant-scoped + tokens and plugin bearer tokens ([[permissions]]). +- `scopes` is required. `expiresIn` is in seconds: one day by default in the API, 12 hours in js-api-client. Cache + the JWT and refresh it before it expires; an expired one fails with `"exp" claim timestamp check failed`. +- The JWT is per tenant, not per shopper: it can write any customer's cart or order, so it never reaches the browser. +- Request a **separate token** for `/subscription-contract`: a token with every scope answered "Unexpected error" on + `create`. +- The Shop API reads products from the Catalogue with the request's credentials. On a tenant whose Catalogue requires + a token, send it (`X-Crystallize-Static-Auth-Token`, or the pair) on every `/cart` call that reads products. + +## Decision Tree + +``` +What do you need to do? +│ +├─ Shopper actions (storefront, account page, payment webhook): Shop API, server-side +│ ├─ Create or update the cart → /cart hydrate (send the WHOLE item list: it replaces) or addSkuItem +│ ├─ Customer on the cart → /cart setCustomer, or hydrate(customer: { identifier, isGuest: false }) +│ │ └─ B2B on behalf of a company → the organisation as the cart customer, the person in cart meta +│ ├─ Lock the cart before charging → /cart place (charge its total) +│ ├─ Order from the cart → /order createFromCart(id, { pipelines, paymentStatus, payments }), no fulfill +│ ├─ Order without a cart (POS, accepted quote, demo seed) → /order create +│ ├─ Payments → /order addPayments / setPayments (paymentStatus is set once, at creation) +│ ├─ Pipeline stage → /order addToStage (ids, not names), then setMeta +│ ├─ Order metadata → /order setMeta (not Core updateOrder) +│ ├─ Customer record → /customer customer(input), addAddress, setMeta +│ ├─ Bookings → /cart bookSkuItem, confirmCartBooking: see bookable-resources +│ ├─ Subscription contracts → one store per tenant: see subscriptions +│ └─ Idempotency guard (webhooks, one order per cart) → /lock acquire / release +│ +├─ Catalogue (back office, scripts): Core API +│ ├─ Create new item → createProduct / createDocument / createFolder +│ ├─ Update a field, or translate → updateComponent (per component, per language) +│ ├─ Rename → update*(input: { name }) (changes the path; the old one goes to history) +│ ├─ Add/update product variants → addProductVariant / updateProductVariant (send its components) +│ ├─ Publish/unpublish → publishItem / unpublishItem (asynchronous) +│ └─ Delete an item → deleteItem +│ +├─ Customers in the back office: Core API +│ ├─ A person or a company, with parents → createCustomer (type: individual | organization) +│ └─ Update → updateCustomer(identifier:) (lists you send replace the stored ones) +│ +├─ Orders nobody reads from the edge (imports into the back office) → Core registerOrder +│ +├─ Media (images, video) → see the media skill +│ +├─ Cache revalidation on publish → Core createWebhook(concern: "items") +│ +└─ Bulk operations → a mass operation: see the mass-operations skill +``` -**Call the Shop API from your server.** It allows browser calls only from Crystallize origins and localhost, so a browser call that works in development fails on your own domain. +## Orders: which store, which call + +Shop API orders and Core orders are meant to be one order in two stores, synced asynchronously. Shop `/order` is +the entry for volume: asynchronous, a FIFO queue, built for millions of orders, so an answer means accepted, not +stored. Core is synchronous but rate limited, so it suits imports and back-office edits. Where an order is **born** +decides what later writes do to it, so choose by who reads it: + +| The order | Create with | Change with | +| -------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------- | +| Comes from a storefront cart | Shop `/order` `createFromCart` | Shop `setMeta`, `addToStage`, `addPayments` | +| Has no cart but a storefront or the Shop API lists it (POS, accepted quote, demo seed) | Shop `/order` `create` | The same Shop calls | +| Nobody reads it from the edge (an import into the back office) | Core `registerOrder` | Core `updateOrder` | + +- **A Core edit of a Core-born order adds another copy to the Shop store** (a sync bug, reported): three + `updateOrder` calls left three Shop orders with one `coreId`, and a storefront summing the list counted the money + three times. Until it is fixed, readers group by `coreId`. A Core edit of a + Shop-born order overwrites it whole. +- **`createFromCart`**: the cart must be `placed`; pass `pipelines`, `paymentStatus` and `payments` in the input + rather than chaining calls, because the order is saved just after the answer. It copies the cart's `meta` (plus + `cartId`, `cartState`, `cartType`) into the order, and its input has no `meta`, so set meta on the cart first. + `additionalInformation: null` is refused ("Output validation error", naming no field): leave it out. It moves the cart to `ordered`, so never call `fulfill` + after it. The order id is the cart id. +- **`create`** takes `relatedOrderIds` (Core ids) for an order made from a quote. Whether it honours `createdAt` was + observed both ways (back-dated on one tenant, "now" on another): keep the intended date in meta (`orderedAt`) as + well. +- **The listing lags.** `orders(customerIdentifier:)` shows new orders after seconds to minutes, and a few never + appeared. Read by id, and key idempotency on your own meta or a `/lock`, never on the listing ([[query]]). +- There is no delete on the Shop API. Archive with `setMeta` and filter. + +Details, inputs and the full store table: [Shop API Order Mutations](references/shop-api-order-mutations.md). ## Common Workflow Patterns -### Create a product end-to-end +### Checkout (storefront, all server-side) -1. **Create the product** with shape, parent folder, VAT type and every required component -2. **Set variants** with SKU, pricing, stock, and images, in the same `createProduct` call: at least one is required -3. **Update components** (description, specs, media) -4. **Publish** the item +1. **Cart**: a server action calls `/cart` `hydrate` with the whole basket, the price context and the customer. + Check the SKUs against Discovery in parallel: an unknown SKU is dropped, or fails the call. +2. **Customer and meta**: `setCustomer` (for B2B, the organisation, with the person in cart meta), then `setMeta`. +3. **Place**: `place` locks the cart and hydrates it one last time. If order creation later fails, the shopper needs + a new cart. +4. **Payment**: create the provider session on the server from `place`'s `total` ([[payments]]). +5. **Order**: in the provider's webhook, verify, then `/order` `createFromCart` with `pipelines`, `paymentStatus` and + `payments` in the input. Bookings: once `cart.orderId` is set, `confirmCartBooking` again + ([[bookable-resources]]). +6. **Confirmation**: show the order `createFromCart` returned, or `order(id:)` with a retry; say that order history + can take a moment to update. -See [Core API Reference](references/core-api.md) for each mutation. +See [Shop API Cart Mutations](references/shop-api-mutations.md) and +[Shop API Order Mutations](references/shop-api-order-mutations.md). -### Update content on an existing item +### Create a product end-to-end (back office) -1. **Query the item** to confirm its ID and current state (use the query skill) -2. **Call `updateComponent`** for each field you need to change -3. **Publish** if the item should go live immediately +1. **Create the product** with shape, parent folder, VAT type, at least one variant, and every required component. + A numeric with a unit list must have a value on create, or the write fails + ([Unit-bound numerics](references/core-api.md#unit-bound-numerics)) +2. **Translate** with `updateComponent` per component and language, after the language version exists +3. **Publish**, then wait for the published version before relying on Discovery + ([Discovery Indexing](../query/references/discovery-indexing.md)) -Each `updateComponent` call targets a single component by `componentId`. You can update multiple components by sending multiple mutations. +### Update content on an existing item -### Checkout flow (storefront) +1. **Query the item** to confirm its ID and current state (use the query skill) +2. **Call `updateComponent`** for each field you change: it touches only that component +3. **Publish** if the change should go live -1. **Hydrate a cart** with product SKUs and quantities -2. **Add/remove items** as the customer shops -3. **Set customer info** and addresses -4. **Place the cart** to lock it for payment -5. **Create the order** from the placed cart +### Revalidate the storefront on publish -See [Shop API Cart Mutations](references/shop-api-mutations.md) for steps 1-4, and [Shop API Order Mutations](references/shop-api-order-mutations.md) for step 5. +Register a Core webhook with `concern: "items"`; `item` and `product` are accepted and never fire. Add a +`graphqlQuery` with `preserveDefaultPayload: true` when the receiver needs the path, and debug with +`webhookInvocations`. See [Webhooks](references/core-api.md#webhooks). ### Bulk import / mass operations -For creating many items at once, use a mass operation: see the [mass-operations skill](../mass-operations/SKILL.md), and the [content-model skill](../content-model/SKILL.md) for shapes and pieces. Mass operations follow a 4-phase ordering: - -1. Pieces (dependencies first) -2. Shapes -3. Topic maps -4. Items +Use a mass operation: see [[mass-operations]], and [[content-model]] for shapes and pieces. Order: pieces, shapes, +topic maps, items. ## Error Handling -The Core API uses union return types. Always include error fragments in your mutations: +The Core API uses union return types. Always include error fragments: ```graphql mutation { @@ -179,13 +230,15 @@ mutation { } ``` -The Shop API has no unions: a failure comes back in the standard GraphQL `errors` list. +The Shop API has no unions: a failure comes back in the standard GraphQL `errors` list. A missing, expired or +rejected token answers HTTP 401 with `{ "success": false, … }` and no `errors`. Neither API accepts an explicit +`null` for an optional field: leave the key out. -Common error types: `BasicError`, `UnauthorizedError`, `ItemNotFoundError`, `OrderDoesNotBelongToTenantError`. +Common Core error types: `BasicError`, `UnauthorizedError`, `ItemNotFoundError`, `OrderDoesNotBelongToTenantError`. ## Using the JS API Client -For JavaScript/TypeScript projects, use `@crystallize/js-api-client` instead of raw HTTP calls. It provides typed helpers for all mutations. See the [js-api-client skill](../js-api-client/SKILL.md) for setup and usage. +For JavaScript/TypeScript, use `@crystallize/js-api-client`; see [[js-api-client]]. ```typescript import { createClient } from "@crystallize/js-api-client"; @@ -195,10 +248,10 @@ const api = createClient({ accessTokenSecret: "...", }); -// Core API mutations (api.crystallize.com/@tenant) +// Core API mutations (back office only) const result = await api.nextPimApi(mutationString, variables); -// Shop API mutations: one caller per endpoint, the Shop API token is fetched for you +// Shop API mutations (server-side): one caller per route, the Shop API token is fetched for you await api.shopCartApi(cartMutation, variables); // /cart await api.shopOrderApi(orderMutation, variables); // /order (js-api-client 7.5+) ``` @@ -213,19 +266,24 @@ When generating mutations for the user, produce: 1. **GraphQL mutations** with clear variable placeholders (e.g., `"your-tenant-id"`, `"item-id"`) 2. **Variable definitions** when the mutation uses GraphQL variables 3. **Expected response shape** so the user knows what to look for +4. **Where it runs**: server action, webhook, script or admin tool, and which token it needs If the user is working in a JS/TS project, prefer generating code using `@crystallize/js-api-client` helpers. ## References -- [Core API Mutations](references/core-api.md) - Item CRUD, variants, components, customers, publish/unpublish, delete, media uploads -- [Media & Images](references/media.md) - Importing and uploading images and video, renditions, showcases, replacing and deleting -- [Shop API Cart Mutations](references/shop-api-mutations.md) - Cart hydration, item management, checkout flow, cart lifecycle -- [Shop API Order Mutations](references/shop-api-order-mutations.md) - Order creation (from cart or direct), payments, pipelines, metadata +- [Core API Mutations](references/core-api.md) - Item CRUD, variants, components, partial writes, unit-bound + numerics, id argument types, customers, pipelines, webhooks, publish/unpublish, delete +- [Shop API Cart Mutations](references/shop-api-mutations.md) - Cart hydration, item management, checkout flow, cart + lifecycle +- [Shop API Order Mutations](references/shop-api-order-mutations.md) - Order creation (from cart or direct), + payments, pipelines, metadata, the order store +- [Media & Images](references/media.md) - Moved to the [[media]] skill ## Related skills -[[query]] covers reads across the same APIs. For bulk writes that would otherwise hit rate limits, use -[[mass-operations]]. Vector ranking has its own Core API mutations — `upsertVocabulary`, `setItemTaste` -and `igniteDiscoApi` — documented in [[vector-ranking]]. Taking payment is in [[payments]], bookings in -[[bookable-resources]] and subscription contracts in [[subscriptions]]. +[[storefront]] owns the API contract and the request path per page type. [[query]] covers reads across the same APIs. +Importing images and video is [[media]]. For bulk writes that would otherwise hit rate limits, use +[[mass-operations]]. Vector ranking has its own Core mutations (`upsertVocabulary`, `setItemTaste`, +`igniteDiscoApi`) in [[vector-ranking]]. Taking payment is in [[payments]], bookings in [[bookable-resources]], +subscription contracts in [[subscriptions]], and prices and promotions in [[pricing]]. diff --git a/use-crystallize/skills/mutation/references/core-api.md b/use-crystallize/skills/mutation/references/core-api.md index 497947f..bf2b916 100644 --- a/use-crystallize/skills/mutation/references/core-api.md +++ b/use-crystallize/skills/mutation/references/core-api.md @@ -1,6 +1,8 @@ # Core API Mutations Reference -The Core API provides full read/write access to items, shapes, customers, orders, and configuration. +The Core API provides full read/write access to items, shapes, customers, orders, and configuration. It is for the +back office (seeds, imports, scheduled jobs, webhook receivers, admin tools behind staff login) and never for a +storefront's request path: shopper writes go to the Shop API ([[storefront]]). See [SKILL.md](../SKILL.md) for endpoint URLs and authentication headers. @@ -16,11 +18,17 @@ Two things decide the shape of every call on this page: - [Reading a result](#reading-a-result) - The union pattern every mutation uses - [Item Mutations](#item-mutations) - Create, publish, unpublish, delete, move +- [Id argument types](#id-argument-types) - Which mutation takes `ID!` and which `String!` +- [What a partial write replaces](#what-a-partial-write-replaces) - Updates that wipe what you did not send +- [Unit-bound numerics](#unit-bound-numerics) - Numerics with a unit list that block writes and publishing - [Component Updates](#component-updates) - Update individual fields on items and variants - [Product Variants](#product-variants) - SKUs, pricing, stock, images - [Customer Mutations](#customer-mutations) - Create, update, delete, hierarchies - [Order Mutations](#order-mutations) - Update orders and their metadata -- [Media & Images](#media--images) - Upload images for items and variants +- [Media & Images](#media--images) - Pointer to the media skill +- [Pipelines](#pipelines) - Stage traps +- [Webhooks](#webhooks) - Publish webhooks for cache revalidation +- [List quirks](#list-quirks) - Filters and limits that behave unexpectedly - [Flow Mutations](#flow-mutations) - Manage item workflows - [Vector Ranking Mutations](#vector-ranking-mutations) - Vocabularies, item taste, re-indexing - [Only in the legacy PIM API](#only-in-the-legacy-pim-api) - What Core does not have @@ -272,14 +280,17 @@ The item mutations are not patches. Sending a component list means "these are th the calls that look narrow have the widest blast radius. Every row below cost a build a round of re-imports. -| Call | What it does to everything you did not send | -| ---------------------------------------------------- | ------------------------------------------------------------------- | -| `updateProduct` / `updateDocument` with `components` | **Replaces the whole component set** for that language | -| `updateProduct` / `updateDocument` with only `name` | Leaves components alone — the safe way to rename | -| `updateProductVariant` **without** `components` | **Empties that variant's components** in that language | -| `updateComponent(itemId, language, component)` | Touches that one component only — use it for partial edits | -| `product/upsert` and friends in a mass operation | Replace all components, so send every one, not only the changed one | -| `setItemTaste` | Empties every **variant's** components on the draft (see below) | +| Call | What it does to everything you did not send | +| ---------------------------------------------------- | ----------------------------------------------------------------------- | +| `updateProduct` / `updateDocument` with `components` | **Replaces the whole component set**: translated components in that language, shared (non-translated) ones in **every** language | +| `updateProduct` / `updateDocument` with only `name` | Leaves components alone, but **changes the path** (see below) | +| `updateDocument(input: { topicIds })` alone | Keeps every component: topics can be rewritten on each run | +| `updateProductVariant` **without** `components` | **Empties that variant's components** in that language | +| `updateComponent(itemId, language, component)` | Touches that one component only — use it for partial edits | +| `updateComponent` with a `piece` | Replaces **every sub-component of the piece**: resend them all | +| `updateProductVariant(images)` in one language | Writes that language only: write variant images per language | +| `product/upsert` and friends in a mass operation | Replace all components, so send every one, not only the changed one | +| `setItemTaste` | Emptied every **variant's** components on one tenant (contested, below) | **Translating is where this bites.** Writing two fields in a second language with `updateProduct(language: "no", input: { components: [tagline, summary] })` fails with "Need to provide at @@ -287,21 +298,70 @@ least 1 related items for component brand" — and had it passed, it would have sent. Translate with `updateComponent` per component, and rename with `update*(input: { name })`. Shared (non-multilingual) components then keep showing in every language, untouched. -**`setItemTaste` has a side effect on variants.** After writing taste, the draft's variant components were +**Renaming changes the path.** `update*(input: { name })` regenerates the item's path from the new name (lower case, +æ → ae, ø → o, å → a, other diacritics stripped, every run of non-alphanumerics → `-`) and writes the old path to +`history`. To keep a legacy URL, pick a name that slugifies to the old slug and keep the display title in a +component, or add aliases; otherwise 301 from `history` ([[information-architecture]]). + +**Create the language version before translating components.** `updateComponent(language: "fi")` on an item with +no Finnish version fails with a bare `TypeError — Cannot read properties of undefined (reading 'shortcuts')`. +Write `update*(id, language: "fi", input: { name })` first, then the components, and not concurrently. + +**`createdAt` is accepted and ignored** on `CreateDocumentInput`, `UpdateDocumentInput` and `document/upsert`: the +item gets "now". Keep an original publish date in a component of its own. + +**`setItemTaste` has a side effect on variants — contested.** After writing taste, the draft's variant components were gone in every language while product components survived, and the publish that follows taste then published them empty. Order the pipeline: taste first, then (re)write variant components, then publish. -(Tools Universe. The same build first blamed a shape update and re-ran it, which changed nothing.) +(Tools Universe. The same build first blamed a shape update and re-ran it, which changed nothing. Four later tenants +did not see it: keep a read-back check rather than a rule; [[vector-ranking]].) -**A variant's content chunks may not publish at all.** On the same tenant a variant chunk sat in the +**A variant's content chunks may not publish at all — contested.** On the same tenant a variant chunk sat in the draft, but after `publishItem` the `current` version — and Discovery — had `chunks: []`, while a `singleLine` on the same variant and a numeric on another shape's variants published fine. If a variant -chunk disappears on publish, move that data to the product (one row per variant, with the SKU in it). +chunk disappears on publish, move that data to the product (one row per variant, with the SKU in it). Another +tenant published variant chunks fine and Discovery served them, so check on yours. **Creating an item validates its required components**, so create is not "create then fill": a document whose relation has `minItems: 1`, or a numeric with a unit list, fails `createDocument` with `ComponentContentValidationFailedError` unless those components are in the create input. Send everything on create. +## Unit-bound numerics + +A numeric component with a **unit list** is the most common write failure across builds (nine of them). The rule, in +one place: + +- **It fails create, `updateProduct` and an upsert's update for any product or variant that has no value**, even + when you didn't send the component and even when it isn't required: `No unit provided for numeric item component + runtime. Need to specify one of the following units: min`. +- **The empty value then blocks publishing** too. +- The unit is stored per value, so range filters in Discovery compare raw numbers across units ([[content-model]]). + +Workarounds that worked: + +| Workaround | Cost | +| --------------------------------------------------------- | --------------------------------------------------------------------------------- | +| Drop the `units` list from the component config | None for writes; the unit is still stored per value. Keep one unit per numeric | +| Create with `{ number: 0, unit }`, then `removeComponent` | Two writes per item | +| `updateComponent` per component instead of `update*` | One call per component | +| `publishItem(disableComponentValidation: true)` | Also hides shape-limit violations (relations over `max`), so check those yourself | + +## Id argument types + +The Core item mutations don't agree on the type of the id, and a shared `$id` variable with the wrong type fails +validation before anything runs (introspected 2026-11-12): + +| Mutation | Id argument | +| ------------------------------------------------- | --------------------------------------------- | +| `updateFolder`, `updateDocument`, `updateProduct` | `id: String!` | +| `updateComponent` | `itemId: ID` (or `sku: String` for a variant) | +| `publishItem`, `unpublishItem` | `id: ID!` | +| `deleteItem` | `itemId: ID!` | +| `removeComponent` | `itemId: ID!`, `componentId`, `sku` | +| `updateProductVariant` | `sku: String!` | +| `addVariantTopics` | `sku: String!`, `topicIds: [String!]!` | + --- ## Component Updates @@ -592,8 +652,21 @@ subscription contracts and customer-targeted price lists all name it. An address ``` `type` on a parent is `customer` or `customerGroup`, and a customer can have more than one — too many answers -`TooManyCustomerParentsProvidedError`. This is how a B2B contact belongs to its company, which in turn decides -whose orders it sees and which contract prices apply — see [[pricing]]. +`TooManyCustomerParentsProvidedError`. + +- **Customer groups are the folder concept, and they nest.** `CustomerType` is only `individual | organization`; + `createCustomerGroup` takes other groups as `parents`. A three-level tree works: groups → organisations + (`parents: [{ type: customerGroup }]`) → people (`parents: [{ type: customer }]`). `childCount` reads it back. + Use groups as folders, not as price-list targets ([[pricing]]). +- `customers(filter: { parent: { identifier, type: customer } })` returns **direct children only**. +- `customers(filter: { meta: { key, value } })` finds customers by one meta pair, and `metaProperty(key)` reads one + value. People often carry their department's keys too, so add a `kind` key or check `type`. +- **Meta presets** (`createMetaPreset`) apply to an entity through a **limitation keyed by the entity** (`customer`, + `order`, `order-item`, `subscription-contract`, `asset`) with the values `["no-limitations"]` for "all". An enum + value is stored as a **JSON array of option keys** (`["NOK"]`); anything else renders as nothing selected, and a + filter on such a key passes the array string. +- A PIM market's `customerIdentifiers` must name existing customers: create the customers first. This is how a B2B contact belongs to its company, which in turn decides + whose orders it sees and which contract prices apply — see [[pricing]]. ### Update and Delete @@ -656,8 +729,12 @@ mutation UpdateOrder($id: ID!, $input: UpdateOrderInput!) { `updateOrderMetadata(id:, key:, value:)` is narrower and does not touch the rest; `deleteOrderMetadata(id:, key:)` removes one. -`registerOrder(input: RegisterOrderInput!)` writes an order that did not come from a cart — a renewal invoice, a -POS sale, an import. It answers `{ id, createdAt }` before the order is stored, so a call right behind it can +`registerOrder(input: RegisterOrderInput!)` writes an order that did not come from a cart, **for orders nobody reads +from the edge** (an import into the back office, renewals on a tenant whose contracts live in Core). A POS sale, an +accepted quote or a demo seed that a storefront lists is a Shop API `create` instead (see the store table in +[Shop API Order Mutations](shop-api-order-mutations.md#the-order-store-and-core)). Quotes are `type: quote` with the +order made from them pointing back through `relatedOrderIds`. The order `reference` can't be set (Core gives each +order a random one), so keep your own order number in meta. It answers `{ id, createdAt }` (select it with `... on OrderConfirmation`, not `... on Order`) before the order is stored, so a call right behind it can get `OrderNotFoundError`. Before using it, read what it does to an order a storefront lists, in [shop-api-order-mutations.md](shop-api-order-mutations.md). @@ -665,22 +742,83 @@ get `OrderNotFoundError`. Before using it, read what it does to an order a store ## Media & Images -Media is registered in the tenant's library first, then referenced **by key** in components or on -variants. Six mutations cover it: - -| Mutation | Notes | -| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `copyRemoteAsset(sourceUrl:, type: image, targetFilename:, requestHeaders:)` | Crystallize fetches the URL. A **bulk task**: it returns `targetKey` before the file lands, and it registers the image for you | -| `generatePresignedUploadRequest(filename:, contentType:, type: MEDIA)` | A target to POST your own bytes to — the only path for video | -| `registerImage(imageKey:)` | Registers an uploaded key. Takes nothing else. Not needed after `copyRemoteAsset` | -| `registerImageRevision(imageKey:, revisionKey:)` | Repoints the library entry — Discovery follows only once the items using it are indexed again | -| `updateImage(key:, language:, input:)` | `altText`, `caption`, `focalPoint`, `meta`, `topicIds`, `showcase` — per language | -| `deleteImage(key:, force:)` | Refuses while any item version references it; `force: true` overrides | - -An import that follows these six in the obvious order still breaks in four different ways — keys whose -file never arrives, renditions that are not ready, revisions the storefront does not show yet, and -deletes that refuse. **See [Media & Images](media.md)** for the working pipeline, what to verify after an -import, and how to replace an image later. +Importing images and video (`copyRemoteAsset`, presigned uploads, `registerImage`, `registerImageRevision`, +`updateImage`, showcases, `deleteImage`) and getting them indexed has its own skill: see [[media]]. + +--- + +## Pipelines + +Pipelines and stages are **created** in the legacy PIM API (below); orders are moved between them on the Shop API +(`addToStage`) when a storefront reads the orders. + +- **`moveStage` fails and deletes the stage it was moving.** Stages can't be reordered: to change the order, delete + and recreate the (empty) pipeline. +- **`placeNewOrders: true` on a stage pulls every new order into that pipeline.** With it on the first stage of + three pipelines, every order landed in all three. For typed pipelines (orders, rentals, quotes), leave it off and + place each order explicitly. +- Read pipeline and stage ids with PIM `pipeline.getMany` at build time and write them into the storefront's data; + `edges` is `null` on a tenant with no pipelines. + +--- + +## Webhooks + +A storefront revalidates its Discovery cache on publish through a Core webhook. No other skill covers them. + +```graphql +mutation Hook($input: CreateWebhookInput!) { + createWebhook(input: $input) { + __typename + ... on Webhook { + id + } + ... on BasicError { + errorName + message + } + } +} +``` + +```json +{ + "input": { + "name": "Revalidate storefront", + "concern": "items", + "event": "publish", + "method": "POST", + "url": "https://shop.example.com/api/revalidate", + "headers": [{ "name": "x-secret", "value": "…" }], + "graphqlQuery": "query ($id: ID!, $language: String!) { item(id: $id, language: $language) { ... on Item { tree { path } } } }", + "graphqlQueryTarget": "next", + "preserveDefaultPayload": true + } +} +``` + +- **`concern` and `event` are plain strings and are not validated.** The concern that fires for item publishes is + `items` (plural): `item` and `product` are accepted and never fire, and so is `nope`. Check what fires with the + `webhookInvocations` query. +- Register one webhook per event: `publish` and `unpublish` (two builds did this, and both fired). +- The default payload has no path. Add a `graphqlQuery` (`graphqlQueryTarget` is `current` or `next`) with + `preserveDefaultPayload: true` when the receiver needs the path or the language. +- The receiver is a server route that verifies the request and clears the storefront's Discovery cache tag. Expect + Discovery to lag the webhook by seconds ([Discovery Indexing](../../query/references/discovery-indexing.md)). + Crystallize does not retry a failed delivery by itself; `retryWebhookInvocation(id:)` re-sends one. +- Set webhooks up once per tenant, in a setup script, not from the storefront. + +--- + +## List quirks + +- `first` is capped at 100 and asking for more returns 100 without a warning; `shapes(first:)` and `pieces(first:)` + above 100 fail instead. Paginate. +- `items(filter: { itemIds })` ignored the filter and returned the first 100 items by name: read `item(id:)` per + item. +- `items(filter: { shapeIdentifiers: [...] })` (plural) returned unrelated items with a correct `totalCount`; the + singular `shapeIdentifier` works and paginates. Query once per shape. +- The `orders` sort is `{ field: createdAt, direction: desc }`, not `{ createdAt: desc }`. --- diff --git a/use-crystallize/skills/mutation/references/media.md b/use-crystallize/skills/mutation/references/media.md index ce54407..0693a63 100644 --- a/use-crystallize/skills/mutation/references/media.md +++ b/use-crystallize/skills/mutation/references/media.md @@ -1,223 +1,11 @@ -# Images, video and media (Core API) +# Images, video and media -You have a list of image URLs from a supplier, or files on disk, and they need to end up on products. -There are **two ways in**, and the one you pick decides what can go wrong afterwards. +Media has its own skill now: see [[media]]. -> Signatures below were read from the live Core API schema on 2026-09-29. The behaviours — what arrives -> late, what fails silently — are attributed to the builds that hit them. +- Importing images (`copyRemoteAsset`, presigned uploads, `registerImage`), its limits and verification: + [media/references/import.md](../../media/references/import.md) +- Video upload and transcoding: [media/references/video.md](../../media/references/video.md) +- Showcases (hotspots): [media/references/showcases.md](../../media/references/showcases.md) +- Alt text, captions and topics per language, replacing and deleting: [media/SKILL.md](../../media/SKILL.md) -Rendering what you have imported is the other half, and it lives in [[responsive-images]]. - -| You have | Use | -| ---------------------------------------- | -------------------------------------------------------------- | -| A URL Crystallize can fetch | `copyRemoteAsset` — Crystallize pulls it, as a bulk task | -| Bytes you hold, or a URL it cannot fetch | `generatePresignedUploadRequest` → form POST → `registerImage` | -| Video, whatever the source | The upload path — `copyRemoteAsset` takes images only | - -## Copying from a supplier URL - -```graphql -mutation Copy($sourceUrl: String!, $filename: String) { - copyRemoteAsset(sourceUrl: $sourceUrl, type: image, targetFilename: $filename) { - __typename - ... on BulkTaskCopyRemoteAsset { - id - targetKey - status - } - ... on BasicError { - errorName - message - } - } -} -``` - -`type` is `RemoteAssetType`, and today its only value is **`image`**. `requestHeaders: [{ name, value }]` -is there for sources that will not serve a bare request. - -**It is a bulk task, so the key comes back before the file does.** `targetKey` is handed to you -immediately; the copy happens afterwards. Four consequences, all found the hard way: - -- **A failed copy only shows on the task.** `bulkTask(id:) { ... on BulkTask { status info } }` ends in - `error`, with the reason in `info.error`. The source has to answer 2xx with an uncompressed body (a - `content-encoding` other than `identity` is refused), a `content-length` within the upload limit, and a - `content-type` of exactly `image/jpeg`, `jpg`, `png`, `webp`, `tiff`, `tif` or `avif`, which is how a - CDN that serves a browser can still fail here. - -- **Do not call `registerImage` afterwards.** `copyRemoteAsset` already registers the image, and the - second call fails. (Tools Universe.) -- **`updateImage` on a fresh key answers `ImageNotFoundError` for a while** — WebP sources seemed - slowest. Retry a "not found" after a delay, or wait for **every** copy task rather than the last few - you happen to hold (`bulkTask(id:)` until it leaves `pending`/`started`). (Tools Universe.) -- **A key can be registered whose file never arrives, with no error on the mutation.** Two builds, two - suppliers: 91 WebP sources (ZF, Brembo) got a key and a library entry while the file behind it 404s - (Car Parts Universe), and every image from one fashion brand did the same because that CDN serves a - normal browser but not Crystallize's fetcher (Fashion Universe). The library shows broken tiles, items - show broken images, and nothing reports it unless you read the tasks. - -So after the copy tasks finish, **HEAD-check the keys** — all of them if the import is small, a sample if -it is not. For the ones that 404: try `requestHeaders` first if you suspect the CDN is refusing the -fetch, and otherwise download the file yourself, convert it if it needs converting (both builds went to -JPEG), and take the upload path below. - -WebP sources do work — some manufacturers publish nothing else — and PNG transparency is preserved. -(Tools Universe.) - -## Uploading bytes yourself - -Three steps: ask for a presigned target, POST the file to it, register what landed. - -```graphql -mutation Upload($filename: String!, $contentType: String!) { - generatePresignedUploadRequest(filename: $filename, contentType: $contentType, type: MEDIA) { - __typename - ... on PresignedUploadRequest { - url - fields { - name - value - } - maxSize - lifetime - } - ... on BasicError { - errorName - message - } - } -} -``` - -`type` is `FileUploadType`: **`MEDIA`** for images and video, `STATIC` for files, `MASS_OPERATIONS` for -an operations file. Build a multipart form from `fields` **in the order given**, append the file last, -and POST it to `url` — `lifetime` is how long that target stays valid and `maxSize` caps the upload. -Then: - -```graphql -mutation Register($imageKey: String!) { - registerImage(imageKey: $imageKey) { - __typename - ... on Image { - key - url - width - height - mimeType - } - ... on BasicError { - errorName - message - } - } -} -``` - -Unlike the copy path, this one **does** need `registerImage`, right after the POST: it makes the key usable -at once. The upload also registers itself in the background, so a late call can fail because the image -already exists, which is harmless. In JS, `createBinaryFileManager(client).uploadImage(path)` does all three -steps, and needs `tenantId` in the client config. - -### Video - -The upload path is the only way in for video, since `copyRemoteAsset` is images only: download the file, -`generatePresignedUploadRequest(contentType: "video/mp4" | "video/quicktime", type: MEDIA)`, POST the -form, then write `{ key, title }` into a `videos` component or a variant's videos. There is no -`registerVideo` step — the upload registers the video, and it is transcoded to HLS and DASH -(`playlists`) within about a minute. MP4 and MOV upload as they are; an HLS-only source has to be -remuxed first (`ffmpeg -i x.m3u8 -c copy`). A `videos` component's `max` is enforced on create -(`Cannot provide more than 2 videos for component hero-video`). (Fashion Universe.) - -Files work the same way: upload with `type: STATIC`, then write `{ key, title }` into a `files` component. -There is no register step for them either. - -## Renditions arrive later, and the storefront has to cope - -`Image.variants` is the generated ladder that [[responsive-images]] builds a `srcset` from, and it is -produced in a queue. After roughly 4,600 copies in one import, `image(key)` answered -`width: null, variants: null` for the later ones for a long while, and Discovery indexed those items with -`variants: []`. (Fashion Universe.) - -Two things follow: a storefront must fall back to the original `url` when `variants` is empty, and the -items need **publishing and re-indexing again** once the renditions exist, or Discovery keeps serving the -empty list it indexed. - -## Replacing an image - -`registerImageRevision(imageKey:, revisionKey:)` points the library entry at a new file — Core -`image(key)` returns the new `url` and `size`, and the ladder rebuilds in about 25 seconds. - -`revisionKey` is a file you have just uploaded (`generatePresignedUploadRequest` → POST). Call it right after -the POST and skip `registerImage`: once the upload has registered itself as an image, the revision is refused. - -**It reaches the read APIs at different times.** The Catalogue API serves the latest revision at once. -Discovery stores the file with each indexed document, so every item using the image keeps the original file -and renditions until that item is indexed again, and a revision indexes nothing by itself. - -So to replace an image in practice: register the revision, wait for the ladder, then **republish the items -that use it** (or re-run `igniteDiscoApi`). Uploading the new file as a **new** image -(`generatePresignedUploadRequest` → POST → `registerImage`) and writing the new key onto the items works too, -and needs the same publish. - -## Metadata, topics and showcases - -```graphql -mutation Annotate($key: String!, $language: String!, $input: UpdateImageInput!) { - updateImage(key: $key, language: $language, input: $input) { - __typename - ... on Image { - key - } - ... on BasicError { - errorName - message - } - } -} -``` - -`UpdateImageInput` carries `altText`, `caption`, `focalPoint`, `meta`, `topicIds` and `showcase`. Note -the required `language`: an image's topics and alt text are **per language**, so tagging an image in one -language leaves the others untagged. - -**Showcases are hotspots on the image — the whole "shop the look" feature, and in no skill until now.** -Core takes `showcase: [{ hotspot: { x, y }, itemIds, skus, meta }]`, several per image, on `ImageInput` -(the `images` component and variant images) and on `updateImage`, and `skus` is required, so send `[]` for -a showcase of items only. `registerImage` takes only the key. Discovery exposes them on the image as -**`showcases`** — plural, type `Showcase`, with `hotspot` as a `Hash` `{ x, y }` plus `items` (the -related documents), `variants` and `meta`. Verified against a live tenant; the naming difference between -input (`showcase`) and output (`showcases`) is easy to trip over. (Fashion Universe.) - -## Deleting - -```graphql -mutation Delete($key: String!) { - deleteImage(key: $key, force: true) { - __typename - ... on DeleteCount { - removed - } - ... on AssetInUseError { - key - referrerCount - } - } -} -``` - -`deleteImage` refuses an image that **any** item version references, including old ones — -`AssetInUseError … referenced in 3 places` came back for an image every current draft and published -version had already moved away from. `force: true` removes it anyway. Check the current versions -yourself before forcing. (Car Parts Universe.) - -## Failure modes - -| Symptom | Cause | Fix | -| ----------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | -| Broken tiles in the library, broken images on items | `copyRemoteAsset` gave a key but the copy never landed | Read the task's `info.error`, HEAD-check the keys; re-import those with `requestHeaders`, or upload | -| `ImageNotFoundError` from `updateImage` right after a copy | The key exists before the file does | Wait for every copy task, and retry "not found" | -| `registerImage` fails on a copied key | `copyRemoteAsset` already registered it | Don't register a copied image | -| `variants: []` in Discovery, `width: null` in Core | Renditions are still queued | Fall back to `url`; publish and re-index once they exist | -| A replaced image still shows the old file on the storefront | Discovery keeps the file it indexed | Republish the items that use the image | -| `AssetInUseError` on an image nothing current uses | Old item versions still reference it | `deleteImage(force: true)` after checking current versions | -| `copyRemoteAsset` rejects a video URL | `RemoteAssetType` is `image` only | Use the presigned upload path | +Rendering images (srcset, sizes, formats) is [[responsive-images]]. diff --git a/use-crystallize/skills/mutation/references/shop-api-mutations.md b/use-crystallize/skills/mutation/references/shop-api-mutations.md index bc8fd03..d3f1451 100644 --- a/use-crystallize/skills/mutation/references/shop-api-mutations.md +++ b/use-crystallize/skills/mutation/references/shop-api-mutations.md @@ -524,7 +524,8 @@ mutation { ## Complete Checkout Flow -The full checkout flow spans the Core API, `/cart` endpoint, and `/order` endpoint: +The full checkout flow spans the `/cart` and `/order` endpoints (and `/customer` when you keep customer records), +all called from your server. No step uses the Core API: ``` 0. (Optional) Create Customer → POST /customer — customer(input:) @@ -542,7 +543,8 @@ separate fulfill step. Customers can be created **before** checkout, on the Shop API or the [Core API](core-api.md), or **inline** during hydration: - **Shop API `/customer`** (from a storefront): `customer(input: { identifier, ... })` creates or updates the customer, and `addAddress`, `setAddress`, `removeAddress` and `setMeta` edit it. The token needs the `customer` scope. -- **Core API** (persistent customer records, from a back office): Use `createCustomer` with `type: individual` or `type: organization`. The customer's `identifier` (typically email) can then be passed to `hydrate`. +- **Core API** (from a back office or a seed, never from the storefront's request path): `createCustomer` with `type: individual` or `type: organization`, and `parents` for a company hierarchy. The customer's `identifier` (typically email) can then be passed to `hydrate`. +- **B2B, ordering on behalf of a company**: put the **organisation's** identifier on the cart customer, so the order belongs to the company and `orders(customerIdentifier: "")` lists it, and put the person who ordered in cart meta (`orderedBy`). The Shop API has no "orders of a parent" query. - **Inline during hydrate** (recommended for checkout): Pass `customer: { identifier, firstName, lastName, isGuest }` directly in the hydrate input. This associates the customer with the cart without requiring a separate API call. For guest checkout, set `isGuest: true` in the hydrate customer input. diff --git a/use-crystallize/skills/mutation/references/shop-api-order-mutations.md b/use-crystallize/skills/mutation/references/shop-api-order-mutations.md index 0579985..37b2e3f 100644 --- a/use-crystallize/skills/mutation/references/shop-api-order-mutations.md +++ b/use-crystallize/skills/mutation/references/shop-api-order-mutations.md @@ -8,7 +8,15 @@ See [SKILL.md](../SKILL.md) for endpoint URLs and authentication headers. This f Convert a placed cart into an order. The cart must be in "placed" state first (via `place` mutation on the `/cart` endpoint). Any other state fails, so a second call on the same cart fails too: the first one left it `ordered`. -**The order is saved just after the answer.** An `addPayments` or `addToStage` sent right behind `createFromCart` can miss it, and an immediate read can lag. Pass `paymentStatus`, `payments` and `pipelines` in this input instead of chaining calls. +**The order is saved just after the answer.** An `addPayments`, `addToStage` or `setMeta` sent right behind `createFromCart` can fail with "Order … not found", and an immediate `order(id:)` read can too. Pass `paymentStatus`, `payments` and `pipelines` in this input instead of chaining calls, and show the confirmation page from the order this mutation returns. + +Run it on your server, normally in the payment provider's webhook after verifying the payment ([[payments]]). After `place` the cart is locked, so if this call fails the shopper needs a new cart. + +- **Cart meta becomes order meta.** `OrderFromCartInput` has no `meta`: set it on the cart (`hydrate(input: { meta })` or `setMeta`) before `place`. The order gets the cart's meta plus `cartId`, `cartState` and `cartType`, and keeps `customer.meta`. +- **The order belongs to the cart's customer.** For B2B, put the organisation's identifier on the cart so `orders(customerIdentifier: "")` lists the company's orders, and the ordering person in meta. +- `additionalInformation: null` is refused ("Output validation error"): leave the field out. +- `coreId` is `null` in the answer; the Core copy arrived within about 20 s with the meta and the stage. +- `appliedPromotions` and `reference` came back `null` in the answer even when the cart had a promotion. ```graphql mutation CreateOrderFromCart($id: UUID!, $input: OrderFromCartInput) { @@ -68,7 +76,11 @@ Variables: ## Create Order Directly -Create an order without a cart (e.g., for POS, imports, or manual order creation). +Create an order without a cart: a POS sale, an accepted quote, a manual order, or a demo seed. **Use this, not Core `registerOrder`, whenever a storefront or the Shop API lists the order**; `registerOrder` is for imports nobody reads from the edge (see [The Order Store and Core](#the-order-store-and-core)). + +- `relatedOrderIds` takes **Core** ids (`coreId`): an order made from an accepted quote points back at the quote. +- **`createdAt` was observed both ways**: honoured on one tenant, ignored ("now") on another. For back-dated seeds, keep the intended date in meta (`orderedAt`) as well and read it from there. +- Seeds: create orders one at a time or at low concurrency, then check by id. The per-customer listing lags and can stay incomplete (47 created, 29 listed), so never use it to decide what still needs creating; key on a meta `seedRef` and keep a ledger. ```graphql mutation CreateOrder($input: OrderInput!) { @@ -172,7 +184,7 @@ Variables: | `relatedOrderIds` | `[String]` | No | Related **Core** order ids (`coreId`), for returns and replacements. A Shop id fails the sync to Core | | `additionalInformation` | `String` | No | Free-text additional info | | `meta` | `[KeyValueInput]` | No | Arbitrary key-value metadata | -| `createdAt` | `DateTime` | No | Override creation timestamp | +| `createdAt` | `DateTime` | No | Override creation timestamp. Ignored on some tenants: keep the date in meta too | ### OrderItemInput @@ -546,8 +558,15 @@ there is nothing left to link: do not follow it with `fulfill`. ## The Order Store and Core -Shop API orders and Core orders are the same orders in two stores, synced asynchronously in both -directions. Where an order was born decides what a Core write does to it. +Shop API orders and Core orders are meant to be one order in two stores, synced asynchronously in both +directions. The two entries do different jobs: + +- **Shop `/order` is the entry for volume.** It is asynchronous: it puts orders on a FIFO queue and writes them to + the database after it answers, and it is built to take millions of orders. An answer means accepted, not stored, + so read the order back by id, with a retry. +- **Core is synchronous but rate limited.** Use it for imports and back-office edits, not for storefront orders. + +Where an order was born decides what a Core write does to it today. **Shop → Core.** An order created here gets its `coreId` in about ten seconds, and `addToStage` moves the Core stage with it. (`coreId` can still read `null` in the answer of a Shop `create` even after @@ -556,7 +575,7 @@ the order has reached Core, so don't use it as a sync flag.) | Born in | Core `updateOrder` | Core `deleteOrder` | | ------------------------------------- | ------------------------------------------------------ | ------------------------------ | | Shop API (`create`, `createFromCart`) | Rewrites the same Shop order with Core's whole version | Removes it from the Shop store | -| Core (`registerOrder`) | **Adds another copy** to the Shop store | Removes only the latest copy | +| Core (`registerOrder`) | **Adds another copy** to the Shop store (a sync bug) | Removes only the latest copy | **A stage moved in Core or the App does not reach the Shop store, and the next Shop write puts it back.** Every `/order` mutation sends the whole Shop order to Core, and Core makes the order's pipelines match it: a @@ -566,16 +585,18 @@ stage may have moved, read the stages from Core and copy them over with `addToSt **Seed demo orders with the Shop API, not with `registerOrder`**, if a storefront is going to list them: orders registered in Core showed up in the Shop store only sometimes. -**Editing an order born in Core adds another copy of it to the Shop store.** Such an order has no Shop id -to come back to, so every change arrives as a new order. Three `updateOrder` calls on one seeded order left -three orders in `orders(customerIdentifier:)` — new Shop ids, the same `coreId`, different `updatedAt`. A +**Editing an order born in Core adds another copy of it to the Shop store.** This is a sync bug, reported to the +platform team: Core and Shop `/order` should work on one order. Until it is fixed, plan for it. Such an order has +no Shop id to come back to, so every change arrives as a new order. Three `updateOrder` calls on one seeded order +left three orders in `orders(customerIdentifier:)` — new Shop ids, the same `coreId`, different `updatedAt` — and +on a sandbox tenant (2026-11-17) one `registerOrder` plus three `updateOrder` calls left four. A storefront that sums that list counts the same money several times over; the Lab Universe build read a department budget of NOK 1,249,299 instead of 411,775. So: - **Change orders through the Shop API** (`setMeta`, `addToStage`, `setPayments`) whenever a storefront reads them. On an order born here, a Core edit also overwrites whatever the Shop wrote just before it. - If an order born in Core must be edited there anyway, have the reader **group by `coreId` and keep the - most recently updated copy**. + most recently updated copy**. This is a workaround for the bug, not how the stores are meant to work. **There is no delete on the Shop API.** Cancelled or mistaken orders stay in the list until `deleteOrder` on the Core order removes them. Otherwise archive them with `setMeta` (`archived: true`) and filter them diff --git a/use-crystallize/skills/payments/SKILL.md b/use-crystallize/skills/payments/SKILL.md index 6f926e9..2482b3f 100644 --- a/use-crystallize/skills/payments/SKILL.md +++ b/use-crystallize/skills/payments/SKILL.md @@ -6,13 +6,14 @@ description: > session from the placed cart, verifying webhooks, creating exactly one order per cart, recording payments, and capture, refund and cancellation from fulfilment pipelines. Use when adding a payment provider or method to a Crystallize storefront, building or fixing checkout payment or a payment webhook, stopping duplicate or unpaid - orders, a cart changed after paying (two tabs, back button), capturing on shipment or refunding. Trigger on - "payment", "payment gateway", "payment webhook", "capture", "refund", "place cart", "lock the cart", - "duplicate order", "paymentStatus", "addPayments", "setPayments", "createFromCart", "Stripe", "Adyen", "Klarna", - "Qliro", "Dintero", "Vipps", "MobilePay", "Mollie", "Montonio", "QuickPay", "Two", "Razorpay", "B2B invoice". + orders, a cart changed after paying (two tabs, back button), capturing on shipment or refunding, or a checkout + started by an AI agent. Trigger on "payment", "payment gateway", "payment webhook", "capture", "refund", + "place cart", "lock the cart", "duplicate order", "paymentStatus", "addPayments", "setPayments", + "createFromCart", "Stripe", "Adyen", "Klarna", "Qliro", "Dintero", "Vipps", "MobilePay", "Mollie", "Montonio", + "QuickPay", "Two", "Razorpay", "B2B invoice", "agent checkout", "MCP checkout", "cart hand-off". metadata: author: Crystallize - version: "2.0" + version: "2.1" --- # Crystallize Payments @@ -44,7 +45,7 @@ only a server-to-server notification you have verified (most gateways sign them) fetched from the gateway yourself proves a payment. On Crystallize that becomes: ```text -Storefront hydrate → set customer, shipping, selections everything the order needs, on the cart +Server hydrate → set customer, shipping, selections everything the order needs, on the cart Shop /cart place cart frozen; place's total = what you charge Server create provider session / intent amount from place, cart id as the reference Browser pay provider's hosted page or embedded component @@ -144,7 +145,8 @@ The same skeleton for every provider: unless it is protected by a signed token. 3. **Decide by the provider's status** (paid, authorized, pending, failed — the reference has the table). Pending and failed create nothing. -4. **`createOrderOnce`**: reads the cart, creates the Core customer if needed, and calls `createFromCart` once. +4. **`createOrderOnce`**: reads the cart, creates the Shop customer (synced to Core) if needed, and calls + `createFromCart` once. Deliveries that collide in the same instant are a trade-off: see [Serialising order writes](#serialising-order-writes-optional). 5. **Answer fast.** 2xx when done or deliberately ignored; **5xx when it failed on your side**, so the @@ -238,7 +240,7 @@ import { createShopLock } from "@crystallize/js-api-client"; const lock = createShopLock(api); export async function withCartLock(cartId: string, work: () => Promise): Promise { - const key = `order:${cartId}`; + const key = `order-${cartId}`; // lock keys keep only a-z, 0-9 and -: a colon would be dropped if (!(await lock.acquire(key, 60))) throw new RetryLater(`cart ${cartId} is being processed`); // → 5xx, retry try { return await work(); @@ -330,6 +332,11 @@ deal with both traps below; before any other Shop write to the order (`setMeta`, payments read `provider: "custom"`, and writing them back would put that on the Core record too. The helpers keep the real name in `meta` as `gateway` and restore it. +**These Core reads are webhook code, not page code**: fine in a payment or stage webhook, never in a storefront +request (the Pay route and return page use only the Shop API). To keep Core off the payment path entirely, move +stages only through Shop `addToStage` (not the App), so `syncStages` has nothing to copy, and read the provider, +`transactionId` and `state` from Shop `order(id)` (the cart id), its payment records and `meta`. + ## Capture on shipment, from fulfilment pipelines Payment is the end of checkout and the start of the order's life. Put orders in a @@ -409,6 +416,22 @@ Unlike a provider's webhook, a 5xx here retries nothing: subscribe a second webh **Invocation failed**, to alert someone, or have a scheduled job re-check orders in the stage whose record is still `authorized`. Retrying is safe: `capture` is idempotent in every reference. +## Checkout started by an agent + +An AI agent (an MCP server, an on-site assistant) builds the basket through tools, with no browser and no cookies. +Two stores settled on this (see [[agentic-commerce]]): + +- **The cart id is the session.** The first cart tool `hydrate`s without an id and returns the `cartId`; later calls + pass it back. Keep no server state; the shopper comes from the call's own credentials (an OAuth token). +- **The browser pays.** The tool returns a URL on your domain with the `cartId` and, when signed in, a short-lived + signed token for that shopper and cart (`/mcp/cart?id=…&as=`). The route checks the cart is still in state + `cart` and the token names it, sets the cart cookie and the session, and redirects to the cart page. Then the + ordinary flow runs: `place`, the provider session, the webhook. An unsigned `as=` lets anyone shop as anyone. +- **An agent never pays.** A `checkout` tool that orders by itself is marked destructive (`destructiveHint: true`) and + limited to methods that move no money at once, such as invoice or a quote for signed-in trade buyers. It runs the + server flow (`setCustomer`, cart `setMeta`, `place`, `createFromCart` with `paymentStatus: "unpaid"`), records later + payments with `addPayments`, and confirms bookings after the order, as in [[bookable-resources]]. + ## Choosing a provider Crystallize works with any gateway; these have a reference here: diff --git a/use-crystallize/skills/payments/references/crystallize-payments-lib.md b/use-crystallize/skills/payments/references/crystallize-payments-lib.md index 1823123..ecc4fc9 100644 --- a/use-crystallize/skills/payments/references/crystallize-payments-lib.md +++ b/use-crystallize/skills/payments/references/crystallize-payments-lib.md @@ -15,6 +15,7 @@ import { JSApiClientCallError, } from "@crystallize/js-api-client"; +// Server only. The pair mints the Shop API token: a pair scoped to this tenant is enough (permissions skill). export const api = createClient( { tenantIdentifier: process.env.CRYSTALLIZE_TENANT_IDENTIFIER!, @@ -156,6 +157,8 @@ export const readOrder = (id: string) => orders.fetch(id, ORDER).catc * Each call here is a Shop write too, and no mutation sets the whole list at once. On an order in several pipelines, * the ones not synced yet move back until their turn comes, and every move fires the stage webhook, so that handler * must stay idempotent. + * + * It reads Core, so call it from webhooks only (payment provider, stage change), never from a storefront request. */ export async function syncStages(order: OrderRead) { if (!order.coreId) return; // Core has not answered yet: nothing can have moved diff --git a/use-crystallize/skills/payments/references/two.md b/use-crystallize/skills/payments/references/two.md index 91d06ce..a39a8d4 100644 --- a/use-crystallize/skills/payments/references/two.md +++ b/use-crystallize/skills/payments/references/two.md @@ -374,7 +374,7 @@ export async function chooseCompany(cartId: string, lookupId: string, person: Re const [street, postalCode, city, country] = [a?.street_address, a?.postal_code, a?.city, a?.country]; await carts.setCustomer(cartId, { ...person, // firstName, lastName, email, phone: Two requires all four - isGuest: false, // true skips the Core customer + isGuest: false, // true skips the Shop customer (which is synced to Core) identifier: person.email, // or your signed-in customer's identifier type: "organization", companyName: co.name, diff --git a/use-crystallize/skills/permissions/SKILL.md b/use-crystallize/skills/permissions/SKILL.md index cba82d0..37d13c0 100644 --- a/use-crystallize/skills/permissions/SKILL.md +++ b/use-crystallize/skills/permissions/SKILL.md @@ -3,7 +3,7 @@ name: permissions description: Manage user roles, permissions, and access control in Crystallize. Use when configuring field-level permissions (read-only or hidden fields for specific roles), managing user roles and team access, creating or updating custom roles (createRole, updateRole, setUserRole, createInviteToken), restricting a role to specific folders, languages or stock locations, creating access tokens and scoping them to a tenant, deciding which user and role an integration runs as, debugging a Forbidden error on the Core API, controlling who can view/edit specific content areas or component fields, designing role-based access for multi-team tenants, or planning permission strategies for content workflows. For wiring credentials and Shop API token scopes into client code use js-api-client. metadata: author: Crystallize - version: "2.0" + version: "2.1" --- # Crystallize Permissions & Access Control @@ -187,7 +187,8 @@ Every access token belongs to a user. There is no tenant-level or service token, - **Secret shown once** — `secret` is only returned at creation - **Limit** — 50 tokens per user - **Tenant scope** — `tenantId` (the id, not the identifier) limits a token to one tenant the user belongs to. Without it, the token reaches every tenant the user is on -- **A tenant-scoped token is refused on `/@me`** with a 403. It cannot call the Me API, and it cannot fetch a Shop API token, which goes through `/@me` too +- **A tenant-scoped token is refused on `/@me`** with a 403, so it cannot call the Me API +- **Shop API tokens are per tenant.** A token pair that isn't tenant-scoped mints a Shop API JWT for any tenant its user belongs to; a tenant-scoped pair mints one for its own tenant only. For any other tenant `/auth/token` answers 400 "User is not a member of tenant X", even when the user is a member, so check the token's scope first - **SSO** — On a tenant that enforces SAML login, a token with no tenant scope only works for a Tenant Admin. Other users need a tenant-scoped token ```graphql @@ -205,7 +206,17 @@ mutation CreateToken($tenantId: ID) { } ``` -**Integrations run as a user.** Give each one a dedicated user, invited with a custom role that holds only what the integration needs, and sign in as that user to create the token. A person's token ties the integration to that person's role and account. Scope the token to the tenant, unless the integration also needs Shop API tokens: then leave it unscoped, and keep that user on a single tenant. +**Integrations run as a user.** Give each one a dedicated user, invited with a custom role that holds only what the integration needs, and sign in as that user to create the token. A person's token ties the integration to that person's role and account. Scope the token to the tenant. A tenant-scoped pair also mints Shop API tokens for that tenant, so a storefront needs no unscoped token. + +### Storefront credentials + +A storefront is such an integration. Its server holds the credentials, and the browser holds none of them: + +- **Shop API**: a token pair on a dedicated user, scoped to the store's tenant, used only on the server to mint the Shop API JWT from `POST https://shop-api.crystallize.com/{tenant}/auth/token`. The JWT is per tenant, not per shopper, so it never goes to the browser. +- **Discovery and Catalogue**: no credential when open, or the static token when **Settings → API access** restricts them. They are two separate settings: Discovery follows the **Search & Discovery** entry (shared with the Search API), Catalogue its own entry. Discovery is open by default, and an open Discovery serves everything it indexes to anyone, price variants and price lists included. Keep confidential terms out of it. +- **Core**: never in the storefront's request path. Seeding, imports and webhook receivers use their own tenant-scoped pair. + +The API each storefront task uses is in [[storefront]]. Where these credentials come from on a new tenant is in [[agent-tenants]] ([tenant setup](../agent-tenants/references/tenant-setup.md#storefront-credentials)). ### Other credentials @@ -215,8 +226,8 @@ Only the Core and PIM APIs check role permissions. | --------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | Core, PIM | Access token pair or session | Yes | | Catalogue | **Settings → API access**: open, static token or access token pair | No: with the pair, any role on the tenant passes | -| Discovery | Static token, when the tenant protects it | No | -| Shop | Bearer token from `/auth/token`, requested with a session or an unscoped pair and a list of scopes | No | +| Discovery | **Settings → API access**, the Search & Discovery entry (shared with Search): static token | No | +| Shop | Bearer token from `/auth/token`, requested with a session or a token pair and a list of scopes | No | See [js-api-client](../js-api-client/SKILL.md) for wiring these credentials. @@ -284,7 +295,7 @@ Solution: 2. Invite a dedicated user with this role, and sign in as them to generate a token scoped to the tenant 3. Use this token in the job's API calls — even if compromised, it can't write data -A storefront needs none of this: the Catalogue and Discovery APIs are read-only and do not use roles. Protect them with **Settings → API access** if they should not be public. +A storefront needs none of this: the Catalogue and Discovery APIs are read-only and do not use roles. Protect them with **Settings → API access** if they should not be public. What it does need is an unscoped pair for Shop API tokens ([Storefront credentials](#storefront-credentials)). ## References diff --git a/use-crystallize/skills/plugins/SKILL.md b/use-crystallize/skills/plugins/SKILL.md index 0f12877..56e1e1a 100644 --- a/use-crystallize/skills/plugins/SKILL.md +++ b/use-crystallize/skills/plugins/SKILL.md @@ -9,10 +9,11 @@ description: > payload and Backend Token, encrypting installation secrets, talking to the App from the iframe with `@crystallize/plugin-signal`, or testing a plugin locally with `issuePluginPayload`. Also use when the user mentions Crystallize plugins, plugin revisions, plugin store, marketplace, plugin - installations, plugin payload, or plugin permissions. + installations, plugin payload, or plugin permissions, or a legacy Crystallize App (PIM `app.create`, + `crystallizeSignature`, an iframe view in the App). metadata: author: Crystallize - version: "1.0" + version: "1.1" --- # Crystallize Plugins @@ -21,6 +22,8 @@ A Crystallize Plugin is a **vendor-hosted application** that extends the Crystal The full normative contract — entities, fields, JWE/JWT specs, request shapes, sequence diagrams — lives in [references/plugin-contract.md](references/plugin-contract.md). This SKILL.md is the **builder's guide**: how to ship a plugin end-to-end. Read the contract when a field, security guarantee, or wire format is in question. +**Legacy Apps are not plugins.** A tenant can also frame a page as an App, registered with PIM `app.create`. An App gets only `?crystallizeSignature=` (tenant and user, no item id or language), so **use a plugin when the view needs the item**. Apps, their signature, `frame-ancestors` and custom views (`tenant.setPreferences(frontends)`) are in [references/legacy-apps.md](references/legacy-apps.md). + ## Consultation Approach Before writing code, get the lay of the land: @@ -479,6 +482,7 @@ The [Crystallize plugins monorepo](https://github.com/CrystallizeAPI/plugins) sh ## References - [Plugin Contract](references/plugin-contract.md) — normative spec: entities, fields, JWE/JWT formats, sequence diagrams, entity context, App channel, security model, V1 vs V2 behavior. +- [Legacy Apps](references/legacy-apps.md) — PIM API iframe views: `app.create`, https `baseUrl`, `crystallizeSignature` and `signatureSecret`, `frame-ancestors`, custom views, and when to pick a plugin instead. - [Official documentation](https://crystallize.com/docs/developer/plugins) - Companion skill: [js-api-client](../js-api-client/SKILL.md) — `createClient`, `createPluginPayloadDecrypter`, all API callers. - CLI helpers: `crystallize plugin create`, `crystallize plugin keygen`, `crystallize plugin encrypt-secret --public-key `, `crystallize plugin decrypt-payload --private-key `. diff --git a/use-crystallize/skills/plugins/references/legacy-apps.md b/use-crystallize/skills/plugins/references/legacy-apps.md new file mode 100644 index 0000000..1cf8508 --- /dev/null +++ b/use-crystallize/skills/plugins/references/legacy-apps.md @@ -0,0 +1,101 @@ +# Legacy Apps (PIM API iframe views) + +Before plugins, a tenant could frame any web page in the Crystallize App as an **App**. Apps still work and some +tenants use them, so you will meet them. They are a much smaller contract than plugins: no manifest, no placements, +no scopes, no Backend Token, and no item context. + +**Pick a plugin when the view needs the item, order or language the editor is on.** An App only learns the tenant +and the user. Pick an App for a tenant-wide view (a dashboard, a report, an import screen) on a tenant that already +has one, or when a plugin is more than the task needs. + +## Register an App + +Apps live on the legacy PIM API (`https://pim.crystallize.com/graphql`), with an access token pair. The Core API has +plugin installations but no apps. + +```graphql +mutation CreateApp($tenantId: ID!) { + app { + create( + input: { + tenantId: $tenantId + identifier: "stock-dashboard" + name: "Stock dashboard" + baseUrl: "https://admin.example.com/apps/stock" + } + ) { + identifier + name + baseUrl + } + } +} +``` + +- **`baseUrl` must be https.** `http://localhost:3000` is refused with "Invalid URL format, make sure URL contains + https protocol". Deploy the page, or put a tunnel in front of the dev server, before you register it. +- **`tenantId` is the tenant's id**, not its identifier. +- **Update and delete by identifier**: `app { update(tenantId, identifier, input: { name, baseUrl }) }` (the input + takes only `name` and `baseUrl`) and `app { delete(tenantId, identifier) }`. Read them with `app { get }` and + `app { getMany }`. + +## What the framed page receives + +The App loads `baseUrl` with one query parameter: + +```text +https://admin.example.com/apps/stock?crystallizeSignature= +``` + +- The JWT carries the tenant and the signed-in user. It carries **no item id and no language**. A per-item view needs + its own deep-link parameters and a lookup from the item id to the item (Discovery, or Core from the server). +- **Verify the signature on the server** with the tenant's `signatureSecret`, read from the PIM API: + + ```graphql + query Secret($id: ID!) { + tenant { + get(id: $id) { + signatureSecret + } + } + } + ``` + + Treat it like any secret: server-side only. `regenerateSecrets` on the tenant rotates it. + +## Allow the App to frame the page + +The page must allow `https://app.crystallize.com` as a frame ancestor. A page component can't set response headers, +so in Next.js put it in `next.config` `headers()` (or the proxy), scoped to the App's routes: + +```js +// next.config.mjs +export default { + async headers() { + return [ + { + source: "/apps/:path*", + headers: [{ key: "Content-Security-Policy", value: "frame-ancestors https://app.crystallize.com" }], + }, + ]; + }, +}; +``` + +Keep the rest of the site at `frame-ancestors 'self'` (or `none`). + +## Custom views (tenant frontends) + +Custom views, the tenant's list of frontends as `{ name, url }`, are tenant preferences and are registered only on +the PIM API: `tenant { setPreferences(tenantId, input: { frontends: [{ name, url }] }) }`. The argument is +`tenantId`. Read them back with `tenant { get(id) { preferences { frontends { name url } } } }`. + +## Apps versus plugins + +| Need | App | Plugin | +| --------------------------------------------- | ---------------------------------------------- | ------------------------------------------ | +| Know the item, order or language being edited | No | Yes, in the decrypted payload | +| Call Crystallize APIs as the user | No: bring your own credentials | Yes, with the per-load Backend Token | +| Placement in the App | One App entry | Declared placements | +| Registration | PIM `app.create`, per tenant | `/@me` plugin, revision, approval, install | +| Signature | JWT signed with the tenant's `signatureSecret` | JWE payload encrypted to your key | diff --git a/use-crystallize/skills/pricing/SKILL.md b/use-crystallize/skills/pricing/SKILL.md index c128d01..a62750b 100644 --- a/use-crystallize/skills/pricing/SKILL.md +++ b/use-crystallize/skills/pricing/SKILL.md @@ -3,7 +3,7 @@ name: pricing description: Design and implement pricing strategies in Crystallize using Price Variants, Price Lists, Promotions, and Markets. Use when recommending pricing structures, setting up multi-currency support, configuring B2B/B2C pricing, planning promotional campaigns, defining markets, or advising on pricing architecture for commerce projects. Also use when the user asks about currencies, multi-market setup, was/now pricing, strikethrough prices, wholesale pricing, contract prices, coupon codes, discount campaigns, tiered or volume pricing, cart discounts, tax-inclusive/exclusive pricing, or any question about how prices work in Crystallize — even if they don't explicitly mention "pricing". metadata: author: Crystallize - version: "2.0" + version: "2.1" --- # Crystallize Pricing Skill @@ -36,6 +36,38 @@ Crystallize resolves prices through a layered hierarchy. Each layer can override 2. Whether a price list overrides that variant (based on market, customer, customer group, time period). When several match, the lowest price wins 3. Whether any promotions apply (based on cart contents, coupon codes, triggers) +## Which price, from which API, for whom + +Read this before building a storefront. The three read APIs resolve price lists for different audiences, +and only one of them knows the customer in the cart: + +| Price | API | Call | Where | +| -------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------- | +| List, sale and "from" price | Discovery | `Price`, the `priceVariants` hash, `variantGroups.summary.price` | Server, cached | +| Market price (public) | Discovery: **markets only** | `PriceFor(marketIdentifiers)`, `BestPriceListFor(marketIdentifiers)`, for the SKUs on screen | Server, cached | +| Contract price for display (B2B) | Shop API price check, or Catalogue | A throw-away `hydrate` with the customer; or Catalogue `priceFor(customerIdentifiers)` for **any** customer | **Server**, cached per org | +| What the cart charges | Shop API `/cart` | `hydrate` resolves the **cart's customer** (and its parents), plus `context.price.markets` and `customerGroups` | Server action | + +- **Discovery has no customer argument anywhere.** `BestPriceList` answers `null` for a list aimed + at a customer, because Discovery does not know who is asking. Never use it for a contract price. +- **Discovery is open by default, and when open, everything it serves is public**: every price variant and, + to anyone who knows a market's identifier, that market's price list. A "market per agreement" makes the + agreement readable without a token, so keep confidential terms out of it. +- **A market identifier works as a key.** A price list aimed at a customer and a market applies to anyone who + sends that market. On a sandbox tenant, a guest cart (`isGuest: true`) with `context.price.markets: + ["b2b-contract"]` got the contract price (71.2 instead of 89), and Discovery `defaultPriceFor` gave the same + price anonymously. Price resolution reads the markets the caller passes, nothing else, so derive markets on the + server from the signed-in session, never from the browser, a query string or an agent tool's arguments. +- **With price lists or contract prices, restrict Catalogue and Search & Discovery.** Both can be open, and are by + default, but then the prices above can be read without a token. Restricting them is strongly recommended: read + them with the static token from the server, and re-ignite Discovery after the change ([[query]]). +- **The Shop API and the Catalogue resolve the same list**, so a contract price shown from either agrees + with the cart. The Shop API resolves only the cart's customer; the Catalogue resolves any customer, which + is what a seller tool or a cached per-organisation price table needs. +- Core is never on this path. For the storefront as a whole, see [[storefront]]; for the tables behind each + row, see [references/price-lists-and-markets.md](references/price-lists-and-markets.md), "Where each API + resolves a price list". + ## Quick Start Decision Tree ``` @@ -81,7 +113,7 @@ Price variants are **global definitions** — they define the _types_ of prices Every Crystallize tenant comes with a `default` price variant. It **must always exist** — it cannot be deleted. -**Best practice: Rename it to match your primary use case.** Only the display **name** changes: the identifier stays `default` for good, because `updatePriceVariant` takes `name`, `currency` and `tierConfig` and no identifier. Set its `currency` too: it is created without one and answers the tenant's default currency. +**Best practice: give it a display name that matches your primary use case.** The identifier stays `default` for good: `updatePriceVariant` takes `name`, `currency` and `tierConfig` and no identifier, and `deletePriceVariant` refuses `default`. So do not plan a `retail` identifier for it; every API call keeps saying `default`. Set its `currency` too: it is created without one and answers the tenant's default currency (EUR on a fresh tenant). Make `default` your primary currency's price rather than adding a `nok` variant next to it, or you carry two copies of the same price. | Business Type | Name `default` | Currency | Rationale | | ----------------- | ---------------------- | -------------------- | --------------------------------- | @@ -248,7 +280,7 @@ Each price list can: - **Apply to all or specific products** (by drag-and-drop or bulk selection) - **Adjust by**: percentage, relative value, or absolute price - **Have a time period**: start/end dates for seasonal campaigns -- **Be scoped to**: a market, customer group, or individual customer +- **Be scoped to**: everyone, a market, or individual customers (organisations reach their people). Customer groups are accepted by the input but do not work today: see below ### Recommended Price List Patterns @@ -265,11 +297,13 @@ Price Lists: ``` Price Lists: - ├── "Wholesale Tier 1" — 15% off B2B variant, Customer Group: Tier 1 - ├── "Wholesale Tier 2" — 25% off B2B variant, Customer Group: Tier 2 - └── "Acme Corp Agreement" — Fixed prices, Customer: Acme Corp + ├── "Wholesale Tier 1" — 15% off B2B variant, Market: wholesale-tier-1 + ├── "Wholesale Tier 2" — 25% off B2B variant, Market: wholesale-tier-2 + └── "Acme Corp Agreement" — 12% off B2B variant, Customer: acme-corp (the organisation) ``` +Tiers are markets because price lists **cannot target customer groups**: `createPriceList` answers `CustomerGroupNotFoundError` (or `NotFoundError`) for a group that exists, seen on four tenants. The storefront then sends the tier's market in `context.price.markets`; a market's `customerIdentifiers` do not put a customer's cart in it. A tier market is public in Discovery, so it suits published tiers, not confidential terms. Keep an agreement a `PERCENTAGE` list so the variant's volume tiers survive, and send the whole SKU set on every `updatePriceList`: see [references/price-lists-and-markets.md](references/price-lists-and-markets.md), "Price lists that work". + #### Seasonal Campaigns ``` @@ -325,7 +359,7 @@ Market ──→ Price Lists (which prices apply) ──→ Checkout context (resolved at purchase time) ``` -Markets are set in the **checkout context** — at cart/checkout time, `context.price.markets` determines which price lists and promotions are evaluated. +Markets are set in the **checkout context** — at cart/checkout time, `context.price.markets` determines which price lists and promotions are evaluated. Set them on the server from the signed-in session: whoever sends a market gets its prices. ## Promotions @@ -407,21 +441,29 @@ Always recommend starting with the minimum viable setup and adding layers as the The Shop API `hydrate` mutation prices a cart from `input.context.price`. The storefront sends it on **every** hydrate: an omitted field goes back to its default, it does not keep the previous value. -| `context.price` | Default | Effect | -| -------------------------------------- | --------- | ------------------------------------------------------------------------------------------ | -| `selectedVariantIdentifier` | `default` | The price variant that sets the price | -| `fallbackVariantIdentifiers` | none | Tried in order when the selected variant has no price for the SKU | -| `compareAtVariantIdentifier` | none | The "was" price, read before price lists. A gap to the selected price lands in `discounts` | -| `markets` | `[]` | Which market-targeted price lists and promotions can match | -| `customerGroups` | `[]` | The same for groups. Not read from the customer record | -| `voucherCodes` | `[]` | Coupon codes. `voucherCode` is deprecated | -| `currency` | `eur` | A label, and what `triggers.currencies` tests. It selects no variant and converts nothing | -| `decimals` | `0` | Rounds every amount returned. **Left at 0, 39.99 comes back as 40** | -| `pricesHaveTaxesIncludedInCrystallize` | `false` | Whether the stored price is gross, see below | -| `taxRate` | none | 0–1, overrides the product's tax group | -| `discountOnNetPrices` | `false` | Promotions and `minValue` work on net instead of gross | - -A SKU with no value on the selected variant or on any fallback silently takes its **first** price variant, possibly in another currency. Was/now in a cart: +| Input | Default | Effect | +| --------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `customer` on the cart (`hydrate` or `setCustomer`) | guest | Customer-targeted price lists, **inherited from parent customers**: a person under an organisation gets its list | +| `selectedVariantIdentifier` | `default` | The price variant that sets the price | +| `fallbackVariantIdentifiers` | none | Tried in order when the selected variant has no price for the SKU: `campaign` then `default` prices campaign-or-list | +| `compareAtVariantIdentifier` | none | The "was" price (or the RRP next to a B2B price), read before price lists. A gap to the selected price lands in `discounts` | +| `markets` | `[]` | Which market-targeted price lists and promotions can match. Not read from the market's `customerIdentifiers` | +| `customerGroups` | `[]` | The same for groups. Not read from the customer record | +| `voucherCodes` | `[]` | A list of coupon codes. `voucherCode` is deprecated. Check one with `validateVoucher(voucher)` | +| `currency` | `eur` | A label, and what `triggers.currencies` tests. It selects no variant and converts nothing | +| `decimals` | `0` | Rounds every amount returned. **Left at 0, 39.99 comes back as 40.** Send `4`, see below | +| `pricesHaveTaxesIncludedInCrystallize` | `false` | Whether the stored price is gross, see below | +| `taxRate` | none | A **fraction** (`0.25`, not `25`), overrides the product's tax group | +| `discountOnNetPrices` | `false` | Promotions and `minValue` work on net instead of gross | + +A SKU with no value on the selected variant or on any fallback silently takes its **first** price variant, possibly in another currency, and a variant with no price at all hydrates at 0, not as an error. + +- **`compareAtVariantIdentifier` falls back too.** When the SKU has no value on the compare-at variant, the cart compares with its first variant: a $64 line without a `usd-before` price reported a 1,172 "discount" (90 %) against the NOK price. Send it only for SKUs that have a before-price. +- **Ask for `decimals: 4` and round for display only, half up.** With 2 decimals, a percentage list on a small unit price drifts a cent between the cart and the product page. The Shop API rounds half up (11.70 × 0.85 = 9.945 → 9.95), while `Math.round(x * 100) / 100` gives 9.94: round via `toFixed(4)` first. +- **A cart line's `price` is the line total**, while order lines carry the unit price. Divide before you compare with a product page. +- **A PERCENTAGE list must carry every price variant the cart can select.** With `campaign` selected and `default` as fallback, a list with a modifier on `default` only leaves campaign-priced SKUs at full price. + +Was/now in a cart: ```graphql context: { @@ -430,12 +472,14 @@ context: { fallbackVariantIdentifiers: ["default"] compareAtVariantIdentifier: "default" currency: "USD" - decimals: 2 + decimals: 4 markets: ["us-retail"] } } ``` +**A contract price for display without the Catalogue API** is a throw-away `hydrate` on the server: a cart with the signed-in customer and the SKUs on screen, read once, cached per organisation, then `remove(id)`. It answers what the real cart will charge. + ## Tax & Pricing Prices in Crystallize are stored as raw numbers — the system does not enforce whether they are tax-inclusive or tax-exclusive. This is a business decision: @@ -448,43 +492,14 @@ The Shop API calculates the tax. The rate is the first of: `taxRate` on the cart ## Migration Paths -Start simple and add layers as your business requires. Here are common upgrade paths: - -### Single variant → Sales pricing - -``` -Before: default (USD) -After: retail (USD) + sales (USD) -``` - -Name the `default` variant "Retail" (its identifier stays `default`). Create a new `sales` variant in the same currency. Only set `sales` on products that are currently on sale. - -### Single currency → Multi-currency - -``` -Before: retail (USD) + sales (USD) -After: retail (USD) + sales (USD) + retail-eur (EUR) + sales-eur (EUR) -``` - -Keep your primary market variants as-is. Add new variant pairs for each additional currency. Create Markets for each region and Price Lists if you need regional adjustments beyond the base variant prices. - -### B2C only → B2C + B2B - -``` -Before: retail (USD) + sales (USD) -After: retail (USD) + sales (USD) + b2b (USD) -``` - -Add a `b2b` variant. Create a Market for B2B customers (e.g. `us-b2b`). Use Price Lists for customer-specific or tiered B2B pricing. - -### Static pricing → Campaigns - -``` -Before: Price variants only -After: Price variants + Promotions -``` +Start simple and add layers as the business requires them: -Keep your variant structure unchanged. Add Promotions for time-limited, cart-level discounts (coupons, buy-X-get-Y, seasonal sales). If you need persistent regional adjustments, add Price Lists instead of (or alongside) Promotions. +| From → to | Add | Keep | +| --------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- | +| One variant → sales pricing | A `sales` variant in the same currency, set only on products on sale | `default`, with the display name "Retail" | +| One currency → several | A `retail-{currency}` / `sales-{currency}` pair per currency, and markets | The primary market's variants as they are | +| B2C → B2C + B2B | A `b2b` variant, a B2B market, price lists per organisation or tier | The consumer variants | +| Static pricing → campaigns | Promotions for time-limited cart discounts | The variant structure; price lists for lasting adjustments | ## Further Reading diff --git a/use-crystallize/skills/pricing/references/price-lists-and-markets.md b/use-crystallize/skills/pricing/references/price-lists-and-markets.md index d030936..3474644 100644 --- a/use-crystallize/skills/pricing/references/price-lists-and-markets.md +++ b/use-crystallize/skills/pricing/references/price-lists-and-markets.md @@ -38,7 +38,7 @@ mutation CreateMarket { } ``` -Listing customers in `customerIdentifiers` does not put their carts in that market. Price resolution reads the markets the caller passes, nothing else. +`create` refuses `customerIdentifiers` that don't exist yet (`MARKET_INVALID_CUSTOMER_IDENTIFIERS`), so seed customers first, then markets, then price lists. Listing customers in `customerIdentifiers` does not put their carts in that market. Price resolution reads the markets the caller passes, nothing else. ### Market Architecture Patterns @@ -141,7 +141,7 @@ Price lists override or adjust the base price (from price variants) for specific - **Price variants** — Which variant(s) this list adjusts - **Adjustment type** — Percentage, relative value, or absolute price - **Period** (optional) — Start and end dates - - **Target** — Market, customer group, or individual customer + - **Target** — Everyone, a market, or individual customers (customer groups: see "Contract prices") ### Via Core API @@ -224,17 +224,23 @@ Price Lists: A market selling in pounds needs its own GBP price variant: `absolute 89` on this variant is €89. -#### Customer Group Tiering +#### Customer Tiering ``` Price Variant: "b2b" (EUR) — Base price: €80 Price Lists: - ├── "Wholesale Tier 1" → Group: tier-1 → Adjust: -10% → Final: €72 - ├── "Wholesale Tier 2" → Group: tier-2 → Adjust: -20% → Final: €64 - └── "Strategic Partner" → Group: strategic → Adjust: -30% → Final: €56 + ├── "Wholesale Tier 1" → Market: tier-1 → Adjust: -10% → Final: €72 + ├── "Wholesale Tier 2" → Market: tier-2 → Adjust: -20% → Final: €64 + └── "Strategic Partner" → Customers: the partner organisations → Adjust: -30% → Final: €56 ``` +Tiers are markets, not customer groups, because a list cannot target a group today (see "Contract +prices"). The storefront maps the signed-in customer to its tier and sends that market in +`context.price.markets`; listing customers on the market does not do it. Discovery serves a tier market's +price to anyone who sends its identifier, so use markets for tiers you would publish anyway, and +`customerIdentifiers` for terms that are confidential. + #### Time-Based Campaigns ``` @@ -301,37 +307,62 @@ you do not need customer groups, and you do not need the customer's own price va **Customer groups are a dead end here for now.** A group created with Core `createCustomerGroup` is listed by `customerGroups`, but `createPriceList(targetAudience: { customerGroupIdentifiers })` answers -`CustomerGroupNotFoundError`, also after a wait — seen on two tenants. Target the customers directly. +`CustomerGroupNotFoundError` (or `NotFoundError — Entity not found: [object Object]`), also after a wait — +seen on four tenants. Target the organisations by `customerIdentifiers`, or use markets. One build did get a +group list to apply in a cart that sent `context.price.customerGroups`, which is how the cart side works if +the list exists: the group is read from the context, never from the customer record. Use customer groups as +folders for customers, not as price-list targets. ### Where each API resolves a price list This is the table to read before designing a B2B storefront, because the three APIs do not agree: -| API | Resolves a list for | How | -| ------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Discovery** | markets only — there is **no customer context** | `PriceFor(marketIdentifiers:)`, `BestPriceListFor(…)` | -| **Catalogue** | customer, customer group **or** market | `priceVariant(identifier) { priceFor(count, customerIdentifiers, customerGroupIdentifiers, marketIdentifiers) { price identifier modifier modifierType } }` | -| **Shop API** | the cart's customer, plus `context.price.markets` and `context.price.customerGroups` | `hydrate` prices the lines | +| API | Resolves a list for | How | +| ------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Discovery** | markets only — there is **no customer context** | `PriceFor(marketIdentifiers:)`, `BestPriceListFor(…)` | +| **Catalogue** | customer, customer group **or** market | `priceVariant(identifier) { priceFor(count, customerIdentifiers, customerGroupIdentifiers, marketIdentifiers) { price identifier modifier modifierType } }` | +| **Shop API** | the cart's customer and its parents, plus `context.price.markets` and `customerGroups` | `hydrate` prices the lines | `customerIdentifiers` is a **list** (`[String!]`), not a single string. A storefront that lists products from Discovery therefore cannot show a contract price from that query alone: `BestPriceList` comes back `null` for a customer-targeted list, since Discovery has no idea -who is asking. Read the customer's terms from the **Catalogue API** server-side, cache them per -organisation, and apply them where you render prices. The cart then agrees by itself, because the Shop API -resolves the same list from the cart's customer. +who is asking. Two server-side ways to show it, both cached per organisation: + +1. **A Shop API price check.** `hydrate` a throw-away cart with the signed-in customer + (`customer: { identifier, isGuest: false }`) and the SKUs on screen, and read the line prices. No + Catalogue access needed, and the numbers are by definition what checkout charges. +2. **The Catalogue API** `priceFor(customerIdentifiers:)`, or `priceList(identifier) { productVariants }` + for the whole list at once. It resolves any customer, so it also serves seller tools. + +Apply the result where you render prices, behind a `` boundary so the rest of the page stays +cached for everyone (a short cache, a few seconds, lets a new list show quickly). The cart then agrees by +itself. Do not read price lists from Core for this: Core is not a storefront API. See [[storefront]]. Note that every price variant generates its own Discovery fields — `nokPrice(count)`, `nokPriceTiers`, `nokPriceFor(marketIdentifiers, count)`, `nokBestPriceListFor(…)`, plus the filter/facet/sort field `price_nok`. A variant with no price for a product answers `null`, so `filters: { price_x: { exists: true } }` -is a usable "is this on that price variant" filter. And because Discovery is public, anyone who knows a -field name can read any price variant it exposes: keep genuinely confidential terms out of Discovery and -read them from the Catalogue API server-side. +is a usable "is this on that price variant" filter. Discovery is open by default, and when it is open, +everything it serves is public: anyone who knows a field name can read any price variant, and anyone who +knows a market identifier can read that market's list with `PriceFor(marketIdentifiers)` and its +modifier with `BestPriceListFor`. Aiming an agreement at a market of its own (`avtale-`) does +make it show in Discovery about 8 s after `createPriceList`, but it publishes the terms. Keep confidential +terms on `customerIdentifiers` and read them server-side as above. + +**Market prices are expensive at volume.** `PriceFor(marketIdentifiers)` added about 1.4 s per 100 +products (about 270 variants each) per market; four markets on 15,500 variants took 21 s and 13 MB. And +`PriceForEveryone` makes Discovery evaluate every price list per variant: 250 products took 7–8 s +per page, and under a 4,000-page build it answered "Response Error". Ask for market prices only for the SKUs +on screen, never in candidate pools or prerender-wide listings. For a B2C sale, put the selling price on the +variant and the before-price on its own price variant, read both from `priceVariants`, and keep lists for +other discounts. ### Working with big lists -- **One `createPriceList` call carries a whole catalogue.** A list with 2,211 SKUs went in as a single - `SOME_SKUS` call with a modifier per SKU; no batching needed. `updatePriceList` replaces the SKU +- **One `createPriceList` call can carry a whole catalogue, but not always.** A list with 2,211 SKUs went + in as a single `SOME_SKUS` call on one tenant; about 2,200 SKUs on another answered HTTP 413 "Entity too + large" as plain text, not JSON. If you see 413, split above about 500 SKUs into several disjoint lists + with the same audience: Discovery and the cart resolve them all. `updatePriceList` replaces the SKU selection whole, so send the complete set every time. To change part of a list, use the legacy PIM API's `priceList { upsertSelectedProductVariants(tenantId, identifier, variants) removeSelectedProductVariants(tenantId, identifier, variants: [sku]) }`, or the mass operation intents `pricelist/selectedProductVariants/upsert` and `.../remove`. @@ -357,6 +388,28 @@ There is no priority and no notion of the most specific list. Every list that ma So an `EVERYONE` campaign at −30 % beats a customer's −20 % contract, and a +10 % list only applies if no other matching list is lower. The base price itself does not compete: a single matching +10 % list does raise the price. +### Price lists that work + +What the B2B builds settled on, on top of the rules above: + +- **Target organisations by `customerIdentifiers`, or markets.** Not customer groups (see "Contract + prices"). A list on the organisation reaches its departments and people in the Catalogue and in the cart. +- **Base discount plus exceptions is two lists on one audience**: an `ALL_SKUS` list for the base and a + `SOME_SKUS` list naming only the SKUs whose rule differs. Observed: −24 % `SOME_SKUS` over −18 % `ALL_SKUS` + for the named SKUs. That is the lowest price winning, so an exception can only deepen the base discount; + a shallower exception needs the base list to leave those SKUs out. +- **A `PERCENTAGE` list keeps the variant's volume tiers; an `ABSOLUTE` list has none.** Make agreements + percentages (see "Contract prices"). +- **Put the modifier on every price variant the cart can select.** A cart that selects `campaign` and + falls back to `default` needs the modifier on both, in `priceVariants` and per SKU, or campaign-priced + SKUs stay at full price. +- **Scoped agreements ("−6 % on feed and parts") are `SOME_SKUS` lists built from Discovery.** A list has no + selection by folder or topic: resolve the scope to SKUs with a Discovery query (`parentPaths`, `shape`, + `topics`) and send the full set. A rerun after the catalogue changes sends the whole set again, because + `updatePriceList` replaces it. +- **Check the result in a cart** for one person under the organisation and for a guest: the person gets + the list, the guest the list price. + ### Best Practices 1. **Name descriptively** — Include the target context in the name: "EU B2B Q1 2025" not "Price List 3" diff --git a/use-crystallize/skills/pricing/references/price-variants.md b/use-crystallize/skills/pricing/references/price-variants.md index 5d85c94..0221d5a 100644 --- a/use-crystallize/skills/pricing/references/price-variants.md +++ b/use-crystallize/skills/pricing/references/price-variants.md @@ -109,6 +109,10 @@ mutation SetVariantPrice { It sets one price at a time and leaves the rest of the variant alone. `updateProductVariant` also takes `priceVariants`, but rewrites more of the variant: see [[mutation]] before using it for a price change. +**Negative prices are legal** (from −1e9 to 1e9), and zero too: useful for option deltas against a base +configuration, such as a deduction for a simpler brake. Write them with the variant (`product/upsert`, +`updateProductVariant`): `product/variant/price/modify` has a minimum of 1. + ## Querying Prices ### Discovery API @@ -149,6 +153,29 @@ query { } ``` +### Every Discovery price field + +Each price variant generates the same set of fields on every product variant type, here for `nok`. The +generic fields take the identifier as an argument instead. Checked by introspection on a live tenant, +2026-11-12: + +| Field | Answers | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| `nokPrice(count)` | The variant's price, the tier price for `count`; `null` when not set | +| `nokPriceTierType`, `nokPriceTiers { threshold price }` | The volume or graduated ladder; `null` without one | +| `nokPriceFor(marketIdentifiers, count)` | The lowest price after the lists aimed at those markets | +| `nokPriceForEveryone(count)` | The same for `EVERYONE` lists. Slow at volume | +| `nokBestPriceList`, `…ForEveryone`, `…For(marketIdentifiers)` | The winning `PriceList { identifier name modifier modifierType }` | +| `priceVariants(key)` | The hash of every variant, `{ price, currency }` each | +| `priceVariantFor(identifier, marketIdentifiers, count)` | `nokPriceFor` with the identifier as an argument | +| `priceVariantForEveryone(identifier, count)` | `nokPriceForEveryone` likewise | +| `bestPriceList(identifier)`, `bestPriceListFor(…)`, `…ForEveryone` | The winning list, likewise | +| `price_nok` (in `filters`, `sorting`, facets) | The filter, sort and facet field; `exists: true` means "has a nok price" | + +None of them takes a customer: Discovery resolves markets only. For a customer's price, see "Which price, +from which API, for whom" in the main pricing guide. A new price variant shows up in the `priceVariants` +hash without a re-ignite. + ### Catalogue API Here `priceVariants` is a list, which is what the helpers below take. diff --git a/use-crystallize/skills/pricing/references/promotions.md b/use-crystallize/skills/pricing/references/promotions.md index a24b72b..0766df4 100644 --- a/use-crystallize/skills/pricing/references/promotions.md +++ b/use-crystallize/skills/pricing/references/promotions.md @@ -128,6 +128,10 @@ Target: The SKU of the shipping line Limitations: Cumulative (can combine with product discounts) ``` +**A promotion without a target discounts the shipping line too.** "10 % off everything" took 99 shipping +down to 89.10, and `changeCartItemPricing` on that line does not exempt it. Give site-wide promotions a +target, or put the shipping SKU in their `exclusions`. + ### Members-Only Discount ``` @@ -250,6 +254,8 @@ mutation HydrateCartWithCoupon { The response includes a `discounts` list on each item and on the cart total when a discount has been applied, and `appliedPromotions` names what fired. If the coupon code is invalid or no promotion matches, the prices are returned without discounts and **without an error**. To tell the shopper, query `validateVoucher(voucher: "WELCOME15") { isValid promotions { identifier name } }` on the same endpoint. It only says that a promotion carries the code, not that this cart qualifies, so compare with `appliedPromotions` after hydrating. +**Read the applied promotions from the cart, not from the order.** `createFromCart` answers `appliedPromotions: null` (and `reference: null`) even when the cart had one; the discounts survive on the lines. If the order must say which promotion fired, copy `appliedPromotions` into cart meta before `place`, since cart meta becomes order meta. Test orders count toward `maxUsagePerCustomer` and orders cannot be deleted, so never test a limited promotion with a real customer's identifier. + ### Cart Hydration with Automatic Promotions Promotions without triggers apply automatically — no coupon code needed: diff --git a/use-crystallize/skills/query/SKILL.md b/use-crystallize/skills/query/SKILL.md index 84d7279..cc04d1b 100644 --- a/use-crystallize/skills/query/SKILL.md +++ b/use-crystallize/skills/query/SKILL.md @@ -1,238 +1,280 @@ --- name: query -description: Query Crystallize APIs for product data, content, and commerce information. Use this skill when fetching product catalogs, listing items, searching products, filtering by attributes, browsing categories, building storefronts, retrieving cart data, reading orders or customers, building admin dashboards, getting item details by path or ID, implementing faceted navigation, paginating results, or reading any data from Crystallize. Covers Core API, Discovery API, Catalogue API, and Shop API queries. Also use when the user asks about GraphQL queries against Crystallize, reading product variants, getting component data, checking stock levels, or any read operation — even if they don't explicitly say "query". +description: Query Crystallize APIs for product data, content, and commerce information. Use this skill when fetching product catalogs, reading an item by path, listing a category, searching products, typeahead, filtering by attributes or typed specs, faceted navigation, listing cards per colourway (variantGroups), picking a variant on a product page, reading list, market or sale prices and stock, translated paths for hreflang and sitemaps, editor draft preview, paginating results, retrieving cart data, reading a shopper's orders, customers or subscription contracts, building back-office dashboards, or reading any data from Crystallize. Covers the Discovery API (every storefront catalogue read), the Shop API (carts, orders, customers), the Catalogue API (the synchronous fallback, for per-customer prices and reads that must be in sync with a publish) and Core API reads (back office only). Also use when choosing which Crystallize API a frontend should read from, debugging empty or stale Discovery results after a publish or a model change, generated Discovery field names, or any read operation — even if the user doesn't explicitly say "query". metadata: author: Crystallize - version: "2.0" + version: "3.0" --- # Crystallize Query Skill -Query product data, content, and commerce information from Crystallize using GraphQL APIs. This skill covers reading data for storefronts, admin interfaces, product pages, search, and cart operations. +Read product data, content and commerce data from Crystallize. This skill covers how each read API behaves. Which +API a storefront calls for each task, and in what order, is the **storefront API contract** below, in full in +[[storefront]]. ## Consultation Approach -Before writing queries, understand the context. Ask clarifying questions: - -1. **What data do you need?** Products, orders, customers, content, shapes? -2. **Is this for a storefront or admin interface?** Discovery/Catalogue for storefronts, Shop API for carts and orders, Core for admin only — Core is rate limited and must not serve storefront traffic. -3. **Do you need search/filtering or exact path reads?** Discovery for search and faceted navigation, Catalogue for deterministic reads by path. -4. **Do you have authentication configured?** Core API requires access tokens. Discovery/Catalogue can be open but should be secured in production. - A public Discovery endpoint serves **every price variant it exposes** to anyone who knows the field name - (`nokPrice`, `wholesalePrice`, …), so confidential terms — negotiated B2B prices in particular — belong - in a price list read from the Catalogue API server-side, not in a price variant. See [[pricing]]. -5. **What volume of results?** Pagination strategy matters — cursor-based is recommended wherever an API has it. Shop API lists use `limit`/`skip`. - -## Choosing the Right API - -- Need search, filtering, or faceting? → **Discovery API** -- Know the exact path? Need strong consistency? → **Catalogue API** -- Admin interface? Orders, customers, shapes? → **Core API** -- Cart/checkout operations? → **Shop API** -- Need results _ordered_ by relevance rules, personalization, or similarity? → **Discovery API** with - `rankBy` / `context` / `nearestTo` — see [[vector-ranking]] - -### Core Is Not a Storefront API - -**Core is heavily rate limited and is not meant for storefront traffic** — not even server-side with a short cache, and never once per page view. A storefront reads the catalogue from Discovery (and Catalogue for deterministic path reads), and does carts, orders, customers and subscription contracts on the Shop API. Core is for the back office: imports, seeding, scheduled jobs and admin tools, behind your own server. - -This costs nothing in capability. The Shop API is edge-distributed and scales near the shopper, and it syncs with Core asynchronously, so an order placed through the Shop API is in Core a few seconds later for the back office to work on. - -## How It Works - -Crystallize provides four main APIs for querying data: - -1. **Core API** - Full read/write API with advanced filtering. Best for admin interfaces, customer/order management. -2. **Discovery API** - Semantic API for search, browse, filter, and faceting. Best for storefronts. -3. **Catalogue API** - Path-based reads for deterministic data access. -4. **Shop API** - Cart and checkout queries at the edge. - -## API Endpoints - -| API | Endpoint | Auth Required | Use For | -| --------------------------- | ----------------------------------------------------------------- | ----------------------- | ------------------------------ | -| Core | `https://api.crystallize.com/@{tenant}` | Yes (access tokens) | Admin, customers, orders | -| Discovery | `https://api.crystallize.com/{tenant}/discovery` | Optional (configurable) | Storefront search/filter | -| Catalogue | `https://api.crystallize.com/{tenant}/catalogue` | Optional (configurable) | Storefront path-based reads | -| Shop /cart | `https://shop-api.crystallize.com/{tenant}/cart` | Yes (JWT) | Cart hydration, checkout flows | -| Shop /order | `https://shop-api.crystallize.com/{tenant}/order` | Yes (JWT) | Order queries by ID/customer | -| Shop /customer | `https://shop-api.crystallize.com/{tenant}/customer` | Yes (JWT) | Customer by identifier | -| Shop /subscription-contract | `https://shop-api.crystallize.com/{tenant}/subscription-contract` | Yes (JWT) | Contracts by ID/customer | - -## Usage - -### Core API (Admin & Advanced Queries) - -The Core API provides full read/write access with advanced filtering capabilities: - -- Read items by ID with full component data -- List items with pagination and filtering -- Query customers and orders with complex filters -- Filter orders by customer, SKU, payment provider, metadata -- Access shape and piece definitions -- Manage flows and archives +Before writing queries, ask: + +1. **Is this a storefront (or any shopper-facing code) or the back office?** It decides the API: see the contract. +2. **Is the data about the catalogue or about a shopper?** Catalogue → Discovery. Cart, the price this customer pays, + orders, customers, bookings, subscriptions → Shop API. +3. **Does the read run in the browser or on the server?** Only an open Discovery may be called from the browser. +4. **Is the data confidential?** An open Discovery serves everything it indexes to anyone: every price variant + (`nokPrice`, `wholesalePrice`, …) and every market's price list. Negotiated B2B terms never go there, see + [[pricing]]. +5. **Was the model or content just changed?** Discovery is eventually consistent, see + [Discovery Indexing](references/discovery-indexing.md). + +## The storefront API contract + +1. **Discovery API: every catalogue read.** Item by path, category listing, search, typeahead, facets, variant groups, + translated paths, list and market prices, stock per location, ranking and similarity. It serves published + content by default and drafts with `publicationState: draft` (editor preview; public on an open tenant). It is + eventually consistent. +2. **Shop API: everything about a shopper.** Carts, the price for this customer and market, promotions and vouchers, + `place`, orders created from the cart or directly, payments, pipeline stages on those orders, the shopper's order + history, customers, bookings, subscription contracts (one store per tenant, see [[subscriptions]]), and locks. +3. **Catalogue API: the synchronous fallback**, for two tasks: per-customer price lists for display + (`priceFor(customerIdentifiers:)`), and a read that must be in sync with what was just published, such as a + price right after it changed. Discovery is updated asynchronously after a publish; Catalogue answers from the + published state at once. Otherwise keep tenants off it. It is not a peer of Discovery: `variants` came back `[]` on three tenants while + `defaultVariant` worked. Draft preview and hreflang are Discovery tasks. +4. **Core API: never in the storefront's request path**, not even server-side with a short cache. It is heavily rate + limited. It is for seeding, imports, scheduled jobs, webhook receivers, admin and seller tools behind staff login, + and the few tasks with no Shop API equivalent (subscription usage tracking). +5. **Legacy PIM API: setup and back office only** (pipelines, markets, VAT types, stock locations, subscription + plans). + +The task-by-task table (task → API → call → token → browser or server), the request path per page type and the +resolved contradictions between skills are in [[storefront]]. Writes follow the same contract, see [[mutation]]. + +### Tokens, scopes, browser and server + +| API | Endpoint | Credential | From the browser? | +| --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| Discovery | `https://api.crystallize.com/{tenant}/discovery` | None when open (the default), drafts included. `X-Crystallize-Static-Auth-Token` when restricted, server-side only | Yes if open (any origin). Everything it serves is then public | +| Shop API | `https://shop-api.crystallize.com/{tenant}/{route}` | `Authorization: Bearer ` from `POST …/{tenant}/auth/token`, minted with an access token pair scoped to this tenant (or unscoped) | **No.** CORS allows only Crystallize origins and localhost | +| Catalogue | `https://api.crystallize.com/{tenant}/catalogue` | Open, static token, or token pair, as the tenant setting requires | Only open, published reads. Contract-price reads are server only | +| Core | `https://api.crystallize.com/@{tenant}` | Token pair, session, or plugin bearer | Never (except a presigned upload made on the server, see [[media]]) | +| PIM | `https://pim.crystallize.com/graphql` | Token pair; most calls take `tenantId` | Never | + +The Shop JWT is **per tenant, not per shopper**: it answers `orders(customerIdentifier:)` for any identifier. Keep it +on the server, cache it, and refresh it before it expires: the API default is one day, and js-api-client asks for 12 +hours. The browser holds only the cart id, in an httpOnly cookie. The token rule for minting is in [[permissions]]. + +| Route | Scope | Serves | +| ------------------------ | ------------------------------------ | ------------------------------------------------------- | +| `/cart` | `cart` | Carts, wishlists, price context, `place`, booking holds | +| `/cart/admin` | `cart` + `cart:admin` | Promotions | +| `/order` | `order` | Orders, payments, pipeline stages | +| `/customer` | `customer` | Shop customers (synced to Core) | +| `/subscription-contract` | `subscription-contract` (+ `:admin`) | Contracts. Request a token of its own, see below | +| `/booking/admin` | `booking:admin` | Reservations, blocks, calendar | +| `/lock` | `lock` | Acquire and release a lock (idempotency guards) | + +`GET https://shop-api.crystallize.com/{tenant}` lists the routes a tenant serves. A token requested with every scope +at once read `/subscription-contract` but answered "Unexpected error" on `create`, while a token scoped to that route +alone worked. Minting, expiry and the error shapes are in [Shop API Queries](references/shop-api-queries.md). + +## Discovery API + +The schema is **generated per tenant** from its shapes and index settings: filter, facet and sort fields, shape types +and ranking arguments differ between tenants and change after an ignite. Introspect rather than derive names. Shape +types are the identifier in camelCase (`... on tool`, `... on machineUnit`); interfaces keep their capital +(`... on Product`, `... on Folder`, `... on Document`). + +Entry points: `search` (all shapes, polymorphic hits), `browse.` (shape-typed; each needs its own fragment), +`autocomplete` (on `name`; it restricts and pads with score-0 hits, see the reference) and `topics`. + +> **Never send an explicit `null`.** `after`, `term`, `context`, `sorting` and `filters` reject `null` +> (`expected string, received null`). Build the argument object conditionally and leave the key out. + +### Item by path, and category listings ```graphql -# Example: Get item with components -query GetItem { - item(id: "item-id", language: "en") { - ... on Product { - id +query ItemByPath($path: String!) { + search(language: en, filters: { path: { equals: $path } }, pagination: { limit: 1 }) { + hits { + itemId name - components { - componentId - content { - ... on RichTextComponentContent { - html - } - } - } - defaultVariant { - sku - price - stock + path + updatedAt + breadcrumbs { + name + path } - } - ... on BasicError { - errorName - message - } - } -} - -# Example: List orders filtered by customer -query ListOrders { - orders( - first: 20 - filter: { customer: { identifier: "customer@example.com" } } - sort: { field: createdAt, direction: desc } - ) { - ... on OrderConnection { - edges { - node { - id - total { - gross - currency - } - customer { - identifier - } + ... on tool { + defaultVariant { + sku + defaultPrice } } } - ... on BasicError { - errorName - message - } } } ``` -The tenant comes from the URL, so no Core query takes a `tenantId`, and most root fields return a union. See [Core API Queries Reference](references/core-api.md) for complete documentation. - -### Discovery API (Recommended for Storefronts) - -The Discovery API is the primary API for frontend development. It supports: - -- Full-text search -- Filtering by any component or attribute -- Faceted navigation -- Sorting and cursor-based pagination +- A full path is unique, but **a last segment is not**: paths are unique only within their folder, so never look an + item up by its slug with `limit: 1`. +- A category listing is `browse.(filters: { parentPaths: { equals: "/tools" } })`, which matches at any + depth, or `Folder.children` for direct children. A `parentPaths` facet gives the subfolders. +- Relations come back in the request's language already, so they need no second lookup to localise them. -The Discovery API has three entry points: `search` for full-text queries across all shapes, `browse` for shape-typed access where each shape becomes its own query type, and `autocomplete` for type-ahead on `name`. A fourth query, `topics`, walks the topic map. +### Listing cards and product pages: variantGroups and `variant(selected:)` -**The Discovery schema is generated per tenant** from its shapes and index settings — filter, facet and sort fields differ between tenants, and ranking arguments exist only on tenants served for ranking. Introspect rather than assume. - -> **Note**: The Discovery API uses lowercase type names in inline fragments (`... on product`, `... on category`) because types are derived from your shape identifiers. You can still use it for interface (`... on Product`, `... on Folder`). +Product-level filters match a product as soon as **different** variants satisfy different conditions. To show one card +per colourway, or to require that one variant satisfies the whole filter, read the groups: ```graphql -# Example: Browse products by shape with pagination -{ +query Cards($parent: String!) { browse { - product(language: en, pagination: { limit: 25 }) { - summary { - totalHits - hasMoreHits - endToken - } + product(language: en, filters: { parentPaths: { equals: $parent } }, pagination: { limit: 24 }) { hits { name path - ... on Product { - defaultVariant { + variantGroups(by: ["colour"], filter: { price_default: { range: { lte: 100 } } }, first: 4) { + key + matched + attributes { + attribute + value + } + summary { + count + price(variant: "default") { + min + max + } + } + representative { sku defaultPrice firstImage { url } } + values(of: "size") { + value + sku + osl: stock(location: "osl") + } } } } } } +``` -# Example: Search with facets and filtering -{ - search( - language: en - term: "green" - filters: { type_in: [product] } - facets: { shape: { limit: 5 } } - pagination: { limit: 20 } - ) { - summary { - totalHits - hasMoreHits - endToken - facets +- `variantGroups` **never removes a group** or changes hits, facets or paging: matching groups come first, and the + rest read `matched: false`. Show the `matched` groups first when a filter is active. +- `summary.price(variant:)` is the "from" price. `values(of:)` gives one entry per size. `stock` and `inStock` take a + `location`, so alias one per stock location. +- `variantGroups { images }` takes no arguments, and was about 70 % of one listing's payload. Prefer + `representative { firstImage }`, and trim renditions as [[responsive-images]] shows. +- Group keys can contain spaces and slashes, so URL-encode them in links. +- Tenant fields on a variant need the generated type: `... on ProductVariantForTool { gtin }`. +- On the product page, `variant(selected: [{ attribute: "colour", value: "Red" }])` gives the first variant that + carries every pair; its `sku` goes into the Shop API `hydrate`. Attribute names and values are case-sensitive. +- `variants(skus:)` takes **one** SKU, and a comma list returns `[]` silently. Use `variants(filter:)` for several. + +### Facets and generated filter fields + +Facets are in `summary { facets }`, a `Hash`. A selection component becomes **one field per option** +(`specs_extraction_dustClass_m`), filtered with `{ exists: true }`; a numeric is `_number`, filtered with +`range`. `NumberFacet` requires `boundaries`. The naming rules, value shapes and operator traps are in +[Generated field names](references/discovery-api.md#generated-field-names). + +**Unset booleans come back `false`.** A boolean component that was never written reads `false` on the hit, so a page, +JSON-LD or an agent can't tell "no" from "not stated" by the value. `equals: false` does **not** match the unset ones; +`exists: false` and `not_equals: true` do. Treat `false` as "not stated" when publishing facts, and don't write +`false` for "unknown" ([[content-model]], [[seo-geo]]). + +### Prices and stock + +| Need | Field | +| ----------------------- | ------------------------------------------------------------------------------------------------------------ | +| List price | `Price` (`nokPrice`, `defaultPrice`), the `priceVariants` hash, `PriceTiers` | +| "From" price on a card | `variantGroups.summary.price(variant:)`; sort and filter on `price_` | +| Public market price | `PriceFor(marketIdentifiers: [...])`, `BestPriceListFor(marketIdentifiers:)` | +| Stock shown on the page | `Stock` per variant (`oslStock`), the `stockLocations` hash; filter on `stock_` | +| Contract price (B2B) | **Not Discovery.** The Shop API cart for that customer, or the Catalogue fallback, server-side ([[pricing]]) | + +Market prices are slow (about 1.4 s per 100 products per market), so read them only for the SKUs on screen. A new +stock location needs a re-ignite before its field exists. + +### Paths per language: hreflang and sitemaps + +Discovery has no `hreflangs` field. Read the item's path in every language with one aliased query by `itemId`: + +```graphql +query Paths($id: String!) { + en: search(language: en, filters: { itemId: { equals: $id } }) { + hits { + path + updatedAt } + } + no: search(language: no, filters: { itemId: { equals: $id } }) { hits { - name path - ... on product { - defaultVariant { - defaultPrice - } - } + updatedAt } } } ``` -### Catalogue API (Path-Based Reads) +Empty `hits` mean the item has no version in that language, so leave that alternate out. A sitemap is one `browse` +per language joined on `itemId`, with `updatedAt` as `lastModified`; it is on every hit. Map tenant language codes to +BCP 47 (`no` → `nb`) and add `x-default`: see [[information-architecture]] and [[seo-geo]]. -Use for deterministic reads when you know the exact path: +### Draft preview ```graphql -{ - catalogue(language: "en", path: "/shop/plants") { - name - ... on Product { - variants { - sku - name - price - } +query Preview($path: String!) { + search(language: en, publicationState: draft, filters: { path: { equals: $path } }) { + hits { + name + publicationState + updatedAt } } } ``` -### Shop API Queries +`publicationState: draft` works on `search`, `autocomplete` and every `browse.`, and the hits report +`publicationState: "draft"`. Draft preview is this Discovery read, run on the server behind editor login and +**never cached**. + +> **On an open Discovery, every draft is public.** `publicationState: draft` needs no credential there: tools-universe +> returned its 541 draft documents to an anonymous request, and another tenant served an unpublished page the same +> way (2026-11-12). Never keep confidential content, prices or embargoed launches in drafts on an open tenant. To +> keep drafts private, restrict Discovery, run `igniteDiscoApi` (the setting does not reach Discovery before that, +> and takes a few more minutes after), and send `X-Crystallize-Static-Auth-Token` from the server only. The access +> token pair was refused there. -Retrieve cart and order intent data: +### Consistency + +Publishing is asynchronous. New shapes and components need an ignite. A new schema reaches the nodes over minutes, +and an error answered in that window is cached per query body. Under heavy load Discovery answers HTTP 200 with +`errors: [{ message: "Response Error" }]`. Ship code that reads a new field only after the field answers reliably, +make cached reads fail-safe, and retry on "Response Error". Details in +[Discovery Indexing](references/discovery-indexing.md). + +## Shop API reads + +All Shop API reads run on the server, with the JWT above. ```graphql +# POST https://shop-api.crystallize.com/{tenant}/cart query { cart(id: "cart-id") { id + state items { variant { sku } - name quantity price { gross @@ -242,35 +284,110 @@ query { total { gross net + currency } } } ``` +- `items.price` on a cart is the **line total**; order lines carry the unit price. +- `/order`: read anything you just wrote with `order(id: UUID!)`, and the shopper's history with + `orders(customerIdentifier:, limit: 100)`. **The listing is a second, eventually consistent store**: new orders + appear after seconds to minutes, a few never did, and `limit`/`skip` paging is inconsistent. Group by `coreId`. Take + the identifier from the session, never from the client. See + [Shop API Order Queries](references/shop-api-order-queries.md). +- `/customer`: `customer(identifier:)`. `/subscription-contract`: `subscriptionContracts(customerIdentifier:)`, on + tenants whose contracts live on the Shop API ([[subscriptions]]). +- Booking availability is a Shop `/cart` read, and Discovery never serves it ([[bookable-resources]]). + +## Catalogue API (fallback) + +Use it for what Discovery and the Shop API can't do: showing a **specific customer's** price-list price on a page, +server-side, cached per organisation, and reads that must be in sync with a publish (Discovery is asynchronous). + +```graphql +query ContractPrice($skus: [String!]!, $customers: [String!]) { + productVariants(skus: $skus, language: "en") { + sku + priceVariant(identifier: "nok") { + priceFor(count: 1, customerIdentifiers: $customers) { + price + identifier + } + } + } +} +``` + +Don't use it for path reads, listings, preview or hreflang. See [Catalogue API](references/catalogue-api.md). + +## Core API reads (back office only) + +Core is for admin dashboards, seller and approval queues across customers, imports and reporting, behind your own +server and staff login. It filters orders by `meta`, `pipelineStageIds`, SKU or payment provider, which the Shop API +can't. No Core query takes a `tenantId`, and most root fields return a union, so always select +`... on BasicError { errorName message }`. + +```graphql +query ListOrders { + orders( + first: 20 + filter: { customer: { identifier: "customer@example.com" } } + sort: { field: createdAt, direction: desc } + ) { + ... on OrderConnection { + edges { + node { + id + total { + gross + currency + } + } + } + } + ... on BasicError { + errorName + message + } + } +} +``` + +See the [Core API Queries Reference](references/core-api.md). + ## Best Practices -1. **Choose the right API** - Core for admin, Discovery for storefront search, Catalogue for path-based reads -2. **Use Discovery API for storefronts** - It's optimized for performance and supports search/filter -3. **Include deterministic sorting** - Always add a secondary sort field (like itemId) for stable pagination -4. **Request only needed fields** - GraphQL allows precise field selection to minimize payload -5. **Handle async updates** - Discovery API may have sub-second delay for recently published content -6. **Protect APIs in production** - Configure authentication for sensitive data -7. **Use Core API for complex filters** - Only Core API supports filtering orders by SKU, payment provider, stage or meta; the Shop API lists them by customer alone -8. **Detect the Discovery schema, don't hardcode it** - Filter/sort/facet fields and the ranking arguments are tenant-generated; introspect before building a query -9. **Keep Core out of the storefront** - Storefront reads are Discovery/Catalogue, and carts, orders, customers and subscription contracts are the Shop API -10. **Scope `customerIdentifier` on the server** - The Shop API token is per tenant, not per shopper: `orders(customerIdentifier:)` answers for any identifier it is given, so take it from the session and never from the client -11. **Read an order list through one store** - Orders registered in Core and edited there appear more than once in the Shop API's list; group by `coreId` and keep the newest copy (see the [Shop API Order Queries Reference](references/shop-api-order-queries.md)) +1. **Follow the contract** - Discovery for catalogue reads, the Shop API for shopper data, Catalogue only for + per-customer prices and in-sync reads, Core never in the request path +2. **Detect the Discovery schema, don't hardcode it** - Introspect filter, facet, sort and ranking fields after each + ignite +3. **Leave optional arguments out** - Never send `null` to Discovery or the Shop API +4. **Sort with one key, or check the order** - Sort keys apply in schema order, so a secondary `itemId` can replace a + primary that sorts after it. `score` is safe as the primary, and `{ itemId: asc }` alone is stable for full scans +5. **Request only needed fields** - `facets` cost about 17 KB per read, and image ladders dominate listings; skip + them in rails and menus +6. **Treat unset booleans as "not stated"** - `false` on a hit may mean never written +7. **Scope `customerIdentifier` on the server** - The Shop JWT is per tenant, not per shopper +8. **Read what you just wrote by id** - `order(id:)`, never the listing, and never the listing for idempotency +9. **Keep confidential prices off Discovery** - When it is open, everything it serves is public +10. **Expect lag after publishing and model changes** - See [Discovery Indexing](references/discovery-indexing.md) ## References -- [Core API Queries Reference](references/core-api.md) - Items, customers, orders, shapes with advanced filtering -- [Discovery API Reference](references/discovery-api.md) - Search, browse, autocomplete, filters, facets, sorting, fuzzy matching, pagination and profiling -- [Catalogue API Reference](references/catalogue-api.md) - Path-based query documentation -- [Shop API Queries Reference](references/shop-api-queries.md) - Tokens and scopes, cart and checkout queries (`/cart` endpoint), customers and subscription contracts -- [Shop API Order Queries Reference](references/shop-api-order-queries.md) - Order queries by ID or customer (`/order` endpoint) +- [Discovery API Reference](references/discovery-api.md) - Search, browse, autocomplete, generated field names, value + shapes, filters, facets, variants and variant groups, prices, sorting, pagination, paths per language, drafts +- [Discovery Indexing](references/discovery-indexing.md) - Ignite, publish lag, schema propagation, cached errors, + relations and media at index time, load errors, verifying that a change landed +- [Catalogue API Reference](references/catalogue-api.md) - The per-customer price fallback and its known failure +- [Shop API Queries Reference](references/shop-api-queries.md) - Routes, tokens and scopes, carts, customers, + subscription contracts +- [Shop API Order Queries Reference](references/shop-api-order-queries.md) - Orders by id or customer, and the order + store's lag +- [Core API Queries Reference](references/core-api.md) - Back-office reads: items, customers, orders, shapes ## Related skills -Reading is only half of it — [[mutation]] covers writes across the same APIs, and [[js-api-client]] -wraps all of them for JS/TS. For ranking Discovery results by relevance rules, a shopper's taste, or -similarity to another item, use [[vector-ranking]]. +[[storefront]] owns the request path per page type and the full API decision table. [[mutation]] covers writes on the +same APIs, and [[js-api-client]] wraps them for JS/TS. Ranking, personalisation and similarity are in +[[vector-ranking]], prices for markets and customers in [[pricing]], and image renditions in [[responsive-images]]. diff --git a/use-crystallize/skills/query/references/catalogue-api.md b/use-crystallize/skills/query/references/catalogue-api.md index d674208..35ea263 100644 --- a/use-crystallize/skills/query/references/catalogue-api.md +++ b/use-crystallize/skills/query/references/catalogue-api.md @@ -1,6 +1,8 @@ # Catalogue API Reference -The Catalogue API provides path-based access to items in your Crystallize tenant. It offers strong consistency for deterministic reads. +The Catalogue API provides path-based access to items in your Crystallize tenant. In a storefront it is a +**fallback for one named task**: showing a specific customer's price-list prices. Every other catalogue read, +including item by path, draft preview and hreflang, goes to the Discovery API ([[storefront]]). ## Base URL @@ -19,17 +21,29 @@ By default, the API is accessible without authentication. You can configure acce 3. Save changes A restricted Catalogue API takes the `X-Crystallize-Static-Auth-Token` header, or -`X-Crystallize-Access-Token-Id` and `X-Crystallize-Access-Token-Secret`, depending on the level chosen. +`X-Crystallize-Access-Token-Id` and `X-Crystallize-Access-Token-Secret`, depending on the level chosen. A missing or +wrong credential answers HTTP 400 `Invalid static auth token`, not 401 as Discovery does. Inside a Shop API `hydrate`, +which reads products from the Catalogue, it shows up as a GraphQL error on `hydrate`. Unlike Discovery, the setting +takes effect at once. ## When to Use Catalogue API -Use the Catalogue API when you need: +| Task | Use | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| A specific customer's price-list price, for display | **Catalogue**, server-side, cached per organisation ([Prices for one customer](#prices-for-one-customer)) | +| Item by path, listings, search, facets, variants | Discovery `search(filters: { path: { equals } })`, `browse` | +| Editor draft preview | Discovery `publicationState: draft` | +| hreflang, translated paths, sitemaps | Discovery, one aliased query per language by `itemId` | +| The price this customer pays in a cart | Shop API `hydrate` with the customer on the cart ([[pricing]]) | +| A back-office check that a publish landed | Catalogue (or Core) by path, from a script | -- **Deterministic exports** - Payload must reflect exact current state -- **Path-based reads** - You know the exact path to the item -- **Strong consistency** - Cannot tolerate async delays +**It is not a peer of Discovery.** On three tenants (Screen Universe and two others) `variants` came back `[]` on +products while `defaultVariant` worked, so a product page built on it showed one variant or none. It did not +reproduce on tools-universe (2026-11-12). If you read variants here at all, check for an empty list. -For search, filtering, and faceting, use the Discovery API instead. +Its stronger consistency is a reason to use it in **seed and verification scripts** (did every path publish?), not +in the storefront's request path. A storefront that falls back to Catalogue whenever Discovery lags gets two code +paths and two failure modes for one page. ## Query Structure @@ -45,7 +59,8 @@ For search, filtering, and faceting, use the Discovery API instead. } ``` -`catalogue` also takes `version` (`published` by default, or `draft`) and `pathResolutionMethods`. That one +`catalogue` also takes `version` (`published` by default, or `draft`; for editor preview use Discovery's +`publicationState: draft` instead) and `pathResolutionMethods`. That one defaults to `[canonical]`, so an alias, a historic path or a shortcut answers `null` unless you ask for `alias`, `history`, `shortcut` or `any`. @@ -190,9 +205,10 @@ Use the Discovery API for these capabilities. ## Prices for one customer -The Catalogue API is the only storefront API that resolves a price list for a **customer**. Discovery knows -markets only, so this is where a B2B storefront reads an account's agreed prices — server-side, cached per -organisation: +This is the task the Catalogue API is still for. Discovery knows markets only. The Shop API resolves a customer's +price list for **the cart's** customer (inherited from parent customers), which a throw-away `hydrate` can use as a +price check. The Catalogue API resolves it for **any** customer you name, so this is where a B2B storefront reads an +account's agreed prices for display: server-side, cached per organisation, never from the browser. ```graphql query ContractPrice($skus: [String!]!, $customers: [String!]) { @@ -215,3 +231,13 @@ query ContractPrice($skus: [String!]!, $customers: [String!]) { `marketIdentifiers`. A percentage list applies on top of the variant's volume tiers, and a list aimed at an organisation resolves for its child customers too — see [[pricing]] for the measurements and the caveats (`productVariants(skus:)` caps at 150 SKUs, and `priceFor` is slow enough to need caching). + +**Size and speed** (Lab Universe): + +- `productVariants(skus:)` takes at most 150 SKUs (`TOO_MANY_SKUS_PROVIDED`), and `priceFor` took about 2 s per + 150 SKUs. +- For a whole agreement, read the list once instead: `priceList(identifier:) { productVariants(language:, first:) + { edges { node { sku priceVariant(identifier:) { priceList(identifier:) { modifier modifierType } } } } } }` took + 3.5 s for 2,211 SKUs. Its `pageInfo.hasNextPage` stays `true` past the last SKU, so stop on an empty page. +- Either way, cache per organisation, and apply the cached rules to the Discovery prices on the page. A slow cache + miss during a Next.js prerender is cut off. diff --git a/use-crystallize/skills/query/references/core-api.md b/use-crystallize/skills/query/references/core-api.md index d6bcc81..bd1d54c 100644 --- a/use-crystallize/skills/query/references/core-api.md +++ b/use-crystallize/skills/query/references/core-api.md @@ -49,11 +49,10 @@ curl -X POST 'https://api.crystallize.com/@your-tenant' \ - Customer management - Bulk data access -**Use Discovery/Catalogue API for:** - -- Storefront product listings -- Search and filtering -- Public content access +**Never in a storefront's request path.** Core is heavily rate limited, so it runs in seeds, imports, scheduled +jobs, webhook receivers and admin or seller tools behind staff login, on your own server. A storefront reads the +catalogue from Discovery and shopper data (carts, orders, customers) from the Shop API; see the contract in +[[storefront]] and the query skill's SKILL.md. ## Reading a Core Response @@ -64,7 +63,8 @@ fails the whole request with a validation error. - **The root fields below return a union.** Select the result with `... on ` and the failure with `... on BasicError`; `items(...) { edges }` without a fragment does not validate. The list types are `ItemConnection`, `CustomerConnection`, `CustomerGroupConnection`, `OrderConnection`, `PieceConnection`, - `FlowContentConnection`, `ArchivedItemVersionConnection`, `BulkTaskConnection` and `ImageConnection`. + `FlowContentConnection`, `ArchivedItemVersionConnection`, `BulkTaskConnection`, `ImageConnection` and + `PriceListConnection` (`priceLists`). `tenant(identifier:)` needs `... on Tenant` the same way. `shapes` is the exception: it returns a plain `ShapeConnection`. - **`content` and `config` are unions too.** Give `content` one fragment per component type you expect. The names carry `Component` here (`RichTextComponentContent`), unlike the Catalogue API (`RichTextContent`). diff --git a/use-crystallize/skills/query/references/discovery-api.md b/use-crystallize/skills/query/references/discovery-api.md index ea07604..57aa646 100644 --- a/use-crystallize/skills/query/references/discovery-api.md +++ b/use-crystallize/skills/query/references/discovery-api.md @@ -1,7 +1,9 @@ # Discovery API Reference -The Discovery API is the primary API for powering storefronts with product information and marketing -content. It is a read-only API optimized for high performance. +The Discovery API is a storefront's catalogue API. Every catalogue read goes here: item by path, listings, search, +facets, variant groups, prices, stock, translated paths, and drafts for preview. It is read-only and eventually +consistent ([Discovery Indexing](discovery-indexing.md)). Which API serves the rest of a storefront is in +[[storefront]]. ## Base URL @@ -14,17 +16,39 @@ belongs to the Core API). ## Authentication -By default, the Discovery API is open. Restrict it with the **Search & Discovery** entry under Settings → API -Access, which is separate from the Catalogue entry, then send the tenant's static token: +By default, the Discovery API is open, and its CORS allows any origin, so a browser can call it. Restrict it with +the **Search & Discovery** entry under Settings → API Access. Discovery shares that setting with the Search API; it is +separate from the Catalogue entry, so restricting one does not restrict the other. -``` -X-Crystallize-Static-Auth-Token: YOUR_STATIC_TOKEN -``` +| Tenant setting | Published reads | Drafts (`publicationState: draft`) | +| -------------- | ------------------------------------------------------------------------------- | --------------------------------------- | +| Open (default) | Nothing | Nothing: **drafts are public** | +| Restricted | `X-Crystallize-Static-Auth-Token: `; missing or wrong answers 401 | The same static token, server-side only | + +The static token is the one credential Discovery is known to read, and a bearer token is ignored. With Search & +Discovery set to `accessTokenPair`, Discovery still took the static token and refused the access token pair (sandbox +tenant, 2026-11-16); with `staticToken` it refused the pair too. Send the static token whichever mode is set. -That header is the only credential Discovery reads, whichever restricted level the entry is set to, so an -access token pair is not accepted. A missing or wrong token answers HTTP 401. +**A change of the setting reaches Discovery only after an ignite.** The Search API follows it at once; Discovery does +not. Change the setting, run `igniteDiscoApi`, poll the bulk task until it is `complete`, then wait for several +refusals in a row before you rely on it: + +- Without an ignite, Discovery stayed open to anonymous reads for at least ten minutes. +- The ignite took 40–75 s. After it, anonymous calls flapped between 200 and 401 for about four more minutes, + while the nodes caught up. +- After that, one query body (a contract price) still answered 200 once, which looks like a cached response for + that body. Drafts and prices can stay readable for a few minutes after the change. +- Opening Discovery again needs an ignite too. + +```graphql +mutation { igniteDiscoApi(stacks: opensearch) { __typename ... on BulkTask { id status } } } +query ($id: ID!) { bulkTask(id: $id) { ... on BulkTask { status } } } +``` -> **Important**: Always secure your API with authentication in production environments. +**When Discovery is open, everything it serves is public**: every price variant (`nokPrice`, `wholesalePrice`), +every market's price list through `…PriceFor(marketIdentifiers:)` to anyone who knows the identifier, and every +draft. Never put confidential terms such as negotiated B2B prices in it ([[pricing]]), and never keep confidential +content or embargoed launches in drafts on an open tenant. ## The schema is generated per tenant @@ -50,6 +74,67 @@ it with the tenant identifier. `{ __typename }` is the cheapest check that a ten > `... on category`) because types are derived from your shape identifiers. Interface fragments keep > their capital (`... on Product`, `... on Folder`, `... on Document`). +## Generated field names + +Nothing in the schema says which component or option a generated field belongs to, so builds kept deriving names and +getting them wrong. The rules seen across builds (introspect `TenantFilter`, `Filter` and `TenantRankByField` +after each ignite to confirm them): + +| Source | Field | Filter with | +| -------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------ | +| Component in a piece | `_` (`physical_beltHook`) | its type's filter | +| Piece inside a `componentChoice` | `__` (`specs_drilling_gears_number`) | its type's filter | +| Numeric | `_number`, and `Unit` on hits | `range: { gte, lte }` | +| Boolean | `` | `equals`, `exists` | +| Selection, single or multiple | **One field per option**: `_` (`specs_extraction_dustClass_m`) | `{ exists: true }` (`false` for "without") | +| Variant component | `variants_` (`variants_gtin`, `variants_durationHours_number`) | its type's filter | +| Price variant, stock location | `price_`, `stock_` (one value per variant) | `range` | +| Shape type | the shape identifier in camelCase (`machineUnit`; `product` stays lowercase) | `shape: { equals }` | + +- **Ids and option keys are camelCased, except that a hyphen before a digit becomes `_`**: `sds-plus` → `sdsPlus`, + `keyless-13` → `keyless_13`, `core-1-1-4-unc` → `core_1_1_4Unc`, `sold-30d` → `sold_30d_number`, but + `gwp-a1-a3` → `gwpA1A3_number`. The field name doesn't spell the selection's own key (`ull-silke` → + `woolSilk`), so map options from the field list rather than by hand. +- `{ variants_markets: { in: [...] } }` on a multi-selection is rejected: use the per-option fields with `exists`. +- **A selection field holds the option's label**, and its facet is keyed by the **label**, with the option key as + `label`: `{ "SDS-plus": { "count": 14, "label": "sds-plus", "filter": "specs_concrete_toolHolder_sdsPlus" } }`. +- A component called `type` becomes `component_type`. Nested numerics are named after the component id on the + shape, not the piece's own id. +- The same field name with two types on two shapes must be aliased in one query (`a: price` / `b: price`), or the + query fails validation. +- There is no "has this choice" filter on a `componentChoice`. To find the products of one spec family, `OR` an + `exists: true` over that family's fields. + +## Shapes of values + +| Value | Comes back as | +| --------------------- | -------------------------------------------------------------------------------------------------------- | +| Selection | A `Hash` `{ key: label }` (`{ "sds-plus": "SDS-plus" }`), not a list | +| Item topics | `topics`: a `Hash` of the leaves with labels (use it for chips); `topicPaths`: every ancestor, unordered | +| Image topics | A flat hash of every ancestor path (`{ "0": "/bilde", "1": "/bilde/type", … }`) | +| Content chunk | An object when not repeatable, a list when repeatable | +| `paragraphCollection` | A flat list | +| Rich text | A scalar; ask for a format with `format:` | +| `breadcrumbs` | A list of lists (one per path to the item), each ending with the item itself | +| Boolean never written | **`false`**, see below | +| Colors | A plain list | + +Selection labels come back in the editor language, so a multilingual storefront localises option labels itself. + +**Unset booleans read `false`.** A boolean component that was never written comes back `false` on the hit. Measured +on tools-universe (2026-11-12) for `physical_beltHook`: 30 items set it to `true`, none to `false`, and the other 510 +read `false`. + +| Filter | Matches | +| ------------------ | ------------------------------------- | +| `equals: true` | items where it was written `true` | +| `equals: false` | only items where `false` was written | +| `exists: false` | items where it was never written | +| `not_equals: true` | written `false` **and** never written | + +So JSON-LD, feeds and agent filters must treat `false` as "not stated", and a model should not write `false` for +"unknown" ([[content-model]], [[seo-geo]]). + ## Queries | Query | Use for | @@ -137,7 +222,7 @@ Hits are polymorphic — use one inline fragment per shape, and read `shape` to ```graphql { - search(language: en, term: "plop") { + search(language: en, term: "plop", sorting: { score: desc }) { hits { name path @@ -146,6 +231,14 @@ Hits are polymorphic — use one inline fragment per shape, and read `shape` to } ``` +- **`term` matches whole words only**: "drill" does not find "drills" or "hammerdrill". Add fuzzy options for typos, + and the autocomplete filter for prefixes (below). +- **Search is per language.** A Norwegian term on `language: en` finds nothing. +- **A `term` is expensive**: full-text reads took 0.4-0.9 s where filter-only reads took under 0.1 s. Search once for + the ids, and read the page's details by id with filters. +- With `rankBy`, the ranking signals **replace** text relevance. Add `{ signal: relevance }` to the terms whenever + there is a `term` ([[vector-ranking]]). + ## Filter operators Filters compose with `AND` and `OR`, each taking a list of nested filters. @@ -159,8 +252,25 @@ Filters compose with `AND` and `OR`, each taking a list of nested filters. | `BooleanFilter` | `exists`, `equals`, `not_equals` | | `GeoFilter` | `exists`, `within: { box, circle, polygon }` — on Location components | -`type_in: [ItemType]` (`product`, `document`, `folder`) is the common way to narrow a `search`. It exists on -`TenantFilter` only: a shape's own filter has no use for it. +`type_in: [ItemType]` (`product`, `document`, `folder`) is the common way to narrow a `search`. It is a top-level +key of `TenantFilter` only: a shape's own filter has no use for it. + +Operators that differ from what builds expected: + +- **There is no `prefix`.** `regex` is anchored and must match the whole value: on tools-universe `sku: { regex: + "4885" }` matched 0 items and `"4885.*"` matched 2. +- `NumberFilter` has `range: { gt, gte, lt, lte }`, not `lte` at the top level. +- Filter on `itemId`, not `id`: the hit `id` is the document id (`--`). +- `sku: { in: [...] }` filters products by SKU. There is no `variants` filter; use the `variants_*` fields, or + `variants(filter:)` on the hit. +- Topics: `topics: { equals: "/city/helsinki" }`, a plain `StringFilter` on the path; there is no `topics_path`. + Two builds found no `topics` key on `browse.` filters, while tools-universe has one (2026-11-12): check the + shape's filter type, and fall back to `search` with `type_in` or to generated fields. +- `parentPaths: { equals: "/shop" }` matches every descendant of `/shop`; `parentId` matches direct children. +- `not_equals` keeps documents that have no value at all, and so does `exists: false`. See + [unset booleans](#shapes-of-values). +- **Explicit `null` is rejected** for `after`, `term`, `context`, `sorting`, `filters` and `rankBy`. Leave the key + out. ## Typo tolerance (fuzzy search) @@ -338,7 +448,7 @@ component fields available directly. This is the recommended approach for storef ```graphql { browse { - product(language: en, sorting: { price_default: asc, itemId: asc }) { + product(language: en, sorting: { price_default: asc }) { hits { name path @@ -351,8 +461,13 @@ component fields available directly. This is the recommended approach for storef **With no `sorting`, hits come back by `itemId` descending, not by relevance**, even with a `term`. Send `sorting: { score: desc }` to order by relevance. -**Always add a deterministic secondary field** (such as `itemId`) so pagination stays stable across -pages. Note that `sorting` does **not** compose predictably with ranking — see below. +**Sort keys apply in schema order, not in the order you write them.** In `{ price_default: asc, itemId: asc }`, +`itemId` comes before the price fields in `TenantSort`, so it became the primary key and the price order was lost +(one build; reproduced on tools-universe, 2026-11-12). Use one key per sort, or check the field order in the generated sort input before adding a second. +`score` is first, so it is safe as the primary. For a full scan, `{ itemId: asc }` alone gave stable cursor paging. +Note that `sorting` does **not** compose predictably with ranking, see below. + +In an `asc` price sort, items without a price come **first**. Filter them out with `exists: true` when that matters. `price_default` holds one value per variant. For one value per product, sort or filter on `defaultVariantPrice_default`, `lowestVariantPrice_default` or `highestVariantPrice_default`. @@ -388,12 +503,22 @@ Use `paginationToken` (returned as `endToken` in summary) for efficient, consist 3. Stop when `summary.hasMoreHits` is `false` **or** `hits` is empty. The last page can still read `hasMoreHits: true`, and the empty page after it has no `endToken` to send -`pagination` accepts `limit`, `after`, `before` and `skip`. +`pagination` accepts `limit`, `after`, `before` and `skip`. The summary field is `endToken`; there is no +`endCursor` (alias it if your code expects one). > **Note**: `skip`-based pagination is deprecated for ordinary queries. Use cursor-based pagination > (`after`). `skip` becomes increasingly expensive on large result sets. **The exception is ranked > queries** — see below. +- **Page size**: `limit: 500` worked on one tenant, and `limit: 1000` returned all 540 documents of tools-universe in + one page (2026-11-12). No cap was hit below that; page anyway for anything larger. +- `limit` is ignored under `nearestTo`. +- Many aliased lookups in one request scale badly: batch about 25 aliases per request. +- **A full scan can come back incomplete** during re-indexing: four passes over one 590-product tenant returned + 173, 590, 556 and 375 hits, with `hasMoreHits: false` too early. For "every product" (a sitemap, an index), retry, + take the union of passes, and check the count against `search { summary { totalHits } }` + ([Discovery Indexing](discovery-indexing.md#under-load)). + ## Faceting Get counts for filter values. `StringFacet` takes `key` and `limit`; `NumberFacet` and `DateFacet` also @@ -415,6 +540,13 @@ require `boundaries`. `summary.facets` is a `Hash`, and accepts an optional `key` argument to pull a single facet out. +- A selection facet is keyed by the option **label**, with the key as `label` (see + [Generated field names](#generated-field-names)). +- The `topics` facet counts every level of the path, and its `limit` defaults to 10 across all topic maps together: + raise it, or the second map's topics never show. +- A `parentPaths` facet on a category listing gives its subfolders with counts. +- Facets cost about 17 KB per read. Leave them out of rails, menus and anything that doesn't render filters. + `summary.priceRange(priceIdentifier: "default", quantity: 1) { min max }` gives the price bounds of the current result set — useful for a range slider that matches the active filters. @@ -463,6 +595,112 @@ or pagination: groups with a matching variant come first, the others read `match and values are case-sensitive. A key that only matches in another case changes nothing in the result and adds a warning under `extensions.warnings`. +What a `ProductVariantGroup` carries (introspected on tools-universe, 2026-11-12): + +| Field | Notes | +| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `key`, `matched`, `attributes` | The group's attribute values; URL-encode `key` in links | +| `representative(pick:, priceVariant:)` | `DEFAULT` (default, else first in stock, else first), `FIRST_IN_STOCK`, `CHEAPEST` (for `priceVariant`), `FIRST` | +| `summary { count matchedCount inStock(location:) matchedInStock(location:) price(variant:) matchedPrice(variant:) }` | `price` is the "from"/"to" range for a card | +| `values(of:) { value sku matched inStock(location:) stock(location:) }` | One entry per value of another attribute (sizes); alias one `stock` per location | +| `variants(first:, filter:)` | The group's variants | +| `images`, `videos` | No arguments: every image of every variant in the group | + +- **`images` on a group is the payload trap**: it takes no rendition filter and was about 70 % of one listing's + bytes. On a card, use `representative { firstImage { variants(types: "webp", minWidth:, maxWidth:) } }`. Repeated + `variants { images }` on a 260-size product made 24 cards 8.2 MB ([[responsive-images]]). +- **Product-level variant filters can be satisfied by two different variants.** "Red and in size M" matches a + product with a red S and a blue M. Use `variants(filter:)` or `variantGroups(filter:)` to require one variant. +- `variants(skus:)` takes **one** SKU (`String`); a comma-separated list returns `[]` silently. `variants` is not + paginated on the product. +- Variant components need the generated type: `... on ProductVariantFor { }`. +- `variant(selected:)` answers `null` when no variant carries every pair. On a product page, feed it the chosen + options, then send its `sku` to the Shop API `hydrate`. + +## Prices and stock on a variant + +Every price variant and stock location becomes its own set of fields on `ProductVariant`. For a price variant `nok`: + +| Field | Gives | +| ------------------------------------------------------------------- | ------------------------------------------------------------- | +| `nokPrice(count:)` | The list price (at a quantity, for tiers) | +| `nokPriceTiers`, `nokPriceTierType` | Volume tiers | +| `nokPriceFor(marketIdentifiers:, count:)` | The lowest price for those markets' price lists | +| `nokBestPriceListFor(marketIdentifiers:)` | Which list applied (`identifier`, `modifier`, `modifierType`) | +| `nokPriceForEveryone`, `nokBestPriceListForEveryone` | Lists aimed at everyone | +| `priceVariants`, `priceVariantFor(identifier:, marketIdentifiers:)` | The same by identifier, as a hash or one value | +| `Stock` (`oslStock`), `stockLocations` | Stock per location; `stock_` to filter | + +- **Market prices are slow**: about 1.4 s per 100 products per market (one tenant). Read them only for the SKUs on + screen, never for a whole listing, and cache per market. `…PriceForEveryone` is slow under build load too. +- Discovery knows **markets only**. A price for a specific customer is a Shop API (cart) or Catalogue read, on the + server ([[pricing]]). +- A new stock location or price variant needs a re-ignite before its fields exist + ([Discovery Indexing](discovery-indexing.md)). + +## Paths per language (hreflang, sitemaps) + +There is no `hreflangs` field. The same item's path in each language comes from one aliased query by `itemId` +(verified on tools-universe, 2026-11-12): + +```graphql +query Paths($id: String!) { + en: search(language: en, filters: { itemId: { equals: $id } }) { + hits { + path + } + } + no: search(language: no, filters: { itemId: { equals: $id } }) { + hits { + path + } + } + sv: search(language: sv, filters: { itemId: { equals: $id } }) { + hits { + path + } + } +} +``` + +- Paths follow the translated names (`/drilling-and-driving`, `/boring-og-skruing`), so localised URLs need nothing + more. Empty `hits` in a language means there is no version there: leave that alternate out. +- A sitemap is one `browse` (or `search`) per language joined on `itemId`. +- **`updatedAt` is on every hit and is the sitemap's `lastModified`.** It was the same in every language for the + same item on tools-universe. +- `aliases`, `history` and `shortcuts` are on every hit too: 301 from `history` after a rename, and keep old paths + out of the sitemap. Tenant language codes are not BCP 47 (`no` → `nb`). See [[information-architecture]] and + [[seo-geo]]. + +## Drafts (`publicationState`) + +`publicationState` is `published` (the default) or `draft`, on `search`, `autocomplete` and every `browse` field. +Hits report `publicationState`, and a draft hit carries the draft's `updatedAt` and `publishedAt: null`. + +```graphql +query Preview($path: String!) { + search(language: en, publicationState: draft, filters: { path: { equals: $path } }) { + hits { + name + path + publicationState + updatedAt + } + } +} +``` + +Draft preview is this read, run from a server route behind editor login, and never cached. + +> **On an open Discovery, every draft is public to anyone who asks.** No credential is needed: tools-universe +> returned the same 541 draft documents (`publicationState: "draft"`, `publishedAt: null`) with and without an +> access token, on `search` and `browse`, in two languages, and another tenant served an unpublished page to an +> anonymous request (2026-11-12). To keep drafts private, restrict Discovery, re-ignite +> (see [Authentication](#authentication)) and send `X-Crystallize-Static-Auth-Token` from the server only. + +Draft documents are indexed like published ones, so the same eventual consistency applies: a draft saved a moment +ago may not be served yet. + ## Ranking, personalization and similarity Ranking-enabled tenants additionally accept `rankBy`, `context` and `nearestTo`, and expose `rankScore` @@ -505,17 +743,16 @@ Every query can report how it was served: ## Async Updates -The Discovery API is asynchronously updated from your published data and therefore eventually -consistent: - -- Typical delay: under 1 second -- Large imports may take longer to surface -- A full re-index (`igniteDiscoApi`) takes minutes, not seconds, to propagate - -For cases requiring exact current state, use the Catalogue API instead. +The Discovery API is updated asynchronously from published data, so it is eventually consistent. A content edit +usually shows within seconds, but publishing answers before anything is published, new shapes and components need an +ignite, schemas roll out over minutes, errors are cached per query body, and relations and media are snapshotted at +indexing time. All of it, with what to do, is in [Discovery Indexing](discovery-indexing.md). The Catalogue API is +not the fix for any of it. ## Related Links +- [Discovery Indexing](discovery-indexing.md) — ignite, publish lag, propagation, load errors +- [[storefront]] — which API a storefront calls for each task - [[vector-ranking]] — ranking, personalization and similarity - [Crystallize Discovery API Documentation](https://crystallize.com/docs/developer/apis/discovery-api) - [Demo tenant: Furnitut](https://www.furnitut.com/) diff --git a/use-crystallize/skills/query/references/discovery-indexing.md b/use-crystallize/skills/query/references/discovery-indexing.md new file mode 100644 index 0000000..31e660d --- /dev/null +++ b/use-crystallize/skills/query/references/discovery-indexing.md @@ -0,0 +1,120 @@ +# Discovery Indexing and Consistency + +Discovery is an index built from published content, not a view of it. Most "Discovery is broken" reports in the +builds behind this file were indexing behaviour: a publish that had not landed, a schema still rolling out, or an +error cached per query body. This file says what is asynchronous, how long it took, and how a storefront and a seed +script live with it. + +> Measured on twelve builds, September to November 2026. Times are what those tenants saw, not guarantees. + +## The states a tenant goes through + +| State | What Discovery answers | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Never ignited | HTTP 404 with a plain JSON body, `{"success": false, "message": "There is no ignited Tenant for ."}`, not GraphQL `errors` | +| Ignited, shape has no discoverable field | The shape may have no type (contested: it may also be schema propagation, see below) | +| Ignite task complete | The new schema reaches the nodes over 5-10 minutes, unevenly: some requests see it, others don't | +| Serving | Published content edits show within seconds; publishes in bulk take minutes | + +A probe that only looks at `errors` misses the 404. `{ __typename }` is the cheapest check that a tenant is serving, +and `summary { profiling { queryEngine lastIndexCompletedAt } }` tells which engine answered and when the last full +index finished. `lastIndexCompletedAt` moves on an ignite, not on every publish. + +## Igniting + +`igniteDiscoApi(stacks: opensearch)` (Core) re-indexes the whole tenant. With `stacks: both` one tenant's task +completed while `profiling.queryEngine` stayed `atlas-search` and ranking never appeared; check `queryEngine` after +the task. Ignites are tenant-wide, so run one at a time and never build a storefront during one. + +**What needs an ignite** (a publish is not enough): + +- New shapes, and new or changed **discoverable** components on a shape. Republishing the items does not add the + field. One build needed a **second** ignite minutes after the first before a new content chunk appeared. +- New stock locations and price variants (their `Stock`, `Price` fields and filters). +- New vocabularies for ranking ([[vector-ranking]]). +- Removed shapes: their types linger for a few minutes after the task completes. + +**After an ignite, the schema reaches Discovery's nodes over minutes.** During that window the same query fails on +some requests (`Cannot query field "inTheBox"`, `Abstract type Document was resolved to a type … that does not +exist`) and succeeds on others. In one build, 4 of 10 introspection queries saw the new filter type and 6 answered +`null`. The rules: + +1. Wait 5-10 minutes before concluding a type or field is missing, and sample several times. +2. **Ship storefront code that queries a new field only after the field has answered ten times in a row.** +3. Coordinate model changes with deploys: the old code must not break on the new schema, and the new code must not + run before the schema is there. + +## Answers are cached per query body + +Discovery caches responses keyed on the query text, and that includes **errors**. A query that failed during the +rollout kept failing verbatim after the index was fine, while the same query with another operation name, another +field order or another `limit` succeeded. Successful answers are cached the same way: one build's verification query +kept answering 333 products for minutes while a renamed query answered the real 377. + +So verification scripts **vary the operation name** (or add a harmless variable) on every call, and a failure right +after a change is retested with a changed body before anyone concludes the schema is wrong. A Next.js dev server can +also keep serving a failed read from its own cache: restart it. + +## Publishing is asynchronous + +`publishItem` answers `PublishInfo` before anything is published. After 527 publishes per language at concurrency 6, +10-35 % of the items still had an older published version several minutes later, and Discovery's counts kept +climbing for about 10 minutes. A few `publishItem` calls answered success for items that never became published. +Republishing at once only adds to the queue. + +For a seed or an import: + +1. Publish, then wait until each item's **published version is at least as new as its draft** (Core + `item(id:, language:, versionLabel: published) { … }`), and republish only what still lags. +2. Then check Discovery counts against what you published, with a fresh operation name each time. +3. Only then ignite, if the run changed the model. + +Deleted items linger in Discovery for 1-3 minutes. Unpublishing follows the same path as publishing. + +## Relations, media and translations are snapshotted at indexing + +Discovery stores each document with what it resolved **when that document was indexed**: + +- **Relations resolve when the referencing item is indexed.** Collections published in the same run as their new + titles came into Discovery with those titles missing, and stayed so until the collections were published again. + Publish the targets first (people, products, folders), then the items that point at them, **in each language**: + a title published in `no` before its people had a Norwegian name listed none of them in `no`. +- **Images and video**: an item published before its image renditions or video playlists existed keeps + `variants: []`, `width: null` or `playlists: []` in Discovery until it is published again. Wait for the media to be + processed, then publish ([[media]]). +- **A replaced image** (`registerImageRevision`) shows in Discovery only once the items using it are re-indexed. +- **A component made discoverable after publishing** needs a republish (and the ignite above). +- Bookable products appeared in Discovery about a minute after publish, with no ignite. + +## Under load + +- **HTTP 200 with `errors: [{ message: "Response Error" }]`** came back after about 900 prerendered pages in one + build, on different pages each run, and during an ignite. Retry on that message as well as on 429 and 5xx, cap + prerender concurrency, or render on demand and cache instead of prerendering every page ([[storefront]]). +- **Totals and replicas flicker during re-indexing.** Counts differ between consecutive requests, and a full cursor + scan can stop early (`hasMoreHits: false` at 173 of 590). A complete index (sitemap, feed, llms-full.txt) needs + retries, the union of passes, and a check against `summary.totalHits`. +- Market price fields (`…PriceFor`, `…PriceForEveryone`) are the slowest reads under load; request them only where + they are shown. + +## Fail-safe reads in a storefront + +- **Cached reads must never throw.** With Next.js `'use cache'`, a read that throws during warming leaves no entry, + and a failing query inside a cached scope breaks background revalidation even when the caller catches it. Return + an `{ error }` value with a short cache life instead, and render a fallback. +- Prefer shape-filtered queries and fragments that tolerate a missing type while a schema rolls out. +- Revalidate on publish with a Core webhook (`concern: items`), and expect the Discovery answer to lag the webhook + by seconds: revalidate again shortly after, or keep the cache life short for freshly published content + ([[mutation]], [[storefront]]). + +## Checklist after a change + +| You changed | Then | +| ------------------------------- | ------------------------------------------------------------------------------------------ | +| Content of existing items | Publish; expect seconds; verify with a fresh operation name | +| Many items | Publish; wait for published ≥ draft per item; republish laggards; check counts | +| A shape or discoverable field | Ignite; wait 5-10 minutes; sample the schema until it answers every time; then deploy code | +| Stock locations, price variants | Ignite, as above | +| Images or video | Wait for renditions or playlists in Core, then publish the items that use them | +| Related items | Publish targets first, then referrers, per language | +| Deleted items | Expect 1-3 minutes before they disappear | diff --git a/use-crystallize/skills/query/references/shop-api-order-queries.md b/use-crystallize/skills/query/references/shop-api-order-queries.md index deaa9f7..13bd447 100644 --- a/use-crystallize/skills/query/references/shop-api-order-queries.md +++ b/use-crystallize/skills/query/references/shop-api-order-queries.md @@ -22,7 +22,10 @@ See the [Shop API Queries Reference](shop-api-queries.md) for token generation d ## Get a Single Order -Retrieve an order by its Shop API UUID. An unknown id answers a GraphQL error, not `null`. +Retrieve an order by its Shop API UUID. The argument is `UUID!`: a variable typed `ID` or `String` fails validation. +An unknown id answers a GraphQL error, not `null`, and so can an order created a moment ago, so a confirmation page +shows the order that `createFromCart` returned and retries `order(id:)` rather than reporting "not found". Several +orders by id in one request (one alias each) worked well. ```graphql query GetOrder($id: UUID!) { @@ -171,7 +174,26 @@ without being the last: `limit: 10` returned 5 orders and then 4 for a customer build. Ask for everything a customer has in one page (`limit: 100`) rather than walking pages. For a company or a department there is no query by parent: read the people's orders and filter on your -own `meta` (the ordering person, the cost centre). +own `meta` (the ordering person, the cost centre). A seller or approval queue across customers is a back-office +read: Core `orders(filter: { meta, pipelineStageIds, customer })` behind staff login, or an index fed by webhooks. + +### The listing lags, and is sometimes incomplete + +`orders(customerIdentifier:)` reads a second, eventually consistent store. Seen on five builds: + +- New orders appear after **seconds to minutes**. Six orders created one at a time all listed after about 60 s. +- **Some never appear.** 47 orders created at concurrency 4: Core had all 47, the listing showed 29 and stayed there + (one tenant). Two hours after an import, `limit: 100` returned 6 of 8 and 4 of 5 orders for two customers + (another tenant). +- `coreId` is `null` on some orders that have reached Core. + +So: + +1. **Read what you just wrote by id**, never through the listing. +2. **Never use the listing for idempotency** (has this seed or webhook already created the order?): it creates + duplicates on a quick rerun. Key on your own meta (`seedRef`) checked by id, keep a ledger, or take a `/lock`. +3. The confirmation page and order history say that a new order can take a moment to appear. +4. A seed checks the listing per customer afterwards and recreates what is missing, rather than trusting one pass. ## The Order Store and Core @@ -198,13 +220,21 @@ So a storefront that lists orders with the Shop API should have them **created** stages** there. Seed demo orders with the Shop API, not with `registerOrder`: orders registered in Core showed up in the Shop store only sometimes. (Tools Universe.) -Two smaller consequences: +Smaller consequences: - **`pipelines` comes back as identifiers only** (`{ identifier, stage }`). A storefront that shows a - stage name has to map the ids to names itself; the names live in the admin APIs, so resolve them at - build or seed time rather than at runtime. + stage name maps the ids to names itself: read them with PIM `pipeline.getMany` at **build time** and write + them into the storefront's data, never at runtime. - **`coreId` can read `null`** on an order created with Shop `create` even after it has reached Core. Don't treat a null `coreId` as "not synced yet". +- **`meta` is a JSON object** `{ key: value }`, on orders and on lines, although it is written as `[{ key, value }]`. +- **An order line's `imageUrl` is a rendition** (`…/@200/x.jpeg`). Strip the `@` segment before deriving + another size. +- **Orders of type `test` count toward a promotion's `maxUsagePerCustomer`**, and Shop orders can't be deleted, so + never test with a demo persona's identifier. +- **Renewal orders** of subscription contracts land in the store that holds the contracts: see [[subscriptions]]. +- **Does Core `deleteOrder` reach the Shop store?** Observed both ways: two builds saw the Shop copy stay, one saw it + disappear from the listing within a minute. Verify on your tenant before relying on either. ## Order Response Types diff --git a/use-crystallize/skills/query/references/shop-api-queries.md b/use-crystallize/skills/query/references/shop-api-queries.md index 3ce0961..724797a 100644 --- a/use-crystallize/skills/query/references/shop-api-queries.md +++ b/use-crystallize/skills/query/references/shop-api-queries.md @@ -1,16 +1,31 @@ # Shop API Queries Reference -The Shop API handles cart and checkout operations at the edge for low-latency commerce experiences. It is one -GraphQL endpoint per concern, each with its own schema: `/cart`, `/order`, `/customer`, `/subscription-contract` -and `/lock`. +The Shop API is everything about a shopper: carts, the price for this customer and market, checkout, orders, +payments, customers, bookings, subscription contracts and locks. It runs at the edge, **from your server only**. It +is one GraphQL endpoint per route, each with its own schema and scope: + +| Route | Scope | +| ------------------------ | -------------------------------------- | +| `/cart` | `cart` | +| `/cart/admin` | `cart` and `cart:admin` (promotions) | +| `/order` | `order` | +| `/customer` | `customer` | +| `/subscription-contract` | `subscription-contract` (and `:admin`) | +| `/booking/admin` | `booking:admin` | +| `/lock` | `lock` | ## Base URL ``` -https://shop-api.crystallize.com/{tenant-identifier}/cart +https://shop-api.crystallize.com/{tenant-identifier}/{route} ``` -The endpoint also serves as a GraphQL playground for documentation. +The `@` before the tenant is optional here. `GET https://shop-api.crystallize.com/{tenant-identifier}` lists the +routes the tenant serves (seven on tools-universe, 2026-11-12), and each route serves a GraphQL playground. + +**Server only.** The Shop API's CORS allows Crystallize origins and localhost, so a browser call that works in +development fails on your own domain (checked 2026-11-12: no `Access-Control-Allow-Origin` for another origin). The +browser keeps the cart id in an httpOnly cookie, and server actions or routes make the calls. ## Authentication @@ -31,7 +46,28 @@ curl -X POST 'https://shop-api.crystallize.com/YOUR_TENANT/auth/token' \ -d '{"scopes":["cart","cart:admin","order"],"expiresIn":18000}' ``` -`expiresIn` is in seconds and defaults to one day. The response is `{ "success": true, "token": "..." }`. +From a script, send a User-Agent of your own: `/auth/token` refused Python's default `urllib` agent with Cloudflare +error 1010 (HTTP 403). + +`expiresIn` is in seconds and defaults to one day in the API; js-api-client asks for 12 hours unless told otherwise. +The response is `{ "success": true, "token": "..." }`. + +- **The JWT is always for one tenant.** An access token pair that isn't tenant-scoped can mint one for any tenant its + user belongs to; a tenant-scoped pair only for its own tenant. Any other tenant answers 400 "User is not a member of + tenant X", even when the user is a member, so check the token's scope. A plugin bearer token is not read + ([[permissions]]). +- **The JWT is per tenant, not per shopper.** It reads any customer's orders and carts, so it never reaches the + browser, and the `customerIdentifier` you pass comes from your session. +- **Cache it on the server and refresh it before it expires.** An expired token fails with + `"exp" claim timestamp check failed`; a missing or rejected one answers HTTP 401 with `{ "success": false, … }` + and no GraphQL `errors`. +- **Request a separate token for `/subscription-contract`.** A token with every scope read contracts but answered + "Unexpected error" on `create`; one scoped to `subscription-contract` (and `:admin`) worked. +- **The Shop API reads products from the Catalogue with the request's credentials**, and the Shop JWT is not one of + them. On a tenant whose Catalogue API requires authentication, send its `X-Crystallize-Static-Auth-Token` (or its + access token pair) as headers on every `/cart` call that reads a product, `hydrate` included, next to the + `Authorization` header ([[bookable-resources]]). `context.catalogue` is not the place: it carries only + `productVariantMaxAge` and `productVariantImages` (`maxCount`, `renditions { minWidth maxWidth formats }`). ### Token Scopes @@ -101,6 +137,12 @@ query { - `items.context` is a `HashMap` holding `taxRate`, `origin` (`crystallize` or `external`) and `managed`, so it takes no sub-selection. +### Profile data without Core + +A storefront that needs per-shopper data (family members, sizes, saved lists) without Core can keep it on a +`wishlist` cart: write it to `customer.meta` and find the cart again with +`carts(customerIdentifier:, types: [wishlist], name:)`. Wishlists never expire. + ### List Carts `carts` lists carts and wishlists. Like `orders`, it answers for whatever `customerIdentifier` it is given, so @@ -175,7 +217,8 @@ query { `/subscription-contract` serves `subscriptionContract(id:)` and `subscriptionContracts(customerIdentifier:, limit:, skip:)`, which answers an empty list when no -`customerIdentifier` is given. See [[subscriptions]]. +`customerIdentifier` is given. Contracts live in **one store per tenant**, the Shop API (marked experimental) or +Core: read them where that tenant writes them. See [[subscriptions]]. ## Cart Concepts diff --git a/use-crystallize/skills/responsive-images/SKILL.md b/use-crystallize/skills/responsive-images/SKILL.md index fec946c..f8c4077 100644 --- a/use-crystallize/skills/responsive-images/SKILL.md +++ b/use-crystallize/skills/responsive-images/SKILL.md @@ -5,15 +5,16 @@ description: > loading, LCP and CLS. Use when building product galleries, hero images, thumbnails, grids or any page that displays Crystallize media; when images are too heavy, the page scores badly on Lighthouse or Core Web Vitals, or the wrong image size is being downloaded; when choosing between - AVIF, WebP and the original format; when deciding whether to use next/image or another framework - image component with Crystallize; or when querying image variants from the Catalogue or Discovery - API. Trigger on "srcset", "sizes", "responsive images", "picture element", "image optimization", + AVIF, WebP and the original format; when picking og:image, share-card or JSON-LD images; when + deciding whether to use next/image or another framework image component with Crystallize; or when + querying image variants from the Catalogue or Discovery API. Trigger on "srcset", "sizes", "responsive images", "picture element", "image optimization", "image variants", "media.crystallize.com", "webp", "avif", "lazy loading", "fetchpriority", "layout shift", "CLS", "LCP", "next/image", "image component", "@crystallize/reactjs-components", - "thumbnail", "image payload", "images too big". + "thumbnail", "image payload", "images too big", "og:image", "share image", "JSON-LD image", + "packshot", "preconnect". metadata: author: Crystallize - version: "1.0" + version: "1.1" --- # Responsive Images with Crystallize @@ -65,8 +66,12 @@ https://media.crystallize.com/{tenant}/{path}/@{width}/{filename}.{ext} | **Formats** | `avif` and `webp` always, plus original if `jpeg` or `png` | | **Fields** | `url`, `key`, `width`, `height`, `size` (bytes) | -**Read URLs from the API, never compose them.** On a tenant with a custom media domain, Catalogue and -Discovery return that host and drop the `{tenant}` segment. +**Read URLs from the API, never compose them from scratch.** On a tenant with a custom media domain, +Catalogue and Discovery return that host and drop the `{tenant}` segment. What you may do is **derive** a +rendition from a URL the API returned for that same image, on the same host: replace `@{width}` with +another width the API listed. `{dir}/@{w}/{name}.webp` held for all 48,519 renditions on one tenant, so a +listing can ask for `variants(types: "webp", minWidth, maxWidth) { width }` only and build the URLs from +the first one; that cut a 16-card listing read from 345 to 108 KB. Only use widths that came back. **Original-format variants exist only for JPEG and PNG sources, and a `.jpg` source gets `.jpeg` variants.** A WebP, AVIF or TIFF source gets `webp` and `avif` only. @@ -81,7 +86,7 @@ you will emit URLs that 404 and a browser that picks them will show nothing. **`variants` can be empty, so keep `url` as the fallback.** They are generated after upload: until then Catalogue returns `null` and Discovery `[]`. Discovery captures them when the item is indexed and does not pick them up by itself, so an item published too early keeps `[]` until it is published again. See -[[mutation]]. +[[media]]. ## Query the fields you need — including `size` @@ -118,11 +123,21 @@ variants(types: "webp", minWidth: 400, maxWidth: 1600) { } ``` -Useful for a listing page that will never render a 3200px hero. `width` picks one exact width. `types` +Useful for a listing page that will never render a 3200px hero. Ask per context — cards up to 1024, +a gallery or hero up to 1920, chat or MCP cards up to 500 — and one image drops from about 27 rendition URLs +to about 4. On a grid this removed every AVIF and original-format rendition from the payload. One build saw +`maxWidth` ignored, so check the answer on your tenant. `width` picks one exact width. `types` matches the end of the variant key, so ask for `"jpeg"`, never `"jpg"`. An image with nothing in range returns `[]`, not a smaller variant, so keep `url` selected. Catalogue's `variants` takes no arguments — filter client-side there. +**Watch for repeated images.** `variants { images }` on a product with many sizes repeats the colourway's +images on every size variant: 24 cards of a 260-size style came to 8.2 MB and broke the hosting cache +("Single item size exceeds maxSize"), against 106 KB with `defaultVariant` only and card-sized WebP. Discovery's +`variantGroups { images }` takes no arguments and returns every group's images (355 images for 16 hits). Ask +for the default variant's images on a card and load the gallery on the product page. The query side is in +[[query]]. + ## Format: measure, do not assume AVIF Conventional advice says prefer AVIF. **On Crystallize's current transcoder settings that is usually @@ -233,23 +248,83 @@ When `sizes` and the CSS disagree, the CSS wins visually and `sizes` wins on ban entire fix for image-driven layout shift. - **Do not lazy-load images already in the viewport** on first paint — the request starts later than it needs to. +- **At most one or two `fetchpriority="high"` per page.** Marking every card high is the same as marking + none. Give images in a closed mega menu or drawer `fetchpriority="low"` (and `loading="lazy"`). +- **Get the LCP image into the first HTML.** Preload it, or render it in the static shell: in a Next.js + partial prerender, a cached listing preview as the `` fallback put the LCP image into the shell, + which was the biggest LCP win on listings in one build. +- **Preconnect to the media host without `crossOrigin`**: + ``. With `crossorigin` the browser opens a CORS + connection that `` requests do not reuse. Use the custom media domain if the tenant has one. +- **Placeholders are yours to make.** Discovery serves no dominant colour or blur hash (image `meta` holds + only import provenance), so generate one at import and store it with the item if you want one. + +## Share and structured-data images + +`og:image`, `twitter:image`, schema.org `image` in JSON-LD and merchant feeds are read by crawlers and link +previewers, not by a browser that negotiates formats: + +- **Use the original format, never AVIF.** Many preview bots and feed readers do not decode AVIF, and some + not WebP. Pick the widest original-format variant (JPEG or PNG), else the widest WebP; skip AVIF. A + `.jpg` source's variants are `.jpeg`. +- **At least 1200 px wide when the source allows.** The capped ladder means a 1200 px source tops out at + 1024, so use the image's `url` then: the original upload, with the image's own `width` and `height`, + provided it is not itself AVIF. +- **Absolute URLs, with dimensions.** Give `og:image` its `og:image:width` and `og:image:height`, from the + variant you picked. +- **The packshot goes in Product JSON-LD and feeds.** Use the white-background product shot, the first image + of the default variant if that is how the catalogue is authored; lifestyle shots belong on the page, not in + the structured data. A manufacturer photo padded with white bars (3:2 letterboxed to 4:3 or square) reads + as a small product in previews: crop it and import it as a new image, as in [[media]]. +- **Generated share cards** (a Next `opengraph-image.tsx` with packshot, name and key specs) fetch the image + at render time, so allow the media host in the image fetch and in any CSP. + +```ts +/** og:image, twitter:image and JSON-LD images: original format first, then WebP, never AVIF, 1200 px or wider. */ +const isAvif = (url: string) => /\.avif(\?|$)/i.test(url); +const formatRank = (url: string) => (isAvif(url) ? 2 : /\.webp(\?|$)/i.test(url) ? 1 : 0); + +type ShareImage = { url: string; width?: number; height?: number }; + +export function shareImage(image?: { + url: string; + width?: number | null; + height?: number | null; + variants?: { url: string; width: number; height: number }[] | null; +} | null): ShareImage | undefined { + if (!image) return undefined; + const best = (image.variants ?? []) + .filter((v) => !isAvif(v.url)) + .sort((a, b) => formatRank(a.url) - formatRank(b.url) || b.width - a.width)[0]; + if (best && best.width >= 1200) return best; + // The ladder stops below the source width, so the original upload is the larger file. + if (!isAvif(image.url)) return { url: image.url, width: image.width ?? undefined, height: image.height ?? undefined }; + return best; // an AVIF upload: the widest WebP rendition is all there is +} +``` + +Where these tags and the JSON-LD are emitted, and how they are validated, is in [[seo-geo]]. ## Failure modes -| Symptom | Cause | Fix | -| ---------------------------------------- | ------------------------------------------------- | ------------------------------------------- | -| Thumbnails download 1024px files | `sizes` missing — browser assumed `100vw` | Write `sizes` to match the rendered width | -| Both AVIF and WebP `` emitted | `size` not selected in the GraphQL query | Add `size` to `variants` | -| Images heavier after "upgrading" to AVIF | AVIF is usually larger here | Ship WebP; keep the original as fallback | -| Some `srcset` URLs 404 | Width ladder hardcoded, or `_availableSizes` used | Build `srcset` from the returned `variants` | -| `variants` is `null` or `[]` | Variants not generated yet, or source under 100px | Use `url`; republish once they exist | -| Page jumps as images load | No `width`/`height` on the `` | Render both; they set the aspect ratio | -| Poor LCP on the product page | Hero is `loading="lazy"` | `eager` + `fetchPriority="high"` | -| Image bill higher than expected | Images routed through a framework optimizer | Serve straight from `media.crystallize.com` | -| `alt` is empty everywhere | `altText` not selected, or not authored | Query `altText`; author it in the PIM | +| Symptom | Cause | Fix | +| ---------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------- | +| Thumbnails download 1024px files | `sizes` missing — browser assumed `100vw` | Write `sizes` to match the rendered width | +| Both AVIF and WebP `` emitted | `size` not selected in the GraphQL query | Add `size` to `variants` | +| Images heavier after "upgrading" to AVIF | AVIF is usually larger here | Ship WebP; keep the original as fallback | +| Some `srcset` URLs 404 | Width ladder hardcoded, or `_availableSizes` used | Build `srcset` from the returned `variants` | +| `variants` is `null` or `[]` | Variants not generated yet, or source under 100px | Use `url`; republish once they exist | +| Page jumps as images load | No `width`/`height` on the `` | Render both; they set the aspect ratio | +| Poor LCP on the product page | Hero is `loading="lazy"` | `eager` + `fetchPriority="high"` | +| Image bill higher than expected | Images routed through a framework optimizer | Serve straight from `media.crystallize.com` | +| `alt` is empty everywhere | `altText` not selected, or not authored | Query `altText`; author it in the PIM | +| Link previews show no image | `og:image` points at an AVIF rendition | Original format or WebP, never AVIF | +| A listing read is hundreds of KB | Every rendition, or `variants { images }`, queried | `variants(types:, maxWidth:)`; default variant images only | +| `` opens a second connection | `preconnect` carries `crossorigin` | Preconnect without `crossOrigin` | ## Related skills [[query]] covers the Catalogue and Discovery queries these fields come from, and [[content-model]] covers the Images component itself — including that product variant images are -built-in rather than components. [[mutation]] covers uploading images and setting `altText`. +built-in rather than components. [[media]] covers importing images and setting `altText`, [[seo-geo]] the +share and structured-data tags, and [[storefront]] where image reads sit in the request path. diff --git a/use-crystallize/skills/responsive-images/references/without-react.md b/use-crystallize/skills/responsive-images/references/without-react.md index aca66fe..57d9cfe 100644 --- a/use-crystallize/skills/responsive-images/references/without-react.md +++ b/use-crystallize/skills/responsive-images/references/without-react.md @@ -73,9 +73,13 @@ const originalExt = (image: { url: string }) => { ### Putting it together ```ts +const escapeAttr = (value: string) => + value.replace(/&/g, "&").replace(/"/g, """).replace(//g, ">"); + function pictureHtml( image: { url: string; altText?: string; width?: number; height?: number; variants?: Variant[] | null }, sizes: string, + { priority = false }: { priority?: boolean } = {}, // true for the LCP image only ) { const variants = image.variants ?? []; const modern = pickModernFormat(variants); @@ -90,8 +94,9 @@ function pictureHtml( return ` ${sources} - ${image.altText ?? + ${escapeAttr(image.altText ?? `; } ``` diff --git a/use-crystallize/skills/seo-geo/SKILL.md b/use-crystallize/skills/seo-geo/SKILL.md new file mode 100644 index 0000000..3a51377 --- /dev/null +++ b/use-crystallize/skills/seo-geo/SKILL.md @@ -0,0 +1,209 @@ +--- +name: seo-geo +description: > + Make a Crystallize storefront findable and quotable by search engines and AI answer engines (SEO and GEO, + generative engine optimization): schema.org JSON-LD built from typed specs, prices, stock, topics and relations + (Product, ProductGroup, Offer incl. and excl. VAT, QuantitativeValue with UN/CEFACT unitCode, PropertyValue, + CategoryCode from ETIM or GS1 codes in topic meta, BreadcrumbList, ItemList, Organization, WebSite + SearchAction), Open Graph, canonicals and hreflang from translated paths, Markdown twins of every page, + llms.txt and llms-full.txt, robots.txt for AI crawlers with Content-Signal, htmlLimitedBots, sitemaps with + hreflang and lastModified, and validation (a schema.org vocabulary check script and the Rich Results Test). + Use when adding SEO or structured data to a Crystallize frontend, asking how ChatGPT, Claude, Perplexity, + Gemini or Google read the store, emitting GTIN, units or classification codes, writing robots.txt or a + sitemap, or auditing why a page lacks a title, canonical or rich result. Trigger on "SEO", "GEO", "AEO", + "JSON-LD", "structured data", "schema.org", "rich results", "Merchant Center", "Open Graph", "og:image", + "canonical", "hreflang", "sitemap", "robots.txt", "llms.txt", "llms-full.txt", "markdown for LLMs", + "AI crawlers", "GPTBot", "ClaudeBot", "PerplexityBot", "Google-Extended", "Content-Signal", + "htmlLimitedBots", "generateMetadata", "unitCode", "UN/CEFACT", "QuantitativeValue", "GTIN", "ETIM", + "CategoryCode", "ProductGroup", "noindex". +metadata: + author: Crystallize + version: "1.0" +--- + +# SEO and GEO for Crystallize Storefronts + +Search engines and AI answer engines read a store in three ways: the HTML `` and its JSON-LD, plain-text +versions of the pages, and the crawl policy. A Crystallize catalogue with typed specs (numbers with units, +booleans, selections), topics and relations has every fact these readers need. This skill turns them into +structured data and text **from the same rows**, so the page, the JSON-LD and the Markdown never disagree. + +The storefront side (Discovery reads, caching, routing) is in [[storefront]]. Letting agents act on the store +(MCP, WebMCP, an assistant) is in [[agentic-commerce]]; this skill is the passive half. + +> Built and checked on three Crystallize storefronts (Tools Universe and two others), September–November +> 2026, and audited against Chrome's Modern Web Guidance v1.0 on 2026-11-12. The JSON-LD of the live Tools +> Universe pages passes the vocabulary check in [references/validation.md](references/validation.md). + +## The principle: state only what the data holds + +Every fact comes from Crystallize, and nothing is claimed that the data doesn't hold. + +- **No `AggregateRating` without real reviews.** Demo or seeded ratings stay out. +- **No `availability` without stock.** `InStock`/`OutOfStock` and `inventoryLevel` come from the variant's stock. +- **No `false` for an unknown boolean.** Discovery returns an unset boolean component as `false`. Treat `false` as + "not stated" and leave it out of JSON-LD, Markdown and agent answers, unless the model guarantees every + boolean is set. +- **No shipping or return policy unless the store has one.** Google asks for them; don't invent them. +- **No guessed identifiers.** A GTIN or national trade number that isn't registered is "not registered", not a + made-up value. +- **No drafts.** The storefront never renders drafts to crawlers or the public: only the preview route reads + `publicationState: draft`, and it is `noindex` and unlinked. On an open Discovery every draft is readable by + anyone, so embargoed content does not belong in drafts there ([[storefront]]). + +```ts +/** Discovery returns an unset boolean as false; the catalogue states the features a product has. */ +export const stated = (r: SpecRow) => r.value !== false; +``` + +## Checklist per page type + +| Page | `` | JSON-LD | Text twin | +| ------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- | +| Home | Title, description, canonical, hreflang, `og:*` | `Organization` (or `OnlineStore`), `WebSite` with `SearchAction` | `/en.md`, linked from `/llms.txt` | +| Category, brand, platform | Same; canonical **without** filter parameters | `CollectionPage` with an `ItemList` of the products on it; `BreadcrumbList`; the `Brand` or concept | `.md` with the product table | +| Product | Same; `og:image` is the packshot in the original format | `Product`, or `ProductGroup` with a `Product` per variant; `Offer` per variant; `BreadcrumbList` | `.md` with the spec table and codes | +| Rental or service | Same | `Product` with `Offer`s that are `LeaseOut` with `leaseLength`, `availableAtOrFrom` places | `.md` | +| Article, landing page | Same | `WebPage` (or `Article`) in the site graph; `FAQPage` only from a real FAQ block | `.md` | +| Search results | **Static** title, `noindex, follow`, canonical to the bare search page | none | none | +| Cart, account, checkout | `noindex` | none | none; disallowed in robots.txt | +| Draft preview | `noindex`; not linked, not in the sitemap | none | none | + +Every page: + +- [ ] ``, description, canonical and hreflang are **in the `<head>` of the HTML that crawlers get**, not + streamed into `<body>` ([references/crawlers.md](references/crawlers.md)). +- [ ] `<html lang>`, hreflang and `inLanguage` are BCP 47 (`nb`, not the tenant's `no`), with `x-default`. +- [ ] Canonical and hreflang come from the translated generated paths, looked up by `itemId`. No typed "canonical + URL" component: it goes stale on the first rename. +- [ ] The description is plain text, at most about 155 characters, cut at a word. Rich text never goes into + `<meta>`; ask Discovery for `format: plainText`. +- [ ] `<link rel="alternate" type="text/markdown">` points at the page's Markdown twin. + +## Where each fact comes from + +| Fact | Crystallize source | schema.org | +| ----------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| Name, description | Item name; an SEO piece or a plain-text summary | `name`, `description` | +| SKU, GTIN | Variant `sku`; a non-translatable `gtin` single line per variant | `sku`, `gtin13` / `gtin12` / `gtin14` by length | +| National trade numbers | An identifiers chunk (NOBB, NRF, …) | `identifier` as `PropertyValue` with `propertyID` | +| Numeric spec with unit | Numeric component (value + unit) | `PropertyValue` / `QuantitativeValue` with `value`, `unitText`, `unitCode` (UN/CEFACT Rec 20) | +| Bound ("max. diameter") | The field id (`maxDrillingDiameter`) | `maxValue` / `minValue` | +| Selection option | Selection component (option key + label) | `valueReference` as `DefinedTerm` with `termCode` | +| Classification code | Topic `meta`, or a topic map mirroring the code set (ETIM, GS1 GPC, UNSPSC) | `category` as `CategoryCode` with `codeValue` and `inCodeSet` | +| Product type | The type topic's path | `category` as text ("Drilling > Combi drill"), what Google Merchant reads | +| Keywords | Trade, material, feature topics | `keywords` | +| Price | Discovery `<variant>Price` per market; volume tiers | `Offer.price` incl. VAT, `UnitPriceSpecification` incl. and excl. VAT, `eligibleQuantity` | +| Stock | `<location>Stock` per variant | `availability`, `inventoryLevel` | +| Accessory, consumable | Item relations | `isAccessoryOrSparePartFor`, `isConsumableFor`, `isRelatedTo` | +| What's in the box | A paragraph or chunk with item relations | `Offer.includesObject` as `TypeAndQuantityNode` | +| Warranty | Numeric component in years | `Offer.warranty` as `WarrantyPromise` | +| Breadcrumbs | Discovery `breadcrumbs` (ends with the item itself) | `BreadcrumbList` | +| Paths per language | Discovery, one aliased query by `itemId` | hreflang; `@id`s per language | +| `lastModified` | `updatedAt` on every Discovery hit | sitemap `<lastmod>` | + +Code for all of it: [references/json-ld.md](references/json-ld.md). Modelling the specs so these facts exist is +in [[content-model]] and [[taxonomy]]. + +## Share images and JSON-LD images + +`og:image` and schema.org `image` are read by link-preview bots and crawlers that don't all decode AVIF. Use an +absolute URL to the **original format** (JPEG or PNG), else WebP, **never AVIF**, at least 1200 px wide when the +source allows. The variant ladder is capped at the source width, so a 1200 px source tops out at 1024: use the +image's `url` then, which is the original upload, with the image's own `width` and `height` (unless the upload is +itself AVIF). Give `og:image` its width and height, and use the white-background packshot for Product +JSON-LD. + +```ts +/** og:image, twitter:image and JSON-LD images: original format first, then WebP, never AVIF, 1200 px or wider. */ +const isAvif = (url: string) => /\.avif(\?|$)/i.test(url); +const formatRank = (url: string) => (isAvif(url) ? 2 : /\.webp(\?|$)/i.test(url) ? 1 : 0); + +type ShareImage = { url: string; width?: number; height?: number }; + +export function shareImage(image?: { + url: string; + width?: number | null; + height?: number | null; + variants?: { url: string; width: number; height: number }[] | null; +} | null): ShareImage | undefined { + if (!image) return undefined; + const best = (image.variants ?? []) + .filter((v) => !isAvif(v.url)) + .sort((a, b) => formatRank(a.url) - formatRank(b.url) || b.width - a.width)[0]; + if (best && best.width >= 1200) return best; + // The ladder stops below the source width, so the original upload is the larger file. + if (!isAvif(image.url)) return { url: image.url, width: image.width ?? undefined, height: image.height ?? undefined }; + return best; // an AVIF upload: the widest WebP rendition is all there is +} +``` + +The same helper is in [[responsive-images]]; keep the two in step. + +On-page images are a different question: see [[responsive-images]] (WebP over AVIF, `sizes`). + +## Text for answer engines + +- **`/llms.txt`** ([llmstxt.org](https://llmstxt.org)): what the store is, markets, currencies and VAT, how + versions, platforms and specs work, the MCP endpoint, then links to the Markdown page of every category, brand + and concept page. +- **`/llms-full.txt`**: the whole catalogue in one file, with prices incl. and excl. VAT, stock, classification + and every typed spec with its codes. +- **A Markdown twin of every page**: `<url>.md`, and the same URL with `Accept: text/markdown` (`Vary: Accept`). + The twin is `noindex` with a canonical `Link` header to the HTML page. + +Code: [references/llms-and-markdown.md](references/llms-and-markdown.md). + +## Crawl policy + +- **robots.txt** allows everything that is the same for every visitor, disallows per-shopper routes (cart, + account, API, OAuth, MCP hand-offs), names the AI crawlers in their own block, and adds + `Content-Signal: search=yes, ai-input=yes` (training left unstated, or set as you decide). +- **A noindex page must stay crawlable.** Search results are `noindex, follow`; disallowing them hides the + noindex and the links. +- **Sitemap**: every page in every language, hreflang alternates joined on `itemId`, `lastModified` from + `updatedAt`, and a sitemap index above a few thousand URLs. +- **Metadata in `<head>`** for every user agent, including Googlebot behind a CDN. + +Code and the curl checks: [references/crawlers.md](references/crawlers.md). + +## Pitfalls + +| Symptom | Cause | Fix | +| ----------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| Googlebot sees no `<title>`, canonical or hreflang | Dynamic `generateMetadata` streamed into `<body>`; the CDN served the cached shell | Prerender each sitemap path; metadata from cached reads only; test with real Googlebot UAs | +| JSON-LD says a tool has no hammer mode | Unset boolean read as `false` | Treat `false` as "not stated" | +| Description shows HTML or is cut mid-word | Rich text in `<meta>` | Plain text, ≤ 155 characters, cut at a word | +| Link previews show no image | AVIF `og:image` | Original format or WebP | +| Canonical points at an old URL | A typed canonical component | Canonical from the current translated path | +| hreflang rejected or ignored | Tenant code (`no`) instead of BCP 47 (`nb`); hreflang outside `<head>` | `nb`, `x-default`, in `<head>` | +| Crawlers only see one market's prices | Market chosen by cookie | Market in the path | +| Search results indexed, or their links never followed | Disallowed in robots.txt instead of `noindex, follow` | Allow crawling, `noindex` | +| Search page title lacks the query, or streams late | `generateMetadata` reads `searchParams` | Static metadata on the search page | +| Filtered category views compete with the category | Canonical carries filter parameters | Canonical to the clean category | +| Merchant listing warnings | schema.org-valid but missing what Google asks for | Rich Results Test; add only what the store really has | +| Unit filters and codes wrong | Several units on one numeric; units without a Rec 20 code guessed | One unit per numeric; no code rather than a wrong one | + +## Live examples + +- [tools-universe.superfast.shop](https://tools-universe.superfast.shop): Product/ProductGroup JSON-LD with ETIM + `CategoryCode`, UN/CEFACT units, rentals as `LeaseOut` offers; `/llms.txt`, `/llms-full.txt`, `.md` twins; the + robots.txt and sitemap described here. Its `/en/mcp` page explains the AI-ready setup. +- [photo-store-vector.superfast.shop/llms.txt](https://photo-store-vector.superfast.shop/llms.txt): llms.txt for a + B2C and B2B store with typed lens and camera specs. +- More stores, by capability: [superfast.shop/demos.json](https://superfast.shop/demos.json); see [[storefront]]. + +## References + +| File | Read it when | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------- | +| [references/json-ld.md](references/json-ld.md) | Emitting JSON-LD for products, variants, offers, specs, listings, brands | +| [references/llms-and-markdown.md](references/llms-and-markdown.md) | Publishing llms.txt, llms-full.txt and Markdown twins | +| [references/crawlers.md](references/crawlers.md) | robots.txt, AI crawlers, htmlLimitedBots, metadata in `<head>`, sitemaps | +| [references/validation.md](references/validation.md) | Checking JSON-LD against schema.org and Google, and crawler-eye curl checks | + +## Related skills + +[[storefront]] for the Discovery reads, caching and routing this builds on; [[content-model]] for typed specs, +units and identifiers; [[taxonomy]] for classification codes in topic meta; [[information-architecture]] for +paths and redirects; [[responsive-images]] for images; [[agentic-commerce]] for agents that act on the store. diff --git a/use-crystallize/skills/seo-geo/references/crawlers.md b/use-crystallize/skills/seo-geo/references/crawlers.md new file mode 100644 index 0000000..c1ab8c9 --- /dev/null +++ b/use-crystallize/skills/seo-geo/references/crawlers.md @@ -0,0 +1,178 @@ +# Crawlers: robots.txt, AI crawlers, metadata in `<head>`, sitemaps + +## robots.txt + +Crawl everything that is the same for every visitor. Keep out what is per-shopper (cart, account) or technical +(API, OAuth, MCP hand-off routes). Name the AI crawlers in their own block: several look for their own +User-Agent, and naming them makes letting them in a deliberate, easy-to-change choice. From a working store +(`app/robots.ts`): + +```ts +import type { MetadataRoute } from "next"; + +const PRIVATE = ["/api/", "/oauth/", "/mcp/", "/*/cart", "/*/account"]; + +const AI_AGENTS = [ + "GPTBot", + "OAI-SearchBot", + "ChatGPT-User", + "ClaudeBot", + "Claude-User", + "Claude-SearchBot", + "anthropic-ai", + "PerplexityBot", + "Perplexity-User", + "Google-Extended", + "Applebot-Extended", + "Amazonbot", + "meta-externalagent", + "DuckAssistBot", + "MistralAI-User", + "CCBot", +]; + +export default function robots(): MetadataRoute.Robots { + return { + rules: [ + { + userAgent: "*", + allow: "/", + disallow: PRIVATE, + // Content Signals (contentsignals.org): searchable and usable as live input to AI answers. + // Training is left unstated. + other: { "Content-Signal": "search=yes, ai-input=yes" }, + }, + { userAgent: AI_AGENTS, allow: "/", disallow: PRIVATE }, + ], + sitemap: absolute("/sitemap.xml"), + }; +} +``` + +- Set `ai-train=yes` or `no` in `Content-Signal` as the business decides; leaving it out states nothing. +- **Don't disallow a page you mark `noindex`.** A crawler that may not fetch the page never sees the `noindex`, + and never follows its links. Search results are `noindex, follow` and crawlable. One store disallowed + `/search?`, which hid the noindex. +- A page that explains the store to agents (an MCP setup page, say) is content: keep it open. +- No `Host:` line; it is non-standard. +- Staging and preview deployments send `X-Robots-Tag: noindex` site-wide ([[storefront]] security headers). +- The draft preview route is `noindex`, never linked and never in the sitemap. Drafts are never rendered on + public pages. + +## Metadata must be in the `<head>` crawlers get + +Google ignores canonical and hreflang outside `<head>`, and crawlers that don't run JavaScript only see the raw +HTML. Next.js 16 streams metadata into `<body>` for normal browsers. + +**What happened on a live store** (found in a Modern Web Guidance audit, confirmed with curl): + +- With Cache Components and PPR, a dynamic `generateMetadata` was streamed into `<body>` instead of the static + shell's `<head>`. +- On Vercel, **real Googlebot user agents were served the cached shell** (`x-vercel-cache: HIT`) with **no + `<title>`, description, canonical or hreflang** on product and category pages: `</head>` at byte 1191, the + metadata only inside the RSC flight data. bingbot, ClaudeBot and GPTBot got `BYPASS` and a full `<head>`. + Browsers got the title about 300 KB into the HTML. +- Googlebot was in `htmlLimitedBots`, but the cached shell won. +- Root cause: the catch-all route had no `generateStaticParams`, so every catalogue URL shared one App Shell, and + that shell can't hold path-dependent metadata. + +**The rule: keep metadata cacheable, and give every URL its own shell.** + +- `generateMetadata` reads only `params` and cached Discovery reads: no `cookies()`, `headers()` or + `searchParams`. Then it lands in the shell's `<head>` for every user agent. +- `generateStaticParams` returns every sitemap path, so each URL is prerendered with its own shell. Items + published after the build get the App Shell first and are prerendered on their first visit. +- The search page's metadata is static (reading `searchParams` deferred it to request time and streamed it). + +Code: [[storefront]] `references/performance.md`. + +### htmlLimitedBots + +`htmlLimitedBots` tells Next.js which user agents get blocking metadata in `<head>` instead of streamed. Most +builds list search engines, AI crawlers and link-preview bots: + +```ts +// next.config.ts +htmlLimitedBots: + /Googlebot|Google-InspectionTool|bingbot|Applebot|DuckDuckBot|YandexBot|Baiduspider|GPTBot|OAI-SearchBot|ChatGPT-User|ClaudeBot|Claude-User|Claude-SearchBot|anthropic-ai|PerplexityBot|Perplexity-User|CCBot|facebookexternalhit|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|TelegramBot/i, +``` + +**Observed both ways for Googlebot; verify on your deployment.** One build removed Googlebot from the list: Next +treats it as a DOM bot, and on Vercel it was served the prerendered shell plus the streamed rest; with Googlebot +listed, the streamed part skipped the metadata and on-demand pages reached Googlebot with nothing. Another build +kept Googlebot listed and fixed the same symptom with `generateStaticParams` for every path. Per-URL shells with +cacheable metadata make the list matter less. In both cases bots in the list reaching pages unknown at build +caused "Expected the resume to render <div>…" errors on Vercel, also fixed by `generateStaticParams`. + +`htmlLimitedBots` does not help when a CDN serves a cached shell to that UA. + +### Check it with the real user agents + +Use the full user-agent strings, not a shortened `Googlebot`, and test the deployment: a local `next start` +upgraded the App Shell after the first visit while production did not. + +```bash +URL=https://shop.example/en/some/category/some-product +for UA in \ + 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Chrome/138.0.0.0 Safari/537.36' \ + 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)' \ + 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm) Chrome/138.0.0.0 Safari/537.36' \ + 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)' \ + 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot'; do + html=$(curl -s -A "$UA" "$URL") + head_end=$(printf '%s' "$html" | grep -bo '</head>' | head -1 | cut -d: -f1) + title_at=$(printf '%s' "$html" | grep -bo '<title>' | head -1 | cut -d: -f1) + echo "$(curl -sI -A "$UA" "$URL" | grep -i '^x-vercel-cache' | tr -d '\r') head_end=$head_end title_at=${title_at:-none} canonical=$(printf '%s' "$html" | grep -c 'rel="canonical"') hreflang=$(printf '%s' "$html" | grep -oi 'hreflang="' | wc -l | tr -d ' ')" +done +``` + +A good result: `title_at` smaller than `head_end`, one canonical and an hreflang per language plus `x-default`, +for every UA. (React writes the attribute as `hrefLang`, hence `grep -i`.) A broken one, as measured on a live store +before the fix: + +``` +x-vercel-cache: HIT head_end=1191 title_at=none canonical=0 hreflang=0 # Googlebot +x-vercel-cache: BYPASS head_end=4865 title_at=1681 canonical=1 hreflang=5 # ClaudeBot +``` + +## Sitemaps + +Every page in every language, each with hreflang alternates to the same item in the other languages (joined on +`itemId`, because paths are translated), and `lastModified` from Discovery's `updatedAt`: + +```ts +// app/sitemap.ts +export default async function sitemap(): Promise<MetadataRoute.Sitemap> { + const all = await Promise.all(LANGS.map(async (l) => [l, await allItems(l)] as const)); // one browse per language + const byItem = new Map<string, Partial<Record<Lang, string>>>(); + for (const [l, items] of all) + for (const i of items) byItem.set(i.itemId, { ...byItem.get(i.itemId), [l]: absolute(`/${l}${i.path}`) }); + const languages = (urls: Partial<Record<Lang, string>>) => ({ + ...Object.fromEntries(LANGS.flatMap((l) => (urls[l] ? [[HREFLANG[l], urls[l]!]] : []))), + "x-default": urls.en ?? Object.values(urls)[0]!, + }); + return all.flatMap(([lang, items]) => + items.map((i) => ({ + url: absolute(`/${lang}${i.path}`), + lastModified: i.updatedAt, + changeFrequency: "weekly" as const, + alternates: { languages: languages(byItem.get(i.itemId) ?? {}) }, + })), + ); +} +``` + +- `hreflang` keys are BCP 47 (`nb`), with `x-default`. +- Above a few thousand URLs, split into a sitemap index by type (pages, categories, products). One store had 2,112 + URLs with 10,560 `xhtml:link` alternates in one file. +- A full Discovery scan can come back incomplete during re-indexing. Read with retry, union the passes, and check + the count against a `search` total. +- Leave out old paths (they are in the item's path history and should 301) and per-shopper pages. + +## Canonicals + +- Canonical from the item's current path in this language, absolute. +- Filtered and sorted category views point at the clean category: facets as GET links can be crawled, but don't + compete with the category. +- A shortcut path (the same item reachable from a second folder) is a duplicate: canonical to the item's main path. +- Paginated listings: each page canonical to itself, or render "load more" for people and keep page 1 canonical. diff --git a/use-crystallize/skills/seo-geo/references/json-ld.md b/use-crystallize/skills/seo-geo/references/json-ld.md new file mode 100644 index 0000000..e22abfa --- /dev/null +++ b/use-crystallize/skills/seo-geo/references/json-ld.md @@ -0,0 +1,419 @@ +# JSON-LD from typed Crystallize data + +One `@graph` per page, with stable `@id`s, so a product, its brand page and its platform page describe the same +entities. Everything is built from the Discovery read the page already made. The code is trimmed from a working +storefront (`lib/seo.ts`); field names such as `defaultPrice`, `defaultStock` and `nokPrice` are generated from +the tenant's price variants and stock locations, so yours will differ. + +Render it escaped, so content can't close the tag: + +```tsx +export function JsonLd({ data }: { data: unknown }) { + return ( + <script + type="application/ld+json" + dangerouslySetInnerHTML={{ __html: JSON.stringify(data).replace(/</g, "\\u003c") }} + /> + ); +} +``` + +## Site graph: Organization and WebSite + +On the home page. Other pages reference them by `@id`. + +```ts +const ORG = `${SITE_URL}/#organization`; +const WEBSITE = `${SITE_URL}/#website`; + +export const organization = (lang: Lang) => ({ + "@type": ["Organization", "OnlineStore"], + "@id": ORG, + name: SITE_NAME, + url: SITE_URL, + logo: { "@type": "ImageObject", url: absolute("/icon.svg") }, + areaServed: ["NO", "SE", "NL"].map((c) => ({ "@type": "Country", name: c })), + knowsLanguage: LANGS.map((l) => HREFLANG[l]), // BCP 47: "nb", not "no" +}); + +export const website = (lang: Lang) => ({ + "@context": "https://schema.org", + "@graph": [ + organization(lang), + { + "@type": "WebSite", + "@id": WEBSITE, + url: absolute(`/${lang}`), + name: SITE_NAME, + inLanguage: MARKET[lang].locale, + publisher: { "@id": ORG }, + potentialAction: { + "@type": "SearchAction", + target: { "@type": "EntryPoint", urlTemplate: absolute(`/${lang}/search?q={search_term_string}`) }, + "query-input": "required name=search_term_string", + }, + }, + ], +}); + +export const breadcrumbs = (items: { name: string; path: string }[]) => ({ + "@type": "BreadcrumbList", + itemListElement: items.map((it, i) => ({ + "@type": "ListItem", + position: i + 1, + name: it.name, + item: absolute(it.path), + })), +}); +``` + +Discovery's `breadcrumbs` end with the item itself; that is what `BreadcrumbList` wants. + +## Prices: incl. and excl. VAT + +Prices in Crystallize are usually net. State the price the shopper pays as `price`, and both incl. and excl. VAT +as `UnitPriceSpecification`s, with volume tiers as `eligibleQuantity`: + +```ts +function price(net: number, lang: Lang, tiers: { threshold: number; price: number }[] = []) { + const m = MARKET[lang]; + const spec = (p: number, minQty?: number) => + [true, false].map((incl) => ({ + "@type": "UnitPriceSpecification", + price: incl ? round(p * (1 + m.vat)) : round(p), + priceCurrency: m.currency, + valueAddedTaxIncluded: incl, + ...(minQty && { eligibleQuantity: { "@type": "QuantitativeValue", minValue: minQty, unitCode: "C62" } }), + })); + return { + price: round(net * (1 + m.vat)), + priceCurrency: m.currency, + priceSpecification: [...spec(net), ...tiers.flatMap((t) => spec(t.price, t.threshold))], + }; +} +``` + +A B2B store whose price is per case, excl. VAT, for business buyers only (from a food wholesale build): + +```ts +offers: { + "@type": "Offer", + url: absolute(url), + price: v.defaultPrice, + priceCurrency: "EUR", + itemCondition: "https://schema.org/NewCondition", + seller: { "@id": `${SITE_URL}/#organization` }, + eligibleCustomerType: "http://purl.org/goodrelations/v1#Business", + priceSpecification: { + "@type": "UnitPriceSpecification", + price: v.defaultPrice, + priceCurrency: "EUR", + valueAddedTaxIncluded: false, + referenceQuantity: { "@type": "QuantitativeValue", value: 1, unitText: "case" }, + }, +}, +``` + +Never put a contract price in JSON-LD: it is per customer, and the page is public. + +A product sold only on quote gets an `Offer` with a `description` ("price on request") and no price. + +## Units: UN/CEFACT Rec 20 + +A numeric component with a unit becomes a `QuantitativeValue` (or a `PropertyValue` carrying the same fields): +`value`, `unitText` as written, and `unitCode` from UN/CEFACT Recommendation 20. The content model's unit list +has no slot for the code, so the storefront maps it. Give no code rather than a guess. + +```ts +const CODES: Record<string, string> = { + mm: "MMT", + cm: "CMT", + m: "MTR", + g: "GRM", + kg: "KGM", + l: "LTR", + V: "VLT", + A: "AMP", + Ah: "AMH", + W: "WTT", + Wh: "WHR", + Nm: "NU", + J: "JOU", + kN: "B47", + kPa: "KPA", + mbar: "MBR", + "m/s": "MTS", + "m/s²": "MSK", + "m³/h": "MQH", + lm: "LUM", + "dB(A)": "2N", + "°": "DD", + "%": "P1", + h: "HUR", + min: "MIN", + s: "SEC", + years: "ANN", +}; + +/** "1/min" is a rotational speed (RPM) on speed fields and a frequency (C94) on impact or stroke rates. */ +export function unitCode(unit: string | null | undefined, field = ""): string | undefined { + if (!unit) return undefined; + if (unit === "1/min") return /speed/i.test(field) ? "RPM" : "C94"; + return CODES[unit]; +} + +/** A bound ("max. drilling diameter") from the field id. */ +export function boundOf(field: string): "max" | "min" | undefined { + const id = field.split(".").at(-1) ?? field; + if (/^max[A-Z_]|Max($|[A-Z_])/.test(id)) return "max"; + if (/^min[A-Z_]|Min($|[A-Z_])/.test(id)) return "min"; + return undefined; +} +``` + +Use one unit per numeric where you can: Discovery range filters ignore the unit, so a field stored in both mm and +cm compares 10 with 100. Pieces (counts) are `C62`. + +## Typed specs as `additionalProperty` + +Turn every typed component into one row first, then render the row as a page table, a Markdown table and a +`PropertyValue`. A row holds the label, value, unit, unit code, bound, the classification feature code (for +example ETIM `EF…`) and, for selections, the option keys with their codes: + +```ts +export type SpecRow = { + key: string; + label: string; + text: string; + value: number | string | boolean; + unit?: string | null; + unitCode?: string; + bound?: "max" | "min"; + etim?: string; // feature code, e.g. EF000001 + options?: { key: string; label: string; etim?: string }[]; + items?: { name: string; path: string }[]; // relations (e.g. the platforms a battery fits) +}; + +function property(r: SpecRow): Record<string, unknown> { + const n = typeof r.value === "number" ? r.value : null; + return { + "@type": "PropertyValue", + name: r.label, + ...(r.etim && { propertyID: r.etim }), + value: r.value, + ...(n != null && r.bound === "max" && { maxValue: n }), + ...(n != null && r.bound === "min" && { minValue: n }), + ...(r.unit && { unitText: r.unit }), + ...(r.unitCode && { unitCode: r.unitCode }), + ...(r.options && { + valueReference: r.options.map((o) => ({ + "@type": "DefinedTerm", + name: o.label, + termCode: o.key, + ...(o.etim && { identifier: { "@type": "PropertyValue", propertyID: "ETIM", value: o.etim } }), + })), + }), + }; +} + +const specs = specGroups(p.specs, p.power, p.physical, lang) + .flatMap((g) => g.rows) + .filter(stated); +``` + +Discovery returns a numeric component as `{ <field>: number, <field>Unit: string }` in the hit, a boolean as a +boolean, and a selection as a hash of option key → label. The row builder walks those (skip `*Unit` keys and +`null`s). A selection option can't carry an external code in the model, so keep codes in a generated labels +file or in the component's `description`, and look them up by option key. + +## Classification codes from topics + +Keep classification codes (ETIM class `EC…`, GS1 GPC, UNSPSC, Google product category) in topic `meta`, or in a +topic map that mirrors the code set (`/etim/<group>/<class>`). Emit them as `CategoryCode`, alongside the product +type as plain text: + +```ts +const ETIM_SET = { "@type": "CategoryCodeSet", name: "ETIM International classification", url: "https://www.etim-international.com/" }; + +/** Discovery `topics` is a hash: topic path → "Map > Parent > Leaf". */ +export function classification(topics: Record<string, string> | null | undefined) { + const entries = Object.entries(topics ?? {}); + const type = entries + .filter(([k]) => k.startsWith("/category/")) + .sort((a, b) => b[0].split("/").length - a[0].split("/").length)[0]; + const etim = entries.find(([k]) => k.startsWith("/etim/")); + const code = etim?.[0].split("/").at(-1)?.toUpperCase(); + return { + type: type?.[1].split(" > ").slice(1).join(" > "), + etim: etim && code ? { code, name: etim[1].split(" > ").at(-1)! } : undefined, + }; +} + +category: [ + type, // "Drilling & driving > Combi drill": what Google Merchant reads + etim && { "@type": "CategoryCode", codeValue: etim.code, name: etim.name, inCodeSet: ETIM_SET }, +].filter(Boolean), +``` + +Keyword-like topics (trade, material, feature, level) become a comma-separated `keywords`. + +## Identifiers + +`sku` is the merchant's SKU; the GTIN is a separate fact (a kit and a bare tool have different GTINs). Pick the +property from the length: + +```ts +const gtin = (g?: string | null) => { + const d = g?.replace(/\D/g, ""); + return d + ? d.length === 13 + ? { gtin13: d } + : d.length === 12 + ? { gtin12: d } + : d.length === 14 + ? { gtin14: d } + : { gtin: d } + : {}; +}; + +const ids = (x: Variant) => ({ + sku: x.sku, + ...gtin(x.gtin), + ...(x.nobbNumber && { identifier: { "@type": "PropertyValue", propertyID: "NOBB", value: x.nobbNumber } }), +}); +``` + +## Product, or ProductGroup with a Product per variant + +One variant: a `Product` with one `Offer`. Several: a `ProductGroup` (`productGroupID` = the item id) whose +`hasVariant` lists a `Product` per variant, each with its own identifiers, images and `Offer`: + +```ts +const offer = (x: Variant) => ({ + "@type": "Offer", + name: x.name ?? undefined, + sku: x.sku, + ...gtin(x.gtin), + url, + ...price(netFor(x, lang), lang, tiersOf(x)), + availability: `https://schema.org/${(x.defaultStock ?? 0) > 0 ? "InStock" : "OutOfStock"}`, + inventoryLevel: { "@type": "QuantitativeValue", value: Math.max(0, x.defaultStock ?? 0), unitCode: "C62" }, + itemCondition: "https://schema.org/NewCondition", + ...(country && { eligibleRegion: { "@type": "Country", name: country } }), + ...(box.length && { includesObject: box }), // TypeAndQuantityNode per item in the box + ...(warranty && { warranty }), // WarrantyPromise with durationOfWarranty in ANN + seller: { "@id": ORG }, +}); + +const node = + p.variants.length > 1 + ? { + "@type": "ProductGroup", + "@id": `${url}#product`, + productGroupID: p.itemId, + ...common, // name, url, description, image, brand, category, keywords, additionalProperty, relations + hasVariant: p.variants.map((x) => ({ + "@type": "Product", + "@id": `${url}#${x.sku}`, + name: `${p.name} (${x.name ?? x.sku})`, + ...ids(x), + isVariantOf: { "@id": `${url}#product` }, + offers: offer(x), + })), + } + : { "@type": "Product", "@id": `${url}#product`, ...ids(v), ...common, offers: offer(v) }; + +return { "@context": "https://schema.org", "@graph": [node, breadcrumbs(crumbs)] }; +``` + +`common` also carries: + +- `brand`: a `Brand` with the brand page's `@id` (`…/brand-path#brand`), so the brand page defines the same + entity. +- `weight`, `width`, `height`, `depth` as `QuantitativeValue`s from the physical specs. +- `releaseDate` from a launch date. +- `image`: up to six images, through `shareImage(img)?.url` (original format, never AVIF). + +## Relations + +Item relations become typed links to other products' `@id`s: + +```ts +const productRef = (lang: Lang, it: { name?: string | null; path?: string | null }) => + it.path ? { "@type": "Product", "@id": `${absolute(`/${lang}${it.path}`)}#product`, name: it.name ?? undefined, url: absolute(`/${lang}${it.path}`) } : null; + +...(fits.length && { [consumable ? "isConsumableFor" : "isAccessoryOrSparePartFor"]: fits }), +...(pairs.length && { isRelatedTo: pairs }), +``` + +A shared concept with its own page (a battery platform, a collection, a technology) is a `DefinedTerm` with that +page's `@id`; products point at it from an `additionalProperty` `valueReference`, and the concept page puts the +same term at the top of its graph. + +## Rentals and services + +A rented machine is a `Product` with one `Offer` per rental period, leased out from the depots that hold it: + +```ts +{ + "@type": "Offer", + name: periodName(v), + sku: v.sku, + url, + businessFunction: "http://purl.org/goodrelations/v1#LeaseOut", + leaseLength: { "@type": "QuantitativeValue", value: hoursOf(v), unitCode: "HUR", unitText: "h" }, + price: p.price, + priceCurrency: p.priceCurrency, + priceSpecification: p.priceSpecification.map((s) => ({ ...s, referenceQuantity: hours })), + availability: `https://schema.org/${pool > 0 ? "InStock" : "OutOfStock"}`, + availableAtOrFrom: depots.map((d) => ({ + "@type": "Place", + name: d.name, + address: { "@type": "PostalAddress", streetAddress: d.street, postalCode: d.postalCode, addressLocality: d.city }, + geo: { "@type": "GeoCoordinates", latitude: d.lat, longitude: d.long }, + })), + availableDeliveryMethod: "https://schema.org/OnSitePickup", + seller: { "@id": ORG }, +} +``` + +`leaseLength` is a property of `Offer`, not `Product`: the vocabulary check catches that. + +## Listings: CollectionPage with an ItemList + +Category, brand and platform pages list the products on the page, each with its default variant's price and +stock: + +```ts +{ + "@type": "CollectionPage", + "@id": url, + name, + url, + inLanguage: MARKET[lang].locale, + isPartOf: { "@id": WEBSITE }, + ...(about && { about }), // the Brand or DefinedTerm the page is about + mainEntity: { + "@type": "ItemList", + name, + numberOfItems: total, + itemListElement: items.map((p, i) => ({ "@type": "ListItem", position: i + 1, url: absolute(`/${lang}${p.path}`), item: listedProduct(p, lang) })), + }, +} +``` + +A brand page adds a `Brand` (`logo`, `slogan`, `sameAs` the brand's own site) and points `about` at it. + +## Other page types + +- **Article, about, info pages**: `WebPage` (or `Article`) with `isPartOf` the website and `publisher` the + organisation. +- **FAQPage** only from a real FAQ block in the content, never generated. +- **Recipe** from a recipe shape, with the products it uses linked (a food build does this). +- **Short factual Q&A built from typed specs** ("Does it have a hammer mode? Yes.") is fine on the page, shown + only when the value exists. + +## What Google asks for beyond schema.org + +Merchant listings ask for `shippingDetails`, `hasMerchantReturnPolicy` and review data. State them only if the +store has them. Check with the Rich Results Test ([validation.md](validation.md)). diff --git a/use-crystallize/skills/seo-geo/references/llms-and-markdown.md b/use-crystallize/skills/seo-geo/references/llms-and-markdown.md new file mode 100644 index 0000000..35dcee5 --- /dev/null +++ b/use-crystallize/skills/seo-geo/references/llms-and-markdown.md @@ -0,0 +1,193 @@ +# llms.txt, llms-full.txt and Markdown twins + +Answer engines quote text. A Crystallize store can give them its own: a short map of the site (`/llms.txt`), the +whole catalogue in one file (`/llms-full.txt`), and a Markdown version of every page. All three are built from +the same cached Discovery reads and the same typed spec rows as the pages and the JSON-LD, so they never +disagree and they follow a publish in the same revalidation ([[storefront]]). + +## /llms.txt + +Follows [llmstxt.org](https://llmstxt.org): an `#` title, a `>` summary, a few lines on how the store works, then +sections of links. Link to the **Markdown** twins, not the HTML pages. What to say up front: + +- What the store sells, to whom, and in which markets, currencies and VAT rates. Which part of the URL decides the + market. +- Whether catalogue prices are net, and what each segment sees (incl. or excl. VAT). +- How the catalogue is structured: versions and variants with their own SKU and price, platforms or systems that + decide compatibility, what typed specs and codes mean. +- The MCP endpoint, if there is one, and the page that explains it. +- That every page has a Markdown version (`.md` suffix or `Accept: text/markdown`), and the languages. +- Where the data comes from (for example, manufacturer data). + +Trimmed from a working store: + +```ts +export async function llmsTxt() { + const items = await allItems("en"); // one cached browse per shape + const of = (shape: string) => items.filter((i) => i.shape === shape); + return [ + `# ${SITE_NAME}`, + "", + `> ${SUMMARY}`, + "", + "- Markets and currencies: … The site language decides the market: `/en` EUR, `/no` NOK, `/sv` SEK.", + "- Prices in the catalogue are net, excluding VAT. Trade customers see prices excl. VAT; consumers incl. VAT.", + "- Specs are typed: numbers with their unit (and its UN/CEFACT code), yes/no, and fixed option sets, with ETIM codes.", + `- MCP server for AI assistants: ${absolute("/api/mcp")} (Streamable HTTP). Setup and tools: ${absolute("/en/mcp")}.`, + "- Every page has a Markdown version: append `.md` to its URL (`/en.md` for the front page), or request it with `Accept: text/markdown`.", + "", + "## Catalogue", + "", + `- [Front page](${mdUrl("en", "/")})`, + ...of("category").map((c) => `- [${c.name}](${mdUrl("en", c.path)}): ${c.tagline ?? ""}`.trim()), + "", + "## Brands", + "", + ...of("brand").map((b) => `- [${b.name}](${mdUrl("en", b.path)})`), + "", + "## Optional", + "", + `- [Full catalogue with prices](${absolute("/llms-full.txt")}): every product in one file`, + `- [Search](${absolute("/en/search?q=")}): append a term`, + `- [Sitemap](${absolute("/sitemap.xml")})`, + "", + ].join("\n"); +} + +// app/llms.txt/route.ts +export async function GET() { + return new Response(await llmsTxt(), { headers: { "content-type": "text/markdown; charset=utf-8" } }); +} +``` + +Write it in the default language and link the other languages' front pages. + +## /llms-full.txt + +The catalogue in one file: per category, every product with brand, price incl. and excl. VAT per currency, SKU, +stock, the Markdown link, classification and every **stated** typed spec with its codes. Page through Discovery +with the cursor, in a cached function: + +```ts +let after: string | null = null; +do { + const data = await discovery( + `query Typed($after: String) { browse { product(language: en, pagination: { limit: 100, after: $after }, sorting: { path: asc }) { + summary { hasMoreHits endToken } hits { path topics ${SPEC_FIELDS} } } } }`, + after ? { after } : {}, + ); + for (const t of data.browse.product.hits) { + const facts = specGroups(t.specs, t.power, t.physical, "en") + .flatMap((g) => g.rows) + .filter(stated) // unset booleans read false: leave them out + .map((r) => `${r.label} ${specFact(r)}${r.etim ? ` [${r.etim}]` : ""}`); + out.set(t.path, facts.join(" · ")); + } + after = data.browse.product.summary.hasMoreHits ? data.browse.product.summary.endToken : null; +} while (after); + +/** "230 Nm (NU)", "SDS-max (EV005657)": the value with its codes, for text-only readers. */ +export function specFact(r: SpecRow) { + const codes = [r.unitCode, ...(r.options ?? []).map((o) => o.etim)].filter(Boolean); + return `${r.text}${codes.length ? ` (${codes.join(", ")})` : ""}`; +} +``` + +A full scan of a large index can come back incomplete when Discovery is re-indexing (totals flicker, `hasMoreHits` +false too early). For files that claim to be complete, compare the count with a `search` total and retry. + +## Markdown twins of every page + +Every storefront URL has a Markdown version at `<url>.md` (`/en.md` for the home page), and the same URL with +`Accept: text/markdown` returns it too. The proxy rewrites both to one route: + +```ts +// proxy.ts, inside the language branch +const accept = request.headers.get("accept") ?? ""; +if (pathname.endsWith(".md") || (accept.includes("text/markdown") && !accept.includes("text/html"))) { + const url = request.nextUrl.clone(); + url.pathname = `/md${pathname.replace(/\.md$/, "")}`; + return NextResponse.rewrite(url); +} +// Same URL, two representations: caches must key on Accept. +const res = NextResponse.next(); +res.headers.set("Vary", "Accept"); +return res; + +// matcher: skip files, but not .md +export const config = { matcher: ["/((?!_next|api|md/|.*\\..*).*)", "/(.*\\.md)"] }; +``` + +The route answers Markdown, out of the index, pointing at the HTML page as canonical: + +```ts +// app/md/[lang]/[[...path]]/route.ts +export async function GET(_: Request, { params }: { params: Promise<{ lang: string; path?: string[] }> }) { + const { lang, path = [] } = await params; + const page = await pageMarkdown("/" + path.map(decodeURIComponent).join("/"), lang); + if (!page) return new Response("Not found", { status: 404 }); + return new Response(page.body + "\n", { + headers: { + "content-type": "text/markdown; charset=utf-8", + "x-robots-tag": "noindex", + link: `<${page.canonical}>; rel="canonical"`, + vary: "Accept", + }, + }); +} +``` + +Announce the twin from the HTML page with `<link rel="alternate" type="text/markdown">`. In Next.js metadata: + +```ts +alternates: { ...alternates(paths, lang), types: { "text/markdown": `${canonical}.md` } }, +``` + +What a twin contains: + +- The page's facts without markup: name, brand, price incl. and excl. VAT in the page's market, stock, SKU and + GTIN per variant. +- The typed spec sheet as a table: spec, value (with `≤`/`≥` for bounds), UN/CEFACT code, classification codes. +- Links to other twins (`[name](https://shop.example/en/path.md)`), so a model can walk the catalogue. +- Listings as tables of products, with the same prices. + +```ts +/** The typed spec sheet: value with unit, the unit's UN/CEFACT code, and the ETIM feature (and value) codes. */ +const specTables = (groups: SpecGroup[], lang: Lang) => + groups + .map((g) => ({ ...g, rows: g.rows.filter(stated) })) + .filter((g) => g.rows.length) + .flatMap((g) => [ + `### ${g.title}`, + "", + ...table( + ["Spec", "Value", "UN/CEFACT", "ETIM"], + g.rows.map((r) => [ + r.label, + `${r.bound === "max" ? "≤ " : r.bound === "min" ? "≥ " : ""}${r.text}`, + r.unitCode ?? "", + [r.etim, ...(r.options ?? []).map((o) => o.etim)].filter(Boolean).join(" · "), + ]), + ), + "", + ]); + +const cell = (s: unknown) => + String(s ?? "") + .replace(/\|/g, "\\|") + .replace(/\s*\n\s*/g, " "); +const table = (head: string[], rows: unknown[][]) => [ + `| ${head.map(cell).join(" | ")} |`, + `|${head.map(() => "---").join("|")}|`, + ...rows.map((r) => `| ${r.map(cell).join(" | ")} |`), +]; +``` + +Another pattern from a Norwegian build: a Markdown twin per SKU (`/produkt/{sku}.md`, and `?format=md`), via +`rewrites()` in `next.config.ts`. + +## One source of truth + +The HTML spec sheet, the JSON-LD `additionalProperty`, the Markdown table, llms-full.txt and an MCP server's +product detail all render the same `SpecRow`s. Build them in one module (`spec-text.ts`), and the five readers +can't disagree about a value, a unit or whether a feature is stated. diff --git a/use-crystallize/skills/seo-geo/references/validation.md b/use-crystallize/skills/seo-geo/references/validation.md new file mode 100644 index 0000000..9dead43 --- /dev/null +++ b/use-crystallize/skills/seo-geo/references/validation.md @@ -0,0 +1,162 @@ +# Validating structured data and the crawler's view + +Three layers, each catching what the others miss: the schema.org vocabulary (does every type and property exist, +and fit where it is used), Google's rules for rich results (which ask for more than schema.org), and what a +crawler actually receives (headers, `<head>`, robots, sitemap, Markdown). + +## 1. The schema.org vocabulary check + +Easy-to-get-wrong properties pass JSON syntax checks and most linters: `leaseLength` on a `Product` (it belongs to +`Offer`), `isConsumableFor` on an `Offer` (it belongs to `Product`), a misspelt `inCodeSet`, a type that doesn't +exist. This script reads the official schema.org release file and checks every `@type` and property on a page, +through the class hierarchy (`ProductGroup` is a `Product`, `OnlineStore` an `Organization`). Node 20+, no +dependencies. Put it in `scripts/` and run it in CI against a deployment or saved HTML. + +```js +#!/usr/bin/env node +// Checks the JSON-LD on pages against the schema.org vocabulary: every @type must exist, every property must exist +// and be allowed on the node's type (domainIncludes, through the class hierarchy). Node 20+, no dependencies. +// +// node check-schema-org.mjs https://shop.example/en https://shop.example/en/some/product +// node check-schema-org.mjs page.html data.jsonld +// +// Exit code 1 when anything is wrong, so it can gate CI. +import { readFile } from "node:fs/promises"; + +const VOCAB = "https://schema.org/version/latest/schemaorg-current-https.jsonld"; +const S = "schema:"; +// Keys that are JSON-LD syntax or Google conventions, not schema.org properties. +const IGNORE = new Set(["@context", "@id", "@type", "@graph", "@value", "@language", "query-input"]); + +const graph = (await (await fetch(VOCAB)).json())["@graph"]; +const types = (n) => [n["@type"]].flat(); +const ids = (v) => [v ?? []].flat().map((x) => x["@id"]); +const parents = new Map(); +const props = new Map(); +for (const n of graph) { + if (types(n).includes("rdfs:Class")) parents.set(n["@id"], ids(n["rdfs:subClassOf"])); + if (types(n).includes("rdf:Property")) props.set(n["@id"], { domain: ids(n["schema:domainIncludes"]) }); +} +const ancestors = (t, seen = new Set()) => { + if (seen.has(t)) return seen; + seen.add(t); + for (const p of parents.get(t) ?? []) ancestors(p, seen); + return seen; +}; + +async function sources(arg) { + const text = /^https?:\/\//.test(arg) + ? await (await fetch(arg, { headers: { "user-agent": "schema-check" } })).text() + : await readFile(arg, "utf8"); + if (arg.endsWith(".json") || arg.endsWith(".jsonld")) return [JSON.parse(text)]; + return [...text.matchAll(/<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g)].map((m) => + JSON.parse(m[1]), + ); +} + +const problems = []; +function walk(node, where) { + if (Array.isArray(node)) return node.forEach((n, i) => walk(n, `${where}[${i}]`)); + if (!node || typeof node !== "object") return; + const own = node["@type"] + ? [node["@type"]].flat().map((t) => (t.startsWith("http") ? t.replace(/^https?:\/\/schema\.org\//, S) : S + t)) + : []; + for (const t of own) if (!parents.has(t)) problems.push(`${where}: unknown type ${t.slice(S.length)}`); + const all = new Set(own.flatMap((t) => [...ancestors(t)])); + for (const [key, value] of Object.entries(node)) { + if (IGNORE.has(key)) continue; + const p = props.get(S + key); + if (!p) problems.push(`${where}: unknown property ${key}`); + else if (own.length && !p.domain.some((d) => all.has(d))) + problems.push( + `${where}: ${key} is not a property of ${own.map((t) => t.slice(S.length)).join("/")} (domain: ${p.domain.map((d) => d.slice(S.length)).join(", ")})`, + ); + walk(value, `${where}.${key}`); + } +} + +for (const arg of process.argv.slice(2)) { + const blocks = await sources(arg); + if (!blocks.length) problems.push(`${arg}: no JSON-LD found`); + blocks.forEach((b, i) => walk(b, `${arg}#${i}`)); +} +for (const p of problems) console.log(p); +console.log( + problems.length + ? `${problems.length} problem(s)` + : "OK: every type and property is in schema.org and fits its type", +); +process.exit(problems.length ? 1 : 0); +``` + +```bash +node scripts/check-schema-org.mjs https://shop.example/en https://shop.example/en/some/product +node scripts/check-schema-org.mjs page.html structured-data.jsonld +``` + +What it reports (a deliberately broken sample): + +``` +bad.jsonld#0: leaseLength is not a property of Product (domain: Accommodation, Offer, RealEstateListing) +bad.jsonld#0: unknown property colour +bad.jsonld#0.offers: isConsumableFor is not a property of Offer (domain: Product) +bad.jsonld#0.brand: unknown type Brandd +4 problem(s) +``` + +- It checks names and domains, not value types (`rangeIncludes`) or Google's required fields. +- `query-input` on a `SearchAction` is a Google convention, not a schema.org property; the script ignores it. +- Pick sample URLs from the sitemap so every page type is covered: home, a category, a brand, a product with + variants, a product without, a rental, an article. +- Fetching a page with a plain user agent tests what browsers get. To test a crawler's copy, add the crawler's + user agent to the `fetch` headers. + +## 2. Google's rules + +The [Rich Results Test](https://search.google.com/test/rich-results) and the Merchant listing reports check what +Google needs for product snippets and merchant listings: `offers` with `price` and `priceCurrency`, `availability`, +and recommended `shippingDetails`, `hasMerchantReturnPolicy`, `aggregateRating`/`review`. Treat its warnings as +questions, not orders: add a return policy or shipping details only if the store has them, and never a rating +without reviews. The [Schema Markup Validator](https://validator.schema.org) shows the parsed graph, useful for +`@id` links between nodes. + +## 3. The crawler's view, with curl + +Run these against the deployment, not a local `next start`: + +```bash +SITE=https://shop.example +GB='Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Chrome/138.0.0.0 Safari/537.36' + +# robots.txt: AI crawler block, Content-Signal, private routes, sitemap +curl -s $SITE/robots.txt + +# sitemap: count URLs and hreflang alternates +curl -s $SITE/sitemap.xml | grep -c '<loc>' +curl -s $SITE/sitemap.xml | grep -c 'xhtml:link' + +# llms.txt and a Markdown twin, both ways +curl -sI $SITE/llms.txt | grep -i content-type +curl -sI $SITE/en/some/product.md | grep -i 'content-type\|x-robots-tag\|^link\|^vary' +curl -s -H 'Accept: text/markdown' $SITE/en/some/product | head -20 + +# <head> as Googlebot sees it (see crawlers.md for the loop over every user agent) +curl -s -A "$GB" $SITE/en/some/product | head -c 6000 | grep -o '<title>[^<]*' +``` + +Expect `text/markdown` with `x-robots-tag: noindex`, a canonical `Link` header and `Vary: Accept` on the +Markdown twin; a `` before `</head>` for every user agent. + +## 4. Ask an answer engine + +The end-to-end test: ask ChatGPT, Claude or Perplexity (with browsing) for a product's voltage, weight and price +incl. VAT in a given market, and for the store's llms.txt. Wrong or missing answers usually point at metadata +outside `<head>`, a disallowed path, or a fact that is only in client-rendered HTML. + +## What to automate + +- The vocabulary check on a sample of sitemap URLs, after each deploy. +- The `<head>` check per user agent on a product and a category URL. +- A test that no spec `PropertyValue` has `value: false` (unset booleans read `false` and should have been left + out; `valueAddedTaxIncluded: false` is fine). +- A test that hreflang in the sitemap matches the translated paths from Discovery. diff --git a/use-crystallize/skills/storefront/SKILL.md b/use-crystallize/skills/storefront/SKILL.md new file mode 100644 index 0000000..ce35ff3 --- /dev/null +++ b/use-crystallize/skills/storefront/SKILL.md @@ -0,0 +1,436 @@ +--- +name: storefront +description: > + Build a storefront (web shop, B2B portal, catalogue site, headless frontend) on Crystallize: which API to call + for each task (Discovery for every catalogue read, the Shop API for carts, customer prices, checkout, orders, + bookings and subscriptions, Catalogue and Core only where named), which tokens and scopes each needs and what + may run in the browser, the request path of category, product, search, cart and checkout pages, caching + Discovery reads and revalidating on publish, translated paths and language/market routing, B2B contract prices + against a public Discovery, draft preview in Crystallize custom views, performance, accessibility and security + headers. Use when starting or reviewing any frontend, choosing between Discovery, Catalogue, Core and the Shop + API, wiring Next.js, Remix, Astro, Nuxt or another SSR app to Crystallize, or debugging slow pages, wrong + prices, missing orders, a stale page after publish or a broken page after a model change. Trigger on + "storefront", "frontend", "headless", "web shop", "PLP", "PDP", "product listing", "product page", "category + page", "cart drawer", "checkout", "Discovery API", "Shop API", "which API", "use cache", "cacheTag", + "revalidateTag", "revalidate on publish", "webhook", "preview", "draft", "draft mode", "custom view", + "publicationState", "hreflang", "i18n routing", "market", "B2B price", "contract price", "variantGroups", + "variant(selected", "Core Web Vitals", "LCP", "accessibility", "security headers", "CSP", "Next.js", "Cache + Components", "PPR". +metadata: + author: Crystallize + version: "1.0" +--- + +# Crystallize Storefront + +A Crystallize storefront reads the catalogue from **Discovery** and does everything about a shopper on the +**Shop API**. Nothing else is in the request path. That one rule settles most design questions, and breaking it +is behind most of the slow pages, wrong prices and missing orders seen in real builds. + +This skill is the workflow: the contract, the request path per page type, and the rules that keep cached pages +correct. The query and mutation details live in [[query]] and [[mutation]]; prices in [[pricing]]; payment in +[[payments]]. Detail for this skill is in `references/`. + +> Drawn from seventeen Crystallize storefront builds (September–November 2026, Next.js 16 with Cache Components +> on Vercel, all on Discovery and the Shop API). Draft reads through Discovery were verified on 2026-11-12: on an +> open Discovery, `publicationState: draft` returned the same 541 drafts with and without credentials. Where a +> claim comes from one build, it says so. + +## The contract in five lines + +1. **Discovery: every catalogue read.** Item by path, browse, search, typeahead, facets, variant groups, + translated paths, list and market prices, stock per location, ranking and similarity. Published content by + default; drafts with `publicationState: draft` (on an open Discovery, to anyone). Eventually consistent. +2. **Shop API: everything about a shopper.** Carts, the price for this customer and market, promotions and + vouchers, `place`, orders, payments, pipeline stages, the shopper's order history, customers, bookings, + subscription contracts, locks. +3. **Catalogue API: the synchronous fallback.** Per-customer price lists for display + (`priceFor(customerIdentifiers)`), server-side, and reads that must be in sync with a publish: Discovery is + updated asynchronously, Catalogue at once. Not for path lookups, preview or hreflang: Discovery does + those. +4. **Core API: never in the request path.** Seeding, imports, scheduled jobs, webhooks, admin tools behind staff + login. It is rate limited. +5. **Legacy PIM API: setup only.** Markets, VAT types, pipelines, stock locations, tenant defaults. + +The full decision table (task → API → call → token → where) is in +[references/api-contract.md](references/api-contract.md). + +## Credentials, and what may run in the browser + +| API | Endpoint | Credential | From the browser? | +| --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| Discovery | `https://api.crystallize.com/{tenant}/discovery` | None when open (the default); `X-Crystallize-Static-Auth-Token` when restricted | Yes if open, and then **everything it serves is public**: every price variant, every market price list, every draft | +| Shop API | `https://shop-api.crystallize.com/{tenant}/{cart,order,customer,…}` | A JWT from `POST …/{tenant}/auth/token`, minted with an access token pair scoped to this tenant (or unscoped) | **No.** Server only. The browser holds the cart id, in an httpOnly cookie | +| Catalogue | `https://api.crystallize.com/{tenant}/catalogue` | Open, static token or token pair, per tenant setting | Only open, published reads; contract prices are server-only | +| Core | `https://api.crystallize.com/@{tenant}` | Token pair | Never | + +- **The Shop JWT is per tenant, not per shopper.** Cache it on the server and refresh it before it expires. The + API default is one day; `@crystallize/js-api-client` defaults to 12 hours. An expired or rejected token + answers 401 with `{ success: false }` and no `errors`: drop the cached token and retry once. +- **Ask for the scopes you use**: `cart`, `cart:admin`, `order`, `customer`, `subscription-contract`, `booking`, + `booking:admin`, `lock`. `/booking/admin` needs **both** `booking` and `booking:admin`: a token with only + `booking:admin` is refused with "Invalid Scopes". Mint a separate token for `subscription-contract`; a token + carrying every scope was seen to lack subscription access silently. +- **The Shop API reads products from the Catalogue with the request's credentials.** On a tenant whose Catalogue + requires a token, every hydrate needs it. +- Never put a token in a `NEXT_PUBLIC_*` (or any client-bundled) variable. See [[permissions]] for which + token pair mints Shop tokens. + +## Before you start + +- [ ] The tenant is ignited for Discovery, and every component you render is `discoverable` (a + non-discoverable component is simply absent from the schema). See [[query]]. +- [ ] New shapes or components have been through an ignite and answer reliably: query a new field ten times in a + row before shipping code that depends on it. +- [ ] You have an access token pair for the Shop API, scoped to this tenant, server-side only. +- [ ] If drafts, price lists or contract prices must stay private, Search & Discovery and Catalogue are restricted, + Discovery has been re-ignited since, and an anonymous Discovery call is refused several times in a row. +- [ ] Languages, price variants, markets, VAT types and stock locations exist, and you know their identifiers + (they become Discovery field names: `nokPrice`, `<location>Stock`). +- [ ] Find a reference implementation with the capabilities you need (below). + +## Two small clients + +Discovery, cached on the server, with retries on rate limits and gateway errors +(trimmed from a working Next.js 16 storefront): + +```ts +import { cacheLife, cacheTag } from "next/cache"; + +const ENDPOINT = `https://api.crystallize.com/${process.env.CRYSTALLIZE_TENANT_IDENTIFIER}/discovery`; + +export async function discovery<T>( + query: string, + variables: Record<string, unknown> = {}, + opts: { draft?: boolean } = {}, +) { + // Draft reads (editor preview) are never cached. + return opts.draft ? request<T>(query, variables) : cached<T>(query, variables); +} + +async function cached<T>(query: string, variables: Record<string, unknown>): Promise<T> { + "use cache: remote"; + cacheLife("hours"); + cacheTag("discovery"); // the publish webhook clears this tag + return request<T>(query, variables); +} + +async function request<T>(query: string, variables: Record<string, unknown>): Promise<T> { + const headers: Record<string, string> = { "content-type": "application/json" }; + // Only on a restricted Discovery; an open one takes no credentials. + const token = process.env.CRYSTALLIZE_STATIC_AUTH_TOKEN; + if (token) headers["X-Crystallize-Static-Auth-Token"] = token; + let json; + for (let attempt = 0; ; attempt++) { + const res = await fetch(ENDPOINT, { method: "POST", headers, body: JSON.stringify({ query, variables }) }); + const text = await res.text(); + try { + if (res.status === 429 || res.status >= 500) throw new Error(`Discovery ${res.status}`); + json = JSON.parse(text); + break; + } catch (e) { + if (attempt >= 4) throw e; + await new Promise((r) => setTimeout(r, 250 * 2 ** attempt + Math.random() * 200)); + } + } + if (json.errors) throw new Error(json.errors.map((e: { message: string }) => e.message).join("\n")); + return json.data as T; +} +``` + +Shop API, server only, with the token cached in module scope: + +```ts +const SHOP = `https://shop-api.crystallize.com/${process.env.CRYSTALLIZE_TENANT_IDENTIFIER}`; +let jwt: { token: string; expires: number } | null = null; + +async function token() { + if (jwt && jwt.expires > Date.now() + 60_000) return jwt.token; + const res = await fetch(`${SHOP}/auth/token`, { + method: "POST", + headers: { + "content-type": "application/json", + "x-crystallize-access-token-id": process.env.CRYSTALLIZE_ACCESS_TOKEN_ID ?? "", + "x-crystallize-access-token-secret": process.env.CRYSTALLIZE_ACCESS_TOKEN_SECRET ?? "", + }, + body: JSON.stringify({ scopes: ["cart", "order"], expiresIn: 18000 }), + }); + const { token } = (await res.json()) as { token: string }; + jwt = { token, expires: Date.now() + 18000 * 1000 }; + return token; +} + +export async function shop<T>(query: string, variables = {}, endpoint: "cart" | "order" = "cart"): Promise<T> { + for (let attempt = 0; ; attempt++) { + const res = await fetch(`${SHOP}/${endpoint}`, { + method: "POST", + headers: { "content-type": "application/json", authorization: `Bearer ${await token()}` }, + body: JSON.stringify({ query, variables }), + cache: "no-store", + }); + // A rejected token answers 401 with { success: false } and no `errors`: get a new one, once. + if (res.status === 401 && attempt === 0) { + jwt = null; + continue; + } + const json = await res.json().catch(() => null); + if (json?.errors) throw new Error(json.errors.map((e: { message: string }) => e.message).join("\n")); + if (!res.ok || !json?.data) throw new Error(`Shop API ${endpoint}: HTTP ${res.status}`); + return json.data as T; + } +} +``` + +In Next.js with Cache Components, call `await connection()` at the top of `shop()` for anything per-shopper, so a +cart never ends up in a prerendered shell. See [references/nextjs-pitfalls.md](references/nextjs-pitfalls.md). + +## The request path, per page type + +### Any catalogue page (home, category, brand) + +- [ ] Language and market come from the **path** (`/no/…`), not a cookie. A cookie market means crawlers only + ever see the default market's prices. +- [ ] A server component reads Discovery through the cached client. Build variables in a fixed order (the cache + key is query + variables). +- [ ] Per-shopper parts (taste-ranked rails, "shopping as", contract prices) stream behind `<Suspense>` with real + content as the fallback, so the shell is complete without them. +- [ ] Card images ask for trimmed variants only (`variants(types: "webp", minWidth, maxWidth)`). Rails and menus + skip `facets`, which cost about 17 KB per read. +- [ ] Look up the item by full path, never by the last segment: paths are unique only within their folder. + +```graphql +query Resolve($path: String!) { + search(language: en, filters: { path: { equals: $path } }) { + hits { + itemId + shape + name + } + } +} +``` + +### Product listing (PLP) with one card per colourway + +`variantGroups` groups a product's variants by an attribute, so a listing card shows each colourway with its own +price range, stock and images, filtered to what the shopper asked for. It never removes a group or changes hits, +facets or paging: groups with a matching variant come first, the rest read `matched: false`. Trimmed from a +fashion build: + +```graphql +colours: variantGroups(by: ["colour"], filter: $variantFilter) { + matched + attributes { value } + summary { + matchedInStock(location: "web") + price: matchedPrice(variant: "default") { min max } + } + representative { sku } + images { url width height variants(types: "webp", minWidth: 500, maxWidth: 768) { width } } + sizes: values(of: "size") { value sku matched inStock(location: "web") } +} +``` + +`filter` is a `VariantFilterInput` (exact operators only). Attribute names and values are case-sensitive. Every +group's images come back, so image selection is most of the payload: trim it per context. See [[query]]. + +### Product detail (PDP) + +- [ ] One `search(filters: { path: { equals } })` returns the product, variants, trimmed images, relations + (already in the request's language), breadcrumbs (which end with the item itself) and typed specs. +- [ ] One aliased query by `itemId` gives the item's path in every language, for hreflang and the language + switcher ([references/i18n-routing.md](references/i18n-routing.md)). +- [ ] The buy box resolves the chosen options with `variant(selected: [{ attribute, value }])`, the first variant + carrying every pair, and passes its SKU to the cart. Stock comes from that variant's `<location>Stock`. +- [ ] List price from Discovery for everyone; the contract price from a cached server-side read for a signed-in + buyer (below); booking availability from the Shop API, loaded after the product. +- [ ] JSON-LD and the Markdown twin come from the same typed rows. An unset boolean reads `false`: treat it as + "not stated". See [[seo-geo]]. + +### Search results + +`browse.<shape>(language, term: $term, options: { fuzzy: { fuzziness: SINGLE } }, sorting: { score: desc })`. +Drop hits with `score` 0 (they matched only through a filter), and widen to `DOUBLE` when nothing is left. When +the query also uses `rankBy`, add `{ signal: relevance }` or the term stops mattering ([[vector-ranking]]). The +search page is `noindex, follow`. + +### Cart and checkout + +The cart is a server action over Shop `hydrate`; checkout is `setCustomer` → `setMeta` → `place` → payment → +`createFromCart` in the payment webhook. Outline below; full flow in +[references/cart-checkout.md](references/cart-checkout.md). + +## Caching and revalidation on publish + +- Cache Discovery reads on the server, keyed on query + variables, tagged `discovery`. +- On publish, a Core webhook (`concern: "items"`, events `publish` and `unpublish`) calls a route that clears the + tag. Page, JSON-LD, sitemap, Markdown twins and llms.txt then follow in one step. `concern: "item"` is + accepted by `createWebhook` and never fires. +- Cached functions never throw a transient error into the cache: retry inside, and fall back to empty. +- Per-customer data (order history, taste, contract prices) is cached per customer or organisation and tagged so + checkout can expire it (`updateTag`). +- Draft reads are never cached. +- Revalidation is billed on some hosts: one build found cache writes were most of its Vercel bill, and fixed it + with `cacheLife('hours')` plus the webhook, and hover-only prefetch. + +Code for the webhook route and its setup: [references/caching-and-revalidation.md](references/caching-and-revalidation.md). + +## Translated paths and i18n routing + +- Every URL starts with the language (`/en`, `/no`); the proxy redirects `/` from a cookie, then + `Accept-Language`, then the default. +- Paths are translated per language, so match items across languages by `itemId`, never by slug. +- `<html lang>`, hreflang and schema.org use BCP 47 (`nb`), not the tenant's language code (`no`). Add + `x-default`. + +Details and code: [references/i18n-routing.md](references/i18n-routing.md). + +## Cart and checkout UI + +- **`hydrate` replaces the whole cart.** Send every line, every time; a booked line must come back with its + `lineId`, `meta` and `booking`, or the reservation is released. +- The hydrate answer is the source of truth for the drawer. On a cart line, `price.net` is the **line total**; + `variant.price.net` is the unit price. +- Price context on every hydrate: `currency`, `selectedVariantIdentifier`, `taxRate` as a fraction (`0.25`), + `decimals: 4` (round for display only), `markets` for price lists, and the customer. +- Re-hydrate a stored cart when it is stale, was built in another language, or for another customer. +- Optimistic UI on top: show the line at once; the hydrate takes 200–400 ms. +- After `place` the cart is locked. If order creation then fails, the shopper needs a new cart. +- `createFromCart` moves the cart to `ordered`; there is no `fulfill` afterwards. +- New orders take seconds to minutes to appear in `orders(customerIdentifier)`: the confirmation page shows the + order `createFromCart` returned, and says so. + +## B2B prices against a public Discovery + +An open Discovery serves every price variant and every market price list to anyone who knows the field name. +**Confidential terms never go there.** With price lists or contract prices, restrict Catalogue and Search & +Discovery and read them with the static token from the server; Discovery needs a re-ignite after the change +([[query]]). Open APIs are fine for a catalogue whose prices are all public. + +| Need | Where | +| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| List, sale, "from" price | Discovery `<variant>Price`, `variantGroups.summary.price` | +| Public market price | Discovery `<variant>PriceFor(marketIdentifiers)`, only for the SKUs on screen (about 1.4 s per 100 products per market) | +| The buyer's contract price, in the cart | Shop `hydrate` with the organisation as customer and its price-list `markets` in the price context. Re-hydrate when the customer changes: price lists apply only to a cart hydrated with them | +| The buyer's contract price, on the page | Server-side, cached per organisation: a throw-away `hydrate` with the customer, or Catalogue `priceFor(customerIdentifiers)` | + +- The customer on a B2B cart is the **organisation** (orders belong to it); the person who ordered goes in cart + meta. +- **Markets come from the server session.** A market identifier works as a key: a guest cart that sends a + contract market gets the contract price. Never take markets from the browser, a query string or a form field + ([[pricing]]). +- Target organisations by `customerIdentifiers` or markets. Customer-group price lists were reported failing + with `CustomerGroupNotFoundError` on several tenants; see [[pricing]]. +- Show incl. or excl. VAT per segment. Prices in Crystallize are usually net; the market decides currency, + price variant and VAT rate. + +## Draft preview + +Draft preview is a Discovery read with `publicationState: draft`, done server-side behind the editor's preview +mode, and never cached. Editors open it from a **custom view** in the Crystallize App, which frames the storefront +next to the item. Setup, code and verification: [references/preview.md](references/preview.md). + +- [ ] **Custom view** (Settings → Custom views): a URL template such as + `https://shop.example.com/api/preview?secret=…&language={{language}}&itemId={{itemId}}&path={{itemPath}}`. + Placeholders: `{{language}}`, `{{itemId}}`, `{{itemPath}}`, `{{itemExternalReference}}`, `{{variantSku}}`. + See the [Custom views](https://crystallize.com/docs/pim/catalogue/custom-views) doc. +- [ ] **Always turn on "Show responsive device toolbar in preview".** The editor switches between mobile and + desktop in the App's toolbar; the storefront only has to be responsive and adds no device buttons or + preview chrome of its own. +- [ ] **A preview route** checks a secret, resolves the item's storefront URL from its **draft**, by item id and + per language (paths are translated and have no `/{lang}` prefix), turns on preview mode (Next's + `draftMode().enable()`) and redirects. Redirect only to a path Discovery returned. +- [ ] **Every Discovery read in preview mode adds `publicationState: draft`** (every field that takes `language` + accepts it, nested `items`/`variants` included). In Next.js, read `draftMode().isEnabled` inside the + `'use cache'` client: off while prerendering, so normal traffic stays cached; with the cookie nothing is + saved. +- [ ] **No caching, `noindex`**, and the App's `frontend-preview-listener.js` loaded in preview mode only, so the + view reloads when the editor saves. +- [ ] **Framing:** `frame-ancestors 'self' https://app.crystallize.com` on the preview route and preview-mode + responses only; every other page keeps `X-Frame-Options: SAMEORIGIN`. +- [ ] **The preview cookie is `SameSite=None; Secure`** (it is set and read inside a third-party iframe), and + `Partitioned`. Next's draft cookie is `Lax` in `next dev`: test the framed preview on a production build. +- **On an open Discovery every draft is public.** Anyone who sends `publicationState: draft` gets it, no + credentials needed (verified 2026-11-12 on two tenants, including unpublished drafts read anonymously). The + preview secret guards the preview mode, not the data. Don't keep confidential or embargoed content in drafts on + an open tenant; if drafts must stay private, restrict Discovery, re-ignite, and send the static token from the server. + The restriction takes effect only after `igniteDiscoApi` and a few minutes more ([[query]]). +- **Never render drafts to crawlers or the public.** Preview responses are `noindex` and uncached, the preview + route is under a `Disallow`ed path and not in the sitemap, and nothing in the store links to it. + +## Consistency the storefront has to live with + +- **Discovery is eventually consistent.** `publishItem` answers before anything is indexed. New shapes and + components need an ignite, and the new schema reaches the nodes over minutes; an error answered in that window + can be cached per query body. +- **Discovery under load** answered HTTP 200 with `errors: [{ message: "Response Error" }]` after about 900 + prerendered pages in one build. Retry on that message, cap prerender concurrency, or render on demand. +- **The Shop order list is a second store.** Orders appear in `orders(customerIdentifier)` after seconds to + minutes. Read by id for anything you just wrote; never use the listing for idempotency. +- **Explicit `null` in Discovery variables is rejected.** Leave the key out instead. + +## Pitfalls + +| Symptom | Cause | Fix | +| ------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| Pages slow, 429s in logs | Core or PIM in the request path | Discovery for reads, Shop API for the shopper | +| Contract prices visible to anyone | Negotiated prices in a price variant or market list on an open Discovery | Shop hydrate or Catalogue `priceFor`, server-side | +| Cart loses lines | `hydrate` sent only the changed line | Send the whole cart every time | +| Line total multiplied by the quantity again | `price.net` on a cart line is the line total | Use `variant.price.net` for the unit price | +| Order missing from the account page | Order listing lag | Show the returned order; say history updates shortly | +| Page stale after publish | No webhook, or `concern: "item"` | `concern: "items"` → route that clears the `discovery` tag | +| Page broke after a model change | Schema not propagated; an error cached per query body | Ignite, wait for ten good answers, then ship | +| Embargoed product readable before launch | Drafts on an open Discovery are public, or Discovery restricted without a re-ignite | Restrict Discovery, re-ignite, use the static token; or keep it out of drafts | +| Crawlers see only the default market | Market chosen by cookie | Language and market in the path | +| Googlebot gets no `<title>` or canonical | Dynamic metadata streamed into `<body>`; cached shell served to Googlebot | Cacheable metadata in the shell's `<head>` ([references/performance.md](references/performance.md)) | +| Search page fails for everyone | An explicit `null` in Discovery variables | Omit the key | +| `og:image` blank in link previews | AVIF share image | Original format (JPEG/PNG) or WebP, never AVIF ([[responsive-images]]) | + +## Images + +Use [[responsive-images]]: plain `<picture>`/`<img>` straight from `media.crystallize.com`, `srcset` from the +returned variants, `sizes` that match the CSS, WebP rather than AVIF, `size` selected. Preconnect to the media host +without `crossOrigin`. `og:image` and JSON-LD `image` use an absolute URL to the **original format**, never AVIF. + +## Reference implementations + +[superfast.shop](https://superfast.shop) lists live demo stores, one per industry, each on its own tenant with a +storefront on Discovery and the Shop API, built agentically with the Crystallize MCP. Before designing a +storefront, find one with the capabilities the user needs and read how it does it: + +- `https://superfast.shop/demos.json`: every store, its capabilities, live URL and build prompt, as JSON. +- `https://superfast.shop/start.md`: interviews the user and hands back a build prompt. +- `https://superfast.shop/llms.txt`; the list filters by URL, e.g. `?cap-model=subscriptions`, `?audience=b2b`. +- `https://superfast.shop/demos/<id>` and `https://superfast.shop/demos/<id>/prompt.md`: a store's page and its + "build your own like it" prompt. Each live store has its own `/llms.txt`. + +| Store | Look at it for | +| ------------------ | --------------------------------------------------------------------------------------------------- | +| `photo-store` | Typed specs as filters, vector ranking per shopper, an MCP server and an on-site assistant | +| `tools-universe` | Rentals and bookings, ETIM typed specs, battery platforms, quotes, stock per location, MCP, JSON-LD | +| `food-universe` | B2B invoice and credit limits, GS1 and allergens, recipes to basket, draft preview | +| `fashion-universe` | Colourways and sizes with `variantGroups`, sale pricing, multi-market | +| `lab-universe` | Approvals, budgets, contract and volume prices, standing orders | +| `screen-universe` | Subscriptions with trials, metered usage | + +## References + +| File | Read it when | +| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| [references/api-contract.md](references/api-contract.md) | Choosing the API, endpoint, token and place for any task | +| [references/caching-and-revalidation.md](references/caching-and-revalidation.md) | Caching Discovery, the publish webhook, per-customer caches | +| [references/i18n-routing.md](references/i18n-routing.md) | Language and market routing, translated paths, hreflang, the language switcher | +| [references/cart-checkout.md](references/cart-checkout.md) | Hydrate, place, order, bookings, quotes, the confirmation page | +| [references/performance.md](references/performance.md) | LCP, prefetch, function region, prerendering, metadata in `<head>` | +| [references/accessibility.md](references/accessibility.md) | Drawers, skip link, focus, forms, live regions | +| [references/security-headers.md](references/security-headers.md) | Companion headers, CSP, frame-ancestors, cookies | +| [references/preview.md](references/preview.md) | Draft preview in a Crystallize custom view: route, draft reads, framing | +| [references/nextjs-pitfalls.md](references/nextjs-pitfalls.md) | Next.js 16 Cache Components and PPR traps | + +## Related skills + +[[query]] and [[mutation]] hold the API details. [[pricing]] covers price variants, price lists and the cart +price context; [[payments]] the provider session and webhook; [[bookable-resources]] and [[subscriptions]] their +flows. [[vector-ranking]] ranks rails and search per shopper. [[responsive-images]] covers images. +[[information-architecture]] covers paths. [[seo-geo]] makes the store findable and quotable; +[[agentic-commerce]] lets AI agents shop it on the same code. diff --git a/use-crystallize/skills/storefront/references/accessibility.md b/use-crystallize/skills/storefront/references/accessibility.md new file mode 100644 index 0000000..1fbda93 --- /dev/null +++ b/use-crystallize/skills/storefront/references/accessibility.md @@ -0,0 +1,83 @@ +# Accessibility + +The accessibility tree is what screen readers read, and it is also what AI browsers and in-browser agents read and +act on. A drawer that is hidden but focusable, or a quantity that is a `<span>` between two buttons, is broken for +both. These are the gaps a Modern Web Guidance (MWG v1.0) audit found on two Crystallize storefronts, with the fix +for each. + +## Drawers and dialogs (cart, assistant, filters) + +What was wrong: an `<aside role="dialog">` without `aria-modal`; when closed, a wrapper with `aria-hidden` that +stayed focusable (only translated off-screen), so Tab reached the hidden close button and textarea; when open, +the page behind was not inert, focus did not move in or come back, and Escape was a hand-written listener. + +Use a native `<dialog>` opened with `showModal()`. The browser then makes the rest of the page inert, exposes a +modal dialog, handles Escape and returns focus on close. + +- Name it with `aria-labelledby` pointing at its heading. Put `autofocus` on the first control. +- `closedby="any"` for light dismiss. +- **No** `role="dialog"`, focus trap or Escape handler of your own. +- **Never** `aria-hidden="true"` on a focusable element or its parent. A closed drawer is not rendered, or is + `inert`. +- Don't lock scroll with `overflow: hidden` on `<html>` or `<body>` (layout shift, broken sticky elements). Use + `overscroll-behavior: contain` on `dialog:modal` and `overflow: hidden` on `dialog::backdrop`. +- Closed drawers cast no shadow onto the page edge. + +## Skip link + +Put a skip link first in `<body>`, before the header and mega menu (WCAG 2.4.1). One store had about 60 KB of +header and menu, with dozens of links, before `<main>`. + +```tsx +<body> + <a href="#main" className="skip-link"> + {t.skipToContent} + </a> + <Header lang={lang} /> + <main id="main">{children}</main> +</body> +``` + +Style `.skip-link` off-screen until `:focus-visible`. + +## Focus + +- A focus indicator with a contrast ratio of **at least 3:1** against what is around it. A lime outline measured + 1.5:1 on the page's off-white. +- Inputs must not replace the outline with a 1 px border change. +- `:focus-visible`, not `:focus`. + +## Forms: quantity, steppers, errors, autofill + +- **Quantity is a labelled native control**: `<input type="number" name="quantity" min="1">`. Steppers have names + that include the product ("Decrease quantity of Combi drill 18V"), not `−` or `−1`. An agent can then read and + set the quantity instead of clicking N times, and an agentic form can build its schema from it. +- Variant options are native radio inputs in a `fieldset` with a `legend`. +- **Announce errors**: a live region (`role="alert"` for errors, `role="status"` for progress) or move focus to + the message. A plain `<p class="error">` is silent. +- **Enter to submit** in a textarea or a search box checks `isComposing` (skip when + `e.nativeEvent.isComposing || e.keyCode === 229`), so an IME user doesn't send half-composed text. +- **Autofill** on checkout fields: `autocomplete="email"`, `name`, `shipping street-address`, `postal-code`, + `cc-number`, and so on. Offer guest checkout. + +## Structure + +- One `<h1>` per page, and an unbroken heading outline. Watch Suspense fallbacks: a fallback with its own `<h1>` + plus the resolved content gave a category page two in the raw HTML. +- Breadcrumbs: `<nav aria-label="Breadcrumbs"><ol>`, the last item with `aria-current="page"`, dividers in CSS. +- Wrap search and filtering in `<search>` rather than `<form role="search">`. +- Landmarks: one `<main>`, labelled `<nav>`s. +- The search combobox: `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant`, a `listbox`, + and a real GET `action` so it works without JavaScript. +- Facets as plain GET links: every filtered view is crawlable, linkable and usable by an agent without JavaScript. + +## Chat and streaming text + +- A chat log is `role="log"`, but don't update it token by token: debounce, or announce the finished message. +- "Thinking" is `role="status"` text or a `<progress>`, not an `aria-label` on a `<p>`. +- Render model output as elements, never with `innerHTML`. + +## Motion + +Don't kill all motion with a global `animation-duration: 0.01ms` under `prefers-reduced-motion`. Drop the +movement (drawer slide, menu translate, scale on hover) and keep non-spatial transitions. diff --git a/use-crystallize/skills/storefront/references/api-contract.md b/use-crystallize/skills/storefront/references/api-contract.md new file mode 100644 index 0000000..3403f26 --- /dev/null +++ b/use-crystallize/skills/storefront/references/api-contract.md @@ -0,0 +1,84 @@ +# The storefront API contract + +Which API a storefront calls for each task, with which token, from where. The rule in one line: **Discovery for +every catalogue read, the Shop API for everything about a shopper, Catalogue and Core only for the tasks named +here.** + +## Decision table + +| Task | API | Call | Token / scope | Where | +| ------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------- | +| Item by path (product, category, document) | Discovery | `search(language, filters: { path: { equals } })`, then shape fragments | none / static | server, cached | +| Category listing | Discovery | `browse.<shape>(filters: { parentPaths: { equals } })` (any depth); the `parentPaths` facet for subfolders | none / static | server, cached | +| Facets | Discovery | `summary { facets }`. Each selection option is its own field (`<field>_<optionKeyCamel>`, `exists: true`); a `NumberFacet` needs at least two `boundaries` | none / static | server | +| Card per colourway | Discovery | `variantGroups(by, filter, first)` with `matched`, `summary`, `representative` | none / static | server | +| Variant pick on the PDP | Discovery | `variant(selected: [{ attribute, value }])`, then the SKU into `hydrate` | none / static | server | +| Search results | Discovery | `term` + `options: { fuzzy: { fuzziness: SINGLE } }`, `sorting: { score: desc }`; add `{ signal: relevance }` when `rankBy` is used | none / static | server | +| Typeahead | Discovery | `filters: { name: { autocomplete: { term } } }` plus the same `term` for scoring; drop `score == 0`. Or an in-memory index built from one Discovery snapshot | none / static | server route or browser index | +| Translated paths, hreflang, sitemap | Discovery | One aliased query per language by `itemId`; a sitemap is one `browse` per language joined on `itemId` | none / static | server, build | +| Personal ranking, "more like this" | Discovery | `rankBy` + `context.userTaste` (rebuilt from Shop order history) + `nearestTo` | none / static | server | +| List, sale, "from" price | Discovery | `<variant>Price`, `variantGroups.summary.price` | none / static | server | +| Public market price | Discovery | `<variant>PriceFor(marketIdentifiers)`; only for the SKUs on screen | none / static | server | +| Contract price for display (B2B) | Shop API, Catalogue | A throw-away `hydrate` with the customer, or Catalogue `priceFor(customerIdentifiers)`, cached per organisation. **Never Discovery** | `cart` / Catalogue token | server | +| Stock on the page | Discovery | `<location>Stock` per variant, `inStock`, `stock_<location>` filters. A new stock location needs a re-ignite | none / static | server | +| Create or change the cart | Shop `/cart` | `hydrate` with the **whole** item list (it replaces), or `addSkuItem`; batch client changes into one hydrate | `cart` | server action | +| Price the cart for customer and market | Shop `/cart` | `context.price { currency, selectedVariantIdentifier, fallbackVariantIdentifiers, compareAtVariantIdentifier, markets, customerGroups, voucherCodes, decimals, taxRate }` | `cart` | server | +| Customer on the cart | Shop `/cart` | `setCustomer`, or `hydrate(customer: { identifier, isGuest: false })`; for B2B the organisation; before any booking | `cart` | server | +| Validate a voucher | Shop `/cart` | `validateVoucher(voucher)` | `cart` | server | +| Lock the cart before charging | Shop `/cart` | `place` (it hydrates one last time; charge its `total`) | `cart` | server | +| Order from the cart | Shop `/order` | `createFromCart(id, { pipelines, paymentStatus, payments })`; cart meta is copied; no `fulfill` afterwards | `order` | server, payment webhook | +| Order without a cart (accepted quote, POS) | Shop `/order` | `create` (takes `relatedOrderIds`) | `order` | server | +| Record payments | Shop `/order` | `addPayments` / `setPayments`; `paymentStatus` is set once, at creation | `order` | server | +| Move the order through stages | Shop `/order` | `addToStage(id, pipelineId, stageId)` (ids, not names), then `setMeta` | `order` | server, back office | +| Order confirmation page | Shop `/order` | The order `createFromCart` returned; `order(id)` can be "not found" for a moment | `order` | server | +| Shopper's order history | Shop `/order` | `orders(customerIdentifier, limit: 100)`; it lags and can be incomplete | `order` | server; identifier from the session | +| Customer record from the storefront | Shop `/customer` | `customer(input)`, `addAddress`, `setMeta` (synced to Core) | `customer` | server | +| Booking availability | Shop `/cart` | `availability`, `nearestAvailability`, `checkBooking` (Discovery never serves availability) | `cart` | server, after the product | +| Hold, change, release a booking | Shop `/cart` | `bookSkuItem` (one at a time per cart); re-`hydrate` without the line to release it | `cart` | server | +| Confirm a booking | Shop `/cart` | `confirmCartBooking` before **and after** `createFromCart`, once `cart.orderId` is set | `cart` | server | +| Read or cancel any reservation (staff) | Shop `/booking/admin` | `reservation(id)`, `cancel(id, reason)`, `block`, `calendar`; see [[bookable-resources]] | `booking` + `booking:admin` (both; one alone is "Invalid Scopes") | server, staff | +| Subscription sign-up and account page | One store per tenant | Shop `/subscription-contract` or Core; see [[subscriptions]] | own token / pair | server | +| Usage metering | Core only | `trackSubscriptionContractUsage`, one call per metered event, never per page view | pair | server | +| Idempotency guard | Shop `/lock` | acquire and release | `lock` | server | +| Pipeline stage names for display | PIM | `pipeline.getMany` at **build time**; write the ids into the storefront's data | pair | build | +| Cache revalidation on publish | Core (setup) | `createWebhook(concern: "items")` with `graphqlQuery` and `preserveDefaultPayload: true` | pair (setup) | setup; receiver is a server route | +| Draft preview | Discovery | `publicationState: draft`; never cached. On an open Discovery drafts are public; restrict it if they must stay private | none / static | server, behind preview mode | +| Seller or approval queue across customers | Core | `orders(filter: { … })` behind staff login, or an index fed by webhooks | pair | back office server | +| Seeding, model, publish, ignite, taste | Core, PIM, mass operations | — | pair | scripts only | + +Field names on Discovery (`nokPrice`, `<location>Stock`, `price_default`, `specs_drilling_torque_number`) are +generated from the tenant's identifiers; read them from the schema, see [[query]]. + +## Where the order lives + +Write an order in one store and read it from the same store. A storefront that lists orders from the Shop API +creates them on the Shop API (`createFromCart`, or `create` without a cart). Core `registerOrder` is for orders +nobody reads from the edge, such as imports into a back office. The order store table in [[mutation]] is the +rule. + +## Shop API token rules + +- Minted with `POST https://shop-api.crystallize.com/{tenant}/auth/token` and `{ scopes, expiresIn }`, using an + access token pair. A pair scoped to the tenant mints for that tenant only; an unscoped pair for any tenant its + user belongs to ([[permissions]]). The `@` before the tenant is + optional on the Shop API. +- Per tenant, not per shopper. Cache it server-side; refresh before `exp`. Expiry is one day by default in the + API and 12 hours in `@crystallize/js-api-client`. +- `"exp" claim timestamp check failed` means the cached token expired. A rejected token answers 401 with + `{ success: false }` and no `errors`. +- The Shop API allows browser calls only from Crystallize origins and localhost. Production calls are server-side + (server action or route), always. + +## Things that look like contradictions + +- **"Discovery is public."** It is open by default and can be restricted with a static token, which takes effect + only after a re-ignite. When open, everything it serves is public. +- **"Catalogue for exact paths."** Discovery resolves paths. Catalogue `variants` came back empty on several + tenants; keep it for per-customer price lists. +- **Customer price resolution.** Discovery resolves markets only. The Shop API resolves the cart's customer (price + lists inherited from parent customers). Catalogue resolves any customer for display. +- **Payments code that reads Core.** That runs in the payment webhook, not in page code; it is not the request + path. See [[payments]]. +- **Deterministic secondary sort.** Discovery applies sort keys in schema order, so a second key such as + `itemId` can replace a primary that sorts after it. Use one key per sort, or check the order; `score` is safe + as the primary. `{ itemId: asc }` alone is stable for full scans. diff --git a/use-crystallize/skills/storefront/references/caching-and-revalidation.md b/use-crystallize/skills/storefront/references/caching-and-revalidation.md new file mode 100644 index 0000000..1145f01 --- /dev/null +++ b/use-crystallize/skills/storefront/references/caching-and-revalidation.md @@ -0,0 +1,137 @@ +# Caching Discovery and revalidating on publish + +Discovery is fast, but a storefront that reads it on every request pays for it in latency and rate limits. Cache +every published read on the server, clear the cache when something is published, and never cache what is +per-shopper or a draft. + +## Cache published reads, keyed on query and variables + +In Next.js 16 with Cache Components, a `'use cache'` function is keyed on its arguments. Pass the query string and +variables, tag the entry, and pick a life: + +```ts +async function cached<T>(query: string, variables: Record<string, unknown>): Promise<T> { + "use cache: remote"; + cacheLife("hours"); + cacheTag("discovery"); + return request<T>(query, variables, false); +} +``` + +- **`'use cache: remote'`** on serverless hosts. The default in-memory cache lives per instance, so a read paid + for on one instance was paid again on the next. The remote handler is shared by every instance. +- **`cacheLife('hours')`, not minutes.** Every revalidation is a cache write, and on Vercel those are billed: one + build found Runtime Cache writes were about $140 of a $226 cycle with a one-minute life. Hours plus the publish + webhook keeps pages fresh without the bill. +- **Build variables in a fixed order.** The cache key is the serialised arguments; `{ a, b }` and `{ b, a }` are + two entries, and a prerender then misses its own cache. +- **Keep clocks out of cache keys.** A taste vector whose decay used `Date.now()` made every render's keys + differ ("unexpected cache miss after cache warming"). Round time to the day. +- **Cached reads never throw a transient error into the cache.** Retry inside the request (429 and 5xx, with + backoff). A failing query inside `'use cache'` broke background revalidation in one build; another made + cached reads return an empty result on failure rather than throw. +- **Rails and menus skip `facets`** (about 17 KB per read) and select only the image widths they render. + +## Revalidate on publish with a webhook + +Crystallize calls a URL when an item is published or unpublished. Register the webhook once, from a setup script on +the Core API (trimmed from a working seed step): + +```js +// The default payload is { id, type, tenantId, language, userId, webhookId }; the query adds the item's path. +const ITEM_QUERY = `query ($id: ID!, $language: String!) { + item(id: $id, language: $language) { ... on Item { id shapeIdentifier tree { path } } } +}`; + +// concern is `items` (plural): `item` is accepted by createWebhook but never fires. +const WEBHOOKS = [ + { name: "storefront-revalidate-publish", concern: "items", event: "publish" }, + { name: "storefront-revalidate-unpublish", concern: "items", event: "unpublish" }, +]; + +for (const w of WEBHOOKS) { + const input = { + ...w, + url: "https://shop.example/api/revalidate", + method: "POST", + headers: [ + { name: "x-revalidate-secret", value: process.env.REVALIDATE_SECRET }, + { name: "content-type", value: "application/json" }, + ], + preserveDefaultPayload: true, + graphqlQuery: ITEM_QUERY, + graphqlQueryTarget: "next", + }; + await core( + `mutation ($input: CreateWebhookInput!) { + createWebhook(input: $input) { ... on Webhook { id } ... on BasicError { errorName message } } + }`, + { input }, + ); +} +``` + +Make the script idempotent: list `webhooks(first: 100)` first, and `updateWebhook` the ones that exist by name. +Keep the secret in a header, never in the URL. + +The receiving route checks the secret and clears tags. With one `discovery` tag, everything follows at once: + +```ts +import { revalidateTag } from "next/cache"; +import { NextResponse, type NextRequest } from "next/server"; + +export async function POST(req: NextRequest) { + const secret = process.env.REVALIDATE_SECRET; + if (!secret || req.headers.get("x-revalidate-secret") !== secret) + return NextResponse.json({ ok: false }, { status: 401 }); + revalidateTag("discovery", "max"); + return NextResponse.json({ ok: true }); +} +``` + +Finer tags are possible: the payload carries `item.tree.path` from the webhook's query, so a route can clear +`product:<slug>` and `categories` instead of everything. One build measured a summary edit showing on production +21 seconds after publish, with stale-while-revalidate (`'max'`). + +Publishing is asynchronous (`publishItem` answers before anything is indexed), so in principle the webhook can +arrive before Discovery serves the new version. The builds did not measure this; if a page re-renders with old +content, delay the revalidation a few seconds. + +Pages, JSON-LD, the sitemap, Markdown twins and llms.txt all read through the same cached client, so one tag +clears them all. See [[seo-geo]]. + +## Per-customer caches + +Order history, the taste vector built from it, and contract prices change rarely and are slow to read. Cache them +per customer or per organisation, with a tag the checkout can expire: + +```ts +export const historyTag = (buyer: string) => `orders:${buyer}`; + +export async function tasteForBuyer(buyer: string) { + "use cache: remote"; + cacheLife("hours"); + cacheTag(historyTag(buyer)); + const orders = await orderHistory(buyer); // Shop API orders(customerIdentifier) + const today = Math.floor(Date.now() / 86_400_000) * 86_400_000; // stable all day + return tasteOf(orders, today); +} + +// In the checkout server action, after createFromCart: +updateTag(historyTag(buyer)); +``` + +A read inside `'use cache'` must not call `connection()` or other request APIs: split the Shop client into a +request-only function for these and a `connection()`-marked one for cart calls. + +## Never cache + +- **Draft reads.** Preview reads (`publicationState: draft`) go straight to Discovery. In Next.js, switch on + `draftMode()` inside the cached client: see [preview.md](preview.md). +- **Carts.** Every cart read and write is request data. +- **Anything keyed on a cookie** that is not part of the cache key. + +## Prefetch is a cost, too + +Prefetching every link in view multiplies cached reads and, on hosts that bill cache reads and writes, the bill. +Prefetch on intent (hover, focus, touch) instead. See [performance.md](performance.md). diff --git a/use-crystallize/skills/storefront/references/cart-checkout.md b/use-crystallize/skills/storefront/references/cart-checkout.md new file mode 100644 index 0000000..dfc1ed2 --- /dev/null +++ b/use-crystallize/skills/storefront/references/cart-checkout.md @@ -0,0 +1,185 @@ +# Cart and checkout on the Shop API + +The browser holds the cart id in an httpOnly cookie. Every cart read and write is a server action or route +calling the Shop API with the server's JWT. Mutation shapes and their options are in [[mutation]]; the price +context in [[pricing]]; payment providers in [[payments]]. + +## The cart is a hydrate + +`hydrate` replaces the whole cart. A server action reads the current cart, applies the change to the full list of +lines, and hydrates all of them (trimmed from a working storefront): + +```ts +"use server"; +import { cookies } from "next/headers"; +import { refresh } from "next/cache"; + +async function change(lang: string, update: (lines: Map<string, number>) => void) { + const jar = await cookies(); + const customer = await currentCustomer(); // the signed-in buyer, or undefined + const cart = await getCart(jar.get("cart")?.value, lang, customer); + // Booked lines pass through untouched; the rest are edited by SKU. + const booked = (cart?.lines ?? []).filter((l) => l.booking); + const lines = new Map((cart?.lines ?? []).filter((l) => !l.booking).map((l) => [l.sku, l.quantity])); + update(lines); + const items = [...booked.map(lineInput), ...[...lines].map(([sku, quantity]) => ({ sku, quantity }))]; + const next = await hydrate(cart?.id, items, lang, customer); + jar.set("cart", next.id, { httpOnly: true, secure: true, sameSite: "lax", path: "/", maxAge: 60 * 60 * 24 * 30 }); + refresh(); + return next.count; +} + +export const addToCart = (sku: string, quantity: number, lang: string) => + change(lang, (l) => l.set(sku, (l.get(sku) ?? 0) + quantity)); +export const setQuantity = (sku: string, quantity: number, lang: string) => + change(lang, (l) => (quantity > 0 ? l.set(sku, quantity) : l.delete(sku))); +``` + +The hydrate itself, with the price context for the language's market: + +```ts +const FIELDS = `id state isStale updatedAt context customer { identifier } + items { lineId name quantity meta variant { sku product { path name } price { net } } price { net } } + total { net gross taxAmount }`; + +export async function hydrate( + id: string | undefined, + items: LineInput[], + language: string, + customer?: CartCustomer, + markets: string[] = [], +) { + const m = MARKET[language]; + const { hydrate } = await shop<{ hydrate: RawCart }>( + `mutation Hydrate($input: CartInput!) { hydrate(input: $input) { ${FIELDS} } }`, + { + input: { + ...(id ? { id } : {}), + ...(customer ? { customer } : {}), + items: items.filter((i) => i.quantity > 0), + context: { + language, + price: { + currency: m.currency, + selectedVariantIdentifier: m.priceVariant, + pricesHaveTaxesIncludedInCrystallize: false, + taxRate: m.vat, // a fraction: 0.25 + decimals: 4, // exact line and tax amounts; round for display only + markets, // the buyer's price-list markets, from the server session: whoever sends a market gets its prices + }, + }, + }, + }, + ); + return toCart(hydrate); +} +``` + +- **`price.net` on a cart line is the line total**; `variant.price.net` is the unit price. Order lines carry the + unit price. +- **A booked line keeps its booking only if it comes back** with its `lineId`, `meta` and `booking`. Hydrating + without it releases the reservation. See [[bookable-resources]]. +- **An unknown SKU** was seen both failing the whole call and silently dropping the line. Check SKUs against + Discovery in parallel, and check the answer for the line you added. +- **Cart meta becomes order meta**: `createFromCart` copies it. + +## Reading a stored cart + +Re-hydrate when the stored cart could be priced wrong: it is stale, it was built in another language, or for +another customer (a company's price lists only apply to a cart hydrated with that company). + +```ts +export async function getCart( + id: string | undefined, + language: string, + customer?: CartCustomer, + markets: string[] = [], +) { + if (!id) return null; + const { cart } = await shop<{ cart: RawCart | null }>(`query Cart($id: UUID!) { cart(id: $id) { ${FIELDS} } }`, { + id, + }).catch(() => ({ cart: null })); + if (!cart || cart.state !== "cart") return null; // placed or ordered: start a new one + const other = + cart.context.language !== language || (cart.customer?.identifier ?? undefined) !== customer?.identifier; + if (cart.isStale || other) return hydrate(id, toCart(cart).lines.map(lineInput), language, customer, markets); + return toCart(cart); +} +``` + +## The drawer + +- Show the line at once (optimistic), then replace the drawer with the hydrate's answer. The hydrate takes about + 200–400 ms; the optimistic line shows in a few milliseconds. +- Batch rapid quantity changes into one hydrate. +- Quantity is a labelled native control, and steppers are named after the product + ([accessibility.md](accessibility.md)). An agent or a screen reader can then read and set it. + +## Checkout + +The order of calls matters. In a server action: + +1. **Hydrate one last time** with the customer and the final lines (product names in line meta if you want them + on the order). +2. **`setCustomer`**. For B2B, the organisation, with the person who ordered in cart meta. +3. **`setMeta(merge: true)`**: market, segment, PO reference, project. +4. **`place`**. The cart is now locked; charge `place`'s `total`. If order creation fails after this, the + shopper needs a new cart. +5. **Bookings**: `confirmCartBooking(cartId)` before the order, which checks the holds still stand. +6. **Payment**: create the provider session on the server from the placed total ([[payments]]). In the + provider's webhook, verify, then: +7. **`createFromCart(id, { type, paymentStatus, payments, pipelines })`** on `/order`, all in the input, not + chained. No `fulfill` afterwards: `createFromCart` already moves the cart to `ordered`. +8. **Bookings again**: poll `cart { orderId }` until it is set (about 0.5 s), then `confirmCartBooking` again, + which links the reservations to the order. +9. Delete the cart cookie, expire the buyer's cached history (`updateTag`), show the confirmation. + +```ts +await shop(`mutation($id: UUID!, $c: CustomerInput!) { setCustomer(id: $id, input: $c) { id } }`, { id, c: customer }); +await shop(`mutation($id: UUID!, $meta: [KeyValueInput!]!) { setMeta(id: $id, meta: $meta, merge: true) { id } }`, { + id, + meta, +}); +await shop(`mutation($id: UUID!) { place(id: $id) { id } }`, { id }); + +const { createFromCart: order } = await shop<{ createFromCart: { id: string } }>( + `mutation($id: UUID!, $input: OrderFromCartInput!) { createFromCart(id: $id, input: $input) { id } }`, + { + id, + input: { + type: "standard", + paymentStatus: "paid", + payments: [{ provider: "custom", method: "card", amount: cart.gross, transactionId: providerReference }], + pipelines: [{ identifier: pipelineId, stage: stageId }], // ids from PIM pipeline.getMany at build time + }, + }, + "order", +); +``` + +- A guest is `{ isGuest: true, identifier: email, firstName, lastName, email }`; a signed-in buyer is + `{ identifier, isGuest: false, … }`. Put the customer on the cart before any booking. +- `additionalInformation: null` is refused: leave the key out. The error is a bare "Output validation error", + which doesn't name the field. +- Pipeline and stage ids, not names. Read them with PIM `pipeline.getMany` at build time. + +## Quotes and invoice + +A quote is `createFromCart` with `type: "quote"`, no payment, and a quotes pipeline. Accepting it creates the +order with Shop `create` (lines and prices from the quote, `relatedOrderIds: [quoteId]`), then moves the quote's +stage. Invoice checkout is `paymentStatus: "unpaid"` with a custom payment, for signed-in trade buyers, after a +credit check against their open orders. + +## The confirmation page + +- Show the order `createFromCart` returned. `order(id)` can answer "not found" for a moment after creation; retry + if you must read it. +- Booking details come from the order meta snapshot. +- Later visits list `orders(customerIdentifier, limit: 100)` on `/order`. New orders can take seconds to minutes to + appear there, and paging with `limit`/`skip` was inconsistent: read one page, and say on the confirmation page + that history updates shortly. + +## Agents in the checkout + +An AI agent's basket has no cookie: it travels as a `cartId`, and a signed hand-off link lets the shopper's +browser adopt it and finish payment in the store. See [[agentic-commerce]]. diff --git a/use-crystallize/skills/storefront/references/i18n-routing.md b/use-crystallize/skills/storefront/references/i18n-routing.md new file mode 100644 index 0000000..65a9ebf --- /dev/null +++ b/use-crystallize/skills/storefront/references/i18n-routing.md @@ -0,0 +1,124 @@ +# Language and market routing, translated paths, hreflang + +Crystallize translates item paths per language, so `/en/sawing/circular-saw-x` and `/no/sager/sirkelsag-x` are +the same item. A storefront routes on the language in the path, resolves the item by its path in that language, +and finds the same item in other languages by `itemId`. + +## Language (and market) in the path + +Put the language, and the market when it differs from the language, in the first path segment. Do not choose the +market by cookie: crawlers carry no cookies, so they only ever see the default market's prices, and the JSON-LD +then has to say so. + +A proxy (Next.js 16 `proxy.ts`, formerly `middleware.ts`) sends a bare URL to a language: the cookie, then +`Accept-Language`, then the default. Trimmed from a working storefront: + +```ts +import { NextResponse, type NextRequest } from "next/server"; + +const LANGS = ["en", "no", "sv", "nl"]; + +export function proxy(request: NextRequest) { + const { pathname } = request.nextUrl; + if (LANGS.some((l) => pathname === `/${l}` || pathname.startsWith(`/${l}/`))) return NextResponse.next(); + const cookie = request.cookies.get("lang")?.value; + const accepted = (request.headers.get("accept-language") ?? "").toLowerCase(); + const fromHeader = LANGS.find((l) => accepted.startsWith(l) || (l === "no" && /^(nb|nn)/.test(accepted))); + const lang = LANGS.includes(cookie ?? "") ? cookie : (fromHeader ?? "en"); + request.nextUrl.pathname = `/${lang}${pathname === "/" ? "" : pathname}`; + return NextResponse.redirect(request.nextUrl); +} + +// Keep Next internals, API routes and files (robots.txt, sitemap.xml, icons) out of the language redirect. +export const config = { matcher: ["/((?!_next|api|favicon.ico|icon|apple-icon|.*\\..*).*)"] }; +``` + +- Icon routes (`icon`, `apple-icon`), `/.well-known/*`, OAuth and webhook routes stay outside the language proxy. +- The proxy also serves Markdown twins (`.md`, `Accept: text/markdown`); see [[seo-geo]]. +- Map each language to its market in one place: currency, price variant identifier, VAT rate, locale. + +```ts +export const MARKET = { + en: { currency: "EUR", priceVariant: "default", vat: 0.21, locale: "en-IE" }, + no: { currency: "NOK", priceVariant: "nok", vat: 0.25, locale: "nb-NO" }, + sv: { currency: "SEK", priceVariant: "sek", vat: 0.25, locale: "sv-SE" }, +} as const; +``` + +## Tenant language codes vs BCP 47 + +Use BCP 47 for `<html lang>`, hreflang, `og:locale` and schema.org `inLanguage`. A tenant's language code is not +always one: Norwegian content in a tenant language `no` is Bokmål, `nb`. + +```ts +export const HREFLANG = { en: "en", no: "nb", sv: "sv", nl: "nl" }; +export const OG_LOCALE = { en: "en_IE", no: "nb_NO", sv: "sv_SE", nl: "nl_NL" }; +``` + +In Discovery, a tenant language with a hyphen becomes camelCase in the `TenantLanguage` enum (`nb-no` is `nbNo`). + +## The same item in every language + +Paths are translated and can be re-slugged, so never match by slug. One aliased query by `itemId` returns the +item's path in every language: + +```ts +export async function pathsForItem(itemId: string) { + const q = LANGS.map( + (l) => + `${l}: search(language: ${l}, filters: { itemId: { equals: $id } }, pagination: { limit: 1 }) { hits { path } }`, + ).join("\n"); + const data = await discovery<Record<string, { hits: { path: string }[] }>>(`query Paths($id: String!) { ${q} }`, { + id: itemId, + }); + return Object.fromEntries(LANGS.flatMap((l) => (data[l].hits[0] ? [[l, `/${l}${data[l].hits[0].path}`]] : []))); +} + +/** Next.js `alternates`: canonical for this language, hreflang for every language, x-default. */ +export function alternates(paths: Record<string, string>, lang: string) { + return { + canonical: absolute(paths[lang]), + languages: { + ...Object.fromEntries(LANGS.flatMap((l) => (paths[l] ? [[HREFLANG[l], absolute(paths[l])]] : []))), + "x-default": absolute(paths.en ?? paths[lang]), + }, + }; +} +``` + +- A language without the item has no hit: leave it out of hreflang rather than pointing at a 404. +- For a sitemap, one `browse` per language, joined on `itemId` (see [[seo-geo]]). +- Folders map across languages the same way. A folder's topic path is a usable cross-language key when folders + mirror a taxonomy. +- A renamed path goes to the item's path history: 301 old URLs to the current path, and keep them out of the + sitemap. See [[information-architecture]]. + +## The language switcher + +Link each language to its front page (so it works without JavaScript), and on click ask a route for the current +page's path in the target language: + +```ts +// GET /api/language?to=no&path=/en/sawing/x → { href: "/no/sager/x" } +const APP_PAGES = new Set(["", "cart", "account", "search"]); + +export async function GET(req: NextRequest) { + const to = req.nextUrl.searchParams.get("to") ?? ""; + const [pathname, query = ""] = (req.nextUrl.searchParams.get("path") ?? "/").split("?"); + const [, from, ...rest] = pathname.split("/"); + const target = (path: string) => NextResponse.json({ href: `/${to}${path}${query ? `?${query}` : ""}` }); + if (APP_PAGES.has(rest[0] ?? "")) return target(rest.length ? `/${rest.join("/")}` : ""); + const item = await resolveItem(`/${rest.join("/")}`, from); // Discovery: path → itemId + const path = item ? await pathInLanguage(item.itemId, to) : null; // Discovery: itemId → path + return target(path ?? ""); +} +``` + +Facet values that are topic paths are language-independent, so a filtered category keeps its filters across the +switch. Prefetching the target language's page on hover makes the switch feel instant. + +## Content that is missing in a language + +An item exists per language, but its text components may be empty in one. Test for content, not for a hit: a +product with no name or description in a language is a fallback case (show the default language's text, or leave +the item out of that language's listings and sitemap), not a page to render empty. diff --git a/use-crystallize/skills/storefront/references/nextjs-pitfalls.md b/use-crystallize/skills/storefront/references/nextjs-pitfalls.md new file mode 100644 index 0000000..f8c3434 --- /dev/null +++ b/use-crystallize/skills/storefront/references/nextjs-pitfalls.md @@ -0,0 +1,87 @@ +# Next.js 16 pitfalls on a Crystallize storefront + +Most builds behind this skill used Next.js 16 (16.3–16.4) with `cacheComponents: true` on Vercel. These are the +traps they hit, with what worked. They are framework behaviour rather than Crystallize behaviour, so re-check +them on the version you run. + +## Shape of the app + +- **A static shell plus cached Discovery reads; per-shopper parts stream behind `<Suspense>`.** The layout reads + no cookies. A layout that reads cookies makes every route dynamic, and then `staleTimes.dynamic` (for example + 20 s) is needed, or a prefetched payload is thrown away the moment it arrives. +- **A page that depends on `params` sits behind `<Suspense>`**, so the route's shell (layout and skeleton) is shared + by every link to it. Next 16.4 with partial prefetching errors on `await params` outside a boundary. +- **Make the fallback real content where you can.** While a category's filters and personal ranking stream, the + fallback is the same category in its default order (cached), not a skeleton. +- **Every internal link is a `next/link`**, prefetched on intent ([performance.md](performance.md)). Test + prefetching in a production build in a visible browser: `next dev` doesn't prefetch, and a hidden or background + tab prefetches nothing and doesn't reveal streamed Suspense content (it waits for `requestAnimationFrame`). + +## Request data and the prerender + +- **`await connection()` before Core or Shop API reads and before `new Date()`** in a request-time render. An + uncached `fetch` does not mark the render dynamic by itself, and `new Date()` after it errors as an "unstable + value during prerendering". +- **A read inside `'use cache'` must not call `connection()`.** Keep two entry points to the Shop API client: one + that marks the render dynamic (carts) and a plain request for cached per-customer reads (order history). +- **Client components calling `usePathname()` in a layout** need a `<Suspense>` with a static fallback, or + `next build` fails prerendering. +- **`'use server'` files may export only async functions.** Keep cookie names and constants in another module. + +## Cache keys + +- **Arguments to a cached function must be identical on every render.** Next renders a prerender twice (warm-up, + then final). Build objects and arrays in a fixed order (sort SKU lists, sort keys); an order that depends on an + API response misses the cache the second time ("Unexpected cache miss after cache warming phase") and the + prefetch answers 503. +- **Keep the clock out of keys.** Day-bucket anything time-based. +- **Cached functions never throw.** A failed read during warming leaves no entry and becomes a miss; one build + returns `{ error }` with `cacheLife('seconds')` instead. The same warning was still seen in Vercel logs with + deterministic arguments and was benign (the part became a dynamic hole). +- **Large cached reads bloat `.meta`.** A 2.5 MB index read directly during prerender made each page's `.meta` + 526 KB (240 MB of the build). Reading it through a small keyed cache function brought it to 55 KB per page. + +## 404s and redirects under a PPR shell + +- **`notFound()` or `permanentRedirect()` inside `<Suspense>` streams HTTP 200**: the status is sent with the + shell. The page still renders "not found" and carries `noindex`, so it doesn't get indexed, but crawlers and + monitoring see a 200. +- What was tried: resolving the lookup in a cached function outside Suspense with `export const instant = false` + worked in one round and not in a later one (still open). The pattern that worked: the proxy checks a cached index + of valid paths and rewrites misses to a static route that calls `notFound()`. +- `dynamicParams` isn't available with Cache Components. + +## Metadata for crawlers + +A dynamic `generateMetadata` streams into `<body>`. With a cached shell on a CDN, Googlebot got pages with no +`<title>`, canonical or hreflang at all. Give every sitemap path its own prerendered shell +(`generateStaticParams`) and keep `generateMetadata` free of request APIs. Full write-up in +[performance.md](performance.md#pitfall-metadata-must-be-in-the-cached-shells-head); crawler side in +[[seo-geo]]. + +Bots in `htmlLimitedBots` that reached catch-all pages unknown at build hit "Expected the resume to render +<div>…" on Vercel. The same fix applies: `generateStaticParams` for every path. + +## Loading states + +- **`loading.tsx` on the segment that changes** replaces the visible page and hides optimistic UI. Moving it one + level up kept sibling navigation instant in one build (a colour switch went from 813 ms to 26 ms). +- **Don't remove `<Suspense>` wrappers because streamed content "never appears"** in an automated browser: that is + the hidden-tab behaviour above, not a bug. + +## Prefetching + +- With Cache Components, the default `<Link>` prefetch of a 16-card grid cost 136 KB on arrival. Intent prefetch + outside the first row brought it to 37 KB. +- `partialPrefetching` (Next 16.3) gave intermittent 503s on shell-route prefetches in one build, and worked in + others. Test it with your routes before relying on it. + +## Deploying on Vercel + +- **Set the function region** (`"regions": ["fra1"]` in `vercel.json`, and on the project) next to the tenant. +- **`vercel env add --force` does not overwrite sensitive variables**, and their values can't be read back. One + site ran on fixtures without anyone noticing. Use `rm` then `add`, and expose a no-secrets status route (mode, + tenant, a live probe). +- **`next start` locally differs from Vercel**: it doesn't send the font `Link: rel=preload` header Vercel sends, + and it upgraded the App Shell after the first visit while production didn't. Compare local with local, and test + crawler behaviour on the deployment. diff --git a/use-crystallize/skills/storefront/references/performance.md b/use-crystallize/skills/storefront/references/performance.md new file mode 100644 index 0000000..0fe2995 --- /dev/null +++ b/use-crystallize/skills/storefront/references/performance.md @@ -0,0 +1,133 @@ +# Performance + +What made Crystallize storefronts fast or slow in practice, plus the gaps a Modern Web Guidance (MWG v1.0) +audit found on a live store. Images are covered by [[responsive-images]]; read it rather than repeating it here. + +## Run next to the API + +Put server functions in the region nearest the tenant's API and media (`fra1` on Vercel for EU tenants): + +```json +{ "regions": ["fra1"] } +``` + +Every page makes several Discovery reads; a transatlantic hop on each one adds up to hundreds of milliseconds. + +## Prefetch on intent, not on view + +A framework link that prefetches every card in view renders every linked page on the server. On a category page +with a mega menu, that was most of one demo's hosting bill. Prefetch on hover, focus or touch: + +```tsx +"use client"; +import Link from "next/link"; +import { useState, type ComponentProps } from "react"; + +export function IntentLink(props: Omit<ComponentProps<typeof Link>, "prefetch">) { + const [intent, setIntent] = useState(false); + const show = () => setIntent(true); + return <Link {...props} prefetch={intent} onMouseEnter={show} onTouchStart={show} onFocus={show} />; +} +``` + +Only the hovered link counts: opening a menu must not count as intent for all its links. Speculation rules do +not apply to an App Router site, which navigates client-side. + +## Prerender, or render on demand + +Prerendering every product page puts the whole catalogue through Discovery during the build. One build got +HTTP 200 with `errors: [{ message: "Response Error" }]` after about 900 pages. Options: + +- Prerender what the sitemap lists, with capped concurrency and a retry on "Response Error". +- Render on demand and cache, for very large catalogues. + +Either way, every URL served must have its own metadata in `<head>` (below). + +## The LCP image + +- **Get the LCP resource into the early HTML.** On one store, product and category pages had the LCP image's + `<link rel="preload">` at byte 282,186 of the HTML, after a 60 KB header and mega menu. Stream above-the-fold + content first, and keep the hero out of a late Suspense boundary. Putting the LCP image in the PPR shell was the + biggest listing LCP win in another build. +- **Preconnect to the media host, without `crossOrigin`**: `<img>` requests are no-cors and won't reuse a CORS + connection. In React: `preconnect('https://media.crystallize.com')` from `react-dom` in the root layout. +- **At most one or two `fetchpriority="high"`** images and preloads per page. One home page had 5 image preloads + and 9 high-priority images. +- **Hidden mega-menu images get `fetchpriority="low"`**, or are not rendered until the menu opens. One store + rendered about 62 menu images into every page's HTML. +- Discovery has no dominant colour or blur hash; generate placeholders at import if you need them. + +## Payload + +- Ask Discovery only for the image widths a slot uses (`variants(types: "webp", minWidth, maxWidth)`). Cards up to + about 1024 px, gallery 1920, chat cards 500. One build cut a listing read from 345 KB to 108 KB by selecting + widths only. Repeated `variants { images }` on a product with 260 sizes made 24 cards 8.2 MB and broke the + cache. +- Skip `facets` on rails and menus. +- Large cached reads bloat the RSC payload of every page that uses them. +- `content-visibility: auto` on long below-the-fold sections. + +## Fonts + +Self-host with `next/font` (`display: swap`, size-adjust fallbacks); preload only the one or two faces used above +the fold. + +## Field data + +Measure in the field: `web-vitals` (attribution build) beaconed to your own route. Without it, INP, LCP and CLS +from real shoppers are unknown. + +## Pitfall: metadata must be in the cached shell's `<head>` + +Found in the MWG audit and confirmed on a live store. + +- With Next.js Cache Components and PPR, a dynamic `generateMetadata` is **streamed into `<body>`** instead of the + static shell's `<head>`. +- On Vercel, real Googlebot user agents were served the cached shell (`x-vercel-cache: HIT`) with **no `<title>`, + description, canonical or hreflang** on product and category pages. bingbot and AI crawlers got `BYPASS` and a + full `<head>`. Browsers got the title about 300 KB into the HTML. Google ignores canonical and hreflang outside + `<head>`. +- `htmlLimitedBots` doesn't help when the cached shell wins. +- A catch-all route without `generateStaticParams` serves one App Shell for every URL, and that shell can't hold + metadata that depends on the path. + +**The rule: keep metadata cacheable.** + +- Build `generateMetadata` only from cached Discovery reads, with no request-time APIs (`cookies()`, + `headers()`, `searchParams`), so it lands in the shell's `<head>` for every user agent. +- Give every sitemap path its own prerendered shell with `generateStaticParams`. Items published after the build + get the App Shell on their first visit and are prerendered then. +- A search page's metadata must not read `searchParams`: make it static (the page is `noindex` anyway). + +```tsx +// app/[lang]/[...path]/page.tsx +export async function generateStaticParams({ params }: { params: { lang: string } }) { + return (await catalogPaths(params.lang)).map((p) => ({ path: p.split("/").filter(Boolean) })); +} + +export async function generateMetadata({ params }: PageProps<"/[lang]/[...path]">): Promise<Metadata> { + const { lang, path } = await params; // params only: no cookies, headers or searchParams + return itemMetadata("/" + path.map(decodeURIComponent).join("/"), lang); // cached Discovery reads +} +``` + +**Verify with the real Googlebot strings**, desktop and smartphone, not a shortened UA, and look at +`x-vercel-cache` and where `<title>` sits. A local `next start` upgraded the App Shell after the first visit while +production did not, so test the deployment: + +```bash +UA='Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Chrome/138.0.0.0 Safari/537.36' +curl -sI -A "$UA" https://shop.example/en/some/product | grep -i x-vercel-cache +curl -s -A "$UA" https://shop.example/en/some/product | head -c 4000 | grep -o '<title>[^<]*\|rel="canonical"[^>]*\|hreflang="[^"]*"' +``` + +Repeat with the smartphone Googlebot UA, bingbot and an AI crawler. The same rule, from the crawler's side, is in +[[seo-geo]]. + +## Low-priority items from the audit + +- Declare `color-scheme` (`` for a light-only design) and + `theme-color`. +- A web app manifest (`app/manifest.ts`). +- `Cache-Control: public, max-age=0, must-revalidate` rather than `no-store`, so nothing blocks the back/forward + cache. diff --git a/use-crystallize/skills/storefront/references/preview.md b/use-crystallize/skills/storefront/references/preview.md new file mode 100644 index 0000000..b0ff7ef --- /dev/null +++ b/use-crystallize/skills/storefront/references/preview.md @@ -0,0 +1,245 @@ +# Frontend preview with custom views + +Editors preview a draft inside the Crystallize App: a **custom view** frames your storefront next to the item +they are editing. The App supplies the frame, the device toolbar and the reload; the storefront supplies one route +that turns preview mode on, and pages that read drafts in that mode. From a working Next.js 16 storefront +(tools-universe, Cache Components, verified with a production build on 2026-11-12). Read the App side in the docs: +[Custom views](https://crystallize.com/docs/pim/catalogue/custom-views). + +## 1. The custom view (in the App) + +Settings → Custom views → **Add custom view**: a name and a URL template. The App fills these placeholders for +the item that is open: + +| Placeholder | Value | +| --------------------------- | ----------------------------------------------------------------------- | +| `{{language}}` | The language the editor is working in (`en`, `no`, …) | +| `{{itemId}}` | The item id: stable across languages and renames. Prefer it | +| `{{itemPath}}` | The Crystallize path: no language prefix, translated per language | +| `{{itemExternalReference}}` | The external reference, if you route by it | +| `{{variantSku}}` | The selected variant's SKU, if the product page selects variants by URL | + +```text +https://shop.example.com/api/preview?secret=…&language={{language}}&itemId={{itemId}}&path={{itemPath}} +``` + +- **Always turn on "Show responsive device toolbar in preview".** The editor then switches between mobile and + desktop widths in the App's toolbar. +- **The storefront adds no preview chrome.** No device buttons, no frame, no banner: it only has to be responsive, + which it already is. The App draws the toolbar and the reload button. +- The secret ends up in the tenant's settings, readable by anyone who can open them. Use a value only for preview. + +**By API:** custom views are tenant preferences. The legacy PIM API has +`tenant { setPreferences(tenantId, input: { frontends: [{ name, url }] }) }`; Core only reads them +(`tenant { preferences { frontends { name url responsive authentication { key } } } }`). The input has no +`responsive`, so the device toolbar is switched on in the App, and `setPreferences` replaces the whole list: read +`frontends` first and send every existing view back, knowing their `responsive` and `authentication` can't be +carried and will be reset. Adding a view in the App is safer. + +## 2. The preview route + +One `GET` route: check the secret, resolve the item's storefront URL **from its draft** in the requested +language, turn on preview mode, redirect. In Next.js: + +```ts +// app/api/preview/route.ts +import { cookies, draftMode } from "next/headers"; +import { redirect } from "next/navigation"; +import { createHash, timingSafeEqual } from "node:crypto"; + +const same = (a: string, b: string) => + timingSafeEqual(createHash("sha256").update(a).digest(), createHash("sha256").update(b).digest()); + +export async function GET(request: Request) { + const params = new URL(request.url).searchParams; + const secret = params.get("secret"); + if (!process.env.PREVIEW_SECRET || !secret || !same(secret, process.env.PREVIEW_SECRET)) + return new Response("Invalid preview secret", { status: 401 }); + + // Redirect only to a path Discovery returned, never to a parameter (no open redirect). + const target = await previewTarget(params.get("language"), params.get("itemId"), params.get("path")); + if (!target) return new Response("No storefront page for this item in this language", { status: 404 }); + + (await draftMode()).enable(); + // Partitioned (CHIPS): kept by browsers that block third-party cookies, and scoped to the App's site. + if (process.env.NODE_ENV !== "development") { + const jar = await cookies(); + const value = jar.get("__prerender_bypass")?.value; + if (value) + jar.set({ + name: "__prerender_bypass", + value, + httpOnly: true, + secure: true, + sameSite: "none", + partitioned: true, + path: "/", + }); + } + redirect(target); +} +``` + +Resolve by item id, per language. The Crystallize path has no language prefix and is translated, so the +storefront URL is `/{lang}` plus the path **in that language**, and the item may map to a special route (the home +landing page to `/{lang}`): + +```ts +async function previewTarget(language: string | null, itemId: string | null, path: string | null) { + const lang = isLang(language) ? language : "en"; + const id = itemId ?? (path ? await itemIdForPath(path, lang) : null); // a path alone: try every language + if (!id) return null; + const data = await discovery<{ search: { hits: { path: string; externalReference?: string }[] } }>( + `query PreviewTarget($id: String!) { + search(language: ${lang}, filters: { itemId: { equals: $id } }, pagination: { limit: 1 }) { + hits { path externalReference } + } + }`, + { id }, + { draft: true }, + ); + const hit = data.search.hits[0]; + if (!hit) return null; + return hit.externalReference === "page:home" ? `/${lang}` : `/${lang}${hit.path}`; +} +``` + +Resolve from the draft: a renamed or not-yet-published item has its new path only there. Look a bare path up in +every language: `{{itemPath}}` may be in another language than `{{language}}`. + +Add an exit route (`/api/preview/exit`, `POST` for forms; with a `GET` link, `prefetch={false}`) that calls +`draftMode().disable()` and also deletes the partitioned cookie with `Partitioned`; a partitioned cookie is only +deleted by a `Set-Cookie` that carries the attribute. Next keeps one `Set-Cookie` per name, so set the partitioned +deletion only where the partitioned cookie was set (production). + +Other frameworks: the same route sets your own signed, `httpOnly` preview cookie with the attributes in section 5, +and your loaders branch on it. + +## 3. Draft reads through Discovery + +In preview mode, every Discovery read asks for drafts: add `publicationState: draft` next to `language`. Every +Discovery field that takes `language` also takes it: `search`, `autocomplete`, every `browse` field, and the +nested relation fields `items(language:)` and `variants(language:)`. One rewrite covers a whole query: + +```ts +export const draftQuery = (query: string) => + query.replace(/\((\s*language:\s*[^,)\s]+)(?![^)]*publicationState)/g, "($1, publicationState: draft"); +``` + +With Next.js Cache Components, put the switch **inside** the cached client. `draftMode().isEnabled` is readable +in `'use cache'` (and `'use cache: remote'`); it is false while prerendering and for every request without the +cookie, so normal traffic stays cached and prerendered. With the cookie, Next re-runs every cached function on +each request and saves nothing: + +```ts +async function cached(query: string, variables: Record): Promise { + "use cache: remote"; + if ((await draftMode()).isEnabled) return request(draftQuery(query), variables); // not saved + cacheLife("hours"); + cacheTag("discovery"); + return request(query, variables); +} +``` + +Then the storefront's own pages are the preview: same routes, same views, no `/preview` copy to keep in step. + +**Drafts are public on an open Discovery.** `publicationState: draft` needs no credentials there (verified on two +tenants). The secret protects the preview **mode**: uncached rendering, `noindex`, framing by the App. It does +not protect the data. To keep drafts private, restrict Discovery, re-ignite +(`igniteDiscoApi`; the setting reaches Discovery only after that, and a few minutes later), and send the static +token from the server. + +## 4. Live reload + +The custom-views doc asks preview pages to load the App's listener. Load it in preview mode only: + +```tsx +async function PreviewListener() { + const { isEnabled } = await draftMode(); + return isEnabled ?