busabase-sdk 0.11.0 → 0.11.3

package/dist/index.js

@@ -36,6 +36,9 @@ var LocaleSchema = z.enum(i18n.locales);
 // ../../packages/openlib/i18n/i-string.ts
 var iStringRecordSchema = z.partialRecord(LocaleSchema, z.string());
 z.union([z.string(), iStringRecordSchema]).describe("i18n string");
+var autoMergeNotAccepted = (reason) => z.literal(false, { error: `\`autoMerge: true\` is not accepted here: ${reason}` }).optional().describe(`Only \`false\` (or omitted) is accepted. ${reason}`);
+
+// ../../packages/busabase-contract/src/domains/base/contract/base-schemas.ts
 var fieldNameSchema = z.union([
   z.string().min(1),
   iStringRecordSchema.refine(
@@ -191,14 +194,21 @@ var createBaseFieldInputSchema = z.object({
   required: z.boolean().optional().default(false),
   options: fieldOptionsSchema.optional().default({})
 });
+var fieldAutoMergeSchema = z.boolean().optional().describe(
+  "Whether to approve and merge this field change immediately. Omitted defaults to merging immediately if the actor has write access on the Base's node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. Not accepted by the delete and convert operations, which always require review."
+);
 var createFieldChangeRequestInputSchema = createBaseFieldInputSchema.extend({
   message: z.string().optional().default("Add field"),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: fieldAutoMergeSchema
 });
 var deleteFieldChangeRequestInputSchema = z.object({
   fieldId: z.string().min(1),
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: autoMergeNotAccepted(
+    "deleting a field soft-deletes its stored values with it, so it always requires review. Omit the flag."
+  )
 });
 var updateFieldChangeRequestInputSchema = z.object({
   fieldId: z.string().min(1),
@@ -208,7 +218,8 @@ var updateFieldChangeRequestInputSchema = z.object({
     options: fieldOptionsSchema.optional()
   }),
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: fieldAutoMergeSchema
 });
 var previewFieldConversionInputSchema = z.object({
   fieldId: z.string().min(1),
@@ -225,25 +236,39 @@ var convertFieldChangeRequestInputSchema = z.object({
   newType: fieldTypeSchema,
   selectChoiceMode: z.enum(["auto_create", "null_on_missing"]).default("null_on_missing"),
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: autoMergeNotAccepted(
+    "converting a field's type can drop values, so it always requires review. Run previewFieldConversion first to see what would change, then omit the flag."
+  )
 });
 var reorderFieldsChangeRequestInputSchema = z.object({
   fieldIds: z.array(z.string()).min(1),
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: fieldAutoMergeSchema
 });
 var archiveBaseInputSchema = z.object({
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: autoMergeNotAccepted(
+    "archiving a Base removes it and every record in it from every listing at once, so it always requires review. Omit the flag."
+  )
 });
 var restoreBaseInputSchema = z.object({
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  // Restoring an archived Base is the undo of a destructive act — nothing is at
+  // risk, so it takes the same permission-aware default as everything else.
+  // `archiveBaseInputSchema` above deliberately has no `autoMerge`: archiving
+  // takes a whole Base and every record in it out of every listing at once,
+  // which is strictly larger than the record `delete` that is already review-only.
+  autoMerge: z.boolean().optional()
 });
 var restoreFieldChangeRequestInputSchema = z.object({
   fieldId: z.string().min(1),
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: fieldAutoMergeSchema
 });
 var withBaseId = { baseId: z.string().min(1) };
 var fieldChangeRequestInputSchema = z.discriminatedUnion("operation", [
@@ -254,6 +279,10 @@ var fieldChangeRequestInputSchema = z.discriminatedUnion("operation", [
   reorderFieldsChangeRequestInputSchema.extend({ operation: z.literal("reorder"), ...withBaseId }),
   restoreFieldChangeRequestInputSchema.extend({ operation: z.literal("restore"), ...withBaseId })
 ]);
+var baseLifecycleChangeRequestInputSchema = z.discriminatedUnion("operation", [
+  archiveBaseInputSchema.extend({ operation: z.literal("archive"), ...withBaseId }),
+  restoreBaseInputSchema.extend({ operation: z.literal("restore"), ...withBaseId })
+]);
 
 // ../../packages/busabase-contract/src/domains/filetree/definition.ts
 var fileTreeOperations = (type) => [
@@ -896,7 +925,10 @@ var createDeleteChangeRequestInputSchema = z.object({
   submittedBy: z.string().optional().default("local-producer"),
   // Only "archive" is supported — hard delete after retention was never
   // implemented, so the API no longer accepts it (breaking change).
-  deleteMode: z.enum(["archive"]).optional().default("archive")
+  deleteMode: z.enum(["archive"]).optional().default("archive"),
+  autoMerge: autoMergeNotAccepted(
+    "archiving a record removes user content from every listing, so it always requires review. Omit the flag."
+  )
 });
 var reviseOperationInputSchema = z.object({
   fields: z.record(z.string(), z.unknown()).describe(
@@ -938,6 +970,19 @@ var listChangeRequestsResponseSchema = z.object({
   changeRequests: z.array(changeRequestSchema),
   nextCursor: z.string().nullable()
 });
+var listChangeRequestsPageInputSchema = z.object({
+  page: z.coerce.number().int().min(1).optional().default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).optional().default(50),
+  status: z.array(changeRequestStatusSchema).optional(),
+  mine: z.boolean().optional()
+}).optional().default({ page: 1, pageSize: 50 });
+var listChangeRequestsPageResponseSchema = z.object({
+  changeRequests: z.array(changeRequestSchema),
+  total: z.number().int().nonnegative(),
+  totalPages: z.number().int().nonnegative(),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1).max(100)
+});
 var changeRequestCountsSchema = z.object({
   review: z.number().int().nonnegative(),
   changes: z.number().int().nonnegative(),
@@ -1107,7 +1152,16 @@ var createFileTreeChangeRequestInputSchema = z.object({
     'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Rewrite README.md quickstart for the new auth flow".'
   ),
   submittedBy: z.string().optional().default("local-producer"),
-  operations: z.array(fileTreeFileOperationInputSchema).min(1)
+  operations: z.array(fileTreeFileOperationInputSchema).min(1),
+  // Honoured only when EVERY operation in the batch is non-destructive
+  // (create / update / metadata_update). A batch containing a `delete` stays
+  // review-first no matter what this says, because deleting a mounted file
+  // destroys content — the same line that keeps record `delete` review-only.
+  // Server-side enforcement lives in the filetree handler, not here: the check
+  // is over the operations array, which a per-field schema cannot express.
+  autoMerge: z.boolean().optional().describe(
+    "Whether to approve and merge these file changes immediately. Omitted defaults to merging immediately if the actor has write access on the node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. IGNORED when any operation is a delete \u2014 those batches always require review."
+  )
 });
 var FILE_TREE_NODE_TYPES = ["skill", "drive", "airapp"];
 var fileTreeNodeTypeSchema = z.enum(FILE_TREE_NODE_TYPES);
@@ -1391,7 +1445,10 @@ var EditAssetContentInputSchema = z.object({
   message: z.string().optional().default("Edit file content").describe(
     'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Fix typo in setup instructions".'
   ),
-  submittedBy: z.string().optional().default("agent")
+  submittedBy: z.string().optional().default("agent"),
+  autoMerge: autoMergeNotAccepted(
+    "editContent rewrites the real mounted file bytes, so it always requires review. Omit the flag."
+  )
 });
 var AssetDownloadInputSchema = z.object({ assetId: z.string() });
 var AssetDownloadVOSchema = z.object({
@@ -1674,9 +1731,42 @@ var listRecordsPageResponseSchema = z.object({
   page: z.number().int().min(1),
   pageSize: z.number().int().min(1).max(100)
 });
-var countRecordsInputSchema = z.object({
-  baseId: z.string().optional()
-}).optional().default({});
+var countRecordsShapeSchema = z.object({
+  baseId: z.string().optional(),
+  /**
+   * Count only the rows a saved View would display (the View's filters
+   * applied; its sort is ignored — a count doesn't need an order). A View
+   * belongs to exactly one Base, so this requires `baseId`.
+   */
+  viewId: z.string().optional(),
+  /**
+   * Ad-hoc filter conditions — same shape `records.list`'s `filters` uses —
+   * for composing a condition set without a saved View (e.g. an AirApp
+   * summary tile like "main-branch PRs"). Combined with the View's own
+   * filters (AND) when `viewId` is also given. Requires `baseId`: a field
+   * slug is only unambiguous within one Base, and proving a filter exact
+   * (see `countRecords`) requires that Base's real field definitions —
+   * never the caller-supplied `fieldType` hint, which elsewhere is only a
+   * pushdown hint and isn't trustworthy enough for an exact count.
+   */
+  filters: z.array(listRecordsFilterSchema).optional()
+}).superRefine((value, ctx) => {
+  if (value.viewId && !value.baseId) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["baseId"],
+      message: "baseId is required when viewId is given"
+    });
+  }
+  if (value.filters?.length && !value.baseId) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["baseId"],
+      message: "baseId is required when filters is given"
+    });
+  }
+});
+var countRecordsInputSchema = countRecordsShapeSchema.optional().default({});
 var countRecordsResponseSchema = z.object({
   /** Total active records in the space (optionally scoped to a base). */
   total: z.number().int().nonnegative()
@@ -1711,7 +1801,13 @@ var createBulkChangeRequestInputSchema = z.object({
   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."
-  )
+  ),
+  // Same permission-aware tri-state as the single-record endpoint above. N record
+  // CREATES are purely additive, so there is nothing here the review gate is
+  // protecting — and until now the published skill doc told agents to send N
+  // separate single-record calls precisely because this one could not merge,
+  // which is slower and produces N change requests instead of one.
+  autoMerge: z.boolean().optional()
 });
 var recordFieldFilterInputSchema = z.object({
   baseId: z.string().optional(),
@@ -1732,7 +1828,10 @@ var recordGetInputSchema = z.union([
 ]);
 var restoreRecordInputSchema = z.object({
   message: z.string().optional(),
-  submittedBy: z.string().optional().default("local-editor")
+  submittedBy: z.string().optional().default("local-editor"),
+  autoMerge: autoMergeNotAccepted(
+    "restoring a record brings archived content back into every listing, so it always requires review. Omit the flag."
+  )
 });
 var withRecordId = { recordId: z.string().min(1) };
 var recordChangeRequestInputSchema = z.discriminatedUnion("operation", [
@@ -1838,20 +1937,13 @@ var baseContract = {
     summary: "Preview field type conversion",
     successDescription: "Dry-run statistics for converting a field to a different type."
   }).input(previewFieldConversionInputSchema.extend({ baseId: z.string() })).output(previewFieldConversionOutputSchema),
-  archiveChangeRequest: oc.route({
-    method: "POST",
-    path: "/bases/{baseId}/archive/change-requests",
-    tags: ["Bases", "Change Requests"],
-    summary: "Archive base",
-    successDescription: "Created change request that archives a base."
-  }).input(archiveBaseInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
-  restoreChangeRequest: oc.route({
+  lifecycleChangeRequest: oc.route({
     method: "POST",
-    path: "/bases/{baseId}/restore/change-requests",
+    path: "/bases/{baseId}/lifecycle/change-requests",
     tags: ["Bases", "Change Requests"],
-    summary: "Restore base",
-    successDescription: "Created change request that restores an archived base."
-  }).input(restoreBaseInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema)
+    summary: "Create Base lifecycle change request",
+    successDescription: "Created change request that moves a Base between its lifecycle states. `operation` selects the direction: `archive` (soft-delete a live Base) or `restore` (bring an archived Base back)."
+  }).input(baseLifecycleChangeRequestInputSchema).output(changeRequestSchema)
 };
 var recordContract = {
   // One listing for records: always keyset-paginated, `baseId` always honoured,
@@ -1877,7 +1969,8 @@ var recordContract = {
     path: "/records/count",
     tags: ["Records"],
     summary: "Count records",
-    successDescription: "Total active records in the space, optionally scoped to a base."
+    description: "A real SQL COUNT \u2014 always the exact total, never a partial or capped number, so it's safe to render as a canonical figure (e.g. a dashboard summary tile). Plain `baseId` scoping is always cheap. Adding `viewId` and/or `filters` is exact too \u2014 provably-exact conditions (e.g. text equals/contains, not_empty/is_empty, checkbox is_true/is_false) stay a cheap SQL COUNT; everything else falls back to evaluating every matching row server-side, which is exact but not free on a large Base. Both `viewId` and `filters` require `baseId`.",
+    successDescription: "Total active records matching the scope: the whole space, one Base, a saved View, an ad-hoc filter set, or a combination."
   }).input(countRecordsInputSchema).output(countRecordsResponseSchema),
   get: oc.route({
     method: "GET",
@@ -1972,7 +2065,12 @@ var createDocChangeRequestInputSchema = z.object({
   message: z.string().optional().default("Update doc").describe(
     'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Add rollback steps to the deploy runbook".'
   ),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  // A Doc body update is the Doc-domain twin of a record `update`, which has taken
+  // the permission-aware default since #5712 — and this node type already has a
+  // direct-write bypass (`PUT /docs/{nodeId}/body`), so review-first here was never
+  // an actual guarantee, just a slower path to the same place.
+  autoMerge: z.boolean().optional()
 });
 var docContract = {
   create: oc.route({
@@ -3154,6 +3252,16 @@ var busabaseContractRoutes = {
       summary: "List change requests",
       successDescription: "A page of change requests plus an opaque nextCursor (null at the end). Filter with `status` and/or `mine`."
     }).input(listChangeRequestsPagedInputSchema).output(listChangeRequestsResponseSchema),
+    // Numbered paging alongside the cursor listing, mirroring records.listPage.
+    // Keyset is right for "keep scrolling"; a reviewer working a 2,000-item tab
+    // needs to jump to page 30 and to see how many pages there are at all.
+    listPage: oc.route({
+      method: "GET",
+      path: "/change-requests/page",
+      tags: ["Change Requests"],
+      summary: "List a numbered change request page",
+      successDescription: "A random-access page of change requests plus the total across the whole filter. Same `status` / `mine` filters as the cursor listing."
+    }).input(listChangeRequestsPageInputSchema).output(listChangeRequestsPageResponseSchema),
     counts: oc.route({
       method: "GET",
       path: "/change-requests/counts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.11.0",
+  "version": "0.11.3",
   "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",
@@ -49,9 +49,9 @@
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^2.1.8",
-    "busabase-contract": "0.11.0",
-    "openlib": "0.1.1",
-    "open-domains": "0.0.2"
+    "busabase-contract": "0.11.3",
+    "open-domains": "0.0.2",
+    "openlib": "0.1.1"
   },
   "engines": {
     "node": ">=24.18.0"