@craftware/crafty-sdk

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:

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)
• Or any runtime with fetch available (browser, Bun, Deno, etc.)

Create a client

import { createCraftyClient } from "@craftware/crafty-sdk";

const crafty = createCraftyClient({
  baseUrl: "https://tenant.crafty.do",
  apiKey: "ENVIRONMENT_API_TOKEN",
  timeoutMs: 10_000
});

Client config

• baseUrl (required): tenant base URL. The SDK appends /api/v1 automatically if missing.
• 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 (ms) for all requests. A timeout is only applied when the value is a number greater than 0.

Available resources

collections

• crafty.collections.list(options?)
• crafty.collections.get(slug, options?)

entries

• crafty.entries.list(collectionSlug, query?, options?)
• crafty.entries.get(collectionSlug, id, options?)

Supported common query params:

• sort_by (any sortable field, including collection fields like title)
• sort_order (asc | desc)
• per_page
• page
• Additional filters as key/value pairs (passed through to the API)

pages

• crafty.pages.list(query?, options?)
• crafty.pages.get(pageSlug, options?)

pages.* endpoints are scoped by the environment resolved from apiKey.

pages.get() returns a page response enriched with block helpers:

• 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 ([] if none)
• page.hasBlock(type) => boolean
• 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:

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: "[email protected]",
  message: "Hello!",
});
// result => { id, form_id, submitted_at }

mediaCollections

• crafty.mediaCollections.list(query?, options?)

Supported query.include values:

• "stats"
• "directories"
• Array form is supported, de-duplicated, and serialized as comma-separated values; a raw string is passed through unchanged

mediaFiles

• crafty.mediaFiles.list(query?, options?)

Supported common query params:

• collection
• directory_id
• ttl_minutes
• per_page
• page

Request options (per call)

Every method accepts options? as the last argument:

• signal: AbortSignal
• headers: request-specific headers (merged with client headers)
• timeoutMs: overrides client timeout for that call

const posts = await crafty.entries.list(
  "posts",
  { per_page: 15, page: 1, sort_by: "updated_at", sort_order: "desc" },
  { timeoutMs: 5_000 }
);

Responses (current shapes)

• collections.list() => { data: CraftyCollection[] }
• collections.get() => CraftyCollection
• entries.list() => paginated { data, links, meta }
• entries.get() => { data: CraftyEntry }
• pages.list() => paginated { data, links, meta }
• 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, network, and configuration failures (e.g. no fetch implementation available at construction).

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);
    console.error(error.requestId); // if API sent x-request-id
  }
}

Current error codes (with their HTTP-status mapping):

• 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

import { createCraftyClient } from "@craftware/crafty-sdk";

const crafty = createCraftyClient({
  baseUrl: "https://tenant.crafty.do",
  apiKey: process.env.CRAFTY_API_KEY,
  siteSlug: "my-site",
  timeoutMs: 10_000
});

const collections = await crafty.collections.list();
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: "[email protected]" });

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()).

const crafty = createCraftyClient({
  baseUrl: "https://tenant.crafty.do",
  apiKey: "ENVIRONMENT_API_TOKEN",
});

await crafty.pages.list({ per_page: 12 });

const landing = await crafty.pages.get("landing");
const processBlock = landing.block("process");
const allProcessBlocks = landing.blocksOf("process");
const processFirst = landing.firstByType.process;
const processList = landing.byType.process ?? [];

Notes

• The SDK normalizes baseUrl and avoids duplicating /api/v1.
• Accept: application/json is set automatically unless overridden.
• src/types/generated.ts is still a placeholder until OpenAPI codegen is wired.
• Public blockTypes endpoints are not exposed yet; block-related types are currently hand-modeled.