busabase-sdk 0.15.0 → 0.16.0

package/dist/airapp-gate.js

@@ -0,0 +1,238 @@
+// src/airapp-gate.ts
+function selectAirAppGateScreen(status) {
+  if (!status) return "connect";
+  switch (status.readiness) {
+    case "needs_connection":
+    case "needs_auth":
+      return "connect";
+    case "needs_space":
+      return "space";
+    case "ready":
+      return "ready";
+  }
+  if (!status.connected) return "connect";
+  return status.requiresSpace ? "space" : "ready";
+}
+function describeAirAppSetupError(error) {
+  const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : "";
+  const raw = String(
+    (typeof error === "object" && error !== null && "message" in error ? error.message : error) ?? "SETUP_REQUIRED"
+  );
+  const parsed = /^([A-Z_]+):\s*(.*)$/s.exec(raw);
+  const resolvedCode = code || parsed?.[1] || raw.trim() || "SETUP_REQUIRED";
+  const detail = parsed ? parsed[2] : code ? raw : "";
+  const pending = resolvedCode === "SETUP_PENDING";
+  const canProvision = resolvedCode === "SETUP_REQUIRED";
+  return {
+    code: resolvedCode,
+    detail,
+    title: pending ? "Waiting for workspace approval" : canProvision ? "Initialize the Busabase workspace" : "Workspace not ready",
+    canProvision,
+    canRetry: resolvedCode === "SETUP_PENDING" || resolvedCode === "SCHEMA_INCOMPLETE"
+  };
+}
+var escapeHtml = (value) => String(value ?? "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#039;");
+var panel = (labelledBy, head, body, footer) => `<div class="bb-gate-overlay"><section class="bb-gate-panel" role="dialog" aria-modal="true" aria-labelledby="${labelledBy}"><div class="bb-gate-head"><div>${head}</div></div><div class="bb-gate-body">${body}</div><div class="bb-gate-footer">${footer}</div></section></div>`;
+var defaultAirAppGateRenderer = {
+  connect(view) {
+    const head = `<h1 id="bbGateConnectTitle">Connect Busabase</h1><p>${escapeHtml(view.appName)} reads and writes through your Busabase workspace.</p>`;
+    const body = (view.oauthError ? `<p class="bb-gate-error" role="alert">${escapeHtml(view.oauthError)}</p>` : "") + (view.reconnect ? `<p class="bb-gate-note">Your session expired. Reconnect to continue.</p>` : "") + `<h2>Server</h2><div class="bb-gate-server-grid"><label class="bb-gate-server-card is-selected"><input type="radio" name="server_mode" value="cloud" checked><span><strong>Busabase Cloud</strong><span>${escapeHtml(hostOf(view.cloudBaseUrl))}</span></span></label><label class="bb-gate-server-card"><input type="radio" name="server_mode" value="custom"><span><strong>Custom server</strong><span>Self-hosted or enterprise address</span></span></label></div><label class="bb-gate-custom-url" data-custom-url hidden><span>Busabase URL</span><input type="url" name="custom_base_url" inputmode="url" placeholder="https://busabase.example.com" autocomplete="url"></label><input type="hidden" name="base_url" value="${escapeHtml(view.cloudBaseUrl)}">`;
+    const footer = `<span class="bb-gate-note">OAuth credentials stay on this machine (~/.busabase/airapps)</span><button class="bb-gate-primary" type="submit">Connect Busabase</button>`;
+    return `<form method="post" action="${escapeHtml(`${view.authBasePath}/auth/start`)}" data-connect-form>${panel("bbGateConnectTitle", head, body, footer)}</form>`;
+  },
+  space(view) {
+    const options = view.spaces.map(
+      (space) => `<option value="${escapeHtml(space.id)}">${escapeHtml(space.name)} \xB7 ${escapeHtml(space.id)}</option>`
+    ).join("");
+    const head = `<h1 id="bbGateSpaceTitle">Choose a Busabase Space</h1><p>Signed in to <strong>${escapeHtml(view.baseUrl)}</strong>. Choose where ${escapeHtml(view.appName)}'s data lives.</p>`;
+    const body = `<label class="bb-gate-space-select"><span>Space</span><select name="space_id" required>${options}</select></label><p class="bb-gate-error" data-space-error hidden></p>`;
+    const footer = `<span class="bb-gate-note">Resources are only checked after you confirm</span><button class="bb-gate-primary" type="submit">Use this Space</button>`;
+    return `<form data-space-form>${panel("bbGateSpaceTitle", head, body, footer)}</form>`;
+  },
+  workspace(view) {
+    const head = `<h1 id="bbGateWorkspaceTitle">${escapeHtml(view.title)}</h1>`;
+    const body = view.canProvision ? `<p>${escapeHtml(view.appName)} will create its Folder and Bases in the current Space.</p><p>Submitted as one idempotent Busabase ChangeRequest; nothing existing is deleted or repurposed.</p><p class="bb-gate-error" data-workspace-status hidden></p>` : `<p>${escapeHtml(view.detail)}</p><p>${escapeHtml(view.appName)} never asks you to create Nodes or Bases by hand, and never silently falls back to local data.</p><p class="bb-gate-error" data-workspace-status hidden></p>`;
+    const footer = (view.demoHref ? `<a class="bb-gate-link" href="${escapeHtml(view.demoHref)}">Open the read-only demo</a>` : "<span></span>") + (view.canProvision ? `<button class="bb-gate-primary" type="button" data-provision>Initialize workspace</button>` : view.canRetry ? `<button class="bb-gate-primary" type="button" data-retry>Check again</button>` : "");
+    return panel("bbGateWorkspaceTitle", head, body, footer);
+  }
+};
+var hostOf = (baseUrl) => {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+};
+var DEFAULT_CLOUD_BASE_URL = "https://busabase.com";
+function createAirAppConnectGate(options) {
+  const {
+    appName,
+    authBasePath = "",
+    onProvision,
+    demoHref = null,
+    render = defaultAirAppGateRenderer
+  } = options;
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const root = () => {
+    if (options.mount) {
+      const element2 = typeof options.mount === "string" ? document.querySelector(options.mount) : options.mount;
+      if (!element2) throw new Error(`AirApp gate mount not found: ${String(options.mount)}`);
+      document.documentElement.classList.add("bb-gate-active");
+      return element2;
+    }
+    let element = document.querySelector("#busabaseAirAppGate");
+    if (!element) {
+      element = document.createElement("div");
+      element.id = "busabaseAirAppGate";
+      document.body.prepend(element);
+    }
+    document.documentElement.classList.add("bb-gate-active");
+    return element;
+  };
+  const close = () => {
+    if (options.mount) {
+      const element = typeof options.mount === "string" ? document.querySelector(options.mount) : options.mount;
+      if (element) element.innerHTML = "";
+    } else {
+      document.querySelector("#busabaseAirAppGate")?.remove();
+    }
+    document.documentElement.classList.remove("bb-gate-active");
+  };
+  const status = async () => {
+    try {
+      const response = await doFetch(`${authBasePath}/auth/status`, {
+        headers: { accept: "application/json" }
+      });
+      const type = response.headers.get("content-type") ?? "";
+      if (!response.ok || !type.includes("application/json")) return null;
+      return await response.json();
+    } catch {
+      return null;
+    }
+  };
+  const renderConnect = (current) => {
+    const element = root();
+    const oauthError = new URLSearchParams(window.location.search).get("oauth_error") ?? "";
+    element.innerHTML = render.connect({
+      appName,
+      cloudBaseUrl: current?.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL,
+      reconnect: current?.readiness === "needs_auth",
+      oauthError,
+      authBasePath
+    });
+    wireConnect(element, current?.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL);
+  };
+  const renderSpace = (current, onReady) => {
+    const element = root();
+    element.innerHTML = render.space({
+      appName,
+      baseUrl: current.baseUrl ?? "",
+      spaces: current.spaces ?? []
+    });
+    wireSpace(element, onReady);
+  };
+  const wireConnect = (element, cloudBaseUrl) => {
+    const form = element.querySelector("[data-connect-form]");
+    if (!form) return;
+    const customField = form.querySelector("[data-custom-url]");
+    const customInput = customField?.querySelector("input") ?? null;
+    const hiddenBaseUrl = form.querySelector('input[name="base_url"]');
+    for (const radio of form.querySelectorAll('input[name="server_mode"]')) {
+      radio.addEventListener("change", () => {
+        const custom = radio.value === "custom";
+        for (const card of form.querySelectorAll(".bb-gate-server-card")) {
+          card.classList.toggle("is-selected", card.querySelector("input")?.checked === true);
+        }
+        if (customField) customField.hidden = !custom;
+        if (customInput) customInput.required = custom;
+        if (hiddenBaseUrl) hiddenBaseUrl.value = custom ? customInput?.value ?? "" : cloudBaseUrl;
+        if (custom) customInput?.focus();
+      });
+    }
+    customInput?.addEventListener("input", () => {
+      if (hiddenBaseUrl) hiddenBaseUrl.value = customInput.value;
+    });
+  };
+  const wireSpace = (element, onReady) => {
+    const form = element.querySelector("[data-space-form]");
+    form?.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      const button = form.querySelector("button[type=submit]");
+      const error = form.querySelector("[data-space-error]");
+      if (button) button.disabled = true;
+      if (error) error.hidden = true;
+      try {
+        const response = await doFetch(`${authBasePath}/auth/space`, {
+          method: "POST",
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+          body: new URLSearchParams(new FormData(form))
+        });
+        const result = await response.json();
+        if (!response.ok) {
+          if (error) {
+            error.textContent = result.error || "Could not select a Space.";
+            error.hidden = false;
+          }
+          if (button) button.disabled = false;
+          return;
+        }
+        onReady();
+      } catch {
+        if (error) {
+          error.textContent = "Could not reach this app's server.";
+          error.hidden = false;
+        }
+        if (button) button.disabled = false;
+      }
+    });
+  };
+  const renderSetupRequired = (error, onRetry) => {
+    const element = root();
+    element.innerHTML = render.workspace({
+      ...describeAirAppSetupError(error),
+      appName,
+      demoHref
+    });
+    element.querySelector("[data-retry]")?.addEventListener("click", () => onRetry());
+    element.querySelector("[data-provision]")?.addEventListener("click", async (event) => {
+      const button = event.currentTarget;
+      const line = element.querySelector("[data-workspace-status]");
+      button.disabled = true;
+      if (line) {
+        line.hidden = false;
+        line.textContent = "Submitting the workspace structure\u2026";
+      }
+      try {
+        await onProvision?.();
+        onRetry();
+      } catch (provisionError) {
+        renderSetupRequired(provisionError, onRetry);
+      }
+    });
+  };
+  const pass = async ({ onReady } = {}) => {
+    if (options.shouldGate && !await options.shouldGate()) {
+      close();
+      return true;
+    }
+    const current = await status();
+    if (!current) return true;
+    const screen = selectAirAppGateScreen(current);
+    if (screen === "ready") {
+      close();
+      return true;
+    }
+    if (screen === "space") {
+      renderSpace(current, () => {
+        close();
+        onReady?.();
+      });
+      return false;
+    }
+    renderConnect(current);
+    return false;
+  };
+  return { pass, renderSetupRequired, close, status };
+}
+
+export { DEFAULT_CLOUD_BASE_URL, createAirAppConnectGate, defaultAirAppGateRenderer, describeAirAppSetupError, escapeHtml, selectAirAppGateScreen };

