Skip to content

feat(skills): storefront API contract, revised skills from 17 builds, and storefront, seo-geo, agentic-commerce and media skills - #35

Merged
didrikhegna merged 35 commits into
mainfrom
feat/skills-storefront-api-contract
Nov 17, 2026
Merged

didrikhegna merged 35 commits into
mainfrom
feat/skills-storefront-api-contract

Conversation

@papelipe

Copy link
Copy Markdown
Member
Q A
Branch? main
Bug fix? yes
New feature? yes
BC breaks? no (no skill renamed or removed)
Fixed tickets

Revises the skills from the findings of 17 Crystallize builds, and adds four skills for building storefronts. Each skill has its own commit, as in #32, so the PR reads best commit by commit.

Why

Developers and agents need to know which API does what in a storefront. The skills either didn't say, or said it in ways that contradicted each other. Across the builds, the same mistakes kept coming back:

  • Catalogue used as a peer of Discovery.
  • Orders written to the wrong store.
  • Contract prices exposed through an open Discovery.
  • Preview and hreflang done through Catalogue.
  • No guidance at all on SEO, answer engines or agent shopping.

The source is a proposal built from every build's skill-findings.md. It cross-checks the findings and the existing skills, and lists 15 contradictions between skills (C1–C15), which this PR resolves.

The storefront API contract (now stated in query, mutation and storefront)

  • Discovery API: every catalogue read: paths, browse, search, facets, variantGroups / variant(selected:), paths per language for hreflang, list and market prices, stock, ranking, and draft preview (publicationState: draft).
  • Shop API: everything about a shopper: cart and price context, checkout, orders from the cart, payments, customers, bookings, subscriptions. Calls are made from the server only.
  • Catalogue API: only as a fallback, for displaying a specific customer's price.
  • Core API: setup, imports and back office. Never in the storefront's request path.

Verified on live tenants (2026-11-12, reads only)

  • An open Discovery serves drafts to anyone. publicationState: draft returned 541 hits on tools-universe with and without credentials, so confidential or embargoed content must not sit in drafts on an open tenant.
  • Contract price lists are readable through an open Discovery. …PriceFor(marketIdentifiers) returned a contract list without a token.
  • /booking/admin needs both booking and booking:admin. booking:admin alone is refused.
  • hreflang works as one aliased Discovery query per language by itemId.
  • Unset booleans read false.
  • Sort keys apply in schema order.
  • Shop CORS refuses foreign origins.

What changed

Skill Change
query Opens with the contract; tokens and scopes per API; variantGroups in SKILL.md; generated field names; booleans read false; hreflang and sitemaps from Discovery; draft preview; new discovery-indexing reference
mutation The write side of the contract; which store an order goes to and which call creates it (C1); B2B orders; server-only checkout; webhooks; media moved out
media (new) Split from mutation: import pipeline with verification, copyRemoteAsset limits, presigned uploads, video, showcases, failure modes
js-api-client Starts from discoveryApi; Catalogue helpers as fallback; Shop callers server only; raw calls where no helper exists
storefront (new) Building a frontend on Discovery and the Shop API: contract, request path per page type, caching and revalidation, i18n, cart and checkout, B2B prices, performance, accessibility, security headers, Next.js pitfalls; links to superfast.shop reference stores
seo-geo (new) JSON-LD from typed data (UN/CEFACT units, CategoryCode, ProductGroup, offers incl./excl. VAT), llms.txt and Markdown twins, AI crawlers, metadata in <head> for every user agent, sitemaps with hreflang, a tested schema.org check
agentic-commerce (new) Shopper MCP server, OAuth sign-in, MCP Apps cards, WebMCP (early preview), on-site assistant
pricing Which price from which API, for whom (C4, C10); price lists at volume; Discovery price fields
subscriptions Renewals follow the order store (C3); Shop endpoint traps
bookable-resources API table for bookings; seven storefront rules from four builds
payments Checkout started by an agent; Core reads marked webhook-only (C12); Shop customers (C13)
vector-ranking Taste-ranked agent results; write and read-back traps
responsive-images OG and JSON-LD images in the original format, never AVIF; LCP image in the static shell; two without-react.md bugs fixed
content-model New typed-specs reference; sku, gtin and mpn as separate fields; one plain-text SEO piece
information-architecture Discovery recipe for hreflang replaces Catalogue; redirects, canonicals, re-slugging, collisions
taxonomy Classification codes in topic meta map to CategoryCode; pathIdentifier rules
mass-operations, data-creation, content-json, permissions, plugins, agent-tenants Fixes from the findings; new legacy-apps and tenant-setup references

