@windrun-huaiin/backend-core 15.1.0 → 17.0.0

package/src/services/ai/env.ts

@@ -0,0 +1,120 @@
+import type { AIMockHandler, AIRuntimeContext, OpenRouterClientConfig } from './types';
+import { createScenarioMockHandler } from './mock';
+
+function parseNumber(value: string | undefined, fallback: number) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function parseBoolean(value: string | undefined, fallback: boolean) {
+  if (value === undefined) {
+    return fallback;
+  }
+
+  return value === '1' || value === 'true' || value === 'TRUE';
+}
+
+export type OpenRouterEnvConfig = {
+  appName: string;
+  timeoutMs: number;
+  apiKey: string;
+  modelName: string;
+  enableMock: boolean;
+  mockType: number;
+  mockTimeoutSeconds: number;
+  mockStreamChunkDelayMs: number;
+  mockStreamChunkSize: number;
+  contextWindowTurns: number;
+  debug: boolean;
+  baseUrl?: string;
+  referer?: string;
+};
+
+type RequestMockOverride = {
+  enabled?: boolean;
+  type?: number;
+  timeoutSeconds?: number;
+  chunkDelayMs?: number;
+  chunkSize?: number;
+};
+
+export function getOpenRouterEnvConfig(): OpenRouterEnvConfig {
+  return {
+    appName: process.env.NEXT_PUBLIC_APP_NAME || 'DDaaS',
+    timeoutMs: parseNumber(process.env.OPENROUTER_TIMEOUT_SECONDS, 240) * 1000,
+    apiKey: process.env.OPENROUTER_API_KEY || '',
+    modelName:
+      process.env.NEXT_PUBLIC_OPENROUTER_MODEL_NAME || 'google/gemini-2.0-flash-001',
+    enableMock: parseBoolean(process.env.OPENROUTER_ENABLE_MOCK, true),
+    mockType: parseNumber(process.env.OPENROUTER_MOCK_TYPE, 0),
+    mockTimeoutSeconds: parseNumber(process.env.OPENROUTER_MOCK_TIMEOUT_SECONDS, 3),
+    mockStreamChunkDelayMs: parseNumber(process.env.OPENROUTER_MOCK_STREAM_CHUNK_DELAY_MS, 60),
+    mockStreamChunkSize: parseNumber(process.env.OPENROUTER_MOCK_STREAM_CHUNK_SIZE, 8),
+    contextWindowTurns: parseNumber(process.env.NEXT_PUBLIC_CHAT_CONTEXT_WINDOW_TURNS, 6),
+    debug: parseBoolean(process.env.NEXT_PUBLIC_OPENROUTER_DEBUG, false),
+    baseUrl: process.env.OPENROUTER_BASE_URL,
+    referer: process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000',
+  };
+}
+
+export function createOpenRouterClientConfigFromEnv(
+  overrides?: Partial<OpenRouterClientConfig>,
+): OpenRouterClientConfig {
+  const envConfig = getOpenRouterEnvConfig();
+
+  return {
+    apiKey: overrides?.apiKey ?? envConfig.apiKey,
+    baseUrl: overrides?.baseUrl ?? envConfig.baseUrl,
+    defaultModel: overrides?.defaultModel ?? envConfig.modelName,
+    referer: overrides?.referer ?? envConfig.referer,
+    title: overrides?.title ?? envConfig.appName,
+    timeoutMs: overrides?.timeoutMs ?? envConfig.timeoutMs,
+    provider: overrides?.provider,
+    temperature: overrides?.temperature,
+    maxTokens: overrides?.maxTokens,
+    fetchImpl: overrides?.fetchImpl,
+  };
+}
+
+export function createOpenRouterMockFromEnv(): AIMockHandler | undefined {
+  return createOpenRouterMockFromEnvForContext();
+}
+
+function getRequestMockOverride(context?: AIRuntimeContext): RequestMockOverride | null {
+  const value = context?.input.metadata?.mock;
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+
+  return value as RequestMockOverride;
+}
+
+export function createOpenRouterMockFromEnvForContext(
+  context?: AIRuntimeContext,
+): AIMockHandler | undefined {
+  const envConfig = getOpenRouterEnvConfig();
+
+  if (!envConfig.enableMock) {
+    return undefined;
+  }
+
+  const requestOverride = getRequestMockOverride(context);
+  if (requestOverride?.enabled === false) {
+    return undefined;
+  }
+
+  const mockType = requestOverride?.type ?? envConfig.mockType;
+  const mockTimeoutSeconds = requestOverride?.timeoutSeconds ?? envConfig.mockTimeoutSeconds;
+  const mockStreamChunkDelayMs =
+    requestOverride?.chunkDelayMs ?? envConfig.mockStreamChunkDelayMs;
+  const mockStreamChunkSize = requestOverride?.chunkSize ?? envConfig.mockStreamChunkSize;
+
+  return createScenarioMockHandler({
+    text:
+      'This is a mock AI response from the shared backend-core runtime. Configure OPENROUTER_API_KEY and disable OPENROUTER_ENABLE_MOCK to use the real upstream model.',
+    mockType,
+    mockTimeoutSeconds,
+    mockStreamChunkDelayMs,
+    mockStreamChunkSize,
+  });
+}

