@tuturuuu/ai 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tuturuuu/ai",
   "license": "MIT",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/tutur3u/platform",
@@ -76,9 +76,9 @@
     "@streamdown/math": "^1.0.2",
     "@streamdown/mermaid": "^1.0.2",
     "@tuturuuu/google": "0.1.0",
-    "@tuturuuu/internal-api": "0.22.0",
+    "@tuturuuu/internal-api": "0.23.0",
     "@tuturuuu/supabase": "0.5.0",
-    "@tuturuuu/utils": "0.18.0",
+    "@tuturuuu/utils": "0.19.0",
     "@vercel/sandbox": "^2.8.0",
     "@zernio/chat-sdk-adapter": "^0.4.0",
     "ai": "^7.0.36",
@@ -103,7 +103,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@tuturuuu/types": "0.21.0",
+    "@tuturuuu/types": "0.22.0",
     "@tuturuuu/typescript-config": "0.1.1",
     "@types/node": "^26.1.1",
     "@types/qrcode": "^1.5.6",

package/src/api-key-hash.ts

@@ -1,8 +1,51 @@
-import { scrypt, timingSafeEqual } from 'node:crypto';
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
 
 const scryptAsync = promisify(scrypt);
 const KEY_DERIVATION_LENGTH = 64;
+const AI_KEY_PREFIX = 'ttr_ai_';
+const KEY_LOOKUP_BYTES = 8;
+const KEY_SECRET_BYTES = 32;
+
+export type GeneratedAiApiKey = {
+  hash: string;
+  prefix: string;
+  secret: string;
+};
+
+export async function hashApiKey(key: string): Promise<string> {
+  const salt = randomBytes(16).toString('hex');
+  const derivedKey = (await scryptAsync(
+    key,
+    salt,
+    KEY_DERIVATION_LENGTH
+  )) as Buffer;
+
+  return `${salt}:${derivedKey.toString('hex')}`;
+}
+
+export async function generateAiApiKey(): Promise<GeneratedAiApiKey> {
+  const prefix = `${AI_KEY_PREFIX}${randomBytes(KEY_LOOKUP_BYTES).toString('hex')}`;
+  const secret = `${prefix}_${randomBytes(KEY_SECRET_BYTES).toString('base64url')}`;
+
+  return {
+    hash: await hashApiKey(secret),
+    prefix,
+    secret,
+  };
+}
+
+export function extractAiApiKeyPrefix(key: string): string | null {
+  if (!key.startsWith(AI_KEY_PREFIX)) return null;
+
+  const separatorIndex = key.indexOf('_', AI_KEY_PREFIX.length);
+  if (separatorIndex === -1) return null;
+
+  const prefix = key.slice(0, separatorIndex);
+  return prefix.length === AI_KEY_PREFIX.length + KEY_LOOKUP_BYTES * 2
+    ? prefix
+    : null;
+}
 
 export async function validateApiKeyHash(
   key: string,

package/src/studio/auth.ts

@@ -0,0 +1,73 @@
+import { createAdminClient } from '@tuturuuu/supabase/next/server';
+import type { Tables } from '@tuturuuu/types';
+import { extractAiApiKeyPrefix, validateApiKeyHash } from '../api-key-hash';
+import { AiStudioError } from './errors';
+
+export type AiStudioApiKey = Tables<
+  { schema: 'private' },
+  'ai_studio_api_keys'
+>;
+
+export type AiStudioCredential = {
+  apiKey: AiStudioApiKey;
+  actorId: string;
+  workspaceId: string;
+};
+
+function readBearerToken(request: Request): string {
+  const authorization = request.headers.get('authorization');
+  if (!authorization?.startsWith('Bearer ')) {
+    throw new AiStudioError('A Tuturuuu AI API key is required.', {
+      code: 'invalid_api_key',
+      status: 401,
+      type: 'authentication_error',
+    });
+  }
+
+  return authorization.slice('Bearer '.length).trim();
+}
+
+export async function authenticateAiStudioRequest(
+  request: Request
+): Promise<AiStudioCredential> {
+  const secret = readBearerToken(request);
+  const prefix = extractAiApiKeyPrefix(secret);
+  if (!prefix) {
+    throw new AiStudioError('The supplied API key is invalid.', {
+      code: 'invalid_api_key',
+      status: 401,
+      type: 'authentication_error',
+    });
+  }
+
+  const sbAdmin = await createAdminClient({ noCookie: true });
+  const { data: apiKey, error } = await sbAdmin
+    .schema('private')
+    .from('ai_studio_api_keys')
+    .select('*')
+    .eq('prefix', prefix)
+    .maybeSingle();
+
+  const expired =
+    apiKey?.expires_at && new Date(apiKey.expires_at).getTime() <= Date.now();
+  const valid =
+    apiKey &&
+    !error &&
+    !apiKey.revoked_at &&
+    !expired &&
+    (await validateApiKeyHash(secret, apiKey.secret_hash));
+
+  if (!valid || !apiKey.created_by) {
+    throw new AiStudioError('The supplied API key is invalid or inactive.', {
+      code: 'invalid_api_key',
+      status: 401,
+      type: 'authentication_error',
+    });
+  }
+
+  return {
+    apiKey,
+    actorId: apiKey.created_by,
+    workspaceId: apiKey.ws_id,
+  };
+}

package/src/studio/errors.ts

@@ -0,0 +1,58 @@
+export type AiStudioErrorCode =
+  | 'invalid_api_key'
+  | 'insufficient_credits'
+  | 'invalid_request_error'
+  | 'model_not_found'
+  | 'rate_limit_exceeded'
+  | 'server_error';
+
+export class AiStudioError extends Error {
+  readonly code: AiStudioErrorCode;
+  readonly status: number;
+  readonly type: string;
+
+  constructor(
+    message: string,
+    {
+      code,
+      status,
+      type = 'invalid_request_error',
+    }: {
+      code: AiStudioErrorCode;
+      status: number;
+      type?: string;
+    }
+  ) {
+    super(message);
+    this.name = 'AiStudioError';
+    this.code = code;
+    this.status = status;
+    this.type = type;
+  }
+}
+
+export function toOpenAiError(error: unknown, requestId?: string) {
+  const studioError =
+    error instanceof AiStudioError
+      ? error
+      : new AiStudioError('The request could not be completed.', {
+          code: 'server_error',
+          status: 500,
+          type: 'server_error',
+        });
+
+  return Response.json(
+    {
+      error: {
+        code: studioError.code,
+        message: studioError.message,
+        param: null,
+        type: studioError.type,
+      },
+    },
+    {
+      status: studioError.status,
+      headers: requestId ? { 'x-request-id': requestId } : undefined,
+    }
+  );
+}

package/src/studio/metering.ts

@@ -0,0 +1,247 @@
+import { createAdminClient } from '@tuturuuu/supabase/next/server';
+import type { Json } from '@tuturuuu/types';
+import { AiStudioError } from './errors';
+
+export type AiStudioRunReservation = {
+  reservationId: string;
+  runId: string;
+};
+
+export type ExternalAiStudioRun = {
+  runId: string;
+};
+
+export type AiStudioUsageCost = {
+  billedCredits: number;
+  providerCostUsd: number;
+};
+
+export type CalculateAiStudioUsageCostInput = {
+  imageCount?: number;
+  inputTokens?: number;
+  modelId: string;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  searchCount?: number;
+  workspaceId: string;
+};
+
+export async function calculateAiStudioUsageCost(
+  input: CalculateAiStudioUsageCostInput
+): Promise<AiStudioUsageCost> {
+  const sbAdmin = await createAdminClient({ noCookie: true });
+  const { data, error } = await sbAdmin
+    .schema('private')
+    .rpc('calculate_ai_studio_usage_cost', {
+      p_image_count: input.imageCount ?? 0,
+      p_input_tokens: input.inputTokens ?? 0,
+      p_model_id: input.modelId,
+      p_output_tokens: input.outputTokens ?? 0,
+      p_reasoning_tokens: input.reasoningTokens ?? 0,
+      p_search_count: input.searchCount ?? 0,
+      p_ws_id: input.workspaceId,
+    });
+
+  const cost = data?.[0];
+  if (error || !cost) {
+    throw new AiStudioError('AI usage cost could not be calculated.', {
+      code: 'server_error',
+      status: 500,
+      type: 'server_error',
+    });
+  }
+
+  return {
+    billedCredits: Number(cost.billed_credits),
+    providerCostUsd: Number(cost.provider_cost_usd),
+  };
+}
+
+export type BeginAiStudioRunInput = {
+  actorId: string;
+  apiKeyId: string;
+  feature: string;
+  idempotencyKey?: string | null;
+  metadata?: Json;
+  modelId: string;
+  requestId: string;
+  reservedCredits: number;
+  workspaceId: string;
+};
+
+function reservationError(code: string | null): AiStudioError {
+  if (code === 'MODEL_NOT_ALLOWED') {
+    return new AiStudioError('This model is not enabled for the workspace.', {
+      code: 'model_not_found',
+      status: 404,
+    });
+  }
+  if (code === 'RATE_LIMIT_EXCEEDED') {
+    return new AiStudioError('The API key rate limit has been reached.', {
+      code: 'rate_limit_exceeded',
+      status: 429,
+      type: 'rate_limit_error',
+    });
+  }
+  if (
+    code === 'KEY_BUDGET_EXCEEDED' ||
+    code === 'WORKSPACE_BUDGET_EXCEEDED' ||
+    code === 'INSUFFICIENT_CREDITS'
+  ) {
+    return new AiStudioError('The workspace has insufficient AI credits.', {
+      code: 'insufficient_credits',
+      status: 402,
+    });
+  }
+
+  return new AiStudioError('The request could not reserve AI credits.', {
+    code: 'server_error',
+    status: 500,
+    type: 'server_error',
+  });
+}
+
+export async function beginAiStudioRun(
+  input: BeginAiStudioRunInput
+): Promise<AiStudioRunReservation> {
+  const sbAdmin = await createAdminClient({ noCookie: true });
+  const { data, error } = await sbAdmin
+    .schema('private')
+    .rpc('begin_ai_studio_run', {
+      p_api_key_id: input.apiKeyId,
+      p_feature: input.feature,
+      p_idempotency_key: input.idempotencyKey ?? undefined,
+      p_metadata: input.metadata,
+      p_model_id: input.modelId,
+      p_request_id: input.requestId,
+      p_reserved_credits: input.reservedCredits,
+      p_user_id: input.actorId,
+      p_ws_id: input.workspaceId,
+    });
+
+  const result = data?.[0];
+  if (error || !result?.success || !result.run_id || !result.reservation_id) {
+    throw reservationError(result?.error_code ?? null);
+  }
+
+  return {
+    reservationId: result.reservation_id,
+    runId: result.run_id,
+  };
+}
+
+export type BeginExternalAiStudioRunInput = {
+  actorId: string;
+  externalAppId: string;
+  feature: string;
+  idempotencyKey?: string | null;
+  metadata?: Json;
+  modelId: string;
+  requestId: string;
+  workspaceId: string;
+};
+
+export async function beginExternalAiStudioRun(
+  input: BeginExternalAiStudioRunInput
+): Promise<ExternalAiStudioRun> {
+  const sbAdmin = await createAdminClient({ noCookie: true });
+  const { data, error } = await sbAdmin
+    .schema('private')
+    .rpc('begin_external_ai_studio_run', {
+      p_external_app_id: input.externalAppId,
+      p_feature: input.feature,
+      p_idempotency_key: input.idempotencyKey ?? undefined,
+      p_metadata: input.metadata,
+      p_model_id: input.modelId,
+      p_request_id: input.requestId,
+      p_user_id: input.actorId,
+      p_ws_id: input.workspaceId,
+    });
+
+  const result = data?.[0];
+  if (error || !result?.success || !result.run_id) {
+    throw reservationError(result?.error_code ?? null);
+  }
+
+  return { runId: result.run_id };
+}
+
+export type SettleAiStudioRunInput = {
+  actualCredits: number;
+  embeddingUnits?: number;
+  errorClass?: string | null;
+  errorMessage?: string | null;
+  firstTokenLatencyMs?: number | null;
+  imageUnits?: number;
+  inputTokens?: number;
+  latencyMs?: number | null;
+  metadata?: Json;
+  outputTokens?: number;
+  providerCostUsd?: number;
+  reasoningTokens?: number;
+  runId: string;
+  status: 'aborted' | 'failed' | 'succeeded';
+};
+
+export async function settleAiStudioRun(
+  input: SettleAiStudioRunInput
+): Promise<void> {
+  const sbAdmin = await createAdminClient({ noCookie: true });
+  const { data, error } = await sbAdmin
+    .schema('private')
+    .rpc('settle_ai_studio_run', {
+      p_actual_credits: input.actualCredits,
+      p_embedding_units: input.embeddingUnits ?? 0,
+      p_error_class: input.errorClass ?? undefined,
+      p_error_message: input.errorMessage ?? undefined,
+      p_first_token_latency_ms: input.firstTokenLatencyMs ?? undefined,
+      p_image_units: input.imageUnits ?? 0,
+      p_input_tokens: input.inputTokens ?? 0,
+      p_latency_ms: input.latencyMs ?? undefined,
+      p_metadata: input.metadata,
+      p_output_tokens: input.outputTokens ?? 0,
+      p_provider_cost_usd: input.providerCostUsd ?? 0,
+      p_reasoning_tokens: input.reasoningTokens ?? 0,
+      p_run_id: input.runId,
+      p_status: input.status,
+    });
+
+  if (error || !data?.[0]?.success) {
+    throw new AiStudioError('AI usage could not be settled.', {
+      code: 'server_error',
+      status: 500,
+      type: 'server_error',
+    });
+  }
+}
+
+export async function settleExternalAiStudioRun(
+  input: Omit<SettleAiStudioRunInput, 'actualCredits'>
+): Promise<void> {
+  const sbAdmin = await createAdminClient({ noCookie: true });
+  const { data, error } = await sbAdmin
+    .schema('private')
+    .rpc('settle_external_ai_studio_run', {
+      p_embedding_units: input.embeddingUnits ?? 0,
+      p_error_class: input.errorClass ?? undefined,
+      p_error_message: input.errorMessage ?? undefined,
+      p_first_token_latency_ms: input.firstTokenLatencyMs ?? undefined,
+      p_image_units: input.imageUnits ?? 0,
+      p_input_tokens: input.inputTokens ?? 0,
+      p_latency_ms: input.latencyMs ?? undefined,
+      p_metadata: input.metadata,
+      p_output_tokens: input.outputTokens ?? 0,
+      p_provider_cost_usd: input.providerCostUsd ?? 0,
+      p_reasoning_tokens: input.reasoningTokens ?? 0,
+      p_run_id: input.runId,
+      p_status: input.status,
+    });
+
+  if (error || !data?.[0]?.success) {
+    throw new AiStudioError('External-app AI usage could not be settled.', {
+      code: 'server_error',
+      status: 500,
+      type: 'server_error',
+    });
+  }
+}

package/src/studio/request.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from 'node:crypto';
+
+export function getAiStudioRequestId(request: Request): string {
+  return request.headers.get('x-request-id')?.slice(0, 128) || randomUUID();
+}
+
+export function getIdempotencyKey(request: Request): string | null {
+  return request.headers.get('idempotency-key')?.slice(0, 255) || null;
+}
+
+export function getRequestDurationMs(startedAt: number): number {
+  return Math.max(0, Math.round(performance.now() - startedAt));
+}