@craftware/crafty-sdk 0.8.0 → 0.10.0

package/skills/crafty-cms/SKILL.md

@@ -8,6 +8,12 @@ metadata:
 
 # Crafty CMS (MCP + JavaScript SDK)
 
+> **MCP prompt: `build-site`.** It takes a site from a business description to a published website: content model, pages, frontend with the SDK, preview and deploy, confirming the plan with you before it writes. Arguments: `description` (the business and what the site needs) and optionally `site_id` (an existing site). Needs a token with `crafty:write`.
+>
+> In Claude Code, type `/` and pick `mcp__<server>__build-site`, where `<server>` is the name you gave the Crafty server; other clients list it in their prompt menu. If your client does not show MCP prompts, ask the agent to call `get_guide getting-started` and follow it.
+>
+> Redesigning a client's existing site? The `redesign-site` prompt reads their current site and social media and proposes the new one before building it (see `get_guide migrate`).
+
 Crafty is a headless, multi-tenant CMS. There are two integration surfaces, and they are used at different stages:
 
 | Surface | Purpose | Auth | Use it to |
@@ -34,13 +40,13 @@ npm create crafty@latest mi-sitio -- --url=https://<tenant>.crafty.do
 # same flow: npx @craftware/crafty-cli create mi-sitio --url=https://<tenant>.crafty.do
 ```
 
-It asks for the framework and template (today: Astro, `astro-services` = "sitio de servicios"; Next.js and Nuxt are coming), logs in through the browser (device flow; the user approves, an admin account is needed), creates the site with the starter's block types, collections, form and demo content, configures the visual editor routes, and writes `.env` (`CRAFTY_API_URL`, `CRAFTY_API_KEY`, `CRAFTY_SITE`), `crafty.json` and `src/crafty.types.ts`. Then:
+It asks for the framework and template (today: Astro, `astro-services` = "sitio de servicios", `astro-store` = "tienda" or `astro-docs` = "documentación"; Next.js and Nuxt are coming), logs in through the browser (device flow; the user approves, an admin account is needed), creates the site with the starter's block types, collections, form and demo content, configures the visual editor routes, and writes `.env` (`CRAFTY_API_URL`, `CRAFTY_API_KEY`, `CRAFTY_SITE`), `crafty.json` and `src/crafty.types.ts`. Then:
 
 ```bash
 cd mi-sitio && npm install && npm run dev   # npm run deploy → Crafty Hosting
 ```
 
-- Flags (after `--`): `--url`, `--framework=astro`, `--template=astro-services`, `--name`, `--site=<slug>`, `--draft` (keep demo content as drafts; by default it is published so the static build shows it), `--yes` (no prompts). Agents should pass `--url` and `--yes` so nothing blocks on a prompt; the browser approval still needs the user.
+- Flags (after `--`): `--url`, `--framework=astro`, `--template=astro-services|astro-store|astro-docs`, `--name`, `--site=<slug>`, `--draft` (keep demo content as drafts; by default it is published so the static build shows it), `--yes` (no prompts). Agents should pass `--url` and `--yes` so nothing blocks on a prompt; the browser approval still needs the user.
 - The command is interactive only for the login: tell the user to open the printed URL and approve the code.
 - After it finishes, **read the project's `AGENTS.md`** and follow its conventions (one renderer per block type in `src/render/blocks/`, routes in `src/lib/routes.ts`, `npm run types` after changing the content model) instead of the generic steps in Phase 2.
 - If the site slug already exists it fails before creating anything; if provisioning fails midway it names the half-created site: delete it in the panel or rerun with another `--site`.
@@ -163,6 +169,10 @@ Serving `llms.txt` / `llms-full.txt` for AI agents and crawlers: `crafty.llms.ha
 
 Analytics and ad pixels (Google Tag Manager, GA4, Meta Pixel, TikTok Pixel): do **not** hard-code their snippets into the site. Set the IDs on the "Analítica" admin screen or with the `configure_analytics` MCP tool; Crafty hosting injects the official loaders into every HTML page on the next deploy. If the site already loads GA4 or pixels through GTM, set only the GTM container. Hosted elsewhere: render `(await crafty.analytics.get()).head` before `</head>` in SSR, or call `crafty.analytics.load()` once in the browser (it skips itself when the deploy already injected them). **Details: `references/sdk-development.md`.**
 
