busa-sdk 0.16.2 → 0.17.0

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { B as BusabaseClient } from './client-DN7Ol1g1.js';
+import { B as BusabaseClient } from './client-DIlpYL9z.js';
 import '@orpc/contract';
 import '@orpc/shared';
 import 'zod';
@@ -47,6 +47,11 @@ import 'zod';
 
 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";
+}>;
 /**
  * A Base field, as an app declares it.
  *
@@ -93,15 +98,20 @@ interface AirAppFolderDeclaration {
 /**
  * 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.
+ * `inspectProvisionedResources`/`provisionDeclaredResources` never create it —
+ * an app's Folder and Bases are plain data-schema resources, safe to bring
+ * into existence unattended, but an AirApp is a bundle of code the viewer's
+ * browser will execute, so bringing it into existence always goes through
+ * `publishAirApp`'s separate, always-review-first ChangeRequest instead of
+ * riding along on the same `autoMerge: true` request as the data layer.
+ * Declaring it here matters for a second reason regardless: 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;
+    description?: string;
     /** Ownership key written into the node's metadata, e.g. `"airapp"`. */
     resourceKey: string;
 }
@@ -153,6 +163,17 @@ interface AirAppResources {
     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.
@@ -229,5 +250,49 @@ declare function inspectProvisionedResources(client: AirAppProvisioningClient, c
  * @throws {AirAppSetupError} with a `code` describing which screen to show.
  */
 declare function provisionDeclaredResources(client: AirAppProvisioningClient, config: AirAppResourceConfig): Promise<AirAppResources>;
+/** The client surface `publishAirApp` needs, on top of provisioning. */
+type AirAppPublishClient = AirAppProvisioningClient & Pick<BusabaseClient, "fileTrees">;
+/** One file of the app's built AirApp bundle, as `publishAirApp` receives it. */
+interface AirAppFileInput {
+    path: string;
+    content: string;
+    mimeType?: string;
+}
+type AirAppPublishResult = {
+    status: "created";
+    changeRequestId: string;
+} | {
+    status: "updated";
+    changeRequestId: string;
+};
+/**
+ * The create-vs-update operation list for one AirApp publish. Pure — no I/O —
+ * so the decision is directly testable: a local path already present on the
+ * deployed node updates it, anything else is a new file. Never deletes a
+ * remote-only path — a file this bundle stopped shipping is left alone rather
+ * than assumed stale, the same conservative choice the rest of this module
+ * makes for a Base's fields (`additiveFieldsFor` only ever appends).
+ */
+declare function buildAirAppFileOperations(localFiles: AirAppFileInput[], deployedPaths: Iterable<string>): FileTreeCreateOrUpdateOperation[];
+/**
+ * Publish the app's own AirApp bundle: create it under the Folder when this
+ * Space has never had it, or propose the local files as an update when it
+ * already exists. Always a separate, always-review-first ChangeRequest from
+ * the data layer's `provisionDeclaredResources` — see the note on
+ * `AirAppNodeDeclaration` for why the two must never share a request.
+ *
+ * Call after `provisionDeclaredResources` has confirmed the Folder exists.
+ * Every call proposes the full local file list, even when nothing actually
+ * changed — this module has no access to the deployed content hashes
+ * (`fileTrees.listFiles` reports paths, not hashes; only a per-file
+ * `readFile` does, and fetching one per file to skip a no-op publish is not
+ * worth the round trips a normal publish cadence would spend on it). A
+ * reviewer sees an empty diff and merges or ignores it; this is a cost in
+ * review noise, not correctness.
+ *
+ * @throws {AirAppSetupError} `SETUP_CONFLICT` when `config` declares no
+ * `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 AirAppFolderDeclaration, type AirAppNodeDeclaration, type AirAppOwnershipRepair, type AirAppProvisionedBase, type AirAppProvisioningClient, type AirAppResourceConfig, type AirAppResourceOwnership, type AirAppResources, type AirAppSetupCode, AirAppSetupError, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, resolveProvisionedFolder };
+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 };

package/dist/airapp.js

@@ -17,8 +17,9 @@ var ownsResource = (node, appId, resourceKey, schemaVersion) => node?.metadata?.
 var hasResourceIdentity = (node, appId, resourceKey) => node?.metadata?.appId === appId && node?.metadata?.resourceKey === resourceKey;
 var ownsAppRoot = (node, appId, schemaVersion) => hasResourceIdentity(node, appId, "app-root") && node?.metadata?.schemaVersion === schemaVersion;
 var hasEmptyMetadata = (node) => Object.keys(node?.metadata ?? {}).length === 0;
+var isUnclaimed = (node) => node?.metadata?.appId === void 0;
 var matchesDeclaration = (node, declaration, type) => node?.type === type && node?.slug === declaration.slug && node?.name === declaration.name && node?.description === (declaration.description ?? "");
-var matchesLegacyAirApp = (node, config) => hasEmptyMetadata(node) && node?.type === "airapp" && node?.slug === config.airApp?.slug && node?.name === config.airApp?.name;
+var matchesLegacyAirApp = (node, config) => isUnclaimed(node) && node?.type === "airapp" && node?.slug === config.airApp?.slug && node?.name === config.airApp?.name;
 var resourceMetadata = (config, resourceKey) => ({
   appId: config.appId,
   resourceKey,
@@ -26,7 +27,7 @@ var resourceMetadata = (config, resourceKey) => ({
 });
 function resolveProvisionedFolder(folder, config) {
   if (!folder) {
-    return { folder: null, bases: [], missing: [...config.bases], repairs: [] };
+    return { folder: null, bases: [], missing: [...config.bases], repairs: [], airApp: null };
   }
   if (folder.node?.type !== "folder" || folder.node?.slug !== config.folder.slug) {
     throw setupError(
@@ -119,7 +120,8 @@ function resolveProvisionedFolder(folder, config) {
     folder: { ...config.folder, nodeId: folder.node.id },
     bases,
     missing,
-    repairs
+    repairs,
+    airApp: airAppNode ? { nodeId: airAppNode.id } : null
   };
 }
 function buildProvisionOperations(config, folder, missingBases) {
@@ -359,5 +361,68 @@ function provisionDeclaredResources(client, config) {
   }
   return state.inFlight;
 }
+function buildAirAppFileOperations(localFiles, deployedPaths) {
+  const deployed = new Set(deployedPaths);
+  return localFiles.map(
+    (file) => ({
+      kind: deployed.has(file.path) ? "update" : "create",
+      path: file.path,
+      content: file.content,
+      ...file.mimeType ? { mimeType: file.mimeType } : {}
+    })
+  );
+}
+async function publishAirApp(client, config, files) {
+  const airApp = config.airApp;
+  if (!airApp) {
+    throw setupError("SETUP_CONFLICT", "This app does not declare an airApp to publish");
+  }
+  const current = await inspectProvisionedResources(client, config);
+  if (!current.folder) {
+    throw setupError(
+      "SETUP_REQUIRED",
+      "Provision the Folder and Bases with provisionDeclaredResources before publishing the AirApp"
+    );
+  }
+  if (!current.airApp) {
+    const changeRequest2 = await client.fileTrees.create({
+      type: "airapp",
+      parentNodeId: current.folder.nodeId,
+      slug: airApp.slug,
+      name: airApp.name,
+      description: airApp.description ?? "",
+      files,
+      mergeMode: "replace",
+      // Explicit even though this app's write-permission credential would
+      // otherwise auto-merge it: executable AirApp code always gets human
+      // review before it runs in a viewer's browser, no exceptions.
+      autoMerge: false
+    });
+    if (changeRequest2.materialized) {
+      throw setupError(
+        "SCHEMA_INCOMPLETE",
+        "AirApp create unexpectedly materialized despite autoMerge: false"
+      );
+    }
+    return { status: "created", changeRequestId: changeRequest2.id };
+  }
+  const deployedFiles = await client.fileTrees.listFiles({
+    nodeId: current.airApp.nodeId,
+    type: "airapp"
+  });
+  const operations = buildAirAppFileOperations(
+    files,
+    deployedFiles.map((file) => file.path)
+  );
+  const changeRequest = await client.fileTrees.createChangeRequest({
+    nodeId: current.airApp.nodeId,
+    type: "airapp",
+    operations,
+    message: `Publish ${config.appName} AirApp`,
+    submittedBy: config.appId,
+    autoMerge: false
+  });
+  return { status: "updated", changeRequestId: changeRequest.id };
+}
 
-export { AirAppSetupError, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, resolveProvisionedFolder };
+export { AirAppSetupError, buildAirAppFileOperations, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, publishAirApp, resolveProvisionedFolder };

package/dist/{client-DN7Ol1g1.d.ts → client-DIlpYL9z.d.ts}

@@ -9182,6 +9182,7 @@ declare const cloudContract: {
         runLocalNode: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
             files: z.ZodRecord<z.ZodString, z.ZodString>;
+            binaryFiles: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
             engine: z.ZodDefault<z.ZodEnum<{
                 "local-node": "local-node";
                 srt: "srt";

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import { z } from 'zod';
 import * as _orpc_client from '@orpc/client';
-import { N as NodeOutput, a as NodeType, O as OperationKind, B as BusabaseClient, R as ResolvedConfig, b as BusabaseConfig } from './client-DN7Ol1g1.js';
-export { C as CREATABLE_NODE_TYPES, c as CloudContract, d as CreatableNodeType, D as DEFAULT_BASE_URL, e as cloudContract, f as createBusabaseClient, r as resolveConfig } from './client-DN7Ol1g1.js';
+import { N as NodeOutput, a as NodeType, O as OperationKind, B as BusabaseClient, R as ResolvedConfig, b as BusabaseConfig } from './client-DIlpYL9z.js';
+export { C as CREATABLE_NODE_TYPES, c as CloudContract, d as CreatableNodeType, D as DEFAULT_BASE_URL, e as cloudContract, f as createBusabaseClient, r as resolveConfig } from './client-DIlpYL9z.js';
 import '@orpc/shared';
 
 /**

package/dist/index.js

@@ -1357,6 +1357,14 @@ var airAppRunLocalNodeInputSchema = z.object({
   /** Text files to mount into the sandbox workdir before installing, keyed by
    *  path (same shape `RunPanel` already assembles for `NodepodRunner.mount`). */
   files: z.record(z.string(), z.string()),
+  /** Binary (asset-backed) files — images, fonts, sample data — keyed by the
+   *  same path, base64-encoded because this input crosses a JSON boundary that
+   *  `Uint8Array` cannot. Separate from `files` rather than a tagged union so
+   *  an older client that sends only `files` keeps working unchanged.
+   *
+   *  The in-browser Nodepod engine never uses this field: it hands raw bytes to
+   *  `Nodepod.boot({ files })` directly and skips the base64 round trip. */
+  binaryFiles: z.record(z.string(), z.string()).optional().default({}),
   /** Server-side execution mode. `"local-node"` spawns a bare host Node.js
    *  process (previewable, data bridge via reverse proxy, NOT OS-isolated);
    *  `"srt"` wraps the same commands in the OS sandbox (isolated execution,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-sdk",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud). Short-name alias for busabase-sdk.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",