@spacefast/common 0.0.24 → 0.2.1

package/dist/docs/catalog.js

@@ -1,27 +1,30 @@
-// Canonical, single-sourced documentation catalog. This hand-curated product
-// content (guides + API reference + CLI + recipes) is the ONE source of truth
-// shared by two surfaces so they can never drift:
+// Canonical, single-sourced documentation catalog (guides, API reference, CLI,
+// recipes), consumed by two surfaces so they cannot drift:
 //   - the CLI's offline `sf docs` index (packages/cli re-exports this module and
 //     derives the bundled `docs-index.generated.json` from it), and
-//   - the control-plane's machine-readable `GET /v1/docs` API, which builds the
-//     same index in memory at startup.
+//   - the control-plane's `GET /v1/docs`, which builds the same index in memory.
 //
-// Entries are tier-tagged from the SAME disclosure tiers the CLI help uses
-// (vocabulary.ts), so listings are ESSENTIAL by default and widen to FULL /
-// REFERENCE. Vocabulary rules apply: say "space", "publish", "version",
-// "channel", "API key", "infra" — never "deployment"/"project"/"site"/"E2B".
+// Entries are tier-tagged from the disclosure tiers in vocabulary.ts, so
+// listings are ESSENTIAL by default. Vocabulary rules apply: say "space",
+// "publish", "version", "channel", "API key", "infra", never
+// "deployment"/"project"/"site"/"E2B".
 //
-// The "error" kind entries below are GENERATED from ERROR_DOCS (error-docs.ts),
-// not hand-written — one catalog entry per ERROR_CODES member, reference tier —
-// so every error code is searchable from `sf docs <code>`, `GET /v1/docs?q=`,
-// and MCP search without a second hand-maintained corpus to drift.
+// The "error" entries are GENERATED from ERROR_DOCS (error-docs.ts), one per
+// ERROR_CODES member at the reference tier, so every code is searchable without
+// a second hand-maintained corpus.
+import { DEFAULT_API_URL, DOCS_BASE_URL } from "../config/domains.js";
 import { errorDocsUrl } from "../contracts/error-codes.js";
 import { ERROR_DOCS } from "./error-docs.js";
+import { PARTNER_API_REFERENCE_URL } from "./reference-urls.js";
 import { renderSpacefastSkill, SPACEFAST_RECIPE_SKILLS } from "./skills.js";
 /** Which part of the docs a page belongs to (runtime list + derived type). */
 export const DOC_KINDS = ["guide", "cli", "api", "recipe", "workflow", "error"];
