busabase-sdk 0.14.1 → 0.16.0

package/dist/airapp-node.js

@@ -0,0 +1,439 @@
+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
+var DEFAULT_CLOUD_BASE_URL = "https://busabase.com";
+var DEFAULT_PENDING_TTL_MS = 5 * 6e4;
+var DEFAULT_TIMEOUT_MS = 8e3;
+var BUSABASE_AIRAPP_GATEWAY_REASONS = {
+  authRequired: "AUTH_REQUIRED",
+  authUnavailable: "AUTH_UNAVAILABLE",
+  connectionRequired: "CONNECTION_REQUIRED",
+  oauthCallbackInvalid: "OAUTH_CALLBACK_INVALID",
+  spaceNotAllowed: "SPACE_NOT_ALLOWED",
+  spaceSelectionRequired: "SPACE_SELECTION_REQUIRED"
+};
+var jsonError = (status, reason, message, data) => Response.json(
+  {
+    error: message,
+    code: status === 401 ? "UNAUTHORIZED" : status === 403 ? "FORBIDDEN" : status === 409 ? "CONFLICT" : status === 503 ? "SERVICE_UNAVAILABLE" : "BAD_REQUEST",
+    data: { reason, ...data }
+  },
+  { 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;
+  try {
+    url = new URL(withoutApi);
+  } catch {
+    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL is invalid");
+  }
+  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 = LOOPBACK_HOSTNAMES.includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new BusabaseOAuthError(
+      "invalid_base_url",
+      "Busabase requires HTTPS except for a loopback development server"
+    );
+  }
+  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)) {
+    throw new BusabaseOAuthError("origin_mismatch", "Request origin did not match");
+  }
+};
+var readInput = async (request) => {
+  const contentType = request.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    return await request.json().catch(() => ({}));
+  }
+  const form = await request.formData().catch(() => new FormData());
+  return Object.fromEntries(form.entries());
+};
+var safeSpaces = (spaces) => spaces.map(({ id, name, slug, plan }) => ({ id, name, slug, plan }));
+var BusabaseAirAppLocalGateway = class {
+  #options;
+  #pendingOAuth = /* @__PURE__ */ new Map();
+  #usesDefaultClient;
+  #environmentSelectedSpace;
+  constructor(options) {
+    this.#usesDefaultClient = !options.clientId;
+    this.#options = {
+      ...options,
+      appId: options.appId,
+      cloudBaseUrl: normalizeOrigin(options.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL),
+      clientId: options.clientId || BUSABASE_AIRAPP_CLIENT_ID,
+      oauthPendingTtlMs: options.oauthPendingTtlMs ?? DEFAULT_PENDING_TTL_MS,
+      requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+      successPath: options.successPath || "/",
+      errorPath: options.errorPath || "/"
+    };
+  }
+  get cloudBaseUrl() {
+    return this.#options.cloudBaseUrl;
+  }
+  #fetch() {
+    return this.#options.fetch ?? fetch;
+  }
+  #now() {
+    return this.#options.now?.() ?? Date.now();
+  }
+  #environment() {
+    return this.#options.environment ?? process.env;
+  }
+  async #target() {
+    const environment = this.#environment();
+    if (environment.BUSABASE_BASE_URL) {
+      const selectedSpaceId = environment.BUSABASE_SPACE_ID?.trim();
+      return {
+        baseUrl: normalizeOrigin(environment.BUSABASE_BASE_URL),
+        accessToken: environment.BUSABASE_API_KEY || "",
+        source: environment.BUSABASE_API_KEY ? "environment" : "open-server",
+        ...selectedSpaceId ? { selectedSpace: { id: selectedSpaceId, name: selectedSpaceId } } : this.#environmentSelectedSpace ? { selectedSpace: this.#environmentSelectedSpace } : {}
+      };
+    }
+    const credential = await getBusabaseAirAppAccessToken(
+      this.#options.appId,
+      this.#options.credentialStore,
+      this.#fetch()
+    );
+    return credential ? {
+      baseUrl: credential.baseUrl,
+      accessToken: credential.accessToken,
+      source: "airapp-oauth-local",
+      ...credential.selectedSpace ? { selectedSpace: credential.selectedSpace } : {}
+    } : null;
+  }
+  async #authInfo(target, spaceId = "") {
+    const headers = new Headers({ accept: "application/json" });
+    if (target.accessToken) headers.set("authorization", `Bearer ${target.accessToken}`);
+    if (spaceId) headers.set("x-busabase-space", spaceId);
+    const response = await this.#fetch()(new URL("/api/v1/auth", target.baseUrl), {
+      headers,
+      signal: AbortSignal.timeout(this.#options.requestTimeoutMs)
+    });
+    if (!response.ok) {
+      throw new BusabaseOAuthError(
+        response.status === 401 ? "auth_required" : "auth_verification_failed",
+        `Busabase auth verification failed (${response.status})`,
+        response.status
+      );
+    }
+    const info = await response.json();
+    if (!Array.isArray(info.spaces)) {
+      throw new BusabaseOAuthError(
+        "invalid_auth_response",
+        "Busabase auth response did not include Spaces"
+      );
+    }
+    return info;
+  }
+  #persistSelectedSpace(target, selectedSpace) {
+    if (target.source === "airapp-oauth-local") {
+      storeBusabaseAirAppSelectedSpace(
+        this.#options.appId,
+        selectedSpace ? { id: selectedSpace.id, name: selectedSpace.name } : null,
+        this.#options.credentialStore
+      );
+    } else {
+      this.#environmentSelectedSpace = selectedSpace || void 0;
+    }
+  }
+  async status() {
+    let target = null;
+    try {
+      target = await this.#target();
+      if (!target) {
+        return {
+          connected: false,
+          cloudBaseUrl: this.cloudBaseUrl,
+          readiness: "needs_connection",
+          action: "connect",
+          reason: BUSABASE_AIRAPP_GATEWAY_REASONS.connectionRequired
+        };
+      }
+      const info = await this.#authInfo(target);
+      const spaces = safeSpaces(info.spaces);
+      if (!spaces.length) {
+        this.#persistSelectedSpace(target, null);
+        return {
+          connected: true,
+          cloudBaseUrl: this.cloudBaseUrl,
+          baseUrl: target.baseUrl,
+          source: target.source,
+          readiness: "needs_space",
+          action: "retry",
+          requiresSpace: true,
+          selectedSpace: null,
+          space: null,
+          spaces,
+          reason: BUSABASE_AIRAPP_GATEWAY_REASONS.spaceSelectionRequired,
+          message: "This account has no accessible Busabase Space"
+        };
+      }
+      const selectedSpaceId = target.selectedSpace?.id;
+      let selected = selectedSpaceId ? spaces.find((space) => space.id === selectedSpaceId) : void 0;
+      if (!selected && spaces.length === 1) selected = spaces[0];
+      if (target.selectedSpace && !selected) this.#persistSelectedSpace(target, null);
+      if (selected && selected.id !== selectedSpaceId) {
+        await this.#authInfo(target, selected.id);
+        this.#persistSelectedSpace(target, selected);
+      }
+      return {
+        connected: true,
+        cloudBaseUrl: this.cloudBaseUrl,
+        baseUrl: target.baseUrl,
+        source: target.source,
+        readiness: selected ? "ready" : "needs_space",
+        action: selected ? "continue" : "select_space",
+        requiresSpace: !selected,
+        selectedSpace: selected || null,
+        space: selected || null,
+        spaces,
+        ...selected ? {} : { reason: BUSABASE_AIRAPP_GATEWAY_REASONS.spaceSelectionRequired }
+      };
+    } catch (error) {
+      const authRequired = error instanceof BusabaseOAuthError && error.status === 401;
+      return {
+        connected: Boolean(target) && !authRequired,
+        cloudBaseUrl: this.cloudBaseUrl,
+        ...target ? { baseUrl: target.baseUrl, source: target.source, requiresSpace: true } : {},
+        readiness: authRequired ? "needs_auth" : "retry",
+        action: authRequired ? "reconnect" : "retry",
+        reason: authRequired ? BUSABASE_AIRAPP_GATEWAY_REASONS.authRequired : BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        message: error instanceof Error ? error.message : "Busabase auth verification failed"
+      };
+    }
+  }
+  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 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",
+          `Busabase OAuth is unavailable (${probe.status})`,
+          probe.status
+        );
+      }
+      this.#pendingOAuth.set(oauthRequest.state, {
+        ...oauthRequest,
+        expiresAt: this.#now() + this.#options.oauthPendingTtlMs
+      });
+      return Response.redirect(oauthRequest.authorizeUrl, 303);
+    } catch (error) {
+      const redirect = new URL(this.#options.errorPath, requestOrigin(request));
+      redirect.searchParams.set(
+        "oauth_error",
+        error instanceof Error ? error.message : "Unable to start Busabase OAuth"
+      );
+      return Response.redirect(redirect, 303);
+    }
+  };
+  callback = async (request) => {
+    const callback = new URL(request.url);
+    const state = callback.searchParams.get("state") || "";
+    const pending = this.#pendingOAuth.get(state);
+    this.#pendingOAuth.delete(state);
+    try {
+      if (!pending || pending.expiresAt <= this.#now()) {
+        throw new BusabaseOAuthError("oauth_request_expired", "OAuth request expired");
+      }
+      const code = parseBusabaseOAuthCallback(callback.toString(), pending);
+      const tokenSet = await exchangeBusabaseOAuthCode(pending, code, this.#fetch());
+      storeBusabaseAirAppOAuthCredential(
+        {
+          appId: this.#options.appId,
+          baseUrl: pending.baseUrl,
+          clientId: pending.clientId,
+          tokenSet
+        },
+        this.#options.credentialStore
+      );
+      return Response.redirect(new URL(this.#options.successPath, requestOrigin(request)), 303);
+    } catch (error) {
+      const redirect = new URL(this.#options.errorPath, requestOrigin(request));
+      redirect.searchParams.set(
+        "oauth_error",
+        error instanceof Error ? error.message : "Busabase OAuth callback failed"
+      );
+      return Response.redirect(redirect, 303);
+    }
+  };
+  selectSpace = async (request) => {
+    try {
+      assertSameOrigin(request);
+      const body = await readInput(request);
+      const spaceId = String(body.space_id || "").trim();
+      const target = await this.#target();
+      if (!target) {
+        return jsonError(
+          401,
+          BUSABASE_AIRAPP_GATEWAY_REASONS.connectionRequired,
+          "Connect Busabase before selecting a Space"
+        );
+      }
+      const info = await this.#authInfo(target);
+      const selected = info.spaces.find((space) => space.id === spaceId);
+      if (!selected) {
+        return jsonError(
+          403,
+          BUSABASE_AIRAPP_GATEWAY_REASONS.spaceNotAllowed,
+          "The selected Space is not accessible to this account"
+        );
+      }
+      await this.#authInfo(target, selected.id);
+      this.#persistSelectedSpace(target, selected);
+      return Response.json({ ok: true, space: { id: selected.id, name: selected.name } });
+    } catch (error) {
+      return jsonError(
+        400,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        error instanceof Error ? error.message : "Unable to select Busabase Space"
+      );
+    }
+  };
+  logout = async (request) => {
+    try {
+      assertSameOrigin(request);
+      if (loadBusabaseAirAppOAuthCredential(this.#options.appId, this.#options.credentialStore)) {
+        await revokeBusabaseAirAppOAuthCredential(
+          this.#options.appId,
+          this.#options.credentialStore,
+          this.#fetch()
+        ).catch(() => void 0);
+      }
+      this.#environmentSelectedSpace = void 0;
+      return Response.json({ ok: true });
+    } catch (error) {
+      return jsonError(
+        400,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        error instanceof Error ? error.message : "Unable to disconnect Busabase"
+      );
+    }
+  };
+  proxy = async (request) => {
+    let target;
+    try {
+      target = await this.#target();
+    } catch {
+      return jsonError(
+        401,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authRequired,
+        "Busabase authentication expired"
+      );
+    }
+    if (!target) {
+      return jsonError(
+        401,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.connectionRequired,
+        "Busabase connection required"
+      );
+    }
+    let selectedSpace = target.selectedSpace;
+    if (!selectedSpace) {
+      try {
+        const info = await this.#authInfo(target);
+        if (info.spaces.length === 1) {
+          selectedSpace = info.spaces[0];
+          this.#persistSelectedSpace(target, selectedSpace);
+        }
+      } catch {
+        return jsonError(
+          503,
+          BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+          "Busabase authentication could not be verified"
+        );
+      }
+    }
+    if (!selectedSpace) {
+      return jsonError(
+        409,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.spaceSelectionRequired,
+        "Busabase Space selection required"
+      );
+    }
+    const incoming = new URL(request.url);
+    const targetUrl = new URL(incoming.pathname + incoming.search, target.baseUrl);
+    const headers = new Headers();
+    const contentType = request.headers.get("content-type");
+    const accept = request.headers.get("accept");
+    if (contentType) headers.set("content-type", contentType);
+    if (accept) headers.set("accept", accept);
+    headers.set("x-busabase-space", selectedSpace.id);
+    if (target.accessToken) headers.set("authorization", `Bearer ${target.accessToken}`);
+    const hasBody = request.method !== "GET" && request.method !== "HEAD";
+    let upstream;
+    try {
+      upstream = await this.#fetch()(targetUrl, {
+        method: request.method,
+        headers,
+        body: hasBody ? await request.arrayBuffer() : void 0,
+        redirect: "manual"
+      });
+    } catch {
+      return jsonError(
+        503,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        "Busabase API is temporarily unavailable"
+      );
+    }
+    const responseHeaders = new Headers();
+    const upstreamType = upstream.headers.get("content-type");
+    if (upstreamType) responseHeaders.set("content-type", upstreamType);
+    return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+  };
+};
+var createBusabaseAirAppLocalGateway = (options) => new BusabaseAirAppLocalGateway(options);
+
+export { BUSABASE_AIRAPP_GATEWAY_REASONS, BusabaseAirAppLocalGateway, createBusabaseAirAppLocalGateway };

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 };