busabase-sdk 0.14.1 → 0.16.0

package/README.md

@@ -70,6 +70,83 @@ storeBusabaseAirAppOAuthCredential({
 
 The Node-only helper writes `~/.busabase/airapps/<app-id>.json` with an owner-only directory and file (`0700`/`0600`). Use `getBusabaseAirAppAccessToken()` inside Hono when proxying `/api/v1`; it refreshes and persists the token set when needed. Use `revokeBusabaseAirAppOAuthCredential()` on logout. The browser must never receive the `bso_` access token, `bsr_` refresh token, or PKCE verifier through JavaScript-visible storage. This local AirApp registration is separate from the CLI's active `~/.busabase/.env` profile.
 
+## Building an AirApp
+
+Three entry points cover what every AirApp needs before it can show its first screen. Use them instead of reimplementing any part — the rules they encode (which server, whose Space, whose Folder) are a security boundary, not app preferences.
+
+### `busabase-sdk/airapp-node` — the local gateway (server)
+
+`createBusabaseAirAppLocalGateway()` owns the whole standalone-run boundary: the pending PKCE request, credential rotation, auth verification, validated Space persistence, logout, and the `/api/v1` proxy. Do not copy those mechanics into each app.
+
+```ts
+import { createBusabaseAirAppLocalGateway } from "busabase-sdk/airapp-node";
+
+const gateway = createBusabaseAirAppLocalGateway({ appId: "kelly-crm", successPath: "/#/overview" });
+
+app.get("/auth/status", (c) => gateway.statusResponse(c.req.raw));
+app.post("/auth/start", (c) => gateway.start(c.req.raw));
+app.get("/auth/callback", (c) => gateway.callback(c.req.raw));
+app.post("/auth/space", (c) => gateway.selectSpace(c.req.raw));
+app.post("/auth/logout", (c) => gateway.logout(c.req.raw));
+app.all("/api/v1/*", (c) => gateway.proxy(c.req.raw));
+```
+
+`proxy()` always sets `x-busabase-space` from its own validated selection and ignores any such header on the incoming request, so a page cannot talk the gateway into reading another Space.
+
+### `busabase-sdk/airapp` — resource provisioning (isomorphic)
+
+Declare the Folder and Bases the app needs; the SDK claims or creates them as one idempotent ChangeRequest.
+
+```ts
+import { inspectProvisionedResources, provisionDeclaredResources } from "busabase-sdk/airapp";
+
+const config = {
+  appId: "kelly-crm",
+  appName: "Kelly CRM",
+  schemaVersion: 1,
+  folder: { slug: "kelly-crm", name: "Kelly CRM", description: "CRM workspace" },
+  bases: [{ key: "contacts", slug: "kelly-crm-contacts-v1", name: "Contacts", fields: [/* … */] }],
+};
+
+let resources = await inspectProvisionedResources(client, config);
+if (!resources.folder || resources.missing.length) {
+  resources = await provisionDeclaredResources(client, config);
+}
+```
+
+An app that ships its own AirApp node inside the Folder declares it too — `airApp: { slug, name, resourceKey }`. It is published, not provisioned, so it is never created here; declaring it is what lets it be stamped, and what stops it from reading as an unattributable stranger that blocks a legacy claim.
+
+**An app owns a node only if it stamped it.** Ownership lives in `node.metadata` as `{ appId, resourceKey, schemaVersion }`. An unstamped node is adopted only when its slug, name, description, and full field list still match the declaration exactly; anything else raises `SETUP_CONFLICT` and nothing is mutated. A `schemaVersion` bump re-stamps in place — it never recreates a Base, so data survives. Concurrent callers on the same client share one in-flight submission.
+
+**Bases evolve by appending fields.** A live Base whose fields are a strict *prefix* of the declaration is an older schema of yours: the missing suffix is added, one approval-gated `bases.fieldChangeRequest` per field, and anything left unapproved surfaces as `SETUP_PENDING` naming the requests. A field renamed, retyped, reordered, or removed is not an upgrade this can reason about, so it refuses rather than guessing which shape is right.
+
+Failures are an `AirAppSetupError` carrying a `code`: `SETUP_REQUIRED` (offer to initialize), `SETUP_PENDING` (submitted, awaiting approval — approval-first working as designed), `SETUP_CONFLICT`, `SETUP_PERMISSION`, `SCHEMA_INCOMPLETE`. `message` keeps the `"CODE: detail"` shape so code that parses the prefix keeps working.
+
+### `busabase-sdk/airapp-gate` — the connect UI (browser)
+
+The three screens the operator sees before the app mounts: choose a server and connect, choose a Space, and initialize the workspace.
+
+```ts
+import { createAirAppConnectGate } from "busabase-sdk/airapp-gate";
+
+const gate = createAirAppConnectGate({
+  appName: "Kelly CRM",
+  shouldGate: () => !isDemo() && shouldUseLocalGateway(), // see below
+  onProvision: () => provisionDeclaredResources(client, config),
+  demoHref: "?demo=1",
+});
+
+if (await gate.pass({ onReady: start })) start();
+// …and when loading data fails because the workspace is not set up yet:
+gate.renderSetupRequired(error, start);
+```
+
+`pass()` returns `true` when the app may load data.
+
+**Pass `shouldGate`.** Where an app runs is a fact its host states: Busabase injects `BUSABASE_AIRAPP_RUNTIME` into the process it spawns, and the app's own server surfaces that to the browser. Never classify it by hostname, iframe nesting, or path — a hosted AirApp can be served from `localhost`, and a standalone run can be reached over a dev tunnel, so both directions of that guess are wrong. Omitted, `pass()` falls back to probing `/auth/status` and treating an unreachable or non-JSON answer as hosted; that works, but it infers something you already know.
+
+Import `busabase-sdk/airapp-gate.css` for the default look; every colour, radius, and font is a `--bb-gate-*` custom property, so an app themes it by overriding them rather than forking. To replace the markup entirely, pass `render` — `selectAirAppGateScreen()` and `describeAirAppSetupError()` are exported so a custom renderer reuses the state machine instead of re-deriving it.
+
 ## Data client entry points
 
 **`Busabase` class** — an ergonomic wrapper with namespaced methods (`bb.bases`, `bb.records`, `bb.changeRequests`, `bb.nodes`, `bb.views`, `bb.assets`, `bb.fileTrees`, `bb.files`, `bb.docs`, `bb.comments`, `bb.auditEvents`, `bb.agent`, `bb.agentTasks`, `bb.embedLinks`, `bb.search()`, `bb.grep()`, `bb.health()`, `bb.me()`). Drop to `bb.client` for the raw oRPC client (e.g. `bb.client.system.meta()`).

package/dist/airapp-gate.css

@@ -0,0 +1,296 @@
+/**
+ * Default styling for the AirApp connect gate (`busabase-sdk/airapp-gate`).
+ *
+ * Ported from the stylesheet 62 App-in-Skills carried as a byte-identical copy,
+ * minus the rules left over from the retired setup-gate (secret rows, ready
+ * pills, prompt blocks) that the gate never rendered.
+ *
+ * Every value an app is likely to want to change is a custom property, so an
+ * app themes the gate by overriding these on `:root` instead of forking the
+ * file — that is the whole reason this can live in the SDK without dictating
+ * anyone's design system.
+ *
+ *   :root { --bb-gate-accent: #7c3aed; --bb-gate-radius: 14px; }
+ *
+ * Load it however the app loads CSS:
+ *   <link rel="stylesheet" href="./vendor/airapp-gate.css">
+ */
+
+:root {
+  --bb-gate-accent: #1570ef;
+  --bb-gate-accent-contrast: #fff;
+  --bb-gate-accent-wash: #f5f9ff;
+  --bb-gate-surface: #fff;
+  --bb-gate-surface-muted: #f9fafb;
+  --bb-gate-text: #17202a;
+  --bb-gate-text-strong: #101828;
+  --bb-gate-text-muted: #667085;
+  --bb-gate-text-label: #344054;
+  --bb-gate-border: #d0d5dd;
+  --bb-gate-border-subtle: #eaecf0;
+  --bb-gate-danger: #b42318;
+  --bb-gate-scrim: color-mix(in srgb, #101828 72%, transparent);
+  --bb-gate-radius: 8px;
+  --bb-gate-radius-inner: 6px;
+  --bb-gate-font: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+html.bb-gate-active,
+html.bb-gate-active body {
+  overflow: hidden;
+}
+
+.bb-gate-overlay {
+  position: fixed;
+  inset: 0;
+  /* Below the max z-index so an app's own toast/portal layer can still sit on
+     top if it deliberately opts to. */
+  z-index: 2147483000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: var(--bb-gate-scrim);
+  font-family: var(--bb-gate-font);
+  color: var(--bb-gate-text);
+}
+
+.bb-gate-panel {
+  width: min(720px, 100%);
+  max-height: min(760px, calc(100vh - 48px));
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  overflow: hidden;
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius);
+  box-shadow: 0 24px 64px rgb(16 24 40 / 28%);
+}
+
+.bb-gate-head {
+  display: flex;
+  gap: 24px;
+  align-items: start;
+  justify-content: space-between;
+  padding: 22px 24px 18px;
+  border-bottom: 1px solid var(--bb-gate-border-subtle);
+}
+
+.bb-gate-head h1 {
+  margin: 0;
+  font-size: 22px;
+  line-height: 1.25;
+  letter-spacing: 0;
+}
+
+.bb-gate-head p {
+  margin: 6px 0 0;
+  color: var(--bb-gate-text-muted);
+  font-size: 14px;
+}
+
+.bb-gate-body {
+  overflow: auto;
+  padding: 20px 24px;
+}
+
+.bb-gate-body h2 {
+  margin: 0 0 12px;
+  font-size: 14px;
+  letter-spacing: 0;
+}
+
+.bb-gate-server-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.bb-gate-server-card {
+  min-height: 104px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 16px;
+  text-align: left;
+  color: var(--bb-gate-text-label);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: 7px;
+  cursor: pointer;
+}
+
+.bb-gate-server-card:hover {
+  border-color: var(--bb-gate-text-muted);
+}
+
+.bb-gate-server-card.is-selected {
+  border-color: var(--bb-gate-accent);
+  box-shadow: inset 0 0 0 1px var(--bb-gate-accent);
+  background: var(--bb-gate-accent-wash);
+}
+
+.bb-gate-server-card input {
+  flex: none;
+  margin: 0;
+}
+
+.bb-gate-server-card > span {
+  display: grid;
+  gap: 2px;
+}
+
+.bb-gate-server-card strong {
+  font-size: 15px;
+}
+
+.bb-gate-server-card span span {
+  color: var(--bb-gate-text-muted);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.bb-gate-custom-url {
+  display: grid;
+  gap: 6px;
+  margin-top: 16px;
+  padding: 16px;
+  border: 1px solid var(--bb-gate-border-subtle);
+  border-radius: 7px;
+  background: var(--bb-gate-surface-muted);
+  color: var(--bb-gate-text-label);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.bb-gate-custom-url[hidden] {
+  display: none;
+}
+
+.bb-gate-custom-url input {
+  min-width: 0;
+  min-height: 38px;
+  padding: 8px 10px;
+  color: var(--bb-gate-text-strong);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius-inner);
+  font: inherit;
+  font-weight: 400;
+}
+
+.bb-gate-space-select {
+  display: grid;
+  gap: 6px;
+  margin-top: 14px;
+  color: var(--bb-gate-text-label);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.bb-gate-space-select select {
+  min-height: 38px;
+  padding: 8px 10px;
+  color: var(--bb-gate-text-strong);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius-inner);
+  font: inherit;
+  font-weight: 400;
+}
+
+.bb-gate-error {
+  color: var(--bb-gate-danger);
+  font-size: 13px;
+}
+
+.bb-gate-note {
+  color: var(--bb-gate-text-muted);
+}
+
+.bb-gate-link {
+  color: var(--bb-gate-accent);
+  font-size: 13px;
+  font-weight: 650;
+  text-decoration: none;
+}
+
+.bb-gate-link:hover {
+  text-decoration: underline;
+}
+
+.bb-gate-footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 10px;
+  padding: 14px 24px;
+  border-top: 1px solid var(--bb-gate-border-subtle);
+  background: var(--bb-gate-surface);
+}
+
+.bb-gate-footer button {
+  min-height: 38px;
+  padding: 0 14px;
+  color: var(--bb-gate-text-label);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius-inner);
+  font-weight: 650;
+  cursor: pointer;
+}
+
+.bb-gate-footer .bb-gate-primary {
+  color: var(--bb-gate-accent-contrast);
+  background: var(--bb-gate-accent);
+  border-color: var(--bb-gate-accent);
+}
+
+.bb-gate-footer button:disabled {
+  opacity: 0.55;
+  cursor: wait;
+}
+
+@media (max-width: 600px) {
+  .bb-gate-overlay {
+    align-items: stretch;
+    padding: 0;
+  }
+
+  .bb-gate-panel {
+    width: 100%;
+    max-height: 100vh;
+    border: 0;
+    border-radius: 0;
+  }
+
+  .bb-gate-head {
+    padding: 18px 16px 14px;
+  }
+
+  .bb-gate-head h1 {
+    font-size: 19px;
+  }
+
+  .bb-gate-head p {
+    font-size: 13px;
+  }
+
+  .bb-gate-body {
+    padding: 16px;
+  }
+
+  .bb-gate-server-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .bb-gate-footer {
+    padding: 12px 16px;
+  }
+
+  .bb-gate-footer button {
+    min-width: 0;
+    flex: 1;
+    padding-inline: 8px;
+  }
+}

package/dist/airapp-gate.d.ts

@@ -0,0 +1,157 @@
+import { BusabaseAirAppAuthStatus } from './airapp-node.js';
+import './oauth-node.js';
+import './oauth.js';
+
+/**
+ * The AirApp connect gate — the browser half of local onboarding.
+ *
+ * `busabase-sdk/airapp-node` already owns the *flow* (PKCE, credential
+ * rotation, Space validation, the `/api/v1` proxy). This module owns the
+ * remaining copy-paste: deciding which of the three screens to show, and
+ * drawing them. 62 App-in-Skills carried a 160-line renderer whose only
+ * per-app difference was the display name interpolated into an HTML string,
+ * plus a byte-identical 290-line stylesheet — while the app-creator template
+ * grew a second, differently-classed implementation of the same three screens.
+ *
+ * Structure, deliberately: every decision and every piece of markup is a pure
+ * function of the gateway's status. The DOM is touched only in `mount` /
+ * `wire`. That is what makes the escaping (the one security-relevant part —
+ * `oauth_error` and Space names both come from outside) testable without a
+ * browser, and what lets an app swap the renderer without reimplementing the
+ * state machine.
+ *
+ * Import `busabase-sdk/airapp-gate.css` (or copy it) for the default look; it
+ * is themed entirely through custom properties.
+ *
+ * @example
+ * ```ts
+ * import { createAirAppConnectGate } from "busabase-sdk/airapp-gate";
+ *
+ * const gate = createAirAppConnectGate({
+ *   appName: "Kelly CRM",
+ *   onProvision: () => provider.provisionResources(),
+ * });
+ *
+ * // Before mounting the app shell:
+ * if (await gate.pass({ onReady: () => start() })) start();
+ *
+ * // When loading data fails because the workspace is not set up yet:
+ * gate.renderSetupRequired(error, () => start());
+ * ```
+ */
+
+/** Which screen the gate owes the operator right now. */
+type AirAppGateScreen = "connect" | "space" | "ready";
+/**
+ * Decide the screen from the gateway's status. Headless — a custom renderer
+ * should call this rather than re-deriving the rules from `connected`.
+ *
+ * Driven by `readiness`, with a fallback to the older `connected` /
+ * `requiresSpace` pair so an app can upgrade the SDK before its server.
+ */
+declare function selectAirAppGateScreen(status: Partial<BusabaseAirAppAuthStatus> | null | undefined): AirAppGateScreen;
+/** The five setup states, decoded into what the workspace screen needs to know. */
+interface AirAppSetupDescription {
+    code: string;
+    /** The message with its `CODE: ` prefix stripped. */
+    detail: string;
+    title: string;
+    /** Offer an "Initialize workspace" button. */
+    canProvision: boolean;
+    /** Offer a "Check again" button (the app cannot act; the operator can retry). */
+    canRetry: boolean;
+}
+/**
+ * Decode a setup failure. Accepts an `AirAppSetupError`, any `Error` whose
+ * message uses the historical `"CODE: detail"` shape, or a bare string — the
+ * generated apps throw all three spellings.
+ */
+declare function describeAirAppSetupError(error: unknown): AirAppSetupDescription;
+interface AirAppGateOptions {
+    /** Shown in the gate's prose, e.g. "Kelly CRM". The one per-app value. */
+    appName: string;
+    /**
+     * Where to mount. A selector, an element, or omitted to create and prepend
+     * `#busabaseAirAppGate` to `<body>`.
+     */
+    mount?: string | HTMLElement;
+    /** Prefix for the gateway routes; `""` means `/auth/status`, `/auth/start`, … */
+    authBasePath?: string;
+    /**
+     * Whether this run owes a gate at all. Return `false` for a Busabase-hosted
+     * AirApp (the ambient session owns auth) or for a demo/offline mode.
+     *
+     * **Pass this.** Omitted, `pass()` falls back to probing `/auth/status` and
+     * treating an unreachable or non-JSON answer as "hosted" — which works, but
+     * infers something the host already states outright. A Busabase-hosted AirApp
+     * is identified by the `BUSABASE_AIRAPP_RUNTIME` env var Busabase injects into
+     * the process it spawns, surfaced to the browser by the app's own server;
+     * never by hostname, iframe nesting, or path, since a hosted AirApp can be
+     * served from localhost and a standalone run can be reached over a dev tunnel.
+     */
+    shouldGate?: () => boolean | Promise<boolean>;
+    /** Injected for tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Called by the workspace screen's "Initialize workspace" button. */
+    onProvision?: () => Promise<unknown>;
+    /** Where the "open the demo" escape hatch points. Omit to hide it. */
+    demoHref?: string | null;
+    /** Replace the default markup wholesale while keeping the state machine. */
+    render?: AirAppGateRenderer;
+}
+interface AirAppGateRenderer {
+    connect(view: AirAppConnectView): string;
+    space(view: AirAppSpaceView): string;
+    workspace(view: AirAppWorkspaceView): string;
+}
+interface AirAppConnectView {
+    appName: string;
+    cloudBaseUrl: string;
+    /** Set when the operator is here because the session lapsed, not first-run. */
+    reconnect: boolean;
+    /** `?oauth_error=` from the callback redirect. Untrusted. */
+    oauthError: string;
+    authBasePath: string;
+}
+interface AirAppSpaceView {
+    appName: string;
+    baseUrl: string;
+    spaces: {
+        id: string;
+        name: string;
+    }[];
+}
+interface AirAppWorkspaceView extends AirAppSetupDescription {
+    appName: string;
+    demoHref: string | null;
+}
+/** HTML-escape. Every interpolation below goes through this. */
+declare const escapeHtml: (value: unknown) => string;
+/** The stock three screens. Pure string builders — no DOM, no fetch. */
+declare const defaultAirAppGateRenderer: AirAppGateRenderer;
+declare const DEFAULT_CLOUD_BASE_URL = "https://busabase.com";
+interface AirAppConnectGate {
+    /**
+     * Resolve the gate before the app shell mounts. `true` means the app may
+     * load data; `false` means a screen is up and waiting on the operator — call
+     * again after `onReady` fires.
+     */
+    pass(options?: {
+        onReady?: () => void;
+    }): Promise<boolean>;
+    /** Show the workspace screen for a setup error thrown while loading data. */
+    renderSetupRequired(error: unknown, onRetry: () => void): void;
+    /** Take the gate down and give scrolling back to the page. */
+    close(): void;
+    /** Fetch the gateway's status without rendering anything. */
+    status(): Promise<BusabaseAirAppAuthStatus | null>;
+}
+/**
+ * Build a gate bound to one app.
+ *
+ * Nothing is rendered until `pass()` decides a screen is owed, so it is safe to
+ * construct at module scope.
+ */
+declare function createAirAppConnectGate(options: AirAppGateOptions): AirAppConnectGate;
+
+export { type AirAppConnectGate, type AirAppConnectView, type AirAppGateOptions, type AirAppGateRenderer, type AirAppGateScreen, type AirAppSetupDescription, type AirAppSpaceView, type AirAppWorkspaceView, BusabaseAirAppAuthStatus, DEFAULT_CLOUD_BASE_URL, createAirAppConnectGate, defaultAirAppGateRenderer, describeAirAppSetupError, escapeHtml, selectAirAppGateScreen };