busa-sdk 0.9.9 → 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<{
@@ -1413,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<{
@@ -1508,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;
@@ -1546,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>>;
@@ -1576,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;
@@ -2562,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;
@@ -14792,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>>>;
@@ -22494,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;
@@ -23039,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;
@@ -23070,7 +23166,7 @@ interface NodeVO {
     slug: string;
     name: string;
     description: string;
-    metadata: {
+    metadata: Record<string, unknown> & {
         entryFile?: string;
         visibility?: "private" | "workspace" | "public";
         version?: string;

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,10 @@ 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)
@@ -647,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({
@@ -836,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
@@ -2081,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");
@@ -2541,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}",
@@ -2677,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.9",
+  "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",