plugin-ai-api 1.0.13 → 1.0.14

package/dist/server/usage.js

@@ -26,34 +26,73 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var usage_exports = {};
 __export(usage_exports, {
+  extractProviderRequestId: () => extractProviderRequestId,
   finishUsageRecord: () => finishUsageRecord,
+  normalizeUsage: () => normalizeUsage,
+  setAiApiUsageResult: () => setAiApiUsageResult,
+  setAiApiUsageUnavailable: () => setAiApiUsageUnavailable,
   startUsageRecord: () => startUsageRecord
 });
 module.exports = __toCommonJS(usage_exports);
+function getAiApiState(ctx) {
+  return ctx.state;
+}
+function normalizeTokenCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
 function normalizeUsage(value) {
   if (!value || typeof value !== "object") return void 0;
   const source = value;
-  const prompt = source.prompt_tokens ?? source.input_tokens;
-  const completion = source.completion_tokens ?? source.output_tokens;
-  const total = source.total_tokens;
-  if (prompt == null && completion == null && total == null) return void 0;
+  const prompt = normalizeTokenCount(source.prompt_tokens ?? source.input_tokens);
+  const completion = normalizeTokenCount(source.completion_tokens ?? source.output_tokens);
+  let total = normalizeTokenCount(source.total_tokens);
+  if (total === null && prompt !== null && completion !== null) {
+    total = prompt + completion;
+  }
+  if (prompt === null && completion === null && total === null) return void 0;
   return {
-    prompt_tokens: typeof prompt === "number" ? prompt : null,
-    completion_tokens: typeof completion === "number" ? completion : null,
-    total_tokens: typeof total === "number" ? total : null
+    prompt_tokens: prompt,
+    completion_tokens: completion,
+    total_tokens: total
+  };
+}
+function setAiApiUsageResult(ctx, value, metadata = {}) {
+  const usage = normalizeUsage(value);
+  getAiApiState(ctx).aiApiUsageResult = usage ? { source: "provider", usage, ...metadata } : { source: "unavailable", ...metadata };
+  return usage;
+}
+function setAiApiUsageUnavailable(ctx, gatewayResponseId) {
+  getAiApiState(ctx).aiApiUsageResult = {
+    source: "unavailable",
+    ...gatewayResponseId ? { gatewayResponseId } : {}
   };
 }
