SDK reference

db import { db } from 'hatchable'

Postgres for your project. Raw SQL — agents are good at it, the skills port everywhere. Each project gets its own database.

import { db } from 'hatchable';

// SELECT
const r = await db.query('SELECT id, email FROM users WHERE active = $1', [true]);
// → { rows: [{ id, email }, …], rowCount: 12 }

// INSERT … RETURNING — get the id back without a second round trip
const ins = await db.query(
  'INSERT INTO posts (title, body) VALUES ($1, $2) RETURNING id',
  [title, body],
);
const postId = ins.rows[0].id;

// Atomic multi-statement
await db.transaction([
  { sql: 'INSERT INTO orders (user_id, amount) VALUES ($1, $2) RETURNING id', params: [u.id, 99] },
  { sql: 'INSERT INTO order_items (order_id, sku) VALUES ($1, $2)',            params: [42, 'tee-l'] },
]);

knowledge import { knowledge } from 'hatchable'

RAG-shaped storage on top of pgvector. Declare a knowledge base by name, add items with text + metadata, search by query. Embeddings are computed for you via the ai module's embed model. Backed by pgvector on this project's own Postgres DB.

const docs = knowledge.base('articles', { dimensions: 1536 });
await docs.add([
  { id: 'p1', text: 'How do I deploy?', metadata: { kind: 'help' } },
  { id: 'p2', text: 'Setting up auth',   metadata: { kind: 'guide' } },
]);
const hits = await docs.search('how do I ship to prod', { topK: 5 });

For builder-curated content (docs, FAQ, manuals), populate via the console's Knowledge tab — paste text or upload .txt / .md / .markdown files. Same _hv_* tables underneath; agent code's search() doesn't care which way the content got there. Declare what you expect with [[knowledge]] blocks in hatchable.toml.

storage import { storage } from 'hatchable'

Object storage backed by S3. The bucket is fully private — every read goes through a short-lived presigned URL minted by storage.put or storage.url, or via storage.get in your handler. There is no permanent public URL.

// Save an upload — store the key, hand the browser a fresh signed URL on render
const bytes = new Uint8Array(await req.body.arrayBuffer());
const key = `uploads/${user.id}/${crypto.randomUUID()}.png`;
await storage.put(key, bytes, 'image/png');
await db.query('INSERT INTO uploads (user_id, storage_key) VALUES ($1, $2)', [user.id, key]);

// Later — render a list with fresh URLs every request
const rows = (await db.query('SELECT storage_key FROM uploads WHERE user_id = $1', [user.id])).rows;
const urls = await Promise.all(rows.map(r => storage.url(r.storage_key)));

Route access & caller identity

You never build a login form, session, or users table — the platform owns identity. Every route declares export const access, and the platform edge authenticates the caller and enforces the gate before your handler runs. Inside the handler you read who's calling; you don't re-check it for authorization, the edge already did.

// Require a signed-in collaborator, then scope to them:
export const access = 'member';

export default async function (req, res) {
  const member = req.member;   // guaranteed present on a gated route; the edge verified it
  const { rows } = await db.query('SELECT * FROM notes WHERE author_id = $1', [member.id]);
  res.json(rows);
}

On 'public' routes req.member may be null — treat that as an anonymous visitor and vary the response, don't throw. The platform sets req.member server-side (the browser can't forge it), so it's safe to trust. The /api/auth/* namespace is reserved by the platform — files under api/auth/ are rejected at deploy. See the config reference.

admin import { admin } from 'hatchable'

Project-owner recognition via the platform's hatchable_session cookie. Use this to gate /admin/* routes inside your app to the project owner. Distinct from access: 'member': a member gate admits any signed-in collaborator, while admin answers the narrower question "is this specifically the owner/operator?"

// Owner-only dashboard route
import { admin, db } from 'hatchable';

export default async function (req, res) {
  const allowed = await admin.require(req, res);
  if (!allowed) return;     // require() already wrote 302/403

  const rows = await db.query('SELECT * FROM waivers ORDER BY signed_at DESC');
  res.json({ waivers: rows.rows });
}

config import { config } from 'hatchable'

One read API for everything declared in hatchable.toml: buyer-editable settings from [[config]] blocks (Configure tab) and sensitive values from [[secret]] blocks (gate-pasted). Walks config → user → project → account → manifest default server-side and returns the first hit.

// [[config]] — buyer-editable, non-sensitive (lowercase snake_case keys)
import { config } from 'hatchable';

const displayName = await config.get('display_name');   // "Welcome" (default) or the buyer's saved value
const accent      = await config.get('accent_color');   // "#f5b840" or the saved hex
const links      = await config.get('links');          // array — JSON round-trips through one column

// [[secret]] — sensitive, gate-pasted (UPPER_SNAKE_CASE keys by convention)
const model = await config.get('DEFAULT_MODEL');     // returns the manifest default if no override

// The [ai] capability is account-scoped — the buyer's own Anthropic /
// OpenAI / Google key is used regardless of which collaborator is signed in.
// asUser on ai.generateText is for usage-tracking (llm_calls.user_id) only.
const reply = await ai.generateText({ asUser: member.id, model, prompt });

