@craftware/crafty-sdk 0.1.0 → 0.2.1

package/README.md

@@ -2,6 +2,18 @@
 
 Official JavaScript SDK for the Crafty public API (current local implementation).
 
+## AI agent skill
+
+This package ships an agent **skill** that teaches Claude, Cursor, and other agents how to configure a Crafty site through its MCP server and build against it with this SDK. It is included in the published package under `skills/crafty-cms/`.
+
+To activate it, copy it into your project's skills directory after installing the SDK:
+
+```bash
+cp -r node_modules/@craftware/crafty-sdk/skills/crafty-cms .claude/skills/
+```
+
+(Use the equivalent skills directory for your agent, e.g. `.cursor/skills/`.) The skill is self-contained — it includes `SKILL.md` plus `references/mcp-configuration.md` and `references/sdk-development.md`.
+
 ## Requirements
 
 - Node `>=20` (package engine)
@@ -13,8 +25,8 @@ Official JavaScript SDK for the Crafty public API (current local implementation)
 import { createCraftyClient } from "@craftware/crafty-sdk";
 
 const crafty = createCraftyClient({
-  baseUrl: "https://tenant.crafty.test",
-  apiKey: "SITE_API_TOKEN",
+  baseUrl: "https://tenant.crafty.do",
+  apiKey: "ENVIRONMENT_API_TOKEN",
   timeoutMs: 10_000
 });
 ```
@@ -22,12 +34,13 @@ const crafty = createCraftyClient({
 ### Client config
 
 - `baseUrl` (required): tenant base URL. The SDK appends `/api/v1` automatically if missing.
-- `apiKey` (optional): site API token sent as `X-API-Key`.
+- `apiKey` (optional): environment API token sent as `X-API-Key`.
   - When provided, the API resolves the active site from this token.
   - `pages.*` requests use this site context automatically (you do not pass `siteSlug`).
+- `siteSlug` (optional): site slug used for public form submissions (`forms.submit()`).
 - `fetch` (optional): custom fetch implementation.
 - `headers` (optional): default headers applied to all requests.
-- `timeoutMs` (optional): default timeout for all requests.
+- `timeoutMs` (optional): default timeout (ms) for all requests. A timeout is only applied when the value is a number greater than `0`.
 
 ## Available resources
 
@@ -53,18 +66,49 @@ Supported common `query` params:
 - `crafty.pages.list(query?, options?)`
 - `crafty.pages.get(pageSlug, options?)`
 
-`pages.*` endpoints are scoped by the `apiKey` configured on the client.
+`pages.*` endpoints are scoped by the environment resolved from `apiKey`.
 
 `pages.get()` returns a page response enriched with block helpers:
 
-- `page.blocks` (array alias of `page.data.blocks ?? []`)
+- `page.data` => the raw `CraftyPage`
+- `page.blocks` => all blocks (`CraftyBlock[]`; a non-array `data.blocks` is coerced to `[]`)
 - `page.block(type)` => first block of that type or `null`
-- `page.blocksOf(type)` => all blocks of that type
+- `page.blocksOf(type)` => all blocks of that type (`[]` if none)
 - `page.hasBlock(type)` => boolean
-- `page.requireBlock(type)` => first block or throws
+- `page.requireBlock(type)` => first block, or throws a plain `Error` (not a `CraftyError`)
 - `page.byType.<type>` => array of blocks for that type
 - `page.firstByType.<type>` => first block for that type or `null`
 
+### `forms`
+
+- `crafty.forms.list(options?)` — list all forms (requires API key)
+- `crafty.forms.get(slug, options?)` — get a single form by slug (requires API key)
+- `crafty.forms.submit(formSlug, data, options?)` — submit a public form (no API key needed)
+
+The `submit()` method uses a public endpoint that does not require authentication. You must provide `siteSlug` in the client config for submissions to work — calling `submit()` without it throws a synchronous `CraftyError` with code `BAD_REQUEST`:
+
+```ts
+const crafty = createCraftyClient({
+  baseUrl: "https://tenant.crafty.do",
+  apiKey: "ENVIRONMENT_API_TOKEN",
+  siteSlug: "my-site",
+});
+
+// List forms (authenticated)
+const forms = await crafty.forms.list();
+
+// Get form details (authenticated)
+const contactForm = await crafty.forms.get("contact");
+
+// Submit a form (public, no API key sent)
+const result = await crafty.forms.submit("contact", {
+  name: "Jane Doe",
+  email: "jane@example.com",
+  message: "Hello!",
+});
+// result => { id, form_id, submitted_at }
+```
+
 ### `mediaCollections`
 
 - `crafty.mediaCollections.list(query?, options?)`
@@ -72,7 +116,7 @@ Supported common `query` params:
 Supported `query.include` values:
 - `"stats"`
 - `"directories"`
-- Array form is supported and serialized as comma-separated values
+- Array form is supported, de-duplicated, and serialized as comma-separated values; a raw string is passed through unchanged
 
 ### `mediaFiles`
 
@@ -108,13 +152,16 @@ const posts = await crafty.entries.list(
 - `entries.list()` => paginated `{ data, links, meta }`
 - `entries.get()` => `{ data: CraftyEntry }`
 - `pages.list()` => paginated `{ data, links, meta }`
-- `pages.get()` => `{ data: CraftyPage }`
+- `pages.get()` => `{ data: CraftyPage }` plus the block helpers listed above
 - `mediaCollections.list()` => `{ data, meta: { includes } }`
 - `mediaFiles.list()` => `{ data, links, meta }` (`meta` includes `ttl_minutes`)
+- `forms.list()` => `{ data: CraftyForm[] }`
+- `forms.get()` => `{ data: CraftyForm }`
+- `forms.submit()` => `{ id, form_id, submitted_at }`
 
 ## Errors
 
-The SDK throws `CraftyError` for HTTP, timeout, abort, and network failures.
+The SDK throws `CraftyError` for HTTP, timeout, abort, network, and configuration failures (e.g. no `fetch` implementation available at construction).
 
 ```ts
 import { CraftyError } from "@craftware/crafty-sdk";
