@narrative.io/data-collaboration-sdk-ts 2.101.1-beta.0 → 2.103.0

package/build/agents/index.d.ts

@@ -0,0 +1,70 @@
+import { BaseApi } from "../base-api";
+import type { ApiRecordsV2, PaginationOptions } from "../types";
+import type { ConversationId, ConversationResponse, CreateConversationRequest, CreateRunRequest, ListMessagesResponse, RunId, RunResponse } from "./types";
+export * from "./types";
+/**
+ * @module AgentsApi
+ * @description Agent Conversations: long-lived conversations with pinned system
+ *   prompt + defaults, asynchronous runs that may pause for caller-declared
+ *   tool outputs, and a versioned delta-cursor message stream.
+ *
+ * @see https://docs.narrative.io/reference/architecture/agent-conversations
+ *
+ * @extends BaseApi
+ */
+export declare class AgentsApi extends BaseApi {
+    /**
+     * Create an agent conversation. `system_prompt` and `defaults.{tools,mcp_servers}`
+     * are pinned at creation; everything else in `defaults` is overridable per-run.
+     */
+    createAgentConversation(request: CreateConversationRequest): Promise<ConversationResponse>;
+    /**
+     * List the calling user's agent conversations, newest first by `created_at`.
+     * Scoped to both `company_id` and `user_id` from the bearer token — peers in
+     * the same company are not visible. Never 404s; empty state is `records: []`.
+     */
+    listAgentConversations(options?: PaginationOptions): Promise<ApiRecordsV2<ConversationResponse>>;
+    /**
+     * Read a conversation's metadata + current `version`. Always re-read this
+     * immediately before starting a run — `version` is the compare-and-swap
+     * token for `expected_version` and a stale value yields 409.
+     */
+    getAgentConversation(conversationId: ConversationId): Promise<ConversationResponse>;
+    /**
+     * Delta-read conversation messages with `sequence_no > since`. Use the
+     * returned `current_version` as the next call's `since` for gap-free reads.
+     */
+    listAgentConversationMessages(conversationId: ConversationId, options?: {
+        since?: number;
+    }): Promise<ListMessagesResponse>;
+    /**
+     * Start a new run on the conversation. Returns immediately with
+     * `status: "pending"` — poll {@link getAgentRun} until terminal.
+     *
+     * - Generate a fresh UUID for `client_op_id` per logical request (it's the
+     *   idempotency key; reusing one is only safe as a retry).
+     * - Set `expected_version` to the value just read from
+     *   {@link getAgentConversation} — mismatches return 409.
+     */
+    createAgentRun(conversationId: ConversationId, request: CreateRunRequest): Promise<RunResponse>;
+    /**
+     * Read a run's current state. Terminal states: `completed`,
+     * `requires_action`, `failed`. Stop polling on any of them.
+     */
+    getAgentRun(runId: RunId): Promise<RunResponse>;
+    /**
+     * Convenience: poll {@link getAgentRun} until terminal. Caller is responsible
+     * for selecting a reasonable backoff; defaults to 1.5s fixed interval with a
+     * 2-minute ceiling.
+     *
+     * Returns the terminal run. Throws on `failed` only if `throwOnFailed` is
+     * true; otherwise the caller inspects `run.status === "failed"`.
+     */
+    waitForAgentRun(runId: RunId, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        onTick?: (run: RunResponse) => void;
+        throwOnFailed?: boolean;
+    }): Promise<RunResponse>;
+}

package/build/agents/index.js

