@narrative.io/data-collaboration-sdk-ts 4.1.0 → 4.3.0

package/build/generated/api-types.js

@@ -0,0 +1,13 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Source: https://docs-cdn.narrative.io/api-reference/main/openapi.json
+ * Spec etag: W/"2579229b75ddefef951659560f71d465"
+ *
+ * Regenerate with: bun run generate:api-types
+ */
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

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

@@ -6,7 +6,10 @@ import type { CreateMcpConnectionRequest, ListMcpConnectionsResponse, McpConnect
  * 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.
+ * it is intentionally not wrapped here. It only stores the authorization code and redirects; the
+ * app then calls {@link McpConnectionsApi.completeMcpConnection} to finish, authenticated as the
+ * user who began the flow. Because the callback is public, it is not allowed to complete anything
+ * itself — otherwise a `state` alone could turn another user's consent into a stored token.
  */
 export declare class McpConnectionsApi extends BaseApi {
     /**
@@ -21,6 +24,20 @@ export declare class McpConnectionsApi extends BaseApi {
      * `authorization_url` the user must visit to consent.
      */
     createMcpConnection(request: CreateMcpConnectionRequest): Promise<McpConnectionCreatedResponse>;
+    /**
+     * Completes a connection begun with {@link McpConnectionsApi.createMcpConnection}, once the user
+     * has consented and the OAuth callback has stored the authorization code. Exchanges that code and
+     * validates the connection with a `tools/list` call before storing the tokens.
+     *
+     * Must be called with the credentials of the user who began the flow — the `state` on its own is
+     * not enough.
+     * @param {string} state - The one-time `state` the OAuth callback forwarded to the app.
+     * @returns {Promise<McpConnectionSummary>} The connection's status view, normally `connected`.
+     * Rejects with 404 if the connection does not exist or belongs to another user; 400 if the
+     * `state` is unknown or expired, the authorization code has not arrived yet, or the token
+     * exchange or validation failed.
+     */
+    completeMcpConnection(state: string): Promise<McpConnectionSummary>;
     /**
      * Fetches one of the calling user's connections.
      * @param {string} connectionId - The connection id.

package/build/mcp-connections/index.js

@@ -6,7 +6,10 @@ const resourceName = "mcp-connections";
  * 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.
+ * it is intentionally not wrapped here. It only stores the authorization code and redirects; the
+ * app then calls {@link McpConnectionsApi.completeMcpConnection} to finish, authenticated as the
+ * user who began the flow. Because the callback is public, it is not allowed to complete anything
+ * itself — otherwise a `state` alone could turn another user's consent into a stored token.
  */
 export class McpConnectionsApi extends BaseApi {
     /**
@@ -25,6 +28,22 @@ export class McpConnectionsApi extends BaseApi {
     async createMcpConnection(request) {
         return await this.post(resourceName, request);
     }
+    /**
+     * Completes a connection begun with {@link McpConnectionsApi.createMcpConnection}, once the user
+     * has consented and the OAuth callback has stored the authorization code. Exchanges that code and
+     * validates the connection with a `tools/list` call before storing the tokens.
+     *
+     * Must be called with the credentials of the user who began the flow — the `state` on its own is
+     * not enough.
+     * @param {string} state - The one-time `state` the OAuth callback forwarded to the app.
+     * @returns {Promise<McpConnectionSummary>} The connection's status view, normally `connected`.
+     * Rejects with 404 if the connection does not exist or belongs to another user; 400 if the
+     * `state` is unknown or expired, the authorization code has not arrived yet, or the token
+     * exchange or validation failed.
+     */
+    async completeMcpConnection(state) {
+        return await this.post(`${resourceName}/complete`, { state });
+    }
     /**
      * Fetches one of the calling user's connections.
      * @param {string} connectionId - The connection id.

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

@@ -7,6 +7,9 @@ export interface McpConnectionCreatedResponse {
     connection_id: string;
     authorization_url: string;
 }
+export interface CompleteMcpConnectionRequest {
+    state: string;
+}
 export interface McpConnectionSummary {
     connection_id: string;
     server_url: string;

package/build/testing/auth.d.ts

@@ -0,0 +1,8 @@
+import type { AuthGuard, AuthGuardContext } from "./types";
+/**
+ * Returns the 401 to send back, or undefined when the request may proceed.
+ *
+ * The response is built here rather than through openapi-msw's typed `response`
+ * helper because none of the covered paths declare a 401 in the spec.
+ */
+export declare function rejectUnauthenticated(guard: AuthGuard, context: AuthGuardContext): Response | undefined;

package/build/testing/auth.js

@@ -0,0 +1,32 @@
+import { HttpResponse } from "msw";
+const BEARER_PREFIX = /^Bearer\s+/i;
+function isAuthenticated(guard, context) {
+    if (typeof guard === "function") {
+        return guard(context);
+    }
+    if (guard.type === "bearer") {
+        const header = context.request.headers.get("Authorization");
+        if (header == null || !BEARER_PREFIX.test(header)) {
+            return false;
+        }
+        const token = header.replace(BEARER_PREFIX, "");
+        return guard.token == null ? token.length > 0 : token === guard.token;
+    }
+    const cookie = context.cookies[guard.name];
+    if (cookie == null) {
+        return false;
+    }
+    return guard.value == null ? cookie.length > 0 : cookie === guard.value;
+}
+/**
+ * Returns the 401 to send back, or undefined when the request may proceed.
+ *
+ * The response is built here rather than through openapi-msw's typed `response`
+ * helper because none of the covered paths declare a 401 in the spec.
+ */
+export function rejectUnauthenticated(guard, context) {
+    if (guard === false || isAuthenticated(guard, context)) {
+        return undefined;
+    }
+    return HttpResponse.json({ message: "Unauthorized" }, { status: 401 });
+}

package/build/testing/fixtures/data-planes.d.ts

@@ -0,0 +1,8 @@
+import type { DataPlaneOwnedResponse, JobResponse } from "../types";
+/**
+ * An owned, active data plane. Every field the spec requires is filled in, so a
+ * caller only overrides what its assertion is about.
+ */
+export declare function createDataPlane(overrides?: Partial<DataPlaneOwnedResponse>): DataPlaneOwnedResponse;
+/** The job a health check enqueues, pending and not yet attempted. */
+export declare function createHealthCheckJob(overrides?: Partial<JobResponse>): JobResponse;

package/build/testing/fixtures/data-planes.js

@@ -0,0 +1,45 @@
+const TIMESTAMP = "2026-01-01T00:00:00Z";
+/**
+ * An owned, active data plane. Every field the spec requires is filled in, so a
+ * caller only overrides what its assertion is about.
+ */
+export function createDataPlane(overrides = {}) {
+    return {
+        type: "owned",
+        id: "5f9d1a4e-0000-4000-8000-000000000001",
+        company_id: 1,
+        created_at: TIMESTAMP,
+        display_name: "Test Data Plane",
+        external_id: "test-data-plane",
+        platform: { type: "platform_aws", region: "us-east-1" },
+        status: "active",
+        updated_at: TIMESTAMP,
+        collaborators: {
+            participants: { type: "none" },
+            manage_compute_pools: { type: "none" },
+        },
+        ...overrides,
+    };
+}
+/** The job a health check enqueues, pending and not yet attempted. */
+export function createHealthCheckJob(overrides = {}) {
+    return {
+        job_id: "5f9d1a4e-0000-4000-8000-00000000000a",
+        data_plane_id: "5f9d1a4e-0000-4000-8000-000000000001",
+        request_source: { type: "api_user", company_id: 1, user_id: 1 },
+        state: "pending",
+        type: "data-plane-health-check",
+        input: {},
+        executor: "job-executor-test",
+        execution_cluster: "dedicated",
+        failures: [],
+        idempotency_key: "test-idempotency-key",
+        result: {},
+        created_at: TIMESTAMP,
+        updated_at: TIMESTAMP,
+        attempted_at: TIMESTAMP,
+        attempt_version: 1,
+        ended_at: TIMESTAMP,
+        ...overrides,
+    };
+}

package/build/testing/fixtures/index.d.ts

@@ -0,0 +1 @@
+export { createDataPlane, createHealthCheckJob } from "./data-planes";

package/build/testing/fixtures/index.js

@@ -0,0 +1 @@
+export { createDataPlane, createHealthCheckJob } from "./data-planes";

package/build/testing/handlers/data-planes.d.ts

@@ -0,0 +1,4 @@
+import type { HttpHandler } from "msw";
+import type { AuthGuard, DataPlaneResponse } from "../types";
+import type { OpenApiHttp } from "./openapi-http";
+export declare function createDataPlaneHandlers(http: OpenApiHttp, auth: AuthGuard, seed?: DataPlaneResponse[]): HttpHandler[];

package/build/testing/handlers/data-planes.js

@@ -0,0 +1,69 @@
+import { rejectUnauthenticated } from "../auth";
+import { createDataPlane, createHealthCheckJob } from "../fixtures/data-planes";
+/**
+ * Records live for the lifetime of one `createHandlers()` call, so each test
+ * suite gets its own copy and writes from one test can't leak into another.
+ */
+function createStore(seed) {
+    const records = seed.map((record) => ({ ...record }));
+    return {
+        list: () => records,
+        find: (id) => records.find((record) => record.id === id),
+    };
+}
+/** The default-compute-pool endpoints exist only for data planes we own. */
+function findOwned(store, id) {
+    const record = store.find(id);
+    return record?.type === "owned" ? record : undefined;
+}
+export function createDataPlaneHandlers(http, auth, seed = [createDataPlane()]) {
+    const store = createStore(seed);
+    return [
+        http.get("/data-planes", ({ request, cookies, response }) => {
+            const unauthorized = rejectUnauthenticated(auth, { request, cookies });
+            if (unauthorized)
+                return response.untyped(unauthorized);
+            return response(200).json({ records: store.list() });
+        }),
+        http.get("/data-planes/{data_plane_id}", ({ params, request, cookies, response }) => {
+            const unauthorized = rejectUnauthenticated(auth, { request, cookies });
+            if (unauthorized)
+                return response.untyped(unauthorized);
+            const record = store.find(params.data_plane_id);
+            return record ? response(200).json(record) : response(404).empty();
+        }),
+        http.put("/data-planes/{data_plane_id}/default-compute-pool/{compute_pool_id}", ({ params, request, cookies, response }) => {
+            const unauthorized = rejectUnauthenticated(auth, { request, cookies });
+            if (unauthorized)
+                return response.untyped(unauthorized);
+            const record = findOwned(store, params.data_plane_id);
+            if (!record)
+                return response(404).empty();
+            record.default_compute_pool_id = params.compute_pool_id;
+            return response(200).json(record);
+        }),
+        http.delete("/data-planes/{data_plane_id}/default-compute-pool", ({ params, request, cookies, response }) => {
+            const unauthorized = rejectUnauthenticated(auth, { request, cookies });
+            if (unauthorized)
+                return response.untyped(unauthorized);
+            const record = findOwned(store, params.data_plane_id);
+            if (!record)
+                return response(404).empty();
+            record.default_compute_pool_id = undefined;
+            return response(200).json(record);
+        }),
+        http.post("/data-planes/{data_plane_id}/health-check", async ({ params, request, cookies, response }) => {
+            const unauthorized = rejectUnauthenticated(auth, { request, cookies });
+            if (unauthorized)
+                return response.untyped(unauthorized);
+            const record = store.find(params.data_plane_id);
+            if (!record)
+                return response(404).empty();
+            const body = await request.json();
+            return response(201).json(createHealthCheckJob({
+                data_plane_id: params.data_plane_id,
+                compute_pool_id: body?.compute_pool_id,
+            }));
+        }),
+    ];
+}

package/build/testing/handlers/index.d.ts

@@ -0,0 +1,10 @@
+import type { HttpHandler } from "msw";
+import type { CreateHandlersOptions } from "../types";
+/**
+ * Builds the request handlers for a mock Narrative API.
+ *
+ * Pass the result to msw's `setupServer` in tests or `setupWorker` in a browser
+ * dev mode. Each call gets its own record store, so handlers from one suite
+ * never see another's writes.
+ */
+export declare function createHandlers(options?: CreateHandlersOptions): HttpHandler[];

package/build/testing/handlers/index.js

@@ -0,0 +1,16 @@
+import { createDataPlaneHandlers } from "./data-planes";
+import { createHttp } from "./openapi-http";
+/** Matches `BaseApi`'s default environment, so the common case needs no options. */
+const DEFAULT_BASE_URL = "https://api.narrative.io";
+/**
+ * Builds the request handlers for a mock Narrative API.
+ *
+ * Pass the result to msw's `setupServer` in tests or `setupWorker` in a browser
+ * dev mode. Each call gets its own record store, so handlers from one suite
+ * never see another's writes.
+ */
+export function createHandlers(options = {}) {
+    const { baseUrl = DEFAULT_BASE_URL, auth = false, dataPlanes } = options;
+    const http = createHttp(baseUrl);
+    return [...createDataPlaneHandlers(http, auth, dataPlanes)];
+}

package/build/testing/handlers/openapi-http.d.ts

@@ -0,0 +1,10 @@
+import { createOpenApiHttp } from "openapi-msw";
+import type { paths } from "../../generated/api-types";
+/** The openapi-msw builder, bound to the generated spec. */
+export type OpenApiHttp = ReturnType<typeof createOpenApiHttp<paths>>;
+/**
+ * openapi-msw joins `baseUrl` to a path that already starts with a slash, so a
+ * trailing slash produces a double slash and every handler quietly stops
+ * matching. `BaseApi#getBaseUrl` returns one, which makes this worth guarding.
+ */
+export declare function createHttp(baseUrl: string): OpenApiHttp;

package/build/testing/handlers/openapi-http.js

@@ -0,0 +1,9 @@
+import { createOpenApiHttp } from "openapi-msw";
+/**
+ * openapi-msw joins `baseUrl` to a path that already starts with a slash, so a
+ * trailing slash produces a double slash and every handler quietly stops
+ * matching. `BaseApi#getBaseUrl` returns one, which makes this worth guarding.
+ */
+export function createHttp(baseUrl) {
+    return createOpenApiHttp({ baseUrl: baseUrl.replace(/\/+$/, "") });
+}

package/build/testing/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typed MSW handlers for the Narrative API, generated against the same OpenAPI
+ * spec the client is checked against.
+ *
+ * Requires `msw` and `openapi-msw`, which are optional peer dependencies —
+ * install them to use this entry point.
+ *
+ * ```ts
+ * import { setupServer } from "msw/node";
+ * import { createHandlers, createDataPlane } from "@narrative.io/data-collaboration-sdk-ts/testing";
+ *
+ * const server = setupServer(...createHandlers({ dataPlanes: [createDataPlane()] }));
+ * ```
+ */
+export { createDataPlane, createHealthCheckJob } from "./fixtures";
+export { createHandlers } from "./handlers";
+export { createDataPlaneHandlers } from "./handlers/data-planes";
+export type { AuthGuard, AuthGuardContext, CreateHandlersOptions, DataPlaneOwnedResponse, DataPlaneResponse, JobResponse, } from "./types";

package/build/testing/index.js

@@ -0,0 +1,17 @@
+/**
+ * Typed MSW handlers for the Narrative API, generated against the same OpenAPI
+ * spec the client is checked against.
+ *
+ * Requires `msw` and `openapi-msw`, which are optional peer dependencies —
+ * install them to use this entry point.
+ *
+ * ```ts
+ * import { setupServer } from "msw/node";
+ * import { createHandlers, createDataPlane } from "@narrative.io/data-collaboration-sdk-ts/testing";
+ *
+ * const server = setupServer(...createHandlers({ dataPlanes: [createDataPlane()] }));
+ * ```
+ */
+export { createDataPlane, createHealthCheckJob } from "./fixtures";
+export { createHandlers } from "./handlers";
+export { createDataPlaneHandlers } from "./handlers/data-planes";

package/build/testing/types.d.ts

@@ -0,0 +1,39 @@
+import type { components } from "../generated/api-types";
+/** A data plane as the API returns it, owned or shared. */
+export type DataPlaneResponse = components["schemas"]["DataPlaneResponse"];
+/** A data plane this company owns. Only owned planes have a default compute pool. */
+export type DataPlaneOwnedResponse = components["schemas"]["DataPlaneOwnedResponse"];
+/** A job as the API returns it, including the one a health check enqueues. */
+export type JobResponse = components["schemas"]["JobResponse"];
+export interface AuthGuardContext {
+    request: Request;
+    /** Cookies msw parsed off the request. */
+    cookies: Record<string, string>;
+}
+/**
+ * How handlers decide whether a request is authenticated.
+ *
+ * `false` accepts everything, which is what SDK tests want. A bearer or cookie
+ * guard omitting its `token`/`value` accepts any non-empty credential, so a
+ * test can assert that the client sends one without pinning its value.
+ */
+export type AuthGuard = false | {
+    type: "bearer";
+    token?: string;
+} | {
+    type: "cookie";
+    name: string;
+    value?: string;
+} | ((context: AuthGuardContext) => boolean);
+export interface CreateHandlersOptions {
+    /**
+     * Origin the handlers match against, without a trailing slash. Note that
+     * `BaseApi#getBaseUrl` returns one with a trailing slash, so pass the origin
+     * rather than that value — or let this default, which matches the client's
+     * own default environment.
+     */
+    baseUrl?: string;
+    auth?: AuthGuard;
+    /** Seeds the in-memory data planes the handlers read and write. */
+    dataPlanes?: DataPlaneResponse[];
+}

package/build/testing/types.js

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

package/package.json

@@ -1,22 +1,77 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "4.1.0",
+	"version": "4.3.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
 	"types": "build/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./build/index.d.ts",
+			"default": "./build/index.js"
+		},
+		"./testing": {
+			"types": "./build/testing/index.d.ts",
+			"default": "./build/testing/index.js"
+		},
+		"./build/access-rules": "./build/access-rules/index.js",
+		"./build/access-tokens": "./build/access-tokens/index.js",
+		"./build/agents": "./build/agents/index.js",
+		"./build/apps": "./build/apps/index.js",
+		"./build/attributes": "./build/attributes/index.js",
+		"./build/authentication": "./build/authentication/index.js",
+		"./build/collaboration-policy": "./build/collaboration-policy/index.js",
+		"./build/companies": "./build/companies/index.js",
+		"./build/company-info": "./build/company-info/index.js",
+		"./build/compute-pools": "./build/compute-pools/index.js",
+		"./build/connections": "./build/connections/index.js",
+		"./build/contracts": "./build/contracts/index.js",
+		"./build/data-planes": "./build/data-planes/index.js",
+		"./build/data-streams": "./build/data-streams/index.js",
+		"./build/datasets": "./build/datasets/index.js",
+		"./build/encryption-materials": "./build/encryption-materials/index.js",
+		"./build/forecast": "./build/forecast/index.js",
+		"./build/health": "./build/health/index.js",
+		"./build/installations": "./build/installations/index.js",
+		"./build/jobs": "./build/jobs/index.js",
+		"./build/json-big-number": "./build/json-big-number/index.js",
+		"./build/mappings": "./build/mappings/index.js",
+		"./build/mcp-connections": "./build/mcp-connections/index.js",
+		"./build/model-inference": "./build/model-inference/index.js",
+		"./build/model-training": "./build/model-training/index.js",
+		"./build/models": "./build/models/index.js",
+		"./build/nql": "./build/nql/index.js",
+		"./build/ping": "./build/ping/index.js",
+		"./build/products": "./build/products/index.js",
+		"./build/queries": "./build/queries/index.js",
+		"./build/resources": "./build/resources/index.js",
+		"./build/rosetta-stone": "./build/rosetta-stone/index.js",
+		"./build/subscriptions": "./build/subscriptions/index.js",
+		"./build/testing": "./build/testing/index.js",
+		"./build/uploads": "./build/uploads/index.js",
+		"./build/views": "./build/views/index.js",
+		"./build/whoami": "./build/whoami/index.js",
+		"./build/workflows": "./build/workflows/index.js",
+		"./build/*": [
+			"./build/*.js",
+			"./build/*/index.js",
+			"./build/*"
+		],
+		"./package.json": "./package.json"
+	},
 	"description": "",
 	"packageManager": "bun@1.2.21",
 	"scripts": {
 		"build": "tsc",
 		"lint": "bunx @biomejs/biome check --write ./src",
 		"prepare": "bunx @biomejs/biome check --write ./src && bun run build",
-		"prepublishOnly": "bun run test && bun run lint",
+		"prepublishOnly": "bun run test && bun run lint && bun run check:built",
 		"preversion": "bun run lint",
 		"version": "bun run && git add -A src",
 		"postversion": "git push && git push --tags",
 		"test": "jest --coverage",
 		"dev": "tsc -w",
+		"generate:api-types": "bun scripts/generate-api-types.ts",
 		"check:built": "node scripts/ensureBuild.js",
 		"link:global": "bun run check:built && bun link",
 		"pack:dist": "bun run check:built && bun pm pack",
@@ -38,6 +93,9 @@
 		"babel-jest": "30.4.1",
 		"jest": "30.4.2",
 		"lefthook": "2.1.10",
+		"msw": "2.15.0",
+		"openapi-msw": "2.0.0",
+		"openapi-typescript": "7.13.0",
 		"ts-jest": "29.4.12",
 		"typescript": "6.0.0-dev.20260416"
 	},
@@ -45,6 +103,18 @@
 		"zod": "4.4.3",
 		"bignumber.js": "11.1.5"
 	},
+	"peerDependencies": {
+		"msw": "^2.10.5",
+		"openapi-msw": "^2.0.0"
+	},
+	"peerDependenciesMeta": {
+		"msw": {
+			"optional": true
+		},
+		"openapi-msw": {
+			"optional": true
+		}
+	},
 	"overrides": {
 		"semver@<7.5.2": "7.5.2"
 	},