@narrative.io/data-collaboration-sdk-ts 4.2.0 → 4.3.1

package/README.md

@@ -13,6 +13,7 @@ The official TypeScript SDK for the Narrative.io Data Collaboration Platform. Th
 - [Configuration](#configuration)
 - [TypeScript Support](#typescript-support)
 - [Error Handling](#error-handling)
+- [Testing with Mock Handlers](#testing-with-mock-handlers)
 - [API Reference](#api-reference)
 - [Contributing](#contributing)
 - [License](#license)
@@ -385,6 +386,75 @@ const narrative = new NarrativeApi({
 });
 ```
 
+## Testing with Mock Handlers
+
+The `testing` subpath ships [MSW](https://mswjs.io) request handlers generated against the
+same OpenAPI spec this SDK is checked against, so your mocks can't drift from what the client
+actually puts on the wire.
+
+`msw` and `openapi-msw` are optional peer dependencies — install both to use this entry point:
+
+```bash
+bun add -d msw openapi-msw
+```
+
+```typescript
+import { setupServer } from 'msw/node';
+import { createHandlers, createDataPlane } from '@narrative.io/data-collaboration-sdk-ts/testing';
+import { DataPlaneApi } from '@narrative.io/data-collaboration-sdk-ts';
+
+const server = setupServer(
+  ...createHandlers({
+    dataPlanes: [createDataPlane({ display_name: 'Primary' })],
+  }),
+);
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterAll(() => server.close());
+
+it('lists data planes', async () => {
+  const { records } = await new DataPlaneApi({ apiKey: 'test' }).getDataPlanes();
+  expect(records[0].display_name).toBe('Primary');
+});
+```
+
+`createHandlers` takes three options, all optional:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `baseUrl` | `https://api.narrative.io` | Origin the handlers match. Pass the **origin**, not `getBaseUrl()` — that returns a trailing slash. |
+| `auth` | `false` | Reject unauthenticated requests with a 401. See below. |
+| `dataPlanes` | one default record | Seeds the in-memory records the handlers read and write. |
+
+Each call gets its own copy of the seed records, so writes in one suite never leak into
+another. Handlers back a small read/write model rather than fixed responses: setting a
+data plane's default compute pool is visible on the next read, and an unknown id returns
+a 404 (which the client surfaces as a thrown `HttpError`).
+
+The auth guard is off by default. Turn it on to assert that your code sends credentials —
+it accepts a bearer token, a cookie, or your own predicate, and the same handlers then work
+for both test servers and a browser dev-mode worker:
+
+```typescript
+createHandlers({ auth: { type: 'bearer' } });                    // any non-empty token
+createHandlers({ auth: { type: 'bearer', token: 'expected' } }); // that exact token
+createHandlers({ auth: { type: 'cookie', name: 'session' } });
+createHandlers({ auth: ({ request }) => request.headers.has('X-My-Header') });
+```
+
+Coverage currently spans the data-planes endpoints; more modules follow.
+
+**Using Jest?** MSW's CommonJS build reaches a few ESM-only packages, so they need to be
+transformed rather than ignored:
+
+```js
+// jest.config.js
+transform: { '\\.[cm]?[jt]sx?$': 'babel-jest' },
+transformIgnorePatterns: [
+  '/node_modules/(?!.*(?:openapi-msw|rettime|until-async|@open-draft/deferred-promise)/)',
+],
+```
+
 ## API Reference
 
 For detailed API documentation, please visit the [Narrative.io API Documentation](https://api.narrative.dev).
@@ -465,6 +535,6 @@ bun add @narrative.io/data-collaboration-sdk-ts             # or @<semver>
 
 - **Build artifacts not updating:** Ensure `bun run dev` is running in the SDK repo (TypeScript watch), and that the app is linked (or reinstalled from a fresh tarball).
 
-- **Accidental imports from `src/*`:** Consumers should import from the package root only. This SDK publishes `build/**` and defines `main`/`types` (and may include an `exports` map) to prevent `src/*` imports.
+- **Accidental imports from `src/*`:** Consumers should import from the package root only. This SDK publishes `build/**` and defines both `main`/`types` and an `exports` map, so `src/*` is unreachable. The map keeps the existing `build/*` deep-import paths working: each built module directory has its own entry, because Vite turns off directory/index resolution for any package that declares `exports`.
 
 - **Type/version drift (e.g., Zod):** If your app and the SDK use different major versions of a library whose types appear in public APIs, align versions or declare that library as a `peerDependency` in the SDK.

package/build/data-planes/types.d.ts

@@ -38,10 +38,11 @@ export interface SnowflakePlatform {
     account_name: string;
     organization_name: string;
     /**
-     * Optional: the platform can fail to parse a region when provisioning the
-     * Snowflake Native App. Informational only.
+     * The platform can fail to parse a region when provisioning the Snowflake
+     * Native App, so this is informational only. Responses always carry the key,
+     * with an explicit `null` when there is no region.
      */
-    region?: DataPlaneRegion;
+    region?: DataPlaneRegion | null;
 }
 /** Platform details returned for a data plane the calling company owns. */
 export type DataPlanePlatform = AwsPlatform | SnowflakePlatform;
@@ -51,7 +52,8 @@ export interface AwsSharedPlatform {
 }
 export interface SnowflakeSharedPlatform {
     type: "platform_shared_snowflake";
-    region?: DataPlaneRegion;
+    /** Nullable for the same reason as {@link SnowflakePlatform.region}. */
+    region?: DataPlaneRegion | null;
 }
 /**
  * Platform details returned for a data plane shared with you. Account
@@ -84,11 +86,21 @@ export interface DataPlaneOwnedResponse {
     status: DataPlaneStatus;
     updated_at: string;
     collaborators: DataPlaneCollaborators;
+    /**
+     * Always present, empty when the plane has no pools: the backend field is a
+     * plain `List`, never an `Option`.
+     */
     compute_pools: ComputePoolResponse[];
-    description?: string;
-    tags?: string[];
-    last_heartbeat_at?: string;
-    default_compute_pool_id?: string;
+    /**
+     * The response encoder does not drop nulls, so each of these four arrives as
+     * an explicit `null` when absent rather than being left out. `tags` is `null`
+     * for a plane with no tags too — `DataPlaneResponse.apply` maps an empty list
+     * to `None` — though a directly constructed response can still send `[]`.
+     */
+    description?: string | null;
+    tags?: string[] | null;
+    last_heartbeat_at?: string | null;
+    default_compute_pool_id?: string | null;
 }
 /**
  * A data plane shared with the calling company. Omits details like the external
@@ -104,11 +116,13 @@ export interface DataPlaneSharedResponse {
     platform: DataPlaneSharedPlatform;
     status: DataPlaneStatus;
     updated_at: string;
+    /** Required for the same reason as {@link DataPlaneOwnedResponse.compute_pools}. */
     compute_pools: ComputePoolResponse[];
-    description?: string;
-    tags?: string[];
-    last_heartbeat_at?: string;
-    default_compute_pool_id?: string;
+    /** Nullable for the same reason as on {@link DataPlaneOwnedResponse}. */
+    description?: string | null;
+    tags?: string[] | null;
+    last_heartbeat_at?: string | null;
+    default_compute_pool_id?: string | null;
 }
 /** Discriminated union of the owned/shared data plane response shapes. */
 export type DataPlane = DataPlaneOwnedResponse | DataPlaneSharedResponse;