@@ -129,17 +176,17 @@ try {
 }
 ```
 
-Current error codes:
+Current error codes (with their HTTP-status mapping):
 
-- `NETWORK_ERROR`
-- `TIMEOUT`
-- `BAD_REQUEST`
-- `UNAUTHORIZED`
-- `FORBIDDEN`
-- `NOT_FOUND`
-- `RATE_LIMITED`
-- `SERVER_ERROR`
-- `UNKNOWN_ERROR`
+- `NETWORK_ERROR` — network failure, or no `fetch` available at construction
+- `TIMEOUT` — request exceeded `timeoutMs`
+- `BAD_REQUEST` — HTTP 400 or 422
+- `UNAUTHORIZED` — HTTP 401
+- `FORBIDDEN` — HTTP 403
+- `NOT_FOUND` — HTTP 404
+- `RATE_LIMITED` — HTTP 429
+- `SERVER_ERROR` — HTTP 5xx
+- `UNKNOWN_ERROR` — any other / unmapped status
 
 ## End-to-end example
 
@@ -147,8 +194,9 @@ Current error codes:
 import { createCraftyClient } from "@craftware/crafty-sdk";
 
 const crafty = createCraftyClient({
-  baseUrl: "https://twocare.crafty.test",
+  baseUrl: "https://tenant.crafty.do",
   apiKey: process.env.CRAFTY_API_KEY,
+  siteSlug: "my-site",
   timeoutMs: 10_000
 });
 
@@ -157,17 +205,19 @@ const posts = await crafty.entries.list("posts", { per_page: 15 });
 const mediaCollections = await crafty.mediaCollections.list({ include: ["stats", "directories"] });
 const mediaFiles = await crafty.mediaFiles.list({ collection: "library", per_page: 24 });
 const homePage = await crafty.pages.get("home");
+const forms = await crafty.forms.list();
+const submission = await crafty.forms.submit("contact", { name: "Jane", email: "jane@test.com" });
 ```
 
