@narrative.io/data-collaboration-sdk-ts 3.4.0 → 3.5.0

package/build/agents/types.d.ts

@@ -25,6 +25,13 @@ export interface McpServerConfig {
     alias: string;
     url: string;
     description?: string;
+    /**
+     * Reference to a registered external-MCP OAuth connection (from `POST /mcp-connections`,
+     * see {@link McpConnectionsApi}). Set for an external server that requires user
+     * authorization — the platform resolves and refreshes the connection's bearer token
+     * server-side; it never appears in the payload. Omit for public or Narrative-owned MCPs.
+     */
+    connection_id?: string;
 }
 export interface ToolSpec {
     /** Caller-declared tools must NOT contain a dash. MCP tools' bare name. */

package/build/index.d.ts

@@ -30,6 +30,8 @@ export * from "./jobs";
 export { default as JsonBigNumber } from "./json-big-number";
 export * from "./mappings";
 export * from "./mappings/types";
+export * from "./mcp-connections";
+export * from "./mcp-connections/types";
 export * from "./model-inference";
 export * from "./model-training";
 export * from "./models";
@@ -77,6 +79,7 @@ import { HealthCheckApi } from "./health";
 import { InstallationsApi } from "./installations";
 import { JobsApi } from "./jobs";
 import { MappingsApi } from "./mappings";
+import { McpConnectionsApi } from "./mcp-connections";
 import { ModelInferenceApi } from "./model-inference";
 import { ModelTrainingApi } from "./model-training";
 import { ModelsApi } from "./models";
@@ -92,6 +95,6 @@ import { WhoAmIApi } from "./whoami";
 import { WorkflowsApi } from "./workflows";
 declare class NarrativeApi extends BaseApi {
 }
-interface NarrativeApi extends BaseApi, HealthCheckApi, AccessTokensApi, DataPlaneApi, DatasetApi, RosettaStoneApi, AttributeApi, AttributeApiV2, PingApi, CompanyInfoApi, InstallationsApi, ConnectionsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, AuthenticationApi, MappingsApi, AccessRulesApi, AppsApi, SubscriptionsApi, JobsApi, QueriesApi, ViewsApi, ModelsApi, ModelTrainingApi, ModelInferenceApi, EncryptionMaterialApi, WhoAmIApi, WorkflowsApi, ComputePoolsApi, AgentsApi, CompaniesApi {
+interface NarrativeApi extends BaseApi, HealthCheckApi, AccessTokensApi, DataPlaneApi, DatasetApi, RosettaStoneApi, AttributeApi, AttributeApiV2, PingApi, CompanyInfoApi, InstallationsApi, ConnectionsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, AuthenticationApi, MappingsApi, AccessRulesApi, AppsApi, SubscriptionsApi, JobsApi, QueriesApi, ViewsApi, ModelsApi, ModelTrainingApi, ModelInferenceApi, EncryptionMaterialApi, WhoAmIApi, WorkflowsApi, ComputePoolsApi, AgentsApi, CompaniesApi, McpConnectionsApi {
 }
 export { NarrativeApi };

package/build/index.js

@@ -31,6 +31,8 @@ export * from "./jobs";
 export { default as JsonBigNumber } from "./json-big-number";
 export * from "./mappings";
 export * from "./mappings/types";
+export * from "./mcp-connections";
+export * from "./mcp-connections/types";
 export * from "./model-inference";
 export * from "./model-training";
 export * from "./models";
@@ -78,6 +80,7 @@ import { HealthCheckApi } from "./health";
 import { InstallationsApi } from "./installations";
 import { JobsApi } from "./jobs";
 import { MappingsApi } from "./mappings";
+import { McpConnectionsApi } from "./mcp-connections";
 import { ModelInferenceApi } from "./model-inference";
 import { ModelTrainingApi } from "./model-training";
 import { ModelsApi } from "./models";
@@ -130,5 +133,6 @@ applyMixins(NarrativeApi, [
     ComputePoolsApi,
     AgentsApi,
     CompaniesApi,
+    McpConnectionsApi,
 ]);
 export { NarrativeApi };

package/build/mcp-connections/index.d.ts

@@ -0,0 +1,38 @@
+import { BaseApi } from "../base-api";
+import type { CreateMcpConnectionRequest, ListMcpConnectionsResponse, McpConnectionCreatedResponse, McpConnectionSummary } from "./types";
+/**
+ * `McpConnectionsApi` wraps the external-MCP connection endpoints. A connection is a per-user
+ * OAuth link to an external (non-Narrative) MCP server; once `connected`, an agent conversation
+ * can reference it by id via `mcp_servers[].connection_id`. Tokens are never returned by the API.
+ *
+ * The OAuth callback (`GET /mcp-connections/callback`) is a browser redirect, not an SDK call, so
+ * it is intentionally not wrapped here.
+ */
+export declare class McpConnectionsApi extends BaseApi {
+    /**
+     * Lists the calling user's MCP connections with their status. Credential-free.
+     * @returns {Promise<ListMcpConnectionsResponse>} The caller's connections (empty if none).
+     */
+    listMcpConnections(): Promise<ListMcpConnectionsResponse>;
+    /**
+     * Begins connecting an external MCP server (OAuth discovery + dynamic client registration).
+     * @param {CreateMcpConnectionRequest} request - The server `url` and routing `alias`.
+     * @returns {Promise<McpConnectionCreatedResponse>} The pending `connection_id` and the
+     * `authorization_url` the user must visit to consent.
+     */
+    createMcpConnection(request: CreateMcpConnectionRequest): Promise<McpConnectionCreatedResponse>;
+    /**
+     * Fetches one of the calling user's connections.
+     * @param {string} connectionId - The connection id.
+     * @returns {Promise<McpConnectionSummary>} The connection's status view. Rejects with 404 if it
+     * does not exist or belongs to another user.
+     */
+    getMcpConnection(connectionId: string): Promise<McpConnectionSummary>;
+    /**
+     * Deletes one of the calling user's connections and its stored tokens.
+     * @param {string} connectionId - The connection id.
+     * @returns {Promise<void>} Resolves when deleted. Rejects with 404 if it does not exist or
+     * belongs to another user.
+     */
+    deleteMcpConnection(connectionId: string): Promise<void>;
+}

package/build/mcp-connections/index.js

@@ -0,0 +1,46 @@
+import { BaseApi } from "../base-api";
+const resourceName = "mcp-connections";
+/**
+ * `McpConnectionsApi` wraps the external-MCP connection endpoints. A connection is a per-user
+ * OAuth link to an external (non-Narrative) MCP server; once `connected`, an agent conversation
+ * can reference it by id via `mcp_servers[].connection_id`. Tokens are never returned by the API.
+ *
+ * The OAuth callback (`GET /mcp-connections/callback`) is a browser redirect, not an SDK call, so
+ * it is intentionally not wrapped here.
+ */
+export class McpConnectionsApi extends BaseApi {
+    /**
+     * Lists the calling user's MCP connections with their status. Credential-free.
+     * @returns {Promise<ListMcpConnectionsResponse>} The caller's connections (empty if none).
+     */
+    async listMcpConnections() {
+        return await this.get(resourceName);
+    }
+    /**
+     * Begins connecting an external MCP server (OAuth discovery + dynamic client registration).
+     * @param {CreateMcpConnectionRequest} request - The server `url` and routing `alias`.
+     * @returns {Promise<McpConnectionCreatedResponse>} The pending `connection_id` and the
+     * `authorization_url` the user must visit to consent.
+     */
+    async createMcpConnection(request) {
+        return await this.post(resourceName, request);
+    }
+    /**
+     * Fetches one of the calling user's connections.
+     * @param {string} connectionId - The connection id.
+     * @returns {Promise<McpConnectionSummary>} The connection's status view. Rejects with 404 if it
+     * does not exist or belongs to another user.
+     */
+    async getMcpConnection(connectionId) {
+        return await this.get(`${resourceName}/${connectionId}`);
+    }
+    /**
+     * Deletes one of the calling user's connections and its stored tokens.
+     * @param {string} connectionId - The connection id.
+     * @returns {Promise<void>} Resolves when deleted. Rejects with 404 if it does not exist or
+     * belongs to another user.
+     */
+    async deleteMcpConnection(connectionId) {
+        await this.delete(`${resourceName}/${connectionId}`);
+    }
+}

package/build/mcp-connections/types.d.ts

@@ -0,0 +1,22 @@
+export type McpConnectionStatus = "pending" | "connected" | "error";
+export interface CreateMcpConnectionRequest {
+    url: string;
+    alias: string;
+}
+export interface McpConnectionCreatedResponse {
+    connection_id: string;
+    authorization_url: string;
+}
+export interface McpConnectionSummary {
+    connection_id: string;
+    server_url: string;
+    alias: string;
+    authorization_server: string;
+    status: McpConnectionStatus;
+    expires_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ListMcpConnectionsResponse {
+    connections: McpConnectionSummary[];
+}

package/build/mcp-connections/types.js

@@ -0,0 +1 @@
+export {};

package/build/nql/AstParser.d.ts

@@ -36,8 +36,8 @@ export interface Select {
     from: Table[] | Raw;
     where: BooleanExpression | Raw | null;
 }
-export type Output = ColumnRef | Lit | Raw | ast.NqlPlaceholder<ast.NqlAstType>;
-export type Expression = BooleanExpression | ColumnRef | Lit | Raw | ast.NqlPlaceholder<ast.NqlAstType>;
+export type Output = ColumnRef | Lit | Func | Raw | ast.NqlPlaceholder<ast.NqlAstType>;
+export type Expression = BooleanExpression | ColumnRef | Lit | Func | Raw | ast.NqlPlaceholder<ast.NqlAstType>;
 export interface Raw {
     type: "nql";
     as?: string;
@@ -99,6 +99,12 @@ export interface Lit {
     value_type: ast.NqlSimpleType;
     value: string | null;
 }
+export interface Func {
+    type: "function";
+    as?: string;
+    name: string;
+    args: Expression[];
+}
 export interface And {
     type: "and";
     as?: string;

package/build/nql/AstParser.js

@@ -175,13 +175,38 @@ export function parseDeduplication(n) {
     return n.qualify !== null ? nqlOrFail(n.qualify) : null;
 }
 export function parseExpression(n) {
-    const parse = oneOf(parseBooleanExpression, parseColumnRef, parseLit, parseStringExpression, parsePlaceholder);
+    const parse = oneOf(parseBooleanExpression, parseColumnRef, parseLit, parseFunction, parseStringExpression, parsePlaceholder);
     return parse(n);
 }
 export function parseOutput(n) {
-    const parse = oneOf(parseColumnRef, parseLit, parsePlaceholder);
+    const parse = oneOf(parseColumnRef, parseLit, parseFunction, parsePlaceholder);
     return parse(n);
 }
+function parseFunction(n) {
+    if (n.type !== "function") {
+        return nqlOrFail(n);
+    }
+    // Only structure functions whose original text is exactly the standard
+    // call syntax `NAME(arg, arg, ...)`. Functions with special syntax —
+    // EXTRACT(unit FROM x), CAST(x AS type), TRIM(BOTH ' ' FROM x) — cannot
+    // be regenerated from name + args and must stay Raw passthroughs, or
+    // compiling would emit comma syntax and corrupt the query.
+    const argTexts = n.args.map((a) => "nql" in a ? a.nql : undefined);
+    if (argTexts.some((t) => t === undefined)) {
+        return nqlOrFail(n);
+    }
+    const reconstructed = `${n.name}(${argTexts.join(", ")})`;
+    if (reconstructed !== n.nql) {
+        return nqlOrFail(n);
+    }
+    const func = {
+        type: "function",
+        as: n.as,
+        name: n.name,
+        args: n.args.map(parseExpression),
+    };
+    return func;
+}
 function parseBooleanExpression(n) {
     switch (n.type) {
         case "binary_op": {

package/build/nql/AstTraverse.js

@@ -28,6 +28,8 @@ function findTraversalTargets(node) {
             }
             return inTargets;
         }
+        case "function":
+            return node.args;
         case "deduplication":
             return node.expressions;
         case "select": {

package/build/nql/NqlBuilder.js

@@ -214,6 +214,8 @@ export function compileOutput(n, dsMap) {
             return compileDatasetColumnRef(n.datasetId, n.column, n.as, dsMap);
         case "lit":
             return compileLit(n.value, n.value_type, n.as, false);
+        case "function":
+            return compileFunction(n, dsMap, false);
         case "raw_ref":
             return compileRawRef(n.nql, n.as);
         case "nql":
@@ -253,6 +255,8 @@ export function compileExpression(n, dsMap) {
             return compileLike(n.value, n.pattern, n.negated, n.as, dsMap);
         case "lit":
             return compileLit(n.value, n.value_type, n.as);
+        case "function":
+            return compileFunction(n, dsMap);
         case "not":
             return compileNot(n.operand, n.as, dsMap);
         case "or":
@@ -355,6 +359,10 @@ function compilePostfixUnaryOperator(op, operand, as, dsMap) {
 function compileRawRef(nql, as) {
     return aliased(nql, as);
 }
+function compileFunction(n, dsMap, parens) {
+    const args = n.args.map((arg) => compileExpression(arg, dsMap)).join(", ");
+    return aliased(`${n.name}(${args})`, n.as, parens);
+}
 export function compilePlaceholder(n) {
     switch (n.expectedType) {
         case "literal":

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "3.4.0",
+	"version": "3.5.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",