@aglyn/plugins-commerce 1.0.0-beta.230 → 1.0.0-beta.232

package/src/lib/model/commerce-printers.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ReceiptData } from './commerce-receipt';
+/**
+ * Cloud receipt printers (AGL-3619).
+ *
+ * A browser register cannot reach a USB or LAN printer without a driver, and
+ * an https console cannot talk to a printer's plain-http web service. Both
+ * vendors that matter at a counter solve this the same way: the PRINTER polls
+ * an https URL, and the server answers with the next job.
+ *
+ *  - Star CloudPRNT (mC-Print3, TSP100IV, mC-Label3): the printer POSTs its
+ *    status as JSON, GETs the job when told one is ready, and DELETEs it to
+ *    confirm, with the result in a `code` query parameter.
+ *  - Epson Server Direct Print (TM-m30III, TM-m50, TM-T88VII): the printer
+ *    POSTs a form (`ConnectionType=GetRequest`) and receives ePOS-Print XML in
+ *    the response, then POSTs `ConnectionType=SetResponse` with the result.
+ *
+ * Every printer belongs to one register and polls one URL that carries the
+ * site, the printer and a per-printer secret. The secret is not stored: it is
+ * an HMAC of those ids and a rotation counter (`server/printer-secret.ts`), so
+ * the console can show it to a manager again and "Regenerate" invalidates the
+ * old URL by bumping the counter.
+ *
+ * `hosts/{hostId}/printers/{printerId}` and `hosts/{hostId}/printJobs/{jobId}`
+ * are written only by the server (the Firestore rules deny every client
+ * write); the console reads both to show status and recent jobs.
+ */
+export type PrinterBrand = 'star' | 'epson';
+export declare const PRINTER_BRANDS: readonly PrinterBrand[];
+export declare const PRINTER_BRAND_LABELS: Record<PrinterBrand, string>;
+/** The models we document and test against, per brand. Free text is allowed. */
+export declare const PRINTER_MODEL_SUGGESTIONS: Record<PrinterBrand, readonly string[]>;
+/** Roll width; it sets the characters per line. */
+export type PrinterPaperWidth = 80 | 58;
+/** Characters per line in the printer's default font A, by roll width. */
+export declare function printerColumns(paperWidthMm: PrinterPaperWidth | undefined): number;
+/**
+ * What the printer last told us about itself. `online` means it can print;
+ * `paper_low` still prints. Everything else stops printing until a person
+ * fixes it.
+ */
+export type PrinterState = 'online' | 'paper_low' | 'paper_out' | 'cover_open' | 'error' | 'unknown';
+export declare const PRINTER_STATE_LABELS: Record<PrinterState, string>;
+/** A printer that has not polled for this long is shown as offline. */
+export declare const PRINTER_OFFLINE_AFTER_MS: number;
+export interface PrinterStatus {
+    state: PrinterState;
+    /** The printer's own words, e.g. Star's `410 Out of paper` or Epson's `EPTR_COVER_OPEN`. */
+    detail?: string;
+    /** Last time the printer polled, ms since epoch. */
+    atMs: number;
+    /** Polling interval the printer reported (Star `GetPollInterval`), seconds. */
+    pollSeconds?: number;
+}
+/** `hosts/{hostId}/printers/{printerId}` (AGL-3619). Server-written only. */
+export interface PosPrinter {
+    name: string;
+    brand: PrinterBrand;
+    model?: string;
+    /**
+     * The printer's identity as it reports it: the Ethernet MAC for Star
+     * (`00:11:62:aa:bb:cc`, lower case), the Server Direct Print `ID` set in
+     * Epson's WebConfig. A poll that names a different device is refused, so a
+     * leaked URL alone cannot drain the queue from another printer.
+     */
+    deviceId: string;
+    registerId: string;
+    paperWidthMm?: PrinterPaperWidth;
+    /** Print a customer receipt when a sale on this register completes. */
+    autoPrintReceipts: boolean;
+    /** Open the cash drawer wired to this printer on cash sales, cash refunds and paid-outs. */
+    kickDrawer: boolean;
+    /**
+     * Print a kitchen (or bar, or packing) ticket for every sale on this
+     * register: the order number, each item and quantity, and no prices.
+     */
+    kitchenTickets?: boolean;
+    /**
+     * The NV logo stored in the printer with the vendor's utility, printed at the
+     * top of every receipt: Star's logo number (1-255), Epson's `key1,key2`
+     * (e.g. `48,48`). Empty prints no logo.
+     */
+    logoKey?: string;
+    /** Bumped by "Regenerate URL"; part of the HMAC that makes the secret. */
+    secretVersion: number;
+    status?: PrinterStatus;
+    createdAtMs: number;
+    createdBy?: string;
+    updatedAtMs?: number;
+}
+export type PrintJobKind = 'receipt' | 'kitchen' | 'drawer' | 'test' | 'report';
+/**
+ * A titled report printed on the receipt roll (AGL-3609): a register shift's
+ * X or Z report. Rows are already formatted, so every printer prints the
+ * figures the console shows.
+ */
+export interface PrintReport {
+    title: string;
+    storeName: string;
+    subtitle?: string;
+    sections: Array<{
+        section: string;
+        rows: Array<{
+            label: string;
+            value: string;
+            strong?: boolean;
+        }>;
+    }>;
+}
+export type PrintJobStatus = 'queued' | 'printing' | 'done' | 'failed' | 'expired' | 'canceled';
+export declare const PRINT_JOB_ACTIVE_STATUSES: readonly PrintJobStatus[];
+export declare const PRINT_JOB_STATUS_LABELS: Record<PrintJobStatus, string>;
+/** `hosts/{hostId}/printJobs/{jobId}` (AGL-3619). Server-written only. */
+export interface PrintJob {
+    printerId: string;
+    registerId?: string;
+    kind: PrintJobKind;
+    status: PrintJobStatus;
+    /** The receipt to render; the printer's brand and width decide the bytes at delivery. */
+    receipt?: ReceiptData;
+    /** The report a `report` job prints. */
+    report?: PrintReport;
+    /** Open the drawer as this job starts (a cash sale's receipt). */
+    openDrawer?: boolean;
+    /** The store a test page names. */
+    storeName?: string;
+    /** IANA zone a test page prints its time in. */
+    timeZone?: string;
+    orderId?: string;
+    /** Why it was printed, for the jobs list: `sale`, `reprint`, `paid_out`, … */
+    reason?: string;
+    /** Deliveries so far; each GET (Star) or poll hand-off (Epson) counts one. */
+    attempts: number;
+    createdAtMs: number;
+    claimedAtMs?: number;
+    finishedAtMs?: number;
+    /** After this the job is never delivered: a drawer that opens minutes later is a hazard. */
+    deliverByMs: number;
+    /** The printer's last result for this job, e.g. `200 OK`, `EPTR_REC_EMPTY`. */
+    resultCode?: string;
+    error?: string;
+    createdBy?: string;
+    /** Firestore TTL: the row is removed a week after it is written. */
+    expiresAt?: unknown;
+}
+/** A job is re-offered if its printer took it and never confirmed within this. */
+export declare const PRINT_JOB_CLAIM_TIMEOUT_MS: number;
+/** Deliveries before a job that keeps failing is given up on. */
+export declare const PRINT_JOB_MAX_ATTEMPTS = 3;
+/**
+ * How long each kind may wait for its printer. A receipt still matters for a
+ * while after the customer leaves; a drawer kick must never fire long after
+ * the sale that asked for it, because by then the drawer opening is unexpected
+ * cash exposure at an unattended till.
+ */
+export declare const PRINT_JOB_DELIVER_WITHIN_MS: Record<PrintJobKind, number>;
+/** Print-job rows are kept for a week, then removed by the Firestore TTL policy. */
+export declare const PRINT_JOB_RETENTION_MS: number;
+/** Star MACs and Epson IDs as we store them. */
+export declare function normalizePrinterDeviceId(brand: PrinterBrand, raw: unknown): string;
+/**
+ * A Star status code (`200 OK`, `211 Paper low`, `410%20Out%20of%20paper`) as
+ * a printer state. Codes are three or four digits followed by an optional
+ * description, URL-encoded because the printer also sends them as a query
+ * parameter. Families: 2xx online, 41x paper, 42x cover, 4xx/5xx/1xxx errors.
+ */
+export declare function starPrinterState(rawStatusCode: unknown): {
+    state: PrinterState;
+    detail: string;
+};
+/** Epson ASB status bits we act on (ePOS-Print XML `<response status>`). */
+export declare const EPSON_ASB: {
+    readonly OFFLINE: 8;
+    readonly COVER_OPEN: 32;
+    readonly MECHANICAL_ERROR: 1024;
+    readonly AUTOCUTTER_ERROR: 2048;
+    readonly UNRECOVERABLE_ERROR: 8192;
+    readonly AUTORECOVER_ERROR: 16384;
+    readonly RECEIPT_NEAR_END: 131072;
+    readonly RECEIPT_END: 524288;
+};
+/**
+ * An Epson result (`success`, `code`, `status`) as a printer state. The code
+ * names the failure when printing failed; the ASB bits say what the printer
+ * looks like now, which matters on success too (paper near end).
+ */
+export declare function epsonPrinterState(input: {
+    success: boolean;
+    code?: string;
+    status?: number;
+}): {
+    state: PrinterState;
+    detail: string;
+};
+/** The state a console row shows: a printer that stopped polling is offline whatever it said last. */
+export declare function printerDisplayState(status: PrinterStatus | undefined, nowMs: number): PrinterState | 'offline';

