busabase-sdk 0.17.3 → 0.19.0

package/dist/airapp.d.ts

@@ -1,56 +1,11 @@
-import { B as BusabaseClient } from './client-BgQn-yGL.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
- * }
- * ```
- */
-
+import { t as BusabaseClient } from "./client-slzL_ils.js";
+//#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];
 type FileTreeChangeRequestInput = Parameters<BusabaseClient["fileTrees"]["createChangeRequest"]>[0];
 type FileTreeOperationInput = FileTreeChangeRequestInput["operations"][number];
 type FileTreeCreateOrUpdateOperation = Extract<FileTreeOperationInput, {
-    kind: "create" | "update";
+  kind: "create" | "update";
 }>;
 /**
  * A Base field, as an app declares it.
@@ -65,35 +20,35 @@ type FileTreeCreateOrUpdateOperation = Extract<FileTreeOperationInput, {
  * surface to match how declarations are actually written.
  */
 interface AirAppFieldDeclaration {
-    slug: string;
-    name: string;
-    type: string;
-    required?: boolean;
-    options?: Record<string, unknown>;
+  slug: string;
+  name: string;
+  type: string;
+  required?: boolean;
+  options?: Record<string, unknown>;
 }
 /** 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;
+  /** 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;
+  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.
@@ -109,76 +64,85 @@ interface AirAppFolderDeclaration {
  * unattributable stranger, and the legacy claim would be refused.
  */
 interface AirAppNodeDeclaration {
-    slug: string;
-    name: string;
-    description?: string;
-    /** Ownership key written into the node's metadata, e.g. `"airapp"`. */
-    resourceKey: string;
+  slug: string;
+  name: string;
+  description?: 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;
+  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`.
  *
+ * Structurally identical to (and kept in lockstep with) the contract package's
+ * `AppResourceOwnership`, which `busabase-package`'s installer writes for the
+ * SAME resources when a user installs the app from the Template Center instead
+ * of running its `setup.mjs`. The two writers only recognise each other's work
+ * by this shape — drift means a user who installed through the UI and then ran
+ * the skill in their shell hits `SETUP_CONFLICT` on their own data. The
+ * assertion below is what makes that drift a compile error rather than a
+ * support ticket.
+ *
  * 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;
+  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;
+  nodeId: string;
+  baseId?: string;
+  resourceKey: string;
+  metadata: AirAppResourceOwnership;
 }
 interface AirAppProvisionedBase extends AirAppBaseDeclaration {
-    nodeId: string;
-    baseId: string;
+  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[];
-    /**
-     * The app's own AirApp node (see `AirAppNodeDeclaration`), when `config.airApp`
-     * is declared and a matching node exists under the Folder — owned or legacy,
-     * stamped or not; a pending stamp repair is reported separately via `repairs`.
-     * `null` when not declared, or declared but not found — the latter is what
-     * `publishAirApp` treats as "create", not a `missing`-array entry, because
-     * unlike a Base it is never auto-created just by finding it absent.
-     */
-    airApp: {
-        nodeId: string;
-    } | null;
-    /**
-     * 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";
+  /** 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[];
+  /**
+   * The app's own AirApp node (see `AirAppNodeDeclaration`), when `config.airApp`
+   * is declared and a matching node exists under the Folder — owned or legacy,
+   * stamped or not; a pending stamp repair is reported separately via `repairs`.
+   * `null` when not declared, or declared but not found — the latter is what
+   * `publishAirApp` treats as "create", not a `missing`-array entry, because
+   * unlike a Base it is never auto-created just by finding it absent.
+   */
+  airApp: {
+    nodeId: string;
+  } | null;
+  /**
+   * 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 —
@@ -199,27 +163,27 @@ type AirAppSetupCode = "SETUP_REQUIRED" | "SETUP_PENDING" | "SETUP_CONFLICT" | "
  * 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);
+  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[];
+  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[];
+  node: ReadNode;
+  children: ReadNode[];
 }
 /**
  * Decide, from one already-read Folder, what exists / is missing / needs
@@ -237,7 +201,7 @@ declare function resolveProvisionedFolder(folder: ReadFolderDetail | null | unde
  * structure lands in a single reviewable change.
  */
 declare function buildProvisionOperations(config: AirAppResourceConfig, folder: {
-    nodeId: string;
+  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>;
@@ -254,19 +218,19 @@ declare function provisionDeclaredResources(client: AirAppProvisioningClient, co
 type AirAppPublishClient = AirAppProvisioningClient & Pick<BusabaseClient, "fileTrees" | "changeRequests">;
 /** One file of the app's built AirApp bundle, as `publishAirApp` receives it. */
 interface AirAppFileInput {
-    path: string;
-    content: string;
-    mimeType?: string;
+  path: string;
+  content: string;
+  mimeType?: string;
 }
 type AirAppPublishResult = {
-    status: "created";
-    changeRequestId: string;
+  status: "created";
+  changeRequestId: string;
 } | {
-    status: "updated";
-    changeRequestId: string;
+  status: "updated";
+  changeRequestId: string;
 } | {
-    status: "pending";
-    changeRequestId: string;
+  status: "pending";
+  changeRequestId: string;
 };
 /**
  * The create-vs-update operation list for one AirApp publish. Pure — no I/O —
@@ -297,5 +261,5 @@ declare function buildAirAppFileOperations(localFiles: AirAppFileInput[], deploy
  * `airApp`; `SETUP_REQUIRED` when the Folder does not exist yet.
  */
 declare function publishAirApp(client: AirAppPublishClient, config: AirAppResourceConfig, files: AirAppFileInput[]): Promise<AirAppPublishResult>;
-
-export { type AirAppBaseDeclaration, type AirAppFieldDeclaration, type AirAppFileInput, type AirAppFolderDeclaration, type AirAppNodeDeclaration, type AirAppOwnershipRepair, type AirAppProvisionedBase, type AirAppProvisioningClient, type AirAppPublishClient, type AirAppPublishResult, type AirAppResourceConfig, type AirAppResourceOwnership, type AirAppResources, type AirAppSetupCode, AirAppSetupError, buildAirAppFileOperations, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, publishAirApp, resolveProvisionedFolder };
+//#endregion
+export { AirAppBaseDeclaration, AirAppFieldDeclaration, AirAppFileInput, AirAppFolderDeclaration, AirAppNodeDeclaration, AirAppOwnershipRepair, AirAppProvisionedBase, AirAppProvisioningClient, AirAppPublishClient, AirAppPublishResult, AirAppResourceConfig, AirAppResourceOwnership, AirAppResources, AirAppSetupCode, AirAppSetupError, buildAirAppFileOperations, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, publishAirApp, resolveProvisionedFolder };