env import { env } from 'hatchable'

Programmatic writes to project-tier and account-tier secret values from inside an authed app handler. Use this for OAuth callbacks ("user just authorized our Stripe Connect; save the connected-account id"), in-app setup wizards, and batch imports — anything where the value is computed at runtime rather than pasted by a human. Reads are still via config.get.

// Stripe Connect callback — capture the connected-account id at runtime
import { env } from 'hatchable';

export const access = 'admin';   // owner-only config flow

export default async function (req, res) {
  const { account_id } = await exchangeCodeForAccount(req.query.code);
  await env.set('STRIPE_CONNECTED_ACCOUNT', account_id);

  res.redirect('/dashboard?connected=1');
}

ai import { ai } from 'hatchable'

Provider-agnostic LLM access. Provider-family aliases, provider-prefixed names, and raw model ids all resolve to the same call shape. The gateway routes to whatever provider the project (or end-user) has a key for. Vercel-AI-SDK-shaped — same input shape, same return fields.

ai.fetch — escape hatch for any provider endpoint

When you need an endpoint generateText / streamText / embed doesn't cover — image generation, audio, files, batches, prompt-caching tuning, anything new — call ai.fetch. The gateway resolves the same [ai] capability key, injects auth, forwards the request, and logs the call to ai_raw_calls. Your code never sees the key.

// Generate an image (Gemini)
const r = await ai.fetch({
  provider: 'google',
  path: '/v1beta/models/gemini-2.5-flash-image-preview:generateContent',
  body: {
    contents: [{ parts: [{ text: prompt }] }],
    generationConfig: { responseModalities: ['IMAGE'] },
  },
  purpose: 'generate-image',
});
const data = await r.json();
const inline = data.candidates[0].content.parts.find(p => p.inlineData).inlineData;
// inline.data is the base64-encoded image. Stash in storage, return URL, etc.

Method gating: GET / POST work without ceremony. PUT / DELETE / PATCH require dangerous: true on the call — catches accidental destructive calls.

Two body shapes: pass body for JSON, or pass fields + files for multipart uploads (OpenAI Files API, Whisper, DALL-E edits, Anthropic Files API). The gateway assembles the multipart envelope server-side. files[i].data accepts Uint8Array, ArrayBuffer, or a base64 string. 50 MB total cap per call. Streaming responses still pending. Full skill: use a provider directly.

Two input shapes

// Single-user-message shortcut — most common case.
const { text } = await ai.generateText({
  model: 'haiku',
  prompt: 'Summarize this article: ...',
  system: 'Be concise.',
  purpose: 'summarize',    // optional — auto-logs to llm_calls when set
});

// Full multi-turn — pass when you have a conversation history.
const { text } = await ai.generateText({
  model: 'sonnet',
  messages: [
    { role: 'user', content: 'Hi' },
    { role: 'assistant', content: 'Hello!' },
    { role: 'user', content: 'How are you?' },
  ],
});

Pass prompt OR messages, not both. Errors out otherwise.

Model resolution — three forms

// 1. Provider-family alias — RECOMMENDED. One mapping per branded
//    line; the platform updates the underlying model when a new
//    generation ships. Templates stay portable.
await ai.generateText({ model: 'sonnet',       prompt });   // Anthropic mid-tier (Sonnet)
await ai.generateText({ model: 'haiku',        prompt });   // Anthropic small/fast (Haiku)
await ai.generateText({ model: 'opus',         prompt });   // Anthropic strongest (Opus)
await ai.generateText({ model: 'gpt',          prompt });   // OpenAI general (GPT-4o)
await ai.generateText({ model: 'gpt-mini',     prompt });   // OpenAI small/fast
await ai.generateText({ model: 'gemini',     prompt });   // Google small/fast (default — Gemini Flash)
await ai.generateText({ model: 'gemini-pro', prompt });   // Google flagship (Gemini Pro)

// 2. Provider-prefixed — pin to a specific provider. Use when you
//    explicitly compare providers, or rely on a model's quirks.
await ai.generateText({ model: 'anthropic.sonnet',    prompt });
await ai.generateText({ model: 'openai.gpt',         prompt });
await ai.generateText({ model: 'google.gemini',      prompt });

// 3. Raw provider model id — passes through verbatim, locks you
//    to that exact version. Avoid unless you have a specific reason.
await ai.generateText({ model: 'claude-sonnet-4-5-20250929', prompt });

// 4. No model field — uses AI_DEFAULT_MODEL configured in Setup,
//    or falls through to the family alias of whichever provider
//    the user has a key for.
await ai.generateText({ prompt });

Tool calling — return tool calls for the caller to handle

const { toolCalls } = await ai.generateText({
  model: 'sonnet',
  prompt: "What's the weather in Paris?",
  tools: {
    get_weather: {
      description: 'Returns current weather for a city',
      inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
    },
  },
});
for (const tc of toolCalls) {
  // tc = { id, name: 'get_weather', input: { city: 'Paris' } }
  // Run the tool, push the result back if you want a continuation.
}

