create-windy 0.3.2 → 0.3.5

package/template/packages/ai-client/src/embedding/client.ts

@@ -0,0 +1,96 @@
+import type {
+  EmbeddingClient,
+  EmbeddingFetch,
+  EmbeddingOperation,
+  EmbeddingInput,
+} from "./contracts.js";
+import { EmbeddingClientError, embeddingHttpError } from "./error.js";
+import { normalizeInputs, parseBatchResult } from "./validation.js";
+
+export interface EmbeddingClientOptions {
+  readonly baseUrl: string | URL;
+  readonly path?: string;
+  readonly fetch?: EmbeddingFetch;
+}
+
+export class HttpEmbeddingClient implements EmbeddingClient {
+  readonly #baseUrl: URL;
+  readonly #path: string;
+  readonly #fetch: EmbeddingFetch;
+
+  constructor(options: EmbeddingClientOptions) {
+    this.#baseUrl = new URL(options.baseUrl);
+    if (!["http:", "https:"].includes(this.#baseUrl.protocol)) {
+      throw invalidConfiguration("Embedding Client 只允许 HTTP 或 HTTPS");
+    }
+    this.#path = options.path ?? "/api/embeddings";
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async embed<Options>(
+    operation: EmbeddingOperation<Options>,
+    input: {
+      readonly items: readonly EmbeddingInput[];
+      readonly options?: Options;
+    },
+    context: { readonly idempotencyKey: string; readonly signal?: AbortSignal },
+  ) {
+    if (!operation.key.trim() || !context.idempotencyKey.trim()) {
+      throw invalidConfiguration("Embedding Operation 与幂等键不能为空");
+    }
+    const items = normalizeInputs(input.items);
+    const options =
+      input.options === undefined
+        ? undefined
+        : (operation.parseOptions?.(input.options) ?? input.options);
+    let response: Response;
+    try {
+      response = await this.#fetch(new URL(this.#path, this.#baseUrl), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "idempotency-key": context.idempotencyKey,
+        },
+        body: JSON.stringify({
+          operationKey: operation.key,
+          items,
+          ...(options === undefined ? {} : { options }),
+        }),
+        signal: context.signal,
+      });
+    } catch (error) {
+      throw new EmbeddingClientError(
+        context.signal?.aborted ? "RUN_CANCELLED" : "RUNTIME_UNAVAILABLE",
+        context.signal?.aborted
+          ? "Embedding 请求已取消"
+          : "Embedding Runtime 暂不可用",
+        !context.signal?.aborted,
+        undefined,
+        { cause: error },
+      );
+    }
+    if (!response.ok) {
+      throw await embeddingHttpError(response, "Embedding 请求失败");
+    }
+    const result = parseBatchResult(await response.json());
+    if (
+      result.items.length !== items.length ||
+      result.items.some((item, index) => item.id !== items[index]?.id)
+    ) {
+      throw new EmbeddingClientError(
+        "INVALID_RESPONSE",
+        "Embedding 响应输入顺序不一致",
+        false,
+      );
+    }
+    return result;
+  }
+}
+
+export function createEmbeddingClient(options: EmbeddingClientOptions) {
+  return new HttpEmbeddingClient(options);
+}
+
+function invalidConfiguration(message: string) {
+  return new EmbeddingClientError("INVALID_CONFIGURATION", message, false);
+}

package/template/packages/ai-client/src/embedding/contracts.ts

@@ -0,0 +1,46 @@
+import type { ArtifactRef } from "../artifact-ref.js";
+
+export type EmbeddingFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface EmbeddingOperation<Options> {
+  readonly key: string;
+  parseOptions?(value: Options): Options;
+}
+
+export type EmbeddingInput =
+  | { readonly id: string; readonly text: string }
+  | { readonly id: string; readonly source: ArtifactRef };
+
+export interface EmbeddingVector {
+  readonly id: string;
+  readonly vector: readonly number[];
+  readonly inputSha256: string;
+}
+
+export interface EmbeddingMetadata {
+  readonly deploymentAlias: string;
+  readonly model: string;
+  readonly version: string;
+  readonly dimensions: number;
+  readonly normalized: boolean;
+}
+
+export interface EmbeddingBatchResult {
+  readonly batchId: string;
+  readonly items: readonly EmbeddingVector[];
+  readonly metadata: EmbeddingMetadata;
+}
+
+export interface EmbeddingClient {
+  embed<Options>(
+    operation: EmbeddingOperation<Options>,
+    input: {
+      readonly items: readonly EmbeddingInput[];
+      readonly options?: Options;
+    },
+    context: { readonly idempotencyKey: string; readonly signal?: AbortSignal },
+  ): Promise<EmbeddingBatchResult>;
+}