package/dist/airapp-node.js

@@ -1,5 +1,5 @@
-import { getBusabaseAirAppAccessToken, storeBusabaseAirAppSelectedSpace, storeBusabaseAirAppOAuthCredential, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential } from './chunk-B2AWPFDI.js';
-import { BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, createBusabaseOAuthRequest, parseBusabaseOAuthCallback, exchangeBusabaseOAuthCode } from './chunk-J2DZKX7A.js';
+import { getBusabaseAirAppAccessToken, storeBusabaseAirAppSelectedSpace, loadBusabaseAirAppDynamicClientId, storeBusabaseAirAppDynamicClientId, storeBusabaseAirAppOAuthCredential, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential } from './chunk-C23JVY2Y.js';
+import { BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, registerBusabaseAirAppOAuthClient, createBusabaseOAuthRequest, parseBusabaseOAuthCallback, exchangeBusabaseOAuthCode } from './chunk-WSHJMHUS.js';
 import './chunk-5NYQX65A.js';
 
 // src/airapp-node.ts
@@ -22,6 +22,7 @@ var jsonError = (status, reason, message, data) => Response.json(
   },
   { status }
 );
+var LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "::1", "[::1]"];
 var normalizeOrigin = (raw, fallback = DEFAULT_CLOUD_BASE_URL) => {
   const withoutApi = String(raw || fallback).trim().replace(/\/+$/, "").replace(/\/api\/v1$/, "");
   let url;
@@ -33,7 +34,7 @@ var normalizeOrigin = (raw, fallback = DEFAULT_CLOUD_BASE_URL) => {
   if (url.username || url.password || url.search || url.hash || url.pathname !== "/" && url.pathname !== "") {
     throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL must be an origin");
   }
-  const loopback = ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+  const loopback = LOOPBACK_HOSTNAMES.includes(url.hostname);
   if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
     throw new BusabaseOAuthError(
       "invalid_base_url",
@@ -43,6 +44,10 @@ var normalizeOrigin = (raw, fallback = DEFAULT_CLOUD_BASE_URL) => {
   return url.origin;
 };
 var requestOrigin = (request) => new URL(request.url).origin;
+var isLoopbackOrigin = (origin) => {
+  const url = new URL(origin);
+  return url.protocol === "http:" && LOOPBACK_HOSTNAMES.includes(url.hostname);
+};
 var assertSameOrigin = (request) => {
   const origin = request.headers.get("origin");
   if (origin && origin !== requestOrigin(request)) {
@@ -61,8 +66,10 @@ var safeSpaces = (spaces) => spaces.map(({ id, name, slug, plan }) => ({ id, nam
 var BusabaseAirAppLocalGateway = class {
   #options;
   #pendingOAuth = /* @__PURE__ */ new Map();
+  #usesDefaultClient;
   #environmentSelectedSpace;
   constructor(options) {
+    this.#usesDefaultClient = !options.clientId;
     this.#options = {
       ...options,
       appId: options.appId,
@@ -211,22 +218,46 @@ var BusabaseAirAppLocalGateway = class {
     }
   }
   statusResponse = async () => Response.json(await this.status());
+  /** Resolve the client for this callback, then probe the authorize endpoint with it. */
+  async #startAuthorization(target, needsDynamicClient, forceRegistration) {
+    let clientId = this.#options.clientId;
+    let reusedStoredClient = false;
+    if (needsDynamicClient) {
+      const stored = forceRegistration ? null : loadBusabaseAirAppDynamicClientId(target, this.#options.credentialStore);
+      if (stored) {
+        clientId = stored;
+        reusedStoredClient = true;
+      } else {
+        const registration = await registerBusabaseAirAppOAuthClient(target, this.#fetch());
+        clientId = registration.clientId;
+        storeBusabaseAirAppDynamicClientId({ ...target, clientId }, this.#options.credentialStore);
+      }
+    }
+    const oauthRequest = await createBusabaseOAuthRequest({
+      baseUrl: target.baseUrl,
+      redirectUri: target.redirectUri,
+      clientId
+    });
+    const probe = await this.#fetch()(oauthRequest.authorizeUrl, {
+      headers: { accept: "text/html" },
+      redirect: "manual",
+      signal: AbortSignal.timeout(this.#options.requestTimeoutMs)
+    });
+    return { oauthRequest, probe, reusedStoredClient };
+  }
   start = async (request) => {
     try {
       assertSameOrigin(request);
       const body = await readInput(request);
       const baseUrl = normalizeOrigin(String(body.base_url || ""), this.cloudBaseUrl);
       const redirectUri = new URL("/auth/callback", requestOrigin(request)).toString();
-      const oauthRequest = await createBusabaseOAuthRequest({
-        baseUrl,
-        redirectUri,
-        clientId: this.#options.clientId
-      });
-      const probe = await this.#fetch()(oauthRequest.authorizeUrl, {
-        headers: { accept: "text/html" },
-        redirect: "manual",
-        signal: AbortSignal.timeout(this.#options.requestTimeoutMs)
-      });
+      const needsDynamicClient = this.#usesDefaultClient && !isLoopbackOrigin(requestOrigin(request));
+      const target = { appId: this.#options.appId, baseUrl, redirectUri };
+      let attempt = await this.#startAuthorization(target, needsDynamicClient, false);
+      if (attempt.probe.status >= 400 && attempt.reusedStoredClient) {
+        attempt = await this.#startAuthorization(target, needsDynamicClient, true);
+      }
+      const { oauthRequest, probe } = attempt;
       if (probe.status >= 400) {
         throw new BusabaseOAuthError(
           "oauth_unavailable",
@@ -263,7 +294,7 @@ var BusabaseAirAppLocalGateway = class {
         {
           appId: this.#options.appId,
           baseUrl: pending.baseUrl,
-          clientId: this.#options.clientId,
+          clientId: pending.clientId,
           tokenSet
         },
         this.#options.credentialStore

package/dist/airapp.d.ts

@@ -0,0 +1,222 @@
+import { B as BusabaseClient } from './client-DB7fREZX.js';
+import '@orpc/contract';
+import '@orpc/shared';
+import 'zod';
+
+/**
+ * AirApp resource provisioning — how an app claims (or creates) the Folder and
+ * Bases it declares, exactly once, without ever taking over someone else's.
+ *
+ * Every App-in-Skill shipped a byte-identical copy of this module (280 lines ×
+ * 65 apps, two spellings). That is the wrong place for it: the rules encoded
+ * here are not app preferences, they are the safety boundary that keeps an app
+ * from adopting a Folder a human created for something else. A third party
+ * re-deriving them from scratch gets the happy path right and the conflict
+ * cases wrong, and the failure is silent — the app happily writes into data it
+ * does not own.
+ *
+ * The contract, in one line: **an app owns a node only if it stamped it.**
+ * Ownership lives in `node.metadata` as `{ appId, resourceKey, schemaVersion }`.
+ * Anything else is either a legacy node this app plausibly created before
+ * stamping existed (claimable *only* after a full structural fingerprint match)
+ * or someone else's (never touched, always a `SETUP_CONFLICT`).
+ *
+ * This module is isomorphic — browser and Node both — and holds no I/O beyond
+ * the passed-in client.
+ *
+ * @example
+ * ```ts
+ * import { createBusabaseClient } from "busabase-sdk";
+ * import { inspectProvisionedResources, provisionDeclaredResources } from "busabase-sdk/airapp";
+ *
+ * const client = createBusabaseClient({ baseUrl: window.location.origin });
+ * 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); // one idempotent ChangeRequest
+ * }
+ * ```
+ */
+
+type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
+type NodeOperationInput = NodeChangeRequestInput["operations"][number];
+type CreateNodeOperationInput = Extract<NodeOperationInput, {
+    kind: "create";
+}>;
+/**
+ * A Base field, typed straight off the contract so a declaration can never drift
+ * from what `nodes.createChangeRequest` actually accepts.
+ */
+type AirAppFieldDeclaration = NonNullable<CreateNodeOperationInput["fields"]>[number];
+/** The client surface provisioning needs. Both `BusabaseClient` and `Busabase` satisfy it. */
+type AirAppProvisioningClient = Pick<BusabaseClient, "nodes" | "bases">;
+/** One Base the app declares it needs. `key` is the app's stable internal handle. */
+interface AirAppBaseDeclaration {
+    /** Stable internal handle, e.g. `"contacts"`. Also the node's `resourceKey`. */
+    key: string;
+    slug: string;
+    name: string;
+    description?: string;
+    fields: AirAppFieldDeclaration[];
+    /** Resolved at provision time; ignore when declaring. */
+    nodeId?: string;
+    /** Resolved at provision time; ignore when declaring. */
+    baseId?: string;
+    /** Free-form extras an app keeps alongside its declaration (e.g. `readLimit`). */
+    [extra: string]: unknown;
+}
+interface AirAppFolderDeclaration {
+    slug: string;
+    name: string;
+    description?: string;
+    /** Pin the Folder by id once known; otherwise it is discovered by slug. */
+    nodeId?: string;
+}
+/**
+ * The app's own AirApp node, when it ships one inside its Folder.
+ *
+ * It is provisioned by publishing the AirApp, not by this module — so it is
+ * never created here, only recognized and stamped. Declaring it matters for a
+ * second reason: without it, an unstamped Folder holding the app's own AirApp
+ * would look like it holds an unattributable stranger, and the legacy claim
+ * would be refused.
+ */
+interface AirAppNodeDeclaration {
+    slug: string;
+    name: string;
+    /** Ownership key written into the node's metadata, e.g. `"airapp"`. */
+    resourceKey: string;
+}
+/** Everything an app declares about the workspace shape it needs. */
+interface AirAppResourceConfig {
+    appId: string;
+    appName: string;
+    /**
+     * Bump when the declared shape changes. A node stamped with an older version
+     * is re-stamped (a "repair"), not recreated — the data survives.
+     */
+    schemaVersion: number;
+    folder: AirAppFolderDeclaration;
+    bases: AirAppBaseDeclaration[];
+    /** The app's own AirApp node inside the Folder, when it ships one. */
+    airApp?: AirAppNodeDeclaration;
+}
+/**
+ * The ownership stamp written into `node.metadata`.
+ *
+ * A type alias rather than an `interface` on purpose: `nodes.updateMetadata`
+ * and the create operations take `Record<string, unknown>`, and an interface —
+ * being open to declaration merging — is not assignable to an index signature.
+ */
+type AirAppResourceOwnership = {
+    appId: string;
+    resourceKey: string;
+    schemaVersion: number;
+};
+/** A node this app owns but whose ownership stamp needs (re)writing. */
+interface AirAppOwnershipRepair {
+    nodeId: string;
+    baseId?: string;
+    resourceKey: string;
+    metadata: AirAppResourceOwnership;
+}
+interface AirAppProvisionedBase extends AirAppBaseDeclaration {
+    nodeId: string;
+    baseId: string;
+}
+interface AirAppResources {
+    /** The app's root Folder, or `null` when it does not exist yet. */
+    folder: (AirAppFolderDeclaration & {
+        nodeId: string;
+    }) | null;
+    /** Declared Bases that exist and are owned, with their resolved ids. */
+    bases: AirAppProvisionedBase[];
+    /** Declared Bases that do not exist yet. */
+    missing: AirAppBaseDeclaration[];
+    /** Owned nodes whose ownership stamp is missing or stale. */
+    repairs: AirAppOwnershipRepair[];
+    /**
+     * Set when the server is too old for `nodes.updateMetadata`, so ownership was
+     * established by full structural fingerprint instead of a stamp.
+     */
+    compatibilityMode?: "verified-legacy-fingerprint";
+}
+/**
+ * Why setup cannot proceed. These are the app's five distinguishable states —
+ * each one wants a different screen, which is why they are codes and not prose.
+ *
+ * - `SETUP_REQUIRED` — nothing exists yet; offer to initialize.
+ * - `SETUP_PENDING` — the ChangeRequest was submitted and awaits human approval.
+ * - `SETUP_CONFLICT` — a node in the way is not this app's; nothing was changed.
+ * - `SETUP_PERMISSION` — this account may not create/repair here.
+ * - `SCHEMA_INCOMPLETE` — the change merged but read back incomplete.
+ */
+type AirAppSetupCode = "SETUP_REQUIRED" | "SETUP_PENDING" | "SETUP_CONFLICT" | "SETUP_PERMISSION" | "SCHEMA_INCOMPLETE";
+/**
+ * A setup failure carrying its state as a `code`.
+ *
+ * `message` is deliberately kept in the historical `"CODE: detail"` shape: the
+ * generated apps parse the prefix off `error.message`, so an app can migrate to
+ * this class without touching its rendering code, then move to `error.code`.
+ */
+declare class AirAppSetupError extends Error {
+    readonly code: AirAppSetupCode;
+    /** The human-readable half, without the `CODE: ` prefix. */
+    readonly detail: string;
+    constructor(code: AirAppSetupCode, detail: string);
+}
+/** True for a 404 / NOT_FOUND from any of the client's transports. */
+declare const isNotFound: (error: unknown) => boolean;
+/** A node as this module reads it — the fields provisioning actually looks at. */
+interface ReadNode {
+    id: string;
+    type: string;
+    slug: string;
+    name: string;
+    description: string;
+    baseId: string | null;
+    metadata: Record<string, unknown>;
+    children?: ReadNode[];
+}
+interface ReadFolderDetail {
+    node: ReadNode;
+    children: ReadNode[];
+}
+/**
+ * Decide, from one already-read Folder, what exists / is missing / needs
+ * re-stamping. Pure — no I/O — so the ownership rules are directly testable.
+ *
+ * @throws {AirAppSetupError} `SETUP_CONFLICT` when a node in the way is not
+ * this app's. Nothing is ever mutated on that path.
+ */
+declare function resolveProvisionedFolder(folder: ReadFolderDetail | null | undefined, config: AirAppResourceConfig): AirAppResources;
+/**
+ * The create operations for one idempotent ChangeRequest. Pure.
+ *
+ * When the Folder does not exist yet it is created under the temp `ref`
+ * `"app-root"` and the Bases nest under it via `parentNodeRef`, so the whole
+ * structure lands in a single reviewable change.
+ */
+declare function buildProvisionOperations(config: AirAppResourceConfig, folder: {
+    nodeId: string;
+} | null, missingBases: AirAppBaseDeclaration[]): NodeOperationInput[];
+/** Read the current state of this app's declared resources. Never mutates. */
+declare function inspectProvisionedResources(client: AirAppProvisioningClient, config: AirAppResourceConfig): Promise<AirAppResources>;
+/**
+ * Ensure the declared Folder and Bases exist, as one idempotent ChangeRequest.
+ *
+ * Safe to call concurrently: calls for the same client + `appId` share one
+ * in-flight promise, so a multi-pane app cannot submit the structure twice.
+ *
+ * @throws {AirAppSetupError} with a `code` describing which screen to show.
+ */
+declare function provisionDeclaredResources(client: AirAppProvisioningClient, config: AirAppResourceConfig): Promise<AirAppResources>;
+
+export { type AirAppBaseDeclaration, type AirAppFieldDeclaration, type AirAppFolderDeclaration, type AirAppNodeDeclaration, type AirAppOwnershipRepair, type AirAppProvisionedBase, type AirAppProvisioningClient, type AirAppResourceConfig, type AirAppResourceOwnership, type AirAppResources, type AirAppSetupCode, AirAppSetupError, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, resolveProvisionedFolder };