package/src/services/ai/error.ts

@@ -0,0 +1,64 @@
+import {
+  createAIErrorPayload,
+  type AIErrorPayload,
+} from '@windrun-huaiin/contracts/ai';
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function getProviderErrorMessage(data: unknown) {
+  if (!isObject(data)) {
+    return null;
+  }
+
+  const error = data.error;
+  if (isObject(error) && typeof error.message === 'string') {
+    return error.message;
+  }
+
+  if (typeof data.message === 'string') {
+    return data.message;
+  }
+
+  return null;
+}
+
+function isAbortError(error: unknown) {
+  return error instanceof DOMException && error.name === 'AbortError';
+}
+
+export function normalizeAIError(error: unknown): AIErrorPayload {
+  if (isObject(error) && typeof error.status === 'number') {
+    const message =
+      getProviderErrorMessage(error) ??
+      (typeof error.message === 'string' ? error.message : 'Error communicating with AI');
+
+    return createAIErrorPayload({
+      message,
+      upstreamStatusCode: error.status,
+    });
+  }
+
+  if (error instanceof Response) {
+    return createAIErrorPayload({
+      message: error.statusText || 'Error communicating with AI',
+      upstreamStatusCode: error.status || 500,
+    });
+  }
+
+  if (isAbortError(error)) {
+    return {
+      error: 'Request timed out',
+      status: 'timeout',
+      upstreamStatusCode: 408,
+    };
+  }
+
+  return {
+    error: error instanceof Error ? error.message : 'Error communicating with AI',
+    status: 'failed',
+    failureReason: 'unknown',
+    upstreamStatusCode: 500,
+  };
+}

package/src/services/ai/index.ts

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './abort';
+export * from './error';
+export * from './env';
+export * from './message-builder';
+export * from './mock';
+export * from './openrouter-client';
+export * from './route';

package/src/services/ai/message-builder.ts

@@ -0,0 +1,17 @@
+import {
+  getMessageText,
+  type AIRuntimeRequest,
+} from '@windrun-huaiin/contracts/ai';
+import type { OpenRouterRequestBody } from './types';
+
+export function buildModelMessages(
+  messages: AIRuntimeRequest['messages'],
+): OpenRouterRequestBody['messages'] {
+  return messages
+    .filter((message) => message.status !== 'failed')
+    .map((message) => ({
+      role: message.role,
+      content: getMessageText(message),
+    }))
+    .filter((message) => message.content.trim().length > 0);
+}

package/src/services/ai/mock.ts

