busa-sdk 0.17.2 → 0.17.3

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { B as BusabaseClient } from './client-DIlpYL9z.js';
+import { B as BusabaseClient } from './client-BgQn-yGL.js';
 import '@orpc/contract';
 import '@orpc/shared';
 import 'zod';

package/dist/{client-DIlpYL9z.d.ts → client-BgQn-yGL.d.ts}

@@ -11163,6 +11163,8 @@ declare const cloudContract: {
             version: z.ZodDefault<z.ZodNullable<z.ZodString>>;
             available: z.ZodDefault<z.ZodBoolean>;
             unavailableReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            connectionRequired: z.ZodDefault<z.ZodBoolean>;
+            connectedAgentName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>, _orpc_contract.MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
         sessions: {
             list: _orpc_contract.ContractProcedure<_orpc_contract.Schema<unknown, unknown>, z.ZodArray<z.ZodObject<{
@@ -11210,6 +11212,14 @@ declare const cloudContract: {
             prompt: _orpc_contract.ContractProcedure<z.ZodObject<{
                 sessionId: z.ZodString;
                 text: z.ZodString;
+                attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        image: "image";
+                        audio: "audio";
+                    }>;
+                    data: z.ZodString;
+                    mimeType: z.ZodString;
+                }, z.core.$strip>>>;
             }, z.core.$strip>, z.ZodObject<{
                 accepted: z.ZodBoolean;
                 sessionId: z.ZodString;
@@ -11761,11 +11771,11 @@ declare const cloudContract: {
                 comments: "comments";
                 bases: "bases";
                 assets: "assets";
+                attachments: "attachments";
                 nodePrincipals: "nodePrincipals";
                 views: "views";
                 fieldValues: "fieldValues";
                 recordLinks: "recordLinks";
-                attachments: "attachments";
                 assetUsages: "assetUsages";
                 assetTexts: "assetTexts";
                 commits: "commits";
@@ -11801,11 +11811,11 @@ declare const cloudContract: {
                 comments: "comments";
                 bases: "bases";
                 assets: "assets";
+                attachments: "attachments";
                 nodePrincipals: "nodePrincipals";
                 views: "views";
                 fieldValues: "fieldValues";
                 recordLinks: "recordLinks";
-                attachments: "attachments";
                 assetUsages: "assetUsages";
                 assetTexts: "assetTexts";
                 commits: "commits";
@@ -17772,6 +17782,19 @@ interface BusabaseConfig {
      * accepts that only when the token has a single unambiguous space.
      */
     spaceId?: string;
+    /**
+     * Origin the *web app* is served from, for building human-openable links (see
+     * {@link Busabase.nodeUrl}). Falls back to `BUSABASE_WEB_URL`, then to
+     * `baseUrl`.
+     *
+     * That fallback is why this field exists rather than being assumed: on Cloud
+     * and on a local OSS server the API and the dashboard happen to be
+     * same-origin, so `baseUrl` is right almost always — but "almost always" was
+     * silently baked into every caller that hand-built a link. Behind a gateway
+     * that mounts the API on its own host, or on a workspace subdomain, they
+     * diverge and only the caller knows.
+     */
+    webUrl?: string;
     /**
      * Extra headers merged into every request (after auth/space headers, so these
      * win on conflict). Static object or a (possibly async) factory.
@@ -17783,6 +17806,7 @@ interface BusabaseConfig {
 /** A {@link BusabaseConfig} with every field resolved from env / defaults. */
 interface ResolvedConfig {
     baseUrl: string;
+    webUrl: string;
     apiKey?: string;
     spaceId?: string;
     headers?: BusabaseConfig["headers"];

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import { z } from 'zod';
 import * as _orpc_client from '@orpc/client';
-import { N as NodeOutput, a as NodeType, O as OperationKind, B as BusabaseClient, R as ResolvedConfig, b as BusabaseConfig } from './client-DIlpYL9z.js';
-export { C as CREATABLE_NODE_TYPES, c as CloudContract, d as CreatableNodeType, D as DEFAULT_BASE_URL, e as cloudContract, f as createBusabaseClient, r as resolveConfig } from './client-DIlpYL9z.js';
+import { N as NodeOutput, a as NodeType, O as OperationKind, B as BusabaseClient, R as ResolvedConfig, b as BusabaseConfig } from './client-BgQn-yGL.js';
+export { C as CREATABLE_NODE_TYPES, c as CloudContract, d as CreatableNodeType, D as DEFAULT_BASE_URL, e as cloudContract, f as createBusabaseClient, r as resolveConfig } from './client-BgQn-yGL.js';
 import '@orpc/shared';
 
 /**
@@ -2909,6 +2909,60 @@ type BusabaseRecordsClient = BusabaseClient["records"] & {
  */
 declare const getRecordByField: (client: Pick<BusabaseClient, "records">, input: RecordByFieldInput) => Promise<RecordVO | null>;
 
+/**
+ * The canonical web URL a *human* opens for a node — the thing you paste into
+ * chat, an email, or a "copy link" button.
+ *
+ * This lives in the contract package on purpose. The formula used to exist in
+ * exactly one place: a React component (`node-share-button.tsx`), inside a
+ * `useMemo` that reads `window.location.origin`. That made it unreachable to
+ * every headless caller — the SDK, the CLI, and the server itself — so anyone
+ * who needed a link had to re-derive it and hope they matched. Both
+ * `busabase-core` (workspace dep) and `busabase-sdk` (bundled in by tsup's
+ * `noExternal`) can import from here, so there is one definition again.
+ *
+ * Note this is the *authenticated* dashboard URL. It is the right link for a
+ * reader who has a session, and the durable one (it never expires). It is NOT a
+ * no-login link: a node is only anonymously reachable at this URL once someone
+ * has enabled public sharing on it, and a Cloud embed link is a different URL
+ * shape entirely (`/embed/{id}?token=…`, minted per-node and short-lived).
+ */
+/** Where the web app is served from — the *browser* origin, not the API root. */
+interface NodeWebUrlInput {
+    /**
+     * Origin the dashboard is served from, e.g. `https://busabase.com` or
+     * `http://localhost:15419`. A trailing slash and a trailing `/api/v1` are both
+     * tolerated, because callers routinely have only an API base URL to hand and
+     * the two happen to be same-origin on Cloud and on a local OSS server.
+     */
+    webOrigin: string;
+    /**
+     * Space id segment. Pass `null` for a workspace-subdomain host, where the
+     * space is already implied by the hostname and the route drops the segment.
+     */
+    spaceId: string | null;
+    /** Node type segment: `base`, `doc`, `folder`, `file`, `drive`, `skill`, `airapp`, … */
+    nodeType: string;
+    /** Node slug (or id, for types addressed by id). */
+    nodeSlug: string;
+    /**
+     * Extra segments below the node, already in route order — e.g. a record id
+     * under a Base (`/base/<slug>/<recordId>`). Empty/blank entries are dropped.
+     */
+    extraSegments?: readonly string[];
+}
+/**
+ * Build the canonical dashboard URL for a node.
+ *
+ * Every caller-supplied segment is percent-encoded: a slug is user-controlled
+ * text, and an un-encoded `/` or `?` in one would silently retarget the link.
+ *
+ * @throws {TypeError} when `webOrigin` is not a parseable absolute URL, so a
+ * malformed config fails loudly at the call site instead of producing a link
+ * that looks fine and 404s.
+ */
+declare function nodeWebUrl({ webOrigin, spaceId, nodeType, nodeSlug, extraSegments, }: NodeWebUrlInput): string;
+
 type RawChangeRequestsClient = BusabaseClient["changeRequests"];
 type ReviewBatchInput = Parameters<RawChangeRequestsClient["review"]>[0];
 type MergeBatchInput = Parameters<RawChangeRequestsClient["merge"]>[0];
@@ -3007,6 +3061,32 @@ declare class Busabase {
     get agentTasks(): BusabaseClient["agentTasks"];
     get webhooks(): BusabaseClient["webhooks"];
     get embedLinks(): BusabaseClient["embedLinks"];
+    /**
+     * The canonical dashboard URL a human opens for a node — the link you hand
+     * back after a write.
+     *
+     * Uses `config.webUrl` (which defaults to `baseUrl`) and `config.spaceId`.
+     * Pass `spaceId: null` for a workspace-subdomain host, where the route drops
+     * the space segment.
+     *
+     * This is the *authenticated*, durable link: it never expires, but the reader
+     * needs a session unless the node has public sharing enabled. For a no-login
+     * link, mint a Cloud embed link instead —
+     * `bb.embedLinks.create({ nodeId })` returns `{ url, iframeUrl }`.
+     *
+     * @example
+     * ```ts
+     * const doc = await bb.docs.create({ ... });
+     * bb.nodeUrl({ nodeType: "doc", nodeSlug: doc.slug });
+     * // → https://busabase.com/dashboard/org_123/doc/q3-pricing
+     * ```
+     */
+    nodeUrl(input: {
+        nodeType: string;
+        nodeSlug: string;
+        spaceId?: string | null;
+        extraSegments?: readonly string[];
+    }): string;
     /** Full-text search across records, change requests, and Bases. */
     search(input: Parameters<BusabaseClient["search"]>[0]): _orpc_client.ClientPromiseResult<{
         query: string;
@@ -3122,4 +3202,4 @@ declare class Busabase {
     }>>>>;
 }
 
-export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeNodeVO as AirAppVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseAssetsClient, type BusabaseChangeRequestsClient, BusabaseClient, BusabaseConfig, type BusabaseRecordsClient, type ChangeRequestBatchFailureVO, type ChangeRequestCountsVO, type ChangeRequestMergeBatchResultVO, type ChangeRequestReviewBatchResultVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CommentSubjectType, type CommentVO, type CommitVO, type CreateFormDTO, type FileTreeFileVO as DriveFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeNodeVO as DriveVO, type FieldType, type FileNodeMetadata, type FileNodeVO, type FileTreeFileVO, type FileTreeNodeVO, type FileTreeReadFileVO, type FormBoundFieldVO, type FormFieldBindingVO, type FormPageSourceVO, type FormShareVO, type FormSubmitResultVO, type FormThemeVO, type FormVO, type GalleryCardSize, type GalleryCoverFit, type GanttScale, type ListFormsDTO, type ListFormsVO, type LookupRollup, type NodeDetailVO, type NodeSearchResultVO, NodeType, type NodeVO, OperationKind, type OperationStatus, type OperationVO, type RecordByFieldInput, type RecordLinkVO, type RecordVO, ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as SkillVO, type SubmitFormDTO, type UpdateFormDTO, type UpdateVaultSettingsDTO, type UserRefVO, VIEW_FIELD_MAX_WIDTH, VIEW_FIELD_MIN_WIDTH, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewType, type ViewVO, getRecordByField, grepAssets, normalizeBaseUrl, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };
+export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeNodeVO as AirAppVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseAssetsClient, type BusabaseChangeRequestsClient, BusabaseClient, BusabaseConfig, type BusabaseRecordsClient, type ChangeRequestBatchFailureVO, type ChangeRequestCountsVO, type ChangeRequestMergeBatchResultVO, type ChangeRequestReviewBatchResultVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CommentSubjectType, type CommentVO, type CommitVO, type CreateFormDTO, type FileTreeFileVO as DriveFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeNodeVO as DriveVO, type FieldType, type FileNodeMetadata, type FileNodeVO, type FileTreeFileVO, type FileTreeNodeVO, type FileTreeReadFileVO, type FormBoundFieldVO, type FormFieldBindingVO, type FormPageSourceVO, type FormShareVO, type FormSubmitResultVO, type FormThemeVO, type FormVO, type GalleryCardSize, type GalleryCoverFit, type GanttScale, type ListFormsDTO, type ListFormsVO, type LookupRollup, type NodeDetailVO, type NodeSearchResultVO, NodeType, type NodeVO, type NodeWebUrlInput, OperationKind, type OperationStatus, type OperationVO, type RecordByFieldInput, type RecordLinkVO, type RecordVO, ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as SkillVO, type SubmitFormDTO, type UpdateFormDTO, type UpdateVaultSettingsDTO, type UserRefVO, VIEW_FIELD_MAX_WIDTH, VIEW_FIELD_MIN_WIDTH, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewType, type ViewVO, getRecordByField, grepAssets, nodeWebUrl, normalizeBaseUrl, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };

package/dist/index.js

@@ -5,6 +5,27 @@ import { OpenAPILink } from '@orpc/openapi-client/fetch';
 import { oc, eventIterator } from '@orpc/contract';
 import { z } from 'zod';
 
+// ../../packages/busabase-contract/src/node-web-url.ts
+var normalizeOrigin = (raw) => raw.trim().replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+function nodeWebUrl({
+  webOrigin,
+  spaceId,
+  nodeType,
+  nodeSlug,
+  extraSegments = []
+}) {
+  const origin = normalizeOrigin(webOrigin);
+  const { origin: base } = new URL(origin);
+  const segments = [
+    "dashboard",
+    ...spaceId ? [spaceId] : [],
+    nodeType,
+    nodeSlug,
+    ...extraSegments
+  ].filter((segment) => segment != null && segment !== "");
+  return `${base}/${segments.map((segment) => encodeURIComponent(segment)).join("/")}`;
+}
+
 // src/asset-grep.ts
 var toUnifiedFilesGrepInput = (input) => ({
   pattern: input.pattern,
@@ -41,7 +62,9 @@ var AgentCatalogEntryVOSchema = z.object({
   /** Whether this entry can be launched right now (binary present / URL configured). */
   available: z.boolean().default(false),
   /** Human-readable reason when `available` is false — never a bare "failed". */
-  unavailableReason: z.string().nullable().default(null)
+  unavailableReason: z.string().nullable().default(null),
+  connectionRequired: z.boolean().default(false),
+  connectedAgentName: z.string().nullable().default(null)
 });
 var AgentSessionStatusSchema = z.enum([
   "connecting",
@@ -93,9 +116,19 @@ var CreateAgentSessionInputSchema = z.object({
   /** Must name a catalog entry. Deliberately NOT a command line — see below. */
   slug: z.string().min(1)
 });
+var PromptAttachmentInputSchema = z.object({
+  kind: z.enum(["image", "audio"]),
+  data: z.string().min(1),
+  mimeType: z.string().min(1)
+});
 var PromptAgentSessionInputSchema = z.object({
   sessionId: z.string().min(1),
-  text: z.string().min(1)
+  // No longer `.min(1)`: an attachment with no caption is a valid prompt.
+  // The refine below is what actually requires SOMETHING to send.
+  text: z.string(),
+  attachments: z.array(PromptAttachmentInputSchema).optional()
+}).refine((value) => value.text.trim().length > 0 || (value.attachments?.length ?? 0) > 0, {
+  message: "A prompt needs text, an attachment, or both."
 });
 var AgentSessionIdInputSchema = z.object({ sessionId: z.string().min(1) });
 var RespondToAgentPermissionInputSchema = z.object({
@@ -3415,7 +3448,7 @@ var busabaseContractRoutes = {
         path: "/nodes/{nodeId}/share",
         tags: ["Nodes", "Sharing"],
         summary: "Read a node's public link-sharing settings",
-        successDescription: "The node's public-share settings, or null when the node was never shared. The stored password is never returned \u2014 only a `hasPassword` flag."
+        successDescription: "The node's public-share settings, or null when the node was never shared. The stored password is never returned \u2014 only a `hasPassword` flag. No URL is returned: the shared node keeps its own canonical address, and only the caller knows which origin its reader should use (see `nodeWebUrl` in busabase-sdk)."
       }).input(z.object({ nodeId: z.string() })).output(nodeShareSchema.nullable()),
       set: oc.route({
         method: "POST",
@@ -3437,7 +3470,7 @@ var busabaseContractRoutes = {
         path: "/nodes/{nodeId}/share",
         tags: ["Nodes", "Sharing"],
         summary: "Revoke a node's public link sharing",
-        successDescription: "Flipped the share scope to none in place (the link is kept so re-enabling produces the same URL). Requires `manage` level on the node."
+        successDescription: "Flipped the share scope to none in place, keeping the row, so re-enabling reopens the node's same canonical address rather than minting a new one. Requires `manage` level on the node."
       }).input(z.object({ nodeId: z.string() })).output(nodeShareSchema.nullable())
     }
   },
@@ -3857,8 +3890,12 @@ var env = (key) => {
   return value && value.length > 0 ? value : void 0;
 };
 function resolveConfig(config = {}) {
+  const baseUrl = normalizeBaseUrl(config.baseUrl ?? env("BUSABASE_BASE_URL") ?? DEFAULT_BASE_URL);
   return {
-    baseUrl: normalizeBaseUrl(config.baseUrl ?? env("BUSABASE_BASE_URL") ?? DEFAULT_BASE_URL),
+    baseUrl,
+    // Same-origin is the overwhelmingly common case (Cloud, and a local OSS
+    // server), so default to it rather than forcing every caller to repeat it.
+    webUrl: normalizeBaseUrl(config.webUrl ?? env("BUSABASE_WEB_URL") ?? baseUrl),
     apiKey: config.apiKey ?? env("BUSABASE_API_KEY"),
     spaceId: config.spaceId ?? env("BUSABASE_SPACE_ID"),
     headers: config.headers,
@@ -4057,6 +4094,36 @@ var Busabase = class {
   get embedLinks() {
     return this.client.embedLinks;
   }
+  /**
+   * The canonical dashboard URL a human opens for a node — the link you hand
+   * back after a write.
+   *
+   * Uses `config.webUrl` (which defaults to `baseUrl`) and `config.spaceId`.
+   * Pass `spaceId: null` for a workspace-subdomain host, where the route drops
+   * the space segment.
+   *
+   * This is the *authenticated*, durable link: it never expires, but the reader
+   * needs a session unless the node has public sharing enabled. For a no-login
+   * link, mint a Cloud embed link instead —
+   * `bb.embedLinks.create({ nodeId })` returns `{ url, iframeUrl }`.
+   *
+   * @example
+   * ```ts
+   * const doc = await bb.docs.create({ ... });
+   * bb.nodeUrl({ nodeType: "doc", nodeSlug: doc.slug });
+   * // → https://busabase.com/dashboard/org_123/doc/q3-pricing
+   * ```
+   */
+  nodeUrl(input) {
+    const spaceId = input.spaceId === void 0 ? this.config.spaceId ?? null : input.spaceId;
+    return nodeWebUrl({
+      webOrigin: this.config.webUrl,
+      spaceId,
+      nodeType: input.nodeType,
+      nodeSlug: input.nodeSlug,
+      ...input.extraSegments ? { extraSegments: input.extraSegments } : {}
+    });
+  }
   /** Full-text search across records, change requests, and Bases. */
   search(input) {
     return this.client.search(input);
@@ -4117,4 +4184,4 @@ var Busabase = class {
   }
 };
 
-export { Busabase, CREATABLE_NODE_TYPES, DEFAULT_BASE_URL, cloudContract, createBusabaseClient, getRecordByField, grepAssets, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };
+export { Busabase, CREATABLE_NODE_TYPES, DEFAULT_BASE_URL, cloudContract, createBusabaseClient, getRecordByField, grepAssets, nodeWebUrl, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-sdk",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud). Short-name alias for busabase-sdk.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",