busabase-sdk 0.9.6 → 0.9.7

package/dist/index.d.ts

@@ -4215,6 +4215,7 @@ declare const cloudContract: {
                     targetBaseSlug: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<true>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             baseId: z.ZodNullable<z.ZodString>;
@@ -4592,11 +4593,13 @@ declare const cloudContract: {
                 visibleOperationHeads: z.ZodRecord<z.ZodString, z.ZodString>;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<false>;
         }, z.core.$strip>]>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         createChangeRequest: _orpc_contract.ContractProcedure<z.ZodObject<{
             fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
             message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
             submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            idempotencyKey: z.ZodOptional<z.ZodString>;
             baseId: z.ZodString;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
@@ -4980,6 +4983,7 @@ declare const cloudContract: {
             records: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
             submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            idempotencyKey: z.ZodOptional<z.ZodString>;
             baseId: z.ZodString;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
@@ -9240,6 +9244,7 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         create: _orpc_contract.ContractProcedure<z.ZodObject<{
             parentNodeId: z.ZodOptional<z.ZodString>;
@@ -9285,6 +9290,8 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            materialized: z.ZodLiteral<true>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             baseId: z.ZodNullable<z.ZodString>;
@@ -9662,6 +9669,7 @@ declare const cloudContract: {
                 visibleOperationHeads: z.ZodRecord<z.ZodString, z.ZodString>;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<false>;
         }, z.core.$strip>]>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         get: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -9683,6 +9691,7 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         listFiles: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -10149,6 +10158,7 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         create: _orpc_contract.ContractProcedure<z.ZodObject<{
             parentNodeId: z.ZodOptional<z.ZodString>;
@@ -10194,6 +10204,8 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            materialized: z.ZodLiteral<true>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             baseId: z.ZodNullable<z.ZodString>;
@@ -10571,6 +10583,7 @@ declare const cloudContract: {
                 visibleOperationHeads: z.ZodRecord<z.ZodString, z.ZodString>;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<false>;
         }, z.core.$strip>]>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         get: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -10592,6 +10605,7 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         listFiles: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -11040,6 +11054,38 @@ declare const cloudContract: {
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     };
     airapps: {
+        runLocalNode: _orpc_contract.ContractProcedure<z.ZodObject<{
+            nodeId: z.ZodString;
+            files: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strip>, _orpc_contract.Schema<AsyncIteratorObject<{
+            type: "log";
+            line: string;
+        } | {
+            type: "installed";
+        } | {
+            type: "ready";
+            previewUrl: string;
+        } | {
+            type: "exit";
+            code: number | null;
+        } | {
+            type: "error";
+            message: string;
+        }, unknown, void>, _orpc_shared.AsyncIteratorClass<{
+            type: "log";
+            line: string;
+        } | {
+            type: "installed";
+        } | {
+            type: "ready";
+            previewUrl: string;
+        } | {
+            type: "exit";
+            code: number | null;
+        } | {
+            type: "error";
+            message: string;
+        }, unknown, void>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         list: _orpc_contract.ContractProcedure<_orpc_contract.Schema<unknown, unknown>, z.ZodArray<z.ZodObject<{
             node: z.ZodType<NodeOutput, unknown, z.core.$ZodTypeInternals<NodeOutput, unknown>>;
             entryFile: z.ZodString;
@@ -11058,6 +11104,7 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         create: _orpc_contract.ContractProcedure<z.ZodObject<{
             parentNodeId: z.ZodOptional<z.ZodString>;
@@ -11103,6 +11150,8 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            materialized: z.ZodLiteral<true>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             baseId: z.ZodNullable<z.ZodString>;
@@ -11480,6 +11529,7 @@ declare const cloudContract: {
                 visibleOperationHeads: z.ZodRecord<z.ZodString, z.ZodString>;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<false>;
         }, z.core.$strip>]>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         get: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -11501,6 +11551,7 @@ declare const cloudContract: {
                 assetId: z.ZodString;
                 displayName: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            skippedGitignorePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         listFiles: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -12007,6 +12058,7 @@ declare const cloudContract: {
                 }>;
                 createdAt: z.ZodString;
             }, z.core.$strip>;
+            materialized: z.ZodLiteral<true>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             baseId: z.ZodNullable<z.ZodString>;
@@ -12384,6 +12436,7 @@ declare const cloudContract: {
                 visibleOperationHeads: z.ZodRecord<z.ZodString, z.ZodString>;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<false>;
         }, z.core.$strip>]>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         get: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -12431,6 +12484,7 @@ declare const cloudContract: {
             node: z.ZodType<NodeOutput, unknown, z.core.$ZodTypeInternals<NodeOutput, unknown>>;
             storagePrefix: z.ZodString;
             body: z.ZodString;
+            materialized: z.ZodLiteral<true>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             baseId: z.ZodNullable<z.ZodString>;
@@ -12808,6 +12862,7 @@ declare const cloudContract: {
                 visibleOperationHeads: z.ZodRecord<z.ZodString, z.ZodString>;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
+            materialized: z.ZodLiteral<false>;
         }, z.core.$strip>]>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         get: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
@@ -20865,6 +20920,35 @@ declare function resolveConfig(config?: BusabaseConfig): ResolvedConfig;
  * ```
  */
 declare function createBusabaseClient(config?: BusabaseConfig): BusabaseClient;
+/** Options for {@link createBusabaseRpcClient}. No `apiKey`/`spaceId` — this
+ * transport authenticates purely via the browser's ambient session cookie. */
+interface BusabaseRpcConfig {
+    /**
+     * Path to the internal RPC endpoint: either a full URL, or a path resolved
+     * against `window.location.origin` (browser only — there is no ambient
+     * session outside one).
+     *
+     * **The default (`/api/rpc`) only matches `apps/busabase` (the OSS app)**,
+     * which mounts busabase's procedures unnamespaced. `apps/busabase-cloud`
+     * mounts the *same* procedures under a `core` prefix instead — pass
+     * `apiBasePath: "/api/rpc/core"` there, or this client will 404 on every
+     * call. There is no single default that works for both; which one you're
+     * targeting is something the caller has to know (this SDK doesn't probe
+     * for it).
+     *
+     * From inside an AirApp running via Nodepod, prepend
+     * `/__busabase_api__` to whichever of the above applies, to route through
+     * the service-worker bridge instead of the sandboxed virtual server — e.g.
+     * `/__busabase_api__/api/rpc/core` for busabase-cloud. See
+     * apps/busabase/docs/node-types.md.
+     */
+    apiBasePath?: string;
+    /** Extra headers merged into every request. Static object or a (possibly async) factory. */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Custom `fetch` implementation (e.g. a proxy-aware or instrumented fetch). */
+    fetch?: typeof fetch;
+}
+declare function createBusabaseRpcClient(config?: BusabaseRpcConfig): BusabaseClient;
 
 /**
  * Attachments — DTO/VO Zod schemas + inferred types (the contract's type source
@@ -22211,6 +22295,7 @@ interface FileTreeNodeVO {
     visibility: "private" | "workspace" | "public";
     version: string;
     files: FileTreeFileVO[];
+    skippedGitignorePaths?: string[];
 }
 interface FileTreeReadFileVO {
     nodeId: string;
@@ -22881,4 +22966,4 @@ declare class Busabase {
     }>>>>;
 }
 
-export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeNodeVO as AirAppVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseClient, type BusabaseConfig, CREATABLE_NODE_TYPES, type ChangeRequestBatchResultVO, type ChangeRequestCountsVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CloudContract, type CommentSubjectType, type CommentVO, type CommitVO, type CreatableNodeType, DEFAULT_BASE_URL, type FileTreeFileVO as DriveFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeNodeVO as DriveVO, type FieldType, type FileNodeMetadata, type FileNodeVO, type FileTreeFileVO, type FileTreeNodeVO, type FileTreeReadFileVO, type NodeType, type NodeVO, type OperationKind, type OperationStatus, type OperationVO, type RecordLinkVO, type RecordVO, type ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as SkillVO, type UpdateVaultSettingsDTO, type UserRefVO, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewVO, cloudContract, createBusabaseClient, normalizeBaseUrl, resolveConfig };
+export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeNodeVO as AirAppVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseClient, type BusabaseConfig, type BusabaseRpcConfig, CREATABLE_NODE_TYPES, type ChangeRequestBatchResultVO, type ChangeRequestCountsVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CloudContract, type CommentSubjectType, type CommentVO, type CommitVO, type CreatableNodeType, DEFAULT_BASE_URL, type FileTreeFileVO as DriveFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeNodeVO as DriveVO, type FieldType, type FileNodeMetadata, type FileNodeVO, type FileTreeFileVO, type FileTreeNodeVO, type FileTreeReadFileVO, type NodeType, type NodeVO, type OperationKind, type OperationStatus, type OperationVO, type RecordLinkVO, type RecordVO, type ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as SkillVO, type UpdateVaultSettingsDTO, type UserRefVO, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewVO, cloudContract, createBusabaseClient, createBusabaseRpcClient, normalizeBaseUrl, resolveConfig };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { createORPCClient } from '@orpc/client';
+import { RPCLink } from '@orpc/client/fetch';
+import { oc, eventIterator, inferRPCMethodFromContractRouter } from '@orpc/contract';
 import { OpenAPILink } from '@orpc/openapi-client/fetch';
-import { oc, eventIterator } from '@orpc/contract';
 import { z } from 'zod';
 
 // src/client.ts
@@ -112,7 +113,9 @@ var baseSchema = z.object({
   fields: z.array(baseFieldSchema)
 });
 var createBaseInputSchema = z.object({
-  parentNodeId: z.string().optional(),
+  parentNodeId: z.string().optional().describe(
+    "Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."
+  ),
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
@@ -855,10 +858,17 @@ var fileTreeNodeSchema = z.object({
   entryFile: z.string(),
   visibility: z.enum(["private", "workspace", "public"]),
   version: z.string(),
-  files: z.array(fileTreeFileSchema)
+  files: z.array(fileTreeFileSchema),
+  // Paths silently dropped from this create call by an uploaded `.gitignore`
+  // (upload-safety layer 1 — see `logic/upload-safety.ts`). Empty on
+  // ordinary get/list responses and on creates that didn't include a
+  // `.gitignore`.
+  skippedGitignorePaths: z.array(z.string()).optional().default([])
 });
 var createFileTreeInputSchema = z.object({
-  parentNodeId: z.string().optional(),
+  parentNodeId: z.string().optional().describe(
+    "Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."
+  ),
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
@@ -920,8 +930,13 @@ var makeFileTreeContract = (routeBase, tag) => {
       path: basePath,
       tags: [tag],
       summary: `Create ${label} node`,
-      successDescription: `Review-first by default: a pending ChangeRequest proposing the ${label} node. Returns the materialized ${label} node instead when \`autoMerge: true\` is passed.`
-    }).input(createFileTreeInputSchema).output(z.union([fileTreeNodeSchema, changeRequestSchema])),
+      successDescription: `Review-first by default: a pending ChangeRequest proposing the ${label} node (\`materialized: false\`). Returns the materialized ${label} node instead (\`materialized: true\`) when \`autoMerge: true\` is passed.`
+    }).input(createFileTreeInputSchema).output(
+      z.union([
+        fileTreeNodeSchema.extend({ materialized: z.literal(true) }),
+        changeRequestSchema.extend({ materialized: z.literal(false) })
+      ])
+    ),
     get: oc.route({
       method: "GET",
       path: `${basePath}/{nodeId}`,
@@ -967,6 +982,22 @@ var makeFileTreeContract = (routeBase, tag) => {
 
 // ../../packages/busabase-contract/src/domains/airapp/contract.ts
 var airappContract = makeFileTreeContract("airapps", "AirApps");
+var airAppRunLocalNodeInputSchema = z.object({
+  nodeId: z.string(),
+  /** 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())
+});
+var airAppRuntimeEventSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("log"), line: z.string() }),
+  z.object({ type: z.literal("installed") }),
+  z.object({ type: z.literal("ready"), previewUrl: z.string() }),
+  z.object({ type: z.literal("exit"), code: z.number().nullable() }),
+  z.object({ type: z.literal("error"), message: z.string() })
+]);
+var airappRuntimeContract = {
+  runLocalNode: oc.input(airAppRunLocalNodeInputSchema).output(eventIterator(airAppRuntimeEventSchema))
+};
 var AttachmentMetadataSchema = z.record(z.string(), z.unknown());
 z.object({
   id: z.string(),
@@ -1409,7 +1440,10 @@ var createChangeRequestInputSchema = z.object({
   message: z.string().optional().default("Initial change request").describe(
     'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Add Acme Corp \u2014 qualified lead from the June webinar".'
   ),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  idempotencyKey: z.string().optional().describe(
+    "Optional client-supplied key that dedupes retries. Scoped per base + submitter: calling this endpoint again with the SAME idempotencyKey (e.g. after a timeout or a 5xx where you couldn't tell if the first call succeeded) returns the change request created by the first call instead of creating a duplicate. Omit for normal one-shot calls; only set it when you might retry."
+  )
 });
 var createBulkChangeRequestInputSchema = z.object({
   records: z.array(z.record(z.string(), z.unknown())).min(1).max(1e3).describe(
@@ -1418,7 +1452,10 @@ var createBulkChangeRequestInputSchema = z.object({
   message: z.string().optional().default("Bulk create records").describe(
     'Explanation shown to the human reviewer for the whole batch \u2014 e.g. "Import 240 June webinar leads".'
   ),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  idempotencyKey: z.string().optional().describe(
+    "Optional client-supplied key that dedupes retries. Scoped per base + submitter: calling this endpoint again with the SAME idempotencyKey returns the bulk change request created by the first call instead of creating a duplicate. Omit for normal one-shot calls; only set it when you might retry."
+  )
 });
 var recordFieldFilterInputSchema = z.object({
   baseId: z.string().optional(),
@@ -1505,8 +1542,13 @@ var baseContract = {
     path: "/bases",
     tags: ["Bases"],
     summary: "Create Base",
-    successDescription: "Review-first by default: a pending ChangeRequest proposing the Base. Returns the materialized Base instead when `autoMerge: true` is passed."
-  }).input(createBaseInputSchema).output(z.union([baseSchema, changeRequestSchema])),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the Base (`materialized: false`). Returns the materialized Base instead (`materialized: true`) when `autoMerge: true` is passed."
+  }).input(createBaseInputSchema).output(
+    z.union([
+      baseSchema.extend({ materialized: z.literal(true) }),
+      changeRequestSchema.extend({ materialized: z.literal(false) })
+    ])
+  ),
   createChangeRequest: oc.route({
     method: "POST",
     path: "/bases/{baseId}/change-requests",
@@ -1707,7 +1749,9 @@ var docSchema = z.object({
   body: z.string()
 });
 var createDocInputSchema = z.object({
-  parentNodeId: z.string().optional(),
+  parentNodeId: z.string().optional().describe(
+    "Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."
+  ),
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
@@ -1741,8 +1785,13 @@ var docContract = {
     path: "/docs",
     tags: ["Docs"],
     summary: "Create Doc node",
-    successDescription: "Review-first by default: a pending ChangeRequest proposing the Doc. Returns the materialized Doc node instead when `autoMerge: true` is passed."
-  }).input(createDocInputSchema).output(z.union([docSchema, changeRequestSchema])),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the Doc (`materialized: false`). Returns the materialized Doc node instead (`materialized: true`) when `autoMerge: true` is passed."
+  }).input(createDocInputSchema).output(
+    z.union([
+      docSchema.extend({ materialized: z.literal(true) }),
+      changeRequestSchema.extend({ materialized: z.literal(false) })
+    ])
+  ),
   get: oc.route({
     method: "GET",
     path: "/docs/{nodeId}",
@@ -1876,7 +1925,9 @@ var FileNodeVOSchema = z.object({
 
 // ../../packages/busabase-contract/src/domains/file-node/contract.ts
 var createFileNodeInputSchema = z.object({
-  parentNodeId: z.string().optional(),
+  parentNodeId: z.string().optional().describe(
+    "Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."
+  ),
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
@@ -1900,8 +1951,13 @@ var fileContract = {
     path: "/files",
     tags: ["Files"],
     summary: "Create File node",
-    successDescription: "Review-first by default: a pending ChangeRequest proposing the File node. Returns the materialized File node instead when `autoMerge: true` is passed."
-  }).input(createFileNodeInputSchema).output(z.union([FileNodeVOSchema, changeRequestSchema])),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the File node (`materialized: false`). Returns the materialized File node instead (`materialized: true`) when `autoMerge: true` is passed."
+  }).input(createFileNodeInputSchema).output(
+    z.union([
+      FileNodeVOSchema.extend({ materialized: z.literal(true) }),
+      changeRequestSchema.extend({ materialized: z.literal(false) })
+    ])
+  ),
   get: oc.route({
     method: "GET",
     path: "/files/{nodeId}",
@@ -2449,7 +2505,7 @@ var busabaseContractRoutes = {
   bases: baseContract,
   skills: skillContract,
   drives: driveContract,
-  airapps: airappContract,
+  airapps: { ...airappContract, ...airappRuntimeContract },
   files: fileContract,
   docs: docContract,
   folders: folderContract,
@@ -2722,6 +2778,26 @@ function createBusabaseClient(config = {}) {
   });
   return createORPCClient(link);
 }
+var getBrowserWindow = () => globalThis.window;
+function createBusabaseRpcClient(config = {}) {
+  const apiBasePath = config.apiBasePath ?? "/api/rpc";
+  const isAbsolute = /^https?:\/\//.test(apiBasePath);
+  if (!isAbsolute && typeof getBrowserWindow() === "undefined") {
+    throw new Error(
+      "createBusabaseRpcClient: apiBasePath must be an absolute URL (http:// or https://) outside a browser \u2014 this client authenticates via the browser's ambient session cookie, which only exists client-side."
+    );
+  }
+  const link = new RPCLink({
+    method: inferRPCMethodFromContractRouter(cloudContract),
+    url: () => isAbsolute ? apiBasePath : `${getBrowserWindow()?.location.origin}${apiBasePath}`,
+    fetch: config.fetch,
+    headers: async () => {
+      const extra = typeof config.headers === "function" ? await config.headers() : config.headers;
+      return { ...extra };
+    }
+  });
+  return createORPCClient(link);
+}
 
 // src/index.ts
 var Busabase = class {
@@ -2848,4 +2924,4 @@ var Busabase = class {
   }
 };
 
-export { Busabase, CREATABLE_NODE_TYPES, DEFAULT_BASE_URL, cloudContract, createBusabaseClient, normalizeBaseUrl, resolveConfig };
+export { Busabase, CREATABLE_NODE_TYPES, DEFAULT_BASE_URL, cloudContract, createBusabaseClient, createBusabaseRpcClient, normalizeBaseUrl, resolveConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -41,9 +41,9 @@
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^2.1.8",
-    "busabase-contract": "0.9.6",
     "open-domains": "0.0.2",
-    "openlib": "0.1.1"
+    "openlib": "0.1.1",
+    "busabase-contract": "0.9.6"
   },
   "engines": {
     "node": ">=24.18.0"