@worm-vue3-print/core 1.3.0 → 1.3.2

package/dist/client/index.d.ts

@@ -0,0 +1,241 @@
+declare const APP_ID = "worm-print-client";
+declare const DEFAULT_PORT = 17521;
+declare const PORT_SCAN_LIMIT = 20;
+/** 服务端可能返回的错误码 */
+type ServerErrorCode = 'INVALID_REQUEST' | 'UNAUTHORIZED' | 'PRINTER_NOT_FOUND' | 'PRINTER_OFFLINE' | 'BUSY' | 'RENDER_TIMEOUT' | 'PRINT_FAILED' | 'INTERNAL';
+/** SDK 本地产生的错误码（服务端不会发送） */
+type ClientErrorCode = 'CLIENT_TIMEOUT' | 'CLIENT_NOT_RUNNING';
+type ProtocolErrorCode = ServerErrorCode | ClientErrorCode;
+interface ClientRequest<T = unknown> {
+    id: string;
+    type: string;
+    payload: T;
+}
+interface ServerOk<T = unknown> {
+    id: string;
+    ok: true;
+    payload: T;
+}
+interface ServerError {
+    id: string;
+    ok: false;
+    error: {
+        code: ServerErrorCode;
+        message: string;
+    };
+}
+type ServerResponse<T = unknown> = ServerOk<T> | ServerError;
+/** 无法解析的服务端消息 */
+interface MalformedMessage {
+    malformed: true;
+}
+interface PrinterInfo {
+    name: string;
+    isDefault: boolean;
+    /** 系统返回的打印机状态描述（如 idle、offline），无信息时为空串 */
+    status: string;
+}
+interface HelloRequestPayload {
+}
+interface HelloResponsePayload {
+    app: typeof APP_ID;
+    version: string;
+    port: number;
+}
+interface PrintersListResponsePayload {
+    printers: PrinterInfo[];
+}
+/** 打印参数；长度单位均为微米（1mm = 1000μm） */
+interface PrintOptions {
+    /** 缺省走系统默认打印机 */
+    printerName?: string;
+    copies?: number;
+    /** 打印机驱动内已配置纸型名，针式打印机优先使用 */
+    paperName?: string;
+    /**
+     * 纸张覆盖项（微米）。
+     * - 普通模板：缺省（或仅给 width）时以模板自带纸张（getPaperDimensions）为准；
+     * - 连续纸模板（templateJson.paperSize === 'CONTINUOUS'）：高度缺省或 <=0 时按渲染探针
+     *   测得的内容高度＋连续纸底边距推导实际纸高；显式 height>0 为配置覆盖（逃生门）。
+     *   宽度缺省取模板 customWidth（默认 80mm）。
+     */
+    paperSize?: {
+        width?: number;
+        height?: number;
+    };
+    landscape?: boolean;
+    /**
+     * 页边距覆盖（微米）；缺省使用模板 margins。
+     * 连续纸的末尾留白由模板连续纸底边距（默认 0）控制，已计入推导纸高。
+     */
+    margins?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    color?: boolean;
+    pageRanges?: Array<{
+        from: number;
+        to: number;
+    }>;
+}
+/** print.submit 请求 payload；templateJson 结构由 core 定义，这里保持松散耦合 */
+interface PrintSubmitRequest {
+    templateJson: Record<string, unknown>;
+    /** 业务数据：对象=单份；非空对象数组=批量（最多 500 份，合并为一个作业） */
+    printData?: Record<string, unknown> | Array<Record<string, unknown>>;
+    /** 相对路径图片资源解析基址 */
+    baseUrl?: string;
+    /** 相对路径字体资源解析基址；缺省回落 baseUrl（客户端必须能访问解析后的地址） */
+    fontBaseUrl?: string;
+    /** 模板名称（业务侧元数据，用于客户端任务记录展示，不参与渲染） */
+    templateName?: string;
+    print: PrintOptions;
+}
+interface PrintSubmitResponsePayload {
+    jobId: string;
+}
+/**
+ * 浏览器侧预渲染结果（@worm-vue3-print/core/browser 的 renderHtmlPages 输出子集）。
+ * 业务页在浏览器内完成两遍渲染后，把最终 HTML 直接提交给客户端静默打印，
+ * 客户端不再持有/执行模板渲染内核。
+ */
+interface RenderedHtmlPages {
+    /** 最终多页 HTML（连续纸纸高已写入 @page/.print-page） */
+    html: string;
+    /** 最终纸张尺寸（mm；连续纸为探针推导高度） */
+    paperMm: {
+        width: number;
+        height: number;
+    };
+    /** 模板是否连续纸 */
+    continuous?: boolean;
+    /** 总页数（客户端任务记录用，可选） */
+    pageCount?: number;
+}
+/** print.submitHtml 请求 payload：浏览器预渲染 HTML 直提交通道 */
+interface PrintSubmitHtmlRequest {
+    /** 最终多页 HTML（必须是 core 同构管线产出的完整文档） */
+    html: string;
+    /** 最终纸张尺寸（mm） */
+    paperMm: {
+        width: number;
+        height: number;
+    };
+    /** 模板是否连续纸（影响纸张覆盖语义，缺省 false） */
+    continuous?: boolean;
+    /** 总页数（可选，任务记录展示） */
+    pageCount?: number;
+    /** 模板名称（业务侧元数据，用于客户端任务记录展示，不参与渲染） */
+    templateName?: string;
+    print: PrintOptions;
+}
+declare const MESSAGE_TYPES: {
+    readonly HELLO: "hello";
+    readonly PRINTERS_LIST: "printers.list";
+    readonly PRINT_SUBMIT: "print.submit";
+    readonly PRINT_SUBMIT_HTML: "print.submitHtml";
+};
+/** 编码请求帧为 JSON 字符串 */
+declare function encodeRequest<T>(type: string, payload: T): string;
+/** 解码服务端消息；任何非法输入统一返回 { malformed: true }，不抛异常 */
+declare function decodeServerMessage(raw: string): ServerResponse | MalformedMessage;
+
+/** 协议/SDK 错误：携带可程序化处理的错误码 */
+declare class WormPrintError extends Error {
+    readonly code: ProtocolErrorCode;
+    constructor(code: ProtocolErrorCode, message: string);
+}
+
+type TransportStatus = 'disconnected' | 'connecting' | 'connected';
+interface TransportOptions {
+    /** 安全开关开启后的配对 token */
+    token?: string;
+    /** 请求默认超时（毫秒），默认 15000 */
+    timeoutMs?: number;
+    /** 覆盖探测端口列表（测试用）；默认 DEFAULT_PORT 起连续 PORT_SCAN_LIMIT 个 */
+    ports?: number[];
+    /** 注入 WebSocket 构造器（测试用） */
+    WebSocketCtor?: typeof WebSocket;
+}
+declare class WsTransport {
+    private ws;
+    private status_;
+    private hello;
+    private pendings;
+    private statusCbs;
+    private manualClose;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private readonly ctor;
+    private readonly defaultTimeout;
+    private opts;
+    constructor(opts?: TransportOptions);
+    get status(): TransportStatus;
+    onStatus(cb: (s: TransportStatus) => void): () => void;
+    setToken(token: string | undefined): void;
+    /** 依次探测端口并完成 hello 握手；全部失败抛 CLIENT_NOT_RUNNING */
+    connect(signal?: AbortSignal): Promise<HelloResponsePayload>;
+    /** 发送请求并等待同 id 响应 */
+    request<T>(type: string, payload: unknown, timeoutMs?: number): Promise<T>;
+    close(): void;
+    private buildUrl;
+    private tryPort;
+    /** 握手成功后绑定正式生命周期（消息分发、掉线重连） */
+    private bindLifecycle;
+    private scheduleReconnect;
+    private failAllPendings;
+    private setStatus;
+}
+
+interface PrintClientOptions {
+    /** 配对 token；不传则自动读取 localStorage 中 pair() 保存的值 */
+    token?: string;
+    /** 单请求默认超时 ms，默认 15000 */
+    timeoutMs?: number;
+    /** @internal 注入 WebSocket 构造器（测试用） */
+    WebSocketCtor?: typeof WebSocket;
+}
+declare class PrintClient {
+    private readonly transport;
+    constructor(opts?: PrintClientOptions);
+    get status(): TransportStatus;
+    /** 连接本机客户端（自动端口探测 + 掉线重连） */
+    connect(signal?: AbortSignal): Promise<HelloResponsePayload>;
+    onStatusChange(cb: (s: TransportStatus) => void): () => void;
+    /** 枚举本机打印机 */
+    listPrinters(): Promise<PrinterInfo[]>;
+    /**
+     * 提交静默打印任务。
+     * @param templateJson core 模板 JSON
+     * @param printData 业务数据
+     * @param options 打印机/纸张/份数等；baseUrl 为相对图片资源基址，fontBaseUrl 为相对字体资源基址
+     *   （字体常在 CDN/前端站点，与图片不在同一域时需单独指定）；timeoutMs 可单独放宽大任务
+     * @param templateName 模板名称，透传给客户端用于任务记录
+     */
+    print(templateJson: Record<string, unknown>, printData?: Record<string, unknown> | Array<Record<string, unknown>>, options?: PrintOptions & {
+        baseUrl?: string;
+        fontBaseUrl?: string;
+        timeoutMs?: number;
+    }, templateName?: string): Promise<PrintSubmitResponsePayload>;
+    /**
+     * 提交浏览器侧预渲染结果静默打印（print.submitHtml）。
+     *
+     * 业务页先用 @worm-vue3-print/core/browser 的 renderHtmlPages 在浏览器内完成
+     * 两遍渲染，再调用本方法把最终 HTML 直送客户端；客户端不再执行模板渲染。
+     *
+     * @param rendered renderHtmlPages 返回值（html/paperMm/continuous/pageCount）
+     * @param options 打印机/纸张/份数等；timeoutMs 可单独放宽大任务
+     * @param templateName 模板名称，透传给客户端用于任务记录
+     */
+    printHtml(rendered: RenderedHtmlPages, options?: {
+        timeoutMs?: number;
+    } & Omit<PrintOptions, 'paperSize' | 'margins' | 'landscape'>, templateName?: string): Promise<PrintSubmitResponsePayload>;
+    /** 保存配对 token（localStorage），并即时更新当前连接的鉴权参数（下次连接生效） */
+    pair(token: string): void;
+    static loadStoredToken(): string | null;
+    close(): void;
+}
+
+export { APP_ID, type ClientErrorCode, type ClientRequest, DEFAULT_PORT, type HelloRequestPayload, type HelloResponsePayload, MESSAGE_TYPES, type MalformedMessage, PORT_SCAN_LIMIT, PrintClient, type PrintClientOptions, type PrintOptions, type PrintSubmitHtmlRequest, type PrintSubmitRequest, type PrintSubmitResponsePayload, type PrinterInfo, type PrintersListResponsePayload, type ProtocolErrorCode, type RenderedHtmlPages, type ServerError, type ServerErrorCode, type ServerOk, type ServerResponse, type TransportOptions, type TransportStatus, WormPrintError, WsTransport, decodeServerMessage, encodeRequest };