@@ -0,0 +1,100 @@
+import { BaseApi } from "../base-api";
+export * from "./types";
+const conversationsResource = "agents/conversations";
+const runsResource = "agents/runs";
+/**
+ * @module AgentsApi
+ * @description Agent Conversations: long-lived conversations with pinned system
+ *   prompt + defaults, asynchronous runs that may pause for caller-declared
+ *   tool outputs, and a versioned delta-cursor message stream.
+ *
+ * @see https://docs.narrative.io/reference/architecture/agent-conversations
+ *
+ * @extends BaseApi
+ */
+export class AgentsApi extends BaseApi {
+    // -------------------- Conversations --------------------
+    /**
+     * Create an agent conversation. `system_prompt` and `defaults.{tools,mcp_servers}`
+     * are pinned at creation; everything else in `defaults` is overridable per-run.
+     */
+    async createAgentConversation(request) {
+        return await this.post(conversationsResource, request);
+    }
+    /**
+     * List the calling user's agent conversations, newest first by `created_at`.
+     * Scoped to both `company_id` and `user_id` from the bearer token — peers in
+     * the same company are not visible. Never 404s; empty state is `records: []`.
+     */
+    async listAgentConversations(options) {
+        return await this.get(conversationsResource, options ? { ...options } : undefined);
+    }
+    /**
+     * Read a conversation's metadata + current `version`. Always re-read this
+     * immediately before starting a run — `version` is the compare-and-swap
+     * token for `expected_version` and a stale value yields 409.
+     */
+    async getAgentConversation(conversationId) {
+        return await this.get(`${conversationsResource}/${conversationId}`);
+    }
+    /**
+     * Delta-read conversation messages with `sequence_no > since`. Use the
+     * returned `current_version` as the next call's `since` for gap-free reads.
+     */
+    async listAgentConversationMessages(conversationId, options) {
+        return await this.get(`${conversationsResource}/${conversationId}/messages`, options?.since !== undefined ? { since: options.since } : undefined);
+    }
+    // -------------------- Runs --------------------
+    /**
+     * Start a new run on the conversation. Returns immediately with
+     * `status: "pending"` — poll {@link getAgentRun} until terminal.
+     *
+     * - Generate a fresh UUID for `client_op_id` per logical request (it's the
+     *   idempotency key; reusing one is only safe as a retry).
+     * - Set `expected_version` to the value just read from
+     *   {@link getAgentConversation} — mismatches return 409.
+     */
+    async createAgentRun(conversationId, request) {
+        return await this.post(`${conversationsResource}/${conversationId}/runs`, request);
+    }
+    /**
+     * Read a run's current state. Terminal states: `completed`,
+     * `requires_action`, `failed`. Stop polling on any of them.
+     */
+    async getAgentRun(runId) {
+        return await this.get(`${runsResource}/${runId}`);
+    }
+    /**
+     * Convenience: poll {@link getAgentRun} until terminal. Caller is responsible
+     * for selecting a reasonable backoff; defaults to 1.5s fixed interval with a
+     * 2-minute ceiling.
+     *
+     * Returns the terminal run. Throws on `failed` only if `throwOnFailed` is
+     * true; otherwise the caller inspects `run.status === "failed"`.
+     */
+    async waitForAgentRun(runId, options = {}) {
+        const interval = options.intervalMs ?? 1500;
+        const timeout = options.timeoutMs ?? 120_000;
+        const deadline = Date.now() + timeout;
+        // terminal predicate kept local to avoid an extra import in consumers
+        const terminal = (s) => s === "completed" || s === "requires_action" || s === "failed";
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            if (options.signal?.aborted) {
+                throw new Error("waitForAgentRun aborted");
+            }
+            const run = await this.getAgentRun(runId);
+            options.onTick?.(run);
+            if (terminal(run.status)) {
+                if (options.throwOnFailed && run.status === "failed") {
+                    throw Object.assign(new Error(run.error?.message ?? "Agent run failed"), { run });
+                }
+                return run;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`waitForAgentRun timed out after ${timeout}ms`);
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+    }
+}