-## Pages scoping (site via API key)
+## Pages scoping (site+environment via API key)
 
 `pages` requests no longer require a `siteSlug` parameter. The site is inferred server-side from the
 `X-API-Key` header (set from `apiKey` in `createCraftyClient()`).
 
 ```ts
 const crafty = createCraftyClient({
-  baseUrl: "https://tenant.crafty.test",
-  apiKey: "SITE_API_TOKEN",
+  baseUrl: "https://tenant.crafty.do",
+  apiKey: "ENVIRONMENT_API_TOKEN",
 });
 
 await crafty.pages.list({ per_page: 12 });

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { CollectionsResource } from "./resources/collections";
 import { EntriesResource } from "./resources/entries";
+import { FormsResource } from "./resources/forms";
 import { MediaCollectionsResource } from "./resources/mediaCollections";
 import { MediaFilesResource } from "./resources/mediaFiles";
 import { PagesResource } from "./resources/pages";
@@ -7,6 +8,7 @@ import type { CraftyClientConfig } from "./types/public";
 export type CraftyClient = {
     collections: CollectionsResource;
     entries: EntriesResource;
+    forms: FormsResource;
     mediaCollections: MediaCollectionsResource;
     mediaFiles: MediaFilesResource;
     pages: PagesResource;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,mBAAmB,CAAC;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAU3E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,mBAAmB,CAAC;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,aAAa,CAAC;IACrB,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAW3E"}

package/dist/client.js

@@ -1,6 +1,7 @@
 import { HttpClient } from "./http";
 import { CollectionsResource } from "./resources/collections";
 import { EntriesResource } from "./resources/entries";
+import { FormsResource } from "./resources/forms";
 import { MediaCollectionsResource } from "./resources/mediaCollections";
 import { MediaFilesResource } from "./resources/mediaFiles";
 import { PagesResource } from "./resources/pages";
@@ -9,6 +10,7 @@ export function createCraftyClient(config) {
     return {
         collections: new CollectionsResource(http),
         entries: new EntriesResource(http),
+        forms: new FormsResource(http),
         mediaCollections: new MediaCollectionsResource(http),
         mediaFiles: new MediaFilesResource(http),
         pages: new PagesResource(http)

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAWlD,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEjD,OAAO;QACL,WAAW,EAAE,IAAI,mBAAmB,CAAC,IAAI,CAAC;QAC1C,OAAO,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC;QAClC,gBAAgB,EAAE,IAAI,wBAAwB,CAAC,IAAI,CAAC;QACpD,UAAU,EAAE,IAAI,kBAAkB,CAAC,IAAI,CAAC;QACxC,KAAK,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC;KAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAYlD,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEjD,OAAO;QACL,WAAW,EAAE,IAAI,mBAAmB,CAAC,IAAI,CAAC;QAC1C,OAAO,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC;QAClC,KAAK,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC;QAC9B,gBAAgB,EAAE,IAAI,wBAAwB,CAAC,IAAI,CAAC;QACpD,UAAU,EAAE,IAAI,kBAAkB,CAAC,IAAI,CAAC;QACxC,KAAK,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC;KAC/B,CAAC;AACJ,CAAC"}

package/dist/http.d.ts

@@ -9,6 +9,7 @@ type RequiredTransportConfig = {
     fetchImpl: typeof fetch;
     defaultHeaders: HeadersInit | undefined;
     apiKey: string | undefined;
+    siteSlug: string | undefined;
     timeoutMs: number | undefined;
 };
 export declare class HttpClient {
@@ -16,12 +17,19 @@ export declare class HttpClient {
     private readonly fetchImpl;
     private readonly defaultHeaders;
     private readonly apiKey;
+    private readonly siteSlug;
     private readonly defaultTimeoutMs;
     constructor(config: RequiredTransportConfig);
     static fromClientConfig(config: CraftyClientConfig): HttpClient;
+    getSiteSlug(): string | undefined;
     get<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, options?: HttpRequestOptions & {
+        skipApiKey?: boolean;
+    }): Promise<T>;
     request<T>(path: string, options: HttpRequestOptions & {
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: unknown;
+        skipApiKey?: boolean;
     }): Promise<T>;
     private buildUrl;
 }

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAc,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErF,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAC/D,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE9C,KAAK,kBAAkB,GAAG,cAAc,GAAG;IACzC,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,cAAc,EAAE,WAAW,GAAG,SAAS,CAAC;IACxC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAEnC,MAAM,EAAE,uBAAuB;WAQpC,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,UAAU;IAwBzD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI9D,OAAO,CAAC,CAAC,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAAG;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;KAAE,GACpF,OAAO,CAAC,CAAC,CAAC;IAkFb,OAAO,CAAC,QAAQ;CAejB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAc,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErF,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAC/D,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE9C,KAAK,kBAAkB,GAAG,cAAc,GAAG;IACzC,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,cAAc,EAAE,WAAW,GAAG,SAAS,CAAC;IACxC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAEnC,MAAM,EAAE,uBAAuB;WASpC,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,UAAU;IAyB/D,WAAW,IAAI,MAAM,GAAG,SAAS;IAI3B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI9D,IAAI,CAAC,CAAC,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,kBAAkB,GAAG;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GACtD,OAAO,CAAC,CAAC,CAAC;IAcA,OAAO,CAAC,CAAC,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAAG;QAC5B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;QACpD,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,GACA,OAAO,CAAC,CAAC,CAAC;IA2Fb,OAAO,CAAC,QAAQ;CAejB"}

package/dist/http.js

@@ -4,12 +4,14 @@ export class HttpClient {
     fetchImpl;
     defaultHeaders;
     apiKey;
+    siteSlug;
     defaultTimeoutMs;
     constructor(config) {
         this.apiBaseUrl = config.apiBaseUrl;
         this.fetchImpl = config.fetchImpl;
         this.defaultHeaders = config.defaultHeaders;
         this.apiKey = config.apiKey;
+        this.siteSlug = config.siteSlug;
         this.defaultTimeoutMs = config.timeoutMs;
     }
     static fromClientConfig(config) {
@@ -29,12 +31,27 @@ export class HttpClient {
             fetchImpl,
             defaultHeaders: config.headers,
             apiKey: config.apiKey,
+            siteSlug: config.siteSlug,
             timeoutMs: config.timeoutMs
         });
     }
+    getSiteSlug() {
+        return this.siteSlug;
+    }
     async get(path, options) {
         return this.request(path, { ...options, method: "GET" });
     }
+    async post(path, body, options) {
+        const requestOptions = {
+            ...options,
+            method: "POST",
+            body
+        };
+        if (options?.skipApiKey) {
+            requestOptions.skipApiKey = true;
+        }
+        return this.request(path, requestOptions);
+    }
     async request(path, options) {
         const url = this.buildUrl(path, options.query);
         const headers = new Headers(this.defaultHeaders);
@@ -45,9 +62,12 @@ export class HttpClient {
         if (!headers.has("Accept")) {
             headers.set("Accept", "application/json");
         }
-        if (this.apiKey && !headers.has("X-API-Key")) {
+        if (this.apiKey && !headers.has("X-API-Key") && !options.skipApiKey) {
             headers.set("X-API-Key", this.apiKey);
         }
+        if (options.body !== undefined && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
         const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs;
         const timeoutController = typeof timeoutMs === "number" && timeoutMs > 0
             ? new AbortController()
@@ -58,11 +78,15 @@ export class HttpClient {
             timeoutHandle = setTimeout(() => timeoutController.abort("timeout"), timeoutMs);
         }
         try {
-            const response = await this.fetchImpl(url, {
+            const fetchInit = {
                 method: options.method,
                 headers,
                 signal: signal ?? null
-            });
+            };
+            if (options.body !== undefined) {
+                fetchInit.body = JSON.stringify(options.body);
+            }
+            const response = await this.fetchImpl(url, fetchInit);
             const payload = await parseResponsePayload(response);
             if (!response.ok) {
                 const requestId = response.headers.get("x-request-id") ?? undefined;

package/dist/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/resources/forms.d.ts

@@ -0,0 +1,10 @@
+import { HttpClient } from "../http";
+import type { FormListResponse, FormShowResponse, FormSubmitData, FormSubmitResponse, RequestOptions } from "../types/public";
+export declare class FormsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: RequestOptions): Promise<FormListResponse>;
+    get(slug: string, options?: RequestOptions): Promise<FormShowResponse>;
+    submit(formSlug: string, data: FormSubmitData, options?: RequestOptions): Promise<FormSubmitResponse>;
+}
+//# sourceMappingURL=forms.d.ts.map

package/dist/resources/forms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.d.ts","sourceRoot":"","sources":["../../src/resources/forms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,qBAAa,aAAa;IACL,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,IAAI,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIzD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAItE,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,kBAAkB,CAAC;CAgB/B"}

package/dist/resources/forms.js

@@ -0,0 +1,24 @@
+import { CraftyError } from "../errors";
+export class FormsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(options) {
+        return this.http.get("/forms", options);
+    }
+    get(slug, options) {
+        return this.http.get(`/forms/${encodeURIComponent(slug)}`, options);
+    }
+    submit(formSlug, data, options) {
+        const siteSlug = this.http.getSiteSlug();
+        if (!siteSlug) {
+            throw new CraftyError({
+                code: "BAD_REQUEST",
+                message: "siteSlug is required in client config to submit forms."
+            });
+        }
+        return this.http.post(`/sites/${encodeURIComponent(siteSlug)}/forms/${encodeURIComponent(formSlug)}/submit`, data, { ...options, skipApiKey: true });
+    }
+}
+//# sourceMappingURL=forms.js.map

package/dist/resources/forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.js","sourceRoot":"","sources":["../../src/resources/forms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAUxC,MAAM,OAAO,aAAa;IACY;IAApC,YAAoC,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,IAAI,CAAC,OAAwB;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAmB,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAEM,GAAG,CAAC,IAAY,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAmB,UAAU,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACxF,CAAC;IAEM,MAAM,CACX,QAAgB,EAChB,IAAoB,EACpB,OAAwB;QAExB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAEzC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,WAAW,CAAC;gBACpB,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,wDAAwD;aAClE,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CACnB,UAAU,kBAAkB,CAAC,QAAQ,CAAC,UAAU,kBAAkB,CAAC,QAAQ,CAAC,SAAS,EACrF,IAAI,EACJ,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CACjC,CAAC;IACJ,CAAC;CACF"}

package/dist/types/public.d.ts

@@ -141,12 +141,45 @@ export type MediaFilesListQuery = {
     per_page?: number;
     page?: number;
 };
+export type CraftyForm = {
+    id: number;
+    name: string;
+    slug: string;
+    description: string | null;
+    fields: Record<string, CraftyFormField>;
+    status: "draft" | "published";
+    hcaptcha_enabled: boolean;
+    created_at: string;
+    updated_at: string;
+};
+export type CraftyFormField = {
+    label: string;
+    type: "text" | "textarea" | "email" | "tel" | "number" | "select" | "checkbox" | "radio" | "date";
+    required: boolean;
+    options?: string[];
+    order: number;
+};
+export type FormListResponse = {
+    data: CraftyForm[];
+};
+export type FormShowResponse = SingleResponse<CraftyForm>;
+export type FormSubmitData = Record<string, unknown>;
+export type FormSubmitResponse = {
+    id: number;
+    form_id: number;
+    submitted_at: string;
+};
 export type CraftyClientConfig = {
     baseUrl: string;
     /**
-     * Site API token. The SDK sends it as `X-API-Key: <token>`.
+     * Environment API token. The SDK sends it as `X-API-Key: <token>`.
+     * The backend resolves site + environment from this key.
      */
     apiKey?: string;
+    /**
+     * Site slug, required for public endpoints like form submissions.
+     */
+    siteSlug?: string;
     fetch?: typeof fetch;
     headers?: HeadersInit;
     timeoutMs?: number;

package/dist/types/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/types/public.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/types/public.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftware/crafty-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -18,7 +18,8 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
     "node": ">=20"

package/skills/crafty-cms/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: crafty-cms
+description: "Build on Crafty CMS — configure sites, pages, blocks, collections, entries, forms, and media through the Crafty MCP server, then develop a frontend with the @craftware/crafty-sdk JavaScript SDK. Use when connecting an agent to a Crafty MCP server; calling Crafty MCP tools like list_sites, create_page, publish_form, or upload_media; installing or importing @craftware/crafty-sdk or createCraftyClient; fetching Crafty pages, entries, collections, or media; rendering page blocks; or submitting Crafty forms."
+license: MIT
+metadata:
+  author: craftware
+---
+
+# Crafty CMS (MCP + JavaScript SDK)
+
+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 |
+|---|---|---|---|
+| **MCP server** | Author and configure content | Bearer token (PAT or OAuth), scoped | Create sites, pages, blocks, collections, entries, forms; upload media; publish |
+| **`@craftware/crafty-sdk`** | Read published content into an app | `X-API-Key` environment token | Fetch pages/blocks, entries, collections, media; submit forms from a site |
+
+The normal flow is **configure with the MCP server → build a frontend with the SDK**.
+
+## When to Use
+
+- Connecting Claude, Cursor, VS Code, Codex, or ChatGPT to a Crafty tenant's MCP server.
+- Driving Crafty MCP tools (`list_sites`, `create_page`, `create_entry`, `create_form`, `publish_page`, `upload_media`, …).
+- Installing or importing `@craftware/crafty-sdk` / `createCraftyClient`.
+- Fetching Crafty pages, entries, collections, or media in app code, or submitting a Crafty form.
+
+## Scope
+
+- **In scope:** using a *deployed* Crafty tenant via its MCP server and the published SDK.
+- **Out of scope:** building or modifying the Crafty backend itself, the SDK's internals, or the publish pipeline (that's the `publish-sdk` skill).
+
+## Domain model
+
+- **Site** — top-level tenant resource. Everything else belongs to a site.
+- **Page** — a web page in a site; `draft` or `published`; composed of ordered **Blocks**.
+- **Block** — a content unit on a page; its **BlockType** defines the data schema.
+- **Collection** — a structured content schema (e.g. "Blog Posts"); defines the fields **Entries** must have.
+- **Entry** — one record in a collection (e.g. a single post). Belongs to a site and a collection.
+- **Form** — a contact/feedback form in a site; `draft` or `published`. Published forms accept **public** submissions without auth.
+- **Form Submission** — visitor-submitted data; read-only after creation.
+- **Media** — files attached to a site via the Spatie Media Library.
+
+## Phase 1 — Configure content via the MCP server
+
+Connect once, then drive the tools. Minimal connect with a Personal Access Token (Claude Code shown):
+
+```bash
+claude mcp add crafty \
+  --transport http \
+  --url https://<your-tenant-domain>/mcp \
+  --header "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN"
+```
+
+The server URL is **per-tenant**: `https://<your-tenant-domain>/mcp`. Tokens carry scopes — `crafty:read`, `crafty:write`, `crafty:publish`, and `crafty:submissions` (reading form submissions, which may contain personal data) — and they are **enforced per tool** (a tool without its scope is hidden and errors if called). Request the scopes the agent needs. **Full connection guide for every client (PAT and OAuth), scopes, and the complete 25-tool catalog: read `references/mcp-configuration.md`.**
+
+Canonical authoring workflow (exact tool names):
+
+1. `list_sites` → pick a `site_id` (or `create_site`).
+2. `list_block_types` → learn the available block types and their data schemas.
+3. `create_page` with `site_id`, `title`, and optional `blocks: [{ block_type_id, data }]`.
+4. `publish_page`.
+
+Collections/entries: `list_collections` → `create_entry` (`collection_slug`, `site_id`, `slug`, `data`) → `update_entry` (snapshots a revision).
+Forms: `create_form` (`site_id`, `name`, `slug`, `fields`) → `publish_form` → `list_form_submissions`.
+Media: `upload_media` (`url`, `site_id`, optional `collection_name`).
+
+> `update_page` **replaces all blocks** when `blocks` is supplied. `update_entry` creates a revision. `create_page` always starts as `draft`.
+
+## Phase 2 — Build a frontend with the SDK
+
+```bash
+npm install @craftware/crafty-sdk
+```
+
+```ts
+import { createCraftyClient } from "@craftware/crafty-sdk";
+
+const crafty = createCraftyClient({
+  baseUrl: "https://<your-tenant>.crafty.do", // SDK appends /api/v1
+  apiKey: process.env.CRAFTY_API_KEY,         // environment API token (sent as X-API-Key)
+  siteSlug: "main-site",                      // required ONLY for forms.submit()
+});
+
+// pages are scoped by the site the apiKey resolves to — no siteSlug argument
+const page = await crafty.pages.get("home");
+const hero = page.block("hero");          // first block of that type, or null
+const posts = await crafty.entries.list("posts", { per_page: 15 });
+```
+
+`pages.get()` returns the page enriched with block helpers (`page.block(type)`, `page.blocksOf(type)`, `page.byType`, …). **Full client config, every resource and return shape, block helpers, errors, and an end-to-end example: read `references/sdk-development.md`.**
+
+## Phase 3 — Deploy a static site with the CLI
+
+```bash
+npm install -D @craftware/crafty-cli
+```
+
+Add to `.env` (the CLI reads this at deploy time, separate from `VITE_*` vars):
+
+```
+CRAFTY_API_URL=https://<your-tenant>.crafty.do/api/v1
+```
+
+Add `crafty.json` at the project root:
+
+```json
+{ "site": "<site-slug>", "environment": "production", "buildDir": "dist" }
+```
+
+Then build and deploy:
+
+```bash
+npm run build   # produces dist/
+crafty deploy   # uploads dist/ to the configured environment
+```
+
+> `crafty.json` is safe to commit. `.env` (which contains your API key) must be gitignored — use `.env.example` with placeholder values.
+
+## Key distinction: MCP auth vs SDK API key
+
+These are two different credentials — do not mix them:
+
+- **MCP** uses a **Bearer** token (Personal Access Token or OAuth access token) with `crafty:*` scopes. Used by an agent/editor to *author* content.
+- **SDK** uses an **environment API token** sent as the `X-API-Key` header. It resolves the site + environment server-side, so `pages.*` need no `siteSlug`. Used by app code to *read* published content.
+
+## Common pitfalls
+
+- **Wrong tenant host** → the MCP endpoint won't resolve. Use the exact `https://<tenant-domain>/mcp`; each tenant has its own endpoint.
+- **401 from the MCP server** → the Bearer token is missing, invalid, or expired; reconnect or regenerate it.
+- **A tool is missing or fails with "Insufficient OAuth scope"** → the token lacks that tool's scope; re-issue it with `crafty:write` / `crafty:publish` / `crafty:submissions` as needed.
+- **`forms.submit()` throws `BAD_REQUEST`** → `siteSlug` was not set in `createCraftyClient()`. Submissions hit the public endpoint and deliberately omit the API key.
+- **`update_entry` / `update_page` wipe fields you don't send** → both MCP tools do a **full replace**, not a merge. If you send only the new fields, all existing fields are deleted in that revision. Always fetch the current entry first (`get_entry`), merge your changes into the full field map, then call `update_entry` with the complete merged object.
+- **Content not visible via the SDK** → it isn't published. Pages/forms must be published (`publish_page` / `publish_form`).
+- **Confusing the two tokens** → the SDK `apiKey` (X-API-Key) is not an MCP Bearer token.
+
+## References
+
+- `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.

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

@@ -0,0 +1,183 @@
+# Configuring Crafty via the MCP server
+
+Use this when an agent should **author and configure** content in a Crafty tenant: sites, pages/blocks, collections/entries, forms, media, and publishing.
+
+## Server URL
+
+The MCP endpoint is **per-tenant** and lives at the `/mcp` path on the tenant's own domain:
+
+```
+https://<your-tenant-domain>/mcp
+```
+
+The tenant is identified by the request **host**, so each tenant has its own endpoint. Hitting the wrong host fails to resolve the tenant. Every request must be authenticated (Bearer token).
+
+## Authentication
+
+Two families, both carrying a **Bearer** token on every request:
+
+### Personal Access Token (PAT) — simplest
+
+Generate a long-lived Personal Access Token from your Crafty profile, choosing the scopes you need, then paste it into the editor config as an `Authorization: Bearer …` header. Best for CLIs and local setups. Regenerate and update the config if it stops working.
+
+### OAuth 2.0 — via an MCP client
+
+Create an "MCP client" in your Crafty profile and pick a grant type:
+
+- **Authorization Code** — standard browser-redirect flow for tools that open a browser (Claude.ai, Cursor, VS Code). Select the redirect URI matching your tool.
+- **Device Code (RFC 8628)** — for CLIs that can't open a browser; the editor shows a code in the terminal that you approve in the browser.
+
+When you create the client manually in your profile you are shown the `client_id` and a **one-time** `client_secret` — copy it immediately (PATs likewise show the token once). Clients that **auto-register** through discovery (e.g. Claude.ai, Cursor) are registered as public clients and receive no client secret.
+
+OAuth clients that support MCP auto-discovery (Claude.ai, Cursor) can find everything from the server URL alone: discovery is published at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, with `authorization_endpoint` `/oauth/authorize`, `token_endpoint` `/oauth/token`, dynamic `registration_endpoint` `/oauth/register`, PKCE (`S256`), and grants `authorization_code` + `refresh_token`. These OAuth endpoints live at the tenant **root**, not under `/mcp`.
+
+## Scopes
+
+When you create a token (PAT or OAuth client) you grant one or more scopes. Scopes are **enforced per tool**: a tool is only advertised when your token carries its required scope, and invoking one without the scope fails with an MCP error (`Insufficient OAuth scope`). Grant the scopes the agent needs:
+
+| Scope | Unlocks | Tools |
+|---|---|---|
+| `crafty:read` | Read sites, pages, block types, collections, entries, media, and form definitions | all `list_*` / `get_*` except form submissions |
+| `crafty:write` | Create and update sites, pages, entries, media, and forms | all `create_*` / `update_*`, `upload_media` |
+| `crafty:publish` | Publish and unpublish pages and forms | `publish_page`, `unpublish_page`, `publish_form`, `unpublish_form` |
+| `crafty:submissions` | Read form submissions (may contain personal data) | `list_form_submissions`, `get_form_submission` |
+
+Request all four for full authoring plus submission access. Scopes are also advertised in OAuth discovery; the `/mcp` endpoint additionally requires a valid authenticated token on every request.
+
+## Connecting each client
+
+Replace `https://<tenant>/mcp` with your tenant URL and `YOUR_PAT` with a Personal Access Token.
+
+**Claude.ai (Authorization Code):** create an Authorization Code MCP client with redirect URI `https://claude.ai/api/mcp/auth_callback`; in Claude.ai go to **Settings → Integrations → Add integration**, enter the server URL, and authorize in the browser.
+
+**Claude Code (CLI):**
+
+```bash
+# Option A — PAT
+claude mcp add crafty --transport http \
+  --url https://<tenant>/mcp \
+  --header "Authorization: Bearer YOUR_PAT"
+
+# Option B — Device Code (create a Device Code MCP client first)
+claude mcp add crafty --transport http \
+  --url https://<tenant>/mcp \
+  --oauth2 device_code \
+  --client-id YOUR_CLIENT_ID \
+  --client-secret YOUR_CLIENT_SECRET
+```
+
+**Cursor (Authorization Code):** create an Authorization Code client with redirect URI `cursor://anysphere.cursor-deeplink/mcp/auth_callback`, then add to `~/.cursor/mcp.json` and authorize when prompted:
+
+```json
+{ "mcpServers": { "crafty": { "url": "https://<tenant>/mcp" } } }
+```
+
+**VS Code (GitHub Copilot, PAT):** add to `.vscode/mcp.json`, then open Copilot Chat → **Agent** mode and select the Crafty tools. (OAuth alternative: Authorization Code client with redirect URI `vscode://github.copilot-chat/mcp/auth_callback`.)
+
+```json
+{ "servers": { "crafty": { "type": "http", "url": "https://<tenant>/mcp",
+  "headers": { "Authorization": "Bearer YOUR_PAT" } } } }
+```
+
+**Codex CLI (`~/.codex/config.yaml`):**
+
+```yaml
+# Option A — PAT
+mcp_servers:
+  crafty:
+    type: sse
+    url: https://<tenant>/mcp
+    headers:
+      Authorization: "Bearer YOUR_PAT"
+# Option B — Device Code: add
+#   auth: { type: device_code, client_id: ..., client_secret: ...,
+#           token_url: https://<tenant>/oauth/token,
+#           device_authorization_url: https://<tenant>/oauth/device/code }
+```
+
+**ChatGPT (Authorization Code, Plus/Pro/Enterprise):** create an Authorization Code client with redirect URI `https://chatgpt.com/aip/g-*/oauth/callback`; in **Explore GPTs → Create → Configure → Actions** enter the server URL and configure OAuth with Authorization URL `/oauth/authorize` and Token URL `/oauth/token`.
+
+## Tool catalog
+
+All tools return a JSON text response. IDs are integers; slugs are strings. Pagination defaults to 25 per page (`per_page` max 100 where supported).
+
+### Read (`crafty:read`)
+
+| Tool | Required | Optional | Returns |
+|---|---|---|---|
+| `list_sites` | — | — | all sites (id, name, slug, domain, is_active) |
+| `get_site` | `site_id` | — | one site |
+| `list_pages` | `site_id` | `status` (`draft`/`published`) | paginated pages, ordered by title |
+| `get_page` | `page_id` | — | page with its blocks (incl. block types) |
+| `list_block_types` | — | — | all block types and their schemas |
+| `list_collections` | — | `site_id` | active collections |
+| `list_entries` | `collection_slug` | `site_id`, `per_page` | paginated entries (newest id first) |
+| `get_entry` | `entry_id` | — | one entry with its collection |
+| `list_media` | `site_id` | `collection`, `per_page` | paginated media for the site |
+| `list_forms` | — | `site_id`, `status`, `per_page` | paginated forms, ordered by name |
+| `get_form` | `form_id` | — | one form with its field definitions |
+
+### Submissions (`crafty:submissions`)
+
+Form submissions may contain personal data, so they require their own scope.
+
+| Tool | Required | Optional | Returns |
+|---|---|---|---|
+| `list_form_submissions` | `form_slug` | `site_id`, `per_page` | paginated submissions, newest first |
+| `get_form_submission` | `form_slug`, `submission_id` | `site_id` | one submission with its data |
+
+### Write (`crafty:write`)
+
+| Tool | Required | Optional | Notes |
+|---|---|---|---|
+| `create_site` | `name` | `slug` | slug auto-generated from name; returns the site (with a generated `api_token`) |
+| `create_page` | `site_id`, `title` | `slug`, `blocks` | starts as `draft`; `blocks: [{ block_type_id, data }]` created in order |
+| `update_page` | `page_id` | `title`, `slug`, `blocks` | **if `blocks` is supplied, ALL existing blocks are replaced** |
+| `create_entry` | `collection_slug`, `site_id`, `slug` | `data` | `data` = field key/value pairs |
+| `update_entry` | `entry_id`, `data` | `slug` | snapshots the prior data into a new revision |
+| `upload_media` | `url`, `site_id` | `collection_name` (default `library`), `file_name` | downloads the file from the URL |
+| `create_form` | `site_id`, `name`, `slug` | `description`, `fields` | `fields: [{ key, type, label, required? }]`; starts as `draft` |
+| `update_form` | `form_id` | `name`, `slug`, `description`, `fields`, `notification_emails` | only supplied fields change; `fields`/`notification_emails` replace |
+
+### Publish (`crafty:publish`)
+
+| Tool | Required | Effect |
+|---|---|---|
+| `publish_page` | `page_id` | status → `published`, sets `published_at` |
+| `unpublish_page` | `page_id` | status → `draft`, clears `published_at` |
+| `publish_form` | `form_id` | status → `published` (now accepts public submissions) |
+| `unpublish_form` | `form_id` | status → `draft` (stops accepting submissions) |
+
+## Canonical workflows
+
+**Build and publish a page**
+
+1. `list_sites` → choose a `site_id` (or `create_site`).
+2. `list_block_types` → note each `id` and its data schema.
+3. `create_page` with `site_id`, `title`, and `blocks: [{ block_type_id, data }, …]`.
+4. `publish_page` with the returned `page_id`.
+
+**Structured content**
+
+1. `list_collections` (optionally `site_id`) → pick a `collection_slug`.
+2. `create_entry` with `collection_slug`, `site_id`, `slug`, and `data`.
+3. `update_entry` to edit (each edit stores a revision).
+
+**Forms**
+
+1. `create_form` with `site_id`, `name`, `slug`, and `fields`.
+2. `publish_form` so it accepts public submissions.
+3. `list_form_submissions` / `get_form_submission` to read what visitors sent.
+
+**Media**
+
+1. `upload_media` with `url` and `site_id` (optionally `collection_name`).
+2. `list_media` to confirm and retrieve URLs.
+
+## Troubleshooting
+
+- **401 / authentication error** — the Bearer token is missing, invalid, or expired; reconnect or regenerate it. Every `/mcp` request must carry a valid token.
+- **A tool is missing, or fails with `Insufficient OAuth scope`** — the token lacks that tool's scope. Tools are only advertised when the token carries the matching scope (`crafty:write` to create/edit, `crafty:publish` to publish, `crafty:submissions` to read form submissions). Re-issue the token with the scopes you need.
+- **Tenant not found** — wrong host; use the exact tenant domain. OAuth token endpoints are at the tenant root (`/oauth/...`), not under `/mcp`.
+- **Device code never appears** — the MCP client must be created as type **Device Code**, with matching `client_id`/`client_secret`.
+- **Token/secret lost** — `client_secret` and PATs are shown only once at creation; regenerate if lost.

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

