@mediamonks/canopy (SDK)

The browser/worker SDK for Canopy projects — the data plane and nothing else (infrastructure stays out of it by design; docs/03-architecture.md).

import { createCanopy } from "/_api/data/v1/sdk.js";
const canopy = createCanopy();

await canopy.db.collection("todos").insert({ text: "hi", done: false });
await canopy.blob.put("avatar.png", file);
await canopy.ai.chat({ messages: [{ role: "user", content: "…" }] });
await canopy.auth.user();

• db — document collections (portable across targets; insert/get/find/update/delete plus per-collection search() — real full-text on SQLite targets, substring fallback on Postgres), and the raw sql() escape hatch (NOT portable: SQL passes through untranslated in the target's own dialect — ask db.dialect() whether you're on "sqlite" or "postgres").
• blob — files on the project's isolated prefix (put/get/list/delete), typed Blob downloads, short-lived signed URLs via getUrl().
• ai — chat(options) / chatStream(options) (options carry messages plus optional model, temperature, maxTokens) and an OpenAI-compatible endpoint(), budget-capped per project by the platform.
• auth — user() / logout().
• services — platform-provided services: list() and get(name).fetch(...).

All paths are built in one place (src/client.ts): ${baseUrl}/data/v1/… with baseUrl defaulting to /_api, so the same code runs on a project host (gateway-scoped), under canopy dev (proxied), and in project workers (env.CANOPY.fetch).

Two distributions, one version

The platform serves the built bundle at /data/v1/sdk.js — always version-matched to the API it fronts, which is what scaffolded projects import. The npm package exists for typed/bundled projects; after a breaking API change npm consumers must update and redeploy (docs/09-plane-split.md §5).

vp pack builds; apps/api/scripts/embed-sdk.mjs embeds the fresh build into canopy-api (always rebuilds — a stale dist must never ship). Publish via the staged workflow (root CLAUDE.md), SDK before CLI.