@vertesia/client 1.5.0-dev.20260901.045442Z → 1.5.0-dev.20260905.011013Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260901.045442Z",
+  "version": "1.5.0-dev.20260905.011013Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,9 +19,9 @@
   },
   "dependencies": {
     "eventsource": "^5.0.0",
-    "@llumiverse/common": "1.5.0-dev.20260831.235912Z",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260901.045442Z",
-    "@vertesia/common": "1.5.0-dev.20260901.045442Z"
+    "@vertesia/api-fetch-client": "1.5.0-dev.20260905.011013Z",
+    "@llumiverse/common": "1.5.0-dev.20260905.004250Z",
+    "@vertesia/common": "1.5.0-dev.20260905.011013Z"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "52481a0537557578febbaf2494b9af5c023ccc70",
+  "gitHead": "ea74a29f6885cec132eec4b6b319e40137df3b40",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/client.test.ts

@@ -1,6 +1,8 @@
 import { APP_VERSION_HEADER } from '@vertesia/common';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
-import { isTokenExpired, VertesiaClient } from './client.js';
+import { decodeJWT, isTokenExpired, VertesiaClient, type VertesiaClientProps } from './client.js';
+import { ZenoClient, type ZenoClientProps } from './store/client.js';
+import { resetUnknownOptionWarnings } from './unknown-options.js';
 
 describe('Test Vertesia Client', () => {
     test('Initialization with studio and zeno URLs', () => {
@@ -217,3 +219,114 @@ describe('isTokenExpired', () => {
         expect(isTokenExpired(makeToken(exp))).toBe(true);
     });
 });
+
+describe('unknown constructor options', () => {
+    // Model the real escape hatch rather than a cast: TypeScript's excess-property check only fires
+    // on an object literal, so a spread of a wider config object reaches the constructor unchecked.
+    function optionsWith(extra: Record<string, unknown>): VertesiaClientProps {
+        return {
+            serverUrl: 'https://api.vertesia.io',
+            storeUrl: 'https://api.vertesia.io',
+            ...extra,
+        } as VertesiaClientProps;
+    }
+
+    beforeEach(() => {
+        resetUnknownOptionWarnings();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    // The option names below are deliberately spelled the way the SDK does NOT accept them. Passing
+    // them used to produce a client that looked fine and then failed every request with
+    // `401 Unauthorized: Authorization token is required`, with nothing pointing at the constructor.
+    test('names the option and what the caller meant', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+        new VertesiaClient(optionsWith({ token: 'jwt' }));
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        const message = warn.mock.calls[0][0] as string;
+        expect(message).toContain('[VertesiaClient]');
+        expect(message).toContain('token');
+        expect(message).toContain('`apikey`');
+    });
+
+    test('reports each unknown option once, not once per client', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const opts = optionsWith({ appVersion: 'v1' });
+
+        new VertesiaClient(opts);
+        new VertesiaClient(opts);
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn.mock.calls[0][0]).toContain('withAppVersion');
+    });
+
+    test('stays silent for a fully valid options object', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+        new VertesiaClient({
+            serverUrl: 'https://api.vertesia.io',
+            storeUrl: 'https://api.vertesia.io',
+            tokenServerUrl: 'https://sts.vertesia.io',
+            apikey: 'sk-1234',
+            sessionTags: 'test',
+            timeout: 1000,
+        });
+
+        expect(warn).not.toHaveBeenCalled();
+    });
+
+    // `key in known` would treat these as known options, because every object inherits them.
+    test.each(['toString', 'constructor', 'valueOf', 'hasOwnProperty'])(
+        'reports %s, which is inherited from Object.prototype',
+        (key) => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+            new VertesiaClient(optionsWith({ [key]: 'whatever' }));
+
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0][0]).toContain(key);
+        },
+    );
+
+    test('covers the store client too', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+        new ZenoClient({
+            serverUrl: 'https://api.vertesia.io',
+            ...{ apiKey: 'sk-1234' },
+        } as ZenoClientProps);
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn.mock.calls[0][0]).toContain('[ZenoClient]');
+        expect(warn.mock.calls[0][0]).toContain('apikey');
+    });
+});
+
+describe('decodeJWT', () => {
+    // An empty or non-JWT credential used to reach `''.split('.')[1]` and die inside the base64
+    // decoder with a TypeError naming neither the token nor the caller.
+    test.each([
+        ['an empty string', ''],
+        ['an API key', 'sk-abcdef'],
+        ['a two-segment string', 'header.payload'],
+    ])('names the failure for %s', (_label, value) => {
+        expect(() => decodeJWT(value)).toThrowError(/Invalid auth token: expected a JWT/);
+    });
+
+    test('names a payload that is not JSON', () => {
+        expect(() => decodeJWT('aGVhZGVy.bm90LWpzb24.sig')).toThrowError(
+            'Invalid auth token: payload segment is not JSON',
+        );
+    });
+
+    test('rejects an empty token before decoding it', async () => {
+        await expect(VertesiaClient.fromAuthToken('   ')).rejects.toThrowError(
+            'VertesiaClient.fromAuthToken requires a non-empty auth token',
+        );
+    });
+});