+function extractProviderRequestId(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const source = value;
+  const responseMetadata = source.response_metadata && typeof source.response_metadata === "object" ? source.response_metadata : void 0;
+  const headers = (responseMetadata == null ? void 0 : responseMetadata.headers) && typeof responseMetadata.headers === "object" ? responseMetadata.headers : void 0;
+  const candidate = (responseMetadata == null ? void 0 : responseMetadata.request_id) ?? (responseMetadata == null ? void 0 : responseMetadata.requestId) ?? (responseMetadata == null ? void 0 : responseMetadata.id) ?? (headers == null ? void 0 : headers["x-request-id"]) ?? (headers == null ? void 0 : headers["request-id"]);
+  return typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+}
 async function startUsageRecord(ctx, requestId, endpoint, model, streaming, mode) {
   var _a, _b;
   const body = ctx.request.body || {};
   const messages = Array.isArray(body.messages) ? body.messages : void 0;
-  const oauth = ctx.state.oauthPrincipal;
+  const promptCount = Array.isArray(body.prompt) ? body.prompt.length : body.prompt === void 0 ? void 0 : 1;
+  const embeddingInputCount = Array.isArray(body.input) ? body.input.length : body.input === void 0 ? void 0 : 1;
+  const state = getAiApiState(ctx);
+  const userId = (_a = state.currentUser) == null ? void 0 : _a.id;
+  if (userId === void 0 || userId === null) {
+    throw new Error("AI API usage record requires an authenticated NocoBase user ID.");
+  }
+  const oauth = state.oauthPrincipal;
   const record = await ctx.db.getRepository("aiApiUsageRecords").create({
     values: {
       requestId,
-      userId: String((_a = ctx.state.currentUser) == null ? void 0 : _a.id),
-      roleName: ctx.state.currentRole || ((_b = ctx.state.currentRoles) == null ? void 0 : _b[0]) || "unknown",
-      authType: ctx.state.aiApiAuthType || (oauth ? "oidc" : "session"),
+      userId,
+      roleName: state.currentRole || ((_b = state.currentRoles) == null ? void 0 : _b[0]) || "unknown",
+      authType: state.aiApiAuthType || (oauth ? "oidc" : "unknown"),
       oauthClientId: oauth == null ? void 0 : oauth.clientId,
       oauthSubject: oauth == null ? void 0 : oauth.subject,
       oauthScopes: oauth == null ? void 0 : oauth.scopes,
@@ -63,32 +102,47 @@ async function startUsageRecord(ctx, requestId, endpoint, model, streaming, mode
       status: "pending",
       streaming,
       startedAt: /* @__PURE__ */ new Date(),
-      requestMetadata: { messageCount: messages == null ? void 0 : messages.length, requestedMaxTokens: body.max_tokens }
+      requestMetadata: {
+        messageCount: messages == null ? void 0 : messages.length,
+        promptCount,
+        embeddingInputCount,
+        requestedMaxTokens: body.max_completion_tokens ?? body.max_tokens
+      }
     }
   });
   return record.id;
 }
 async function finishUsageRecord(ctx, id, startedAt, status) {
-  var _a, _b;
+  var _a;
   const response = ctx.body || {};
-  const streamResult = ctx.state.aiApiStreamResult;
-  const usage = normalizeUsage(response.usage) || normalizeUsage((_a = response.response_metadata) == null ? void 0 : _a.usage) || normalizeUsage(streamResult == null ? void 0 : streamResult.usage);
+  const state = getAiApiState(ctx);
+  const streamResult = state.aiApiStreamResult;
+  const usageResult = state.aiApiUsageResult ?? { source: "unavailable" };
+  const usage = usageResult.source === "provider" ? usageResult.usage : void 0;
+  const gatewayResponseId = usageResult.gatewayResponseId || response.id || (streamResult == null ? void 0 : streamResult.id);
   const values = {
     status: streamResult ? streamResult.succeeded ? "succeeded" : "failed" : status,
     httpStatus: ctx.status,
-    errorCode: ((_b = response.error) == null ? void 0 : _b.code) || (streamResult == null ? void 0 : streamResult.errorCode),
-    inputTokens: usage == null ? void 0 : usage.prompt_tokens,
-    outputTokens: usage == null ? void 0 : usage.completion_tokens,
-    totalTokens: usage == null ? void 0 : usage.total_tokens,
-    providerRequestId: response.id || (streamResult == null ? void 0 : streamResult.id),
+    errorCode: ((_a = response.error) == null ? void 0 : _a.code) || (streamResult == null ? void 0 : streamResult.errorCode),
+    inputTokens: (usage == null ? void 0 : usage.prompt_tokens) ?? null,
+    outputTokens: (usage == null ? void 0 : usage.completion_tokens) ?? null,
+    totalTokens: (usage == null ? void 0 : usage.total_tokens) ?? null,
+    providerRequestId: usageResult.providerRequestId ?? null,
     completedAt: /* @__PURE__ */ new Date(),
     durationMs: Date.now() - startedAt,
-    responseMetadata: { usageSource: usage ? "provider" : "unavailable" }
+    responseMetadata: {
+      usageSource: usageResult.source,
+      ...gatewayResponseId ? { gatewayResponseId } : {}
+    }
   };
   await ctx.db.getRepository("aiApiUsageRecords").update({ filterByTk: id, values });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  extractProviderRequestId,
   finishUsageRecord,
+  normalizeUsage,
+  setAiApiUsageResult,
+  setAiApiUsageUnavailable,
   startUsageRecord
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-ai-api",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "main": "dist/server/index.js",
   "dependencies": {},
   "peerDependencies": {

package/src/server/__tests__/usage-migration.test.ts

@@ -0,0 +1,171 @@
+import { DataTypes, type Database } from '@nocobase/database';
+import type { MigrationContext } from '@nocobase/database';
+import { describe, expect, it, vi } from 'vitest';
+import ChangeUsageUserIdToBigInt, {
+  isBigIntColumnType,
+  normalizeLegacyUserId,
+} from '../migrations/20260727140000-change-usage-user-id-to-bigint';
+
+interface HarnessOptions {
+  allowNull?: boolean;
+  collectionExists?: boolean;
+  collectionRegistered?: boolean;
+  columnType?: string;
+  dialect?: 'mysql' | 'postgres' | 'sqlite';
+  rows?: Array<{ recordId: string | number; userId: unknown }>;
+}
+
+function createHarness(options: HarnessOptions = {}) {
+  const rows = options.rows ?? [];
+  const dialect = options.dialect ?? 'sqlite';
+  const changeColumn = vi.fn().mockResolvedValue(undefined);
+  const describeTable = vi.fn().mockResolvedValue({
+    userId: {
+      type: options.columnType ?? 'VARCHAR(255)',
+      allowNull: options.allowNull ?? true,
+    },
+  });
+  const queryInterface = { changeColumn, describeTable };
+  const query = vi.fn(async (sql: string) => {
+    if (sql.startsWith('SELECT')) return rows;
+    return undefined;
+  });
+  const transaction = vi.fn(async (callback: (value: object) => Promise<void>) => callback({}));
+  const collection = {
+    existsInDb: vi.fn().mockResolvedValue(options.collectionExists ?? true),
+    getField: vi.fn().mockReturnValue({ columnName: () => 'userId' }),
+    getTableNameWithSchema: () => 'aiApiUsageRecords',
+    quotedTableName: () => '"aiApiUsageRecords"',
+  };
+  const registerCollection = vi.fn().mockReturnValue(collection);
+  const removeCollection = vi.fn();
+  const db = {
+    collection: registerCollection,
+    getCollection: vi.fn().mockReturnValue(options.collectionRegistered ? collection : undefined),
+    inDialect: (...dialects: string[]) => dialects.includes(dialect),
+    quoteIdentifier: (identifier: string) => `"${identifier}"`,
+    removeCollection,
+    sequelize: {
+      getQueryInterface: () => queryInterface,
+      query,
+      transaction,
+    },
+  };
+  const migration = new ChangeUsageUserIdToBigInt({
+    db: db as unknown as Database,
+    queryInterface,
+    sequelize: db.sequelize,
+  } as unknown as MigrationContext);
+
+  return {
+    changeColumn,
+    collection,
+    describeTable,
+    migration,
+    query,
+    registerCollection,
+    removeCollection,
+    transaction,
+  };
+}
+
+describe('AI API usage userId BIGINT migration', () => {
+  it('accepts numeric strings without converting them through JavaScript Number', () => {
+    expect(normalizeLegacyUserId('42')).toBe('42');
+    expect(normalizeLegacyUserId(' 00042 ')).toBe('00042');
+    expect(normalizeLegacyUserId('9007199254740993')).toBe('9007199254740993');
+    expect(normalizeLegacyUserId('9223372036854775808')).toBeUndefined();
+    expect(normalizeLegacyUserId('undefined')).toBeUndefined();
+    expect(normalizeLegacyUserId('')).toBeUndefined();
+  });
+
+  it('changes a valid legacy column to a non-null BIGINT', async () => {
+    const harness = createHarness({
+      dialect: 'mysql',
+      rows: [
+        { recordId: 1, userId: '42' },
+        { recordId: 2, userId: '0007' },
+        { recordId: 3, userId: '9007199254740993' },
+      ],
+    });
+
+    await harness.migration.up();
+
+    expect(harness.changeColumn).toHaveBeenCalledWith('aiApiUsageRecords', 'userId', {
+      type: DataTypes.BIGINT,
+      allowNull: false,
+    });
+    expect(harness.query).toHaveBeenCalledTimes(1);
+    expect(String(harness.query.mock.calls[0][0])).toContain('SELECT');
+    expect(harness.registerCollection).toHaveBeenCalledOnce();
+    expect(harness.removeCollection).toHaveBeenCalledWith('aiApiUsageRecords');
+  });
+
+  it('uses an explicit PostgreSQL USING cast inside a transaction', async () => {
+    const harness = createHarness({ dialect: 'postgres', rows: [{ recordId: 1, userId: '42' }] });
+
+    await harness.migration.up();
+
+    const ddl = harness.query.mock.calls.find(([sql]) => String(sql).startsWith('ALTER TABLE'))?.[0];
+    expect(String(ddl)).toContain('TYPE BIGINT USING BTRIM("userId")::BIGINT');
+    expect(String(ddl)).toContain('SET NOT NULL');
+    expect(harness.transaction).toHaveBeenCalledOnce();
+    expect(harness.changeColumn).not.toHaveBeenCalled();
+  });
+
+  it('rejects invalid values before running any DDL', async () => {
+    const harness = createHarness({
+      dialect: 'postgres',
+      rows: [
+        { recordId: 4, userId: 'undefined' },
+        { recordId: 5, userId: '' },
+      ],
+    });
+
+    await expect(harness.migration.up()).rejects.toThrow('2 invalid userId value(s)');
+
+    expect(harness.query.mock.calls.some(([sql]) => String(sql).startsWith('ALTER TABLE'))).toBe(false);
+    expect(harness.changeColumn).not.toHaveBeenCalled();
+    expect(harness.transaction).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unsupported legacy column type before scanning data', async () => {
+    const harness = createHarness({ columnType: 'INTEGER' });
+
+    await expect(harness.migration.up()).rejects.toThrow('does not support converting INTEGER to BIGINT');
+
+    expect(harness.query).not.toHaveBeenCalled();
+    expect(harness.changeColumn).not.toHaveBeenCalled();
+  });
+
+  it('is idempotent when the column is already a non-null BIGINT', async () => {
+    const harness = createHarness({ columnType: 'BIGINT', allowNull: false, rows: [{ recordId: 1, userId: '42' }] });
+
+    await harness.migration.up();
+
+    expect(isBigIntColumnType('BIGINT')).toBe(true);
+    expect(harness.changeColumn).not.toHaveBeenCalled();
+    expect(harness.query.mock.calls.some(([sql]) => String(sql).startsWith('ALTER TABLE'))).toBe(false);
+  });
+
+  it('enforces non-null when a BIGINT column was migrated incompletely', async () => {
+    const harness = createHarness({
+      columnType: 'BIGINT',
+      allowNull: true,
+      dialect: 'postgres',
+      rows: [{ recordId: 1, userId: '42' }],
+    });
+
+    await harness.migration.up();
+
+    const ddl = harness.query.mock.calls.find(([sql]) => String(sql).startsWith('ALTER TABLE'))?.[0];
+    expect(String(ddl)).toContain('ALTER COLUMN "userId" SET NOT NULL');
+  });
+
+  it('is a no-op when the collection has not been installed', async () => {
+    const harness = createHarness({ collectionExists: false });
+    await expect(harness.migration.up()).resolves.toBeUndefined();
+    expect(harness.describeTable).not.toHaveBeenCalled();
+    expect(harness.removeCollection).toHaveBeenCalledWith('aiApiUsageRecords');
+  });
+});

package/src/server/__tests__/usage-route.test.ts

@@ -0,0 +1,105 @@
+import type { Context } from '@nocobase/actions';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type PluginAiApiServer from '../plugin';
+import { handleChatCompletions } from '../routes/chat-completions';
+import { resolveModelString } from '../utils/resolve-service';
+
+vi.mock('../utils/resolve-service', () => ({
+  resolveModelString: vi.fn(),
+}));
+
+interface ModelResult {
+  content: string;
+  response_metadata?: Record<string, unknown>;
+  usage_metadata?: Record<string, unknown>;
+}
+
+function createContext(result: ModelResult): Context {
+  const model = {
+    invoke: vi.fn().mockResolvedValue(result),
+    modelKwargs: {},
+  };
+  class TestProvider {
+    createModel() {
+      return model;
+    }
+  }
+
+  return {
+    app: {
+      pm: {
+        get: vi.fn().mockReturnValue({
+          aiManager: {
+            llmProviders: new Map([['test-provider', { provider: TestProvider }]]),
+          },
+        }),
+      },
+    },
+    db: {
+      getRepository: vi.fn().mockReturnValue({ findOne: vi.fn().mockResolvedValue(null) }),
+    },
+    log: { error: vi.fn() },
+    request: {
+      body: {
+        model: 'test-service/test-model',
+        messages: [{ role: 'user', content: 'Hello' }],
+        stream: false,
+      },
+    },
+    state: {},
+    set: vi.fn(),
+  } as unknown as Context;
+}
+
+describe('AI API chat usage collection', () => {
+  beforeEach(() => {
+    vi.mocked(resolveModelString).mockResolvedValue({
+      service: {
+        enabled: true,
+        name: 'test-service',
+        options: {},
+        provider: 'test-provider',
+      },
+      modelId: 'test-model',
+    });
+  });
+
+  it('keeps the public zero fallback but marks missing provider usage as unavailable internally', async () => {
+    const ctx = createContext({ content: 'Hello back' });
+
+    await handleChatCompletions(ctx, {} as PluginAiApiServer);
+
+    expect(ctx.status).toBe(200);
+    expect((ctx.body as { usage: object }).usage).toEqual({
+      prompt_tokens: 0,
+      completion_tokens: 0,
+      total_tokens: 0,
+    });
+    expect(ctx.state.aiApiUsageResult).toMatchObject({
+      source: 'unavailable',
+      gatewayResponseId: expect.stringMatching(/^chatcmpl-/),
+    });
+  });
+
+  it('stores provider usage and provider request ID separately from the gateway response ID', async () => {
+    const ctx = createContext({
+      content: 'Hello back',
+      response_metadata: { request_id: 'provider-request-1' },
+      usage_metadata: { input_tokens: 8, output_tokens: 3, total_tokens: 11 },
+    });
+
+    await handleChatCompletions(ctx, {} as PluginAiApiServer);
+
+    expect((ctx.body as { usage: object }).usage).toEqual({
+      prompt_tokens: 8,
+      completion_tokens: 3,
+      total_tokens: 11,
+    });
+    expect(ctx.state.aiApiUsageResult).toMatchObject({
+      source: 'provider',
+      providerRequestId: 'provider-request-1',
+      gatewayResponseId: expect.stringMatching(/^chatcmpl-/),
+      usage: { prompt_tokens: 8, completion_tokens: 3, total_tokens: 11 },
+    });
+  });
+});

package/src/server/__tests__/usage.test.ts

@@ -0,0 +1,201 @@
+import type { Context } from '@nocobase/actions';
+import { describe, expect, it, vi } from 'vitest';
+import { authenticateBearer } from '../routes/auth';
+import {
+  extractProviderRequestId,
+  finishUsageRecord,
+  normalizeUsage,
+  setAiApiUsageResult,
+  setAiApiUsageUnavailable,
+  startUsageRecord,
+} from '../usage';
+
+function createContext(overrides: Record<string, unknown> = {}): Context {
+  return {
+    state: {},
+    request: { body: {} },
+    ...overrides,
+  } as unknown as Context;
+}
+
+describe('AI API usage normalization', () => {
+  it('normalizes LangChain fields and derives a missing total', () => {
+    expect(normalizeUsage({ input_tokens: 12, output_tokens: 5 })).toEqual({
+      prompt_tokens: 12,
+      completion_tokens: 5,
+      total_tokens: 17,
+    });
+  });
+
+  it('preserves explicit zero usage from a provider', () => {
+    expect(normalizeUsage({ prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 })).toEqual({
+      prompt_tokens: 0,
+      completion_tokens: 0,
+      total_tokens: 0,
+    });
+  });
+
+  it('rejects synthetic or invalid usage values', () => {
+    expect(normalizeUsage(undefined)).toBeUndefined();
+    expect(normalizeUsage({ prompt_tokens: '12', completion_tokens: -1, total_tokens: Number.NaN })).toBeUndefined();
+    expect(normalizeUsage({ prompt_tokens: Number.MAX_SAFE_INTEGER + 1 })).toBeUndefined();
+  });
+
+  it('extracts a provider request ID only from provider metadata', () => {
+    expect(extractProviderRequestId({ id: 'gateway-id', response_metadata: { request_id: 'provider-id' } })).toBe(
+      'provider-id',
+    );
+    expect(extractProviderRequestId({ id: 'gateway-id' })).toBeUndefined();
+  });
+});
+
+describe('AI API usage persistence', () => {
+  it('preserves the authenticated BIGINT identifier without Number or String coercion', async () => {
+    const create = vi.fn().mockResolvedValue({ id: 91 });
+    const ctx = createContext({
+      state: {
+        currentUser: { id: '9007199254740993' },
+        currentRole: 'member',
+        aiApiAuthType: 'bearer',
+      },
+      request: {
+        body: {
+          messages: [{ role: 'user', content: 'Hello' }],
+          max_tokens: 100,
+          max_completion_tokens: 200,
+        },
+      },
+      db: { getRepository: vi.fn().mockReturnValue({ create }) },
+    });
+
+    await expect(startUsageRecord(ctx, 'req-1', '/chat/completions', 'service/model', false, 'llm')).resolves.toBe(91);
+    expect(create).toHaveBeenCalledWith({
+      values: expect.objectContaining({
+        userId: '9007199254740993',
+        authType: 'bearer',
+        requestMetadata: {
+          messageCount: 1,
+          promptCount: undefined,
+          embeddingInputCount: undefined,
+          requestedMaxTokens: 200,
+        },
+      }),
+    });
+  });
+
+  it('refuses to create a usage record without an authenticated user ID', async () => {
+    const ctx = createContext({
+      db: { getRepository: vi.fn() },
+    });
+
+    await expect(startUsageRecord(ctx, 'req-1', '/chat/completions', 'service/model', false, 'llm')).rejects.toThrow(
+      'requires an authenticated NocoBase user ID',
+    );
+  });
+
+  it('stores real provider usage and separates provider and gateway IDs', async () => {
+    const update = vi.fn().mockResolvedValue(undefined);
+    const ctx = createContext({
+      status: 200,
+      body: { id: 'gateway-body-id' },
+      db: { getRepository: vi.fn().mockReturnValue({ update }) },
+    });
+
+    setAiApiUsageResult(
+      ctx,
+      { input_tokens: 20, output_tokens: 4 },
+      {
+        gatewayResponseId: 'gateway-result-id',
+        providerRequestId: 'provider-id',
+      },
+    );
+    await finishUsageRecord(ctx, 1, Date.now() - 10, 'succeeded');
+
+    expect(update).toHaveBeenCalledWith({
+      filterByTk: 1,
+      values: expect.objectContaining({
+        status: 'succeeded',
+        inputTokens: 20,
+        outputTokens: 4,
+        totalTokens: 24,
+        providerRequestId: 'provider-id',
+        responseMetadata: { usageSource: 'provider', gatewayResponseId: 'gateway-result-id' },
+      }),
+    });
+  });
+
+  it('does not persist synthetic zeroes when provider usage is unavailable', async () => {
+    const update = vi.fn().mockResolvedValue(undefined);
+    const ctx = createContext({
+      status: 200,
+      body: {
+        id: 'gateway-id',
+        usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+      },
+      db: { getRepository: vi.fn().mockReturnValue({ update }) },
+    });
+
+    setAiApiUsageUnavailable(ctx, 'gateway-id');
+    await finishUsageRecord(ctx, 2, Date.now() - 10, 'succeeded');
+
+    expect(update).toHaveBeenCalledWith({
+      filterByTk: 2,
+      values: expect.objectContaining({
+        inputTokens: null,
+        outputTokens: null,
+        totalTokens: null,
+        providerRequestId: null,
+        responseMetadata: { usageSource: 'unavailable', gatewayResponseId: 'gateway-id' },
+      }),
+    });
+  });
+
+  it('uses streaming execution state to persist a failed stream', async () => {
+    const update = vi.fn().mockResolvedValue(undefined);
+    const ctx = createContext({
+      status: 200,
+      state: {
+        aiApiStreamResult: { succeeded: false, id: 'gateway-stream-id', errorCode: 'stream_error' },
+      },
+      db: { getRepository: vi.fn().mockReturnValue({ update }) },
+    });
+
+    await finishUsageRecord(ctx, 3, Date.now() - 10, 'succeeded');
+
+    expect(update).toHaveBeenCalledWith({
+      filterByTk: 3,
+      values: expect.objectContaining({
+        status: 'failed',
+        httpStatus: 200,
+        errorCode: 'stream_error',
+        responseMetadata: { usageSource: 'unavailable', gatewayResponseId: 'gateway-stream-id' },
+      }),
+    });
+  });
+});
+
+describe('AI API authentication provenance', () => {
+  it('classifies a pre-authenticated NocoBase principal as bearer rather than session', async () => {
+    const ctx = createContext({
+      state: { currentUser: { id: 1 }, currentRole: 'member' },
+      get: vi.fn((name: string) => (name === 'Authorization' ? 'Bearer token' : '')),
+    });
+
+    await expect(authenticateBearer(ctx)).resolves.toBe(true);
+    expect(ctx.state.aiApiAuthType).toBe('bearer');
+  });
+
+  it('classifies a principal as OIDC only when verified OAuth state is present', async () => {
+    const ctx = createContext({
+      state: {
+        currentUser: { id: 1 },
+        currentRole: 'member',
+        oauthPrincipal: { subject: '1', clientId: 'client-1' },
+      },
+      get: vi.fn((name: string) => (name === 'Authorization' ? 'Bearer token' : '')),
+    });
+
+    await expect(authenticateBearer(ctx)).resolves.toBe(true);
+    expect(ctx.state.aiApiAuthType).toBe('oidc');
+  });
+});

package/src/server/collections/ai-api-usage-records.ts

@@ -5,7 +5,15 @@ export default defineCollection({
   autoGenId: true,
   fields: [
     { name: 'requestId', type: 'string', unique: true, index: true },
-    { name: 'userId', type: 'string', index: true },
+    { name: 'userId', type: 'bigInt', allowNull: false, index: true },
+    {
+      name: 'user',
+      type: 'belongsTo',
+      target: 'users',
+      targetKey: 'id',
+      foreignKey: 'userId',
+      constraints: false,
+    },
     { name: 'roleName', type: 'string', index: true },
     { name: 'authType', type: 'string', index: true },
     { name: 'oauthClientId', type: 'string', allowNull: true, index: true },