package/template/packages/ai-client/src/embedding/error.ts

@@ -0,0 +1,61 @@
+export class EmbeddingClientError extends Error {
+  constructor(
+    readonly code:
+      | "INVALID_CONFIGURATION"
+      | "INVALID_INPUT"
+      | "FORBIDDEN"
+      | "CAPABILITY_UNAVAILABLE"
+      | "RUNTIME_UNAVAILABLE"
+      | "RUN_CANCELLED"
+      | "BUDGET_EXCEEDED"
+      | "RUN_CONFLICT"
+      | "INVALID_RESPONSE",
+    message: string,
+    readonly retryable: boolean,
+    readonly requestId?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "EmbeddingClientError";
+  }
+}
+
+export async function embeddingHttpError(response: Response, fallback: string) {
+  try {
+    const value = (await response.json()) as Record<string, unknown>;
+    if (
+      typeof value.code === "string" &&
+      typeof value.message === "string" &&
+      typeof value.retryable === "boolean" &&
+      value.message.length <= 200
+    ) {
+      return new EmbeddingClientError(
+        knownCode(value.code),
+        value.message,
+        value.retryable,
+        typeof value.requestId === "string" ? value.requestId : undefined,
+      );
+    }
+  } catch {
+    // 不透传不可信正文。
+  }
+  return new EmbeddingClientError(
+    "RUNTIME_UNAVAILABLE",
+    `${fallback}（HTTP ${response.status}）`,
+    response.status >= 500,
+  );
+}
+
+function knownCode(code: string): EmbeddingClientError["code"] {
+  return [
+    "INVALID_INPUT",
+    "FORBIDDEN",
+    "CAPABILITY_UNAVAILABLE",
+    "RUNTIME_UNAVAILABLE",
+    "RUN_CANCELLED",
+    "BUDGET_EXCEEDED",
+    "RUN_CONFLICT",
+  ].includes(code)
+    ? (code as EmbeddingClientError["code"])
+    : "RUNTIME_UNAVAILABLE";
+}

package/template/packages/ai-client/src/embedding/index.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./contracts.js";
+export * from "./error.js";

package/template/packages/ai-client/src/embedding/validation.ts

@@ -0,0 +1,117 @@
+import type { EmbeddingBatchResult, EmbeddingInput } from "./contracts.js";
+import { EmbeddingClientError } from "./error.js";
+
+export function normalizeInputs(
+  inputs: readonly EmbeddingInput[],
+): readonly EmbeddingInput[] {
+  if (!inputs.length) invalid("Embedding 输入不能为空");
+  const ids = new Set<string>();
+  return inputs.map((input) => {
+    if (!input.id.trim() || ids.has(input.id))
+      invalid("Embedding ID 无效或重复");
+    ids.add(input.id);
+    if ("text" in input) {
+      if (!input.text.trim()) invalid("Embedding 文本不能为空");
+      return { id: input.id, text: input.text };
+    }
+    const source = input.source;
+    if (
+      !source.value.trim() ||
+      /^[a-z][a-z0-9+.-]*:\/\//i.test(source.value) ||
+      !source.mediaType.trim() ||
+      !Number.isSafeInteger(source.byteSize) ||
+      source.byteSize < 1 ||
+      !/^[a-f0-9]{64}$/.test(source.sha256)
+    ) {
+      invalid("Embedding ArtifactRef 无效");
+    }
+    return {
+      id: input.id,
+      source: {
+        value: source.value,
+        mediaType: source.mediaType,
+        byteSize: source.byteSize,
+        sha256: source.sha256,
+        ...(source.expiresAt ? { expiresAt: source.expiresAt } : {}),
+      },
+    };
+  });
+}
+
+export function parseBatchResult(value: unknown): EmbeddingBatchResult {
+  const root = record(value, "EmbeddingResult");
+  const metadata = record(root.metadata, "EmbeddingResult.metadata");
+  const dimensions = integer(
+    metadata.dimensions,
+    "EmbeddingResult.metadata.dimensions",
+    1,
+  );
+  if (typeof metadata.normalized !== "boolean") {
+    invalid("EmbeddingResult.metadata.normalized");
+  }
+  if (!Array.isArray(root.items) || !root.items.length) {
+    invalid("EmbeddingResult.items");
+  }
+  const ids = new Set<string>();
+  const items = root.items.map((raw, index) => {
+    const item = record(raw, `EmbeddingResult.items[${index}]`);
+    const id = text(item.id, `EmbeddingResult.items[${index}].id`);
+    if (ids.has(id)) invalid(`EmbeddingResult.items[${index}].id`);
+    ids.add(id);
+    if (
+      !Array.isArray(item.vector) ||
+      item.vector.length !== dimensions ||
+      item.vector.some(
+        (entry) => typeof entry !== "number" || !Number.isFinite(entry),
+      )
+    ) {
+      invalid(`EmbeddingResult.items[${index}].vector`);
+    }
+    const inputSha256 = text(
+      item.inputSha256,
+      `EmbeddingResult.items[${index}].inputSha256`,
+    );
+    if (!/^[a-f0-9]{64}$/.test(inputSha256)) {
+      invalid(`EmbeddingResult.items[${index}].inputSha256`);
+    }
+    return { id, vector: item.vector as number[], inputSha256 };
+  });
+  return {
+    batchId: text(root.batchId, "EmbeddingResult.batchId"),
+    items,
+    metadata: {
+      deploymentAlias: text(
+        metadata.deploymentAlias,
+        "EmbeddingResult.metadata.deploymentAlias",
+      ),
+      model: text(metadata.model, "EmbeddingResult.metadata.model"),
+      version: text(metadata.version, "EmbeddingResult.metadata.version"),
+      dimensions,
+      normalized: metadata.normalized,
+    },
+  };
+}
+
+function record(value: unknown, path: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid(path);
+  return value as Record<string, unknown>;
+}
+
+function text(value: unknown, path: string) {
+  if (typeof value !== "string" || !value.trim()) invalid(path);
+  return value;
+}
+
+function integer(value: unknown, path: string, minimum: number) {
+  if (!Number.isSafeInteger(value) || Number(value) < minimum) invalid(path);
+  return Number(value);
+}
+
+function invalid(path: string): never {
+  throw new EmbeddingClientError(
+    "INVALID_RESPONSE",
+    `Embedding 响应字段无效：${path}`,
+    false,
+  );
+}

