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

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,52 @@ 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 escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function parseFunction(n) {
+    if (n.type !== "function") {
+        return nqlOrFail(n);
+    }
+    // Only structure functions whose original text is the standard call
+    // syntax `NAME(arg, arg, ...)`, optionally followed by an alias — the
+    // server serializes `expr AS alias` as the inner node with the alias
+    // wrapper's `as`/`nql` merged on top, so an aliased function's `nql`
+    // span reads `NAME(args) AS alias`. 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. The match
+    // tolerates whitespace differences (and a missing/implicit AS keyword)
+    // because compiling name + args back to `NAME(arg, arg, ...) AS "alias"`
+    // only ever normalizes those, never changes semantics.
+    const argTexts = n.args.map((a) => "nql" in a ? a.nql : undefined);
+    if (argTexts.some((t) => t === undefined)) {
+        return nqlOrFail(n);
+    }
+    const aliasSuffix = n.as !== undefined
+        ? `(?:\\s+(?:AS\\s+)?(?:"${escapeRegExp(n.as)}"|${escapeRegExp(n.as)}))?`
+        : "";
+    const standardCall = new RegExp(`^${escapeRegExp(n.name)}\\s*\\(\\s*${argTexts
+        .map(escapeRegExp)
+        .join("\\s*,\\s*")}\\s*\\)${aliasSuffix}$`, "i");
+    if (!standardCall.test(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": {
@@ -586,10 +625,18 @@ function oneOf(...fs) {
 function nqlOrFail(n) {
     if ("nql" in n) {
         const as = "as" in n ? n.as : undefined;
+        // The server serializes `expr AS alias` by merging the alias wrapper's
+        // `as`/`nql` onto the inner node, so an aliased node's span carries a
+        // trailing ` AS alias`. Strip it: a Raw node's `nql` holds the bare
+        // expression and `as` holds the alias — otherwise compiling the node
+        // re-appends the alias and emits a corrupt double alias.
+        const nqlText = as !== undefined
+            ? n.nql.replace(new RegExp(`\\s+(?:AS\\s+)?(?:"${escapeRegExp(as)}"|${escapeRegExp(as)})\\s*$`, "i"), "")
+            : n.nql;
         const nql = {
             type: "nql",
             as,
-            nql: n.nql,
+            nql: nqlText,
         };
         return nql;
     }

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.1",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -43,7 +43,7 @@
 	},
 	"dependencies": {
 		"zod": "4.4.3",
-		"bignumber.js": "11.1.4"
+		"bignumber.js": "11.1.5"
 	},
 	"overrides": {
 		"semver@<7.5.2": "7.5.2"