+Structured data (schema.org JSON-LD for Google rich results and AI search): do **not** write JSON-LD by hand. Fill the business data (type, address, hours, phone, social profiles) with the `configure_structured_data` MCP tool, map collections to Product / Article / BlogPosting / FAQPage / Event / Service with `structured_data` on `create_collection` / `update_collection`, and render `crafty.structuredData(page, entries)` in `<head>`: the home page carries the business JSON-LD, mapped entries their own. For FAQ blocks, `crafty.structuredData(crafty.faqPage(block.data.items))`. Crafty Hosting adds the business JSON-LD to the home page on deploy when the site does not render it. **Details: `references/sdk-development.md`.**
+
+Online store (when the site's "Tienda" tab is on): products are entries of `productos`; keep the cart with `createCart()` from `@craftware/crafty-sdk/cart`, show totals from `crafty.orders.quote(cart.items())` and send the visitor to Crafty's hosted checkout with `crafty.checkout.start(cart.items())`. Never compute prices or taxes in the frontend. **Details: `references/online-store.md`.**
+
 ## Phase 3 — Deploy a static site with the CLI
 
 ```bash
@@ -230,5 +240,6 @@ These are two different credentials — do not mix them:
 
 - `references/mcp-configuration.md` — connecting every client, scopes, and the full MCP tool catalog with workflows.
 - `references/sdk-development.md` — the complete SDK surface, block helpers, error handling, and examples.
+- `references/online-store.md` — the online store: switching it on (`configure_store`), the products collection, cart, quotes, hosted checkout, orders and webhooks.
 - `references/migrate-to-crafty.md` — migrating an existing site (WordPress or any other) into Crafty: crawl, classify, model, bulk import as drafts, media, redirects, human review, publish.
 - `references/visual-editor.md` — preparing a site for the visual editor: the mandatory question, marking, preview tokens, bridge, headers, `configure_visual_editor`, verification.

package/skills/crafty-cms/references/mcp-configuration.md

@@ -112,6 +112,8 @@ All tools return a JSON text response. IDs are integers; slugs are strings. Pagi
 | `list_forms` | — | `site_id`, `status`, `per_page` | paginated forms, ordered by name |
 | `get_form` | `form_id` | — | one form with its field definitions |
 | `list_redirects` | `site_id` | `environment` (default `production`) | the environment's redirects `{ source, destination, status_code }` |
+| `get_assistant_settings` | `site_id` | `environment` (default `production`) | the site assistant's settings, `status` (`mode` assistant/whatsapp/off, `blocked_reason` server/plan/disabled/quota, this month's `usage`), `answers_count` and the allowed `options` |
+| `list_assistant_answers` | `site_id` | `environment` (default `production`) | the assistant's private fixed answers `{ id, question, answer, author, updated_at }`, newest first |
 | `list_webhooks` | `site_id` | `environment` (default `production`) | content webhooks (admins only) with their events and last deliveries; `upsert_webhook` / `delete_webhook` manage them (`crafty:write`) |
 
 ### Submissions (`crafty:submissions`)
@@ -147,14 +149,20 @@ Form submissions may contain personal data, so they require their own scope.
 | `manage_media_collection` | `site_id`, `key` | `name`, `description`, `is_public` | creates or updates a media repository; `is_public: true` gives permanent public URLs (existing files are moved in the background); new repositories are private |
 | `update_media` | `site_id`, `media_id`, `alt` | — | sets the alt text (max 500 chars) of one media file; `null` or `""` clears it |
 | `delete_media` | `site_id`, `media_id`, `confirm: true` | — | **permanently** deletes one media file (ids from `list_media`) |
-| `create_form` | `site_id`, `name`, `slug` | `description`, `fields` | `fields: [{ key, type, label, required? }]`; starts as `draft` |
+| `create_form` | `site_id`, `name`, `slug` | `description`, `fields`, `captcha` | `fields: [{ key, type, label, required? }]`; starts as `draft`; protected by a captcha by default when Crafty has one configured (`captcha: false` to opt out), and the frontend must then render it with `crafty.forms.captcha()` |
 | `update_form` | `form_id` | `name`, `slug`, `description`, `fields`, `notification_emails` | only supplied fields change; `fields`/`notification_emails` replace |
 | `configure_visual_editor` | `site_id` | `environment` (default `production`), `frontend_url`, `routes` (`page_pattern`, `home_slug`, `collections`, `fixed`), `render_mode` (`ssr`/`hybrid`/`static`/`unknown`), `upload_media_collection` | visual editor settings of one environment; only sent keys change, `null` resets to the fallback; with only `site_id` it just reads; returns the effective settings plus `llms_warnings` (the `llms.txt` generator's warnings, since routes affect it too) |
 | `configure_llms` | `site_id` | `environment` (default `production`), `title`, `summary`, `language`, `excluded_collections` (routed collections to drop), `included_collections` (routeless collections to opt in), `collection_languages` | admins only; same read/partial-update semantics as `configure_visual_editor`; only sent keys change, `null` resets to the fallback; with only `site_id` it just reads; returns the effective settings, the configuration warnings, and the first 40 lines of the generated `llms.txt` |
 
+| `configure_assistant` | `site_id` and at least one setting | `environment` (default `production`), `enabled`, `whatsapp_enabled`, `whatsapp_number`, `whatsapp_label`, `contact_form`, `hours` (`weekdays`/`saturday`/`sunday` → `{ open, close }` or `null`), `timezone`, `greeting`, `suggestions` (max 3), `tone` (`friendly`/`formal`/`technical`), `guidelines`, `privacy_url`, `appearance` (`name`, `color`, `font`, `corners`, `position`, `avatar_on_launcher`) | only sent keys change, `null` resets to the default; the avatar is uploaded in the panel; returns the effective settings and `status` |
+| `configure_store` | `site_id` | `environment` (default `production`), `enabled`, `currency`, `order_prefix`, `prices_include_tax`, `taxes`, `default_tax`, `delivery` (`enabled`, `fee`, `free_from`, `tax`, `zone`), `pickup` (`enabled`, `address`), `payment_methods` (`cash_on_delivery`, `pay_at_pickup`, `transfer`), `transfer_accounts`, `notify_emails`, `customer_emails`, `return_url`, `color`, `captcha` | admins only; `enabled: true` needs the store in the plan and creates (or adopts) the `productos` collection and the checkout URL; only sent keys change; with only `site_id` it just reads; returns the settings, `open`, the products summary and `checkout_url`. See `online-store.md` |
+| `upsert_assistant_answer` | `site_id`, `question`, `answer` | `environment` (default `production`), `answer_id` | adds a fixed answer, or edits the one with `answer_id`; the assistant uses it from the next visitor message |
+| `delete_assistant_answer` | `site_id`, `answer_id` | `environment` (default `production`) | deletes one fixed answer |
 | `upsert_redirects` | `site_id`, `redirects` | `environment` (default `production`), `dry_run` | up to 500 `{ source, destination, status_code? }` per call, matched by `source`; `source` is a path starting with `/` (no spaces, `?` or `#`; Cloudflare Pages `*` splats and `:placeholders` allowed), `destination` a path or absolute http(s) URL, `status_code` 301 (default) / 302 / 307 / 308; invalid items are listed in `failed` and skipped. Crafty hosting writes them to `_redirects` on the next deploy (after the site's own rules; limit 2000 static + 100 dynamic); custom frontends read `GET /api/v1/redirects` |
 | `delete_redirect` | `site_id`, `source` | `environment` (default `production`) | deletes one redirect |
 
+Assistant tools follow the panel's **Asistente** section: admins always, editors with read access can read and editors with write access can change.
+
 Redirect tools follow the **Pages** permission: reading needs access to pages, changing needs write access.
 
 ### Publish (`crafty:publish`)

package/skills/crafty-cms/references/migrate-to-crafty.md

@@ -1,5 +1,11 @@
 # Migrating an existing site to Crafty
 
+> **MCP prompt: `migrate-site`.** It runs this whole runbook for you and stops at every checkpoint for you to confirm. Arguments: `site_id` (the target site), `source` (the old site's URL, its `sitemap.xml` or a description of the export) and optionally `environment` (default `production`) and `research` (default `yes`: it also researches the brand on the web and proposes content the old site lacks; `no` for a strict 1:1 move). Needs a token with `crafty:write`.
+>
+> In Claude Code, type `/` and pick `mcp__<server>__migrate-site`, where `<server>` is the name you gave the Crafty server; other clients list it in their prompt menu. If your client does not show MCP prompts, ask the agent to call `get_guide migrate` and follow it.
+>
+> **Redesign instead of a 1:1 move? MCP prompt: `redesign-site`.** It studies the client's current site, social media and what the rest of the web says about them, sums up their brand, voice and content, and proposes a new site (site map, sections built from your block types, draft copy, visual direction) before it creates anything. Once you approve the proposal it builds it as drafts and never publishes. Arguments: `website` (the current site's URL) and optionally `social` (profile URLs or handles), `goals` and `site_id` (leave it out to make the proposal before the client has a Crafty site). Needs a token with `crafty:write`. Social networks often block automated reading, so be ready to paste the bio and a few posts or share screenshots.
+
 Runbook for moving a site that already exists (WordPress, Webflow, Wix, a static site, another headless CMS) into Crafty with an agent and the MCP server, without breaking its URLs. Work in this order; each phase has a checkpoint where a human confirms before the next one.
 
 Tools used: `bulk_upsert_entries`, `import_media_from_urls`, `upsert_redirects` (plus the usual `create_block_type`, `create_collection`, `create_page`, `publish_*`). Token scopes: `crafty:read` + `crafty:write`; add `crafty:publish` only for the final phase.
@@ -20,8 +26,9 @@ Build an inventory of every URL of the old site:
 1. Sources, best first: the CMS export or API (WordPress REST `/wp-json/wp/v2/posts?per_page=100&page=N`, `/pages`, `/media`; or the WXR export), `sitemap.xml` (and sitemap indexes), then a crawl of internal links from the home page.
 2. For each URL record: old path, title, type guess, language, last modified, the main content (HTML), the images and files it uses, and the old ID if known.
 3. Also collect the URLs that already redirect (HTTP 301/302) and anything in the old site's redirect plugin or `.htaccess`: those must be carried over too.
+4. Research the brand beyond its site: search the web for its name (Google Business profile and reviews, social media, press, directories and marketplaces, award or partner pages). List what the old site lacks as **proposed additions**: reviews and testimonials, FAQs drawn from customer questions, opening hours, locations, services or products listed elsewhere, awards, press mentions, social links. Give each one its source URL and how sure you are, flag information that contradicts the site or looks outdated, and never invent facts. Keep the additions apart from the inventory: they are proposals, not migrated content. Skip this step for a strict 1:1 move (the `migrate-site` prompt takes `research: "no"`).
 
-**Checkpoint:** show the user the counts per type and any URL you could not fetch.
+**Checkpoint:** show the user the counts per type, any URL you could not fetch and the proposed additions. Only the additions the user picks are added, in phase 5, as new drafts.
 
 ## Phase 2 — Classify
 
@@ -58,7 +65,8 @@ Follow "Model content with block types first" in `SKILL.md`:
 1. Transform each item to the collection schema: clean the HTML (drop builder shortcodes, inline styles, tracking pixels), rewrite internal links to the **new** paths, and replace image URLs in the HTML with the `original_url` values from phase 4. Put media references (`cover`, `gallery`) as `media_id` values.
 2. `bulk_upsert_entries` with `{ site_id, collection_slug, entries: [{ slug, external_id, data }], dry_run: true }`. Fix every `failed` item (the errors name the field, e.g. `data.published_on: …`) and check `warnings` (dropped keys = a field missing from the schema).
 3. Run the same batch without `dry_run`. Entries are created as **drafts**; existing ones (same `external_id` or `slug`) are updated with a revision.
-4. Singleton pages: `create_page` with `blocks` in the default locale; they start as drafts too. Other languages of the old site go in with `configure_locales` and `upsert_translation`, not as extra pages.
+4. Write the additions the user picked in phase 1 as new drafts (no `external_id` from the old site) and list them, with their sources, in the review report.
+5. Singleton pages: `create_page` with `blocks` in the default locale; they start as drafts too. Other languages of the old site go in with `configure_locales` and `upsert_translation`, not as extra pages.
 
 ## Phase 6 — Redirects
 

package/skills/crafty-cms/references/online-store.md

@@ -0,0 +1,138 @@
+# Online store
+
+Crafty can sell for any site without a payment gateway: the merchant takes **cash on delivery**, **payment at pickup** or a **bank transfer**, and confirms the payment in the panel. Card payments through the merchant's own gateway (CardNET, AZUL) come in a later stage and plug into the same orders.
+
+The frontend never computes prices and never touches payment data. It shows products, keeps a cart of slugs and quantities, asks Crafty for the totals, and sends the visitor to Crafty's **hosted checkout** (`checkout.crafty.do/{store}`), where they enter their details, pick delivery or pickup and a payment method, and get an order page and an email.
+
+## How it fits together
+
+| Piece | Where | What it does |
+| --- | --- | --- |
+| Plan | Crafty central (`store_enabled`) | The workspace's plan must include the online store. |
+| Store settings | Panel → site → **Tienda** tab, or the `configure_store` MCP tool (admins) | Switch the store on per environment; currency, taxes, delivery, pickup, payment methods, order emails, return URL, checkout color, captcha. |
+| Products | The `productos` collection (Panel → Tienda → **Productos**, or entries tools) | One published entry per product. |
+| Cart and totals | Your frontend, with the SDK | `createCart()` keeps the cart; `crafty.orders.quote()` prices it. |
+| Checkout | `checkout.crafty.do/{store}/c/{session}` (hosted by Crafty) | Customer details, delivery or pickup, payment method, captcha; places the order. |
+| Order page | `checkout.crafty.do/{store}/o/{number}?t={token}` | Status, lines, totals and payment instructions; linked from the emails. |
+| Orders | Panel → Tienda → **Pedidos** | Confirm, mark ready, delivered or cancelled, mark paid, internal note, WhatsApp the customer. |
+| Integrations | Content webhooks `order.created`, `order.status_changed`, `order.paid` | Notify other systems (ERP, digital delivery, Slack). |
+
+## 1. Switch the store on
+
+In the panel: site → **Tienda** → choose the environment → **Activar tienda**. Through MCP (admins):
+
+```json
+configure_store {
+  "site_id": 3,
+  "enabled": true,
+  "currency": "DOP",
+  "pickup": { "enabled": true, "address": "Av. Sarasota 55, Santo Domingo" },
+  "delivery": { "enabled": true, "fee": "250", "free_from": "4000", "tax": "itbis-18", "zone": "Gran Santo Domingo" },
+  "payment_methods": { "cash_on_delivery": true, "pay_at_pickup": true, "transfer": true },
+  "transfer_accounts": "Banco Popular · Cuenta corriente 812-345678-9 · Café Monteverde SRL",
+  "notify_emails": ["pedidos@monteverde.do"],
+  "return_url": "https://monteverde.do/tienda"
+}
+```
+
+Switching it on:
+
+- creates the `productos` collection, or adopts an existing `productos` collection when its store fields have the types below (otherwise it reports the conflicting fields);
+- gives the environment a store handle and its checkout URL (`checkout.crafty.do/<site-slug>` for production, `<site-slug>-<environment>` for others);
+- sets an order prefix from the site's initials (`CM-` → `CM-1001`) and the Dominican tax template (ITBIS 18 %, ITBIS 16 %, Exento).
+
+Switching it off stops new orders; products and orders stay. Send `configure_store` with only `site_id` to read the current settings, the checkout URL and how many products have no price.
+
+## 2. Products
+
+Products are entries of `productos`. While the store is on, these fields can be relabeled but not removed or retyped (pricing reads them), and the collection can't be deleted. Add any other fields you need: they never change the price.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `nombre` | string, required | Product name (also the entry title and slug source). |
+| `precio` | decimal, required | Price in the store currency, e.g. `1450` or `1450.50`. Taxes included unless the store says otherwise. |
+| `disponible` | select, required | `disponible`, `pocas` (few left) or `agotado` (sold out: can't be bought). |
+| `variantes` | repeater | Each variant: `nombre` (required), `precio` (only when it changes the price), `sku`. A product with variants must be bought with one. |
+| `imagenes` | multiReference → Media | The first image appears on the checkout and the order. |
+| `sku` | string | |
+| `impuesto` | string | A tax key of the store (`itbis-18`, `itbis-16`, `exento`). Empty uses the store's default tax. |
+
+Only **published** products can be bought. Translations of `nombre` (via `upsert_translation` / `translate_content`) show on the checkout in the visitor's language.
+
+## 3. The cart and totals in the frontend
+
+Store calls need `siteSlug` in the client config. The API key, when sent, picks its environment; without it the store uses production.
+
+```ts
+import { createCraftyClient } from "@craftware/crafty-sdk";
+import { createCart } from "@craftware/crafty-sdk/cart";
+
+const crafty = createCraftyClient({ baseUrl, apiKey, siteSlug: "monteverde" });
+const cart = createCart({ key: "monteverde:cart" });
+
+const store = await crafty.store.get();
+// { enabled, currency, prices_include_tax, taxes, delivery, pickup, payment_methods, checkout_url, … }
+
+const { data: products } = await crafty.entries.list("productos", { per_page: 100 });
+
+cart.add("geisha-lavado", { variant: "Molido para filtro", quantity: 2 });
+cart.subscribe((items) => renderCartBadge(items));
+
+const quote = await crafty.orders.quote(cart.items(), { fulfillment: "delivery" });
+// quote.items, quote.subtotal, quote.delivery_fee, quote.taxes, quote.total (decimal strings)
+// quote.unavailable: lines Crafty left out, with reason not_found | sold_out | variant_not_found | variant_required | no_price
+```
+
+Show `quote.total`, not a total you add up: Crafty applies variant prices, the free-delivery threshold and rounds each tax once per order, exactly as the order will be charged. `crafty.store.get()` is cached for a minute; `quote()` is always fresh.
+
+## 4. Checkout
+
+```ts
+await crafty.checkout.start(cart.items(), {
+  returnUrl: "https://monteverde.do/tienda", // optional; defaults to the store's return URL
+  fields: { regalo: "Envolver para regalo" }, // optional notes shown to the merchant
+});
+```
+
+`start()` creates a checkout session (valid 24 hours) and sends the browser to the hosted checkout. `checkout.create()` returns `{ id, url, expires_at }` without redirecting, for SSR or links. The checkout re-prices the cart; if a price changed since the page loaded it shows the new total and asks the customer to confirm.
+
+After the order, **Volver a la tienda** leads to the return URL with `?pedido=<number>`. On that page call `cart.clearOnReturn()`: it empties the cart and returns the order number so you can thank the customer.
+
+An order can be read back with its token, which is in the order page link (`?t=`):
+
+```ts
+const order = await crafty.orders.get("CM-1001", token);
+```
+
+## 5. Orders and notifications
+
+- Each order gets a number per environment (`<prefix>1001`, `1002`, …), status **Nuevo**, payment **Pendiente**.
+- Status moves forward only: new → confirmed → ready → delivered; any open order can be cancelled.
+- **Marcar pagado** records the payment (with an optional reference, e.g. the transfer number).
+- The customer gets an email on each step (from the store's name, replies go to the merchant); the `notify_emails` get every new order. Turn customer emails off with `customer_emails: false`.
+- Editors see **Pedidos** only with the `orders` section permission (hidden, read or edit), set per user in Settings → Users.
+
+## REST endpoints
+
+No API key is required; the site is in the URL. Errors use the usual `{ error, message }` shape.
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| GET | `/api/v1/sites/{site}/store` | Public settings. |
+| POST | `/api/v1/sites/{site}/orders/quote` | Body `{ items: [{ slug, variant?, quantity }], fulfillment?: "delivery" \| "pickup", locale? }`. |
+| POST | `/api/v1/sites/{site}/checkout` | Body `{ items, return_url?, fields?, locale? }` → 201 `{ data: { id, url, expires_at } }`. |
+| GET | `/api/v1/sites/{site}/orders/{number}` | Token in `?token=` or `X-Order-Token`. |
+
+A closed store answers `404 STORE_DISABLED`. The quote and checkout endpoints are rate limited per visitor.
+
+## Starter
+
+`npm create crafty -- --template=astro-store` creates a store site in Astro: catalog, product pages with variants, a cart page with live totals and the hosted checkout. It creates the `productos` collection and demo products, and switches the store on when the workspace plan includes it.
+
+## Common pitfalls
+
+- **Prices or taxes computed in the frontend.** Always show `quote()` totals; the checkout charges Crafty's numbers.
+- **Products as drafts.** Only published products can be bought; a static build lists only published entries too.
+- **A product with variants added without one.** It comes back in `unavailable` with `variant_required`.
+- **Checkout 404.** The store is off, the plan doesn't include it, or the session expired (24 h): start a new checkout.
+- **Moving the site to another workspace.** Orders and the checkout handle move with it.

package/skills/crafty-cms/references/sdk-development.md

@@ -187,6 +187,7 @@ Types depend on the environment (generate with the key of the environment the co
 crafty.forms.list(options?)                  // => { data: CraftyForm[] }            (requires apiKey)
 crafty.forms.get(slug, options?)             // => { data: CraftyForm }              (requires apiKey)
 crafty.forms.submit(formSlug, data, options?) // => { id, form_id, submitted_at }   (public; apiKey optional, picks the environment)
+crafty.forms.captcha(form, container)         // => CraftyFormCaptcha | null           (browser; renders the form's captcha widget)
 ```
 
 `forms.submit()` uses a **public** endpoint: the `X-API-Key`, when configured, only selects the environment (a staging key submits to staging, no key submits to production), but it **requires `siteSlug` in the client config** — calling it without one throws a synchronous `CraftyError` with code `BAD_REQUEST`.
@@ -205,6 +206,19 @@ const result = await crafty.forms.submit("contact", {
 // => { id, form_id, submitted_at }
 ```
 
+Forms protected by a captcha return `captcha: { provider, site_key, token_field }` (absent otherwise), and their submissions are rejected with 422 without the widget token. In the browser, render the widget next to the form and pass it to `submit()`:
+
+```ts
+const { data: form } = await crafty.forms.get("contact");
+const captcha = await crafty.forms.captcha(form, document.querySelector("#captcha")!); // null when not needed
+
+await crafty.forms.submit("contact", values, { captcha }); // adds the token, then resets the widget
+```
+
+The provider is set by Crafty, so read it from `captcha.provider` instead of assuming one: Turnstile runs invisibly and only shows a challenge to suspicious visitors, hCaptcha shows a checkbox the visitor must tick, so leave room for it in the layout. Without the SDK, load the provider script yourself and post the token in `captcha.token_field`.
+
+New forms get the captcha by default once Crafty has captcha keys configured; it is the **Proteger con captcha** box in the form's settings in the panel, or `captcha: false` on `create_form`. Turning it on for a form on a site that does not render the widget makes every submission fail with 422, so update the frontend first.
+
 > Note the asymmetry: `collections.get()` returns the bare object, while `forms.get()` and `entries.get()` are wrapped in `{ data }`.
 
 ### `mediaCollections`
@@ -281,6 +295,40 @@ crafty.analytics.load(options?)  // browser only => "loaded" | "already-loaded"
 
 Never hard-code GTM / GA4 / pixel snippets in the site, and never add GA4 both here and inside GTM (page views are counted twice).
 
+## Structured data
+
+The public API serves schema.org JSON-LD in `structured_data`: on the home page (`pages.get(homeSlug)`, the business set with `configure_structured_data`), on `crafty.site.get()`, and on each published entry of a collection with a structured data mapping (`structured_data` on `create_collection` / `update_collection`). It is `null` when nothing is configured or a required property is empty.
+
+```ts
+crafty.site.get(options?)                 // => { name, slug, environment, default_locale, locales, structured_data }
+crafty.structuredData(...sources)         // => '<script type="application/ld+json">…</script>' tags, "" when none
+crafty.jsonLd(...sources)                 // => the JSON-LD objects, for useHead / <Head>
+crafty.faqPage([{ question, answer }])    // => FAQPage JSON-LD for a FAQ block, or null
+```
+
+Sources can be pages, entries, their API responses, list responses, the site or JSON-LD objects; FAQPage objects are merged into one per page. The script content escapes `<`, so it is safe to inject as raw HTML (`set:html`, `v-html`, `dangerouslySetInnerHTML`). Validate the result at https://search.google.com/test/rich-results. On Crafty Hosting the deploy also adds the business JSON-LD to the home page (`index.html`) when the page does not render it already, so a site gets LocalBusiness even without the helper.
+
+## Online store
+
+When the store is on (the site's "Tienda" tab), products are entries of the `productos` collection: list them with `entries.list("productos")` (fields `nombre`, `precio`, `disponible`, `variantes`, `imagenes`, `sku`, `impuesto`). Never compute totals in the frontend: the cart holds slugs, variants and quantities only, Crafty prices it, and the visitor finishes on Crafty's hosted checkout (delivery or pickup, cash, pay at pickup or bank transfer). Store calls need `siteSlug` in the client config; the API key, when sent, picks its environment.
+
+```ts
+import { createCart } from "@craftware/crafty-sdk/cart";
+
+crafty.store.get()                                   // => { enabled, currency, taxes, delivery, pickup, payment_methods, checkout_url, … }
+crafty.orders.quote(cart.items(), { fulfillment })   // => { items, unavailable, subtotal, delivery_fee, taxes, total } as decimal strings
+crafty.checkout.start(cart.items(), { returnUrl })   // creates the session and sends the browser to the hosted checkout
+crafty.checkout.create(cart.items(), options)        // => { id, url, expires_at } without redirecting
+crafty.orders.get(number, token)                     // => the order, with the token from its page link (?t=)
+
+const cart = createCart();          // localStorage, key "crafty:cart" (pass { key } per site)
+cart.add("geisha", { variant: "Molido", quantity: 2 });
+cart.update("geisha", 3, "Molido"); cart.remove("taza"); cart.count(); cart.subscribe(render);
+cart.clearOnReturn();               // on the return page: empties the cart when the URL has ?pedido=, returns the number
+```
+
+`quote().unavailable` lists lines Crafty left out (`not_found`, `sold_out`, `variant_not_found`, `variant_required`, `no_price`). A closed store answers 404 `STORE_DISABLED`. After the order, "Volver a la tienda" leads to `returnUrl` (or the store's setting) with `?pedido=<number>`.
+
 ## Error handling
 
 The SDK throws `CraftyError` for HTTP, timeout, abort, network, and config failures.