package/src/lib/model/commerce-printers.js

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export const PRINTER_BRANDS = [
+    'star',
+    'epson'
+];
+export const PRINTER_BRAND_LABELS = {
+    star: 'Star Micronics (CloudPRNT)',
+    epson: 'Epson (Server Direct Print)'
+};
+/** The models we document and test against, per brand. Free text is allowed. */ export const PRINTER_MODEL_SUGGESTIONS = {
+    star: [
+        'mC-Print3',
+        'TSP143IV',
+        'TSP100IV SK',
+        'mC-Label3'
+    ],
+    epson: [
+        'TM-m30III',
+        'TM-m30II',
+        'TM-m50II',
+        'TM-T88VII'
+    ]
+};
+/** Characters per line in the printer's default font A, by roll width. */ export function printerColumns(paperWidthMm) {
+    return paperWidthMm === 58 ? 32 : 48;
+}
+export const PRINTER_STATE_LABELS = {
+    online: 'Online',
+    paper_low: 'Paper low',
+    paper_out: 'Out of paper',
+    cover_open: 'Cover open',
+    error: 'Printer error',
+    unknown: 'Waiting for the printer'
+};
+/** A printer that has not polled for this long is shown as offline. */ export const PRINTER_OFFLINE_AFTER_MS = 2 * 60 * 1000;
+export const PRINT_JOB_ACTIVE_STATUSES = [
+    'queued',
+    'printing'
+];
+export const PRINT_JOB_STATUS_LABELS = {
+    queued: 'Waiting',
+    printing: 'Printing',
+    done: 'Printed',
+    failed: 'Failed',
+    expired: 'Expired',
+    canceled: 'Canceled'
+};
+/** A job is re-offered if its printer took it and never confirmed within this. */ export const PRINT_JOB_CLAIM_TIMEOUT_MS = 90 * 1000;
+/** Deliveries before a job that keeps failing is given up on. */ export const PRINT_JOB_MAX_ATTEMPTS = 3;
+/**
+ * How long each kind may wait for its printer. A receipt still matters for a
+ * while after the customer leaves; a drawer kick must never fire long after
+ * the sale that asked for it, because by then the drawer opening is unexpected
+ * cash exposure at an unattended till.
+ */ export const PRINT_JOB_DELIVER_WITHIN_MS = {
+    receipt: 30 * 60 * 1000,
+    // A ticket that reaches the kitchen long after the order is a meal remade twice.
+    kitchen: 10 * 60 * 1000,
+    test: 10 * 60 * 1000,
+    drawer: 2 * 60 * 1000,
+    report: 30 * 60 * 1000
+};
+/** Print-job rows are kept for a week, then removed by the Firestore TTL policy. */ export const PRINT_JOB_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** Star MACs and Epson IDs as we store them. */ export function normalizePrinterDeviceId(brand, raw) {
+    const value = String(raw != null ? raw : '').trim();
+    if (brand === 'star') {
+        const hex = value.toLowerCase().replace(/[^0-9a-f]/g, '');
+        if (hex.length !== 12) return '';
+        return hex.match(/../g).join(':');
+    }
+    // Epson's WebConfig ID: the same 1-30 safe characters its job ids allow.
+    return /^[A-Za-z0-9._-]{1,30}$/.test(value) ? value : '';
+}
+/**
+ * A Star status code (`200 OK`, `211 Paper low`, `410%20Out%20of%20paper`) as
+ * a printer state. Codes are three or four digits followed by an optional
+ * description, URL-encoded because the printer also sends them as a query
+ * parameter. Families: 2xx online, 41x paper, 42x cover, 4xx/5xx/1xxx errors.
+ */ export function starPrinterState(rawStatusCode) {
+    var _ref;
+    var _detail_match;
+    let detail = String(rawStatusCode != null ? rawStatusCode : '').trim();
+    try {
+        detail = decodeURIComponent(detail.replace(/\+/g, ' '));
+    } catch (unused) {
+    // Not URL-encoded after all; keep the raw text.
+    }
+    const code = (_ref = (_detail_match = detail.match(/^\d{3,4}/)) == null ? void 0 : _detail_match[0]) != null ? _ref : '';
+    if (!code) return {
+        state: 'unknown',
+        detail
+    };
+    if (code === '211') return {
+        state: 'paper_low',
+        detail
+    };
+    if (code.startsWith('2')) return {
+        state: 'online',
+        detail
+    };
+    if (code.length === 3 && code.startsWith('41')) return {
+        state: 'paper_out',
+        detail
+    };
+    if (code.length === 3 && code.startsWith('42')) return {
+        state: 'cover_open',
+        detail
+    };
+    return {
+        state: 'error',
+        detail
+    };
+}
+/** Epson ASB status bits we act on (ePOS-Print XML `<response status>`). */ export const EPSON_ASB = {
+    OFFLINE: 0x00000008,
+    COVER_OPEN: 0x00000020,
+    MECHANICAL_ERROR: 0x00000400,
+    AUTOCUTTER_ERROR: 0x00000800,
+    UNRECOVERABLE_ERROR: 0x00002000,
+    AUTORECOVER_ERROR: 0x00004000,
+    RECEIPT_NEAR_END: 0x00020000,
+    RECEIPT_END: 0x00080000
+};
+/**
+ * An Epson result (`success`, `code`, `status`) as a printer state. The code
+ * names the failure when printing failed; the ASB bits say what the printer
+ * looks like now, which matters on success too (paper near end).
+ */ export function epsonPrinterState(input) {
+    var _input_code;
+    const code = String((_input_code = input.code) != null ? _input_code : '');
+    const status = Number.isFinite(input.status) ? Number(input.status) : 0;
+    if (code === 'EPTR_REC_EMPTY' || status & EPSON_ASB.RECEIPT_END) {
+        return {
+            state: 'paper_out',
+            detail: code || 'Roll paper has run out'
+        };
+    }
+    if (code === 'EPTR_COVER_OPEN' || status & EPSON_ASB.COVER_OPEN) {
+        return {
+            state: 'cover_open',
+            detail: code || 'Cover is open'
+        };
+    }
+    if (!input.success || status & (EPSON_ASB.MECHANICAL_ERROR | EPSON_ASB.AUTOCUTTER_ERROR | EPSON_ASB.UNRECOVERABLE_ERROR | EPSON_ASB.AUTORECOVER_ERROR)) {
+        return {
+            state: 'error',
+            detail: code || 'Printer error'
+        };
+    }
+    if (status & EPSON_ASB.RECEIPT_NEAR_END) {
+        return {
+            state: 'paper_low',
+            detail: 'Roll paper is nearly out'
+        };
+    }
+    return {
+        state: 'online',
+        detail: code
+    };
+}
+/** The state a console row shows: a printer that stopped polling is offline whatever it said last. */ export function printerDisplayState(status, nowMs) {
+    if (!(status == null ? void 0 : status.atMs)) return 'unknown';
+    if (nowMs - status.atMs > PRINTER_OFFLINE_AFTER_MS) return 'offline';
+    return status.state;
+}
+
+//# sourceMappingURL=commerce-printers.js.map

