busabase-sdk 0.10.2 → 0.11.0

package/dist/index.js

@@ -1,9 +1,34 @@
+import { normalizeBaseUrl } from './chunk-5NYQX65A.js';
+export { normalizeBaseUrl } from './chunk-5NYQX65A.js';
 import { createORPCClient, ORPCError } from '@orpc/client';
 import { OpenAPILink } from '@orpc/openapi-client/fetch';
 import { oc, eventIterator } from '@orpc/contract';
 import { z } from 'zod';
 
-// src/client.ts
+// src/asset-grep.ts
+var toUnifiedFilesGrepInput = (input) => ({
+  pattern: input.pattern,
+  flags: input.flags,
+  sources: ["files"],
+  scope: input.scope ? { files: input.scope } : void 0,
+  maxMatches: input.maxMatches,
+  contextLines: input.contextLines
+});
+var toFilesOnlyGrepResult = (result) => ({
+  matches: result.matches.flatMap((match) => {
+    if (match.source !== "files") return [];
+    const { source: _source, ...fileMatch } = match;
+    return [fileMatch];
+  }),
+  filesScanned: result.coverage.files.scanned,
+  missing: result.coverage.files.missing,
+  stale: result.coverage.files.stale,
+  unsearchable: result.coverage.files.unsearchable,
+  errored: result.coverage.files.errored,
+  notReached: result.coverage.files.notReached,
+  truncated: result.truncated
+});
+var grepAssets = async (client, input) => toFilesOnlyGrepResult(await client.grep(toUnifiedFilesGrepInput(input)));
 var i18n = {
   locales: ["en", "zh-CN", "zh-TW", "ja", "ko", "de", "fr", "es", "pt"]};
 var LocaleSchema = z.enum(i18n.locales);