package/dist/client/index.js

@@ -0,0 +1,346 @@
+// src/client/protocol.ts
+var APP_ID = "worm-print-client";
+var DEFAULT_PORT = 17521;
+var PORT_SCAN_LIMIT = 20;
+var MESSAGE_TYPES = {
+  HELLO: "hello",
+  PRINTERS_LIST: "printers.list",
+  PRINT_SUBMIT: "print.submit",
+  PRINT_SUBMIT_HTML: "print.submitHtml"
+};
+var seq = 0;
+function nextId() {
+  seq = (seq + 1) % Number.MAX_SAFE_INTEGER;
+  return `${Date.now().toString(36)}-${seq.toString(36)}`;
+}
+function encodeRequest(type, payload) {
+  const frame = { id: nextId(), type, payload };
+  return JSON.stringify(frame);
+}
+function decodeServerMessage(raw) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return { malformed: true };
+  }
+  if (typeof data !== "object" || data === null) return { malformed: true };
+  const obj = data;
+  if (typeof obj.id !== "string" || typeof obj.ok !== "boolean") return { malformed: true };
+  if (obj.ok) {
+    return { id: obj.id, ok: true, payload: obj.payload ?? {} };
+  }
+  const err = obj.error;
+  if (!err || typeof err.code !== "string" || typeof err.message !== "string") {
+    return { malformed: true };
+  }
+  return {
+    id: obj.id,
+    ok: false,
+    error: { code: err.code, message: err.message }
+  };
+}
+
+// src/client/errors.ts
+var WormPrintError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "WormPrintError";
+    this.code = code;
+  }
+};
+
+// src/client/transport.ts
+var AuthRejectedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "UNAUTHORIZED";
+    this.name = "AuthRejectedError";
+  }
+};
+var WsTransport = class {
+  constructor(opts = {}) {
+    this.ws = null;
+    this.status_ = "disconnected";
+    this.hello = null;
+    this.pendings = /* @__PURE__ */ new Map();
+    this.statusCbs = /* @__PURE__ */ new Set();
+    this.manualClose = false;
+    this.reconnectTimer = null;
+    this.reconnectAttempts = 0;
+    this.opts = opts;
+    this.ctor = opts.WebSocketCtor ?? WebSocket;
+    this.defaultTimeout = opts.timeoutMs ?? 15e3;
+  }
+  get status() {
+    return this.status_;
+  }
+  onStatus(cb) {
+    this.statusCbs.add(cb);
+    return () => this.statusCbs.delete(cb);
+  }
+  setToken(token) {
+    this.opts = { ...this.opts, token };
+  }
+  /** 依次探测端口并完成 hello 握手；全部失败抛 CLIENT_NOT_RUNNING */
+  async connect(signal) {
+    if (this.status_ === "connected" && this.hello) return this.hello;
+    this.setStatus("connecting");
+    const ports = this.opts.ports ?? Array.from({ length: PORT_SCAN_LIMIT }, (_, i) => DEFAULT_PORT + i);
+    for (const port of ports) {
+      if (signal?.aborted) throw new WormPrintError("CLIENT_NOT_RUNNING", "\u8FDE\u63A5\u5DF2\u53D6\u6D88");
+      try {
+        this.hello = await this.tryPort(port, signal);
+        this.manualClose = false;
+        this.reconnectAttempts = 0;
+        this.setStatus("connected");
+        return this.hello;
+      } catch (err) {
+        if (err instanceof AuthRejectedError) {
+          this.setStatus("disconnected");
+          throw new WormPrintError(
+            "UNAUTHORIZED",
+            err.message || "\u914D\u5BF9 token \u65E0\u6548\u6216\u6765\u6E90\u672A\u6388\u6743"
+          );
+        }
+      }
+    }
+    this.setStatus("disconnected");
+    throw new WormPrintError(
+      "CLIENT_NOT_RUNNING",
+      "\u672A\u53D1\u73B0\u8FD0\u884C\u4E2D\u7684\u6253\u5370\u5BA2\u6237\u7AEF\uFF08\u5DF2\u63A2\u6D4B\u9ED8\u8BA4\u7AEF\u53E3\u533A\u95F4\uFF09\uFF0C\u8BF7\u786E\u8BA4\u5BA2\u6237\u7AEF\u5DF2\u542F\u52A8"
+    );
+  }
+  /** 发送请求并等待同 id 响应 */
+  request(type, payload, timeoutMs) {
+    if (this.status_ !== "connected" || !this.ws) {
+      return Promise.reject(new WormPrintError("CLIENT_NOT_RUNNING", "\u6253\u5370\u5BA2\u6237\u7AEF\u672A\u8FDE\u63A5"));
+    }
+    const raw = encodeRequest(type, payload);
+    const frame = JSON.parse(raw);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendings.delete(frame.id);
+        reject(new WormPrintError("CLIENT_TIMEOUT", `\u8BF7\u6C42 ${type} \u8D85\u65F6\u672A\u54CD\u5E94`));
+      }, timeoutMs ?? this.defaultTimeout);
+      this.pendings.set(frame.id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.ws.send(raw);
+    });
+  }
+  close() {
+    this.manualClose = true;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+    this.ws?.close();
+    this.failAllPendings(new WormPrintError("CLIENT_NOT_RUNNING", "\u8FDE\u63A5\u5DF2\u5173\u95ED"));
+    this.setStatus("disconnected");
+  }
+  // ─── 内部 ───
+  buildUrl(port) {
+    const url = new URL(`ws://127.0.0.1:${port}`);
+    if (this.opts.token) url.searchParams.set("token", this.opts.token);
+    return url.toString().replace(/\/$/, "");
+  }
+  tryPort(port, signal) {
+    return new Promise((resolve, reject) => {
+      const ws = new this.ctor(this.buildUrl(port));
+      this.ws = ws;
+      let settled = false;
+      const cleanupAbort = () => {
+        if (!settled) {
+          settled = true;
+          reject(new Error("aborted"));
+        }
+      };
+      signal?.addEventListener("abort", cleanupAbort, { once: true });
+      ws.onopen = () => {
+        ws.send(encodeRequest("hello", {}));
+      };
+      ws.onmessage = (ev) => {
+        const msg = decodeServerMessage(String(ev.data));
+        if ("malformed" in msg) return;
+        if (msg.ok && isHello(msg.payload)) {
+          if (settled) return;
+          settled = true;
+          this.bindLifecycle(ws);
+          resolve(msg.payload);
+        } else if (!msg.ok && msg.error.code === "UNAUTHORIZED") {
+          if (settled) return;
+          settled = true;
+          reject(new AuthRejectedError(msg.error.message));
+        } else if (!settled) {
+          settled = true;
+          reject(new Error("\u63E1\u624B\u5931\u8D25"));
+        }
+      };
+      ws.onerror = () => {
+        if (!settled) {
+          settled = true;
+          reject(new Error("\u8FDE\u63A5\u9519\u8BEF"));
+        }
+      };
+      ws.onclose = () => {
+        if (!settled) {
+          settled = true;
+          reject(new Error("\u8FDE\u63A5\u5173\u95ED"));
+        }
+      };
+    });
+  }
+  /** 握手成功后绑定正式生命周期（消息分发、掉线重连） */
+  bindLifecycle(ws) {
+    ws.onmessage = (ev) => {
+      const msg = decodeServerMessage(String(ev.data));
+      if ("malformed" in msg) return;
+      const pending = this.pendings.get(msg.id);
+      if (!pending) return;
+      this.pendings.delete(msg.id);
+      clearTimeout(pending.timer);
+      if (msg.ok) {
+        pending.resolve(msg.payload);
+      } else {
+        pending.reject(new WormPrintError(msg.error.code, msg.error.message));
+      }
+    };
+    ws.onclose = () => {
+      this.failAllPendings(new WormPrintError("CLIENT_NOT_RUNNING", "\u4E0E\u5BA2\u6237\u7AEF\u7684\u8FDE\u63A5\u4E2D\u65AD"));
+      this.hello = null;
+      this.ws = null;
+      if (!this.manualClose) this.scheduleReconnect();
+    };
+    ws.onerror = () => {
+    };
+  }
+  scheduleReconnect() {
+    this.setStatus("connecting");
+    const delay = Math.min(1e3 * 2 ** this.reconnectAttempts++, 1e4);
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch(() => this.scheduleReconnect());
+    }, delay);
+  }
+  failAllPendings(err) {
+    for (const [, p] of this.pendings) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pendings.clear();
+  }
+  setStatus(s) {
+    if (this.status_ === s) return;
+    this.status_ = s;
+    for (const cb of this.statusCbs) cb(s);
+  }
+};
+function isHello(payload) {
+  return typeof payload === "object" && payload !== null && payload.app === "worm-print-client";
+}
+
+// src/client/print-client.ts
+var TOKEN_STORAGE_KEY = "worm-print-client:token";
+var PrintClient = class _PrintClient {
+  constructor(opts = {}) {
+    const token = opts.token ?? _PrintClient.loadStoredToken() ?? void 0;
+    const transportOpts = {
+      token,
+      timeoutMs: opts.timeoutMs,
+      WebSocketCtor: opts.WebSocketCtor
+    };
+    this.transport = new WsTransport(transportOpts);
+  }
+  get status() {
+    return this.transport.status;
+  }
+  /** 连接本机客户端（自动端口探测 + 掉线重连） */
+  connect(signal) {
+    return this.transport.connect(signal);
+  }
+  onStatusChange(cb) {
+    return this.transport.onStatus(cb);
+  }
+  /** 枚举本机打印机 */
+  async listPrinters() {
+    const res = await this.transport.request(
+      MESSAGE_TYPES.PRINTERS_LIST,
+      {}
+    );
+    return res.printers;
+  }
+  /**
+   * 提交静默打印任务。
+   * @param templateJson core 模板 JSON
+   * @param printData 业务数据
+   * @param options 打印机/纸张/份数等；baseUrl 为相对图片资源基址，fontBaseUrl 为相对字体资源基址
+   *   （字体常在 CDN/前端站点，与图片不在同一域时需单独指定）；timeoutMs 可单独放宽大任务
+   * @param templateName 模板名称，透传给客户端用于任务记录
+   */
+  print(templateJson, printData, options = {}, templateName) {
+    const { baseUrl, fontBaseUrl, timeoutMs, ...print } = options;
+    const payload = { templateJson, printData, baseUrl, fontBaseUrl, print };
+    if (typeof templateName === "string" && templateName.trim().length > 0) {
+      payload.templateName = templateName;
+    }
+    return this.transport.request(
+      MESSAGE_TYPES.PRINT_SUBMIT,
+      payload,
+      timeoutMs
+    );
+  }
+  /**
+   * 提交浏览器侧预渲染结果静默打印（print.submitHtml）。
+   *
+   * 业务页先用 @worm-vue3-print/core/browser 的 renderHtmlPages 在浏览器内完成
+   * 两遍渲染，再调用本方法把最终 HTML 直送客户端；客户端不再执行模板渲染。
+   *
+   * @param rendered renderHtmlPages 返回值（html/paperMm/continuous/pageCount）
+   * @param options 打印机/纸张/份数等；timeoutMs 可单独放宽大任务
+   * @param templateName 模板名称，透传给客户端用于任务记录
+   */
+  printHtml(rendered, options = {}, templateName) {
+    const { timeoutMs, ...print } = options;
+    const payload = {
+      html: rendered.html,
+      paperMm: rendered.paperMm,
+      continuous: rendered.continuous,
+      pageCount: rendered.pageCount,
+      print
+    };
+    if (typeof templateName === "string" && templateName.trim().length > 0) {
+      payload.templateName = templateName;
+    }
+    return this.transport.request(
+      MESSAGE_TYPES.PRINT_SUBMIT_HTML,
+      payload,
+      timeoutMs
+    );
+  }
+  /** 保存配对 token（localStorage），并即时更新当前连接的鉴权参数（下次连接生效） */
+  pair(token) {
+    localStorage.setItem(TOKEN_STORAGE_KEY, token);
+    this.transport.setToken(token);
+  }
+  static loadStoredToken() {
+    try {
+      return localStorage.getItem(TOKEN_STORAGE_KEY);
+    } catch {
+      return null;
+    }
+  }
+  close() {
+    this.transport.close();
+  }
+};
+export {
+  APP_ID,
+  DEFAULT_PORT,
+  MESSAGE_TYPES,
+  PORT_SCAN_LIMIT,
+  PrintClient,
+  WormPrintError,
+  WsTransport,
+  decodeServerMessage,
+  encodeRequest
+};