From 6d12a6165a8e2a870d9435aa9446a2f9882ecddc Mon Sep 17 00:00:00 2001 From: papelipe Date: Thu, 12 Nov 2026 11:30:27 +0100 Subject: [PATCH 01/35] fix(skills): query opens with the storefront API contract Discovery for every catalogue read, the Shop API for everything about a shopper, Catalogue only for per-customer price display, Core never in the request path. Token and scope tables per API, variantGroups and variant(selected:) in SKILL.md, generated field names, unset booleans reading false, paths per language for hreflang and sitemaps, draft preview through Discovery (and that drafts are public on an open Discovery), and a new discovery-indexing reference on ignite, propagation and consistency. Co-Authored-By: Claude Opus 5.5 --- use-crystallize/skills/query/SKILL.md | 486 +++++++++++------- .../skills/query/references/catalogue-api.md | 43 +- .../skills/query/references/core-api.md | 9 +- .../skills/query/references/discovery-api.md | 270 +++++++++- .../query/references/discovery-indexing.md | 120 +++++ .../references/shop-api-order-queries.md | 40 +- .../query/references/shop-api-queries.md | 52 +- 7 files changed, 782 insertions(+), 238 deletions(-) create mode 100644 use-crystallize/skills/query/references/discovery-indexing.md diff --git a/use-crystallize/skills/query/SKILL.md b/use-crystallize/skills/query/SKILL.md index 84d7279..0594d2f 100644 --- a/use-crystallize/skills/query/SKILL.md +++ b/use-crystallize/skills/query/SKILL.md @@ -1,238 +1,277 @@ --- 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 (fallback for per-customer price display only) 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: a fallback for one named task**, per-customer price lists for display + (`priceFor(customerIdentifiers:)`). 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 that is **not tenant-scoped** | **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 (Wee). 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 and send `X-Crystallize-Static-Auth-Token`, from the server only. Whether +> a restricted Discovery also accepts the access token pair is unverified. -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 +281,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 the one task that Discovery and the Shop API can't do: showing a **specific customer's** price-list price +on a page, server-side, cached per organisation. + +```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 price display, 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..4849628 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 @@ -23,13 +25,22 @@ A restricted Catalogue API takes the `X-Crystallize-Static-Auth-Token` header, o ## 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 (Høiax, Screen Universe, WoolLand) `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 +56,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 +202,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 +228,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..f1575a0 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 diff --git a/use-crystallize/skills/query/references/discovery-api.md b/use-crystallize/skills/query/references/discovery-api.md index ea07604..45872d0 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,21 @@ 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, which is separate from the Catalogue entry. -``` -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 | -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. +The static token is the one credential Discovery is known to read. Whether a restricted Discovery also accepts the +access token pair is unverified, and a bearer token is ignored. -> **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 +56,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 +204,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 +213,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 +234,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 +430,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 +443,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 +(Felleskjøpet; 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 +485,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 Høiax, 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 +522,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 +577,113 @@ 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 (Oslo VVS). 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 and send +> `X-Crystallize-Static-Auth-Token` from the server only. Whether a restricted Discovery accepts the access token +> pair instead is unverified. + +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 +726,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..1391860 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 + (Felleskjøpet). Two hours after an import, `limit: 100` returned 6 of 8 and 4 of 5 orders for two customers + (WoolLand). +- `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..d831802 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,23 @@ 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": "..." }`. +`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": "..." }`. + +- **Mint it with an access token that is not tenant-scoped.** The token endpoint checks who you are on `/@me`, which + refuses a tenant-scoped access token and a plugin bearer token ([[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 +132,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. (WoolLand.) + ### List Carts `carts` lists carts and wishlists. Like `orders`, it answers for whatever `customerIdentifier` it is given, so @@ -175,7 +212,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 From b14ae21e4ac147fac84d07b71c11ebb7b07d9c82 Mon Sep 17 00:00:00 2001 From: papelipe Date: Thu, 12 Nov 2026 11:30:27 +0100 Subject: [PATCH 02/35] fix(skills): mutation follows the write side of the contract Shopper writes go through the Shop API from the server, Core is for the back office, PIM for setup. Which store an order goes to and which call creates it (createFromCart, Shop create, registerOrder only for imports), B2B orders on behalf of a company, a server-only checkout flow, webhooks for revalidation, the unit-bound numerics rule, and partial-write traps. Media moves to its own skill. Co-Authored-By: Claude Opus 5.5 --- use-crystallize/skills/mutation/SKILL.md | 307 +++++++++++------- .../skills/mutation/references/core-api.md | 206 ++++++++++-- .../skills/mutation/references/media.md | 228 +------------ .../mutation/references/shop-api-mutations.md | 6 +- .../references/shop-api-order-mutations.md | 18 +- 5 files changed, 380 insertions(+), 385 deletions(-) diff --git a/use-crystallize/skills/mutation/SKILL.md b/use-crystallize/skills/mutation/SKILL.md index 8ecaa43..00636be 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 with a pair that + is **not tenant-scoped**. +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,135 @@ 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 the same orders in two stores, synced asynchronously. 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**: three `updateOrder` calls left three Shop + orders with one `coreId`, and a storefront summing the list counted the money three times. 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: 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 +227,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 +245,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 +263,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..df0fbdb 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** for that 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 (Felleskjøpet) 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 }` 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..c3f99b3 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 WoolLand, ignored ("now") on Wee. 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 From 19e4baf47f3933961d6cb037903fc233219fcba5 Mon Sep 17 00:00:00 2001 From: papelipe Date: Thu, 12 Nov 2026 11:30:27 +0100 Subject: [PATCH 03/35] feat(skills): media, split out of mutation Getting images and video in reliably: choosing the way in, copyRemoteAsset limits (timeout, URL length, Content-Length, bot protection), a seven-step import pipeline with verification, presigned uploads, metadata per language, replacing and deleting, showcases, and a failure-mode table. Co-Authored-By: Claude Opus 5.5 --- use-crystallize/skills/media/SKILL.md | 183 +++++++++++++++ .../skills/media/references/import.md | 218 ++++++++++++++++++ .../skills/media/references/showcases.md | 93 ++++++++ .../skills/media/references/video.md | 71 ++++++ 4 files changed, 565 insertions(+) create mode 100644 use-crystallize/skills/media/SKILL.md create mode 100644 use-crystallize/skills/media/references/import.md create mode 100644 use-crystallize/skills/media/references/showcases.md create mode 100644 use-crystallize/skills/media/references/video.md 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..d3ba24f --- /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=/korsbakken-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..2a08dbb --- /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. (Armaturjonsson, +Fashion Universe, WoolLand, Wee and YIT, 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. From cb65c1addaf30610f2ef65e337d91b530e01e06e Mon Sep 17 00:00:00 2001 From: papelipe Date: Thu, 12 Nov 2026 11:30:27 +0100 Subject: [PATCH 04/35] fix(skills): js-api-client starts from discoveryApi The quick start uses discoveryApi; catalogueApi and the Catalogue-based helpers are the fallback. Shop callers are server only, token defaults are stated, "Shop or Core?" matches the order rules, and the raw calls for subscription contracts and booking admin are documented where no helper exists. Co-Authored-By: Claude Opus 5.5 --- use-crystallize/skills/js-api-client/SKILL.md | 98 ++++++++++++++----- 1 file changed, 71 insertions(+), 27 deletions(-) diff --git a/use-crystallize/skills/js-api-client/SKILL.md b/use-crystallize/skills/js-api-client/SKILL.md index 86bb4e8..7affa25 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 price display; 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,28 @@ 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 fallback for one task, a specific customer's price-list prices for display (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 +81,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 +108,8 @@ All callers share the same signature: | Caller | Purpose | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `catalogueApi` | Catalogue GraphQL | -| `discoveryApi` | Discovery GraphQL (search/browse) | +| `catalogueApi` | Catalogue GraphQL: fallback for per-customer price display | +| `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 | @@ -157,6 +164,20 @@ who you are on `/@me`, which refuses a tenant-scoped access token. A bearer-only access token pair (it is sent instead of the pair) and a tenant-scoped pair all fail with `Could not fetch shop api token: …`. +**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 +226,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 +258,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 +299,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 +327,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 +335,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`. From c519294cd33c50374e0bac67bafd6fe3038607f5 Mon Sep 17 00:00:00 2001 From: papelipe Date: Thu, 12 Nov 2026 11:30:27 +0100 Subject: [PATCH 05/35] feat(skills): storefront, building a frontend on Discovery and the Shop API The umbrella skill: the API contract once, credentials and what may run in the browser, a task-to-API decision table, the request path per page type (listing with variantGroups, product page with variant(selected:), search, cart, checkout), caching and the publish webhook, translated paths, B2B prices against a public Discovery, draft preview, and references for performance, accessibility, security headers, i18n routing, cart and checkout, and Next.js pitfalls. Points at superfast.shop for reference implementations. Co-Authored-By: Claude Opus 5.5 --- use-crystallize/skills/storefront/SKILL.md | 426 ++++++++++++++++++ .../storefront/references/accessibility.md | 83 ++++ .../storefront/references/api-contract.md | 83 ++++ .../references/caching-and-revalidation.md | 136 ++++++ .../storefront/references/cart-checkout.md | 184 ++++++++ .../storefront/references/i18n-routing.md | 124 +++++ .../storefront/references/nextjs-pitfalls.md | 87 ++++ .../storefront/references/performance.md | 133 ++++++ .../storefront/references/security-headers.md | 136 ++++++ 9 files changed, 1392 insertions(+) create mode 100644 use-crystallize/skills/storefront/SKILL.md create mode 100644 use-crystallize/skills/storefront/references/accessibility.md create mode 100644 use-crystallize/skills/storefront/references/api-contract.md create mode 100644 use-crystallize/skills/storefront/references/caching-and-revalidation.md create mode 100644 use-crystallize/skills/storefront/references/cart-checkout.md create mode 100644 use-crystallize/skills/storefront/references/i18n-routing.md create mode 100644 use-crystallize/skills/storefront/references/nextjs-pitfalls.md create mode 100644 use-crystallize/skills/storefront/references/performance.md create mode 100644 use-crystallize/skills/storefront/references/security-headers.md diff --git a/use-crystallize/skills/storefront/SKILL.md b/use-crystallize/skills/storefront/SKILL.md new file mode 100644 index 0000000..2c473ea --- /dev/null +++ b/use-crystallize/skills/storefront/SKILL.md @@ -0,0 +1,426 @@ +--- +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, 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", "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: a fallback for one named task.** Per-customer price lists for display + (`priceFor(customerIdentifiers)`), server-side. 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 that is **not tenant-scoped** | **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 why a + tenant-scoped token can't mint 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 unscoped access token pair for the Shop API, server-side only. +- [ ] Languages, price variants, markets, VAT types and stock locations exist, and you know their identifiers + (they become Discovery field names: `nokPrice`, `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( + query: string, + variables: Record = {}, + opts: { draft?: boolean } = {}, +) { + // Draft reads (editor preview) are never cached. + return opts.draft ? request(query, variables) : cached(query, variables); +} + +async function cached(query: string, variables: Record): Promise { + "use cache: remote"; + cacheLife("hours"); + cacheTag("discovery"); // the publish webhook clears this tag + return request(query, variables); +} + +async function request(query: string, variables: Record): Promise { + const headers: Record = { "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(query: string, variables = {}, endpoint: "cart" | "order" = "cart"): Promise { + 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 `` 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 `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.(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. +- ``, 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.** + +| Need | Where | +| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| List, sale, "from" price | Discovery `Price`, `variantGroups.summary.price` | +| Public market price | Discovery `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. +- 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. + +```ts +// Add publicationState: draft to every search/browse that takes `language: $language`. +export const withState = (query: string, draft?: boolean) => + draft ? query.replace(/\((language: \$language)/g, "($1, publicationState: draft") : query; + +const data = await discovery( + withState( + `query Resolve($language: [TenantLanguage!], $path: String!) { + search(language: $language, filters: { path: { equals: $path } }) { hits { itemId shape } } + }`, + draft, + ), + { language, path }, + { draft }, +); +``` + +- Serve preview on its own route (`/preview/[...path]?language=…`), `noindex`, outside the storefront's layout, + rendering the same views from draft data. Register it as the tenant's frontend preview URL. +- The App posts `{ crystallize: { reloadDueToStaleItem: true } }` when the editor saves: call + `router.refresh()` and answer `{ frontendPreview: { reloading: true } }`. Once mounted, post + `{ frontendPreview: { loaded: true } }` to the parent. +- **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). Don't + keep confidential or embargoed content in drafts on an open tenant. If drafts must stay private, restrict + Discovery and send the static token from the server. +- **Never render drafts to crawlers or the public.** The preview route is `noindex`, not linked from the store, + not in the sitemap, and the storefront's own pages never pass `draft`. + +## 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 | Restrict Discovery and 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 `` 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/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..aa7f6d3 --- /dev/null +++ b/use-crystallize/skills/storefront/references/api-contract.md @@ -0,0 +1,83 @@ +# 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 whose token is **not tenant-scoped** ([[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. 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..1b6d7c7 --- /dev/null +++ b/use-crystallize/skills/storefront/references/caching-and-revalidation.md @@ -0,0 +1,136 @@ +# 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. +- **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..9cdb8b8 --- /dev/null +++ b/use-crystallize/skills/storefront/references/cart-checkout.md @@ -0,0 +1,184 @@ +# 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 + }, + }, + }, + }, + ); + 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. +- 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/security-headers.md b/use-crystallize/skills/storefront/references/security-headers.md new file mode 100644 index 0000000..20c4b6f --- /dev/null +++ b/use-crystallize/skills/storefront/references/security-headers.md @@ -0,0 +1,136 @@ +# Security headers + +A live Crystallize storefront audited against Modern Web Guidance v1.0 sent only `strict-transport-security`. No +Content Security Policy, no `nosniff`, no Referrer-Policy, no framing protection. This matters more once a store +has agent tools: WebMCP tools act with the shopper's session, so an XSS becomes an agent acting as the shopper. + +## Companion headers: always + +Cheap, and they break nothing on a typical storefront. From a working `next.config.ts`: + +```ts +const nextConfig: NextConfig = { + async headers() { + return [ + { + source: "/:path*", + headers: [ + { key: "X-Content-Type-Options", value: "nosniff" }, + { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }, + { + key: "Permissions-Policy", + value: "camera=(), microphone=(), geolocation=(), payment=(), usb=(), browsing-topics=()", + }, + { key: "X-Frame-Options", value: "SAMEORIGIN" }, + { key: "Content-Security-Policy", value: "frame-ancestors 'self'" }, + ], + }, + // Not 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, which COOP: same-origin would cut. + { + source: "/:path((?!oauth(?:/|$)|(?:en|no|sv|nl)/oauth(?:/|$)).*)", + headers: [{ key: "Cross-Origin-Opener-Policy", value: "same-origin" }], + }, + ]; + }, +}; +``` + +- `Permissions-Policy: payment=()` blocks the Payment Request API. Leave `payment` out if a provider's button uses + it in your page. +- If a payment provider opens a popup and reads `window.opener`, exclude its return route from COOP the same way + as the OAuth pages, or use `same-origin-allow-popups`. +- `Strict-Transport-Security` usually comes from the host; check it is there. + +## Routes embedded in Crystallize + +A preview route, a custom view or a legacy App shown inside the Crystallize App must allow it as a frame +ancestor, and only on those routes (from two builds with embedded views): + +```ts +async headers() { + const csp = { key: "Content-Security-Policy", value: "frame-ancestors 'self' https://app.crystallize.com https://*.crystallize.com" }; + return [ + { source: "/app", headers: [csp] }, + { source: "/app/:path*", headers: [csp] }, + ]; +} +``` + +Keep these routes out of the site-wide `frame-ancestors 'self'` and `X-Frame-Options` rule, or the stricter one +wins. Add `http://localhost:*` in development if you embed a local server. + +## Content Security Policy + +None of the builds enforces a script CSP yet. The audit's recommendation: + +- Start with `Content-Security-Policy-Report-Only` and move to enforcing once the reports are clean. +- `script-src` with a nonce or hashes and `'strict-dynamic'`; `object-src 'none'`; `base-uri 'none'`; + `require-trusted-types-for 'script'`. +- `img-src` names the Crystallize media host (or your custom media domain). Discovery and the Shop API are called + from the server, so `connect-src` does not need them. +- **A per-request nonce conflicts with a static PPR shell.** A nonce forces dynamic rendering, and hashes don't + fit streamed inline scripts. With Cache Components, either accept dynamic HTML, or ship the parts of CSP that + need no nonce (`object-src`, `base-uri`, `frame-ancestors`, `img-src`) and decide the script policy + explicitly. +- JSON-LD in `