package/src/lib/model/commerce-printers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-printers.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { ReceiptData } from './commerce-receipt'\n\n/**\n * Cloud receipt printers (AGL-3619).\n *\n * A browser register cannot reach a USB or LAN printer without a driver, and\n * an https console cannot talk to a printer's plain-http web service. Both\n * vendors that matter at a counter solve this the same way: the PRINTER polls\n * an https URL, and the server answers with the next job.\n *\n *  - Star CloudPRNT (mC-Print3, TSP100IV, mC-Label3): the printer POSTs its\n *    status as JSON, GETs the job when told one is ready, and DELETEs it to\n *    confirm, with the result in a `code` query parameter.\n *  - Epson Server Direct Print (TM-m30III, TM-m50, TM-T88VII): the printer\n *    POSTs a form (`ConnectionType=GetRequest`) and receives ePOS-Print XML in\n *    the response, then POSTs `ConnectionType=SetResponse` with the result.\n *\n * Every printer belongs to one register and polls one URL that carries the\n * site, the printer and a per-printer secret. The secret is not stored: it is\n * an HMAC of those ids and a rotation counter (`server/printer-secret.ts`), so\n * the console can show it to a manager again and \"Regenerate\" invalidates the\n * old URL by bumping the counter.\n *\n * `hosts/{hostId}/printers/{printerId}` and `hosts/{hostId}/printJobs/{jobId}`\n * are written only by the server (the Firestore rules deny every client\n * write); the console reads both to show status and recent jobs.\n */\n\nexport type PrinterBrand = 'star' | 'epson'\n\nexport const PRINTER_BRANDS: readonly PrinterBrand[] = ['star', 'epson']\n\nexport const PRINTER_BRAND_LABELS: Record<PrinterBrand, string> = {\n  star: 'Star Micronics (CloudPRNT)',\n  epson: 'Epson (Server Direct Print)',\n}\n\n/** The models we document and test against, per brand. Free text is allowed. */\nexport const PRINTER_MODEL_SUGGESTIONS: Record<PrinterBrand, readonly string[]> = {\n  star: ['mC-Print3', 'TSP143IV', 'TSP100IV SK', 'mC-Label3'],\n  epson: ['TM-m30III', 'TM-m30II', 'TM-m50II', 'TM-T88VII'],\n}\n\n/** Roll width; it sets the characters per line. */\nexport type PrinterPaperWidth = 80 | 58\n\n/** Characters per line in the printer's default font A, by roll width. */\nexport function printerColumns(paperWidthMm: PrinterPaperWidth | undefined): number {\n  return paperWidthMm === 58 ? 32 : 48\n}\n\n/**\n * What the printer last told us about itself. `online` means it can print;\n * `paper_low` still prints. Everything else stops printing until a person\n * fixes it.\n */\nexport type PrinterState =\n  | 'online'\n  | 'paper_low'\n  | 'paper_out'\n  | 'cover_open'\n  | 'error'\n  | 'unknown'\n\nexport const PRINTER_STATE_LABELS: Record<PrinterState, string> = {\n  online: 'Online',\n  paper_low: 'Paper low',\n  paper_out: 'Out of paper',\n  cover_open: 'Cover open',\n  error: 'Printer error',\n  unknown: 'Waiting for the printer',\n}\n\n/** A printer that has not polled for this long is shown as offline. */\nexport const PRINTER_OFFLINE_AFTER_MS = 2 * 60 * 1000\n\nexport interface PrinterStatus {\n  state: PrinterState\n  /** The printer's own words, e.g. Star's `410 Out of paper` or Epson's `EPTR_COVER_OPEN`. */\n  detail?: string\n  /** Last time the printer polled, ms since epoch. */\n  atMs: number\n  /** Polling interval the printer reported (Star `GetPollInterval`), seconds. */\n  pollSeconds?: number\n}\n\n/** `hosts/{hostId}/printers/{printerId}` (AGL-3619). Server-written only. */\nexport interface PosPrinter {\n  name: string\n  brand: PrinterBrand\n  model?: string\n  /**\n   * The printer's identity as it reports it: the Ethernet MAC for Star\n   * (`00:11:62:aa:bb:cc`, lower case), the Server Direct Print `ID` set in\n   * Epson's WebConfig. A poll that names a different device is refused, so a\n   * leaked URL alone cannot drain the queue from another printer.\n   */\n  deviceId: string\n  registerId: string\n  paperWidthMm?: PrinterPaperWidth\n  /** Print a customer receipt when a sale on this register completes. */\n  autoPrintReceipts: boolean\n  /** Open the cash drawer wired to this printer on cash sales, cash refunds and paid-outs. */\n  kickDrawer: boolean\n  /**\n   * Print a kitchen (or bar, or packing) ticket for every sale on this\n   * register: the order number, each item and quantity, and no prices.\n   */\n  kitchenTickets?: boolean\n  /**\n   * The NV logo stored in the printer with the vendor's utility, printed at the\n   * top of every receipt: Star's logo number (1-255), Epson's `key1,key2`\n   * (e.g. `48,48`). Empty prints no logo.\n   */\n  logoKey?: string\n  /** Bumped by \"Regenerate URL\"; part of the HMAC that makes the secret. */\n  secretVersion: number\n  status?: PrinterStatus\n  createdAtMs: number\n  createdBy?: string\n  updatedAtMs?: number\n}\n\nexport type PrintJobKind = 'receipt' | 'kitchen' | 'drawer' | 'test' | 'report'\n\n/**\n * A titled report printed on the receipt roll (AGL-3609): a register shift's\n * X or Z report. Rows are already formatted, so every printer prints the\n * figures the console shows.\n */\nexport interface PrintReport {\n  title: string\n  storeName: string\n  subtitle?: string\n  sections: Array<{ section: string; rows: Array<{ label: string; value: string; strong?: boolean }> }>\n}\n\nexport type PrintJobStatus = 'queued' | 'printing' | 'done' | 'failed' | 'expired' | 'canceled'\n\nexport const PRINT_JOB_ACTIVE_STATUSES: readonly PrintJobStatus[] = ['queued', 'printing']\n\nexport const PRINT_JOB_STATUS_LABELS: Record<PrintJobStatus, string> = {\n  queued: 'Waiting',\n  printing: 'Printing',\n  done: 'Printed',\n  failed: 'Failed',\n  expired: 'Expired',\n  canceled: 'Canceled',\n}\n\n/** `hosts/{hostId}/printJobs/{jobId}` (AGL-3619). Server-written only. */\nexport interface PrintJob {\n  printerId: string\n  registerId?: string\n  kind: PrintJobKind\n  status: PrintJobStatus\n  /** The receipt to render; the printer's brand and width decide the bytes at delivery. */\n  receipt?: ReceiptData\n  /** The report a `report` job prints. */\n  report?: PrintReport\n  /** Open the drawer as this job starts (a cash sale's receipt). */\n  openDrawer?: boolean\n  /** The store a test page names. */\n  storeName?: string\n  /** IANA zone a test page prints its time in. */\n  timeZone?: string\n  orderId?: string\n  /** Why it was printed, for the jobs list: `sale`, `reprint`, `paid_out`, … */\n  reason?: string\n  /** Deliveries so far; each GET (Star) or poll hand-off (Epson) counts one. */\n  attempts: number\n  createdAtMs: number\n  claimedAtMs?: number\n  finishedAtMs?: number\n  /** After this the job is never delivered: a drawer that opens minutes later is a hazard. */\n  deliverByMs: number\n  /** The printer's last result for this job, e.g. `200 OK`, `EPTR_REC_EMPTY`. */\n  resultCode?: string\n  error?: string\n  createdBy?: string\n  /** Firestore TTL: the row is removed a week after it is written. */\n  expiresAt?: unknown\n}\n\n/** A job is re-offered if its printer took it and never confirmed within this. */\nexport const PRINT_JOB_CLAIM_TIMEOUT_MS = 90 * 1000\n\n/** Deliveries before a job that keeps failing is given up on. */\nexport const PRINT_JOB_MAX_ATTEMPTS = 3\n\n/**\n * How long each kind may wait for its printer. A receipt still matters for a\n * while after the customer leaves; a drawer kick must never fire long after\n * the sale that asked for it, because by then the drawer opening is unexpected\n * cash exposure at an unattended till.\n */\nexport const PRINT_JOB_DELIVER_WITHIN_MS: Record<PrintJobKind, number> = {\n  receipt: 30 * 60 * 1000,\n  // A ticket that reaches the kitchen long after the order is a meal remade twice.\n  kitchen: 10 * 60 * 1000,\n  test: 10 * 60 * 1000,\n  drawer: 2 * 60 * 1000,\n  report: 30 * 60 * 1000,\n}\n\n/** Print-job rows are kept for a week, then removed by the Firestore TTL policy. */\nexport const PRINT_JOB_RETENTION_MS = 7 * 24 * 60 * 60 * 1000\n\n/** Star MACs and Epson IDs as we store them. */\nexport function normalizePrinterDeviceId(brand: PrinterBrand, raw: unknown): string {\n  const value = String(raw ?? '').trim()\n  if (brand === 'star') {\n    const hex = value.toLowerCase().replace(/[^0-9a-f]/g, '')\n    if (hex.length !== 12) return ''\n    return hex.match(/../g)!.join(':')\n  }\n  // Epson's WebConfig ID: the same 1-30 safe characters its job ids allow.\n  return /^[A-Za-z0-9._-]{1,30}$/.test(value) ? value : ''\n}\n\n/**\n * A Star status code (`200 OK`, `211 Paper low`, `410%20Out%20of%20paper`) as\n * a printer state. Codes are three or four digits followed by an optional\n * description, URL-encoded because the printer also sends them as a query\n * parameter. Families: 2xx online, 41x paper, 42x cover, 4xx/5xx/1xxx errors.\n */\nexport function starPrinterState(rawStatusCode: unknown): { state: PrinterState; detail: string } {\n  let detail = String(rawStatusCode ?? '').trim()\n  try {\n    detail = decodeURIComponent(detail.replace(/\\+/g, ' '))\n  } catch {\n    // Not URL-encoded after all; keep the raw text.\n  }\n  const code = detail.match(/^\\d{3,4}/)?.[0] ?? ''\n  if (!code) return { state: 'unknown', detail }\n  if (code === '211') return { state: 'paper_low', detail }\n  if (code.startsWith('2')) return { state: 'online', detail }\n  if (code.length === 3 && code.startsWith('41')) return { state: 'paper_out', detail }\n  if (code.length === 3 && code.startsWith('42')) return { state: 'cover_open', detail }\n  return { state: 'error', detail }\n}\n\n/** Epson ASB status bits we act on (ePOS-Print XML `<response status>`). */\nexport const EPSON_ASB = {\n  OFFLINE: 0x00000008,\n  COVER_OPEN: 0x00000020,\n  MECHANICAL_ERROR: 0x00000400,\n  AUTOCUTTER_ERROR: 0x00000800,\n  UNRECOVERABLE_ERROR: 0x00002000,\n  AUTORECOVER_ERROR: 0x00004000,\n  RECEIPT_NEAR_END: 0x00020000,\n  RECEIPT_END: 0x00080000,\n} as const\n\n/**\n * An Epson result (`success`, `code`, `status`) as a printer state. The code\n * names the failure when printing failed; the ASB bits say what the printer\n * looks like now, which matters on success too (paper near end).\n */\nexport function epsonPrinterState(input: {\n  success: boolean\n  code?: string\n  status?: number\n}): { state: PrinterState; detail: string } {\n  const code = String(input.code ?? '')\n  const status = Number.isFinite(input.status) ? Number(input.status) : 0\n  if (code === 'EPTR_REC_EMPTY' || status & EPSON_ASB.RECEIPT_END) {\n    return { state: 'paper_out', detail: code || 'Roll paper has run out' }\n  }\n  if (code === 'EPTR_COVER_OPEN' || status & EPSON_ASB.COVER_OPEN) {\n    return { state: 'cover_open', detail: code || 'Cover is open' }\n  }\n  if (\n    !input.success ||\n    status &\n      (EPSON_ASB.MECHANICAL_ERROR |\n        EPSON_ASB.AUTOCUTTER_ERROR |\n        EPSON_ASB.UNRECOVERABLE_ERROR |\n        EPSON_ASB.AUTORECOVER_ERROR)\n  ) {\n    return { state: 'error', detail: code || 'Printer error' }\n  }\n  if (status & EPSON_ASB.RECEIPT_NEAR_END) {\n    return { state: 'paper_low', detail: 'Roll paper is nearly out' }\n  }\n  return { state: 'online', detail: code }\n}\n\n/** The state a console row shows: a printer that stopped polling is offline whatever it said last. */\nexport function printerDisplayState(\n  status: PrinterStatus | undefined,\n  nowMs: number,\n): PrinterState | 'offline' {\n  if (!status?.atMs) return 'unknown'\n  if (nowMs - status.atMs > PRINTER_OFFLINE_AFTER_MS) return 'offline'\n  return status.state\n}\n"],"names":["PRINTER_BRANDS","PRINTER_BRAND_LABELS","star","epson","PRINTER_MODEL_SUGGESTIONS","printerColumns","paperWidthMm","PRINTER_STATE_LABELS","online","paper_low","paper_out","cover_open","error","unknown","PRINTER_OFFLINE_AFTER_MS","PRINT_JOB_ACTIVE_STATUSES","PRINT_JOB_STATUS_LABELS","queued","printing","done","failed","expired","canceled","PRINT_JOB_CLAIM_TIMEOUT_MS","PRINT_JOB_MAX_ATTEMPTS","PRINT_JOB_DELIVER_WITHIN_MS","receipt","kitchen","test","drawer","report","PRINT_JOB_RETENTION_MS","normalizePrinterDeviceId","brand","raw","value","String","trim","hex","toLowerCase","replace","length","match","join","starPrinterState","rawStatusCode","detail","decodeURIComponent","code","state","startsWith","EPSON_ASB","OFFLINE","COVER_OPEN","MECHANICAL_ERROR","AUTOCUTTER_ERROR","UNRECOVERABLE_ERROR","AUTORECOVER_ERROR","RECEIPT_NEAR_END","RECEIPT_END","epsonPrinterState","input","status","Number","isFinite","success","printerDisplayState","nowMs","atMs"],"mappings":"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"}

package/src/lib/model/commerce-receipt.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { HostOrder } from './commerce-orders';
+/**
+ * A receipt as DATA (AGL-3619), shared by every surface that prints one: the
+ * cloud printer renderers (Star bytes, Epson ePOS-Print XML, plain text) and
+ * the 80mm thermal receipt the register shows and prints from the browser
+ * (AGL-3609). One model, so a reprint from the console, an auto-print on a
+ * sale and the on-screen receipt cannot disagree about what was sold.
+ *
+ * Amounts are integer minor units in `currency`, and every label is already
+ * the words to print: the renderers lay text out, they do not decide it.
+ */
+export interface ReceiptLine {
+    name: string;
+    /** A variant label or SKU, printed under the name. */
+    detail?: string;
+    quantity: number;
+    unitCents: number;
+    totalCents: number;
+}
+export interface ReceiptTender {
+    /** e.g. `Cash`, `Visa •••• 4242`, `Gift card`. */
+    label: string;
+    amountCents: number;
+}
+export interface ReceiptData {
+    storeName: string;
+    /** Address, phone or website lines under the store name. */
+    storeLines?: string[];
+    /** The printable order number, e.g. `1042`. */
+    orderNumber: string;
+    orderId?: string;
+    createdAtMs: number;
+    /** IANA zone the timestamp is printed in; UTC when absent. */
+    timeZone?: string;
+    registerName?: string;
+    cashierName?: string;
+    /** ISO 4217, any case. */
+    currency: string;
+    lines: ReceiptLine[];
+    subtotalCents: number;
+    discountCents?: number;
+    shippingCents?: number;
+    taxCents?: number;
+    tipCents?: number;
+    totalCents: number;
+    tenders?: ReceiptTender[];
+    changeCents?: number;
+    refundedCents?: number;
+    /** Printed small at the bottom: a returns policy, a thank-you. */
+    footer?: string;
+    /** Code128 under the totals so a return can scan the order back up. Defaults to the order number. */
+    barcode?: string;
+    /** `REPRINT` / `COPY` banner. */
+    banner?: string;
+}
+/** A money amount for print: `$12.50`, `-€3.00`. Locale is fixed so receipts read the same everywhere. */
+export declare function formatReceiptMoney(cents: number, currency: string): string;
+/** The receipt timestamp, e.g. `Oct 6, 2026, 3:04 PM`. */
+export declare function formatReceiptTime(atMs: number, timeZone?: string): string;
+/**
+ * The tenders an order was paid with: the register's payment ledger
+ * (`payments[]`, AGL-3607) when the order has one, otherwise a single tender
+ * read from the order itself (a cash sale's `changeCents`, a QR card sale).
+ */
+export declare function receiptTendersFromOrder(order: HostOrder & Record<string, any>): {
+    tenders: ReceiptTender[];
+    changeCents: number;
+    tipCents: number;
+};
+export interface ReceiptContext {
+    storeName: string;
+    storeLines?: string[];
+    registerName?: string;
+    cashierName?: string;
+    timeZone?: string;
+    currency?: string;
+    footer?: string;
+    banner?: string;
+}
+/** The receipt an order prints, from the order as stored. */
+export declare function receiptDataFromOrder(orderId: string, order: HostOrder & Record<string, any>, context: ReceiptContext): ReceiptData;