busabase-sdk 0.10.1 → 0.10.3

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);
@@ -220,6 +245,15 @@ var restoreFieldChangeRequestInputSchema = z.object({
   message: z.string().optional(),
   submittedBy: z.string().optional().default("local-editor")
 });
+var withBaseId = { baseId: z.string().min(1) };
+var fieldChangeRequestInputSchema = z.discriminatedUnion("operation", [
+  createFieldChangeRequestInputSchema.extend({ operation: z.literal("create"), ...withBaseId }),
+  updateFieldChangeRequestInputSchema.extend({ operation: z.literal("update"), ...withBaseId }),
+  deleteFieldChangeRequestInputSchema.extend({ operation: z.literal("delete"), ...withBaseId }),
+  convertFieldChangeRequestInputSchema.extend({ operation: z.literal("convert"), ...withBaseId }),
+  reorderFieldsChangeRequestInputSchema.extend({ operation: z.literal("reorder"), ...withBaseId }),
+  restoreFieldChangeRequestInputSchema.extend({ operation: z.literal("restore"), ...withBaseId })
+]);
 
 // ../../packages/busabase-contract/src/domains/filetree/definition.ts
 var fileTreeOperations = (type) => [
@@ -521,7 +555,13 @@ var listNodesInputSchema = z.object({
   parentId: z.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
   depth: z.coerce.number().int().min(1).max(5).optional().describe(
     "How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5."
-  )
+  ),
+  /**
+   * `active` (default) walks the live tree. `archived` returns the flat set of
+   * 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")
 }).optional();
 var isDescendantInputSchema = z.object({
   nodeId: z.string(),
@@ -850,6 +890,9 @@ var createCommentInputSchema = commentSubjectInputSchema.extend({
 var listInputSchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional().default(50)
 }).optional().default({ limit: 50 });
+var listByStatusInputSchema = z.object({
+  status: z.enum(["active", "archived"]).optional().default("active")
+});
 var listChangeRequestsPagedInputSchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional().default(50),
   /** Opaque base64 cursor (`createdAt|id`) for keyset pagination. */
@@ -1032,74 +1075,75 @@ var createFileTreeChangeRequestInputSchema = z.object({
   submittedBy: z.string().optional().default("local-producer"),
   operations: z.array(fileTreeFileOperationInputSchema).min(1)
 });
-var makeFileTreeContract = (routeBase, tag) => {
-  const label = tag.endsWith("s") ? tag.slice(0, -1) : tag;
-  const basePath = `/${routeBase}`;
-  return {
-    list: oc.route({
-      method: "GET",
-      path: basePath,
-      tags: [tag],
-      summary: `List ${label} nodes`,
-      successDescription: `${label} nodes with their Asset-backed file trees.`
-    }).output(z.array(fileTreeNodeSchema)),
-    create: oc.route({
-      method: "POST",
-      path: basePath,
-      tags: [tag],
-      summary: `Create ${label} node`,
-      successDescription: `Review-first by default: a pending ChangeRequest proposing the ${label} node (\`materialized: false\`). Returns the materialized ${label} node instead (\`materialized: true\`) when \`autoMerge: true\` is passed.`
-    }).input(createFileTreeInputSchema).output(
-      z.union([
-        fileTreeNodeSchema.extend({ materialized: z.literal(true) }),
-        changeRequestSchema.extend({ materialized: z.literal(false) })
-      ])
-    ),
-    get: oc.route({
-      method: "GET",
-      path: `${basePath}/{nodeId}`,
-      tags: [tag],
-      summary: `Get ${label} node`,
-      successDescription: `${label} node detail and file tree.`
-    }).input(z.object({ nodeId: z.string() })).output(fileTreeNodeSchema),
-    listFiles: oc.route({
-      method: "GET",
-      path: `${basePath}/{nodeId}/files`,
-      tags: [tag],
-      summary: `List ${label} files`,
-      successDescription: `Asset-backed files mounted under the ${label} node.`
-    }).input(z.object({ nodeId: z.string() })).output(z.array(fileTreeFileSchema)),
-    readFile: oc.route({
-      method: "GET",
-      path: `${basePath}/{nodeId}/files/{+filePath}`,
-      tags: [tag],
-      summary: `Read ${label} file`,
-      successDescription: `${label} file content and content hash.`
-    }).input(z.object({ nodeId: z.string(), filePath: z.string() })).output(
-      z.object({
-        nodeId: z.string(),
-        path: z.string(),
-        encoding: z.enum(["utf8", "url"]),
-        content: z.string(),
-        mimeType: z.string(),
-        assetId: z.string(),
-        displayName: z.string().nullable(),
-        assetUrl: z.string().nullable(),
-        contentHash: z.string()
-      })
-    ),
-    createChangeRequest: oc.route({
-      method: "POST",
-      path: `${basePath}/{nodeId}/change-requests`,
-      tags: [tag, "Change Requests"],
-      summary: `Create ${label} change request`,
-      successDescription: `Created file-tree change request for a ${label} node.`
-    }).input(createFileTreeChangeRequestInputSchema.extend({ nodeId: z.string() })).output(changeRequestSchema)
-  };
+var FILE_TREE_NODE_TYPES = ["skill", "drive", "airapp"];
+var fileTreeNodeTypeSchema = z.enum(FILE_TREE_NODE_TYPES);
+var fileTreeRefSchema = z.object({
+  nodeId: z.string(),
+  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",
+    tags: ["File Trees"],
+    summary: "Create file-tree node",
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the node (`materialized: false`). Returns the materialized node instead (`materialized: true`) when `autoMerge: true` is passed."
+  }).input(createFileTreeInputSchema.extend({ type: fileTreeNodeTypeSchema })).output(
+    z.union([
+      fileTreeNodeSchema.extend({ materialized: z.literal(true) }),
+      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",
+    tags: ["File Trees"],
+    summary: "List file-tree files",
+    successDescription: "Asset-backed files mounted under the node."
+  }).input(fileTreeRefSchema).output(z.array(fileTreeFileSchema)),
+  readFile: oc.route({
+    method: "GET",
+    path: "/file-trees/{nodeId}/files/{+filePath}",
+    tags: ["File Trees"],
+    summary: "Read file-tree file",
+    successDescription: "File content and content hash."
+  }).input(fileTreeRefSchema.extend({ filePath: z.string() })).output(
+    z.object({
+      nodeId: z.string(),
+      path: z.string(),
+      encoding: z.enum(["utf8", "url"]),
+      content: z.string(),
+      mimeType: z.string(),
+      assetId: z.string(),
+      displayName: z.string().nullable(),
+      assetUrl: z.string().nullable(),
+      contentHash: z.string()
+    })
+  ),
+  createChangeRequest: oc.route({
+    method: "POST",
+    path: "/file-trees/{nodeId}/change-requests",
+    tags: ["File Trees", "Change Requests"],
+    summary: "Create file-tree change request",
+    successDescription: "Created file-tree change request for the node."
+  }).input(createFileTreeChangeRequestInputSchema.extend(fileTreeRefSchema.shape)).output(changeRequestSchema)
 };
 
 // ../../packages/busabase-contract/src/domains/airapp/contract.ts
-var airappContract = makeFileTreeContract("airapps", "AirApps");
 var airAppRunLocalNodeInputSchema = z.object({
   nodeId: z.string(),
   /** Text files to mount into the sandbox workdir before installing, keyed by
@@ -1258,7 +1302,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(""),
@@ -1279,7 +1323,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). */
@@ -1413,13 +1457,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",
@@ -1531,6 +1568,24 @@ var restoreViewInputSchema = z.object({
   message: z.string().optional().default("Restore view"),
   submittedBy: z.string().optional().default("local-producer")
 });
+var viewChangeRequestInputSchema = z.discriminatedUnion("operation", [
+  createViewInputSchema.extend({
+    operation: z.literal("create"),
+    baseId: z.string().min(1).describe("Base the new view belongs to.")
+  }),
+  updateViewInputSchema.extend({
+    operation: z.literal("update"),
+    viewId: z.string().min(1)
+  }),
+  deleteViewInputSchema.extend({
+    operation: z.literal("delete"),
+    viewId: z.string().min(1)
+  }),
+  restoreViewInputSchema.extend({
+    operation: z.literal("restore"),
+    viewId: z.string().min(1)
+  })
+]);
 
 // ../../packages/busabase-contract/src/domains/base/contract/record-schemas.ts
 var recordSchema = z.object({
@@ -1564,20 +1619,33 @@ var listRecordsInputSchema = z.object({
   baseId: z.string().optional(),
   /** Opaque base64 cursor for keyset pagination (createdAt-keyed, or sort-keyed when `sort` is set). */
   cursor: z.string().optional(),
+  /**
+   * `active` (default) is the live table; `archived` is the Base's trash — the
+   * same keyset pagination either way, which is why these are one endpoint
+   * rather than a `/records/archived` twin.
+   */
+  status: z.enum(["active", "archived"]).optional().default("active"),
   /** View filters for server-side push-down (superset; client still narrows). */
   filters: z.array(listRecordsFilterSchema).optional(),
   /** View sort for server-side push-down (number/date fields only). */
   sort: listRecordsSortSchema.optional()
-}).optional().default({ limit: 50 });
+}).optional().default({ limit: 50, status: "active" });
 var listRecordsResponseSchema = z.object({
   records: z.array(recordSchema),
   nextCursor: z.string().nullable()
 });
-var listArchivedRecordsPagedInputSchema = z.object({
-  baseId: z.string(),
-  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
-  /** Opaque base64 cursor (createdAt-keyed) for keyset pagination. */
-  cursor: z.string().optional()
+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()
@@ -1625,14 +1693,30 @@ 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")
 });
+var withRecordId = { recordId: z.string().min(1) };
+var recordChangeRequestInputSchema = z.discriminatedUnion("operation", [
+  reviseOperationInputSchema.extend({
+    operation: z.literal("update"),
+    autoMerge: z.boolean().optional(),
+    ...withRecordId
+  }),
+  createDeleteChangeRequestInputSchema.extend({ operation: z.literal("delete"), ...withRecordId }),
+  restoreRecordInputSchema.extend({ operation: z.literal("restore"), ...withRecordId })
+]);
 var recordLinkSchema = z.object({
   id: z.string(),
   baseId: z.string(),
@@ -1652,22 +1736,15 @@ var baseContract = {
     path: "/bases",
     tags: ["Bases"],
     summary: "List Bases",
-    successDescription: "Flat list of developer-facing Bases."
-  }).output(z.array(baseSchema)),
-  listArchived: oc.route({
-    method: "GET",
-    path: "/bases/archived",
-    tags: ["Bases"],
-    summary: "List archived bases",
-    successDescription: "Bases that have been archived."
-  }).output(z.array(baseSchema)),
+    successDescription: "Developer-facing Bases. `status=archived` returns the archived ones instead of the active ones."
+  }).input(listByStatusInputSchema).output(z.array(baseSchema)),
   get: oc.route({
     method: "GET",
     path: "/bases/{baseId}",
     tags: ["Bases"],
     summary: "Get Base",
-    successDescription: "Single Base by id or slug."
-  }).input(z.object({ baseId: z.string() })).output(baseSchema.nullable()),
+    successDescription: "Single Base by id or slug, or 404 when it does not exist or is not visible."
+  }).input(z.object({ baseId: z.string() })).output(baseSchema),
   listDeletedFields: oc.route({
     method: "GET",
     path: "/bases/{baseId}/fields/deleted",
@@ -1679,30 +1756,9 @@ var baseContract = {
     method: "GET",
     path: "/bases/{baseId}/views",
     tags: ["Views"],
-    summary: "List active views for a Base",
-    successDescription: "Saved table views for a Base."
-  }).input(z.object({ baseId: z.string() })).output(z.array(viewSchema)),
-  listArchivedViews: oc.route({
-    method: "GET",
-    path: "/bases/{baseId}/views/archived",
-    tags: ["Views"],
-    summary: "List archived views for a Base",
-    successDescription: "Views that have been archived (soft-deleted) from a Base."
-  }).input(z.object({ baseId: z.string() })).output(z.array(viewSchema)),
-  listArchivedRecords: oc.route({
-    method: "GET",
-    path: "/bases/{baseId}/records/archived",
-    tags: ["Records"],
-    summary: "List archived records for a Base",
-    successDescription: "Records that have been archived (soft-deleted) from a Base."
-  }).input(z.object({ baseId: z.string() })).output(z.array(recordSchema)),
-  listArchivedRecordsPaged: oc.route({
-    method: "GET",
-    path: "/bases/{baseId}/records/archived/paged",
-    tags: ["Records"],
-    summary: "List archived records for a Base with keyset pagination",
-    successDescription: "A page of archived (soft-deleted) records plus an opaque nextCursor (null at the end)."
-  }).input(listArchivedRecordsPagedInputSchema).output(listRecordsResponseSchema),
+    summary: "List views for a Base",
+    successDescription: "Saved table views for a Base. `status=archived` returns the soft-deleted ones instead."
+  }).input(listByStatusInputSchema.extend({ baseId: z.string() })).output(z.array(viewSchema)),
   create: oc.route({
     method: "POST",
     path: "/bases",
@@ -1741,34 +1797,13 @@ var baseContract = {
     summary: "Create Base field",
     successDescription: "Created Base field."
   }).input(createBaseFieldInputSchema.extend({ baseId: z.string() })).output(baseSchema),
-  createFieldChangeRequest: oc.route({
+  fieldChangeRequest: oc.route({
     method: "POST",
     path: "/bases/{baseId}/fields/change-requests",
     tags: ["Bases", "Change Requests"],
-    summary: "Create Add Field change request",
-    successDescription: "Created change request that proposes a new field."
-  }).input(createFieldChangeRequestInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
-  createViewChangeRequest: oc.route({
-    method: "POST",
-    path: "/bases/{baseId}/views/change-requests",
-    tags: ["Views", "Change Requests"],
-    summary: "Create View change request",
-    successDescription: "Created change request that proposes a new View."
-  }).input(createViewInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
-  deleteFieldChangeRequest: oc.route({
-    method: "DELETE",
-    path: "/bases/{baseId}/fields/change-requests",
-    tags: ["Bases", "Change Requests"],
-    summary: "Create Delete Field change request",
-    successDescription: "Created change request that soft-deletes a field."
-  }).input(deleteFieldChangeRequestInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
-  updateFieldChangeRequest: oc.route({
-    method: "PATCH",
-    path: "/bases/{baseId}/fields/change-requests",
-    tags: ["Bases", "Change Requests"],
-    summary: "Create Update Field change request",
-    successDescription: "Created change request that updates field metadata (name, required, options)."
-  }).input(updateFieldChangeRequestInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
+    summary: "Create field change request",
+    successDescription: "Created change request proposing a field change. `operation` selects what to propose: `create`, `update`, `delete`, `convert` (change type), `reorder`, or `restore` (undo a soft delete)."
+  }).input(fieldChangeRequestInputSchema).output(changeRequestSchema),
   previewFieldConversion: oc.route({
     method: "POST",
     path: "/bases/{baseId}/fields/convert/preview",
@@ -1776,20 +1811,6 @@ 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),
-  convertFieldChangeRequest: oc.route({
-    method: "POST",
-    path: "/bases/{baseId}/fields/convert/change-requests",
-    tags: ["Bases", "Change Requests"],
-    summary: "Create Convert Field change request",
-    successDescription: "Created change request that converts a field to a different type."
-  }).input(convertFieldChangeRequestInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
-  reorderFieldsChangeRequest: oc.route({
-    method: "POST",
-    path: "/bases/{baseId}/fields/reorder/change-requests",
-    tags: ["Bases", "Change Requests"],
-    summary: "Reorder fields",
-    successDescription: "Created change request that reorders fields."
-  }).input(reorderFieldsChangeRequestInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
   archiveChangeRequest: oc.route({
     method: "POST",
     path: "/bases/{baseId}/archive/change-requests",
@@ -1803,30 +1824,27 @@ var baseContract = {
     tags: ["Bases", "Change Requests"],
     summary: "Restore base",
     successDescription: "Created change request that restores an archived base."
-  }).input(restoreBaseInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema),
-  restoreFieldChangeRequest: oc.route({
-    method: "POST",
-    path: "/bases/{baseId}/fields/restore/change-requests",
-    tags: ["Bases", "Change Requests"],
-    summary: "Restore deleted field",
-    successDescription: "Created change request that restores a soft-deleted field."
-  }).input(restoreFieldChangeRequestInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema)
+  }).input(restoreBaseInputSchema.extend({ baseId: z.string() })).output(changeRequestSchema)
 };
 var recordContract = {
+  // One listing for records: always keyset-paginated, `baseId` always honoured,
+  // `status` picking live rows or the trash. The old unpaginated `/records`
+  // silently dropped `baseId` (its schema had no such field), so a caller
+  // scoping to one Base quietly got the whole space back.
   list: oc.route({
     method: "GET",
     path: "/records",
     tags: ["Records"],
     summary: "List records",
-    successDescription: "Canonical records created from merged change requests."
-  }).input(listInputSchema).output(z.array(recordSchema)),
-  listPaged: oc.route({
+    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/paged",
+    path: "/records/page",
     tags: ["Records"],
-    summary: "List records with keyset pagination",
-    successDescription: "A page of canonical records plus an opaque nextCursor (null at the end)."
-  }).input(listRecordsInputSchema).output(listRecordsResponseSchema),
+    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",
@@ -1836,11 +1854,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",
@@ -1848,37 +1870,18 @@ 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()),
-  updateChangeRequest: oc.route({
-    method: "PUT",
+  changeRequest: oc.route({
+    method: "POST",
     path: "/records/{recordId}/change-requests",
     tags: ["Records", "Change Requests"],
-    summary: "Create record update change request",
-    successDescription: "Permission-aware by default: updates the record immediately when the actor has write access, otherwise returns a pending ChangeRequest. Pass `autoMerge: false` to force review."
-  }).input(
-    reviseOperationInputSchema.extend({
-      recordId: z.string(),
-      autoMerge: z.boolean().optional()
-    })
-  ).output(
+    summary: "Create record change request",
+    successDescription: "Creates a record change request selected by `operation`. Updates auto-merge when the actor has write access unless `autoMerge: false`; delete and restore remain review-first."
+  }).input(recordChangeRequestInputSchema).output(
     z.union([
       recordSchema.extend({ materialized: z.literal(true) }),
       changeRequestSchema.extend({ materialized: z.literal(false) })
     ])
   ),
-  deleteChangeRequest: oc.route({
-    method: "DELETE",
-    path: "/records/{recordId}/change-requests",
-    tags: ["Records", "Change Requests"],
-    summary: "Create record delete change request",
-    successDescription: "Created change request that proposes archiving or deleting a record."
-  }).input(createDeleteChangeRequestInputSchema.extend({ recordId: z.string() })).output(changeRequestSchema),
   listChangeRequests: oc.route({
     method: "GET",
     path: "/records/{recordId}/change-requests",
@@ -1886,13 +1889,6 @@ var recordContract = {
     summary: "List record change request history",
     successDescription: "Change requests and operations connected to the canonical record."
   }).input(z.object({ recordId: z.string() })).output(z.array(changeRequestSchema)),
-  restoreChangeRequest: oc.route({
-    method: "POST",
-    path: "/records/{recordId}/restore/change-requests",
-    tags: ["Records", "Change Requests"],
-    summary: "Create record restore change request",
-    successDescription: "Created change request that restores an archived record."
-  }).input(restoreRecordInputSchema.extend({ recordId: z.string() })).output(changeRequestSchema),
   listLinks: oc.route({
     method: "GET",
     path: "/records/{recordId}/links",
@@ -1902,27 +1898,13 @@ var recordContract = {
   }).input(z.object({ recordId: z.string() })).output(z.array(recordLinkSchema))
 };
 var viewContract = {
-  updateChangeRequest: oc.route({
-    method: "PUT",
-    path: "/views/{viewId}/change-requests",
-    tags: ["Views", "Change Requests"],
-    summary: "Create View update change request",
-    successDescription: "Created change request that proposes updating a View."
-  }).input(updateViewInputSchema.extend({ viewId: z.string() })).output(changeRequestSchema),
-  deleteChangeRequest: oc.route({
-    method: "DELETE",
-    path: "/views/{viewId}/change-requests",
-    tags: ["Views", "Change Requests"],
-    summary: "Create View delete change request",
-    successDescription: "Created change request that proposes archiving a View."
-  }).input(deleteViewInputSchema.extend({ viewId: z.string() })).output(changeRequestSchema),
-  restoreChangeRequest: oc.route({
+  changeRequest: oc.route({
     method: "POST",
-    path: "/views/{viewId}/restore/change-requests",
+    path: "/views/change-requests",
     tags: ["Views", "Change Requests"],
-    summary: "Create View restore change request",
-    successDescription: "Created change request that restores an archived View."
-  }).input(restoreViewInputSchema.extend({ viewId: z.string() })).output(changeRequestSchema)
+    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)
 };
 var ReadDocLinesInputSchema = z.object({
   nodeId: z.string(),
@@ -2009,9 +1991,6 @@ var docContract = {
     successDescription: "Created a change request that proposes a new Doc body."
   }).input(createDocChangeRequestInputSchema.extend({ nodeId: z.string() })).output(changeRequestSchema)
 };
-
-// ../../packages/busabase-contract/src/domains/drive/contract.ts
-var driveContract = makeFileTreeContract("drives", "Drives");
 var DumpTableSchema = z.enum([
   "nodes",
   /** Node-level access grants (permissions). Not secret — restore must keep them
@@ -2466,9 +2445,6 @@ var installContract = {
     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");
 var VaultItemKeySchema = z.string().trim().min(1).max(128).regex(/^[A-Z_][A-Z0-9_]*$/, "Use uppercase letters, numbers, and underscores");
 var VaultItemValueSchema = z.string().max(8192);
 var VaultItemKindSchema = z.enum(["secret", "variable"]);
@@ -2762,7 +2738,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(),
@@ -2871,11 +2847,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",
@@ -2905,13 +2879,6 @@ var busabaseContractRoutes = {
       summary: "Check whether a node is a descendant of another",
       successDescription: "Server-authoritative parentId-chain walk from nodeId up to potentialAncestorId. Used to gate cross-branch drag-and-drop drops in the sidebar, since the full tree is no longer guaranteed to be loaded client-side (depth-bounded lazy load) \u2014 a purely local walk could wrongly allow dropping a folder into its own unloaded descendant."
     }).input(isDescendantInputSchema).output(isDescendantOutputSchema),
-    listArchived: oc.route({
-      method: "GET",
-      path: "/nodes/archived",
-      tags: ["Nodes"],
-      summary: "List archived nodes",
-      successDescription: "Soft-archived folders, docs, and skills (for the Trash view)."
-    }).output(z.array(nodeSchema)),
     createChangeRequest: oc.route({
       method: "POST",
       path: "/nodes/change-requests",
@@ -3093,9 +3060,10 @@ var busabaseContractRoutes = {
     subscribe: oc.output(eventIterator(liveEventSchema))
   },
   bases: baseContract,
-  skills: skillContract,
-  drives: driveContract,
-  airapps: { ...airappContract, ...airappRuntimeContract },
+  // Skills, Drives, and AirApps share one transport surface — they differ only
+  // in seed files and entry file, which is a server-side config concern.
+  fileTrees: fileTreeContract,
+  airapps: airappRuntimeContract,
   files: fileContract,
   docs: docContract,
   folders: folderContract,
@@ -3106,18 +3074,13 @@ var busabaseContractRoutes = {
   dump: dumpContract,
   install: installContract,
   changeRequests: {
+    // Always keyset-paginated — the unpaginated twin returned a bare array that
+    // silently truncated at `limit` with no way to ask for the next page.
     list: oc.route({
       method: "GET",
       path: "/change-requests",
       tags: ["Change Requests"],
       summary: "List change requests",
-      successDescription: "Change requests waiting for review or ready to merge."
-    }).input(listInputSchema).output(z.array(changeRequestSchema)),
-    listPaged: oc.route({
-      method: "GET",
-      path: "/change-requests/paged",
-      tags: ["Change Requests"],
-      summary: "List change requests with keyset pagination",
       successDescription: "A page of change requests plus an opaque nextCursor (null at the end). Filter with `status` and/or `mine`."
     }).input(listChangeRequestsPagedInputSchema).output(listChangeRequestsResponseSchema),
     counts: oc.route({
@@ -3460,9 +3423,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),
@@ -3510,6 +3470,17 @@ 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 Busabase = class {
   /** The underlying fully-typed oRPC client. Use it for anything not surfaced here. */
@@ -3526,7 +3497,13 @@ 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;
@@ -3550,13 +3527,17 @@ var Busabase = class {
     return this.client.agent;
   }
   get assets() {
-    return this.client.assets;
-  }
-  get skills() {
-    return this.client.skills;
+    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);
+      }
+    });
   }
-  get drives() {
-    return this.client.drives;
+  /** Skills, Drives, and AirApps — one surface, discriminated by `type`. */
+  get fileTrees() {
+    return this.client.fileTrees;
   }
   get files() {
     return this.client.files;
@@ -3585,10 +3566,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);
@@ -3638,4 +3617,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 };