@@ -536,7 +561,33 @@ var listNodesInputSchema = z.object({
    * soft-archived nodes for the Trash view — no `parentId`/`depth` walk, since
    * archived nodes are shown as a list, not a tree.
    */
-  status: z.enum(["active", "archived"]).optional().default("active")
+  status: z.enum(["active", "archived"]).optional().default("active"),
+  /**
+   * Narrow to specific node types and return a FLAT list of lightweight node
+   * summaries (`children: []`) instead of walking the tree. This is what
+   * replaced the four retired narrow listings (`GET /docs`, `/files`,
+   * `/folders`, `/file-trees`); file-trees are selected with their real
+   * discriminators `skill` / `drive` / `airapp`, since there is no synthetic
+   * "file-tree" node type.
+   *
+   * Omitting `types` leaves every existing caller on exactly today's
+   * behaviour (full tree, or a `parentId`/`depth`-bounded walk, or the
+   * archived flat list) — the two modes never interfere.
+   *
+   * NOTE — no `projection` parameter, deliberately. The consolidation roadmap
+   * sketched `?projection=summary`, but it also rules out adding
+   * `projection=detail` in this batch (the retired detail lists were the
+   * N+1 payloads this change exists to remove). That would leave a parameter
+   * with exactly one legal value, which is noise in OpenAPI/MCP/CLI rather
+   * than a decision a caller gets to make. Detail is `GET /nodes/{nodeId}`.
+   *
+   * A GET query param that occurs exactly once (`?types=doc`) arrives as a
+   * bare string, not a 1-element array — only a REPEATED occurrence
+   * (`?types=doc&types=file`) becomes an array. Accept both and normalize.
+   */
+  types: z.union([z.array(z.enum(NODE_TYPES)), z.enum(NODE_TYPES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe(
+    "Return a flat list of lightweight summaries for these node types instead of the tree. Read one node's full detail with GET /nodes/{nodeId}."
+  )
 }).optional();
 var isDescendantInputSchema = z.object({
   nodeId: z.string(),
@@ -704,11 +755,19 @@ var liveEventSchema = z.object({
     // via the audit funnel, but nothing needs reviewing). Consumed by
     // `use-live-sync.ts` to pop a desktop Notification, and by
     // busabase-cloud's host hook to persist an inbox notification row.
-    "change_request.pending_review"
+    "change_request.pending_review",
+    // A node's metadata was written directly, outside the change-request flow
+    // (`PATCH /api/v1/nodes/{nodeId}/metadata` — agents, the SDK, an MCP tool,
+    // and every rich-node editor's own Save). Carries the touched node in
+    // `nodeIds` so open dashboards refetch the node tree instead of showing a
+    // stale whiteboard/workflow/HTML document until the next reload.
+    "node.metadata_updated"
   ]),
   spaceId: z.string(),
   actorId: z.string(),
-  changeRequestId: z.string(),
+  // Null for events that aren't about a change request at all
+  // (`node.metadata_updated`), which is every direct, auto-audited write.
+  changeRequestId: z.string().nullable(),
   baseId: z.string().nullable(),
   nodeIds: z.array(z.string()),
   recordIds: z.array(z.string()),
@@ -1057,13 +1116,6 @@ var fileTreeRefSchema = z.object({
   type: fileTreeNodeTypeSchema.optional()
 });
 var fileTreeContract = {
-  list: oc.route({
-    method: "GET",
-    path: "/file-trees",
-    tags: ["File Trees"],
-    summary: "List file-tree nodes",
-    successDescription: "Skill, Drive, and AirApp nodes with their Asset-backed file trees. Pass `type` to narrow to one kind."
-  }).input(z.object({ type: fileTreeNodeTypeSchema.optional() })).output(z.array(fileTreeNodeSchema)),
   create: oc.route({
     method: "POST",
     path: "/file-trees",
@@ -1076,13 +1128,6 @@ var fileTreeContract = {
       changeRequestSchema.extend({ materialized: z.literal(false) })
     ])
   ),
-  get: oc.route({
-    method: "GET",
-    path: "/file-trees/{nodeId}",
-    tags: ["File Trees"],
-    summary: "Get file-tree node",
-    successDescription: "File-tree node detail and its file list."
-  }).input(fileTreeRefSchema).output(fileTreeNodeSchema),
   listFiles: oc.route({
     method: "GET",
     path: "/file-trees/{nodeId}/files",
@@ -1277,7 +1322,7 @@ var GREP_DEFAULT_MAX_MATCHES = 100;
 var GREP_HARD_MAX_MATCHES = 1e3;
 var GREP_DEFAULT_CONTEXT_LINES = 0;
 var GREP_MAX_CONTEXT_LINES = 10;
-var GrepInputSchema = z.object({
+z.object({
   pattern: z.string().min(1),
   /** JS RegExp flags, e.g. `"i"` for case-insensitive. `g`/`y` are ignored (grep always scans every match per line). */
   flags: z.string().optional().default(""),
@@ -1298,7 +1343,7 @@ var GrepMatchVOSchema = z.object({
   before: z.array(z.string()),
   after: z.array(z.string())
 });
-var GrepResultVOSchema = z.object({
+z.object({
   matches: z.array(GrepMatchVOSchema),
   filesScanned: z.number().int().nonnegative(),
   /** Asset ids in scope with no text yet (contentKind text-or-writable-binary, no row). */
@@ -1432,13 +1477,6 @@ var assetsContract = {
     summary: "Request a presigned upload URL for large text",
     successDescription: "Presigned (or dev) upload URL for a temporary text object; PUT the bytes there, then call putText with the returned storageKey to bind, verify, and content-address it."
   }).input(CreateTextUploadUrlInputSchema).output(CreateTextUploadUrlVOSchema),
-  grep: oc.route({
-    method: "POST",
-    path: "/assets/grep",
-    tags: ["Assets"],
-    summary: "Search every text-bearing asset in scope",
-    successDescription: "Streaming regex/literal matches with real file + line + column numbers and context, across every asset with text \u2014 any size, no 256KB cap. Honest coverage: missing/stale/unsearchable/errored name assets that were not (fully or successfully) searched, notReached counts present assets the scan never got to, and truncated flags a capped response."
-  }).input(GrepInputSchema).output(GrepResultVOSchema),
   readTextLines: oc.route({
     method: "GET",
     path: "/assets/{assetId}/text/lines",
@@ -1525,6 +1563,9 @@ var viewSchema = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var autoMergeSchema = z.boolean().optional().describe(
+  "Whether to approve and merge this view 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."
+);
 var createViewInputSchema = z.object({
   config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
   description: z.string().optional().default(""),
@@ -1532,7 +1573,8 @@ var createViewInputSchema = z.object({
   name: z.string().min(1),
   type: viewTypeSchema.optional().default("table"),
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var updateViewInputSchema = z.object({
   config: viewConfigSchema.optional(),
@@ -1540,15 +1582,18 @@ var updateViewInputSchema = z.object({
   message: z.string().optional().default("Update view"),
   name: z.string().min(1).optional(),
   type: viewTypeSchema.optional(),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var deleteViewInputSchema = z.object({
   message: z.string().optional().default("Delete view"),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var restoreViewInputSchema = z.object({
   message: z.string().optional().default("Restore view"),
-  submittedBy: z.string().optional().default("local-producer")
+  submittedBy: z.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var viewChangeRequestInputSchema = z.discriminatedUnion("operation", [
   createViewInputSchema.extend({
@@ -1616,6 +1661,19 @@ var listRecordsResponseSchema = z.object({
   records: z.array(recordSchema),
   nextCursor: z.string().nullable()
 });
+var listRecordsPageInputSchema = z.object({
+  baseId: z.string().min(1),
+  viewId: z.string().min(1).optional(),
+  page: z.coerce.number().int().min(1).optional().default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).optional().default(50)
+});
+var listRecordsPageResponseSchema = z.object({
+  records: z.array(recordSchema),
+  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 countRecordsInputSchema = z.object({
   baseId: z.string().optional()
 }).optional().default({});
@@ -1662,10 +1720,16 @@ var recordFieldFilterInputSchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional().default(50)
 });
 var recordFieldGetInputSchema = z.object({
-  baseId: z.string(),
-  fieldSlug: z.string().min(1),
-  valueText: z.string().min(1)
+  baseId: z.string().describe("Field selector: Base id. Requires fieldSlug and valueText."),
+  fieldSlug: z.string().min(1).describe("Field selector: exact field slug. Requires baseId and valueText."),
+  valueText: z.string().min(1).describe("Field selector: exact text value. Requires baseId and fieldSlug.")
 });
+var recordGetInputSchema = z.union([
+  z.object({
+    recordId: z.string().min(1).describe("Record id selector. Use alone; do not combine with field selector fields.")
+  }).strict(),
+  recordFieldGetInputSchema.strict()
+]);
 var restoreRecordInputSchema = z.object({
   message: z.string().optional(),
   submittedBy: z.string().optional().default("local-editor")
@@ -1801,6 +1865,13 @@ var recordContract = {
     summary: "List records",
     successDescription: "A page of canonical records plus an opaque nextCursor (null at the end). `status=archived` lists the Base's trash instead of its live rows."
   }).input(listRecordsInputSchema).output(listRecordsResponseSchema),
+  listPage: oc.route({
+    method: "GET",
+    path: "/records/page",
+    tags: ["Records"],
+    summary: "List a numbered record page",
+    successDescription: "A random-access page of active records. When viewId is supplied, the saved view is authoritatively filtered and sorted before total and page slicing are calculated."
+  }).input(listRecordsPageInputSchema).output(listRecordsPageResponseSchema),
   count: oc.route({
     method: "GET",
     path: "/records/count",
@@ -1810,11 +1881,15 @@ var recordContract = {
   }).input(countRecordsInputSchema).output(countRecordsResponseSchema),
   get: oc.route({
     method: "GET",
-    path: "/records/{recordId}",
+    path: "/records/get",
     tags: ["Records"],
     summary: "Get record",
-    successDescription: "Canonical record detail."
-  }).input(z.object({ recordId: z.string() })).output(recordSchema),
+    description: "Provide exactly one selector: recordId alone, or the complete baseId + fieldSlug + valueText tuple. Other combinations return 400.",
+    successDescription: "One canonical record selected by id or exact field value."
+  }).errors({
+    BAD_REQUEST: { status: 400, message: "Exactly one record selector is required" },
+    NOT_FOUND: { status: 404, message: "Record not found" }
+  }).input(recordGetInputSchema).output(recordSchema),
   search: oc.route({
     method: "GET",
     path: "/records/search",
@@ -1822,13 +1897,6 @@ var recordContract = {
     summary: "Filter records by field text",
     successDescription: "Canonical records matching a field text filter."
   }).input(recordFieldFilterInputSchema).output(z.array(recordSchema)),
-  getByField: oc.route({
-    method: "GET",
-    path: "/records/by-field",
-    tags: ["Records"],
-    summary: "Get record by field value",
-    successDescription: "Single canonical record whose field value exactly matches, or null when none does \u2014 a scoped point lookup (e.g. by a unique slug or path field), not a list."
-  }).input(recordFieldGetInputSchema).output(recordSchema.nullable()),
   changeRequest: oc.route({
     method: "POST",
     path: "/records/{recordId}/change-requests",
@@ -1862,8 +1930,13 @@ var viewContract = {
     path: "/views/change-requests",
     tags: ["Views", "Change Requests"],
     summary: "Create view change request",
-    successDescription: "Created change request proposing a view change. `operation` selects what to propose: `create` (addressed by `baseId`), or `update` / `delete` / `restore` (addressed by `viewId`)."
-  }).input(viewChangeRequestInputSchema).output(changeRequestSchema)
+    successDescription: "Proposes a view change. `operation` selects what to propose: `create` (addressed by `baseId`), or `update` / `delete` / `restore` (addressed by `viewId`). Review-first when the actor lacks write access or passes `autoMerge: false` \u2014 a pending ChangeRequest (`materialized: false`). Otherwise the change is approved and merged in the same call and the materialized View comes back instead (`materialized: true`)."
+  }).input(viewChangeRequestInputSchema).output(
+    z.union([
+      viewSchema.extend({ materialized: z.literal(true) }),
+      changeRequestSchema.extend({ materialized: z.literal(false) })
+    ])
+  )
 };
 var ReadDocLinesInputSchema = z.object({
   nodeId: z.string(),
@@ -1902,13 +1975,6 @@ var createDocChangeRequestInputSchema = z.object({
   submittedBy: z.string().optional().default("local-producer")
 });
 var docContract = {
-  list: oc.route({
-    method: "GET",
-    path: "/docs",
-    tags: ["Docs"],
-    summary: "List Doc nodes",
-    successDescription: "Doc nodes with their storage-backed bodies."
-  }).output(z.array(docSchema)),
   create: oc.route({
     method: "POST",
     path: "/docs",
@@ -1921,19 +1987,12 @@ var docContract = {
       changeRequestSchema.extend({ materialized: z.literal(false) })
     ])
   ),
-  get: oc.route({
-    method: "GET",
-    path: "/docs/{nodeId}",
-    tags: ["Docs"],
-    summary: "Get Doc node",
-    successDescription: "Doc node detail and body."
-  }).input(z.object({ nodeId: z.string() })).output(docSchema),
   readLines: oc.route({
     method: "GET",
     path: "/docs/{nodeId}/lines",
     tags: ["Docs"],
     summary: "Read an exact line range from a Doc body",
-    successDescription: "Lines [startLine, endLine] (range capped at 2000 lines / ~2MB response) sliced from the Doc's full body \u2014 Docs are KB-scale, so the whole body is read in memory; no byte-range/checkpoint machinery like assets.readTextLines uses for potentially multi-GB files. The Doc-domain follow-up to a Unified Grep match with `source: \"docs\"`, so an agent can read just the lines around a match instead of `get`'s entire body."
+    successDescription: "Lines [startLine, endLine] (range capped at 2000 lines / ~2MB response) sliced from the Doc's full body \u2014 Docs are KB-scale, so the whole body is read in memory; no byte-range/checkpoint machinery like assets.readTextLines uses for potentially multi-GB files. The Doc-domain follow-up to a Unified Grep match with `source: \"docs\"`, so an agent can read just the lines around a match instead of `nodes.get`'s entire body."
   }).input(ReadDocLinesInputSchema).output(ReadLinesVOSchema),
   updateBody: oc.route({
     method: "PUT",
@@ -2099,13 +2158,6 @@ var createFileNodeInputSchema = z.object({
   autoMerge: z.boolean().optional()
 });
 var fileContract = {
-  list: oc.route({
-    method: "GET",
-    path: "/files",
-    tags: ["Files"],
-    summary: "List File nodes",
-    successDescription: "Workspace File nodes with their backing Asset metadata."
-  }).output(z.array(FileNodeVOSchema)),
   create: oc.route({
     method: "POST",
     path: "/files",
@@ -2117,34 +2169,7 @@ var fileContract = {
       FileNodeVOSchema.extend({ materialized: z.literal(true) }),
       changeRequestSchema.extend({ materialized: z.literal(false) })
     ])
-  ),
-  get: oc.route({
-    method: "GET",
-    path: "/files/{nodeId}",
-    tags: ["Files"],
-    summary: "Get File node",
-    successDescription: "File node detail and backing Asset metadata."
-  }).input(z.object({ nodeId: z.string() })).output(FileNodeVOSchema)
-};
-var folderSchema = z.object({
-  node: nodeSchema,
-  children: z.array(nodeSchema)
-});
-var folderContract = {
-  list: oc.route({
-    method: "GET",
-    path: "/folders",
-    tags: ["Folders"],
-    summary: "List Folder nodes",
-    successDescription: "Folder nodes with their direct children."
-  }).output(z.array(folderSchema)),
-  get: oc.route({
-    method: "GET",
-    path: "/folders/{nodeId}",
-    tags: ["Folders"],
-    summary: "Get Folder node",
-    successDescription: "Folder node and its direct children."
-  }).input(z.object({ nodeId: z.string() })).output(folderSchema)
+  )
 };
 var FormFieldBindingSchema = z.object({
   inputName: z.string().min(1),
@@ -2697,7 +2722,7 @@ var UnifiedGrepScopeSchema = z.object({
 });
 var UnifiedGrepInputSchema = z.object({
   pattern: z.string().min(1),
-  /** JS RegExp flags, e.g. `"i"` for case-insensitive — same language as `assets.grep`. */
+  /** JS RegExp flags, e.g. `"i"` for case-insensitive. */
   flags: z.string().optional().default(""),
   /** Which sources to scan. Omitted = all three (`files`, `docs`, `records`). */
   sources: z.array(GrepSourceSchema).optional(),
@@ -2777,16 +2802,86 @@ var UnifiedGrepResultVOSchema = z.object({
   /** True when any source truncated, or any source has `notReached > 0`. */
   truncated: z.boolean()
 });
+var folderSchema = z.object({
+  node: nodeSchema,
+  children: z.array(nodeSchema)
+});
+
+// ../../packages/busabase-contract/src/contract/node-detail-schemas.ts
+var genericNodeDetailSchema = (type) => z.object({
+  type: z.literal(type),
+  node: nodeSchema
+});
+var NODE_DETAIL_VARIANTS = {
+  folder: folderSchema.extend({ type: z.literal("folder") }),
+  doc: docSchema.extend({ type: z.literal("doc") }),
+  file: FileNodeVOSchema.extend({ type: z.literal("file") }),
+  // Skills, Drives, and AirApps are one server-side shape (`fileTreeNodeSchema`)
+  // but three real node types — there is no synthetic "file-tree" node type, so
+  // each gets its own discriminated variant rather than a shared alias.
+  skill: fileTreeNodeSchema.extend({ type: z.literal("skill") }),
+  drive: fileTreeNodeSchema.extend({ type: z.literal("drive") }),
+  airapp: fileTreeNodeSchema.extend({ type: z.literal("airapp") }),
+  base: genericNodeDetailSchema("base"),
+  form: genericNodeDetailSchema("form"),
+  whiteboard: genericNodeDetailSchema("whiteboard"),
+  workflow: genericNodeDetailSchema("workflow"),
+  html: genericNodeDetailSchema("html")
+};
+var NodeDetailVOSchema = z.discriminatedUnion("type", [
+  NODE_DETAIL_VARIANTS.folder,
+  NODE_DETAIL_VARIANTS.doc,
+  NODE_DETAIL_VARIANTS.file,
+  NODE_DETAIL_VARIANTS.skill,
+  NODE_DETAIL_VARIANTS.drive,
+  NODE_DETAIL_VARIANTS.airapp,
+  NODE_DETAIL_VARIANTS.base,
+  NODE_DETAIL_VARIANTS.form,
+  NODE_DETAIL_VARIANTS.whiteboard,
+  NODE_DETAIL_VARIANTS.workflow,
+  NODE_DETAIL_VARIANTS.html
+]);
+var getNodeInputSchema = z.object({
+  nodeId: z.string().describe("Node id, or a slug that is unique within its type."),
+  type: z.enum(NODE_TYPES).optional().describe(
+    "Optional disambiguation hint, only needed when `nodeId` is a slug that exists under more than one node type."
+  )
+});
 
 // ../../packages/busabase-contract/src/contract/busabase.ts
-var changeRequestBatchResultSchema = z.object({
+var changeRequestBatchFailureSchema = z.object({
+  changeRequestId: z.string(),
+  ok: z.literal(false),
+  error: z.string(),
+  code: z.string().optional(),
+  data: z.unknown().optional()
+});
+var changeRequestReviewBatchResultSchema = z.object({
   results: z.array(
-    z.object({
-      changeRequestId: z.string(),
-      ok: z.boolean(),
-      status: z.string().optional(),
-      error: z.string().optional()
-    })
+    z.discriminatedUnion("ok", [
+      z.object({
+        changeRequestId: z.string(),
+        ok: z.literal(true),
+        status: z.string(),
+        changeRequest: changeRequestSchema
+      }),
+      changeRequestBatchFailureSchema
+    ])
+  )
+});
+var changeRequestMergeBatchResultSchema = z.object({
+  results: z.array(
+    z.discriminatedUnion("ok", [
+      z.object({
+        changeRequestId: z.string(),
+        ok: z.literal(true),
+        status: z.string(),
+        changeRequest: changeRequestSchema,
+        record: recordSchema.nullable(),
+        view: viewSchema.nullable()
+      }),
+      changeRequestBatchFailureSchema
+    ])
   )
 });
 var busabaseContractRoutes = {
@@ -2806,11 +2901,9 @@ var busabaseContractRoutes = {
     summary: "Search Busabase",
     successDescription: "Paginated search results across records, change requests, Bases, File nodes, and Assets."
   }).input(searchInputSchema).output(searchResponseSchema),
-  // Unified Grep (P2a files+docs, P2b records) — top-level, cross-source
-  // superset of `assets.grep`. See apps/busabase/content/spec/unified-grep.md.
-  // Composes `logic/grep.ts`; `assets.grep` (files-only specialist) is
-  // unchanged and stays the dedicated endpoint for its fuller
-  // missing/stale/unsearchable reporting.
+  // Unified Grep (P2a files+docs, P2b records) — the single public pattern
+  // search endpoint. Files-only callers use `sources: ["files"]` and retain
+  // the full missing/stale/unsearchable coverage block.
   grep: oc.route({
     method: "POST",
     path: "/grep",
@@ -2823,8 +2916,8 @@ var busabaseContractRoutes = {
       method: "GET",
       path: "/nodes",
       tags: ["Nodes"],
-      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."
+      summary: "List nodes (workspace tree, or a flat summary list by type)",
+      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. Passing `types` instead returns a FLAT, ACL-filtered list of lightweight summaries (`children: []`) for just those node types \u2014 this is what replaced `GET /docs`, `/files`, `/folders`, and `/file-trees`, and it deliberately hydrates nothing heavy (no Doc bodies, backing Assets, folder children, or file inventories). Open one item with `GET /nodes/{nodeId}`."
     }).input(listNodesInputSchema).output(z.array(nodeSchema)),
     searchByName: oc.route({
       method: "GET",
@@ -2894,6 +2987,21 @@ var busabaseContractRoutes = {
       summary: "List the current actor's favorited nodes",
       successDescription: "The acting user's favorited nodes, newest-favorited first, filtered through the same archived/deleted/visibility rules as the main tree \u2014 a favorited node that's later archived, purged, or (cloud) hidden from this actor silently drops out rather than erroring."
     }).output(z.array(nodeSchema)),
+    // Registered LAST among the `/nodes/...` GETs on purpose. `GET /nodes/search`
+    // and `GET /nodes/favorites` are literal paths that now share a prefix with
+    // this template. The oRPC OpenAPI matcher is a rou3 radix trie, which
+    // prefers a static segment over a param segment independently of insertion
+    // order — but keeping the literals declared first means the source order
+    // matches the resolution order, so nobody has to know that to read this
+    // file. `tests/openapi-node-routes.test.ts` proves the literals still win
+    // against a real handler rather than resolving as `nodeId: "search"`.
+    get: oc.route({
+      method: "GET",
+      path: "/nodes/{nodeId}",
+      tags: ["Nodes"],
+      summary: "Get one node's typed detail",
+      successDescription: "The node's full detail, discriminated by its `type`. One entry point for every node type, so a caller holding an id never has to discover the type first: `folder` carries its direct `children`, `doc` its storage-backed `body`, `file` its backing `asset`, and `skill`/`drive`/`airapp` their Asset-backed `files`. Types with no richer detail yet (`base`, `form`, `whiteboard`, `workflow`, `html`) return just `node`. `nodeId` accepts an id or a slug; pass `type` when a slug exists under more than one type. Archived nodes are not returned (404), matching the typed gets this replaced."
+    }).input(getNodeInputSchema).output(NodeDetailVOSchema),
     principals: {
       list: oc.route({
         method: "GET",
@@ -3027,7 +3135,9 @@ var busabaseContractRoutes = {
   airapps: airappRuntimeContract,
   files: fileContract,
   docs: docContract,
-  folders: folderContract,
+  // No `folders` key: the Folder domain's only two operations were `GET /folders`
+  // and `GET /folders/{nodeId}`, both now served by the unified Node surface
+  // (`nodes.list({ types: ["folder"] })` / `nodes.get`).
   forms: formContract,
   assets: assetsContract,
   vault: vaultContract,
@@ -3059,23 +3169,16 @@ var busabaseContractRoutes = {
       successDescription: "Change Request detail."
     }).input(z.object({ changeRequestId: z.string() })).output(changeRequestSchema),
     review: oc.route({
-      method: "POST",
-      path: "/change-requests/{changeRequestId}/reviews",
-      tags: ["Change Requests"],
-      summary: "Review change request",
-      successDescription: "Reviewed change request."
-    }).input(reviewChangeRequestInputSchema.extend({ changeRequestId: z.string() })).output(changeRequestSchema),
-    reviewMany: oc.route({
       method: "POST",
       path: "/change-requests/reviews",
       tags: ["Change Requests"],
-      summary: "Review many change requests",
+      summary: "Review change requests",
       successDescription: "Per-change-request review results (failures isolated \u2014 one bad id does not abort the rest)."
     }).input(
       reviewChangeRequestInputSchema.extend({
         changeRequestIds: z.array(z.string()).min(1).max(100)
       })
-    ).output(changeRequestBatchResultSchema),
+    ).output(changeRequestReviewBatchResultSchema),
     close: oc.route({
       method: "POST",
       path: "/change-requests/{changeRequestId}/close",
@@ -3084,25 +3187,12 @@ var busabaseContractRoutes = {
       successDescription: "Closed change request (terminal \u2014 distinct from request changes)."
     }).input(z.object({ changeRequestId: z.string(), reason: z.string().optional() })).output(changeRequestSchema),
     merge: oc.route({
-      method: "POST",
-      path: "/change-requests/{changeRequestId}/merge",
-      tags: ["Change Requests"],
-      summary: "Merge change request into Base",
-      successDescription: "Merged change request and canonical record."
-    }).input(z.object({ changeRequestId: z.string() })).output(
-      z.object({
-        changeRequest: changeRequestSchema,
-        record: recordSchema.nullable(),
-        view: viewSchema.nullable()
-      })
-    ),
-    mergeMany: oc.route({
       method: "POST",
       path: "/change-requests/merge",
       tags: ["Change Requests"],
-      summary: "Merge many change requests",
+      summary: "Merge change requests",
       successDescription: "Per-change-request merge results (each merged in its own transaction; failures isolated)."
-    }).input(z.object({ changeRequestIds: z.array(z.string()).min(1).max(100) })).output(changeRequestBatchResultSchema)
+    }).input(z.object({ changeRequestIds: z.array(z.string()).min(1).max(100) })).output(changeRequestMergeBatchResultSchema)
   },
   operations: {
     revise: oc.route({
@@ -3384,9 +3474,6 @@ var env = (key) => {
   const value = process.env[key];
   return value && value.length > 0 ? value : void 0;
 };
-function normalizeBaseUrl(raw) {
-  return raw.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
-}
 function resolveConfig(config = {}) {
   return {
     baseUrl: normalizeBaseUrl(config.baseUrl ?? env("BUSABASE_BASE_URL") ?? DEFAULT_BASE_URL),
@@ -3434,7 +3521,22 @@ function createBusabaseClient(config = {}) {
   return createORPCClient(link);
 }
 
+// src/record-get.ts
+var isNotFound = (error) => typeof error === "object" && error !== null && ("status" in error && error.status === 404 || "code" in error && error.code === "NOT_FOUND");
+var getRecordByField = async (client, input) => {
+  try {
+    return await client.records.get(input);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+};
+
 // src/index.ts
+var batchItemError = (result) => Object.assign(new Error(result?.error ?? "Change request action returned no result"), {
+  ...result?.code ? { code: result.code } : {},
+  ...result?.data === void 0 ? {} : { data: result.data }
+});
 var Busabase = class {
   /** The underlying fully-typed oRPC client. Use it for anything not surfaced here. */
   client;
@@ -3450,17 +3552,67 @@ var Busabase = class {
     return this.client.bases;
   }
   get records() {
-    return this.client.records;
+    const getByField = (input) => getRecordByField(this.client, input);
+    return new Proxy(this.client.records, {
+      get(target, property, receiver) {
+        if (property === "getByField") return getByField;
+        return Reflect.get(target, property, receiver);
+      }
+    });
   }
   get views() {
     return this.client.views;
   }
   get changeRequests() {
-    return this.client.changeRequests;
+    const review = async (input) => {
+      if ("changeRequestIds" in input) return this.client.changeRequests.review(input);
+      const { changeRequestId, ...reviewInput } = input;
+      const { results } = await this.client.changeRequests.review({
+        ...reviewInput,
+        changeRequestIds: [changeRequestId]
+      });
+      const result = results[0];
+      if (!result?.ok) throw batchItemError(result);
+      return result.changeRequest;
+    };
+    const merge = async (input) => {
+      if ("changeRequestIds" in input) return this.client.changeRequests.merge(input);
+      const { results } = await this.client.changeRequests.merge({
+        changeRequestIds: [input.changeRequestId]
+      });
+      const result = results[0];
+      if (!result?.ok) throw batchItemError(result);
+      return {
+        changeRequest: result.changeRequest,
+        record: result.record,
+        view: result.view
+      };
+    };
+    return new Proxy(this.client.changeRequests, {
+      get(target, property, receiver) {
+        if (property === "review") return review;
+        if (property === "merge") return merge;
+        return Reflect.get(target, property, receiver);
+      }
+    });
   }
   get operations() {
     return this.client.operations;
   }
+  /**
+   * The workspace node surface, and the single entry point for reading ONE node
+   * of any type: `bb.nodes.get({ nodeId })` returns a `NodeDetailVO`
+   * discriminated by `type` (`folder` carries `children`, `doc` a `body`, `file`
+   * its `asset`, `skill`/`drive`/`airapp` their `files`). It replaced the four
+   * typed gets (`docs`/`files`/`folders`/`fileTrees`), so a caller holding an id
+   * no longer has to know the node's type before it can read it.
+   *
+   * `bb.nodes.list({ types })` is the matching list: a flat array of lightweight
+   * summaries for just those types. Without `types` it still returns the full
+   * workspace tree.
+   *
+   * There is no `bb.folders` any more — folders are `type: "folder"` here.
+   */
   get nodes() {
     return this.client.nodes;
   }
@@ -3474,21 +3626,46 @@ var Busabase = class {
     return this.client.agent;
   }
   get assets() {
-    return this.client.assets;
+    const filesOnlyGrep = (input) => grepAssets(this.client, input);
+    return new Proxy(this.client.assets, {
+      get(target, property, receiver) {
+        if (property === "grep") return filesOnlyGrep;
+        return Reflect.get(target, property, receiver);
+      }
+    });
   }
-  /** Skills, Drives, and AirApps — one surface, discriminated by `type`. */
+  /**
+   * Skills, Drives, and AirApps — one surface, discriminated by `type`.
+   *
+   * Creation and per-file reads/writes live here. Listing them and reading one
+   * node's detail moved to the unified Node surface:
+   * `bb.nodes.list({ types: ["skill", "drive", "airapp"] })` and
+   * `bb.nodes.get({ nodeId, type })`.
+   */
   get fileTrees() {
     return this.client.fileTrees;
   }
+  /**
+   * File nodes. `create` only — list with `bb.nodes.list({ types: ["file"] })`
+   * and read one (backing Asset included) with `bb.nodes.get({ nodeId })`.
+   */
   get files() {
     return this.client.files;
   }
+  /**
+   * Docs. Create / read a line range / update the body / open a Change Request.
+   * List with `bb.nodes.list({ types: ["doc"] })` and read one (body included)
+   * with `bb.nodes.get({ nodeId })`.
+   *
+   * There is deliberately no `bb.docs.list()` shim. The retired `GET /docs`
+   * returned every Doc *with its body*; the one-call replacement returns
+   * lightweight summaries, and the only way to keep the old shape would be a
+   * detail request per Doc. An SDK convenience that quietly turns one call into
+   * N is worse than a compile error that points at `bb.nodes`.
+   */
   get docs() {
     return this.client.docs;
   }
-  get folders() {
-    return this.client.folders;
-  }
   get agentTasks() {
     return this.client.agentTasks;
   }
@@ -3507,10 +3684,8 @@ var Busabase = class {
    * source (Drive/Skill files, Doc bodies, and Base records — records read
    * the canonical `headCommit.fields`, never the truncated search
    * projection), with a shared `maxMatches`/deadline budget and per-source
-   * honest coverage. Use this when the answer could live anywhere; use
-   * `client.assets.grep` directly instead when you specifically only care
-   * about files and want its fuller `missing`/`stale`/`unsearchable`
-   * file-only reporting.
+   * honest coverage. `bb.assets.grep` remains available as a files-only SDK
+   * convenience and delegates here with `sources: ["files"]`.
    */
   grep(input) {
     return this.client.grep(input);
@@ -3560,4 +3735,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, getRecordByField, grepAssets, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };