@antasphere/chassis-sdk 0.0.0-stage → 1.0.1

package/test/defaults.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_DOWNLOAD_TIMEOUT_MS, DEFAULT_TIMEOUT_MS } from '../src/index.js';
+
+/**
+ * The default deadlines, as literals (PRDCT-2530, verifier M19). The timeout
+ * tests compare a call's signal against these same constants, so a changed
+ * value moves with them; a number a person waits on is pinned by its value.
+ */
+describe('chassis client default deadlines', () => {
+  it('30 s a request, 10 min a download', () => {
+    expect(DEFAULT_TIMEOUT_MS).toBe(30_000);
+    expect(DEFAULT_DOWNLOAD_TIMEOUT_MS).toBe(600_000);
+  });
+});

package/test/demo-redeem.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { ChassisClient, PlatformApiError } from '../src/index.js';
+
+/**
+ * The demo pass redeem is an endpoint of the sign-in library
+ * (`/api/v1/auth/demo/redeem`), so it has no route contract and the route
+ * coverage guard cannot see it (the same stance as `signInEmail`). This pins
+ * its method, its path and its body by hand.
+ */
+
+function recordingClient(answer: Response) {
+  const calls: Array<{ method: string; path: string; body: unknown; credentials: unknown }> = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(typeof input === 'string' ? input : input.toString(), 'http://x');
+    calls.push({
+      method: (init?.method ?? 'GET').toUpperCase(),
+      path: url.pathname,
+      body: typeof init?.body === 'string' ? JSON.parse(init.body) : undefined,
+      credentials: init?.credentials
+    });
+    return answer;
+  }) as typeof globalThis.fetch;
+  return { client: new ChassisClient<'things:read'>({ fetch }), calls };
+}
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+describe('redeemDemoPass', () => {
+  it('posts the secret as `pass` to the sign-in library, same-origin, and answers the person', async () => {
+    const answer = {
+      user: { id: 'u1', email: 'a@example.com', name: 'A' },
+      path: '/decks',
+      expiresAt: '2026-09-28T00:00:00.000Z'
+    };
+    const { client, calls } = recordingClient(json(200, answer));
+    await expect(client.redeemDemoPass('s3cr3t')).resolves.toEqual(answer);
+    expect(calls).toEqual([
+      {
+        method: 'POST',
+        path: '/api/v1/auth/demo/redeem',
+        body: { pass: 's3cr3t' },
+        credentials: 'same-origin'
+      }
+    ]);
+  });
+
+  it('turns the one refusal into a PlatformApiError carrying its code', async () => {
+    const { client } = recordingClient(
+      json(401, { error: { code: 'invalid_demo_pass', message: 'This demo link is not valid' } })
+    );
+    const refused = await client.redeemDemoPass('nope').catch((err: unknown) => err);
+    expect(refused).toBeInstanceOf(PlatformApiError);
+    expect(refused).toMatchObject({ status: 401, code: 'invalid_demo_pass' });
+  });
+});

package/test/download-headers.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { ChassisClient, PlatformApiError } from '../src/index.js';
+
+/**
+ * PRDCT-2426: a download is a request like any other, so it carries the
+ * active workspace. A browser anchor cannot send `X-Workspace-Id`, which is
+ * why a dashboard downloads through these methods: each of them must put the
+ * header on the wire, or a file of a non-default workspace answers 404.
+ * (The generic downloads; the tool SDK judges its own on its own class.)
+ */
+
+const FILE = '33333333-3333-3333-3333-333333333333';
+const WORKSPACE = '44444444-4444-4444-4444-444444444444';
+type Client = ChassisClient<'things:read'>;
+
+function recordingClient() {
+  const calls: { url: string; init: RequestInit }[] = [];
+  const fetchImpl = (async (input: unknown, init?: RequestInit) => {
+    calls.push({ url: String(input), init: init ?? {} });
+    return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+  }) as typeof globalThis.fetch;
+  const client: Client = new ChassisClient({ baseUrl: 'http://x', fetch: fetchImpl, workspaceId: WORKSPACE });
+  return { client, calls };
+}
+
+const DOWNLOADS: Record<string, [(c: Client) => Promise<Response>, string]> = {
+  downloadFileContent: [(c) => c.downloadFileContent(FILE), `/api/v1/files/${FILE}/content`],
+  downloadExport: [(c) => c.downloadExport(), '/api/v1/workspace/export']
+};
+
+describe('chassis client downloads carry the active workspace', () => {
+  it.each(Object.entries(DOWNLOADS))('%s', async (_name, [call, path]) => {
+    const { client, calls } = recordingClient();
+    await call(client);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe(`http://x${path}`);
+    expect((calls[0]!.init.headers as Record<string, string>)['x-workspace-id']).toBe(WORKSPACE);
+  });
+
+  it('percent-encodes the file id: no path or query break-out', async () => {
+    const { client, calls } = recordingClient();
+    await client.downloadFileContent('../f?x#1');
+    expect(calls[0]!.url).toBe('http://x/api/v1/files/..%2Ff%3Fx%231/content');
+  });
+
+  it('follows setWorkspace, and sends no header once it is cleared', async () => {
+    const { client, calls } = recordingClient();
+    client.setWorkspace('other');
+    await client.downloadFileContent(FILE);
+    client.setWorkspace(null);
+    await client.downloadFileContent(FILE);
+    expect((calls[0]!.init.headers as Record<string, string>)['x-workspace-id']).toBe('other');
+    expect((calls[1]!.init.headers as Record<string, string>)['x-workspace-id']).toBeUndefined();
+  });
+
+  it('a refusal throws the wire error instead of handing back a body to save', async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ error: { code: 'not_found', message: 'File not found' } }), {
+        status: 404,
+        headers: { 'content-type': 'application/json' }
+      })) as typeof globalThis.fetch;
+    const client: Client = new ChassisClient({ baseUrl: 'http://x', fetch: fetchImpl });
+    for (const call of [() => client.downloadFileContent(FILE), () => client.downloadExport()]) {
+      const error = await call().then(
+        () => null,
+        (e: unknown) => e
+      );
+      expect(error).toBeInstanceOf(PlatformApiError);
+      expect(error).toMatchObject({ name: 'PlatformApiError', status: 404, code: 'not_found' });
+    }
+  });
+});

package/test/extra-headers.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { ChassisClient, type ClientOptions } from '../src/index.js';
+
+/**
+ * `headers` rides on every call, and it never stands in for a credential:
+ * a client given no key sends no `authorization` at all (the CLI's owner
+ * session holds a cookie and must never look like a machine caller), and a
+ * client given a key keeps its own bearer whatever the caller passed.
+ */
+
+function recordingClient(options: ClientOptions = {}) {
+  const sent: Array<Record<string, string>> = [];
+  const fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
+    sent.push({ ...(init?.headers as Record<string, string>) });
+    return new Response(JSON.stringify({ passes: [] }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' }
+    });
+  }) as typeof globalThis.fetch;
+  return { client: new ChassisClient<'things:read'>({ ...options, fetch }), sent };
+}
+
+describe('ClientOptions.headers', () => {
+  it('sends the given headers on every call, and no authorization when no key is given', async () => {
+    const { client, sent } = recordingClient({
+      baseUrl: 'http://x',
+      headers: { cookie: 'a.session_token=v', origin: 'http://x' }
+    });
+    await client.demoPasses();
+    await client.mintDemoPass({ email: 'ada@example.com' });
+    expect(sent).toHaveLength(2);
+    for (const headers of sent) {
+      expect(headers['cookie']).toBe('a.session_token=v');
+      expect(headers['origin']).toBe('http://x');
+      expect(headers).not.toHaveProperty('authorization');
+    }
+  });
+
+  it('never lets a given header replace the key', async () => {
+    const { client, sent } = recordingClient({
+      apiKey: 'k_1_s',
+      headers: { authorization: 'Bearer forged', 'x-extra': '1' }
+    });
+    await client.demoPasses();
+    expect(sent[0]!['authorization']).toBe('Bearer k_1_s');
+    expect(sent[0]!['x-extra']).toBe('1');
+  });
+});

package/test/route-coverage.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'vitest';
+import { defineChassisContract } from '@antasphere/chassis-contract';
+import * as chassisRoutes from '@antasphere/chassis-contract/routes';
+import { ChassisClient } from '../src/index.js';
+
+/**
+ * Chassis client ↔ chassis contract drift guard, the generic half of the
+ * tool SDK's own route-coverage test. Request/response SHAPES already fail
+ * typecheck; this closes the remaining gap: the method + path string literals
+ * inside each client method.
+ *
+ * The scope-carrying routes are instantiated with scopes that are NOT any real
+ * tool's (`things:*`), so the chassis stays honest about never spelling one.
+ *
+ * Better Auth wrapper methods (session/signInEmail/signOut) call /auth/* and
+ * are intentionally NOT in the contract; they are excluded below.
+ */
+
+const contract = defineChassisContract({ scopes: ['things:read', 'things:write'] });
+const scopedRoutes = chassisRoutes.defineChassisRoutes(
+  contract,
+  { cliKeyScopesLabel: 'things:read+write', scopes: { dataExport: 'things:export' } },
+  { fileInUseOpenApi: 'file_in_use: referenced by a thing' }
+);
+type ThingsScope = 'things:read' | 'things:write';
+type Client = ChassisClient<ThingsScope>;
+
+const SAMPLE_ID = '11111111-1111-1111-1111-111111111111';
+const SAMPLE_TOKEN = 'x'.repeat(24);
+
+/** contract route → a client call. Keyed by `METHOD path` (contract shape). */
+/** A Better Auth user id: text, never a uuid. */
+const SAMPLE_USER_ID = 'usr_projects_coverage';
+const SAMPLE_TEAM_ID = '7b0c3d1e-2f4a-4b6c-8d9e-0f1a2b3c4d5e';
+
+const INVOKERS: Record<string, (c: Client) => Promise<unknown>> = {
+  'GET /instance': (c) => c.instance(),
+  'POST /setup': (c) =>
+    c.setup({
+      instanceName: 'X',
+      owner: { email: 'a@b.co', name: 'A', password: 'x'.repeat(12) }
+    }),
+  'GET /me': (c) => c.me(),
+  'POST /me/onboarding/dismiss': (c) => c.dismissOnboarding(),
+  'PUT /me/default-workspace': (c) => c.setDefaultWorkspace(SAMPLE_ID),
+  'POST /workspaces': (c) => c.createWorkspace('Second'),
+  'POST /sso/logout': (c) => c.ssoLogout(),
+  'POST /cli/auth/request': (c) => c.cliAuthRequest({ email: 'a@b.co' }),
+  'POST /cli/auth/complete': (c) => c.cliAuthComplete({ email: 'a@b.co', otp: '123456' }),
+  'DELETE /cli/auth/key': (c) => c.cliAuthRevoke(),
+  'POST /sso/cli-connect': (c) => c.ssoCliConnect({ token: SAMPLE_TOKEN }),
+  'GET /members': (c) => c.members(),
+  'PATCH /members/{id}': (c) => c.updateMember(SAMPLE_ID, { role: 'admin' }),
+  'DELETE /members/{id}': (c) => c.deleteMember(SAMPLE_ID),
+  'POST /members/{id}/remove': (c) => c.removeMember(SAMPLE_ID),
+  'POST /members/{id}/reset-link': (c) => c.createMemberResetLink(SAMPLE_ID),
+  'POST /members/{id}/change-email-link': (c) =>
+    c.createMemberChangeEmailLink(SAMPLE_ID, { newEmail: 'a@b.co' }),
+  'GET /projects': (c) => c.projects(),
+  'POST /projects': (c) => c.createProject({ name: 'P' }),
+  'GET /projects/{id}': (c) => c.project(SAMPLE_ID),
+  'PATCH /projects/{id}': (c) => c.updateProject(SAMPLE_ID, { name: 'P' }),
+  'POST /projects/{id}/archive': (c) => c.archiveProject(SAMPLE_ID),
+  'POST /projects/{id}/unarchive': (c) => c.unarchiveProject(SAMPLE_ID),
+  'GET /projects/{id}/members': (c) => c.projectMembers(SAMPLE_ID),
+  'POST /projects/{id}/members': (c) => c.addProjectMember(SAMPLE_ID, { email: 'a@b.co', role: 'viewer' }),
+  'PATCH /projects/{id}/members/{userId}': (c) => c.setProjectMemberRole(SAMPLE_ID, SAMPLE_USER_ID, 'editor'),
+  'DELETE /projects/{id}/members/{userId}': (c) => c.removeProjectMember(SAMPLE_ID, SAMPLE_USER_ID),
+  'PATCH /projects/{id}/teams/{teamId}': (c) => c.setProjectTeamRole(SAMPLE_ID, SAMPLE_TEAM_ID, 'editor'),
+  'DELETE /projects/{id}/teams/{teamId}': (c) => c.removeProjectTeam(SAMPLE_ID, SAMPLE_TEAM_ID),
+  'GET /teams': (c) => c.teams(),
+  'GET /teams/{id}': (c) => c.team(SAMPLE_ID),
+  'POST /teams': (c) => c.createTeam({ name: 'Design' }),
+  'PATCH /teams/{id}': (c) => c.updateTeam(SAMPLE_ID, { name: 'Design' }),
+  'DELETE /teams/{id}': (c) => c.deleteTeam(SAMPLE_ID),
+  'GET /teams/{id}/members': (c) => c.teamMembers(SAMPLE_ID),
+  'POST /teams/{id}/members': (c) => c.addTeamMember(SAMPLE_ID, { email: 'a@b.co' }),
+  'DELETE /teams/{id}/members/{userId}': (c) => c.removeTeamMember(SAMPLE_ID, SAMPLE_USER_ID),
+  'GET /demo/passes': (c) => c.demoPasses(),
+  'POST /demo/passes': (c) => c.mintDemoPass({ email: 'a@example.com' }),
+  'DELETE /demo/passes/{id}': (c) => c.revokeDemoPass(SAMPLE_ID),
+  'GET /api-keys': (c) => c.apiKeys(),
+  'POST /api-keys': (c) => c.createApiKey({ name: 'k', scopes: ['things:read'] }),
+  'DELETE /api-keys/{id}': (c) => c.revokeApiKey(SAMPLE_ID),
+  'PATCH /workspace': (c) => c.updateWorkspace({ name: 'Acme' }),
+  'GET /invitations': (c) => c.invitations(),
+  'POST /invitations': (c) => c.createInvitation({ email: 'a@b.co', role: 'member' }),
+  'DELETE /invitations/{id}': (c) => c.revokeInvitation(SAMPLE_ID),
+  'GET /invitations/lookup': (c) => c.lookupInvitation(SAMPLE_TOKEN),
+  'POST /invitations/accept': (c) => c.acceptInvitation({ token: SAMPLE_TOKEN }),
+  'POST /admin/break-glass/claim-ownership': (c) => c.breakGlassClaimOwnership(),
+  'POST /admin/break-glass/reset-2fa': (c) => c.breakGlassResetTwoFactor({ userId: SAMPLE_ID }),
+  'GET /audit': (c) => c.audit(),
+  'GET /workspace/export': (c) => c.downloadExport(),
+  'GET /files': (c) => c.files(),
+  'GET /files/{id}': (c) => c.file(SAMPLE_ID),
+  'POST /files': (c) => c.uploadFile('n.txt', new Uint8Array([1])),
+  'DELETE /files/{id}': (c) => c.deleteFile(SAMPLE_ID)
+};
+
+interface ContractRoute {
+  method: string;
+  path: string;
+}
+
+function contractRoutes(): Array<{ key: string; method: string; path: string }> {
+  // Both halves of the chassis routes: the static ones, then the ones
+  // instantiated with the test tool's scopes.
+  return [
+    ...Object.values(chassisRoutes as Record<string, unknown>),
+    ...Object.values(scopedRoutes as Record<string, unknown>)
+  ]
+    .filter((r): r is ContractRoute => {
+      const o = r as Partial<ContractRoute>;
+      return typeof o?.method === 'string' && typeof o?.path === 'string';
+    })
+    .map((r) => ({
+      key: `${r.method.toUpperCase()} ${r.path}`,
+      method: r.method.toUpperCase(),
+      path: r.path
+    }));
+}
+
+/** Records the (method, pathname) of the single request a client call makes. */
+function recordingClient(): { client: Client; calls: Array<{ method: string; path: string }> } {
+  const calls: Array<{ method: string; path: string }> = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(typeof input === 'string' ? input : input.toString(), 'http://x');
+    calls.push({ method: (init?.method ?? 'GET').toUpperCase(), path: url.pathname });
+    return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as typeof globalThis.fetch;
+  return { client: new ChassisClient<ThingsScope>({ fetch }), calls };
+}
+
+/** The contract path with every param substituted, to compare against the client's real path. */
+function expectedPath(contractPath: string): string {
+  return `/api/v1${contractPath
+    .replace('{id}', SAMPLE_ID)
+    .replace('{userId}', SAMPLE_USER_ID)
+    .replace('{teamId}', SAMPLE_TEAM_ID)}`;
+}
+
+describe('chassis client route coverage (contract drift guard)', () => {
+  const all = contractRoutes();
+
+  it('sees both halves of the chassis routes', () => {
+    expect(all.length).toBe(Object.keys(INVOKERS).length);
+    expect(all.map((r) => r.key)).toContain('GET /me');
+    expect(all.map((r) => r.key)).toContain('GET /instance');
+  });
+
+  it('maps every chassis route to a client method', () => {
+    const missing = all.filter((r) => !(r.key in INVOKERS)).map((r) => r.key);
+    expect(missing, `contract routes without a client method: ${missing.join(', ')}`).toEqual([]);
+  });
+
+  it('has no stale mappings (every mapping targets a real contract route)', () => {
+    const keys = new Set(all.map((r) => r.key));
+    const stale = Object.keys(INVOKERS).filter((k) => !keys.has(k));
+    expect(stale, `INVOKERS entries with no matching contract route: ${stale.join(', ')}`).toEqual([]);
+  });
+
+  for (const route of contractRoutes()) {
+    it(`${route.key} hits the right method + path`, async () => {
+      const invoke = INVOKERS[route.key];
+      if (!invoke) return; // coverage asserted separately
+      const { client, calls } = recordingClient();
+      await invoke(client);
+      expect(calls).toHaveLength(1);
+      expect(calls[0]!.method).toBe(route.method);
+      expect(calls[0]!.path).toBe(expectedPath(route.path));
+    });
+  }
+});