package/template/packages/ai-client/src/speech/client.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import { createSpeechAiClient } from "./client.js";
+import type { SpeechTranscriptionResult } from "./contracts.js";
+import { SpeechClientError } from "./error.js";
+
+const source = {
+  value: "artifact_opaque",
+  mediaType: "audio/mpeg",
+  byteSize: 128,
+  sha256: "a".repeat(64),
+};
+
+describe("Speech AI Client", () => {
+  test("提交、分段事件、结果 Artifact 与取消使用稳定批量协议", async () => {
+    const requests: Array<{ url: string; init?: RequestInit }> = [];
+    const client = createSpeechAiClient({
+      baseUrl: "https://windy.example",
+      fetch: async (input, init) => {
+        const url = String(input);
+        requests.push({ url, init });
+        if (url.endsWith("/api/speech/runs")) {
+          return Response.json({
+            runId: "speech-run-1",
+            status: "accepted",
+            eventsUrl: "/api/speech/runs/speech-run-1/events",
+          });
+        }
+        if (url.includes("/events")) {
+          return new Response(
+            [
+              'data: {"type":"run.started","runId":"speech-run-1","sequence":1}',
+              "",
+              'data: {"type":"speech.segment.completed","runId":"speech-run-1","sequence":2,"completedSegments":1,"totalSegments":1,"endMs":2500}',
+              "",
+              'data: {"type":"run.completed","runId":"speech-run-1","sequence":3}',
+              "",
+              "",
+            ].join("\n"),
+          );
+        }
+        if (url.endsWith("/result")) {
+          return Response.json({
+            output: {
+              language: "zh",
+              durationMs: 2500,
+              segments: [],
+              metadata: { engine: "local" },
+              artifact: {
+                mediaType: "application/json",
+                byteSize: 64,
+                sha256: "b".repeat(64),
+              },
+            },
+          });
+        }
+        if (url.endsWith("/artifact")) {
+          return new Response('{"segments":[]}', {
+            headers: {
+              "content-type": "application/json",
+              "content-length": "15",
+              "x-content-sha256": "b".repeat(64),
+            },
+          });
+        }
+        return Response.json({ runId: "speech-run-1", status: "cancelled" });
+      },
+    });
+    const run = await client.transcribe(
+      {
+        key: "speech.transcribe.batch",
+        parseOutput(value) {
+          return value as SpeechTranscriptionResult;
+        },
+      },
+      {
+        source,
+        options: {
+          language: "zh",
+          timestamps: "segment",
+          vad: { enabled: true },
+        },
+      },
+      { idempotencyKey: "speech-1" },
+    );
+
+    const events = [];
+    for await (const event of run.events) events.push(event);
+    expect(events.map(({ type }) => type)).toEqual([
+      "run.started",
+      "speech.segment.completed",
+      "run.completed",
+    ]);
+    expect((await run.result()).durationMs).toBe(2500);
+    expect((await run.artifact()).sha256).toBe("b".repeat(64));
+    await run.cancel("不再需要");
+    expect(JSON.parse(String(requests[0]?.init?.body))).toEqual({
+      operationKey: "speech.transcribe.batch",
+      source,
+      options: {
+        language: "zh",
+        timestamps: "segment",
+        vad: { enabled: true },
+      },
+    });
+    expect(requests[0]?.init?.headers).toMatchObject({
+      "idempotency-key": "speech-1",
+    });
+  });
+
+  test("拒绝无效 ArtifactRef 和跨 Origin events URL", async () => {
+    const client = createSpeechAiClient({
+      baseUrl: "https://windy.example",
+      fetch: async () =>
+        Response.json({
+          runId: "speech-run-1",
+          status: "accepted",
+          eventsUrl: "https://evil.example/events",
+        }),
+    });
+    await expect(
+      client.transcribe(
+        { key: "speech.transcribe.batch", parseOutput: (value) => value },
+        { source: { ...source, sha256: "invalid" } },
+        { idempotencyKey: "speech-invalid" },
+      ),
+    ).rejects.toBeInstanceOf(SpeechClientError);
+    await expect(
+      client.transcribe(
+        { key: "speech.transcribe.batch", parseOutput: (value) => value },
+        { source },
+        { idempotencyKey: "speech-origin" },
+      ),
+    ).rejects.toBeInstanceOf(SpeechClientError);
+  });
+});

