busabase-sdk 0.30.0 → 0.40.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as FileTreeReadFileVO, A as SearchResultKind, At as AttachmentRef, B as VaultRuntimeEnv, C as NodeSearchResultVO, Ct as VIEW_FIELD_MIN_WIDTH, D as ReviewVO, Dt as ViewSortVO, E as OperationVO, Et as ViewFilterVO, F as VaultAccessPolicy, Ft as CREATABLE_NODE_TYPES, G as AssetDetailVO, H as VaultSettingsVO, I as VaultEnvironment, It as CreatableNodeType, J as AssetVO, K as AssetTextStatus, L as VaultItemInput, Lt as NodeType, M as SourceAttributionVO, Mt as cloudContract, N as UserRefVO, Nt as NodeIcon, O as ReviewVerdict, Ot as ViewType, P as UpdateVaultSettingsDTO, Pt as NodeIconSchema, Q as FileTreeNodeVO, R as VaultItemKind, Rt as OperationKind, S as LookupRollup, St as VIEW_FIELD_MAX_WIDTH, T as OperationStatus, Tt as ViewFilterOperator, U as FileNodeMetadata, V as VaultScopeType, W as FileNodeVO, X as GrepResultVO, Y as GrepInputDTO, Z as FileTreeFileVO, _ as ChangeRequestVO, _t as GalleryCardSize, a as createBusabaseClient, at as FormPageSourceVO, b as CommitVO, bt as RecordLinkVO, c as AuditAction, ct as FormThemeVO, d as ChangeRequestBatchFailureVO, dt as ListFormsVO, et as NodeDetailVO, f as ChangeRequestCountsVO, ft as SubmitFormDTO, g as ChangeRequestTargetType, gt as BaseVO, h as ChangeRequestStatus, ht as BaseFieldVO, i as ResolvedConfig, it as FormFieldBindingVO, j as SearchResultVO, jt as CloudContract, k as SearchResponseVO, kt as ViewVO, l as AuditEventVO, lt as FormVO, m as ChangeRequestReviewBatchResultVO, mt as AssetAttachmentRef, n as BusabaseConfig, nt as CreateFormDTO, o as resolveConfig, ot as FormShareVO, p as ChangeRequestMergeBatchResultVO, pt as UpdateFormDTO, q as AssetUsageVO, r as DEFAULT_BASE_URL, rt as FormBoundFieldVO, s as AgentTaskVO, st as FormSubmitResultVO, t as BusabaseClient, tt as ActivityItemVO, u as BusabaseSourceChannel, ut as ListFormsDTO, v as CommentSubjectType, vt as GalleryCoverFit, w as NodeVO, wt as ViewConfigVO, x as FieldType, xt as RecordVO, y as CommentVO, yt as GanttScale, z as VaultItemVO } from "./client-CVz2pqrF.js";
+import { $ as FileTreeReadFileVO, A as SearchResultKind, At as AttachmentRef, B as VaultRuntimeEnv, C as NodeSearchResultVO, Ct as VIEW_FIELD_MIN_WIDTH, D as ReviewVO, Dt as ViewSortVO, E as OperationVO, Et as ViewFilterVO, F as VaultAccessPolicy, Ft as CREATABLE_NODE_TYPES, G as AssetDetailVO, H as VaultSettingsVO, I as VaultEnvironment, It as CreatableNodeType, J as AssetVO, K as AssetTextStatus, L as VaultItemInput, Lt as NodeType, M as SourceAttributionVO, Mt as cloudContract, N as UserRefVO, Nt as NodeIcon, O as ReviewVerdict, Ot as ViewType, P as UpdateVaultSettingsDTO, Pt as NodeIconSchema, Q as FileTreeNodeVO, R as VaultItemKind, Rt as OperationKind, S as LookupRollup, St as VIEW_FIELD_MAX_WIDTH, T as OperationStatus, Tt as ViewFilterOperator, U as FileNodeMetadata, V as VaultScopeType, W as FileNodeVO, X as GrepResultVO, Y as GrepInputDTO, Z as FileTreeFileVO, _ as ChangeRequestVO, _t as GalleryCardSize, a as createBusabaseClient, at as FormPageSourceVO, b as CommitVO, bt as RecordLinkVO, c as AuditAction, ct as FormThemeVO, d as ChangeRequestBatchFailureVO, dt as ListFormsVO, et as NodeDetailVO, f as ChangeRequestCountsVO, ft as SubmitFormDTO, g as ChangeRequestTargetType, gt as BaseVO, h as ChangeRequestStatus, ht as BaseFieldVO, i as ResolvedConfig, it as FormFieldBindingVO, j as SearchResultVO, jt as CloudContract, k as SearchResponseVO, kt as ViewVO, l as AuditEventVO, lt as FormVO, m as ChangeRequestReviewBatchResultVO, mt as AssetAttachmentRef, n as BusabaseConfig, nt as CreateFormDTO, o as resolveConfig, ot as FormShareVO, p as ChangeRequestMergeBatchResultVO, pt as UpdateFormDTO, q as AssetUsageVO, r as DEFAULT_BASE_URL, rt as FormBoundFieldVO, s as AgentTaskVO, st as FormSubmitResultVO, t as BusabaseClient, tt as ActivityItemVO, u as BusabaseSourceChannel, ut as ListFormsDTO, v as CommentSubjectType, vt as GalleryCoverFit, w as NodeVO, wt as ViewConfigVO, x as FieldType, xt as RecordVO, y as CommentVO, yt as GanttScale, z as VaultItemVO } from "./client-CWlHll4H.js";
 import { z } from "zod";
 //#region src/url.d.ts
 /**

package/dist/index.js

@@ -354,7 +354,7 @@ const LocaleSchema = z.enum({
 * - ZH: isIString 接受 JSON 字符串并尝试解析为按语言分布的对象；纯字符串将返回 false。
 */
 const iStringRecordSchema = z.partialRecord(LocaleSchema, z.string());
