feat(core): report the client fingerprint on every request

The client sent no User-Agent at all, so the service could not tell which SDK,
version or platform a request came from and had to learn about breaking changes
from customer reports. Send the same identity headers the Go and Python SDKs
send, using their spellings so the three languages aggregate into the same
buckets, and keep the signed-URL download leg free of them.

Author: moonyue-w

README.md

@@ -232,6 +232,25 @@ Pass `signal` to cancel a request yourself. The deadline stays armed while the r
 await client.sessions.list({}, { signal: AbortSignal.timeout(5_000) });
 ```
 
+## Client fingerprint
+
+Every API request identifies the client so the service can tell which SDK versions are in use before changing a response shape:
+
+| Header | Value |
+| --- | --- |
+| `User-Agent` | `qca-js/<version>` |
+| `X-Qoder-Lang` | `js` |
+| `X-Qoder-Package-Version` | the published package version, also exported as `VERSION` |
+| `X-Qoder-OS` / `X-Qoder-Arch` | normalized platform, e.g. `MacOS` / `arm64` |
+| `X-Qoder-Runtime` / `X-Qoder-Runtime-Version` | `node` and its version |
+| `X-Qoder-Retry-Count` / `X-Qoder-Timeout` | attempt number, and the request deadline in seconds |
+
+The signed-URL leg of a file download carries none of these, so nothing is disclosed to object storage. Any of them can be replaced:
+
+```ts
+const client = new ForwardClient({ defaultHeaders: { 'User-Agent': 'my-app/2.1' } });
+```
+
 ## Auto-pagination
 
 List methods return an async-iterable page. Iterating the result fetches subsequent pages as needed, carrying your filter parameters forward.

scripts/build.mjs

@@ -1,6 +1,15 @@
-import { rm, mkdir, writeFile } from 'node:fs/promises';
+import { rm, mkdir, writeFile, readFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 
+// The reported version is a hand-written constant, so a release that forgets to
+// bump it would make the SDK report a version that was never published.
+const declared = (await readFile(new URL('../src/version.ts', import.meta.url), 'utf8')).match(/VERSION = '(.*)'/)?.[1];
+const published = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
+if (declared !== published) {
+  console.error(`src/version.ts declares ${declared} but package.json is ${published}`);
+  process.exit(1);
+}
+
 await rm(new URL('../dist/', import.meta.url), { recursive: true, force: true });
 for (const config of ['tsconfig.json', 'tsconfig.esm.json']) {
   const result = spawnSync(process.execPath, ['node_modules/typescript/bin/tsc', '-p', config], { stdio: 'inherit' });

src/core/client.ts

@@ -3,6 +3,8 @@ import { type Credential, readEnv } from './credentials.js';
 import { APIConnectionError, APIConnectionTimeoutError, APIError, APIUserAbortError, QoderError } from './error.js';
 import { Page, PagePromise, type PageResponse, type PaginationMode } from './pagination.js';
 import { Stream } from './streaming.js';
+import { VERSION } from '../version.js';
+import { platformHeaders } from './detect-platform.js';
 
 export type HeadersLike = HeadersInit | Record<string, string | null | undefined>;
 export type Middleware = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
@@ -177,7 +179,12 @@ export class APIClient {
     }
     const method = options.method.toUpperCase();
     const value = await withSignal(Promise.resolve(options.body), callerSignal, () => false);
-    const headers = storage ? new Headers() : mergeHeaders({ Accept: options.responseType === 'stream' ? 'text/event-stream' : 'application/json' }, this.options.defaultHeaders, options.headers);
+    const headers = storage ? new Headers() : mergeHeaders({
+      Accept: options.responseType === 'stream' ? 'text/event-stream' : 'application/json',
+      'User-Agent': `qca-js/${VERSION}`,
+      ...platformHeaders(),
+      ...(timeout ? { 'X-Qoder-Timeout': String(Math.trunc(timeout / 1000)) } : {}),
+    }, this.options.defaultHeaders, options.headers);
     if (options.idempotencyKey !== undefined) headers.set('Idempotency-Key', options.idempotencyKey);
     let body: BodyInit | undefined;
     if (value !== undefined) {

src/core/detect-platform.ts

@@ -0,0 +1,46 @@
+import { VERSION } from '../version.js';
+
+// The spellings match the Go SDK's convention/requestconfig.go on purpose: the
+// server aggregates SDK usage across languages, so the same machine has to land in
+// the same bucket no matter which SDK called. process.arch and Go's runtime.GOARCH
+// name the same architecture differently, hence the aliases.
+const OS_NAMES: Record<string, string> = {
+  darwin: 'MacOS',
+  win32: 'Windows',
+  windows: 'Windows',
+  linux: 'Linux',
+  ios: 'iOS',
+  android: 'Android',
+  freebsd: 'FreeBSD',
+  openbsd: 'OpenBSD',
+};
+
+const ARCH_NAMES: Record<string, string> = {
+  ia32: 'x32',
+  x32: 'x32',
+  x64: 'x64',
+  x86_64: 'x64',
+  arm: 'arm',
+  arm64: 'arm64',
+  aarch64: 'arm64',
+};
+
+// The package targets Node (see engines), and has no @types/node, so reach for
+// process the same way credentials.ts does.
+function nodeProcess(): { platform?: string; arch?: string; version?: string } {
+  return (globalThis as unknown as { process?: { platform?: string; arch?: string; version?: string } }).process ?? {};
+}
+
+export function platformHeaders(): Record<string, string> {
+  const { platform, arch, version } = nodeProcess();
+  return {
+    'X-Qoder-Lang': 'js',
+    'X-Qoder-Package-Version': VERSION,
+    'X-Qoder-OS': platform ? OS_NAMES[platform] ?? `Other:${platform}` : 'Unknown',
+    'X-Qoder-Arch': arch ? ARCH_NAMES[arch] ?? `other:${arch}` : 'unknown',
+    // Only Node is supported today; report the runtime we actually detect rather
+    // than claiming node when process is missing.
+    'X-Qoder-Runtime': version ? 'node' : 'unknown',
+    'X-Qoder-Runtime-Version': version ? version.replace(/^v/, '') : 'unknown',
+  };
+}

src/index.ts

@@ -1,5 +1,6 @@
 export { ForwardClient } from './forward/forwardClient.js';
 export { ManagedClient } from './managed/managedClient.js';
+export { VERSION } from './version.js';
 export * from './core/client.js';
 export * from './core/error.js';
 export * from './core/credentials.js';

src/version.ts

@@ -0,0 +1,6 @@
+// Reported to the server in User-Agent and X-Qoder-Package-Version. It must match
+// the version in package.json, otherwise the server-side SDK version statistics
+// describe a version that was never published; `npm run build` compares the two.
+// Declared here rather than imported from package.json so bundlers do not have to
+// resolve JSON from outside src/.
+export const VERSION = '0.0.1-dev.1';

tests/protocol.test.mjs

@@ -95,6 +95,42 @@ for (const mode of ['forward', 'managed']) {
     const res = mode === 'forward' ? await c.files.download('file') : await c.files.download('file', {});
     assert.equal(await res.text(), 'actual file'); assert.equal(calls, 2);
   });
+  test(`${mode}: client fingerprint identifies the SDK but never reaches storage`, async () => {
+    const seen = [];
+    const c = testClient(mode, req => {
+      seen.push(req.headers);
+      if (new URL(req.url).host === 'qoder.test') return response({ url: 'https://storage.test/object?signature=signed' });
+      return response('actual file');
+    }, { timeout: 30_000 });
+    const res = mode === 'forward' ? await c.files.download('file') : await c.files.download('file', {});
+    assert.equal(await res.text(), 'actual file');
+    const [api, storage] = seen;
+    assert.equal(api.get('user-agent'), `qca-js/${sdk.VERSION}`);
+    assert.equal(api.get('x-qoder-lang'), 'js');
+    assert.equal(api.get('x-qoder-package-version'), sdk.VERSION);
+    assert.equal(api.get('x-qoder-runtime'), 'node');
+    assert.equal(api.get('x-qoder-runtime-version'), process.version.replace(/^v/, ''));
+    // Normalized rather than raw process.platform/arch, so the same machine lands
+    // in the same server-side bucket as the Go and Python SDKs.
+    assert.ok(['MacOS', 'Windows', 'Linux', 'iOS', 'Android', 'FreeBSD', 'OpenBSD'].includes(api.get('x-qoder-os')));
+    assert.ok(['x32', 'x64', 'arm', 'arm64'].includes(api.get('x-qoder-arch')));
+    assert.equal(api.get('x-qoder-timeout'), '30');
+    for (const name of ['user-agent', 'x-qoder-lang', 'x-qoder-package-version', 'x-qoder-os', 'x-qoder-arch', 'x-qoder-runtime', 'x-qoder-timeout']) {
+      assert.equal(storage.get(name), null, name);
+    }
+  });
+  test(`${mode}: client fingerprint yields to caller headers and omits an absent deadline`, async () => {
+    const seen = [];
+    const c = testClient(mode, req => { seen.push(req.headers); return response({ data: [] }); }, {
+      timeout: 0,
+      defaultHeaders: { 'User-Agent': 'caller/1.0', 'X-Qoder-Lang': 'cli' },
+    });
+    const r = mode === 'forward' ? c.templates : c.agents;
+    await r.list({});
+    assert.equal(seen[0].get('user-agent'), 'caller/1.0');
+    assert.equal(seen[0].get('x-qoder-lang'), 'cli');
+    assert.equal(seen[0].get('x-qoder-timeout'), null);
+  });
   test(`${mode}: multipart files retain relative names and metadata`, async () => {
     let calls = 0;
     const c = testClient(mode, async req => {