busa-sdk 0.9.8 → 0.9.10

package/dist/index.d.ts

@@ -251,7 +251,7 @@ interface NodeOutput {
     slug: string;
     name: string;
     description: string;
-    metadata: {
+    metadata: Record<string, unknown> & {
         entryFile?: string;
         visibility?: "private" | "workspace" | "public";
         version?: string;
@@ -393,6 +393,8 @@ declare const cloudContract: {
                 slug: z.ZodNullable<z.ZodString>;
                 plan: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
+            createdSpace: z.ZodOptional<z.ZodBoolean>;
+            bootstrapRequired: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     };
     search: _orpc_contract.ContractProcedure<z.ZodObject<{
@@ -512,6 +514,19 @@ declare const cloudContract: {
             parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             depth: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
         }, z.core.$strip>>, z.ZodArray<z.ZodType<NodeOutput, unknown, z.core.$ZodTypeInternals<NodeOutput, unknown>>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+        searchByName: _orpc_contract.ContractProcedure<z.ZodObject<{
+            query: z.ZodString;
+            limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodEnum<{
+                [x: string]: string;
+            }>;
+            name: z.ZodString;
+            slug: z.ZodString;
+            path: z.ZodString;
+            updatedAt: z.ZodString;
+        }, z.core.$strip>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         isDescendant: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
             potentialAncestorId: z.ZodString;
@@ -1400,6 +1415,10 @@ declare const cloudContract: {
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+        updateMetadata: _orpc_contract.ContractProcedure<z.ZodObject<{
+            nodeId: z.ZodString;
+            metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodType<NodeOutput, unknown, z.core.$ZodTypeInternals<NodeOutput, unknown>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         purge: _orpc_contract.ContractProcedure<z.ZodObject<{
             nodeId: z.ZodString;
         }, z.core.$strip>, z.ZodObject<{
@@ -1495,6 +1514,7 @@ declare const cloudContract: {
                 "asset.metadata_updated": "asset.metadata_updated";
                 "asset.text_written": "asset.text_written";
                 "asset.text_marked_none": "asset.text_marked_none";
+                "node.metadata_updated": "node.metadata_updated";
                 "node.purged": "node.purged";
             }>;
             actorId: z.ZodString;
@@ -1533,6 +1553,7 @@ declare const cloudContract: {
                 "asset.metadata_updated": "asset.metadata_updated";
                 "asset.text_written": "asset.text_written";
                 "asset.text_marked_none": "asset.text_marked_none";
+                "node.metadata_updated": "node.metadata_updated";
                 "node.purged": "node.purged";
             }>;
             actorId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -1563,6 +1584,7 @@ declare const cloudContract: {
                 "asset.metadata_updated": "asset.metadata_updated";
                 "asset.text_written": "asset.text_written";
                 "asset.text_marked_none": "asset.text_marked_none";
+                "node.metadata_updated": "node.metadata_updated";
                 "node.purged": "node.purged";
             }>;
             actorId: z.ZodString;
@@ -2549,6 +2571,7 @@ declare const cloudContract: {
                         "asset.metadata_updated": "asset.metadata_updated";
                         "asset.text_written": "asset.text_written";
                         "asset.text_marked_none": "asset.text_marked_none";
+                        "node.metadata_updated": "node.metadata_updated";
                         "node.purged": "node.purged";
                     }>;
                     actorId: z.ZodString;
@@ -14729,6 +14752,15 @@ declare const cloudContract: {
             rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             nextCursor: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+        exportAssetText: _orpc_contract.ContractProcedure<z.ZodObject<{
+            assetId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            assetId: z.ZodString;
+            textStorageKey: z.ZodString;
+            downloadUrl: z.ZodNullable<z.ZodString>;
+            textContentHash: z.ZodNullable<z.ZodString>;
+            byteCount: z.ZodNumber;
+        }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         importBegin: _orpc_contract.ContractProcedure<_orpc_contract.Schema<unknown, unknown>, z.ZodObject<{
             sessionId: z.ZodString;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
@@ -14753,7 +14785,7 @@ declare const cloudContract: {
                 commits: "commits";
                 changeRequests: "changeRequests";
                 auditEvents: "auditEvents";
-            }>, z.ZodLiteral<"docBodies">, z.ZodLiteral<"attachmentBlobs">]>;
+            }>, z.ZodLiteral<"docBodies">, z.ZodLiteral<"attachmentBlobs">, z.ZodLiteral<"assetTextBlobs">]>;
             rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>, z.ZodObject<{
             inserted: z.ZodNumber;
@@ -14770,6 +14802,91 @@ declare const cloudContract: {
             ok: z.ZodBoolean;
         }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     };
+    install: {
+        planFromGithub: _orpc_contract.ContractProcedure<z.ZodObject<{
+            repoUrl: z.ZodString;
+            intoFolder: z.ZodOptional<z.ZodString>;
+            rename: z.ZodOptional<z.ZodBoolean>;
+            autoMerge: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            package: z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodDefault<z.ZodString>;
+                version: z.ZodOptional<z.ZodString>;
+                author: z.ZodOptional<z.ZodString>;
+                license: z.ZodOptional<z.ZodString>;
+                homepage: z.ZodOptional<z.ZodString>;
+                tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+            source: z.ZodObject<{
+                owner: z.ZodString;
+                repo: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                subdir: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            targetFolderSlug: z.ZodString;
+            nodes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                slug: z.ZodString;
+                name: z.ZodString;
+                type: z.ZodEnum<{
+                    file: "file";
+                    base: "base";
+                    folder: "folder";
+                    skill: "skill";
+                    drive: "drive";
+                    airapp: "airapp";
+                    doc: "doc";
+                }>;
+                depth: z.ZodNumber;
+                fieldCount: z.ZodOptional<z.ZodNumber>;
+                recordCount: z.ZodOptional<z.ZodNumber>;
+                fileCount: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>>;
+            counts: z.ZodObject<{
+                folders: z.ZodNumber;
+                docs: z.ZodNumber;
+                bases: z.ZodNumber;
+                records: z.ZodNumber;
+                skills: z.ZodNumber;
+                airapps: z.ZodNumber;
+                drives: z.ZodNumber;
+                files: z.ZodNumber;
+            }, z.core.$strip>;
+            collisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    base: "base";
+                    node: "node";
+                }>;
+                slug: z.ZodString;
+                path: z.ZodString;
+                renamedTo: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            requiresAutoMerge: z.ZodBoolean;
+            applicable: z.ZodBoolean;
+        }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+        fromGithub: _orpc_contract.ContractProcedure<z.ZodObject<{
+            repoUrl: z.ZodString;
+            intoFolder: z.ZodOptional<z.ZodString>;
+            rename: z.ZodOptional<z.ZodBoolean>;
+            autoMerge: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            targetFolderSlug: z.ZodString;
+            targetFolderNodeId: z.ZodString;
+            created: z.ZodObject<{
+                folders: z.ZodNumber;
+                docs: z.ZodNumber;
+                bases: z.ZodNumber;
+                views: z.ZodNumber;
+                records: z.ZodNumber;
+                fileTreeNodes: z.ZodNumber;
+                files: z.ZodNumber;
+            }, z.core.$strip>;
+            pendingChangeRequests: z.ZodNumber;
+            warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    };
     changeRequests: {
         list: _orpc_contract.ContractProcedure<z.ZodDefault<z.ZodOptional<z.ZodObject<{
             limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
@@ -22472,6 +22589,7 @@ declare const activityItemSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             "asset.metadata_updated": "asset.metadata_updated";
             "asset.text_written": "asset.text_written";
             "asset.text_marked_none": "asset.text_marked_none";
+            "node.metadata_updated": "node.metadata_updated";
             "node.purged": "node.purged";
         }>;
         actorId: z.ZodString;
@@ -23017,7 +23135,7 @@ type ChangeRequestTargetType = "base" | "node";
 type ReviewVerdict = "approved" | "rejected";
 type SearchResultKind = "record" | "change_request" | "base" | "file";
 type CommentSubjectType = "record" | "change_request" | "operation" | "commit";
-type AuditAction = "record.viewed" | "change_request.created" | "change_request.updated" | "change_request.deleted" | "change_request.reviewed" | "change_request.merged" | "base.created" | "field.created" | "doc.created" | "doc.updated" | "file.created" | "skill.created" | "drive.created" | "airapp.created" | "asset.deleted" | "asset.metadata_updated" | "asset.text_written" | "asset.text_marked_none" | "node.purged";
+type AuditAction = "record.viewed" | "change_request.created" | "change_request.updated" | "change_request.deleted" | "change_request.reviewed" | "change_request.merged" | "base.created" | "field.created" | "doc.created" | "doc.updated" | "file.created" | "skill.created" | "drive.created" | "airapp.created" | "asset.deleted" | "asset.metadata_updated" | "asset.text_written" | "asset.text_marked_none" | "node.metadata_updated" | "node.purged";
 interface UserRefVO {
     id: string;
     name: string | null;
@@ -23025,6 +23143,22 @@ interface UserRefVO {
     image: string | null;
     role?: string | null;
 }
+/**
+ * Cheap, name/slug-only match from `nodes.searchByName` (see
+ * `apps/busabase/content/spec/search-quick-jump.md`) — deliberately a much
+ * smaller projection than `NodeVO` (no `description`/`metadata`/tree shape):
+ * this backs the dashboard's instant quick-jump palette, not the sidebar tree
+ * or a node's own detail view. `path` is the route this node navigates to
+ * (e.g. `/base/{slug}`), not a filesystem/breadcrumb tree path.
+ */
+interface NodeSearchResultVO {
+    id: string;
+    type: NodeType;
+    name: string;
+    slug: string;
+    path: string;
+    updatedAt: string;
+}
 interface NodeVO {
     id: string;
     parentId: string | null;
@@ -23032,7 +23166,7 @@ interface NodeVO {
     slug: string;
     name: string;
     description: string;
-    metadata: {
+    metadata: Record<string, unknown> & {
         entryFile?: string;
         visibility?: "private" | "workspace" | "public";
         version?: string;
@@ -23351,4 +23485,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, 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 GalleryCardSize, type GalleryCoverFit, type GanttScale, 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 ViewType, type ViewVO, cloudContract, createBusabaseClient, createBusabaseRpcClient, 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 GalleryCardSize, type GalleryCoverFit, type GanttScale, type NodeSearchResultVO, 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 ViewType, type ViewVO, cloudContract, createBusabaseClient, createBusabaseRpcClient, normalizeBaseUrl, resolveConfig };

package/dist/index.js

@@ -427,7 +427,7 @@ var nodeSchema = z.lazy(
       visibility: z.enum(["private", "workspace", "public"]).optional(),
       version: z.string().optional(),
       assetId: z.string().optional()
-    }).default({}),
+    }).catchall(z.unknown()).default({}),
     position: z.number(),
     createdAt: z.string(),
     updatedAt: z.string(),
@@ -459,6 +459,22 @@ var isDescendantInputSchema = z.object({
 var isDescendantOutputSchema = z.object({
   isDescendant: z.boolean()
 });
+var updateNodeMetadataInputSchema = z.object({
+  nodeId: z.string(),
+  metadata: z.record(z.string(), z.unknown())
+});
+var searchNodesByNameInputSchema = z.object({
+  query: z.string().min(1),
+  limit: z.number().int().min(1).max(50).optional().default(20)
+});
+var nodeSearchResultSchema = z.object({
+  id: z.string(),
+  type: z.enum(NODE_TYPES),
+  name: z.string(),
+  slug: z.string(),
+  path: z.string(),
+  updatedAt: z.string()
+});
 var userRefSchema = z.object({
   id: z.string(),
   name: z.string().nullable(),
@@ -635,6 +651,7 @@ var auditActionSchema = z.enum([
   "asset.metadata_updated",
   "asset.text_written",
   "asset.text_marked_none",
+  "node.metadata_updated",
   "node.purged"
 ]);
 var auditEventSchema = z.object({
@@ -824,7 +841,11 @@ var authInfoSchema = z.object({
    * space-scoped — when this has more than one entry, callers should confirm the
    * intended space and target it explicitly via the `x-busabase-space` header.
    */
-  spaces: z.array(authSpaceSchema)
+  spaces: z.array(authSpaceSchema),
+  /** Cloud only: the server created this user's first Space during this exact request. */
+  createdSpace: z.boolean().optional(),
+  /** Cloud only: this auto-created Space still needs its idempotent starter initialization. */
+  bootstrapRequired: z.boolean().optional()
 });
 
 // ../../packages/busabase-contract/src/domains/filetree/contract.ts
@@ -1907,12 +1928,36 @@ var ExportTablesVOSchema = z.object({
   rows: z.array(z.record(z.string(), z.unknown())),
   nextCursor: z.string().nullable()
 });
+var ExportAssetTextInputSchema = z.object({ assetId: z.string() });
+var ExportAssetTextVOSchema = z.object({
+  assetId: z.string(),
+  /** The row's `text_storage_key` — the exact key a restore must write back to. */
+  textStorageKey: z.string(),
+  /**
+   * `null` when this row owns no separate text object and therefore needs no
+   * blob in the archive:
+   *  - auto-registered text-kind rows (`writtenBy: "auto"`), whose
+   *    `textStorageKey` IS the owning attachment's own key — those bytes are
+   *    already archived by the attachment-blob pass, and re-archiving them
+   *    would duplicate bytes and collide on restore;
+   *  - `status: "none"` rows (no extractable text), whose key is `""`.
+   */
+  downloadUrl: z.string().nullable(),
+  /** `sha256:<hex>` of the text bytes, so a backup can verify what it downloaded. */
+  textContentHash: z.string().nullable(),
+  byteCount: z.number().int().nonnegative()
+});
 var ImportBeginVOSchema = z.object({
   sessionId: z.string()
 });
 var ImportTablesInputSchema = z.object({
   sessionId: z.string(),
-  table: z.union([DumpTableSchema, z.literal("docBodies"), z.literal("attachmentBlobs")]),
+  table: z.union([
+    DumpTableSchema,
+    z.literal("docBodies"),
+    z.literal("attachmentBlobs"),
+    z.literal("assetTextBlobs")
+  ]),
   rows: z.array(z.record(z.string(), z.unknown()))
 });
 var ImportTablesVOSchema = z.object({
@@ -1938,6 +1983,13 @@ var dumpContract = {
     summary: "Export raw rows for one table (cursor-paginated)",
     successDescription: "A page of raw rows for the requested table (id-ordered), plus an opaque nextCursor (null at the end). Vault items and webhook secrets are never exportable through this endpoint."
   }).input(ExportTablesInputSchema).output(ExportTablesVOSchema),
+  exportAssetText: oc.route({
+    method: "GET",
+    path: "/dump/export/asset-texts/{assetId}/content",
+    tags: ["Dump"],
+    summary: "Resolve the download URL for one asset's extracted-text object",
+    successDescription: "A resolved download URL for the asset's DERIVED text blob (`asset-texts/blobs/sha256/\u2026`) plus its `textStorageKey` and `textContentHash`, so a backup can archive the exact bytes and verify them. `downloadUrl` is null when the row owns no separate object (auto-registered text-kind rows point at their attachment's own key, already covered by the attachment blobs; `status: \"none\"` rows have no text at all)."
+  }).input(ExportAssetTextInputSchema).output(ExportAssetTextVOSchema),
   importBegin: oc.route({
     method: "POST",
     path: "/dump/import/begin",
@@ -1950,7 +2002,7 @@ var dumpContract = {
     path: "/dump/import/tables",
     tags: ["Dump"],
     summary: "Import a batch of raw rows into an open session",
-    successDescription: "Inserted rows preserving their original ids. `docBodies` is a pseudo-table ({nodeId, markdown}[]) written directly to object storage (doc bodies are not a DB row)."
+    successDescription: "Inserted rows preserving their original ids. `docBodies` ({nodeId, markdown}[]), `attachmentBlobs` ({storageKey, mimeType, base64}[]) and `assetTextBlobs` ({textStorageKey, base64}[]) are pseudo-tables written directly to object storage (none of them are DB rows)."
   }).input(ImportTablesInputSchema).output(ImportTablesVOSchema),
   importCommit: oc.route({
     method: "POST",
@@ -2038,6 +2090,168 @@ var folderContract = {
     successDescription: "Folder node and its direct children."
   }).input(z.object({ nodeId: z.string() })).output(folderSchema)
 };
+var InstallPlanNodeTypeSchema = z.enum([
+  "folder",
+  "doc",
+  "base",
+  "skill",
+  "airapp",
+  "drive",
+  "file"
+]);
+var InstallPlanNodeVOSchema = z.object({
+  /** Package-relative path, e.g. `guides/faq`. Unique within a plan. */
+  path: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: InstallPlanNodeTypeSchema,
+  /** 0 for a top-level node under the target folder. */
+  depth: z.number().int().min(0),
+  /** Bases only. */
+  fieldCount: z.number().int().min(0).optional(),
+  /** Bases only — the per-base record count §15.4 asks the plan to surface. */
+  recordCount: z.number().int().min(0).optional(),
+  /** skill / airapp / drive only — files carried verbatim inside the node. */
+  fileCount: z.number().int().min(0).optional()
+});
+var InstallCollisionVOSchema = z.object({
+  kind: z.enum(["node", "base"]),
+  slug: z.string(),
+  /** Human-readable location, e.g. `my-package/product-catalog`. */
+  path: z.string(),
+  /** Set when `rename` resolved it — the slug that would actually be created. */
+  renamedTo: z.string().optional()
+});
+var InstallPlanCountsVOSchema = z.object({
+  folders: z.number().int().min(0),
+  docs: z.number().int().min(0),
+  bases: z.number().int().min(0),
+  records: z.number().int().min(0),
+  skills: z.number().int().min(0),
+  airapps: z.number().int().min(0),
+  drives: z.number().int().min(0),
+  files: z.number().int().min(0)
+});
+var InstallPackageInfoVOSchema = z.object({
+  name: z.string(),
+  description: z.string().default(""),
+  version: z.string().optional(),
+  author: z.string().optional(),
+  license: z.string().optional(),
+  homepage: z.string().optional(),
+  tags: z.array(z.string()).default([])
+});
+var InstallPlanVOSchema = z.object({
+  package: InstallPackageInfoVOSchema,
+  /** Resolved GitHub source, echoed back so the UI can show what it actually fetched. */
+  source: z.object({
+    owner: z.string(),
+    repo: z.string(),
+    ref: z.string().optional(),
+    subdir: z.string().optional()
+  }),
+  targetFolderSlug: z.string(),
+  nodes: z.array(InstallPlanNodeVOSchema).default([]),
+  counts: InstallPlanCountsVOSchema,
+  collisions: z.array(InstallCollisionVOSchema).default([]),
+  warnings: z.array(z.string()).default([]),
+  /**
+   * True when a record carries a relation VALUE. A relation stores the ids of the
+   * records it points at, and those exist only once the records are merged — so a
+   * review-first install would land every relation empty. `autoMerge` is required
+   * in that case, and the UI must say why.
+   */
+  requiresAutoMerge: z.boolean(),
+  /**
+   * Whether installing with **the options this plan was asked for** would work:
+   * false when a collision is unresolved, or when `requiresAutoMerge` is unmet
+   * for the `autoMerge` the caller passed.
+   *
+   * It is therefore an answer to "what happens if I install like this", not a
+   * property of the package — a package whose records carry relation values
+   * reports `applicable: false` when planned WITHOUT `autoMerge` and true WITH
+   * it. A client that offers an auto-merge toggle must re-plan when it changes
+   * (the same way it re-plans when `rename` or `intoFolder` change), rather than
+   * treating one plan's `applicable` as final.
+   *
+   * There is deliberately no `blockedReason` string here: the reason is already
+   * carried structurally by `collisions[]` (with `renamedTo`) and
+   * `requiresAutoMerge`, and each client words it for its own surface — a CLI
+   * says "re-run with --auto-merge", a dialog points at its own checkbox.
+   */
+  applicable: z.boolean()
+});
+var InstallCreatedCountsVOSchema = z.object({
+  folders: z.number().int().min(0),
+  docs: z.number().int().min(0),
+  bases: z.number().int().min(0),
+  views: z.number().int().min(0),
+  records: z.number().int().min(0),
+  fileTreeNodes: z.number().int().min(0),
+  files: z.number().int().min(0)
+});
+var InstallResultVOSchema = z.object({
+  targetFolderSlug: z.string(),
+  targetFolderNodeId: z.string(),
+  created: InstallCreatedCountsVOSchema,
+  /**
+   * Change requests left for a human to review. Structure (folders, Bases, their
+   * fields and views) is always created immediately — a pending Base has no id, so
+   * there would be nowhere to attach a view or a record. Content (records, docs,
+   * skills, AirApps) is what lands here for review.
+   */
+  pendingChangeRequests: z.number().int().min(0),
+  warnings: z.array(z.string()).default([])
+});
+var repoUrlField = z.string().min(1).describe(
+  "GitHub repo URL: https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]. Only GitHub hosts are accepted."
+);
+var intoFolderField = z.string().optional().describe("Slug of the folder to install into. Defaults to the package manifest's name.");
+var renameField = z.boolean().optional().describe(
+  "Resolve slug collisions by suffixing (-2, -3, \u2026) instead of refusing. Never overwrites anything."
+);
+var InstallPlanFromGithubDTOSchema = z.object({
+  repoUrl: repoUrlField,
+  intoFolder: intoFolderField,
+  rename: renameField,
+  /**
+   * Plan as if installing with auto-merge. Only affects the returned
+   * `applicable` (see `InstallPlanVOSchema`) — a dry run never writes either
+   * way. A client with an auto-merge toggle passes the toggle's current value so
+   * the preview answers the question the user is actually about to ask.
+   *
+   * `.optional()` with no `.default()`, matching `rename` above: `z.infer` gives
+   * the OUTPUT type, so a default would make this REQUIRED for every caller.
+   * Omitted means "plan without auto-merge" (applied in the logic layer).
+   */
+  autoMerge: z.boolean().optional()
+});
+var InstallFromGithubDTOSchema = z.object({
+  repoUrl: repoUrlField,
+  intoFolder: intoFolderField,
+  rename: renameField,
+  autoMerge: z.boolean().optional().describe(
+    "Merge the content change requests on the spot instead of leaving them for review. This trusts the package author: a package can carry skills and AirApps, i.e. code this space's agents will execute."
+  )
+});
+
+// ../../packages/busabase-contract/src/domains/install/contract.ts
+var installContract = {
+  planFromGithub: oc.route({
+    method: "POST",
+    path: "/install/github/plan",
+    tags: ["Install"],
+    summary: "Dry-run a GitHub package install",
+    successDescription: "What installing this package would create: the node outline, per-base record counts, slug collisions, warnings, and whether autoMerge is required. Creates nothing."
+  }).input(InstallPlanFromGithubDTOSchema).output(InstallPlanVOSchema),
+  fromGithub: oc.route({
+    method: "POST",
+    path: "/install/github",
+    tags: ["Install"],
+    summary: "Install a package from a GitHub repo",
+    successDescription: "Created counts plus the number of change requests left for review. Structure (folders, Bases, fields, views) is created immediately \u2014 a pending Base has no id to attach a view or record to; content (records, docs, skills, AirApps) lands as change requests unless `autoMerge` is set."
+  }).input(InstallFromGithubDTOSchema).output(InstallResultVOSchema)
+};
 
 // ../../packages/busabase-contract/src/domains/skill/contract.ts
 var skillContract = makeFileTreeContract("skills", "Skills");
@@ -2463,6 +2677,13 @@ var busabaseContractRoutes = {
       summary: "List node tree",
       successDescription: "Workspace node tree including folders, Bases, files, and agents. With no `parentId`/`depth`, returns the FULL tree (legacy behavior, still what every non-sidebar caller gets). Passing `parentId` and/or `depth` switches to a depth-bounded fetch: `parentId` omitted/null starts from the space root and returns it wrapped exactly like the legacy call (just depth-limited); an explicit `parentId` returns that node's children directly, ready to merge into its `NodeVO.children` for a sidebar's lazy per-folder expand. See `NodeVO.hasChildren` for how a depth boundary is surfaced."
     }).input(listNodesInputSchema).output(z.array(nodeSchema)),
+    searchByName: oc.route({
+      method: "GET",
+      path: "/nodes/search",
+      tags: ["Nodes", "Search"],
+      summary: "Search nodes by name/slug (cheap, name-only quick-jump)",
+      successDescription: "Plain ilike match on name/slug across every node type (folder/base/skill/drive/airapp/file/doc), scoped by the same node-visibility ACL as `nodes.list`. No content scan and no full-text ranking \u2014 ordered exact-slug-match first, then by name. Backs the dashboard search dialog's 'Recent' tab cache-miss path (see apps/busabase/content/spec/search-quick-jump.md); the heavier `search` endpoint remains the dedicated full-text content search."
+    }).input(searchNodesByNameInputSchema).output(z.array(nodeSearchResultSchema)),
     isDescendant: oc.route({
       method: "GET",
       path: "/nodes/{nodeId}/is-descendant",
@@ -2491,6 +2712,13 @@ var busabaseContractRoutes = {
       summary: "Move or reorder a node",
       successDescription: "Merged change request that repositioned the node under its (optionally new) parent. Applied immediately (auto-merged) since reordering is a low-risk structural tweak, not a review-worthy content change."
     }).input(moveNodeInputSchema).output(changeRequestSchema),
+    updateMetadata: oc.route({
+      method: "PATCH",
+      path: "/nodes/{nodeId}/metadata",
+      tags: ["Nodes"],
+      summary: "Update node metadata",
+      successDescription: "Shallow-merged the supplied top-level keys into the active node's existing metadata. Requires write access on the node."
+    }).input(updateNodeMetadataInputSchema).output(nodeSchema),
     purge: oc.route({
       method: "DELETE",
       path: "/nodes/{nodeId}",
@@ -2627,6 +2855,7 @@ var busabaseContractRoutes = {
   vault: vaultContract,
   webhooks: webhookContract,
   dump: dumpContract,
+  install: installContract,
   changeRequests: {
     list: oc.route({
       method: "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-sdk",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "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",