@mediamonks/canopy-cli 0.7.10 → 0.7.12

package/dist/docs/sdk-ai.md

@@ -1,103 +0,0 @@
----
-title: AI
-description: Metered LLM access through the project's budget-capped gateway key — chat, streaming, and an OpenAI-compatible endpoint.
----
-
-`canopy.ai` gives your project LLM access without any API keys in your code.
-Every request authenticates as the project and is metered against a hard
-per-project daily budget — spend and limits are covered in
-[AI access & usage](https://docs.canopy.website/platform/ai-usage).
-
-## ai.chat(options)
-
-One-shot chat completion. Takes a `ChatOptions` object, resolves to a
-`ChatResponse`:
-
-```ts
-const res = await canopy.ai.chat({
-  messages: [
-    { role: "system", content: "You are terse." },
-    { role: "user", content: "Say hi in five words." },
-  ],
-  model: "anthropic/claude-haiku-4-5", // optional
-  temperature: 0.7, // optional, 0–2
-  maxTokens: 256, // optional
-});
-
-res.message.content; // the assistant's reply
-res.model; // the model that actually answered
-res.usage; // { inputTokens: number, outputTokens: number }
-```
-
-**`ChatOptions`:**
-
-- `messages` — required, non-empty array of `{ role, content }`. `role` is
-  `"system" | "user" | "assistant"`; `content` is a non-empty string.
-- `model` — optional `"{provider}/{model}"` id. Omit it and the platform's
-  default model answers. Ask for a model whose provider isn't enabled and the
-  call fails with a message listing what _is_ available; `ai.endpoint()`
-  returns the full curated list.
-- `temperature` — optional number between 0 and 2.
-- `maxTokens` — optional integer, at least 1.
-
-**`ChatResponse`:** `{ message: ChatMessage, model: string, usage: { inputTokens, outputTokens } }`.
-`message.role` is `"assistant"`.
-
-## ai.chatStream(options)
-
-Same `ChatOptions`, but resolves to a `ReadableStream<Uint8Array>` of
-server-sent events — the raw SSE bytes of the completion, for chat-style UIs
-that render tokens as they arrive:
-
-```ts
-const stream = await canopy.ai.chatStream({
-  messages: [{ role: "user", content: "Count to five." }],
-});
-
-const decoder = new TextDecoder();
-let text = "";
-for await (const chunk of stream) {
-  text += decoder.decode(chunk, { stream: true });
-}
-```
-
-Each SSE event is a `data: {...}` line carrying an OpenAI-style completion
-chunk. If you'd rather not parse SSE yourself, use `ai.endpoint()` below and
-let an ecosystem client handle streaming for you.
-
-## ai.endpoint()
-
-Returns the project's OpenAI-compatible endpoint info:
-
-```ts
-const { baseUrl, models } = await canopy.ai.endpoint();
-// baseUrl — an OpenAI-compatible base URL
-// models  — the curated model list, "{provider}/{model}" ids; models[0] is the default
-```
-
-Point any OpenAI-compatible client — the Vercel AI SDK, an OpenAI SDK, a
-tool-calling loop — at `baseUrl`. It uses the same project key and counts
-against the same budget as `ai.chat()`:
-
-```ts
-import { createOpenAI } from "@ai-sdk/openai";
-
-const { baseUrl, models } = await canopy.ai.endpoint();
-const openai = createOpenAI({ baseURL: baseUrl, apiKey: "unused" });
-const model = openai(models[0]);
-```
-
-## Errors
-
-Failed calls throw `CanopyError` with the HTTP `status` and the response body
-as the `message`. Two worth handling:
-
-- **Budget exhausted** — status `429`, body contains
-  `"ai_budget_exceeded"`. The project hit its daily AI cap; AI calls resume
-  the next day (or after a maintainer raises the budget). Everything else in
-  your app keeps working.
-- **Invalid request** — status `400`, body contains `"invalid_chat"` and a
-  detail explaining which option was rejected.
-
-> **Note:** Budgets are enforced before every call, so a runaway loop becomes a capped bill — see [AI access
-> &amp; usage](https://docs.canopy.website/platform/ai-usage) for how spend is tracked and displayed.

package/dist/docs/sdk-auth.md

@@ -1,57 +0,0 @@
----
-title: Auth
-description: Read who the platform signed in — you never build a login screen.
----
-
-Authentication happens before your code runs: the platform gates every request
-to your project, so by the time a page loads or a worker route fires, there is
-always a signed-in user. You never build a login screen, store passwords, or
-check tokens — see [Members and access](https://docs.canopy.website/platform/members-and-access) for
-who gets in and how. `canopy.auth` only reports who the platform let in.
-
-## auth.user()
-
-Returns the authenticated user for the current session as a `CanopyUser`:
-
-```ts
-const user = await canopy.auth.user();
-// { id: "…", email: "ada@monks.com", name: "Ada Lovelace", kind: "monk" }
-```
-
-| Field   | Type                   | Meaning                                                                                                                |
-| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `id`    | `string`               | Stable subject from OneLogin — safe to key user data on.                                                               |
-| `email` | `string`               | The user's email address.                                                                                              |
-| `name`  | `string`               | Display name.                                                                                                          |
-| `kind`  | `"monk" \| "external"` | `"monk"` = signed in through OneLogin; `"external"` = a visitor who got in with the project's client password instead. |
-
-`kind: "external"` sessions come from client-password access — clients viewing
-a shared project without a Monks account. Branch on it when externals should
-see a trimmed-down experience:
-
-```ts
-const user = await canopy.auth.user();
-
-document.querySelector("h1")!.textContent = `Welcome, ${user.name}`;
-
-if (user.kind === "external") {
-  // Client viewer: hide internal tooling, show the presentation view.
-  document.querySelector("#admin-panel")?.remove();
-}
-```
-
-> **Warning:** Branching on `kind` in the browser is presentation, not security — anything your page can fetch, a
-> visitor can fetch. The platform's access rules are what actually protect data.
-
-## auth.logout()
-
-Ends the platform session for the current visitor. Their next request hits the
-login flow again:
-
-```ts
-await canopy.auth.logout();
-location.reload(); // next load re-authenticates
-```
-
-This signs out the browser session only — it does not touch your `canopy login`
-on the CLI.

package/dist/docs/sdk-database.md

@@ -1,126 +0,0 @@
----
-title: Database
-description: Document-style collections on your project's private database, plus a raw SQL escape hatch.
----
-
-Every project has its own private database. The paved road is `canopy.db` —
-document-style collections with no tables to create and no migrations to run.
-Insert a JSON document, get it back with an id and timestamps. For the rare
-case where documents aren't enough, `db.sql()` runs raw SQL against the same
-database.
-
-## Collections
-
-```ts
-const todos = canopy.db.collection<Todo>("todos");
-```
-
-`db.collection<T>(name)` returns a typed `Collection<T>`. The name must be
-lowercase: start with a letter, then letters, digits, and underscores only
-(`^[a-z][a-z0-9_]*$`). Use `snake_case` for multi-word names — `blog_posts`,
-not `blogPosts`. An invalid name throws immediately.
-
-Pass an interface as `T` to type every call end to end:
-
-```ts
-interface Todo extends Record<string, unknown> {
-  title: string;
-  done: boolean;
-}
-
-const todos = canopy.db.collection<Todo>("todos");
-```
-
-Every document you read back is a `Doc<T>` — your own fields plus three
-platform-managed ones:
-
-| Field        | Type     | Meaning                         |
-| ------------ | -------- | ------------------------------- |
-| `_id`        | `string` | Stable document id              |
-| `_createdAt` | `string` | ISO timestamp, set on insert    |
-| `_updatedAt` | `string` | ISO timestamp, bumped on update |
-
-## Writing documents
-
-```ts
-// insert(data: T) → Promise<Doc<T>>
-const created = await todos.insert({ title: "try canopy", done: false });
-created._id; // "…" — use this for get/update/delete
-
-// update(id, patch: Partial<T>) → Promise<Doc<T>>
-await todos.update(created._id, { done: true });
-
-// delete(id) → Promise<void>
-await todos.delete(created._id);
-```
-
-`update` is a merge-patch (RFC 7386): top-level and nested objects merge into
-the existing document, and setting a key to `null` removes it. Fields you
-leave out of the patch are untouched.
-
-## Reading documents
-
-```ts
-// get(id) → Promise<Doc<T> | null> — null when the id doesn't exist
-const one = await todos.get(created._id);
-
-// find(options?) → Promise<Doc<T>[]>
-const open = await todos.find({
-  where: { done: false },
-  orderBy: "_createdAt",
-  order: "desc",
-  limit: 5,
-  offset: 0,
-});
-```
-
-`find` takes a `FindOptions` object; every field is optional (call
-`find()` with no arguments to list everything):
-
-| Option    | Type                      | Meaning                                              |
-| --------- | ------------------------- | ---------------------------------------------------- |
-| `where`   | `Record<string, unknown>` | Filter on document fields, e.g. `{ status: "open" }` |
-| `orderBy` | `string`                  | Field to sort on (your fields or `_createdAt` etc.)  |
-| `order`   | `"asc" \| "desc"`         | Sort direction                                       |
-| `limit`   | `number`                  | Maximum documents to return                          |
-| `offset`  | `number`                  | Documents to skip (pagination)                       |
-
-## Searching text
-
-```ts
-// search(text, options?) → Promise<Doc<T>[]>
-const hits = await todos.search("canopy", { limit: 10 });
-```
-
-`search` matches `text` against the content of every document in the
-collection. On SQLite sites it is real full-text search; on Postgres sites it
-falls back to substring matching — same call, same results shape, slightly
-different ranking. `options` accepts everything `FindOptions` does except
-`where` (`orderBy`, `order`, `limit`, `offset`).
-
-## Raw SQL
-
-```ts
-// dialect() → Promise<"sqlite" | "postgres">
-const dialect = await canopy.db.dialect();
-
-// sql<Row>(query, params?) → Promise<Row[]>
-const rows =
-  dialect === "postgres"
-    ? await canopy.db.sql("SELECT * FROM my_table WHERE id = $1", [42])
-    : await canopy.db.sql("SELECT * FROM my_table WHERE id = ?", [42]);
-```
-
-`db.sql()` runs against the same project database, but it is **not
-portable**: the query passes through untranslated in the deployment's own
-dialect. That means SQLite syntax on some sites and Postgres syntax on
-others — including placeholders, `?` on SQLite versus `$1` on Postgres.
-`db.dialect()` tells you which one you're talking to; the result is cached
-per SDK instance, so calling it often is free.
-
-> **Note:** Reach for collections first — they work identically everywhere your project can deploy. Use
-> `db.sql()` only when you genuinely need SQL (aggregates, joins, bulk updates), and branch on
-> `db.dialect()` whenever the syntax differs.
-
-Where the data lives, snapshots, and how to inspect it from the dashboard are
-covered in [Project data](https://docs.canopy.website/platform/project-data).

package/dist/docs/sdk-files.md

@@ -1,82 +0,0 @@
----
-title: Files
-description: Upload, download, and list files on your project's private blob storage.
----
-
-`canopy.blob` stores files under your project's own isolated prefix. Nothing
-is publicly accessible — every download goes through the platform with the
-visitor's session, or through a short-lived signed URL you request explicitly.
-
-## Uploading
-
-```ts
-// put(key, data, options?) → Promise<BlobObject>
-await canopy.blob.put("notes.txt", "hello canopy", { contentType: "text/plain" });
-await canopy.blob.put("avatars/arjan.png", file); // a File/Blob carries its own type
-```
-
-`data` can be a `Blob` (including a `File`), an `ArrayBuffer`, or a `string`.
-The content type is resolved in order: the explicit `options.contentType`, then
-the `Blob`'s own `type`, then `application/octet-stream`. Keys are plain
-strings — use `/`-separated segments (`avatars/arjan.png`) so related files
-share a prefix you can `list()` later. Putting to an existing key overwrites it.
-
-Every upload (and every `list` entry) is described by a `BlobObject`:
-
-| Field         | Type     | Meaning                      |
-| ------------- | -------- | ---------------------------- |
-| `key`         | `string` | The key you stored it under  |
-| `size`        | `number` | Size in bytes                |
-| `contentType` | `string` | MIME type it was stored with |
-| `uploadedAt`  | `string` | ISO timestamp of the upload  |
-
-## Downloading
-
-```ts
-// get(key) → Promise<Blob | null> — null when the key doesn't exist
-const blob = await canopy.blob.get("notes.txt");
-const text = await blob?.text();
-
-// getUrl(key) → Promise<{ url: string; expiresAt: string }>
-const { url, expiresAt } = await canopy.blob.getUrl("avatars/arjan.png");
-```
-
-`get` returns the content as a standard `Blob`, typed with the MIME type it
-was uploaded with — use `.text()` for text, `.arrayBuffer()` or `.stream()`
-for processing, or `URL.createObjectURL(blob)` for an `<img src>`.
-
-`getUrl` returns a short-lived download URL served through the platform (the
-signature alone grants access, so no cookies are needed). Prefer it when the
-browser should fetch the bytes itself — image `src` attributes, download
-links, media elements — and prefer `get` when your code needs the content.
-Request a fresh URL when you render rather than storing one: it expires at
-`expiresAt`.
-
-## Listing and deleting
-
-```ts
-// list(prefix?) → Promise<BlobObject[]>
-const everything = await canopy.blob.list();
-const avatars = await canopy.blob.list("avatars/");
-
-// delete(key) → Promise<void>
-await canopy.blob.delete("notes.txt");
-```
-
-## Example: upload from a file input
-
-```tsx
-async function onFileChange(event: React.ChangeEvent<HTMLInputElement>) {
-  const file = event.target.files?.[0];
-  if (!file) return;
-
-  const stored = await canopy.blob.put(`uploads/${file.name}`, file);
-  const { url } = await canopy.blob.getUrl(stored.key);
-  setImageUrl(url); // <img src={imageUrl} />
-}
-
-<input type="file" accept="image/*" onChange={onFileChange} />;
-```
-
-Storage location and limits are covered in
-[Project data](https://docs.canopy.website/platform/project-data).

package/dist/docs/sdk-services.md

@@ -1,58 +0,0 @@
----
-title: Services
-description: Curated internal data services, invoked through the platform's connector — auth handled for you.
----
-
-`canopy.services` is the catalog of curated internal data services enabled
-for your project. Calls go through the platform's connector, which handles
-authentication — a service token or on-behalf-of-user credentials, depending
-on the service — so there is nothing to configure in your code.
-
-> **Warning:** Services aren't live yet: the SDK surface below is stable, but the platform currently answers
-> every service call with "not implemented" and no services can be enabled. This page describes what
-> to build against once the first services land.
-
-## services.list()
-
-The services enabled for this project:
-
-```ts
-const available = await canopy.services.list();
-// [{ name: string, description: string }]
-```
-
-The catalog is curated per project — an empty array means no services are
-enabled yet.
-
-## services.get(name)
-
-Returns a `ServiceRef` for a named service. This is a local handle — no
-network call happens until you invoke it:
-
-```ts
-const service = canopy.services.get("example");
-```
-
-## ref.fetch(path, init?)
-
-Invoke a path on the service and get its JSON response back, typed with the
-generic you provide:
-
-```ts
-const pong = await canopy.services.get("example").fetch("/ping");
-
-const report = await canopy.services.get("example").fetch<Report>("/reports/weekly", {
-  method: "POST",
-  body: { week: 33 },
-});
-```
-
-- `path` — the path to invoke on the service, e.g. `"/ping"`.
-- `init.method` — optional HTTP method, defaults to `"GET"`.
-- `init.body` — optional request body, sent as JSON.
-- Returns `Promise<T>` (defaults to `unknown`) — the service's JSON response.
-
-Failed invocations throw `CanopyError` with the HTTP `status`.
-
-> **Note:** Services are for reading and invoking internal Monks data sources the platform has connected — not
-> arbitrary outbound HTTP. For external APIs, use `fetch` directly.

package/dist/docs/sdk.md

@@ -1,126 +0,0 @@
----
-title: Using the SDK
-description: One typed client for auth, data, files, AI, and services — no keys, no connection strings, the platform authenticates for you.
----
-
-`@mediamonks/canopy` is a thin, typed client over the platform's project API.
-One `createCanopy()` call gives you five modules — `auth`, `db`, `blob`, `ai`,
-and `services` — and that is the entire surface. There are no API keys,
-connection strings, or environment variables to manage: every call rides the
-session the platform already established before your code ran.
-
-The same code works everywhere your project runs — in the browser during
-`canopy dev`, in the deployed site, and in a project's backend worker.
-
-## Getting the SDK
-
-You usually don't install anything. The `spa` and `worker` templates ship with
-`@mediamonks/canopy` in `package.json`; the `static` template imports the same
-bundle straight from the platform, untyped but always version-matched to the
-API:
-
-```ts
-// spa / worker templates (typed, from npm)
-import { createCanopy } from "@mediamonks/canopy";
-
-// static template (untyped, served by the platform)
-import { createCanopy } from "/_api/data/v1/sdk.js";
-```
-
-## createCanopy(config)
-
-`createCanopy` takes an optional config object and returns the client:
-
-```ts
-import { createCanopy } from "@mediamonks/canopy";
-
-const canopy = createCanopy();
-// canopy.auth, canopy.db, canopy.blob, canopy.ai, canopy.services
-```
-
-| Option    | Type           | Default        | What it does                                                                                                          |
-| --------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl` | `string`       | `"/_api"`      | Base URL of the platform data API. The default is same-origin, so it works untouched in the browser.                  |
-| `token`   | `string`       | none           | A project-scoped `cnpy_` token sent as a bearer on every request — for scripts and CI running outside Canopy hosting. |
-| `fetch`   | `typeof fetch` | global `fetch` | Override how requests are sent — a backend worker passes its platform service binding here.                           |
-
-In the browser no config is needed. In a backend worker (the `worker`
-template), the platform is reachable through the `CANOPY` service binding, so
-create the client per request with that binding's fetch:
-
-```ts
-app.get("/api/hello", async (c) => {
-  const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
-  const user = await canopy.auth.user();
-  return c.json({ message: `Hello from the backend, ${user.name}!` });
-});
-```
-
-Outside Canopy hosting — a local Node script, a CI job — there is no session
-and no service binding. Mint a dev token (`canopy dev` does this for you, or
-`POST /control/v1/projects/:slug/dev-token`) and pass it with the platform's
-API host:
-
-```ts
-const canopy = createCanopy({
-  baseUrl: "https://api.canopy.website",
-  token: process.env.CANOPY_TOKEN, // a project-scoped cnpy_ token
-});
-```
-
-## One instance, shared
-
-In the browser, create the client once and import it everywhere. The scaffolds
-do this in `src/canopy.ts`:
-
-```ts
-// src/canopy.ts
-import { createCanopy } from "@mediamonks/canopy";
-
-export const canopy = createCanopy();
-```
-
-## Error handling
-
-Any call that fails throws a `CanopyError` (exported from the package). It
-extends `Error` with the HTTP `status` of the failed request; `message` carries
-the response body when the platform sent one:
-
-```ts
-import { CanopyError } from "@mediamonks/canopy";
-
-try {
-  await canopy.db.collection("todos").insert({ title: "hi", done: false });
-} catch (err) {
-  if (err instanceof CanopyError && err.status === 403) {
-    // e.g. a viewer hitting a write — show a friendly message
-  }
-  throw err;
-}
-```
-
-Two read calls are deliberately soft instead: `collection.get(id)` and
-`blob.get(key)` resolve to `null` for a missing document or object rather than
-throwing.
-
-## Where it runs
-
-The client is plain `fetch` underneath, so behavior is identical across
-environments:
-
-- **Browser, deployed** — calls go to same-origin `/_api`; the platform
-  authenticated the visitor before your page loaded, and the session cookie
-  rides along automatically.
-- **Browser, `canopy dev`** — the dev server proxies `/_api` to the platform
-  with your CLI login, so local code talks to your project's real data.
-- **Backend worker** — pass the `CANOPY` service binding's fetch (shown
-  above); the incoming request's identity carries through, so `auth.user()`
-  and per-project budgets behave exactly as in the browser.
-
-## Modules
-
-- [Auth](https://docs.canopy.website/sdk/auth) — who is signed in, and ending sessions.
-- [Database](https://docs.canopy.website/sdk/database) — document collections, plus a raw SQL escape hatch.
-- [Files](https://docs.canopy.website/sdk/files) — private blob storage under the project's prefix.
-- [AI](https://docs.canopy.website/sdk/ai) — metered, budget-capped LLM access.
-- [Services](https://docs.canopy.website/sdk/services) — curated internal data services.

package/dist/docs/staging.md

@@ -1,106 +0,0 @@
----
-title: Staging & promoting
-description: Deploy to a safe copy of your project first — own database cloned from live — then promote the exact same version.
----
-
-Every project can have a **staging channel**: a second, private copy of the
-app with its own database (cloned from live), its own files, and its own
-backend, served at
-
-```
-https://staging-dot-<slug>.canopy.website
-```
-
-behind the same sign-in as the live site. Deploy there first, click around
-against real-shaped data, then **promote** — the exact version you tested
-becomes live, nothing is rebuilt.
-
-You don't set anything up. The first staged deploy creates the channel and
-copies the live database into it.
-
-## The workflow
-
-```bash
-canopy deploy --staging   # build + deploy to staging (created on first use)
-canopy open --staging     # check it in the browser
-canopy promote            # happy? make that version live
-```
-
-`canopy deploy --staging` is the normal deploy in every way — same build, same
-versioning — except the result serves on the staging URL and the live site is
-untouched. Versions share one sequence: if live is at v7 and you stage v8,
-promoting makes that same v8 live.
-
-`canopy promote` is not a redeploy: the platform re-uses the exact files and
-backend bundle you staged. If migrations were rehearsed on staging, they replay
-against the live database first (with an automatic snapshot), then the pointer
-flips.
-
-## Testing schema migrations
-
-This is the staging channel's superpower. Because the staging database starts
-as a copy of live, a migration that works there will behave the same way on
-the real thing:
-
-```bash
-canopy deploy --staging      # pending migrations apply to the STAGING database
-# … verify the app against the migrated copy …
-canopy promote               # the same migrations replay against live, then v goes live
-```
-
-A migration that fails on staging costs you nothing — live never saw it. See
-[Schema migrations](https://docs.canopy.website/guides/migrations) for the migration system itself.
-
-## Staging an older version
-
-Any version in the deploy history can be pointed at the staging channel —
-from the dashboard's deploy list (the **Stage** action, next to Rollback) or
-with `canopy staging use v3`. Like rollback, it's a pointer move: nothing is
-rebuilt, and live is untouched. Handy for comparing an old build against the
-staging data, or re-testing a version before promoting it.
-
-## Keeping staging fresh
-
-Staging data drifts as you test. Re-clone it from live anytime:
-
-```bash
-canopy staging sync          # replace staging data with a fresh copy of live
-canopy staging status        # what's staged vs live
-```
-
-Writes on staging never flow back to live — promote moves code and schema, not
-data.
-
-## What's shared, what's separate
-
-Separate per channel: the database, uploaded files, and the backend worker.
-Shared with live: members, secrets, the client password, schedules (they run
-against live only), and the AI budget — staging traffic counts against the
-same cap.
-
-## Developing against staging data
-
-Remote dev can point at the staging database instead of live — useful while a
-schema is in flux:
-
-```bash
-canopy dev --staging
-```
-
-## Cleaning up
-
-```bash
-canopy staging destroy       # removes the staging database, files and backend
-```
-
-Live is untouched, and the next `canopy deploy --staging` recreates the channel
-from a fresh copy. The dashboard's Settings tab has the same controls, the
-Overview tab shows what's staged with a Promote button, and a Live/Staging
-toggle above the Data and Files tabs browses either channel's data.
-
-## Staging vs version previews
-
-Version preview URLs (`v12-dot-<slug>`) show an old **frontend** against the
-**live** data — good for comparing builds. The staging channel is the full
-package: candidate frontend, candidate backend, and its own database. Use
-previews to look backwards, staging to look forwards.