package/build/agents/types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Agent Conversations API — types.
+ *
+ * Mirrors `/agents/conversations` and `/agents/runs` on the Narrative Data
+ * Collaboration Platform (RFC 7807 errors; OpenAI-Assistants-shaped semantics).
+ *
+ * Two tool dimensions:
+ *  - `mcp_servers[]` — server-side, resolved by the platform via MCP. Model sees
+ *    each tool as `{alias}-{name}`.
+ *  - `tools[]` — caller-declared. Dash-free names. When called, the run pauses
+ *    at `requires_action`; resume by posting a follow-up run with
+ *    `payload.kind: "tool_outputs"`.
+ */
+export type ConversationId = string;
+export type RunId = string;
+export type ClientOpId = string;
+export type ConversationVersion = number;
+export type ToolUseId = string;
+export type AgentModel = "anthropic.claude-haiku-4.5" | "anthropic.claude-sonnet-4.5" | "anthropic.claude-sonnet-4.6" | "anthropic.claude-opus-4.5" | "anthropic.claude-opus-4.6" | "openai.gpt-oss-120b" | "openai.gpt-4.1" | "openai.o4-mini" | (string & {});
+export type ExecutionCluster = "shared" | "dedicated";
+/** Subset of JSON Schema Draft 2020-12 accepted by Bedrock structured output. */
+export type JsonSchemaObject = Record<string, unknown>;
+export interface McpServerConfig {
+    /** 1–8 char `[a-zA-Z][a-zA-Z0-9]{0,7}` — namespace prefix for the server's tools. */
+    alias: string;
+    url: string;
+    description?: string;
+}
+export interface ToolSpec {
+    /** Caller-declared tools must NOT contain a dash. MCP tools' bare name. */
+    name: string;
+    description: string;
+    input_schema: JsonSchemaObject;
+    /** Defaults to true. Leave true in production. */
+    strict?: boolean;
+}
+export interface ConversationDefaults {
+    model: AgentModel;
+    data_plane_id: string;
+    execution_cluster: ExecutionCluster;
+    compute_pool_id?: string;
+    max_iterations?: number;
+    max_tokens?: number;
+    temperature?: number;
+    output_format_schema?: JsonSchemaObject;
+    mcp_servers?: McpServerConfig[];
+    tools?: ToolSpec[];
+}
+export interface CreateConversationRequest {
+    name?: string;
+    system_prompt?: string;
+    defaults: ConversationDefaults;
+}
+export interface ConversationResponse {
+    id: ConversationId;
+    company_id: number;
+    user_id: number;
+    name: string | null;
+    system_prompt: string | null;
+    defaults: ConversationDefaults;
+    version: ConversationVersion;
+    created_at: string;
+    updated_at: string;
+}
+export type RunStatus = "pending" | "running" | "completed" | "requires_action" | "failed";
+export interface UserMessagePayload {
+    kind: "user_message";
+    text: string;
+}
+export interface ToolOutput {
+    tool_use_id: ToolUseId;
+    /** Plain text. Serialize JSON results before sending. */
+    content: string;
+    is_error?: boolean;
+}
+export interface ToolOutputsPayload {
+    kind: "tool_outputs";
+    outputs: ToolOutput[];
+}
+export type RunPayload = UserMessagePayload | ToolOutputsPayload;
+export type ToolChoice = {
+    kind: "auto";
+} | {
+    kind: "any";
+} | {
+    kind: "specific_tool";
+    name: string;
+    /** Set when pinning an MCP-resolved tool; omit for caller-declared. */
+    mcp_alias?: string | null;
+};
+/** Sparse override applied per-run; lists replace wholesale. */
+export interface RunConfigOverride {
+    model?: AgentModel;
+    data_plane_id?: string;
+    execution_cluster?: ExecutionCluster;
+    compute_pool_id?: string;
+    max_iterations?: number;
+    max_tokens?: number;
+    temperature?: number;
+    output_format_schema?: JsonSchemaObject;
+    mcp_servers?: McpServerConfig[];
+    tools?: ToolSpec[];
+}
+export interface CreateRunRequest {
+    client_op_id: ClientOpId;
+    expected_version: ConversationVersion;
+    payload: RunPayload;
+    tool_choice?: ToolChoice;
+    config_override?: RunConfigOverride;
+}
+export interface PendingToolCall {
+    tool_use_id: ToolUseId;
+    /** Wire-form name. For caller-declared tools, dash-free. */
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface AgentInferenceUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface RunError {
+    /** Stable incident code, e.g. "AgentLoopMaxIterationsExceeded". */
+    type: string;
+    message: string;
+    title?: string;
+    docs_url?: string;
+}
+export interface RunResponse {
+    id: RunId;
+    conversation_id: ConversationId;
+    company_id: number;
+    user_id: number;
+    client_op_id: ClientOpId;
+    status: RunStatus;
+    tool_choice?: ToolChoice;
+    effective_config: ConversationDefaults;
+    iterations_used?: number | null;
+    usage?: AgentInferenceUsage | null;
+    submitted_inference_job_ids: string[];
+    pending_tool_calls: PendingToolCall[];
+    final_text?: string | null;
+    error?: RunError | null;
+    started_at: string;
+    completed_at?: string | null;
+}
+export type AgentMessageRole = "user" | "assistant" | "tool";
+export interface TextContentBlock {
+    type: "text";
+    text: string;
+}
+export interface ToolUseContentBlock {
+    type: "tool_use";
+    tool_use_id: ToolUseId;
+    /** Fully-aliased wire name (`{alias}-{tool_name}` for MCP, bare for caller-declared). */
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolResultContentBlock {
+    type: "tool_result";
+    tool_use_id: ToolUseId;
+    content: ContentBlock[];
+    is_error: boolean;
+}
+export type ContentBlock = TextContentBlock | ToolUseContentBlock | ToolResultContentBlock;
+export interface MessageDto {
+    id: string;
+    sequence_no: number;
+    role: AgentMessageRole;
+    content_blocks: ContentBlock[];
+    run_id: RunId;
+    created_at: string;
+}
+export interface ListMessagesResponse {
+    current_version: ConversationVersion;
+    messages: MessageDto[];
+}
+export interface AgentRfcError {
+    type?: string | null;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    log_id: string;
+    debug?: Record<string, unknown> | null;
+}
+export declare const TERMINAL_RUN_STATUSES: ReadonlyArray<RunStatus>;
+export declare function isTerminalRunStatus(status: RunStatus): boolean;

package/build/agents/types.js

@@ -0,0 +1,22 @@
+/**
+ * Agent Conversations API — types.
+ *
+ * Mirrors `/agents/conversations` and `/agents/runs` on the Narrative Data
+ * Collaboration Platform (RFC 7807 errors; OpenAI-Assistants-shaped semantics).
+ *
+ * Two tool dimensions:
+ *  - `mcp_servers[]` — server-side, resolved by the platform via MCP. Model sees
+ *    each tool as `{alias}-{name}`.
+ *  - `tools[]` — caller-declared. Dash-free names. When called, the run pauses
+ *    at `requires_action`; resume by posting a follow-up run with
+ *    `payload.kind: "tool_outputs"`.
+ */
+// Terminal states helper
+export const TERMINAL_RUN_STATUSES = [
+    "completed",
+    "requires_action",
+    "failed",
+];
+export function isTerminalRunStatus(status) {
+    return TERMINAL_RUN_STATUSES.includes(status);
+}

package/build/apps/index.d.ts

@@ -1,5 +1,4 @@
 import { BaseApi } from "../base-api";
-import type { JsonSchemaConnectorPolicy } from "../collaboration-policy/core/jsonschema/json-schema-types";
 import type { ApiRecords } from "../types";
 import type { App, Installation } from "./types";
 /**
@@ -15,11 +14,5 @@ declare class AppsApi extends BaseApi {
      */
     getApps(appCategory?: string): Promise<ApiRecords<App>>;
     getInstalledApps(appCategory?: string): Promise<ApiRecords<Installation>>;
-    /**
-     * Get all interfaces for the current user's installed connectors.
-     * @param {string[]} [tags] - Optional tags to filter interfaces (e.g. ["audience_delivery"]).
-     * @returns {Promise<ApiRecords<JsonSchemaConnectorPolicy>>} - Promise resolving with the list of interfaces.
-     */
-    getInstalledInterfaces(tags?: string[]): Promise<ApiRecords<JsonSchemaConnectorPolicy>>;
 }
 export { type App, AppsApi, type Installation };

package/build/apps/index.js

@@ -21,14 +21,5 @@ class AppsApi extends BaseApi {
         const url = `installations${appCategoryQuery}`;
         return await this.get(url);
     }
-    /**
-     * Get all interfaces for the current user's installed connectors.
-     * @param {string[]} [tags] - Optional tags to filter interfaces (e.g. ["audience_delivery"]).
-     * @returns {Promise<ApiRecords<JsonSchemaConnectorPolicy>>} - Promise resolving with the list of interfaces.
-     */
-    async getInstalledInterfaces(tags) {
-        const queryString = this.constructQueryString(tags != null ? { tags } : undefined);
-        return await this.get(`${resourceName}/installed/interfaces${queryString}`);
-    }
 }
 export { AppsApi };

