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

package/README.md

@@ -311,6 +311,80 @@ try {
 }
 ```
 
+### Centralized Error Handling
+
+Instead of repeating `try/catch` normalization at every call site, you can register a
+single `errorTransformer` on the client. It runs once per failed request — for both
+non-2xx responses (as an `HttpError`) and native fetch/network rejections — after the
+`HttpError` (with its parsed `body`) has been built. Whatever it returns is thrown in
+its place, so you can map transport failures onto your own application error types.
+
+The SDK only supplies the mechanism; your application decides what a failure *means*.
+The SDK does not log out, retry, redirect, show a toast, or treat any status as fatal
+on your behalf. A `500`, for example, is not automatically application-fatal — that
+policy is yours to define. This keeps the SDK framework-agnostic: no Vue, Nuxt, Pinia,
+or other UI dependency is involved.
+
+```typescript
+import {
+  NarrativeApi,
+  HttpError,
+  type HttpRequestContext,
+} from '@narrative.io/data-collaboration-sdk-ts';
+
+// Your application's own error types — the SDK does not define these.
+class AuthenticationRequiredError extends Error {}
+class ApiServerError extends Error {}
+
+const narrative = new NarrativeApi({
+  apiKey: process.env.NARRATIVE_API_KEY!,
+  errorTransformer(error: unknown, context: HttpRequestContext) {
+    // Only HTTP responses carry a status; network rejections do not.
+    if (error instanceof HttpError) {
+      const status = error.response.status;
+
+      if (status === 401) {
+        return new AuthenticationRequiredError(
+          `Authentication required for ${context.method} ${context.url}`,
+        );
+      }
+
+      if (status >= 500) {
+        return new ApiServerError(`Server error (${status})`);
+      }
+    }
+
+    // Return `undefined` (or the original `error`) to rethrow it unchanged.
+    return undefined;
+  },
+});
+```
+
+Semantics:
+
+- The transformer runs **exactly once** per failed request, always after the
+  `HttpError` and its parsed `body` are available.
+- **Returning the original `error`** preserves its object identity.
+- **Returning a replacement** causes that value to be thrown instead.
+- **Returning `undefined`** means "rethrow the original error unchanged" — identical
+  to having no transformer.
+- If the **transformer itself throws or rejects**, that error propagates and the
+  transformer is not invoked a second time.
+- `context` intentionally exposes only `method` and `url`. Request bodies and headers
+  (including `Authorization`) are never passed to the transformer.
+
+### Custom `fetch` Implementation
+
+By default the SDK uses `globalThis.fetch`. You can supply your own implementation —
+useful for tests, instrumentation, or non-browser runtimes:
+
+```typescript
+const narrative = new NarrativeApi({
+  apiKey: process.env.NARRATIVE_API_KEY!,
+  fetch: myCustomFetch, // defaults to globalThis.fetch
+});
+```
+
 ## API Reference
 
 For detailed API documentation, please visit the [Narrative.io API Documentation](https://api.narrative.dev).

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/base-api.js

@@ -23,6 +23,8 @@ export class BaseApi {
             baseUrl: this.getBaseUrl(),
             headers: this.constructHeaders(),
             responseAs: config.responseAs ?? "json",
+            errorTransformer: config.errorTransformer,
+            fetch: config.fetch,
         });
         if (this.verbose) {
             console.info(`Using environment: ${this.environment}`);

package/build/forecast/types.d.ts

@@ -72,7 +72,7 @@ export interface ForecastDimensions {
     distinct_counts: string[];
     group_by?: string;
 }
-export type JobState = "pending" | "running" | "completed" | "pending_cancellation" | "cancelled" | "failed";
+export type JobState = "pending" | "scheduled" | "running" | "completed" | "pending_cancellation" | "cancelled" | "failed";
 export interface ForecastResult {
     cost: number;
     datasets: DatasetForecastResponse[];

package/build/http-client.d.ts

@@ -11,9 +11,40 @@
  *   resolves to `null`
  * - throws on any non-2xx status, attaching the {@link Response} and the parsed
  *   body to the error
+ *
+ * An optional {@link HttpErrorTransformer} lets consumers observe or replace the
+ * error before it propagates. It runs for both non-2xx responses and network
+ * rejections, always after the {@link HttpError} (with its parsed body) has been
+ * built. When absent, the original error is thrown unchanged.
  */
 /** How a response body should be returned from a request. */
 export type ResponseAs = "json" | "text" | "response";
+/** HTTP verbs the SDK issues. */
+export type HttpRequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Minimal, side-effect-free description of the request that produced an error.
+ *
+ * Intentionally excludes the request body and headers (including any
+ * `Authorization` header) so an {@link HttpErrorTransformer} cannot leak
+ * credentials or payloads.
+ */
+export interface HttpRequestContext {
+    /** The HTTP verb used for the request. */
+    method: HttpRequestMethod;
+    /** The fully-resolved request URL (base URL joined with the endpoint). */
+    url: string;
+}
+/**
+ * Hook invoked when a request fails, either with an {@link HttpError} (non-2xx)
+ * or a native fetch/network rejection.
+ *
+ * Return the value to throw in place of the original error. Returning the
+ * original `error` preserves its identity. Returning `undefined` means "rethrow
+ * the original error unchanged" — the same as having no transformer. If the
+ * transformer itself throws (or rejects), that error propagates; the transformer
+ * is never invoked a second time for the same request.
+ */
+export type HttpErrorTransformer = (error: unknown, context: HttpRequestContext) => unknown | Promise<unknown>;
 /** Options for constructing an {@link HttpClient}. */
 export interface HttpClientOptions {
     /** Absolute base URL that every request is resolved against. */
@@ -22,6 +53,16 @@ export interface HttpClientOptions {
     headers?: Record<string, string>;
     /** How to interpret response bodies. Defaults to `"json"`. */
     responseAs?: ResponseAs;
+    /**
+     * Optional hook to observe or transform request failures. See
+     * {@link HttpErrorTransformer}.
+     */
+    errorTransformer?: HttpErrorTransformer;
+    /**
+     * Optional `fetch` implementation. Defaults to `globalThis.fetch`, resolved
+     * at call time so the ambient global is honored when this is omitted.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 /**
  * Error thrown for any non-2xx response. Carries the originating
@@ -36,10 +77,25 @@ export declare class HttpClient {
     private readonly baseUrl;
     private readonly headers;
     private readonly responseAs;
+    private readonly errorTransformer?;
+    private readonly fetchImpl?;
     constructor(options: HttpClientOptions);
     get<T>(url: string): Promise<T>;
     post<T>(url: string, data?: unknown): Promise<T>;
     put<T>(url: string, data?: unknown): Promise<T>;
     delete<T>(url: string): Promise<T>;
     private request;
+    /**
+     * Performs the request and parses the response. Throws {@link HttpError} on a
+     * non-2xx status; native fetch/network failures reject as they always have.
+     * All failures are funneled through {@link transformError} by {@link request}.
+     */
+    private send;
+    /**
+     * Runs the configured {@link HttpErrorTransformer}, if any, and returns the
+     * error to throw. Without a transformer, or when the transformer returns
+     * `undefined`, the original error is returned unchanged. A transformer that
+     * throws/rejects propagates its own error (and is not retried).
+     */
+    private transformError;
 }

package/build/http-client.js

@@ -11,6 +11,11 @@
  *   resolves to `null`
  * - throws on any non-2xx status, attaching the {@link Response} and the parsed
  *   body to the error
+ *
+ * An optional {@link HttpErrorTransformer} lets consumers observe or replace the
+ * error before it propagates. It runs for both non-2xx responses and network
+ * rejections, always after the {@link HttpError} (with its parsed body) has been
+ * built. When absent, the original error is thrown unchanged.
  */
 /**
  * Error thrown for any non-2xx response. Carries the originating
@@ -39,9 +44,13 @@ export class HttpClient {
     baseUrl;
     headers;
     responseAs;
+    errorTransformer;
+    fetchImpl;
     constructor(options) {
         this.baseUrl = options.baseUrl;
         this.responseAs = options.responseAs ?? "json";
+        this.errorTransformer = options.errorTransformer;
+        this.fetchImpl = options.fetch;
         this.headers = {
             Accept: "application/json",
             "Content-Type": "application/json",
@@ -61,12 +70,33 @@ export class HttpClient {
         return this.request("DELETE", url);
     }
     async request(method, url, data) {
+        const requestUrl = joinUrl(this.baseUrl, url);
+        try {
+            return await this.send(method, requestUrl, data);
+        }
+        catch (error) {
+            throw await this.transformError(error, {
+                method: method,
+                url: requestUrl,
+            });
+        }
+    }
+    /**
+     * Performs the request and parses the response. Throws {@link HttpError} on a
+     * non-2xx status; native fetch/network failures reject as they always have.
+     * All failures are funneled through {@link transformError} by {@link request}.
+     */
+    async send(method, requestUrl, data) {
         const init = { method, headers: this.headers };
         // Only POST/PUT/PATCH carry a body.
         if (method[0] === "P" && data !== undefined && data !== null) {
             init.body = JSON.stringify(data);
         }
-        const response = await fetch(joinUrl(this.baseUrl, url), init);
+        // Resolve the fetch implementation at call time so the ambient global is
+        // honored when no custom `fetch` was supplied. Invoked as a bare call so
+        // `this` stays undefined, which native fetch requires.
+        const fetchImpl = this.fetchImpl ?? globalThis.fetch;
+        const response = await fetchImpl(requestUrl, init);
         // Return the raw Response untouched when asked.
         if (this.responseAs === "response") {
             if (response.status >= 200 && response.status < 300) {
@@ -83,4 +113,16 @@ export class HttpClient {
         }
         throw new HttpError(response, body);
     }
+    /**
+     * Runs the configured {@link HttpErrorTransformer}, if any, and returns the
+     * error to throw. Without a transformer, or when the transformer returns
+     * `undefined`, the original error is returned unchanged. A transformer that
+     * throws/rejects propagates its own error (and is not retried).
+     */
+    async transformError(error, context) {
+        if (!this.errorTransformer)
+            return error;
+        const transformed = await this.errorTransformer(error, context);
+        return transformed === undefined ? error : transformed;
+    }
 }

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/jobs/index.d.ts

@@ -2,7 +2,7 @@ import { BaseApi } from "../base-api";
 import type { ApiRecordsV2 } from "../types";
 import type { CalculateAffectedRowsInput, CalculateAffectedRowsJob, CollectAccessRulesBillingDataInput, CollectAccessRulesBillingDataJob, CollectAccessRulesBillingDataResult, ColumnDetails, ColumnStatDataType, CostsInput, CostsJob, CreateTableInput, DatasetsCalculateColumnStatsJob, DatasetsCreateTableJob, DatasetsDeleteTableJob, DatasetsDeliverDataJob, DatasetsEnforceRowTtlRetentionPolicyJob, DatasetsEnforceTableTtlRetentionPolicyJob, DatasetsExecuteDmlJob, DatasetsExecuteSelectJob, DatasetsSampleJob, DatasetsSuggestMappingsJob, DatasetsTruncateTableJob, DeleteInput, DeliverInput, EnabledColumnStatFlags, EnforceRowTtlRetentionPolicyInput, EnforceTableTtlRetentionPolicyInput, ExecuteDmlInput, ExecuteDmlResult, ExecuteSelectInput, ExecuteSelectResult, ExplainInput, ExplainJob, ExplainOutput, ForecastInput, ForecastInternalJob, ForecastJob, HealthCheckJob, Job, JobExecutionCluster, JobRequestSource, JobRequestSourceApiUser, JobRequestSourceProcess, JobType, KnownJob, MaterializedViewInput, MaterializedViewJob, MaterializedViewOutput, MaterializedViewRowStats, ModelInferenceRunInput, ModelInferenceRunJob, ModelInferenceRunJobResult, ModelsDeliverModelInput, ModelsDeliverModelJob, ModelsTrainClassifierJob, ModelTrainingRunInput, ModelTrainingRunJob, RefreshMaterializedViewResult, SampleInput, StatsInput, StatsInputV2, SuggestMappingsInput, SuggestMappingsResult, TruncateTableInput } from "./types";
 import { isKnownJob, KNOWN_JOB_TYPES } from "./types";
-type JobStateFilter = "cancelled" | "completed" | "failed" | "pending" | "pending_cancellation" | "running";
+type JobStateFilter = "cancelled" | "completed" | "failed" | "pending" | "pending_cancellation" | "running" | "scheduled";
 interface GetJobsParameters extends Record<string, string | number | boolean | string[] | undefined> {
     dataset_id?: number;
     per_page?: number;

package/build/jobs/types.d.ts

@@ -39,6 +39,8 @@ interface BaseJob {
     idempotency_key: string;
     created_at: string;
     updated_at: string;
+    attempted_at: string;
+    attempt_version: number;
     ended_at?: string;
     tags?: string[];
     dequeued_at?: string;

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/build/types.d.ts

@@ -1,4 +1,4 @@
-import type { ResponseAs } from "./http-client";
+import type { HttpErrorTransformer, ResponseAs } from "./http-client";
 /**
  * Environment for the API.
  *
@@ -18,6 +18,23 @@ export interface Config {
     headers?: Record<string, string>;
     verbose?: boolean;
     responseAs?: ResponseAs;
+    /**
+     * Optional hook to centrally observe or transform request failures — both
+     * non-2xx responses (as an {@link HttpError}) and native fetch/network
+     * rejections. Return a replacement error to throw, return the original error
+     * to preserve it, or return `undefined` to rethrow it unchanged. With no
+     * transformer configured, errors propagate exactly as before.
+     *
+     * The SDK only supplies the mechanism; the consuming application decides
+     * whether a given failure is local, authentication-related, retryable, or
+     * fatal. A 500, for instance, is not treated as application-fatal here.
+     */
+    errorTransformer?: HttpErrorTransformer;
+    /**
+     * Optional `fetch` implementation, useful for testing and non-browser
+     * runtimes. Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 export interface ApiRecordsV2<T> extends PaginationMetadata {
     records: T[];

package/package.json

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