package/src/client.ts

@@ -28,6 +28,7 @@ import { VERSION, VERSION_HEADER } from './store/version.js';
 import ToolsApi from './ToolsApi.js';
 import TrainingApi from './TrainingApi.js';
 import UsersApi from './UsersApi.js';
+import { warnUnknownOptions } from './unknown-options.js';
 import ViewsApi from './ViewsApi.js';
 
 /**
@@ -63,7 +64,6 @@ export type VertesiaClientProps = {
     storeUrl?: string;
     tokenServerUrl?: string;
     apikey?: string;
-    projectId?: string;
     sessionTags?: string | string[];
     onRequest?: (request: Request) => void;
     onResponse?: (response: Response) => void;
@@ -77,6 +77,25 @@ export type VertesiaClientProps = {
     fetch?: FETCH_FN | Promise<FETCH_FN>;
 };
 
+/**
+ * Every option the constructor reads. Typing it as `Record<keyof Required<VertesiaClientProps>, true>`
+ * keeps it exhaustive in both directions: a new prop that is missing here fails to compile, and a key
+ * here that is not a prop fails too. Without that, the table would silently rot into false warnings.
+ */
+const KNOWN_CLIENT_OPTIONS: Record<keyof Required<VertesiaClientProps>, true> = {
+    site: true,
+    serverUrl: true,
+    storeUrl: true,
+    tokenServerUrl: true,
+    apikey: true,
+    sessionTags: true,
+    onRequest: true,
+    onResponse: true,
+    retryPolicy: true,
+    timeout: true,
+    fetch: true,
+};
+
 export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     /**
      * The JWT token linked to the API KEY (sk or pk)
@@ -119,6 +138,10 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         payload?: AuthTokenPayload,
         endpoints?: { studio: string; store: string; token?: string; git?: string },
     ) {
+        if (!token?.trim()) {
+            throw new Error('VertesiaClient.fromAuthToken requires a non-empty auth token');
+        }
+
         if (!payload) {
             payload = decodeJWT(token);
         }
@@ -138,6 +161,8 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
             site: 'api.vertesia.io',
         },
     ) {
+        warnUnknownOptions('VertesiaClient', opts, KNOWN_CLIENT_OPTIONS);
+
         let studioServerUrl: string;
         let zenoServerUrl: string;
 
@@ -455,9 +480,27 @@ export function isTokenExpired(token: string | null) {
 }
 
 export function decodeJWT(jwt: string): AuthTokenPayload {
-    const payloadBase64 = jwt.split('.')[1];
-    const decodedJson = base64UrlDecode(payloadBase64);
-    return JSON.parse(decodedJson);
+    // Never echo the token itself in these messages: it is a live credential, and decode failures
+    // are routinely logged. The shape of the failure is enough to identify the caller's mistake.
+    const segments = typeof jwt === 'string' ? jwt.split('.') : [];
+    if (segments.length !== 3 || !segments[1]) {
+        throw new Error(
+            `Invalid auth token: expected a JWT of three dot-separated segments, got ${segments.length || 'none'}`,
+        );
+    }
+
+    let decodedJson: string;
+    try {
+        decodedJson = base64UrlDecode(segments[1]);
+    } catch (err) {
+        throw new Error(`Invalid auth token: payload segment is not base64url (${(err as Error).message})`);
+    }
+
+    try {
+        return JSON.parse(decodedJson);
+    } catch {
+        throw new Error('Invalid auth token: payload segment is not JSON');
+    }
 }
 
 type RuntimeProcess = {

package/src/store/AgentsApi.artifacts.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { escapeArtifactPathDelimiters } from './AgentsApi.js';
+import { ZenoClient } from './client.js';
+
+const SERVER_URL = 'https://store.test';
+const RUN_ID = 'run-1';
+
+/**
+ * A client whose injected fetch records the URL of every request it is handed. The URL is read off
+ * the Request object, so the assertions see the path after WHATWG URL parsing — which is where an
+ * unescaped `#` was being dropped.
+ */
+function clientRecordingUrls(body: unknown = { url: 'https://signed', path: 'p' }) {
+    const urls: string[] = [];
+    const client = new ZenoClient({
+        serverUrl: SERVER_URL,
+        apikey: 'token',
+        fetch: async (input: RequestInfo) => {
+            urls.push(input instanceof Request ? input.url : String(input));
+            return new Response(JSON.stringify(body), {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+            });
+        },
+    });
+    return { client, urls };
+}
+
+/** The artifact path the server reconstructs: the URL path after the route prefix, decoded per segment. */
+function serverPath(url: string, prefix: string): string {
+    const tail = new URL(url).pathname.split(`/${prefix}/`)[1] ?? '';
+    return tail.split('/').map(decodeURIComponent).join('/');
+}
+
+describe('escapeArtifactPathDelimiters', () => {
+    it('escapes the two characters that truncate a path', () => {
+        expect(escapeArtifactPathDelimiters('files/tpl (YYYY-0#).docx')).toBe('files/tpl (YYYY-0%23).docx');
+        expect(escapeArtifactPathDelimiters('files/report?v2.docx')).toBe('files/report%3Fv2.docx');
+    });
+
+    // Scope guard. Anything this helper touches changes the bytes on the wire for filenames that
+    // work today, so it must leave everything except `#` and `?` exactly as it found it.
+    it.each([
+        ['percent', 'files/100% done.docx'],
+        ['spaces', 'files/MHA - Client IQ FSD.docx'],
+        ['non-ascii and accents', 'files/café résumé.docx'],
+        ['backslash', 'files/back\\slash.docx'],
+        ['segment separators', 'files/nested/a b.txt'],
+        ['already-encoded sequence', 'files/report%23.md'],
+    ])('leaves %s untouched', (_label, path) => {
+        expect(escapeArtifactPathDelimiters(path)).toBe(path);
+    });
+});
+
+describe('AgentsApi artifact paths', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.unstubAllGlobals();
+    });
+
+    // A `#` in an uploaded filename used to be parsed as the URL fragment, so the server saw a
+    // truncated path and stored the object under a key nothing could read back.
+    it('uploadArtifact preserves a path containing #', async () => {
+        vi.stubGlobal(
+            'fetch',
+            vi.fn(async () => new Response(null, { status: 200 })),
+        );
+        const { client, urls } = clientRecordingUrls();
+        const path = 'files/Design Template (YYYY-0#).docx';
+
+        await client.agents.uploadArtifact(RUN_ID, path, 'content');
+
+        expect(urls).toHaveLength(1);
+        expect(urls[0]).not.toContain('#');
+        expect(serverPath(urls[0], 'artifacts')).toBe(path);
+    });
+
+    // The query is concatenated onto the path, so an unescaped delimiter took it down too.
+    it.each([
+        ['hash', 'files/Design (YYYY-0#).docx'],
+        ['question mark', 'files/report?v2.docx'],
+    ])('getArtifactUrl round-trips %s and keeps the query intact', async (_label, path) => {
+        const { client, urls } = clientRecordingUrls();
+
+        await client.agents.getArtifactUrl(RUN_ID, path, 'attachment', 'download-name.docx');
+
+        const url = new URL(urls[0]);
+        expect(serverPath(urls[0], 'artifacts')).toBe(path);
+        expect(url.hash).toBe('');
+        expect(url.searchParams.get('url')).toBe('1');
+        expect(url.searchParams.get('disposition')).toBe('attachment');
+        expect(url.searchParams.get('filename')).toBe('download-name.docx');
+    });
+
+    // Pins the scope boundary: `%` must go on the wire exactly as it does with no escaping at all.
+    it('sends a path containing % exactly as it did before, unescaped', async () => {
+        const { client, urls } = clientRecordingUrls();
+        const path = 'files/100% done.docx';
+
+        await client.agents.getArtifactUrl(RUN_ID, path);
+
+        const unescaped = new URL(`${SERVER_URL}/api/v1/agents/${RUN_ID}/artifacts/${path}?url=1`);
+        expect(new URL(urls[0]).pathname).toBe(unescaped.pathname);
+        expect(new URL(urls[0]).pathname).toContain('100%%20done.docx');
+    });
+
+    it('getArtifactContent and updateArtifactContent preserve a path containing #', async () => {
+        const { client, urls } = clientRecordingUrls({ content: '', generation: '1' });
+        const path = 'files/notes (v0#1).md';
+
+        await client.agents.getArtifactContent(RUN_ID, path);
+        await client.agents.updateArtifactContent(RUN_ID, path, { content: 'x', generation: '1' });
+
+        expect(urls).toHaveLength(2);
+        for (const url of urls) {
+            expect(serverPath(url, 'artifact-content')).toBe(path);
+        }
+    });
+});

package/src/store/AgentsApi.ts

@@ -64,6 +64,14 @@ export interface AgentRunStreamMessagesOptions {
     onHistoryError?: (error: unknown) => void;
 }
 
+/**
+ * `#` and `?` are URL delimiters, not path content: either one truncates the path before the
+ * request is built. Nothing else is escaped — `%` keeps its existing rejection at upload.
+ */
+export function escapeArtifactPathDelimiters(path: string): string {
+    return path.replace(/#/g, '%23').replace(/\?/g, '%3F');
+}
+
 export class AgentsApi extends ApiTopic {
     constructor(parent: ClientBase) {
         super(parent, '/api/v1/agents');
@@ -795,7 +803,7 @@ export class AgentsApi extends ApiTopic {
 
     /** Read a text artifact together with its conditional-write generation token. */
     getArtifactContent(id: string, path: string): Promise<AgentArtifactContentResponse> {
-        return this.get(`/${id}/artifact-content/${path}`);
+        return this.get(`/${id}/artifact-content/${escapeArtifactPathDelimiters(path)}`);
     }
 
     /** Conditionally replace the text content of an agent artifact. */
@@ -804,7 +812,7 @@ export class AgentsApi extends ApiTopic {
         path: string,
         payload: UpdateAgentArtifactContentPayload,
     ): Promise<UpdateAgentArtifactContentResponse> {
-        return this.put(`/${id}/artifact-content/${path}`, { payload });
+        return this.put(`/${id}/artifact-content/${escapeArtifactPathDelimiters(path)}`, { payload });
     }
 
     /**
@@ -819,7 +827,7 @@ export class AgentsApi extends ApiTopic {
         const query: Record<string, string> = { url: '1' };
         if (disposition) query.disposition = disposition;
         if (fileName) query.filename = fileName;
-        return this.get(`/${id}/artifacts/${path}`, { query });
+        return this.get(`/${id}/artifacts/${escapeArtifactPathDelimiters(path)}`, { query });
     }
 
     /**
@@ -840,7 +848,7 @@ export class AgentsApi extends ApiTopic {
         const mimeType = contentType || 'application/octet-stream';
 
         // 1. Get signed upload URL from the agents API
-        const result = (await this.put(`/${id}/artifacts/${path}`, {
+        const result = (await this.put(`/${id}/artifacts/${escapeArtifactPathDelimiters(path)}`, {
             headers: { 'Content-Type': mimeType },
         })) as AgentArtifactUrlResponse;
 

package/src/store/DataApi.test.ts

@@ -0,0 +1,42 @@
+import type { ImportDataPayload } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import { ZenoClient } from './client.js';
+
+describe('DataApi', () => {
+    // `import` is the name applications built against the 1.4 SDK call, through the client the
+    // platform serves them rather than one they bundle -- so renaming it (as 1.5 briefly did, to
+    // `importData`) breaks them at deploy time rather than at their next upgrade. This pins both
+    // the name and the request it issues.
+    it('exposes `import` as POST {store}/import with the data store header', async () => {
+        const requests: { url: string; method: string; storeHeader: string | null; body: string }[] = [];
+        const fetchImport = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+            const request = new Request(input, init);
+            requests.push({
+                url: request.url,
+                method: request.method,
+                storeHeader: request.headers.get('x-data-store-id'),
+                body: await request.text(),
+            });
+            return new Response(JSON.stringify({ id: 'import-1', status: 'completed' }), {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+            });
+        };
+
+        const client = new ZenoClient({ serverUrl: 'https://store.test', apikey: 'token', fetch: fetchImport });
+        const payload: ImportDataPayload = {
+            mode: 'append',
+            message: 'test import',
+            tables: { customers: { source: 'inline', data: [{ id: 1 }] } },
+        };
+
+        const job = await client.data.import('store-1', payload);
+
+        expect(job).toEqual({ id: 'import-1', status: 'completed' });
+        expect(requests).toHaveLength(1);
+        expect(requests[0].method).toBe('POST');
+        expect(requests[0].url).toBe('https://store.test/api/v1/data/store-1/import');
+        expect(requests[0].storeHeader).toBe('store-1');
+        expect(JSON.parse(requests[0].body)).toEqual(payload);
+    });
+});

package/src/store/DataApi.ts

@@ -255,7 +255,7 @@ export class DataApi extends ApiTopic {
      *
      * @example
      * ```typescript
-     * const job = await client.data.importData(storeId, {
+     * const job = await client.data.import(storeId, {
      *   mode: 'append',
      *   message: 'Monthly data import',
      *   tables: {
@@ -271,8 +271,14 @@ export class DataApi extends ApiTopic {
      *   }
      * });
      * ```
+     *
+     * Do not rename this method. 1.5 renamed it to `importData` (composableai#1645) on the theory
+     * that the token sequence `import(` confused Vite/Rollup import analysis; it does not on the
+     * current toolchain. Applications built against the 1.4 SDK call this through the client the
+     * platform serves them rather than one they bundle themselves, so a rename would break them
+     * the moment 1.5 is deployed, not at their next upgrade.
      */
-    importData(id: string, payload: ImportDataPayload): Promise<ImportJob> {
+    import(id: string, payload: ImportDataPayload): Promise<ImportJob> {
         return this.post(`/${id}/import`, { payload, headers: this.storeHeaders(id) });
     }
 

package/src/store/IndexingApi.ts

@@ -1,4 +1,4 @@
-import { ApiTopic, type ClientBase, type ServerSentEvent } from '@vertesia/api-fetch-client';
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
     AnalyzeDriftBatchResult,
     BulkDeleteResult,
@@ -22,8 +22,6 @@ import type {
     NextIndexCursorResult,
     ReindexAgentRunsPayload,
     ReindexAgentRunsResponse,
-    ReindexViaBulkRequest,
-    ReindexViaBulkResult,
     StartProjectReindexPayload,
     SwapAliasRequest,
     SwapAliasResult,
@@ -345,71 +343,4 @@ export class IndexingApi extends ApiTopic {
             backend,
         } satisfies SwapAliasRequest);
     }
-
-    /**
-     * Full reindex of a tenant via zeno-bulk (all-in-one).
-     * The Go service handles sharding, indexing, catch-up, and alias swap internally.
-     *
-     * In JSON mode (default): waits for completion and returns the final result.
-     * In SSE mode (when onEvent is provided): streams progress events from zeno-bulk
-     * and returns the final result. The onEvent callback receives parsed SSE events
-     * with { event: "progress" | "done", data: string (JSON) }.
-     */
-    async reindexViaBulk(
-        tenantId: string,
-        onEvent?: ((event: ServerSentEvent) => void) | null,
-        dryRun?: boolean,
-        backend?: ElasticsearchBackend,
-        projectId?: string,
-        tuning?: {
-            shardSize?: number;
-            shards?: number;
-            bulkConcurrency?: number;
-            bulkSizeBytes?: number;
-            bulkMaxDocs?: number;
-        },
-    ): Promise<ReindexViaBulkResult> {
-        const bulkUrl = `${this.zenoBulkBaseUrl}/reindex`;
-        const params = {
-            tenant_id: tenantId,
-            project_id: projectId,
-            dry_run: dryRun ?? false,
-            backend,
-            shard_size: tuning?.shardSize,
-            shards: tuning?.shards,
-            bulk_concurrency: tuning?.bulkConcurrency,
-            bulk_size_bytes: tuning?.bulkSizeBytes,
-            bulk_max_docs: tuning?.bulkMaxDocs,
-        } satisfies ReindexViaBulkRequest;
-
-        if (!onEvent) {
-            return this.client.post(bulkUrl, { payload: { params } });
-        }
-
-        // SSE mode: stream progress events from zeno-bulk
-        let lastResult: ReindexViaBulkResult | undefined;
-
-        await this.client.sseRequest(
-            'POST',
-            bulkUrl,
-            {
-                payload: { params },
-            },
-            (event) => {
-                onEvent(event);
-                if (event.type === 'event' && event.event === 'done') {
-                    try {
-                        lastResult = JSON.parse(event.data) as ReindexViaBulkResult;
-                    } catch {
-                        // data might not be valid JSON
-                    }
-                }
-            },
-        );
-
-        if (!lastResult) {
-            throw new Error('zeno-bulk SSE stream ended without a done event');
-        }
-        return lastResult;
-    }
 }

package/src/store/client.ts

@@ -5,6 +5,7 @@ import {
     type RequestError,
 } from '@vertesia/api-fetch-client';
 import { APP_VERSION_HEADER, type BulkOperationPayload, type BulkOperationResponse } from '@vertesia/common';
+import { warnUnknownOptions } from '../unknown-options.js';
 import { AgentsApi } from './AgentsApi.js';
 import { CollectionsApi } from './CollectionsApi.js';
 import { CostApi } from './CostApi.js';
@@ -39,6 +40,18 @@ export interface ZenoClientProps {
     fetch?: FETCH_FN | Promise<FETCH_FN>;
 }
 
+/** Exhaustive in both directions — see the same table in `../client.ts`. */
+const KNOWN_STORE_OPTIONS: Record<keyof Required<ZenoClientProps>, true> = {
+    serverUrl: true,
+    tokenServerUrl: true,
+    apikey: true,
+    onRequest: true,
+    onResponse: true,
+    retryPolicy: true,
+    timeout: true,
+    fetch: true,
+};
+
 function ensureDefined(serverUrl: string | undefined) {
     if (!serverUrl) {
         throw new Error('zeno client serverUrl is required');
@@ -48,6 +61,7 @@ function ensureDefined(serverUrl: string | undefined) {
 
 export class ZenoClient extends AbstractFetchClient<ZenoClient> {
     constructor(opts: ZenoClientProps = {}) {
+        warnUnknownOptions('ZenoClient', opts, KNOWN_STORE_OPTIONS);
         super(ensureDefined(opts.serverUrl), opts.fetch);
         if (opts.apikey) {
             this.withApiKey(opts.apikey);

package/src/unknown-options.ts

@@ -0,0 +1,56 @@
+/**
+ * Client constructors take a plain options object, so an option name that does not exist is not a
+ * runtime error — it is silently dropped. TypeScript's excess-property check catches it for an
+ * object literal, but not for a spread, an `any`, or plain JavaScript, and the resulting client
+ * looks healthy right up to the first request. A credential passed under the wrong name produces a
+ * client with no `Authorization` header, so every call fails with
+ * `401 Unauthorized: Authorization token is required` and nothing points at the constructor.
+ *
+ * These helpers make that case say so, once per unknown option name.
+ */
+
+/** Options that never existed, mapped to what the caller almost certainly meant. */
+const OPTION_HINTS: Record<string, string> = {
+    token: 'pass the credential as `apikey`, or build the client with `VertesiaClient.fromAuthToken(token)`',
+    accessToken: 'pass the credential as `apikey`, or build the client with `VertesiaClient.fromAuthToken(token)`',
+    authToken: 'pass the credential as `apikey`, or build the client with `VertesiaClient.fromAuthToken(token)`',
+    apiKey: 'the option is spelled `apikey`, all lowercase',
+    api_key: 'the option is spelled `apikey`, all lowercase',
+    appVersion: 'pin the app version with the `withAppVersion(version)` method after construction',
+    apiVersion: 'pin the API version with the `withApiVersion(version)` method after construction',
+    projectId: 'the project is determined by the credential; this option was never read',
+    baseUrl: 'use `serverUrl` for studio and `storeUrl` for the store',
+};
+
+const warned = new Set<string>();
+
+/**
+ * Warn once per unknown option name. Deliberately a warning and not a throw: passing a harmless
+ * extra key is common (spreading a wider config object) and has never failed, so throwing would
+ * break working callers to report a mistake they may not have made.
+ *
+ * @param clientName the constructor name, used to prefix the message
+ * @param opts the options object as given by the caller
+ * @param known the options the constructor actually reads
+ */
+export function warnUnknownOptions(clientName: string, opts: object, known: Record<string, true>): void {
+    // `Object.hasOwn`, not `in`: `in` walks the prototype chain, so options named `toString`,
+    // `constructor` or `valueOf` would look like known options and go unreported.
+    const unknown = Object.keys(opts).filter((key) => !Object.hasOwn(known, key) && !warned.has(key));
+    if (unknown.length === 0) {
+        return;
+    }
+    for (const key of unknown) {
+        warned.add(key);
+    }
+    const details = unknown.map((key) => (Object.hasOwn(OPTION_HINTS, key) ? `${key} (${OPTION_HINTS[key]})` : key));
+    console.warn(
+        `[${clientName}] Ignoring unknown constructor option(s): ${details.join('; ')}. ` +
+            'Unknown options have no effect.',
+    );
+}
+
+/** Test-only: forget which option names have already been reported. */
+export function resetUnknownOptionWarnings(): void {
+    warned.clear();
+}