package/build/collaboration-policy/core/filter-builder.js

@@ -1,12 +1,6 @@
 import { normalizePathValue } from "../utils/path-helpers";
 import { resolveAttributeExpression } from "../utils/sql-helpers";
-function isAttributeReference(node) {
-    return (!!node &&
-        typeof node === "object" &&
-        "type" in node &&
-        node.type === "attribute" &&
-        "attribute_name" in node);
-}
+import { isAttributeReference } from "./filter-utils";
 export function filterToSql(filter, attributeByName, datasetName) {
     const op = filter.op.toLowerCase();
     switch (op) {

package/build/collaboration-policy/core/types.d.ts

@@ -1,91 +1,20 @@
-/**
- * PathValue describes a path to a subfield, expressed as either dot notation
- * or a JSON Pointer. Used in filter attribute references to specify which
- * subfield of an attribute to operate on.
- */
-export type PathValue = {
-    dot: string;
-} | {
-    pointer: string;
-};
-/**
- * An attribute reference within a filter expression.
- */
-export interface FilterAttributeRef {
-    type: "attribute";
-    attribute_name: string;
-    path?: PathValue;
-}
-/**
- * A filter expression: a literal value or an attribute reference.
- */
-export type FilterExpression = string | number | boolean | FilterAttributeRef;
-/**
- * PolicyFilter is a single filter entry in a policy definition.
- *
- * This is the canonical filter type used across the codebase (JSON-Schema
- * filters, SQL builder, etc.).
- */
-export type PolicyFilter = PolicyFilterAndOr | PolicyFilterNot | PolicyFilterIsNull | PolicyFilterIn | PolicyFilterCompare | PolicyFilterBetween;
-interface PolicyFilterBase {
-    stage?: "generation";
-    name?: string;
-    required?: boolean;
-}
-interface PolicyFilterAndOr extends PolicyFilterBase {
-    op: "and" | "or";
-    args: FilterExpression[];
-}
-interface PolicyFilterNot extends PolicyFilterBase {
-    op: "not";
-    args: FilterExpression[];
-}
-interface PolicyFilterIsNull extends PolicyFilterBase {
-    op: "is_null" | "is_not_null";
-    left: FilterExpression;
-}
-interface PolicyFilterIn extends PolicyFilterBase {
-    op: "in" | "not in";
-    left: FilterExpression;
-    right: FilterExpression[];
-}
-interface PolicyFilterCompare extends PolicyFilterBase {
-    op: "=" | "<>" | ">" | ">=" | "<" | "<=" | "like" | "not like";
-    left: FilterExpression;
-    right: FilterExpression;
-}
-interface PolicyFilterBetween extends PolicyFilterBase {
-    op: "between";
-    operand: FilterExpression;
-    lower: FilterExpression;
-    upper: FilterExpression;
-}
-/**
- * Map from attribute name -> set of normalized paths that must be selected
- * for SQL generation.
- */
+import type { CollaborationPolicyType } from "../types";
+type PolicyDefinition = CollaborationPolicyType["policy"]["definition"];
+export type StructureNode = PolicyDefinition["structure"];
+export type ExtendedAttributeNode = Extract<StructureNode, {
+    field: unknown;
+}>;
+export type PolicyFilter = NonNullable<PolicyDefinition["filters"]>[number];
+export type PathValue = NonNullable<ExtendedAttributeNode["field"]["additional_required_properties"]>[number];
 export type AttributePathIndex = Map<string, Set<string>>;
-/**
- * A logical group of SQL fragments combined by an operation.
- */
 export interface PolicySqlGroup {
     fragments: Array<string | PolicySqlGroup>;
     operation: "AND" | "OR";
 }
-/**
- * Core SQL fragments required to represent a set of collaboration policies.
- */
 export interface PolicySqlFragments {
     select: string[];
     where: Array<PolicySqlGroup | string>;
 }
-/**
- * Full result of applying collaboration policies to a dataset, including:
- * - which policies were applied
- * - which were skipped and why
- * - warnings
- * - the minimum refresh schedule across applied policies
- */
 export interface PolicyMatchResult extends PolicySqlFragments {
     appliedPolicies: string[];
     skippedPolicies: Array<{
@@ -94,7 +23,7 @@ export interface PolicyMatchResult extends PolicySqlFragments {
         details: string[];
     }>;
     warnings: string[];
-    /** The minimum refresh schedule as an ISO 8601 duration string across all evaluated policies */
-    refresh_schedule: string;
+    /** The minimum refresh schedule in milliseconds across all evaluated policies */
+    refresh_schedule: number;
 }
 export {};

package/build/collaboration-policy/index.d.ts

@@ -1,5 +1,4 @@
-export type { JsonSchemaConnectorPolicy } from "./core/jsonschema/json-schema-types";
-export { evaluateJsonSchemaPolicies } from "./core/jsonschema/policy-evaluator";
-export { buildPolicySql, buildPolicySqlWithJsonSchema, buildPolicySqlWithValidation, categorizePolicies, type JsonSchemaPolicyMatchResult, } from "./core/jsonschema/sql-builder";
-export type { AttributePathIndex, FilterAttributeRef, FilterExpression, PathValue, PolicyFilter, PolicyMatchResult, PolicySqlFragments, PolicySqlGroup, } from "./core/types";
-export { default as useCollaborationPolicy } from "./useCollaborationPolicy";
+export { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/sql-builder";
+export type { AttributePathIndex, ExtendedAttributeNode, PathValue, PolicyFilter, PolicyMatchResult, PolicySqlFragments, PolicySqlGroup, StructureNode, } from "./core/types";
+export type { CollaborationPolicyInput, CollaborationPolicyType, } from "./types";
+export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./types";

package/build/collaboration-policy/index.js

@@ -1,4 +1,3 @@
-export { evaluateJsonSchemaPolicies } from "./core/jsonschema/policy-evaluator";
-export { buildPolicySql, buildPolicySqlWithJsonSchema, buildPolicySqlWithValidation, categorizePolicies, } from "./core/jsonschema/sql-builder";
-// Hook-style entrypoint
-export { default as useCollaborationPolicy } from "./useCollaborationPolicy";
+// Export the main functions
+export { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/sql-builder";
+export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./types";