package/test/timeout.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { ChassisClient, DEFAULT_DOWNLOAD_TIMEOUT_MS, DEFAULT_TIMEOUT_MS } from '../src/index.js';
+
+/**
+ * PRDCT-1353 / CLI-10 — `fetch` has no default timeout anywhere. Without an
+ * AbortSignal a silent (or deliberately stalling) instance parks the caller
+ * forever. Every call the chassis client makes must carry one. (The tool SDK
+ * keeps the same cases on its own class; these judge the generic half alone.)
+ */
+
+function recordingClient(overrides: { timeoutMs?: number; downloadTimeoutMs?: number } = {}) {
+  const inits: RequestInit[] = [];
+  const fetchImpl = (async (_input: unknown, init?: RequestInit) => {
+    inits.push(init ?? {});
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' }
+    });
+  }) as typeof globalThis.fetch;
+  const client = new ChassisClient<'things:read'>({
+    baseUrl: 'http://x',
+    apiKey: 'thk_k_s',
+    fetch: fetchImpl,
+    ...overrides
+  });
+  return { client, inits };
+}
+
+describe('chassis client request deadlines', () => {
+  it('puts an AbortSignal on the JSON calls', async () => {
+    const { client, inits } = recordingClient();
+    await client.instance();
+    expect(inits).toHaveLength(1);
+    expect(inits[0]!.signal).toBeInstanceOf(AbortSignal);
+    expect(inits[0]!.signal!.aborted).toBe(false);
+  });
+
+  it('puts an AbortSignal on the streaming download calls', async () => {
+    const { client, inits } = recordingClient();
+    await client.downloadExport();
+    await client.downloadFileContent('file');
+    expect(inits).toHaveLength(2);
+    for (const init of inits) expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('puts an AbortSignal on the upload call', async () => {
+    const { client, inits } = recordingClient();
+    await client.uploadFile('a.txt', new Uint8Array([1]), 'text/plain');
+    expect(inits).toHaveLength(1);
+    expect(inits[0]!.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('actually aborts once the deadline passes', async () => {
+    const stalling = (async (_input: unknown, init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => reject(new Error('aborted')));
+      })) as typeof globalThis.fetch;
+    const client = new ChassisClient<'things:read'>({ baseUrl: 'http://x', fetch: stalling, timeoutMs: 20 });
+    await expect(client.instance()).rejects.toThrow(/abort/i);
+  });
+
+  it('lets an explicit 0 opt out, per kind of call', async () => {
+    const { client, inits } = recordingClient({ timeoutMs: 0 });
+    await client.instance();
+    await client.downloadExport();
+    expect(inits[0]!.signal).toBeUndefined();
+    expect(inits[1]!.signal).toBeInstanceOf(AbortSignal);
+
+    const downloads = recordingClient({ downloadTimeoutMs: 0 });
+    await downloads.client.downloadExport();
+    await downloads.client.instance();
+    expect(downloads.inits[0]!.signal).toBeUndefined();
+    expect(downloads.inits[1]!.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('documents its defaults', () => {
+    expect(DEFAULT_TIMEOUT_MS).toBeGreaterThan(0);
+    expect(DEFAULT_DOWNLOAD_TIMEOUT_MS).toBeGreaterThan(DEFAULT_TIMEOUT_MS);
+  });
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.