@mediamonks/canopy-cli 0.7.12 → 0.7.13

package/dist/docs/porting-nextjs.md

@@ -0,0 +1,233 @@
+---
+title: Porting a Next.js app
+description: How to restructure a Next.js (App Router) project so it runs on Canopy.
+---
+
+Canopy can host a project that started life as a Next.js app — but not by
+running Next.js's server. This guide explains why, and walks through the
+restructuring: a **static frontend** plus an optional **backend worker on
+`/api/*`**, with the platform taking over auth, data, files, and AI.
+
+If your app barely uses Next's server side, the port is a day or two of work.
+If it leans heavily on server components, server actions, or ISR, read
+[When not to port](#when-not-to-port) first.
+
+## Why a lift-and-shift doesn't work
+
+Canopy deliberately hosts no arbitrary servers — that's what keeps a thousand
+idle projects free to run and safe to operate. Three consequences matter for
+Next.js:
+
+- **Every page is a static file.** The platform serves your deployed build
+  from storage; requests to `/`, `/about`, or any other page route never reach
+  project code (see [How static files are served](https://docs.canopy.website/guides/static-serving)).
+  Server-side rendering, React Server Components resolved per request,
+  and Incremental Static Regeneration have nowhere to run.
+- **The backend is one worker, reachable only under `/api/*`.** A project can
+  ship a single bundled module exporting `fetch()` (and optionally
+  `scheduled()`), and the platform routes `/api/*` requests to it. Server
+  actions — which POST to page routes — never reach it.
+- **Auth belongs to the platform.** Every request is already behind OneLogin
+  (or a project password) before your code runs. NextAuth, auth middleware,
+  and session handling come out of the ported app entirely.
+
+So the port is a restructure: the frontend becomes a static build, and
+whatever genuinely needs a server moves into the worker.
+
+## What a ported app looks like
+
+```
+my-app/
+├── canopy.json          ← slug, build command, dist folder, worker entry
+├── src/                 ← frontend (static build)
+├── worker/
+│   └── index.ts         ← backend: fetch handler for /api/*
+└── dist/                ← build output that gets deployed
+```
+
+```json
+{
+  "slug": "my-app",
+  "build": "npm run build",
+  "dist": "dist",
+  "worker": "worker/index.ts"
+}
+```
+
+One `canopy deploy` builds and ships both; frontend and backend always move
+together as a single version, with rollback.
+
+## Step 1 — take inventory
+
+List everything in the app that runs on the server. Each item lands in one of
+three buckets:
+
+| Next.js feature                                 | Where it goes on Canopy                                                          |
+| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| Pages, layouts, client components               | Static build (unchanged in spirit)                                               |
+| Server components fetching data at request time | Client-side fetching, or a worker endpoint                                       |
+| Route handlers (`app/api/*/route.ts`)           | Worker endpoints under `/api/*`                                                  |
+| Server actions                                  | Explicit worker endpoints, called with `fetch` from the client                   |
+| Middleware                                      | Usually deleted (auth is platform-provided); anything else moves into the worker |
+| NextAuth / auth middleware                      | Deleted — use `canopy.auth.user()` (client) or `env.USER` (worker)               |
+| Database (Prisma, Postgres, …)                  | `canopy.db` — per-project database, document API + SQL escape hatch              |
+| File uploads (S3, …)                            | `canopy.blob` — per-project file storage with signed downloads                   |
+| AI SDK / OpenAI client                          | `canopy.ai.chat()`, or point the Vercel AI SDK at `canopy.ai.endpoint()`         |
+| `NEXT_PUBLIC_*` env vars                        | Build-time env vars in your CI — the platform doesn't inject build config        |
+| Server-side env vars / secrets                  | Project secrets (dashboard Settings) — injected into the worker's `env`          |
+| Cron (`vercel.json` crons)                      | [Schedules](https://docs.canopy.website/platform/schedules) — delivered to the worker's `scheduled()`       |
+| ISR / `revalidate` / caching                    | Dropped — at internal-tool scale, fetch fresh or cache in the client             |
+| `next/image` optimization                       | Plain `<img>`, or optimize at build time                                         |
+| Custom domain                                   | Not available — projects live at `<slug>.canopy.<domain>` behind sign-in         |
+| Queues / background jobs                        | Not supported — restructure around request/response plus schedules               |
+
+If the last two rows are deal-breakers, stop here: see
+[When not to port](#when-not-to-port).
+
+## Step 2 — make the frontend static
+
+Two routes, pick one:
+
+**Static export (quickest).** Set `output: 'export'` in `next.config.js` and
+fix what breaks. You keep the App Router file layout and components, but lose
+everything request-time: no route handlers, no server actions, no dynamic
+route segments without `generateStaticParams`, no request-time server
+components (they still run — but once, at build time). `next build` writes a
+fully static site to `out/`; point `dist` at it. Set
+`images: { unoptimized: true }` since there's no image optimizer serving
+requests.
+
+**Rebuild as a Vite SPA (more idiomatic).** Canopy's templates and tooling
+assume a single-page app: one `index.html`, client-side routing, `canopy dev`
+for local development against real project data. If you're porting an app
+you'll keep evolving on Canopy — especially with an AI agent doing the work —
+converting pages to a React + Vite SPA usually pays for itself quickly, and
+agents handle this conversion well. Page routes become client routes (the
+platform serves `index.html` for unknown paths, so deep links work).
+
+Either way, data that pages used to fetch on the server now arrives one of two
+ways: fetched from the client through the SDK (`canopy.db`, `canopy.blob` —
+fine for most internal tools), or from your worker via `/api/*` when it needs
+server-side logic or secrets.
+
+## Step 3 — move the backend into a worker
+
+Route handlers and server actions become endpoints in one fetch handler.
+[Hono](https://hono.dev) is a natural fit and bundles cleanly:
+
+```ts
+// worker/index.ts
+import { createCanopy } from "@mediamonks/canopy";
+import { Hono } from "hono";
+
+type Env = {
+  CANOPY: { fetch: typeof fetch };
+  /** Signed-in monk, verified by the platform; null for cron. */
+  USER: { sub: string; email: string; name: string } | null;
+  /** Project secrets from dashboard Settings appear as plain keys. */
+  MY_API_KEY?: string;
+};
+
+const app = new Hono<{ Bindings: Env }>();
+
+// was: app/api/report/route.ts
+app.post("/api/report", async (c) => {
+  const user = c.env.USER;
+  if (!user) return c.json({ error: "unauthenticated" }, 401);
+
+  // The SDK works inside the worker through the CANOPY binding —
+  // same database and files the frontend sees, caller's identity attached.
+  const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
+  const rows = await canopy.db.collection("reports").find({ where: { owner: user.email } });
+  return c.json({ rows });
+});
+
+// was: a server action
+app.post("/api/submit", async (c) => {
+  const body = await c.req.json();
+  // …validate, write via canopy.db, call an external API with c.env.MY_API_KEY…
+  return c.json({ ok: true });
+});
+
+export default {
+  fetch: app.fetch.bind(app),
+  // was: vercel.json crons — configure in dashboard Settings → Schedules
+  async scheduled(event: { name: string }, env: Env) {
+    if (event.name === "nightly-report") {
+      // …
+    }
+  },
+};
+```
+
+Rules of the road for the worker:
+
+- It's **one bundled file** — dependencies are bundled in at deploy time, so
+  stick to packages that don't need Node built-ins or native modules.
+- **No filesystem, no long-lived state.** Persist through `canopy.db` and
+  `canopy.blob`.
+- **Outbound requests are controlled.** Calls to external APIs pass through a
+  per-project egress allowlist — deny-by-default, managed by you. Allow the
+  hosts your worker calls with `canopy egress allow <host>` or in dashboard
+  Settings → Outbound hosts (see [Outbound requests](https://docs.canopy.website/platform/egress)).
+- Frontend calls are plain `fetch("/api/…")` — same origin, the platform
+  session cookie rides along automatically.
+
+## Step 4 — swap the data layer
+
+Replace the ORM and connection strings with the project's own database:
+
+- The paved road is the [document API](https://docs.canopy.website/sdk/database):
+  `canopy.db.collection("todos").insert(…)` / `find(…)` — schemaless JSON, no
+  migrations. For most internal tools this replaces Prisma models outright.
+- Relational shapes port via the SQL escape hatch, `canopy.db.sql()`, against
+  the same per-project database.
+- Existing data can be imported once: export from your old database, then load
+  it through the worker or the [SQL console](https://docs.canopy.website/guides/data) in the dashboard.
+
+Files move to [`canopy.blob`](https://docs.canopy.website/sdk/files) (uploads, listings, short-lived
+signed download URLs — nothing is ever publicly readable). AI calls move to
+[`canopy.ai`](https://docs.canopy.website/sdk/ai); if the app uses the Vercel AI SDK, point it at
+`canopy.ai.endpoint()` and it keeps working, now metered and budget-capped.
+
+## Step 5 — delete the auth
+
+This is the satisfying part. OneLogin fronts every request before your code
+runs, so the ported app removes sign-in pages, session handling, and auth
+middleware entirely:
+
+- **Client:** `canopy.auth.user()` returns the signed-in monk.
+- **Worker:** `env.USER` carries the verified identity (no round-trip).
+- Client-facing access without OneLogin is a per-project
+  [password](https://docs.canopy.website/platform/client-access), configured in Settings — not code.
+
+Authorization (who may do what _inside_ the app) stays yours, but it now keys
+off a verified identity instead of a homegrown session.
+
+## When not to port
+
+Be honest about fit before starting. Dedicated hosting is the better home
+when the app:
+
+- depends on **per-request SSR** for real reasons — SEO on public pages,
+  personalization at the edge, streaming server components as a core UX;
+- is built around **server actions and RSC data flow** so thoroughly that the
+  restructure is a rewrite;
+- needs a **custom domain or anonymous public access** — nothing on Canopy is
+  reachable without OneLogin or a project password;
+- needs **queues, background jobs, or long-running work**.
+
+That's not a workaround waiting to happen — it's the platform's design. Canopy
+optimizes for small internal tools; an app that genuinely needs a server is
+past greenhouse size (see [Use cases](https://docs.canopy.website/overview/use-cases)).
+
+## Checklist
+
+- [ ] Inventory server-side surface (RSC fetching, actions, route handlers, middleware, crons)
+- [ ] Frontend: `output: 'export'` or Vite SPA; fix dynamic segments and `next/image`
+- [ ] Worker: route handlers + server actions → `/api/*` endpoints in `worker/index.ts`
+- [ ] Data: ORM → `canopy.db`; uploads → `canopy.blob`; AI clients → `canopy.ai`
+- [ ] Delete NextAuth/middleware; read identity from `canopy.auth.user()` / `env.USER`
+- [ ] Secrets into dashboard Settings; `NEXT_PUBLIC_*` into your CI build
+- [ ] Crons into Settings → Schedules, handled in `scheduled()`
+- [ ] `canopy.json` with `build`, `dist`, `worker` — then `canopy deploy`

package/dist/docs/sdk-ai.md

@@ -0,0 +1,103 @@
+---
+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

@@ -0,0 +1,57 @@
+---
+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

@@ -0,0 +1,126 @@
+---
+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

@@ -0,0 +1,82 @@
+---
+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

@@ -0,0 +1,58 @@
+---
+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.