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

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.