package/template/packages/ai-client/src/speech/client.ts

@@ -0,0 +1,104 @@
+import type {
+  SpeechAiClient,
+  SpeechFetch,
+  SpeechOperation,
+  SpeechRun,
+  SubmitTranscriptionInput,
+} from "./contracts.js";
+import { SpeechClientError, speechHttpError } from "./error.js";
+import { HttpSpeechRun } from "./run.js";
+import { parseArtifactRef, parseCreatedRun } from "./validation.js";
+
+export interface SpeechClientOptions {
+  readonly baseUrl: string | URL;
+  readonly runsPath?: string;
+  readonly fetch?: SpeechFetch;
+}
+
+export class HttpSpeechAiClient implements SpeechAiClient {
+  private readonly baseUrl: URL;
+  private readonly runsPath: string;
+  private readonly fetch: SpeechFetch;
+
+  constructor(options: SpeechClientOptions) {
+    this.baseUrl = new URL(options.baseUrl);
+    if (!["http:", "https:"].includes(this.baseUrl.protocol)) {
+      throw new SpeechClientError(
+        "INVALID_CONFIGURATION",
+        "Speech Client 只允许 HTTP 或 HTTPS",
+        false,
+      );
+    }
+    this.runsPath = options.runsPath ?? "/api/speech/runs";
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async transcribe<Options, Output>(
+    operation: SpeechOperation<Options, Output>,
+    input: SubmitTranscriptionInput<Options>,
+    context: { idempotencyKey: string; signal?: AbortSignal },
+  ): Promise<SpeechRun<Output>> {
+    if (!operation.key.trim() || !context.idempotencyKey.trim()) {
+      throw new SpeechClientError(
+        "INVALID_CONFIGURATION",
+        "Speech Operation 与幂等键不能为空",
+        false,
+      );
+    }
+    const source = parseArtifactRef(input.source);
+    const options = input.options
+      ? (operation.parseOptions?.(input.options) ?? input.options)
+      : undefined;
+    let response: Response;
+    try {
+      response = await this.fetch(this.endpoint(this.runsPath), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "idempotency-key": context.idempotencyKey,
+        },
+        body: JSON.stringify({ operationKey: operation.key, source, options }),
+        signal: context.signal,
+      });
+    } catch (error) {
+      throw new SpeechClientError(
+        context.signal?.aborted ? "RUN_CANCELLED" : "RUNTIME_UNAVAILABLE",
+        context.signal?.aborted
+          ? "创建转写任务已取消"
+          : "Speech Runtime 暂不可用",
+        !context.signal?.aborted,
+        undefined,
+        { cause: error },
+      );
+    }
+    if (!response.ok) throw await speechHttpError(response, "创建转写任务失败");
+    const created = parseCreatedRun(await response.json());
+    const runPath = `${this.runsPath}/${encodeURIComponent(created.runId)}`;
+    return new HttpSpeechRun({
+      id: created.runId,
+      eventsUrl: this.endpoint(created.eventsUrl),
+      resultUrl: this.endpoint(`${runPath}/result`),
+      artifactUrl: this.endpoint(`${runPath}/artifact`),
+      cancelUrl: this.endpoint(`${runPath}/cancel`),
+      fetch: this.fetch,
+      signal: context.signal,
+      parseOutput: operation.parseOutput,
+    });
+  }
+
+  private endpoint(path: string): URL {
+    const endpoint = new URL(path, this.baseUrl);
+    if (endpoint.origin !== this.baseUrl.origin) {
+      throw new SpeechClientError(
+        "INVALID_RESPONSE",
+        "Speech Runtime 返回了不受信任的 Endpoint",
+        false,
+      );
+    }
+    return endpoint;
+  }
+}
+
+export function createSpeechAiClient(options: SpeechClientOptions) {
+  return new HttpSpeechAiClient(options);
+}