@@ -0,0 +1,198 @@
+# Developing with `@craftware/crafty-sdk`
+
+Use this when writing application code that **reads published Crafty content** (pages/blocks, entries, collections, media) or **submits forms**. Authoring/configuration is done via the MCP server (see `mcp-configuration.md`), not the SDK.
+
+## Install
+
+```bash
+npm install @craftware/crafty-sdk
+```
+
+Requires Node `>=20`, or any runtime with `fetch` (browser, Bun, Deno, modern edge runtimes).
+
+## Create a client
+
+```ts
+import { createCraftyClient } from "@craftware/crafty-sdk";
+
+const crafty = createCraftyClient({
+  baseUrl: "https://<your-tenant>.crafty.do",
+  apiKey: process.env.CRAFTY_API_KEY,
+  siteSlug: "main-site",
+  timeoutMs: 10_000,
+});
+```
+
+`createCraftyClient(config)` returns a plain object with six resources: `collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`.
+
+### Config options
+
+| Option | Required | Notes |
+|---|---|---|
+| `baseUrl` | **yes** | Tenant base URL. Trailing slashes are stripped; `/api/v1` is appended automatically unless already present. |
+| `apiKey` | no | Environment API token. Sent as `X-API-Key`. Resolves the site + environment server-side, so `pages.*` need no `siteSlug`. |
+| `siteSlug` | no | Site slug. **Required for `forms.submit()`** (the public submit path is `/sites/{siteSlug}/forms/{formSlug}/submit`). |
+| `fetch` | no | Custom fetch. Defaults to `globalThis.fetch`. If none is available, construction throws `CraftyError` (`NETWORK_ERROR`). |
+| `headers` | no | Default headers merged into every request. |
+| `timeoutMs` | no | Default per-request timeout. A timeout is only armed when the value is a number `> 0`. |
+
+## Per-call options
+
+Every method takes an optional final `options` argument:
+
+- `signal: AbortSignal` — merged with the internal timeout signal.
+- `headers: HeadersInit` — merged over the client's default headers.
+- `timeoutMs: number` — overrides the client timeout for this call.
+
+```ts
+const posts = await crafty.entries.list(
+  "posts",
+  { per_page: 15, page: 1, sort_by: "updated_at", sort_order: "desc" },
+  { timeoutMs: 5_000 }
+);
+```
+
+## Resources
+
+### `collections`
+
+```ts
+crafty.collections.list(options?)        // => { data: CraftyCollection[] }
+crafty.collections.get(slug, options?)   // => CraftyCollection   (BARE object, not wrapped)
+```
+
+### `entries`
+
+```ts
+crafty.entries.list(collectionSlug, query?, options?)  // => { data: CraftyEntry[], links, meta }  (paginated)
+crafty.entries.get(collectionSlug, id, options?)       // => { data: CraftyEntry }
+```
+
+`query`: `sort_by`, `sort_order` (`asc`/`desc`), `per_page`, `page`, plus any extra key/value filters passed through to the API.
+
+### `pages`
+
+```ts
+crafty.pages.list(query?, options?)   // => { data: CraftyPage[], links, meta }  (paginated)
+crafty.pages.get(pageSlug, options?)  // => enriched page (see below)
+```
+
+Pages are scoped server-side by the site the `apiKey` resolves to — there is **no `siteSlug` argument**. `query` accepts `per_page` and `page`.
+
+`pages.get()` resolves to `{ data: CraftyPage }` **plus** block helpers:
+
+| Helper | Returns |
+|---|---|
+| `page.blocks` | `CraftyBlock[]` (all blocks; non-array data coerced to `[]`) |
+| `page.block(type)` | first block of `type`, or `null` |
+| `page.blocksOf(type)` | all blocks of `type` (`[]` if none) |
+| `page.hasBlock(type)` | `boolean` |
+| `page.requireBlock(type)` | first block, or **throws a plain `Error`** (`Crafty page block not found: …`) — not a `CraftyError` |
+| `page.byType` | `Record<type, CraftyBlock[]>` |
+| `page.firstByType` | `Record<type, CraftyBlock \| null>` |
+| `page.data` | the raw `CraftyPage` |
+
+```ts
+const landing = await crafty.pages.get("landing");
+const hero = landing.block("hero");                 // CraftyBlock | null
+const features = landing.blocksOf("feature");       // CraftyBlock[]
+const cta = landing.requireBlock("cta");            // throws plain Error if absent
+```
+
+### `forms`
+
+```ts
+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, no apiKey)
+```
+
+`forms.submit()` uses a **public** endpoint: it sends no `X-API-Key`, but it **requires `siteSlug` in the client config** — calling it without one throws a synchronous `CraftyError` with code `BAD_REQUEST`.
+
+```ts
+const crafty = createCraftyClient({
+  baseUrl: "https://<your-tenant>.crafty.do",
+  siteSlug: "main-site", // required for submit()
+});
+
+const result = await crafty.forms.submit("contact", {
+  name: "Jane Doe",
+  email: "jane@example.com",
+  message: "Hello!",
+});
+// => { id, form_id, submitted_at }
+```
+
+> Note the asymmetry: `collections.get()` returns the bare object, while `forms.get()` and `entries.get()` are wrapped in `{ data }`.
+
+### `mediaCollections`
+
+```ts
+crafty.mediaCollections.list(query?, options?)  // => { data: CraftyMediaCollection[], meta: { includes } }
+```
+
+`query.include` accepts `"stats"`, `"directories"`, or an array of them (de-duplicated and serialized comma-separated).
+
+### `mediaFiles`
+
+```ts
+crafty.mediaFiles.list(query?, options?)  // => { data: CraftyMediaFile[], links, meta: { ...pagination, ttl_minutes } }
+```
+
+`query`: `collection`, `directory_id`, `ttl_minutes` (signed-URL lifetime), `per_page`, `page`.
+
+## Error handling
+
+The SDK throws `CraftyError` for HTTP, timeout, abort, network, and config failures.
+
+```ts
+import { CraftyError } from "@craftware/crafty-sdk";
+
+try {
+  await crafty.pages.get("home");
+} catch (error) {
+  if (error instanceof CraftyError) {
+    console.error(error.code, error.status, error.message, error.requestId);
+  }
+}
+```
+
+Codes: `NETWORK_ERROR`, `TIMEOUT`, `BAD_REQUEST` (HTTP 400 **and** 422), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404), `RATE_LIMITED` (429), `SERVER_ERROR` (5xx), `UNKNOWN_ERROR` (any other / unmapped status). `error.requestId` is populated when the API returns an `x-request-id` header.
+
+> `page.requireBlock()` throws a plain `Error`, not a `CraftyError` — handle it separately.
+
+## End-to-end example
+
+```ts
+import { createCraftyClient, CraftyError } from "@craftware/crafty-sdk";
+
+const crafty = createCraftyClient({
+  baseUrl: "https://<your-tenant>.crafty.do",
+  apiKey: process.env.CRAFTY_API_KEY,
+  siteSlug: "main-site",
+  timeoutMs: 10_000,
+});
+
+const home = await crafty.pages.get("home");
+const hero = home.block("hero");
+
+const { data: posts } = await crafty.entries.list("posts", { per_page: 15, sort_order: "desc" });
+const { data: collections } = await crafty.collections.list();
+
+const media = await crafty.mediaCollections.list({ include: ["stats", "directories"] });
+const files = await crafty.mediaFiles.list({ collection: "library", per_page: 24 });
+
+try {
+  await crafty.forms.submit("contact", { name: "Jane", email: "jane@test.com" });
+} catch (e) {
+  if (e instanceof CraftyError && e.code === "BAD_REQUEST") {
+    // missing siteSlug, or validation failed
+  }
+}
+```
+
+## Notes
+
+- `Accept: application/json` is set automatically unless overridden.
+- `baseUrl` is normalized so `/api/v1` is never duplicated.
+- The `apiKey` (`X-API-Key`) is an **environment** token and is distinct from the **Bearer** tokens used for the MCP server.