-z.union([z.string(), iStringRecordSchema]).describe("i18n string");
+const iStringSchema = z.union([z.string(), iStringRecordSchema]).describe("i18n string");
 //#endregion
 //#region ../../packages/busabase-contract/src/contract/auto-merge.ts
 /**
@@ -500,7 +500,8 @@ const baseSchema = z.object({
 		requiredApprovals: z.number()
 	}),
 	createdAt: z.string(),
-	fields: z.array(baseFieldSchema)
+	fields: z.array(baseFieldSchema),
+	metadata: z.record(z.string(), z.unknown()).default({})
 });
 const createBaseInputSchema = z.object({
 	parentNodeId: z.string().optional().describe("Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."),
@@ -1081,6 +1082,81 @@ const NodeIconSchema = z.discriminatedUnion("type", [z.object({
 	}).optional()
 })]);
 //#endregion
+//#region ../../packages/busabase-contract/src/contract/node-agent-prompt-schemas.ts
+/**
+* Per-node custom scenario prompts (`node.metadata.agentPrompts`) — the single
+* schema shared by BOTH write and read paths, per
+* `apps/busabase-cloud/content/spec/node-agent-prompts-v2.md` §7.3:
+*
+* - Write: `busabase-cli nodes set-agent-prompts` validates a file against this
+*   schema client-side, before calling `nodes.updateMetadata` — a malformed file
+*   never reaches the network.
+* - Read: `buildNodeAgentPrompts` (`packages/busabase-core/.../node-agent-prompts.ts`)
+*   `.safeParse`s whatever is stored in `metadata.agentPrompts` and falls back to
+*   the node type's default scenarios on failure, so a bad write (or a manual
+*   jsonb edit) can never crash the Agent Prompts dialog.
+*
+* One schema, one place to edit the limits — do not duplicate this validation on
+* either side.
+*/
+/** Recommended limits from the spec (§7.3) — kept as named constants so a limit
+* change has exactly one place to edit, and so error messages can cite them. */
+const CUSTOM_AGENT_PROMPT_LIMITS = {
+	/** Max custom prompts per node. */
+	maxPrompts: 50,
+	/** Max characters per localized `label` value. */
+	maxLabelChars: 80,
+	/** Max bytes (UTF-8) per localized `body` value. */
+	maxBodyBytes: 8192
+};
+/** Same intent vocabulary `PromptDef.intent` uses — `change` is the router-side
+* default when omitted, matching the existing curated-prompt behavior. */
+const customPromptIntentSchema = z.enum(["read-only", "change"]);
+const iStringLocaleValues = (value) => typeof value === "string" ? [value] : Object.values(value);
+/** UTF-8 byte length — `body` includes CJK/JA text, whose per-character byte
+* cost is not 1, so a character-count limit alone would under-enforce §7.3's
+* "8 KiB per localized body" budget. */
+const utf8ByteLength = (value) => new TextEncoder().encode(value).length;
+const customPromptLabelSchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => v.length <= CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars), { message: `label must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars} characters per locale` });
+const customPromptBodySchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => utf8ByteLength(v) <= CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes), { message: `body must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes} bytes (UTF-8) per locale` });
+/**
+* One custom scenario prompt. `body`'s `{target}` placeholder is substituted at
+* render time with the same target string `PromptDef.body(target)` receives
+* today (see `node-agent-prompts.ts`) — this schema does not interpolate it.
+*/
+const customPromptDefSchema = z.object({
+	/** Stable id, unique within this node's custom list. */
+	key: z.string().trim().min(1, { message: "key must not be empty" }),
+	/** Defaults to `change` (same default the curated prompts use) so a prompt
+	* cannot silently bypass the approval-first policy by omission. */
+	intent: customPromptIntentSchema.optional(),
+	/** Short title shown in the dialog's left list. */
+	label: customPromptLabelSchema,
+	/** Template text; "{target}" is substituted with the rendered target line. */
+	body: customPromptBodySchema
+});
+/**
+* The full `metadata.agentPrompts` array. `.max` bounds the list; the
+* `superRefine` catches duplicate keys with an issue path pointing at the
+* offending entry, so a CLI/server validation error names which entry and
+* which key collided instead of a bare "keys must be unique".
+*/
+const customAgentPromptsSchema = z.array(customPromptDefSchema).max(CUSTOM_AGENT_PROMPT_LIMITS.maxPrompts, { message: `at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxPrompts} custom prompts per node` }).superRefine((prompts, ctx) => {
+	const firstIndexByKey = /* @__PURE__ */ new Map();
+	prompts.forEach((prompt, index) => {
+		const firstIndex = firstIndexByKey.get(prompt.key);
+		if (firstIndex === void 0) {
+			firstIndexByKey.set(prompt.key, index);
+			return;
+		}
+		ctx.addIssue({
+			code: "custom",
+			path: [index, "key"],
+			message: `duplicate key "${prompt.key}" — already used at entry ${firstIndex + 1}`
+		});
+	});
+});
+//#endregion
 //#region ../../packages/busabase-contract/src/contract/schemas.ts
 const nodeSchema = z.lazy(() => z.object({
 	id: z.string(),
@@ -1090,6 +1166,7 @@ const nodeSchema = z.lazy(() => z.object({
 	name: z.string(),
 	description: z.string(),
 	metadata: z.object({ version: z.string().optional() }).catchall(z.unknown()).default({}),
+	settings: nodeSettingsSchema.default({}),
 	explicitVisibility: z.enum([
 		"private",
 		"workspace",
@@ -1173,6 +1250,65 @@ const updateNodeMetadataInputSchema = z.object({
 	nodeId: z.string(),
 	metadata: z.record(z.string(), z.unknown())
 });
+/**
+* System settings Busabase itself acts on, per node.
+*
+* A CLOSED object, unlike `metadata`'s `z.record(z.string(), z.unknown())`.
+* That difference is the point: `metadata` is the open bag callers put their
+* own keys in, and its endpoint merges whatever it is handed. Anything the
+* product *reads and acts on* must not live there — `metadata.visibility` had
+* to be pulled out into its own column precisely because the generic endpoint
+* handed a `write`-level actor a door into an ACL input.
+*
+* Adding a key here is a deliberate change to this schema, which is what keeps
+* `PATCH /nodes/{nodeId}/settings` from becoming a second free-form bag.
+*
+* `strictObject`, not `object`: zod's default is to STRIP an unknown key, which
+* would hand a client that misspelled `airappEngine` a 200 and no effect —
+* exactly the silent failure a closed schema exists to prevent. Verified
+* against a running server, where the permissive version returned 200.
+*/
+const nodeSettingsSchema = z.strictObject({ 
+/**
+* Which engine an AirApp runs on, when a human has chosen.
+*
+* `undefined` means "follow the app" — `airapp.json`'s `preferredEngine`
+* decides, or the default does. A value means somebody overrode it in the
+* node settings dialog, and it outranks the manifest from then on. So absence
+* must stay distinguishable from any particular value; `null` clears an
+* override and returns the node to following the app.
+*/
+airappEngine: z.enum([
+	"browser",
+	"local",
+	"remote"
+]).nullish() });
+const updateNodeSettingsInputSchema = z.object({
+	nodeId: z.string(),
+	settings: nodeSettingsSchema
+});
+/**
+* This node's custom scenario prompts.
+*
+* A separate read from `nodes.get`/`nodes.list` on purpose: the list is capped
+* at 50 prompts x 8 KiB of body per locale, so carrying it on every node of
+* every sidebar load is exactly what its own column exists to avoid. The dialog
+* asks for it when it opens.
+*
+* `agentPrompts: null` means "this node has never set any" — distinct from `[]`,
+* which means "set, and deliberately empty". Both fall back to the node type's
+* default scenarios in the UI, but only the first is a node nobody has touched.
+*/
+const getNodeAgentPromptsInputSchema = z.object({ nodeId: z.string() });
+const nodeAgentPromptsSchema = z.object({
+	nodeId: z.string(),
+	agentPrompts: customAgentPromptsSchema.nullable()
+});
+const updateNodeAgentPromptsInputSchema = z.object({
+	nodeId: z.string(),
+	/** Replaces the whole list — this is not a merge. Send `null` to clear. */
+	agentPrompts: customAgentPromptsSchema.nullable()
+});
 const searchNodesByNameInputSchema = z.object({
 	query: z.string().min(1),
 	limit: z.coerce.number().int().min(1).max(50).optional().default(20)
@@ -1368,7 +1504,8 @@ const liveEventSchema = z.object({
 		"change_request.reviewed",
 		"change_request.merged",
 		"change_request.pending_review",
-		"node.metadata_updated"
+		"node.metadata_updated",
+		"node.settings_updated"
 	]),
 	spaceId: z.string(),
 	actorId: z.string(),
@@ -1399,6 +1536,8 @@ const auditActionSchema = z.enum([
 	"asset.text_written",
 	"asset.text_marked_none",
 	"node.metadata_updated",
+	"node.settings_updated",
+	"node.agent_prompts_updated",
 	"node.purged"
 ]);
 const auditEventSchema = z.object({
@@ -1814,16 +1953,17 @@ const airAppRunLocalInputSchema = z.object({
 	*  The in-browser Nodepod engine never uses this field: it hands raw bytes to
 	*  `Nodepod.boot({ files })` directly and skips the base64 round trip. */
 	binaryFiles: z.record(z.string(), z.string()).optional().default({}),
-	/** Server-side execution mode. `"local"` spawns a bare host Node.js
-	*  process (previewable, data bridge via reverse proxy, NOT OS-isolated);
-	*  `"srt"` wraps the same commands in the OS sandbox (isolated execution,
-	*  but live preview is unreachable). `"nodepod"` never calls this endpoint —
-	*  it runs entirely in-browser. */
-	engine: z.enum([
-		"local",
-		"srt",
-		"sandock"
-	]).default("local")
+	/** Where the server should run it. `"local"` spawns a bare process on the
+	*  Busabase host (previewable, data bridge via reverse proxy, NOT isolated);
+	*  `"remote"` runs the same lifecycle on a provisioned machine elsewhere.
+	*  `"browser"` never reaches this endpoint — it runs entirely in the tab.
+	*
+	*  Required, deliberately. This used to default to `"local"`, so a call that
+	*  simply omitted the field asked the server to spawn a host process — the
+	*  most privileged of the two options, reached by saying nothing. Naming the
+	*  engine is now the caller's job, and the handler independently refuses one
+	*  this deployment does not offer. */
+	engine: z.enum(["local", "remote"])
 });
 const airAppRuntimeEventSchema = z.discriminatedUnion("type", [
 	z.object({
@@ -2414,6 +2554,41 @@ const listRecordsResponseSchema = z.object({
 const listRecordsPageInputSchema = z.object({
 	baseId: z.string().min(1),
 	viewId: z.string().min(1).optional(),
+	/**
+	* Extra conditions ANDed with the View's own filters — "this View, further
+	* narrowed". The motivating case is one board column: the saved View's
+	* filters plus `stackField equals <choice>`, paged independently of the
+	* other columns.
+	*
+	* Unlike `records.list`'s `filters` (a SUPERSET push-down the client then
+	* narrows), these are applied with the same authority as a saved View's:
+	* every returned page is exactly what the client's own matcher would keep.
+	* That distinction is the whole point — a *superset* page can be missing
+	* records, and a board column that silently drops cards reads as data loss.
+	*/
+	filters: z.array(listRecordsFilterSchema).optional(),
+	/**
+	* Scope the page to records whose `date`/`created_time`/`updated_time` field
+	* falls in `[gte, lt)` — an absolute UTC instant range, not a `filters`
+	* condition. It is deliberately NOT an operator on `listRecordsFilterSchema`:
+	* that model mirrors the client's label-based view-filter matching (see
+	* `recordMatchesViewFilter`), which for a date renders via
+	* `toLocaleDateString()` — meaningless without knowing the viewer's
+	* timezone, which the server never has. A UTC instant range has no such
+	* ambiguity, so it is resolved once here, by the caller (who DOES know the
+	* viewer's timezone), and applied as a real timestamp comparison.
+	*
+	* The motivating case is a Calendar month grid: the client computes the UTC
+	* bounds of its own local 42-day grid and asks for only that slice, instead
+	* of every record in the Base.
+	*/
+	dateRange: z.object({
+		fieldSlug: z.string().min(1),
+		/** Inclusive lower bound, ISO 8601 UTC instant. */
+		gte: z.string(),
+		/** Exclusive upper bound, ISO 8601 UTC instant. */
+		lt: z.string()
+	}).optional(),
 	page: z.coerce.number().int().min(1).optional().default(1),
 	pageSize: z.coerce.number().int().min(1).max(100).optional().default(50)
 });
@@ -2458,6 +2633,42 @@ const countRecordsInputSchema = z.object({
 const countRecordsResponseSchema = z.object({ 
 /** Total active records in the space (optionally scoped to a base). */
 total: z.number().int().nonnegative() });
+const groupRecordsInputSchema = z.object({
+	/** Group within exactly one Base — a field slug is only unambiguous there. */
+	baseId: z.string().min(1),
+	/**
+	* The field to group by. Restricted to `select` and `checkbox`: their stored
+	* value IS the grouping key (a choice id / a boolean), so a SQL GROUP BY
+	* returns exactly the buckets a client would build. Text/number keys would
+	* be truncated at the projection limit, and date keys would bucket by the
+	* server's timezone rather than the viewer's — both would report a
+	* confidently wrong split, so they're rejected instead of approximated.
+	*/
+	fieldSlug: z.string().min(1),
+	/** Group only the rows a saved View would display (its filters; sort ignored). */
+	viewId: z.string().min(1).optional(),
+	/** Ad-hoc filters, ANDed with the View's own when both are given. */
+	filters: z.array(listRecordsFilterSchema).optional()
+});
+const groupRecordsResponseSchema = z.object({
+	groups: z.array(z.object({
+		/**
+		* The raw stored key: a `select` choice id, or `"true"`/`"false"` for a
+		* checkbox. For a select, `null` is the bucket of records with no value
+		* (what a Kanban board shows as its "Uncategorized" column). A checkbox
+		* never reports `null` — an unset checkbox counts as `"false"`, matching
+		* how view filters already treat it (`is_false` covers null/undefined).
+		*
+		* Choice LABELS are deliberately not resolved here — the client already
+		* holds the Base's field definitions and renders labels itself, and
+		* returning ids keeps this response stable across a choice rename.
+		*/
+		value: z.string().nullable(),
+		count: z.number().int().nonnegative()
+	})),
+	/** Sum of every group's count — the same number `records.count` would return. */
+	total: z.number().int().nonnegative()
+});
 const createChangeRequestInputSchema = z.object({
 	fields: z.record(z.string(), z.unknown()).describe("Record field values keyed by field slug. The base's PRIMARY field (its first field) becomes the record's display name and the change request title everywhere — always give it a short, human-readable value, never an id or placeholder."),
 	message: z.string().optional().default("Initial change request").describe("Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. \"Add Acme Corp — qualified lead from the June webinar\"."),
@@ -2657,7 +2868,7 @@ const recordContract = {
 		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."
+		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. `dateRange` additionally scopes to a `[gte, lt)` UTC instant window on a date/created_time/updated_time field."
 	}).input(listRecordsPageInputSchema).output(listRecordsPageResponseSchema),
 	count: oc.route({
 		method: "GET",
@@ -2667,6 +2878,23 @@ const recordContract = {
 		description: "A real SQL COUNT — 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 — 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),
+	groupBy: oc.route({
+		method: "GET",
+		path: "/records/group-by",
+		tags: ["Records"],
+		summary: "Count records per group",
+		description: "One SQL GROUP BY returning every bucket's exact count — the split a board column header or a summary tile needs, without reading the records themselves. `fieldSlug` must name a `select` or `checkbox` field: their stored value IS the grouping key, so the buckets are exactly the ones a client would build. Grouping by a text, number or date field is rejected rather than approximated (text keys are truncated at the projection limit; date keys would bucket by the server's timezone, not the viewer's). `viewId` and `filters` narrow the set first, with the same exactness rules as `records.count`: provably-exact conditions stay a cheap SQL aggregate, anything else falls back to evaluating every matching row server-side — exact, but not free on a large Base. Groups come back keyed by raw choice id (or `\"true\"`/`\"false\"`), with `null` for records that have no value; labels are the client's to render.",
+		successDescription: "Every group's exact count, plus the total across all groups. Groups with zero records are omitted — a Base's full choice list lives in its field definition, so the client already knows which buckets to render empty."
+	}).errors({
+		BAD_REQUEST: {
+			status: 400,
+			message: "Field is not groupable"
+		},
+		NOT_FOUND: {
+			status: 404,
+			message: "Base or field not found"
+		}
+	}).input(groupRecordsInputSchema).output(groupRecordsResponseSchema),
 	get: oc.route({
 		method: "GET",
 		path: "/records/get",
@@ -2840,19 +3068,55 @@ const ExportAssetTextVOSchema = z.object({
 	textContentHash: z.string().nullable(),
 	byteCount: z.number().int().nonnegative()
 });
-const ImportBeginInputSchema = z.object({ 
+const ExportDocBodiesInputSchema = z.object({ nodeIds: z.array(z.string()).min(1).max(25) });
+const ExportDocBodiesVOSchema = z.object({ 
 /**
-* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
-* in the `.bbdump`, already integrity-verified before this is called).
-* `importTableRows`'s "nodes" handling needs this to recognize the
-* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
-* scanning each batch's rows for "the one with a null `parentId`" only
-* works when that row happens to land in the SAME batch as its children,
-* which cursor pagination (id-ordered, not tree-ordered) does not
-* guarantee once a space has more nodes than one page. See the matching
-* comment in `import-logic.ts`.
+* One entry per requested node that is a Doc in this space. A node id that
+* does not resolve is simply absent (not an error): the caller asked for a
+* batch, and one bad id must not cost it the other 24. A Doc that exists but
+* has no body object yet yields `markdown: ""`, matching what a read through
+* the Doc domain would return.
 */
-sourceSpaceId: z.string() });
+bodies: z.array(z.object({
+	nodeId: z.string(),
+	markdown: z.string()
+})) });
+const ImportBeginInputSchema = z.object({
+	/**
+	* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
+	* in the `.bbdump`, already integrity-verified before this is called).
+	* `importTableRows`'s "nodes" handling needs this to recognize the
+	* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
+	* scanning each batch's rows for "the one with a null `parentId`" only
+	* works when that row happens to land in the SAME batch as its children,
+	* which cursor pagination (id-ordered, not tree-ordered) does not
+	* guarantee once a space has more nodes than one page. See the matching
+	* comment in `import-logic.ts`.
+	*/
+	sourceSpaceId: z.string(),
+	/**
+	* Continue a restore that was interrupted partway through, instead of
+	* requiring an empty space.
+	*
+	* A restore that FAILS rolls itself back (`importAbort`), so the target is
+	* left clean and a plain re-run works. What cannot roll itself back is a
+	* restore whose process died — Ctrl-C, OOM, a dropped connection, the
+	* machine rebooting. That leaves the space holding however many of the
+	* archive's rows had landed, and every subsequent attempt is refused
+	* ("requires an empty target space") with no way forward except wiping it.
+	*
+	* In this mode the empty-space guard is skipped and inserts become
+	* `ON CONFLICT DO NOTHING`, so replaying the same archive re-lands only what
+	* is missing. Blobs and doc bodies are content-addressed writes to object
+	* storage and were already idempotent.
+	*
+	* DANGEROUS if pointed at the wrong space: rows that collide are silently
+	* skipped rather than reported, so restoring archive A into a space holding
+	* archive B's data would interleave the two instead of refusing. Only pass
+	* it to continue the SAME archive into the SAME space.
+	*/
+	resume: z.boolean().optional().default(false)
+});
 const ImportBeginVOSchema = z.object({ sessionId: z.string() });
 /**
 * `docBodies`, `attachmentBlobs` and `assetTextBlobs` are pseudo-tables: doc
@@ -2910,6 +3174,13 @@ const dumpContract = {
 		summary: "Resolve the download URL for one asset's extracted-text object",
 		successDescription: "A resolved download URL for the asset's DERIVED text blob (`asset-texts/blobs/sha256/…`) plus its `textStorageKey` and `textContentHash`, so a backup can archive the exact bytes and verify them. `downloadUrl` is null when the row owns no separate object (auto-registered text-kind rows point at their attachment's own key, already covered by the attachment blobs; `status: \"none\"` rows have no text at all)."
 	}).input(ExportAssetTextInputSchema).output(ExportAssetTextVOSchema),
+	exportDocBodies: oc.route({
+		method: "POST",
+		path: "/dump/export/doc-bodies",
+		tags: ["Dump"],
+		summary: "Read the raw markdown for a batch of Doc nodes",
+		successDescription: "The raw body behind each requested Doc, read straight from object storage — archived Docs included, which the ordinary `nodes.get` deliberately refuses. Ids that do not resolve to a Doc in this space are omitted rather than failing the batch."
+	}).input(ExportDocBodiesInputSchema).output(ExportDocBodiesVOSchema),
 	importBegin: oc.route({
 		method: "POST",
 		path: "/dump/import/begin",
@@ -4462,6 +4733,27 @@ const busabaseContractRoutes = {
 			summary: "Update node metadata",
 			successDescription: "Shallow-merged the supplied top-level keys into the active node's existing metadata. Requires write access on the node. Node CONTENT (a Doc body, or a whiteboard/workflow/html document) does not go through here — use PUT /nodes/{nodeId}/content instead."
 		}).input(updateNodeMetadataInputSchema).output(nodeSchema),
+		updateSettings: oc.route({
+			method: "PATCH",
+			path: "/nodes/{nodeId}/settings",
+			tags: ["Nodes"],
+			summary: "Update node system settings",
+			successDescription: "Replaced the node's system settings. Unlike metadata this is a closed set of keys Busabase itself acts on, so an unknown key is rejected rather than stored. Send a key as null to clear it — for an AirApp's engine that returns the node to following its airapp.json. Requires write access on the node."
+		}).input(updateNodeSettingsInputSchema).output(nodeSchema),
+		getAgentPrompts: oc.route({
+			method: "GET",
+			path: "/nodes/{nodeId}/agent-prompts",
+			tags: ["Nodes"],
+			summary: "Get node custom agent prompts",
+			successDescription: "This node's custom scenario prompts, which replace the node type's default prompts in the Ask-agent dialog. `null` means the node has never had any set, which is not the same as an empty list. Read separately from the node itself because the list is large enough (50 prompts x 8 KiB per locale) that carrying it on every node listing would be its own problem. Requires read access on the node."
+		}).input(getNodeAgentPromptsInputSchema).output(nodeAgentPromptsSchema),
+		updateAgentPrompts: oc.route({
+			method: "PUT",
+			path: "/nodes/{nodeId}/agent-prompts",
+			tags: ["Nodes"],
+			summary: "Replace node custom agent prompts",
+			successDescription: "Replaced this node's custom scenario prompts — the whole list, not a merge. Send `null` to clear them and return the node to its type's default prompts. Requires write access on the node."
+		}).input(updateNodeAgentPromptsInputSchema).output(nodeAgentPromptsSchema),
 		updateContent: oc.route({
 			method: "PUT",
 			path: "/nodes/{nodeId}/content",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.30.0",
+  "version": "0.40.0",
   "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",
@@ -67,9 +67,9 @@
     "tsx": "^4.20.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "busabase-contract": "0.30.0",
-    "open-domains": "0.0.2",
-    "openlib": "0.1.1"
+    "busabase-contract": "0.40.0",
+    "openlib": "0.1.1",
+    "open-domains": "0.0.2"
   },
   "engines": {
     "node": ">=24.18.0"