@huaqiu/component-gen-server 0.3.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.d.mts

@@ -0,0 +1,205 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/types.d.ts
+/**
+ * `@huaqiu/component-gen-server` — shared domain types.
+ *
+ * These mirror `@huaqiu/component-gen-app/src/ports.ts` (structurally
+ * identical, JSON interop) but are owned by the server as the authority.
+ */
+type ComponentGenPage = 'symbol' | 'footprint';
+type JobKind = 'symbol' | 'extract-footprint' | 'generate-footprint';
+type JobStatus = 'queued' | 'running' | 'needs_confirmation' | 'completed' | 'failed' | 'cancelled';
+interface JobInput {
+  imageDataUrl?: string;
+  instruction?: string;
+  packageType?: string;
+  dimensions?: Record<string, number>;
+  fileName?: string;
+  edited?: Record<string, boolean>;
+}
+interface JobState {
+  id: string;
+  kind: JobKind;
+  status: JobStatus;
+  progress?: string;
+  result?: Record<string, unknown>;
+  dimensions?: Record<string, unknown>;
+  pkgType?: string | null;
+  fileName?: string | null;
+  error?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+type JobEvent = {
+  type: 'progress';
+  message: string;
+  at: string;
+} | {
+  type: 'needs_confirmation';
+  dimensions: Record<string, unknown>;
+  pkgType?: string | null;
+  fileName?: string | null;
+  at: string;
+} | {
+  type: 'completed';
+  job: JobState;
+  at: string;
+} | {
+  type: 'failed';
+  error: string;
+  result?: Record<string, unknown>;
+  at: string;
+} | {
+  type: 'cancelled';
+  at: string;
+};
+interface StartJobRequest {
+  kind: JobKind;
+  input: JobInput;
+}
+interface HistoryQuery {
+  limit?: number;
+  cursor?: string | null;
+}
+interface HistoryPage {
+  entries: HistoryEntry[];
+  nextCursor?: string | null;
+}
+interface HistoryEntry {
+  id: string;
+  kind: 'symbol' | 'footprint';
+  createdAt: string;
+  status: 'generated' | 'failed' | 'cancelled';
+  input: {
+    imageId?: string;
+    instruction?: string;
+    packageType?: string;
+    dimensions?: Record<string, number>;
+  };
+  edited?: Record<string, boolean>;
+  result?: {
+    artifactId: string;
+    filename: string;
+    fileUrl?: string;
+    size?: number;
+  };
+  error?: string;
+}
+interface HistoryPatch {
+  status?: HistoryEntry['status'];
+  result?: HistoryEntry['result'];
+  error?: string;
+  edited?: Record<string, boolean>;
+}
+interface ComponentGenConfig {
+  hostMode: boolean;
+  capabilities: {
+    symbol: boolean;
+    footprint: boolean;
+  };
+  limits: {
+    imageBytes: number;
+  };
+}
+declare const COMPONENT_GEN_ROUTE_PREFIX = "/api/v1/huaqiu/component-gen";
+declare const MAX_IMAGE_BYTES: number;
+//#endregion
+//#region src/backend.d.ts
+interface GenerationExec {
+  signal?: AbortSignal;
+}
+interface ComponentGenBackend {
+  generateSymbol(args: {
+    imageDataUrl: string;
+    instruction?: string;
+  }, exec: GenerationExec): Promise<Record<string, unknown>>;
+  extractFootprint(args: {
+    imageDataUrl: string;
+    packageType?: string;
+    instruction?: string;
+  }, exec: GenerationExec): Promise<Record<string, unknown>>;
+  generateFootprint(args: {
+    packageType: string;
+    fileName?: string;
+    dimensions: Record<string, number>;
+  }, exec: GenerationExec): Promise<Record<string, unknown>>;
+}
+//#endregion
+//#region src/history.d.ts
+/** `data:image/...;base64,....` → { mime, bytes } | null. */
+declare function parseDataUrl(dataUrl: string): {
+  mime: string;
+  bytes: Buffer;
+} | null;
+declare class HistoryStore {
+  private readonly dir;
+  private readonly file;
+  private entries;
+  constructor(dir: string);
+  /** All entries, newest first. */
+  private sorted;
+  append(entry: HistoryEntry): Promise<HistoryEntry>;
+  list(query: HistoryQuery): Promise<HistoryPage>;
+  get(id: string): Promise<HistoryEntry | null>;
+  patch(id: string, patch: HistoryPatch): Promise<HistoryEntry | null>;
+  delete(id: string): Promise<void>;
+  saveImage(imageId: string, dataUrl: string): Promise<void>;
+  readImage(imageId: string): Promise<{
+    bytes: Uint8Array;
+    mime: string;
+  } | null>;
+}
+declare function newHistoryId(): string;
+declare function newImageId(): string;
+//#endregion
+//#region src/routes.d.ts
+interface ComponentGenHandlerDeps {
+  backend: ComponentGenBackend;
+  history: HistoryStore;
+  hostMode?: boolean;
+  getAccessToken?: () => Promise<string | null>;
+}
+type ComponentGenHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void> | void;
+declare function createComponentGenHandler(deps: ComponentGenHandlerDeps): ComponentGenHandler;
+//#endregion
+//#region src/jobs.d.ts
+interface JobMeta {
+  /** stored input thumbnail id (points into the history store's inputs/). */
+  imageId?: string;
+}
+declare class JobStore {
+  private readonly jobs;
+  private readonly listeners;
+  create(req: StartJobRequest, meta: JobMeta): JobState;
+  get(id: string): JobState | undefined;
+  abort(id: string): boolean;
+  signal(id: string): AbortSignal | undefined;
+  subscribe(id: string, cb: (e: JobEvent) => void): (() => void) | null;
+  private emit;
+  /** Update job state (public — the runner writes progress/status). */
+  update(id: string, patch: Partial<JobState>, event?: JobEvent): JobState;
+  /** Update + emit the canonical event for a terminal state. */
+  settle(id: string, patch: Partial<JobState>): JobState;
+  remove(id: string): void;
+}
+interface RunOutcome {
+  state: JobState;
+  /** whether a history entry was appended. */
+  recorded: boolean;
+}
+/**
+ * Run one generation to a terminal state. Returns the final JobState.
+ * History recording happens here so entry and state cannot drift.
+ */
+declare function runGeneration(store: JobStore, backend: ComponentGenBackend, history: HistoryStore, id: string, req: StartJobRequest, meta: JobMeta, onProgress?: (message: string) => void): Promise<RunOutcome>;
+//#endregion
+//#region src/index.d.ts
+interface ComponentGenWebRoute {
+  kind: 'prefix';
+  path: string;
+  handler: ReturnType<typeof createComponentGenHandler>;
+}
+/** Build the DSH `webServer.register(...)` route object. */
+declare function createComponentGenRoutes(deps: ComponentGenHandlerDeps): ComponentGenWebRoute;
+//#endregion
+export { COMPONENT_GEN_ROUTE_PREFIX, type ComponentGenBackend, type ComponentGenConfig, type ComponentGenHandler, type ComponentGenHandlerDeps, type ComponentGenPage, ComponentGenWebRoute, type GenerationExec, type HistoryEntry, type HistoryPage, type HistoryPatch, type HistoryQuery, HistoryStore, type JobEvent, type JobInput, type JobKind, type JobMeta, type JobState, JobStore, MAX_IMAGE_BYTES, type RunOutcome, type StartJobRequest, createComponentGenHandler, createComponentGenRoutes, newHistoryId, newImageId, parseDataUrl, runGeneration };