@@ -0,0 +1,378 @@
+import {
+  createAIErrorPayload,
+  type AIStreamEvent,
+} from '@windrun-huaiin/contracts/ai';
+import type { AIMockHandler, AIRuntimeContext } from './types';
+
+const streamingHeaders = {
+  'Content-Type': 'text/event-stream; charset=utf-8',
+  'Cache-Control': 'no-cache, no-store, max-age=0, must-revalidate, no-transform',
+  Connection: 'keep-alive',
+  Pragma: 'no-cache',
+  'X-Accel-Buffering': 'no',
+} as const;
+
+function encodeEvent(event: AIStreamEvent) {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+function createStreamResponse(events: AIStreamEvent[]) {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const event of events) {
+        controller.enqueue(encoder.encode(encodeEvent(event)));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: streamingHeaders,
+  });
+}
+
+export function createSimpleMockHandler(text: string): AIMockHandler {
+  return (context: AIRuntimeContext) => {
+    const messageId = `mock-${context.requestId}`;
+    return createStreamResponse([
+      {
+        type: 'message_started',
+        messageId,
+        createdAt: Date.now(),
+      },
+      {
+        type: 'text_delta',
+        messageId,
+        text,
+      },
+      {
+        type: 'message_completed',
+        messageId,
+        createdAt: Date.now(),
+      },
+    ]);
+  };
+}
+
+export function createErrorMockResponse(statusCode: number, message: string) {
+  return Response.json(
+    createAIErrorPayload({
+      message,
+      upstreamStatusCode: statusCode,
+    }),
+    { status: statusCode },
+  );
+}
+
+type MockFailureType = 'timeout' | 'request_aborted' | 'stream_error';
+
+type MockScenario = {
+  mode?: 'text_stream' | 'event_sequence';
+  initialDelayMs?: number;
+  streamFailureType?: MockFailureType;
+  streamFailureAfterChunks?: number;
+  immediateErrorType?: MockFailureType;
+};
+
+export type ConfigurableMockOptions = {
+  text: string;
+  initialDelayMs?: number;
+  chunkDelayMs?: number;
+  chunkSize?: number;
+  streamFailureType?: MockFailureType;
+  streamFailureAfterChunks?: number;
+};
+
+export function getMockScenario(mockType: number, mockTimeoutMs: number): MockScenario {
+  switch (mockType) {
+    case 1:
+      return {
+        mode: 'text_stream',
+        initialDelayMs: mockTimeoutMs,
+      };
+    case 2:
+      return {
+        mode: 'text_stream',
+        immediateErrorType: 'timeout',
+      };
+    case 3:
+      return {
+        mode: 'text_stream',
+        streamFailureType: 'timeout',
+        streamFailureAfterChunks: 3,
+      };
+    case 4:
+      return {
+        mode: 'text_stream',
+        streamFailureType: 'request_aborted',
+        streamFailureAfterChunks: 3,
+      };
+    case 5:
+      return {
+        mode: 'text_stream',
+        streamFailureType: 'stream_error',
+        streamFailureAfterChunks: 3,
+      };
+    case 6:
+      return {
+        mode: 'event_sequence',
+      };
+    case 7:
+      return {
+        mode: 'event_sequence',
+      };
+    default:
+      return {
+        mode: 'text_stream',
+      };
+  }
+}
+
+async function sleep(delayInMs: number) {
+  await new Promise((resolve) => setTimeout(resolve, delayInMs));
+}
+
+function createMockErrorPayload(failureType: MockFailureType) {
+  if (failureType === 'timeout') {
+    return createAIErrorPayload({
+      message: 'Request timed out',
+      upstreamStatusCode: 408,
+    });
+  }
+
+  if (failureType === 'request_aborted') {
+    return createAIErrorPayload({
+      message: 'Request aborted',
+      upstreamStatusCode: 499,
+    });
+  }
+
+  return createAIErrorPayload({
+    message: 'Error communicating with AI',
+    upstreamStatusCode: 502,
+    failureReason: 'stream_error',
+  });
+}
+
+function createMockFailureResponse(failureType: MockFailureType) {
+  const payload = createMockErrorPayload(failureType);
+  return Response.json(payload, { status: payload.upstreamStatusCode ?? 500 });
+}
+
+function chunkTextByWords(text: string, chunkSize: number) {
+  const wordChunks = text.match(/\S+\s*/g) ?? [text];
+  const normalizedChunkSize = Math.max(1, chunkSize);
+  const chunks: string[] = [];
+
+  for (let index = 0; index < wordChunks.length; index += normalizedChunkSize) {
+    chunks.push(wordChunks.slice(index, index + normalizedChunkSize).join(''));
+  }
+
+  return chunks;
+}
+
+export function createConfigurableMockHandler(options: ConfigurableMockOptions): AIMockHandler {
+  return async (context: AIRuntimeContext) => {
+    if ((options.initialDelayMs ?? 0) > 0) {
+      await sleep(options.initialDelayMs!);
+    }
+
+    const messageId = `mock-${context.requestId}`;
+    const chunks = chunkTextByWords(options.text, options.chunkSize ?? 4);
+    const chunkDelayMs = Math.max(0, options.chunkDelayMs ?? 0);
+    const failureAfterChunks = options.streamFailureAfterChunks ?? 0;
+    const encoder = new TextEncoder();
+
+    const stream = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        controller.enqueue(
+          encoder.encode(
+            encodeEvent({
+              type: 'message_started',
+              messageId,
+              createdAt: Date.now(),
+            }),
+          ),
+        );
+
+        for (let index = 0; index < chunks.length; index += 1) {
+          if (
+            options.streamFailureType &&
+            failureAfterChunks > 0 &&
+            index >= failureAfterChunks
+          ) {
+            controller.enqueue(
+              encoder.encode(
+                encodeEvent({
+                  type: 'error',
+                  error: createMockErrorPayload(options.streamFailureType),
+                }),
+              ),
+            );
+            controller.close();
+            return;
+          }
+
+          controller.enqueue(
+            encoder.encode(
+              encodeEvent({
+                type: 'text_delta',
+                messageId,
+                text: chunks[index],
+              }),
+            ),
+          );
+
+          if (chunkDelayMs > 0) {
+            await sleep(chunkDelayMs);
+          }
+        }
+
+        controller.enqueue(
+          encoder.encode(
+            encodeEvent({
+              type: 'message_completed',
+              messageId,
+              createdAt: Date.now(),
+            }),
+          ),
+        );
+        controller.close();
+      },
+    });
+
+    return new Response(stream, {
+      headers: streamingHeaders,
+    });
+  };
+}
+
+function createEventSequenceMockHandler(events: AIStreamEvent[]): AIMockHandler {
+  return async () => createStreamResponse(events);
+}
+
+function createMarkdownShowcaseEvents(messageId: string): AIStreamEvent[] {
+  return [
+    {
+      type: 'message_started',
+      messageId,
+      createdAt: Date.now(),
+    },
+    {
+      type: 'text_delta',
+      messageId,
+      text: [
+        '# Markdown Showcase',
+        '',
+        'This scenario verifies headings, lists, quotes, tables, code, and image rendering in the chat message body.',
+        '',
+        '## Bullet List',
+        '',
+        '- Bullet list item one',
+        '- Bullet list item two',
+        '',
+        '## Quote',
+        '',
+        '> Blockquote content for layout verification.',
+        '',
+        '## Table',
+        '',
+        '| Column | Value |',
+        '| --- | --- |',
+        '| Status | OK |',
+        '| Mode | Markdown |',
+        '',
+        '## Code',
+        '',
+        '```ts',
+        "const mode = 'markdown-showcase';",
+        'console.log(mode);',
+        '```',
+        '',
+        '## Image',
+        '',
+        '![Mock Image](https://r2.d8ger.com/default.webp)',
+      ].join('\n'),
+    },
+    {
+      type: 'message_completed',
+      messageId,
+      createdAt: Date.now(),
+    },
+  ];
+}
+
+function createTrophyCardShowcaseEvents(messageId: string): AIStreamEvent[] {
+  return [
+    {
+      type: 'message_started',
+      messageId,
+      createdAt: Date.now(),
+    },
+    {
+      type: 'text_delta',
+      messageId,
+      text: [
+        '# Trophy Card Showcase',
+        '',
+        'This scenario verifies a structured chat part rendered between normal markdown blocks.',
+        '',
+        'The card below is emitted as a dedicated `trophy_card` part, not as Markdown component syntax.',
+      ].join('\n'),
+    },
+    {
+      type: 'part',
+      messageId,
+      part: {
+        type: 'trophy_card',
+        title: 'Structured Trophy Card',
+        description: 'This is rendered from `MessagePart`, which is the recommended path for chat-specific rich blocks.\n\n- Reusable shared React component\n- Chat-specific structured part\n- Ready to extend to file, audio, and video cards',
+      },
+    },
+    {
+      type: 'text_delta',
+      messageId,
+      text: '\n\nUse this as the reference pattern for future file, audio, video, or tool result parts.',
+    },
+    {
+      type: 'message_completed',
+      messageId,
+      createdAt: Date.now(),
+    },
+  ];
+}
+
+export function createScenarioMockHandler(params: {
+  text: string;
+  mockType: number;
+  mockTimeoutSeconds: number;
+  mockStreamChunkDelayMs: number;
+  mockStreamChunkSize: number;
+}): AIMockHandler {
+  const scenario = getMockScenario(params.mockType, params.mockTimeoutSeconds * 1000);
+  const messageId = `mock-scenario-${params.mockType}`;
+
+  if (scenario.immediateErrorType) {
+    return async () => createMockFailureResponse(scenario.immediateErrorType!);
+  }
+
+  if (scenario.mode === 'event_sequence') {
+    if (params.mockType === 6) {
+      return createEventSequenceMockHandler(createMarkdownShowcaseEvents(messageId));
+    }
+
+    if (params.mockType === 7) {
+      return createEventSequenceMockHandler(createTrophyCardShowcaseEvents(messageId));
+    }
+  }
+
+  return createConfigurableMockHandler({
+    text: params.text,
+    initialDelayMs: scenario.initialDelayMs,
+    chunkDelayMs: params.mockStreamChunkDelayMs,
+    chunkSize: params.mockStreamChunkSize,
+    streamFailureType: scenario.streamFailureType,
+    streamFailureAfterChunks: scenario.streamFailureAfterChunks,
+  });
+}