Matching docs

The same structure is published at https://crystallize.com/docs/developer/storefront (18 pages).

Not done here

  • Version bump. Left for the release commit.
  • Contested findings. These are written as "observed both ways" rather than as rules.
  • Write-dependent claims. These are not re-tested live: order-listing lag, webhook firing, media timings. They come from the builds' findings.

Checks

  • make codeclean: clean on the changed files. It also reformats about 19 unrelated MCP server files that already drift on main; those changes are left out of this PR.
  • make tests: 232 pass, 0 fail.

🤖 Generated with Claude Code

papelipe and others added 30 commits November 12, 2026 11:30
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…op 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 <noreply@anthropic.com>
JSON-LD per page type from typed data (QuantitativeValue with UN/CEFACT codes, classification codes as CategoryCode, ProductGroup, offers with and without VAT, relations), llms.txt, llms-full.txt and Markdown twins, robots for AI crawlers with Content-Signal, metadata in <head> for every user agent (with the Cache Components / PPR pitfall and curl checks), sitemaps with hreflang and updatedAt, and a tested schema.org vocabulary check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Three surfaces on one code path: a shopper-facing MCP server on Discovery and the Shop API (tool design, typed-spec filters parsed from text, "Did you mean", the cartId hand-off, checkout as a destructive tool), OAuth sign-in, MCP Apps cards with host detection, WebMCP (early preview), and an on-site assistant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Discovery for list and market prices (public when open), the Shop API for the cart's customer, Catalogue for displaying any customer's price. Customer row in the cart context, compare-at and rounding rules, price lists that work at volume, the full Discovery price-field table, and promotion traps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renewal orders follow the tenant's order store (registerOrder or Shop create from orderIntent), Shop endpoint traps, and every call on the server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Discovery for the pool and policy snapshot, Shop /cart for availability, holds and confirmation, /order for the order, /booking/admin (booking and booking:admin scopes) for staff, Core for setup. Seven storefront rules from four builds, and booking-flow and modelling additions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The cartId is the session, a signed hand-off lets the browser adopt the basket, an agent never pays card. Core reads labelled webhook-only, Shop customers, lock keys, and the non-tenant-scoped token rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… traps

Write taste sequentially and read it back, userTaste as a list, rebuild taste from Shop order history on the server for agents, house ranking when signed out, and ranking once per query.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
og:image and JSON-LD use the original format, never AVIF, at least 1200 px. Derive only from URLs the API returned, one or two high-priority images, the LCP image in the static shell, and two bugs fixed in without-react.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New typed-specs reference (units to schema.org with UN/CEFACT codes, unit lists breaking writes, unset switches reading false). sku, gtin and mpn are separate fields. One plain-text SEO piece without a canonical field. Discovery vs Catalogue follows the storefront contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ang and redirects

Paths per language from one aliased Discovery query by itemId (replacing the Catalogue recipe), BCP 47 tags and x-default, sitemaps joined on itemId, history redirects, canonicals for shortcuts, re-slugging and collision rules, menus and breadcrumbs from Discovery.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ETIM, GS1 GPC, UNSPSC and Google category codes in topic meta map to JSON-LD CategoryCode. updateTopic without pathIdentifier re-slugs; translate one depth level at a time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion gaps

The real resourceIdentifier charset, where errors live, validation differences, second-language upserts emptying shared relations, large variant sets, and throughput.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…essing