Auto-loop — runtime drives tool calls until the model is done

// Add `execute` functions and set maxSteps > 1.
const { text, steps } = await ai.generateText({
  model: 'sonnet',
  prompt: "What's the weather in SF and Tokyo?",
  tools: {
    get_weather: {
      description: 'Returns current weather for a city',
      inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
      execute: async ({ city }) => {
        const r = await fetch(`https://api.weather.com/...?q=${city}`);
        return await r.json();
      },
    },
  },
  maxSteps: 10,
  purpose: 'weather',
});
// text  = "It's 65°F in SF and 50°F in Tokyo..."
// steps = full per-step trace for observability

Tracking calls per caller (usage analytics)

const member = req.member;
await ai.generateText({
  model: 'sonnet',
  prompt,
  userId: member.id,    // labels the llm_calls row for per-caller usage / billing
  asUser: member.id,    // alias for userId (kept for back-compat). Both run against
                         // the project owner's key — SDK calls don't switch keys per caller.
  purpose: 'chat',
});

Streaming

const stream = await ai.streamText({
  model: 'sonnet',
  prompt,
  tools,                  // optional; same shape as generateText
  maxSteps: 10,           // optional; agent loop in stream form
  purpose: 'chat-stream',
});

for await (const ev of stream) {
  // ev.type: 'token' | 'tool_call_start' | 'tool_call_delta' |
  //          'tool_call_complete' | 'final'
  if (ev.type === 'token') res.write(ev.text);
}

See Secrets architecture for the full provider catalog, tier-to-model mapping, and the gateway resolution flow.

scheduler import { scheduler } from 'hatchable'

Cron-style recurring jobs and one-shot future invocations. Both end up calling one of your api/* routes.

// Recurring — every hour
await scheduler.at("0 * * * *", "/api/nightly-report");

// One-shot at a specific moment
await scheduler.at("2026-05-01T07:00:00Z", "/api/book", {
  payload: { missionId: 42 },
});

// Idempotent named arm — repeated calls update in place
await scheduler.at("0 9 * * *", "/api/daily-digest", { name: "daily-digest" });

email import { email } from 'hatchable'

Transactional email. Routed through the platform's SMTP — no provider account, no API keys, no DNS. Just call email.send(...).

mcp tools mcp/<name>.js + [mcp] enabled = true

Expose your project's logic to AI clients (Claude, ChatGPT, Cursor) via the Model Context Protocol. The user authorizes once via OAuth on hatchable.com; their AI client then calls your tools directly. Works on private/personal projects — visibility doesn't matter, the OAuth grant is the access check.

Two pieces: opt in via hatchable.toml, then add one file per tool.

# hatchable.toml
[mcp]
enabled = true

// mcp/list_todos.js — filename MUST equal the exported `name` field.
export default {
  name: 'list_todos',
  description: 'List todos, optionally filtered by status.',
  inputSchema: {
    type: 'object',
    properties: { status: { type: 'string', enum: ['active', 'done'] } },
  },
  async handler(args, ctx) {
    const { rows } = await ctx.db.query(
      'SELECT id, title, status FROM todos WHERE ($1::text IS NULL OR status = $1)',
      [args.status ?? null],
    );
    return { todos: rows };
  },
};

The handler signature is (args, ctx), not (req, res). ctx exposes the full SDK — same db / ai / email / storage / scheduler / config / knowledge / browser / images / tasks that api/*.js handlers get. Return any JSON-serializable value; throw to surface an error.

The MCP endpoint lives at https://<slug>.hatchable.site/mcp. The OAuth flow lives at https://hatchable.com/oauth/<slug>/... and is discovered automatically by any compliant MCP client. Tokens are project-scoped (a grant for project A can't be replayed at project B even on the same account) and revocable from the console's MCP tab.

browser import { browser } from 'hatchable'

Managed Chromium pool. Render a page, screenshot it, generate a PDF, or open a stateful Playwright-shaped session for scraping + multi-step flows.

api import { api } from 'hatchable'

Call third-party HTTP APIs declared in [[api]] (Reddit, Notion, …). The platform runs the OAuth/key connect flow, refreshes credentials, and proxies the request with auth attached — your handler never touches the token. See the config reference for declaring an [[api]].

webhooks import { webhooks } from 'hatchable'

Verify the signature on an inbound webhook. Provider-agnostic by design: the platform owns the security floor (verifies against the raw body, constant-time compare, optional replay window); you supply the provider's header / signed-payload shape from a recipe. See skill integrations/verify-a-webhook for Stripe / GitHub / Shopify / Slack recipes.

// Stripe: header is t=<ts>,v1=<hex>, signs `t.rawBody`
const p = Object.fromEntries(
  (req.headers['stripe-signature'] || '').split(',').map((kv) => kv.split('='))
);
const ok = await webhooks.verifyHmac({
  raw: `${p.t}.${req.rawBody}`, signature: p.v1, secret, timestamp: p.t,
});
if (!ok) return res.status(400).json({ error: 'Invalid signature.' });