package/src/services/ai/openrouter-client.ts

@@ -0,0 +1,94 @@
+import { normalizeAIError } from './error';
+import type {
+  OpenRouterClientConfig,
+  OpenRouterRequestBody,
+  OpenRouterStreamResult,
+} from './types';
+
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+
+export async function callOpenRouterStream(
+  config: OpenRouterClientConfig,
+  body: OpenRouterRequestBody,
+  signal: AbortSignal,
+): Promise<OpenRouterStreamResult> {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const response = await fetchImpl(`${config.baseUrl ?? OPENROUTER_BASE_URL}/chat/completions`, {
+    method: 'POST',
+    signal,
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      'Content-Type': 'application/json',
+      ...(config.referer ? { 'HTTP-Referer': config.referer } : {}),
+      ...(config.title ? { 'X-Title': config.title } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok || !response.body) {
+    let errorData: unknown = null;
+    try {
+      errorData = await response.clone().json();
+    } catch {
+      errorData = { message: response.statusText };
+    }
+
+    throw {
+      status: response.status,
+      message: response.statusText,
+      ...((typeof errorData === 'object' && errorData !== null) ? errorData : {}),
+    };
+  }
+
+  return {
+    response,
+    status: response.status,
+  };
+}
+
+export async function guardedOpenRouterStreamStart(
+  response: Response,
+) {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    return {
+      ok: false as const,
+      error: normalizeAIError(new Error('Empty upstream response body')),
+    };
+  }
+
+  const firstChunk = await reader.read();
+  if (firstChunk.done || !firstChunk.value) {
+    return {
+      ok: false as const,
+      error: {
+        error: 'AI returned an empty response',
+        status: 'failed' as const,
+        failureReason: 'empty_response' as const,
+        upstreamStatusCode: response.status,
+      },
+    };
+  }
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(firstChunk.value);
+    },
+    async pull(controller) {
+      const nextChunk = await reader.read();
+      if (nextChunk.done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(nextChunk.value);
+    },
+    cancel(reason) {
+      void reader.cancel(reason);
+    },
+  });
+
+  return {
+    ok: true as const,
+    stream,
+  };
+}