-/** Base URL all bundled docs links resolve against. */
-export const DOCS_BASE_URL = "https://spacefast.com/docs";
+/**
+ * Base URL all bundled docs links resolve against. Owned by the domain registry
+ * (`../config/domains.ts`) and re-exported here, where every docs caller
+ * already looks for it.
+ */
+export { DOCS_BASE_URL };
 const HAND_WRITTEN_DOCS_CATALOG = [
     // ----- Guides -----------------------------------------------------------
     {
@@ -40,8 +43,8 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         kind: "guide",
         tier: "essential",
         summary: "How `sf publish` builds, uploads, and goes live.",
-        keywords: ["publish", "go live", "upload", "release", "static"],
-        url: `${DOCS_BASE_URL}/publishing`,
+        keywords: ["publish", "go live", "upload", "release", "artifact"],
+        url: `${DOCS_BASE_URL}/publish`,
         body: "`sf publish` snapshots your output directory into an immutable version and promotes it to the production channel. Use `--no-wait` to return before serving finishes.",
     },
     {
@@ -51,7 +54,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         tier: "full",
         summary: "Change a space slug and its managed view.fast address without breaking old links.",
         keywords: ["space", "rename", "slug", "view.fast", "redirect", "managed hostname"],
-        url: `${DOCS_BASE_URL}/spaces/rename`,
+        url: `${DOCS_BASE_URL}/operate/spaces`,
         body: 'Run `sf spaces update --space <space> --slug <new-slug> --wait`, or PATCH `/v1/spaces/{spaceId}` with `{ "slug": "<new-slug>" }`. The managed view.fast hostname changes with the slug. Former managed addresses and branch aliases redirect directly to their current counterparts with a temporary, path- and query-preserving 307 for the life of the space unless an operator explicitly releases them. Custom domains stay attached, and immutable version URLs do not change.',
     },
     {
@@ -93,17 +96,17 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Publish a file or zipped output folder directly to /v1/publish. No account, CLI install, or MCP setup is required for anonymous publishes.",
         keywords: ["publish", "curl", "anonymous", "no install", "claim"],
         url: `${DOCS_BASE_URL}/agents#publish-with-curl`,
-        body: "curl publish static file folder archive zip anonymous no account no install live URL immutable version claim link /v1/publish",
+        body: "curl publish file folder archive zip anonymous no account no install live URL immutable version claim link /v1/publish",
     },
     {
         slug: "workflow/publish-receipt",
         title: "Publish receipt fields",
         kind: "workflow",
         tier: "full",
-        summary: "Use the receipt as the source of truth. For anonymous publishes, claim.url is the private-site door and claim.claimUrl is the browser claim link; liveUrl and immutableUrl identify resources for automation.",
+        summary: "Use the receipt as the source of truth. For anonymous publishes, claim.url is the private-site door and claim.claimUrl is the browser claim link; space.liveUrl and version.immutableUrl identify resources for automation.",
         keywords: ["receipt", "share", "claim", "diagnostics"],
         url: `${DOCS_BASE_URL}/api#publish`,
-        body: "receipt liveUrl open url immutableUrl claim expiresAt diagnostics links finalize promote upload errors docsUrl",
+        body: "receipt space.liveUrl open url version.immutableUrl claim expiresAt diagnostics links finalize promote upload errors docsUrl",
     },
     {
         slug: "workflow/continue-after-claim",
@@ -146,20 +149,20 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "On-Device MCP through the CLI",
         kind: "workflow",
         tier: "full",
-        summary: "Run sf mcp for stdio or sf mcp http --host 127.0.0.1 --port 3945 --path /mcp for On-Device Streamable HTTP.",
-        keywords: ["mcp", "stdio", "streamable http", "on-device", "local"],
+        summary: "Run sf mcp for the stdio On-Device MCP server in the local checkout.",
+        keywords: ["mcp", "stdio", "on-device", "local"],
         url: `${DOCS_BASE_URL}/agents#mcp`,
-        body: "MCP on-device local CLI stdio streamable HTTP sf mcp roots files workspace tool calls structuredContent apps",
+        body: "MCP on-device local CLI stdio sf mcp roots files workspace tool calls structuredContent apps",
     },
     {
         slug: "workflow/space-files",
         title: "Space file conventions",
         kind: "workflow",
         tier: "full",
-        summary: "Spacefast recognizes _redirects, _headers, nearest 404.html, and sf.jsonc. Static artifacts are served as files; server code is not executed.",
+        summary: "Spacefast recognizes _redirects, _headers, nearest 404.html, and sf.jsonc. Published artifacts are served as files; server code is not executed.",
         keywords: ["_redirects", "_headers", "sf.jsonc", "spacefast.jsonc", "404"],
         url: `${DOCS_BASE_URL}/configuration`,
-        body: "_redirects _headers 404.html sf.jsonc static artifact server code not executed proxy rewrite headers",
+        body: "_redirects _headers 404.html sf.jsonc artifact server code not executed proxy rewrite headers",
     },
     {
         slug: "workflow/domains-diagnostics",
@@ -183,13 +186,13 @@ const HAND_WRITTEN_DOCS_CATALOG = [
     },
     {
         slug: "workflow/agent-auth",
-        title: "Agent accounts and OAuth",
+        title: "Machine OAuth clients",
         kind: "workflow",
         tier: "full",
-        summary: "Prefer OAuth agent accounts with private_key_jwt and SPACEFAST_AGENT_CONFIG for On-Device MCP and automation instead of broad shared API keys.",
-        keywords: ["oauth", "agent account", "private_key_jwt", "SPACEFAST_AGENT_CONFIG"],
+        summary: "Use team-owned OAuth clients with private_key_jwt and SPACEFAST_AGENT_CONFIG for On-Device MCP and automation. Do not use broad shared API keys.",
+        keywords: ["oauth", "client credentials", "private_key_jwt", "SPACEFAST_AGENT_CONFIG"],
         url: `${DOCS_BASE_URL}/agents#agent-accounts`,
-        body: "OAuth agent account private_key_jwt SPACEFAST_AGENT_CONFIG client credentials scoped token mcp automation teams",
+        body: "OAuth client private_key_jwt SPACEFAST_AGENT_CONFIG client credentials scoped token mcp automation teams",
     },
     {
         slug: "custom-domains",
@@ -269,7 +272,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Run code on a space with Zero or Functions.",
         keywords: ["runtime", "zero", "functions", "server", "dynamic", "code", "backend", "sf.jsonc"],
         url: `${DOCS_BASE_URL}/runtimes`,
-        body: "A space serves static files until you declare a `runtime` block in sf.jsonc. Every space has its own runtime site. Zero is a capsule with its own database and transactions; Functions is a Cloudflare worker with one `fetch` handler and any npm package. Both are available on every plan and compile during `sf publish`.",
+        body: "A space serves published files until you declare a `runtime` block in sf.jsonc. Every space has its own runtime site. Zero is a capsule with its own database and transactions; Functions is a Cloudflare worker with one `fetch` handler and any npm package. Both are available on every plan and compile during `sf publish`.",
     },
     {
         slug: "runtimes/zero",
@@ -289,7 +292,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
             "sql",
             "sf dev",
         ],
-        url: `${DOCS_BASE_URL}/runtimes/zero`,
+        url: `${DOCS_BASE_URL}/zero-runtime`,
         body: "Zero is for apps where the data is the point. Write one capsule — schema, queries, mutations, endpoints — start it locally with `sf dev`, and `sf publish` puts it live with its own database and dedicated runtime site on every plan.",
     },
     {
@@ -340,7 +343,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Proxy selected paths to an upstream origin.",
         keywords: ["proxy", "upstream", "route", "api", "backend", "rewrite"],
         url: `${DOCS_BASE_URL}/proxy-routes`,
-        body: "Forward specific path prefixes to an external upstream so a static space can front a dynamic API without exposing the origin.",
+        body: "Forward specific path prefixes to an external upstream so a space can front an external API without exposing its origin.",
     },
     {
         slug: "image-acceleration",
@@ -371,7 +374,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
             "revalidatePath",
         ],
         url: `${DOCS_BASE_URL}/integrations/nextjs`,
-        body: "Run `sf publish` in a Next.js project. Spacefast builds it with pinned OpenNext and publishes the static assets plus its Functions worker. The automatic adapter keeps the Next Data Cache and tag invalidations in private origin storage scoped to the exact space and version, so cached data survives cold Worker isolates; `revalidateTag()` and `revalidatePath()` invalidate that same store. Concurrent stale ISR requests share a 30-second regeneration lease, with at most 4,096 leases active for one version. Each cached value is limited to 4 MiB; one version may retain 128 MiB, 4,096 entries, and 8,192 tags. A project with its own `open-next.config.ts` owns its adapters instead of receiving Spacefast's automatic cache config.",
+        body: 'Run `sf publish` in a Next.js project. Spacefast reads the resolved build mode from Next itself: `output: "export"` ships the generated browser files directly, while server-rendered apps are bundled with pinned OpenNext and publish their browser assets plus a Functions worker. The automatic adapter keeps the Next Data Cache and tag invalidations in private origin storage scoped to the exact space and version, so cached data survives cold Worker isolates; `revalidateTag()` and `revalidatePath()` invalidate that same store. Concurrent stale ISR requests share a 30-second regeneration lease, with at most 4,096 leases active for one version. Each cached value is limited to 4 MiB; one version may retain 128 MiB, 4,096 entries, and 8,192 tags. A project with its own `open-next.config.ts` owns its adapters instead of receiving Spacefast\'s automatic cache config.',
     },
     {
         slug: "integrations/vite",
@@ -390,7 +393,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         tier: "reference",
         summary: "File counts, sizes, and rate limits per plan.",
         keywords: ["limits", "quota", "size", "rate limit", "plan", "storage"],
-        url: `${DOCS_BASE_URL}/limits`,
+        url: `${DOCS_BASE_URL}/account/plans`,
         body: "Reference for per-space file counts, archive and file size ceilings, and rate limits, which vary by plan.",
     },
     {
@@ -559,7 +562,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "sf api-keys",
         kind: "cli",
         tier: "full",
-        summary: "Create and revoke API keys for the platform API.",
+        summary: "Create and revoke API keys for the Spacefast API.",
         keywords: ["api-keys", "api key", "token", "create", "revoke", "list", "credential"],
         url: `${DOCS_BASE_URL}/cli`,
         body: "`sf api-keys create` mints a bearer key (shown once, masked in `--json`); `sf api-keys list` and `sf api-keys revoke` manage existing keys.",
@@ -617,13 +620,13 @@ const HAND_WRITTEN_DOCS_CATALOG = [
     // ----- API reference ----------------------------------------------------
     {
         slug: "api",
-        title: "Platform API overview",
+        title: "API overview",
         kind: "api",
         tier: "full",
-        summary: "Authenticate and call the Spacefast platform API.",
-        keywords: ["api", "rest", "http", "platform", "endpoint", "openapi", "bearer"],
+        summary: "Authenticate and call the Spacefast API.",
+        keywords: ["api", "rest", "http", "spacefast", "endpoint", "openapi", "bearer"],
         url: `${DOCS_BASE_URL}/api`,
-        body: "The platform API uses bearer API keys and returns the same `{ data }` / `{ error }` envelope as the CLI. Create a key with `sf api-keys create`.",
+        body: "The Spacefast API uses bearer API keys and returns the same `{ data }` / `{ error }` envelope as the CLI. Create a key with `sf api-keys create`.",
     },
     {
         slug: "api/publish",
@@ -663,7 +666,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Attach and inspect custom domains over HTTP.",
         keywords: ["api", "domains", "domain", "dns", "certificate", "endpoint"],
         url: `${DOCS_BASE_URL}/api`,
-        body: "Add a custom domain, read its verification and certificate status, and manage DNS records through the platform API.",
+        body: "Add a custom domain, read its verification and certificate status, and manage DNS records through the Spacefast API.",
     },
     {
         slug: "api/teams",
@@ -683,7 +686,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Fetch the machine-readable documentation index.",
         keywords: ["api", "docs", "index", "discovery", "machine-readable", "v1/docs"],
         url: `${DOCS_BASE_URL}/api`,
-        body: "`GET /v1/docs` returns the tier-aware docs index (filter with `q` and `category`); `GET /v1/docs/{slug}` returns one page. It mirrors the CLI's offline `sf docs`.",
+        body: "`GET /v1/docs` returns the tier-aware docs index (filter with `q` and `category`); `GET /v1/docs/pages/{slug}` returns one page. It mirrors the CLI's offline `sf docs`.",
     },
     {
         slug: "api/webhooks",
@@ -696,14 +699,126 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         body: "Register a team-scoped, signed webhook to receive version, build, domain, and transfer events. Verify the signature header before trusting a payload.",
     },
     {
-        slug: "api/platform",
-        title: "Platform (tenant) API",
+        slug: "sdk",
+        title: "TypeScript SDK (@spacefast/sdk)",
+        kind: "api",
+        tier: "essential",
+        summary: "The typed client for the API, generated from the OpenAPI spec.",
+        keywords: [
+            "sdk",
+            "typescript",
+            "javascript",
+            "client",
+            "npm",
+            "library",
+            "types",
+            "tanstack",
+            "react-query",
+            "node",
+        ],
+        url: `${DOCS_BASE_URL}/sdk`,
+        body: "`npm install @spacefast/sdk`, then `createSpacefastClient({ baseUrl: 'https://api.spacefast.com', apiKey })`. Paths, parameters, and responses are all typed from the same OpenAPI spec the API serves: `client.get('/v1/spaces/{spaceId}', { path: { spaceId } })` returns the space. Failures throw `SpacefastApiError` carrying the problem document (`status`, `code`, `pointer`, `next`, `requestId`). Subpaths: `/schema` for raw types, `/query` for TanStack Query factories (browser, cookie-authenticated), `/transport` for the HTTP core, `/publish` for the publish pipeline, `/openapi.json` for your own codegen.",
+    },
+    // ----- Partner surface --------------------------------------------------
+    {
+        slug: "api/partner",
+        title: "Partner (tenant) API",
+        kind: "api",
+        tier: "reference",
+        summary: "The tenant-facing partner API for running Spacefast as infra.",
+        keywords: ["api", "partner", "tenant", "infra", "openapi", "multi-tenant", "white label"],
+        url: `${DOCS_BASE_URL}/partners`,
+        body: `There is no partner route tree. Partners call the same \`/v1\` routes as everyone else: successes carry a \`{ data }\` envelope and failures are RFC 9457 problem documents (\`application/problem+json\` with a stable \`code\`), exactly as elsewhere in the API. A tenant-rooted credential's policy scope and response projection decide what it sees. "Partner" is a spec visibility tier: those operations, plus tenants and principals, are published as a second OpenAPI document at ${DEFAULT_API_URL}/openapi.partner.json, rendered at ${PARTNER_API_REFERENCE_URL}. Point \`openapi-typescript\` at that document for types. Configuration is not a set of endpoints: a tenant declares its integration in one designated space's published manifest (see \`partner/system-space\`).`,
+    },
+    {
+        slug: "partner/onboarding",
+        title: "Partner onboarding",
         kind: "api",
         tier: "reference",
-        summary: "The tenant-facing platform API for running Spacefast as infra.",
-        keywords: ["api", "platform", "tenant", "infra", "openapi", "multi-tenant"],
-        url: `${DOCS_BASE_URL}/platforms`,
-        body: "The platform API is the tenant-facing surface for operating Spacefast as hosting infra. It shares the `{ data }` / `{ error }` envelope and is documented via OpenAPI.",
+        summary: "Bootstrap a tenant: one key, one space, one designation, one publish.",
+        keywords: ["partner", "onboarding", "tenant", "bootstrap", "partner_admin", "api key", "setup"],
+        url: `${DOCS_BASE_URL}/partners#onboarding`,
+        body: "Tenant creation is superadmin-side and mints one bootstrap tenant-rooted API key with the `partner_admin` preset (`tenants:*`, `principals:read`, and space/domain/publish actions over the tenant). From there it is four steps you drive yourself: create a space with that key, `PATCH /v1/tenants/{tenantId}` with `systemSpaceId` to designate it, publish the manifest, then read `manifestStatus` on `GET /v1/tenants/{tenantId}` to watch each declared item converge. Mint further keys through the normal API-key routes — every one is bounded to a subset of its grantor's policy.",
+    },
+    {
+        slug: "partner/system-space",
+        title: "The system space",
+        kind: "api",
+        tier: "reference",
+        summary: "Your integration is a published space, so config versions and rolls back.",
+        keywords: [
+            "partner",
+            "system space",
+            "manifest",
+            "sf.jsonc",
+            "systemSpaceId",
+            "manifestStatus",
+            "gitops",
+            "reconciliation",
+            "white label",
+        ],
+        url: `${DOCS_BASE_URL}/partners#system-space`,
+        body: "A tenant designates one ordinary space as its system space, and that space's live version *is* the integration definition: a top-level `system` section in `sf.jsonc` (presentation, hostname apex, API origin, token issuers, event subscriptions) plus `_pages/` and `theme.json` as the defaults layer. One config language, one validation pipeline, one publish flow — and `sf rollback` rolls back your configuration with it. Finalize, promote, and rollback all reconcile declared state against current state. Presentation, pages, theme, and subscriptions apply immediately; hostnames, API origins, and token issuers enter `pending` until their DNS, TLS, or key-possession check passes. Dropping an item from the manifest deactivates it. Per-item state lands in `manifestStatus` (`{ key, state, detail, since }` plus the source version id) on `GET /v1/tenants/{tenantId}`. There are no imperative config routes: the fix for a failed item is a new publish. Secrets are never declared — webhook secrets and API keys are minted by their own routes.",
+    },
+    {
+        slug: "partner/tokens",
+        title: "Partner tokens",
+        kind: "api",
+        tier: "reference",
+        summary: "Let your own auth system mint tokens Spacefast verifies directly.",
+        keywords: [
+            "partner",
+            "token",
+            "jwt",
+            "issuer",
+            "eddsa",
+            "ed25519",
+            "auth",
+            "partner_token",
+            "audience",
+            "revocation",
+        ],
+        url: `${DOCS_BASE_URL}/partners#tokens`,
+        body: "Your customers never need a Spacefast credential: your auth system mints standard JWT access tokens and Spacefast verifies them. Declare the issuer in the system-space manifest with its pinned Ed25519 public keys — there is no issuer CRUD. The first publish returns `state: pending` with a challenge nonce in `manifestStatus`; sign it with the declared key and republish with the `proof` field, and the issuer activates. Proof of key possession lives in your repo next to the declaration. The token profile is strict: `typ` of `at+jwt`, `alg` of `EdDSA` only, the per-issuer minted `aud` (never a shared value), all of `iss`/`sub`/`client_id`/`jti`/`iat`/`exp` required, `exp - iat` at most 30 minutes, 300s clock skew; embedded or fetched keys are rejected. A verified token becomes a `partner_token` credential bound to one external principal, carrying a fixed least-privilege policy: publish, read, versions, and variables over that principal's subtree — never tenant or principal management. Revoke by removing the issuer or rotating its keys; worst-case acceptance of a revoked token is the shorter of a 30s cache TTL and the token's own expiry.",
+    },
+    {
+        slug: "partner/principals",
+        title: "Principals and ownership",
+        kind: "api",
+        tier: "reference",
+        summary: "External principals are your customer directory; spaces have exactly one owner.",
+        keywords: [
+            "partner",
+            "principals",
+            "external",
+            "tenant",
+            "ownership",
+            "iam",
+            "policy",
+            "scope",
+            "variables",
+        ],
+        url: `${DOCS_BASE_URL}/partners#principals`,
+        body: "Your customers are external principals inside your tenant. `GET /v1/principals` lists them within the caller's granted scope (a tenant-rooted key sees the whole tenant) and `GET /v1/principals/external/{principalId}` reads one. There is no create route: a principal is upserted implicitly in the same transaction as its first owned resource, and its identity is the normalized id — the display casing you first sent is preserved but never authoritative. Every space has exactly one owner: a team, an external principal, or an open claim token. IAM actions stay generic nouns (`tenants:read`, `tenants:write`, `principals:read`) rather than a `partner:*` namespace, evaluated per route like every other action, so a partner credential's reach is a policy fact and not a router branch. Per-principal environment variables live under `/v1/principals/{principalType}/{principalId}/variables`.",
+    },
+    {
+        slug: "partner/events",
+        title: "Partner events and notifications",
+        kind: "api",
+        tier: "reference",
+        summary: "Tenant-owned webhooks, declared in the manifest — including customer email.",
+        keywords: [
+            "partner",
+            "events",
+            "webhook",
+            "subscriptions",
+            "notifications",
+            "email",
+            "signature",
+            "hmac",
+        ],
+        url: `${DOCS_BASE_URL}/partners#events`,
+        body: "Webhooks are the one event primitive, and their ownership generalizes from teams to tenants. Declare subscriptions in the system-space manifest (`url` plus an `events` selection) and reconciliation creates, updates, or disables the rows; delivery uses the same `Spacefast-Signature` HMAC and dual-secret rotation as team webhooks, so verify the signature before trusting a payload. Email white-labeling is not a separate endpoint: subscribe to `principal.notification.*` events (claim link issued, security notice, publish receipt) and send them yourself in your own voice. For a partner tenant these events replace Spacefast-sent email to your customers — no active subscription means no send, and Spacefast never falls back to sending as itself to someone else's customer.",
     },
 ];
 const SKILL_RECIPE_DOCS = SPACEFAST_RECIPE_SKILLS.map((skill) => ({