package/template/packages/ai-client/src/speech/contracts.ts

@@ -0,0 +1,129 @@
+import type { ArtifactRef } from "../artifact-ref.js";
+
+export type SpeechFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface BatchTranscriptionOptions {
+  readonly language?: string;
+  readonly vad?: {
+    readonly enabled: boolean;
+    readonly minSpeechMs?: number;
+    readonly maxSilenceMs?: number;
+  };
+  readonly timestamps?: "segment" | "word";
+}
+
+export interface SpeechOperation<Options, Output> {
+  readonly key: string;
+  parseOutput(value: unknown): Output;
+  parseOptions?(value: Options): Options;
+}
+
+export interface SubmitTranscriptionInput<Options> {
+  readonly source: ArtifactRef;
+  readonly options?: Options & BatchTranscriptionOptions;
+}
+
+export interface SpeechWord {
+  readonly text: string;
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly confidence?: number;
+}
+
+export interface SpeechSegment {
+  readonly id: string;
+  readonly text: string;
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly confidence?: number;
+  readonly language?: string;
+  readonly words?: readonly SpeechWord[];
+}
+
+export interface SpeechResultArtifactMetadata {
+  readonly mediaType: "application/json";
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface SpeechTranscriptionResult {
+  readonly language?: string;
+  readonly durationMs: number;
+  readonly segments: readonly SpeechSegment[];
+  readonly metadata: Readonly<Record<string, string | number | boolean>>;
+  readonly artifact: SpeechResultArtifactMetadata;
+}
+
+export interface OpenedSpeechResultArtifact extends SpeechResultArtifactMetadata {
+  readonly body: ReadableStream<Uint8Array>;
+}
+
+export type SpeechRunStatus =
+  | "accepted"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export type SpeechEvent =
+  | {
+      readonly type: "run.started" | "run.completed" | "run.cancelled";
+      readonly runId: string;
+      readonly sequence: number;
+    }
+  | {
+      readonly type: "speech.segment.completed";
+      readonly runId: string;
+      readonly sequence: number;
+      readonly completedSegments: number;
+      readonly totalSegments: number;
+      readonly endMs: number;
+    }
+  | {
+      readonly type: "run.failed";
+      readonly runId: string;
+      readonly sequence: number;
+      readonly error: SpeechErrorPayload;
+    };
+
+export interface SpeechErrorPayload {
+  readonly code: SpeechErrorCode;
+  readonly message: string;
+  readonly requestId: string;
+  readonly retryable: boolean;
+}
+
+export type SpeechErrorCode =
+  | "OPERATION_NOT_FOUND"
+  | "OPERATION_DISABLED"
+  | "INVALID_INPUT"
+  | "FORBIDDEN"
+  | "LICENSE_NOT_ALLOWED"
+  | "ARTIFACT_UNAVAILABLE"
+  | "ARTIFACT_EXPIRED"
+  | "CAPABILITY_UNAVAILABLE"
+  | "RUNTIME_UNAVAILABLE"
+  | "BUDGET_EXCEEDED"
+  | "OUTPUT_VALIDATION_FAILED"
+  | "RUN_CONFLICT"
+  | "RUN_TIMEOUT"
+  | "RUN_CANCELLED";
+
+export interface SpeechRun<Output> {
+  readonly id: string;
+  readonly events: AsyncIterable<SpeechEvent>;
+  result(): Promise<Output>;
+  artifact(): Promise<OpenedSpeechResultArtifact>;
+  cancel(reason?: string): Promise<void>;
+}
+
+export interface SpeechAiClient {
+  transcribe<Options, Output>(
+    operation: SpeechOperation<Options, Output>,
+    input: SubmitTranscriptionInput<Options>,
+    context: { idempotencyKey: string; signal?: AbortSignal },
+  ): Promise<SpeechRun<Output>>;
+}