Dimensions as numerics with units, stop and ask instead of picking the closest option, and create the language version before translating.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tables written as HTML come back from Discovery as semantic table nodes; it is the App that drops rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Shop JWTs minted on the server from a pair that is not tenant-scoped, per tenant not per shopper; Discovery open by default and public when open; Core never in the request path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New legacy-apps reference: app.create, the signature query parameter, frame-ancestors and tenant frontends.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New tenant-setup reference: which API creates each setting, getMany shapes, first ignite, storefront credentials and publish webhooks. A Serve step in SKILL.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
agentic-commerce, media, seo-geo and storefront.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add references/preview.md: the custom view and its placeholders, the responsive
device toolbar always on (no preview chrome in the storefront), a preview route
that checks a secret and resolves the item per language from its draft, draft
reads through Discovery switched inside the cached client, no caching and
noindex, the App's listener script, framing by https://app.crystallize.com only
on preview responses, SameSite=None; Secure; Partitioned cookies, and pitfalls.
The storefront skill's draft-preview section links to it, and security-headers
gains the preview exception to deny-framing-everywhere.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The findings now say "one build", "another tenant" and similar instead of
naming customers. Crystallize's own demo tenants (tools-universe and the
other *-universe stores) are kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The upload case still expected mutation/media, which is now a pointer to the media skill. Seven new cases cover media, storefront, seo-geo and agentic-commerce.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
seo-geo and responsive-images stated the same rule but their helpers differed: bestImage ignored the 1200 px floor, shareImage did not check for an AVIF upload, and neither returned dimensions. Both now carry the same helper, which falls back to the original upload with its own width and height.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…talogue's

Tested on a sandbox tenant: restricting Search & Discovery restricts the Search API at once and Discovery after a re-ignite, while Catalogue stays open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Minor bumps for the eleven changed skills that kept their version, and metadata for content-json, which had none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tenant

Tested on a sandbox tenant: a tenant-scoped pair minted a Shop JWT for its tenant (200) and was refused for another tenant its user belongs to, with 400 "User is not a member of tenant X". The skills said a tenant-scoped pair could not mint at all, and told storefronts to use an unscoped token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
didrikhegna and others added 5 commits November 17, 2026 13:54
Tested on a sandbox tenant: the Search & Discovery setting reaches the Search API at once but Discovery only after igniteDiscoApi, and anonymous calls then flapped for about four minutes. The skills told users to restrict Discovery without saying so, and called the access token pair unverified; it was refused in both modes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…strict their read APIs

Tested on a sandbox tenant: a guest cart that sent a contract market got the contract price, and Discovery gave it anonymously. Pricing, storefront, cart-checkout and agentic-commerce now say that a market identifier works as a key, and recommend restricting Catalogue and Search & Discovery when a tenant has price lists or contract prices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hop /order is the default

Tested on a sandbox tenant: one registerOrder and three updateOrder calls left four Shop orders with one coreId, while a Shop-born order was rewritten in place. Core and Shop /order are meant to work on one order, so the skills now call the copies a reported bug with a workaround, and explain that Shop /order is the asynchronous FIFO entry built for volume while Core is synchronous and rate limited.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A component update replaces shared (non-translated) components in every language, not only the one sent.
- A restricted Catalogue answers 400 Invalid static auth token, and takes effect at once.
- Shop /auth/token refuses Python's default urllib User-Agent (Cloudflare 1010).
- additionalInformation: null fails with a bare Output validation error.
- market.create refuses customers that don't exist yet.
- priceLists and tenant(identifier:) are unions; registerOrder answers OrderConfirmation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ool descriptions

Discovery stays the default for storefront reads, but it is updated asynchronously after a publish. Catalogue is the fallback for per-customer prices and for reads that must be in sync with a publish. The query-catalogue tool still called Catalogue a storefront API for building frontends; both tool descriptions now follow the contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@didrikhegna
didrikhegna merged commit 5609c0e into main Nov 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants