@stardeck-customer-apps/testing 0.7.0 → 0.8.0

package/SKILL.md

@@ -175,7 +175,8 @@ externalId })` helper models a trusted platform/channel link, and
   `.all()`, `.latest()`, `.to(recipient)`, `.channel("line")`, `.count`, `.clear()`.
 - `app.edge` — edge print/display/bindings from edge-sdk: `.prints`, `.displays`,
   `.testPrints`, `.latestPrint()`, `.latestDisplay()`, `.bindings`,
-  `.seedDevices()`, `.seedPeripherals()`, `.seedBindings()`, `.count`, `.clear()`.
+  `.seedDevices()`, `.seedPeripherals()`, `.seedBindings()`,
+  `.seedCapabilities(caps, peripheralId?)`, `.count`, `.clear()`.
 - `app.query(sql, params?)` / `app.db` — direct database access for
   assertions and seeding.
 - `callRoute(handler, opts)` — invoke an App Router route handler with a real
@@ -242,8 +243,32 @@ cursor, limit })`; `list()` intentionally keeps its previous array shape.
 - `client.slack` / `client.line` / `client.facebook` send endpoints — captured
   in `app.messages`.
 - `createEdgeClient()` (print, pair/unpair, list devices/peripherals, show/clear
-  display, test print) — captured in `app.edge`; seed devices/peripherals for
-  pairing pickers via `app.edge.seedDevices()` / `seedPeripherals()`.
+  display, test print, `getCapabilities()`) — captured in `app.edge`; seed
+  devices/peripherals for pairing pickers via `app.edge.seedDevices()` /
+  `seedPeripherals()`.
+
+### Receipt layout and printer capabilities
+
+`edge.getCapabilities(target)` answers with a stock 80mm text-mode printer
+unless the test says otherwise. Seed a different one to exercise layout,
+degradation, and preview code — per peripheral when a test models more than one
+station:
+
+```ts
+app.edge.seedPeripherals([kitchenPrinter, counterPrinter]);
+app.edge.seedCapabilities({ ...caps58mm, renderMode: "raster" }, kitchenPrinter.id);
+
+const caps = await edge.getCapabilities({ peripheralId: kitchenPrinter.id });
+expect(caps.columns).toBe(32);
+```
+
+The simulator resolves the target the way production does: an unpaired alias
+throws `BindingError` (`BINDING_NOT_FOUND`) and an unknown peripheral 404s, so
+target-resolution bugs surface in tests rather than in the field.
+
+Printed receipts are captured whole, so assert on the ordered blocks an app
+produced — `app.edge.latestPrint()?.receipt.blocks` — not just its totals.
+
 - `next/headers` (`headers()`/`cookies()`) inside handlers under `callRoute`.
 
 ## End-to-end (Playwright) suite

package/dist/index.d.mts

@@ -204,17 +204,54 @@ interface TestMessages {
     clear(): void;
     get count(): number;
 }
+interface ReceiptItem {
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    total: number;
+    note?: string;
+}
+type ReceiptAlign = "left" | "center" | "right";
+type ReceiptTextSize = "small" | "normal" | "large";
+/** Mirrors the edge SDK's block model so assertions can inspect the exact
+ * ordered content an app printed, not just its totals. */
+type ReceiptBlock = {
+    type: "text";
+    text: string;
+    align?: ReceiptAlign;
+    bold?: boolean;
+    size?: ReceiptTextSize;
+} | {
+    type: "columns";
+    left: string;
+    right: string;
+    bold?: boolean;
+    size?: ReceiptTextSize;
+} | {
+    type: "separator";
+    style?: "dashed" | "solid";
+} | {
+    type: "spacer";
+    lines?: number;
+} | {
+    type: "items";
+    rows: ReceiptItem[];
+} | {
+    type: "barcode";
+    format: "qr" | "code128";
+    data: string;
+    align?: ReceiptAlign;
+    /** QR width as a percentage of the printable width (5–100). Omitted →
+     * the printer's default cell size. Mirrors the edge SDK. */
+    widthPercent?: number;
+};
 interface ReceiptPayload {
+    paperWidth?: "58mm" | "80mm";
+    blocks?: ReceiptBlock[];
     header?: {
         lines: string[];
     };
-    items?: Array<{
-        name: string;
-        quantity: number;
-        unitPrice: number;
-        total: number;
-        note?: string;
-    }>;
+    items?: ReceiptItem[];
     subtotal?: number;
     tax?: number;
     discount?: number;
@@ -232,6 +269,23 @@ interface ReceiptPayload {
     };
     rawEscPos?: string;
 }
+/** Mirrors the edge SDK's PrinterCapabilities so tests can drive
+ * `edge.getCapabilities()` without the SDK being a dependency here. */
+interface PrinterCapabilities {
+    paperWidth: "58mm" | "80mm";
+    columns: number;
+    dotsPerLine: number;
+    renderMode: "text" | "raster";
+    textEncoding: "utf8" | "tis620";
+    unicodeText: boolean;
+    thaiText: boolean;
+    bold: boolean;
+    textSizes: ReceiptTextSize[];
+    barcodeFormats: Array<"qr" | "code128">;
+    rasterImages: boolean;
+    cut: boolean;
+    cashDrawer: boolean;
+}
 interface DeviceInfo {
     id: string;
     displayName: string;
@@ -301,6 +355,13 @@ interface TestEdge {
     seedDevices(devices: DeviceInfo[]): void;
     seedPeripherals(peripherals: PeripheralInfo[]): void;
     seedBindings(bindings: BindingInfo[]): void;
+    /**
+     * Answer `edge.getCapabilities()` with a specific printer — e.g. a 58mm or a
+     * raster/Thai one — so layout and preview code can be tested against it.
+     * Pass a `peripheralId` to model stations with different printers; without
+     * one this sets the default every untargeted lookup falls back to.
+     */
+    seedCapabilities(capabilities: PrinterCapabilities | null, peripheralId?: string): void;
     clear(): void;
     get count(): number;
 }

package/dist/index.d.ts

@@ -204,17 +204,54 @@ interface TestMessages {
     clear(): void;
     get count(): number;
 }
+interface ReceiptItem {
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    total: number;
+    note?: string;
+}
+type ReceiptAlign = "left" | "center" | "right";
+type ReceiptTextSize = "small" | "normal" | "large";
+/** Mirrors the edge SDK's block model so assertions can inspect the exact
+ * ordered content an app printed, not just its totals. */
+type ReceiptBlock = {
+    type: "text";
+    text: string;
+    align?: ReceiptAlign;
+    bold?: boolean;
+    size?: ReceiptTextSize;
+} | {
+    type: "columns";
+    left: string;
+    right: string;
+    bold?: boolean;
+    size?: ReceiptTextSize;
+} | {
+    type: "separator";
+    style?: "dashed" | "solid";
+} | {
+    type: "spacer";
+    lines?: number;
+} | {
+    type: "items";
+    rows: ReceiptItem[];
+} | {
+    type: "barcode";
+    format: "qr" | "code128";
+    data: string;
+    align?: ReceiptAlign;
+    /** QR width as a percentage of the printable width (5–100). Omitted →
+     * the printer's default cell size. Mirrors the edge SDK. */
+    widthPercent?: number;
+};
 interface ReceiptPayload {
+    paperWidth?: "58mm" | "80mm";
+    blocks?: ReceiptBlock[];
     header?: {
         lines: string[];
     };
-    items?: Array<{
-        name: string;
-        quantity: number;
-        unitPrice: number;
-        total: number;
-        note?: string;
-    }>;
+    items?: ReceiptItem[];
     subtotal?: number;
     tax?: number;
     discount?: number;
@@ -232,6 +269,23 @@ interface ReceiptPayload {
     };
     rawEscPos?: string;
 }
+/** Mirrors the edge SDK's PrinterCapabilities so tests can drive
+ * `edge.getCapabilities()` without the SDK being a dependency here. */
+interface PrinterCapabilities {
+    paperWidth: "58mm" | "80mm";
+    columns: number;
+    dotsPerLine: number;
+    renderMode: "text" | "raster";
+    textEncoding: "utf8" | "tis620";
+    unicodeText: boolean;
+    thaiText: boolean;
+    bold: boolean;
+    textSizes: ReceiptTextSize[];
+    barcodeFormats: Array<"qr" | "code128">;
+    rasterImages: boolean;
+    cut: boolean;
+    cashDrawer: boolean;
+}
 interface DeviceInfo {
     id: string;
     displayName: string;
@@ -301,6 +355,13 @@ interface TestEdge {
     seedDevices(devices: DeviceInfo[]): void;
     seedPeripherals(peripherals: PeripheralInfo[]): void;
     seedBindings(bindings: BindingInfo[]): void;
+    /**
+     * Answer `edge.getCapabilities()` with a specific printer — e.g. a 58mm or a
+     * raster/Thai one — so layout and preview code can be tested against it.
+     * Pass a `peripheralId` to model stations with different printers; without
+     * one this sets the default every untargeted lookup falls back to.
+     */
+    seedCapabilities(capabilities: PrinterCapabilities | null, peripheralId?: string): void;
     clear(): void;
     get count(): number;
 }

package/dist/index.js

@@ -117,6 +117,8 @@ var state = globalSingleton("state", () => ({
   edgeDevices: [],
   edgePeripherals: [],
   edgeBindings: /* @__PURE__ */ new Map(),
+  edgeCapabilities: null,
+  edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
   allowNetwork: false
 }));
 function requireDb() {
@@ -1877,6 +1879,44 @@ function buildBinding(alias, peripheralId) {
     updatedAt: now2()
   };
 }
+var DEFAULT_CAPABILITIES = {
+  paperWidth: "80mm",
+  columns: 48,
+  dotsPerLine: 576,
+  renderMode: "text",
+  textEncoding: "utf8",
+  unicodeText: false,
+  thaiText: false,
+  bold: true,
+  textSizes: ["small", "normal", "large"],
+  barcodeFormats: ["qr"],
+  rasterImages: true,
+  cut: true,
+  cashDrawer: false
+};
+function handleCapabilities(request) {
+  const url = new URL(request.url);
+  const alias = url.searchParams.get("alias");
+  const deviceId = url.searchParams.get("deviceId");
+  let peripheralId = url.searchParams.get("peripheralId");
+  if (alias) {
+    const binding = state.edgeBindings.get(alias);
+    if (!binding) return bindingNotFound(alias);
+    peripheralId = binding.peripheral?.id ?? null;
+  }
+  if (peripheralId) {
+    const peripheral = findPeripheral(peripheralId);
+    if (!peripheral) {
+      return edgeFailure("Peripheral not found or its device is not granted to this project", 404);
+    }
+    const seeded = state.edgePeripheralCapabilities.get(peripheralId);
+    return success({ capabilities: seeded ?? state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+  }
+  if (deviceId && !state.edgeDevices.some((d) => d.id === deviceId)) {
+    return edgeFailure("Project does not have access to this device", 403);
+  }
+  return success({ capabilities: state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+}
 function handleListDevices() {
   return success({ devices: [...state.edgeDevices] });
 }
@@ -1980,6 +2020,9 @@ async function handleEdgeRequest(request, subPath) {
   if (subPath === "/print" && method === "POST") {
     return handlePrint(request);
   }
+  if (subPath === "/capabilities" && method === "GET") {
+    return handleCapabilities(request);
+  }
   if (subPath === "/devices" && method === "GET") {
     return handleListDevices();
   }
@@ -2041,7 +2084,17 @@ function createEdge() {
         state.edgeBindings.set(binding.alias, binding);
       }
     },
+    seedCapabilities(capabilities, peripheralId) {
+      if (peripheralId === void 0) {
+        state.edgeCapabilities = capabilities;
+        return;
+      }
+      if (capabilities === null) state.edgePeripheralCapabilities.delete(peripheralId);
+      else state.edgePeripheralCapabilities.set(peripheralId, capabilities);
+    },
     clear() {
+      state.edgeCapabilities = null;
+      state.edgePeripheralCapabilities.clear();
       state.edgePrints = [];
       state.edgeDisplays = [];
       state.edgeTestPrints = [];

package/dist/index.mjs

@@ -71,6 +71,8 @@ var state = globalSingleton("state", () => ({
   edgeDevices: [],
   edgePeripherals: [],
   edgeBindings: /* @__PURE__ */ new Map(),
+  edgeCapabilities: null,
+  edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
   allowNetwork: false
 }));
 function requireDb() {
@@ -1831,6 +1833,44 @@ function buildBinding(alias, peripheralId) {
     updatedAt: now2()
   };
 }
+var DEFAULT_CAPABILITIES = {
+  paperWidth: "80mm",
+  columns: 48,
+  dotsPerLine: 576,
+  renderMode: "text",
+  textEncoding: "utf8",
+  unicodeText: false,
+  thaiText: false,
+  bold: true,
+  textSizes: ["small", "normal", "large"],
+  barcodeFormats: ["qr"],
+  rasterImages: true,
+  cut: true,
+  cashDrawer: false
+};
+function handleCapabilities(request) {
+  const url = new URL(request.url);
+  const alias = url.searchParams.get("alias");
+  const deviceId = url.searchParams.get("deviceId");
+  let peripheralId = url.searchParams.get("peripheralId");
+  if (alias) {
+    const binding = state.edgeBindings.get(alias);
+    if (!binding) return bindingNotFound(alias);
+    peripheralId = binding.peripheral?.id ?? null;
+  }
+  if (peripheralId) {
+    const peripheral = findPeripheral(peripheralId);
+    if (!peripheral) {
+      return edgeFailure("Peripheral not found or its device is not granted to this project", 404);
+    }
+    const seeded = state.edgePeripheralCapabilities.get(peripheralId);
+    return success({ capabilities: seeded ?? state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+  }
+  if (deviceId && !state.edgeDevices.some((d) => d.id === deviceId)) {
+    return edgeFailure("Project does not have access to this device", 403);
+  }
+  return success({ capabilities: state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+}
 function handleListDevices() {
   return success({ devices: [...state.edgeDevices] });
 }
@@ -1934,6 +1974,9 @@ async function handleEdgeRequest(request, subPath) {
   if (subPath === "/print" && method === "POST") {
     return handlePrint(request);
   }
+  if (subPath === "/capabilities" && method === "GET") {
+    return handleCapabilities(request);
+  }
   if (subPath === "/devices" && method === "GET") {
     return handleListDevices();
   }
@@ -1995,7 +2038,17 @@ function createEdge() {
         state.edgeBindings.set(binding.alias, binding);
       }
     },
+    seedCapabilities(capabilities, peripheralId) {
+      if (peripheralId === void 0) {
+        state.edgeCapabilities = capabilities;
+        return;
+      }
+      if (capabilities === null) state.edgePeripheralCapabilities.delete(peripheralId);
+      else state.edgePeripheralCapabilities.set(peripheralId, capabilities);
+    },
     clear() {
+      state.edgeCapabilities = null;
+      state.edgePeripheralCapabilities.clear();
       state.edgePrints = [];
       state.edgeDisplays = [];
       state.edgeTestPrints = [];

package/dist/next/headers-shim.js

@@ -63,6 +63,8 @@ var state = globalSingleton("state", () => ({
   edgeDevices: [],
   edgePeripherals: [],
   edgeBindings: /* @__PURE__ */ new Map(),
+  edgeCapabilities: null,
+  edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
   allowNetwork: false
 }));
 

package/dist/next/headers-shim.mjs

@@ -36,6 +36,8 @@ var state = globalSingleton("state", () => ({
   edgeDevices: [],
   edgePeripherals: [],
   edgeBindings: /* @__PURE__ */ new Map(),
+  edgeCapabilities: null,
+  edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
   allowNetwork: false
 }));
 

package/dist/setup.js

@@ -57,6 +57,8 @@ var state = globalSingleton("state", () => ({
   edgeDevices: [],
   edgePeripherals: [],
   edgeBindings: /* @__PURE__ */ new Map(),
+  edgeCapabilities: null,
+  edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
   allowNetwork: false
 }));
 function requireDb() {
@@ -1473,6 +1475,44 @@ function buildBinding(alias, peripheralId) {
     updatedAt: now2()
   };
 }
+var DEFAULT_CAPABILITIES = {
+  paperWidth: "80mm",
+  columns: 48,
+  dotsPerLine: 576,
+  renderMode: "text",
+  textEncoding: "utf8",
+  unicodeText: false,
+  thaiText: false,
+  bold: true,
+  textSizes: ["small", "normal", "large"],
+  barcodeFormats: ["qr"],
+  rasterImages: true,
+  cut: true,
+  cashDrawer: false
+};
+function handleCapabilities(request) {
+  const url = new URL(request.url);
+  const alias = url.searchParams.get("alias");
+  const deviceId = url.searchParams.get("deviceId");
+  let peripheralId = url.searchParams.get("peripheralId");
+  if (alias) {
+    const binding = state.edgeBindings.get(alias);
+    if (!binding) return bindingNotFound(alias);
+    peripheralId = binding.peripheral?.id ?? null;
+  }
+  if (peripheralId) {
+    const peripheral = findPeripheral(peripheralId);
+    if (!peripheral) {
+      return edgeFailure("Peripheral not found or its device is not granted to this project", 404);
+    }
+    const seeded = state.edgePeripheralCapabilities.get(peripheralId);
+    return success({ capabilities: seeded ?? state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+  }
+  if (deviceId && !state.edgeDevices.some((d) => d.id === deviceId)) {
+    return edgeFailure("Project does not have access to this device", 403);
+  }
+  return success({ capabilities: state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+}
 function handleListDevices() {
   return success({ devices: [...state.edgeDevices] });
 }
@@ -1576,6 +1616,9 @@ async function handleEdgeRequest(request, subPath) {
   if (subPath === "/print" && method === "POST") {
     return handlePrint(request);
   }
+  if (subPath === "/capabilities" && method === "GET") {
+    return handleCapabilities(request);
+  }
   if (subPath === "/devices" && method === "GET") {
     return handleListDevices();
   }

package/dist/setup.mjs

@@ -33,6 +33,8 @@ var state = globalSingleton("state", () => ({
   edgeDevices: [],
   edgePeripherals: [],
   edgeBindings: /* @__PURE__ */ new Map(),
+  edgeCapabilities: null,
+  edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
   allowNetwork: false
 }));
 function requireDb() {
@@ -1449,6 +1451,44 @@ function buildBinding(alias, peripheralId) {
     updatedAt: now2()
   };
 }
+var DEFAULT_CAPABILITIES = {
+  paperWidth: "80mm",
+  columns: 48,
+  dotsPerLine: 576,
+  renderMode: "text",
+  textEncoding: "utf8",
+  unicodeText: false,
+  thaiText: false,
+  bold: true,
+  textSizes: ["small", "normal", "large"],
+  barcodeFormats: ["qr"],
+  rasterImages: true,
+  cut: true,
+  cashDrawer: false
+};
+function handleCapabilities(request) {
+  const url = new URL(request.url);
+  const alias = url.searchParams.get("alias");
+  const deviceId = url.searchParams.get("deviceId");
+  let peripheralId = url.searchParams.get("peripheralId");
+  if (alias) {
+    const binding = state.edgeBindings.get(alias);
+    if (!binding) return bindingNotFound(alias);
+    peripheralId = binding.peripheral?.id ?? null;
+  }
+  if (peripheralId) {
+    const peripheral = findPeripheral(peripheralId);
+    if (!peripheral) {
+      return edgeFailure("Peripheral not found or its device is not granted to this project", 404);
+    }
+    const seeded = state.edgePeripheralCapabilities.get(peripheralId);
+    return success({ capabilities: seeded ?? state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+  }
+  if (deviceId && !state.edgeDevices.some((d) => d.id === deviceId)) {
+    return edgeFailure("Project does not have access to this device", 403);
+  }
+  return success({ capabilities: state.edgeCapabilities ?? DEFAULT_CAPABILITIES });
+}
 function handleListDevices() {
   return success({ devices: [...state.edgeDevices] });
 }
@@ -1552,6 +1592,9 @@ async function handleEdgeRequest(request, subPath) {
   if (subPath === "/print" && method === "POST") {
     return handlePrint(request);
   }
+  if (subPath === "/capabilities" && method === "GET") {
+    return handleCapabilities(request);
+  }
   if (subPath === "/devices" && method === "GET") {
     return handleListDevices();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Vitest test harness for Stardeck customer apps — in-process Postgres (PGlite) plus a control-plane simulator so the real Stardeck SDKs run unmodified in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -65,8 +65,8 @@
     "@electric-sql/pglite": "^0.3.0"
   },
   "peerDependencies": {
-    "@stardeck-customer-apps/integrations-sdk": ">=1.6.0",
     "@stardeck-customer-apps/edge-sdk": ">=1.4.0",
+    "@stardeck-customer-apps/integrations-sdk": ">=1.6.0",
     "@stardeck-customer-apps/payments-sdk": ">=0.1.0",
     "@stardeck-customer-apps/storage-sdk": ">=0.1.0",
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
@@ -93,8 +93,8 @@
     "@eslint/js": "^9.0.0",
     "@neondatabase/serverless": "^1.0.0",
     "@stardeck-customer-apps/data-store-sdk": "*",
-    "@stardeck-customer-apps/email-sdk": "*",
     "@stardeck-customer-apps/edge-sdk": "*",
+    "@stardeck-customer-apps/email-sdk": "*",
     "@stardeck-customer-apps/integrations-sdk": "*",
     "@stardeck-customer-apps/payments-sdk": "*",
     "@stardeck-customer-apps/storage-sdk": "*",
@@ -102,7 +102,7 @@
     "@types/node": "^24.10.1",
     "kysely": "^0.27.0",
     "kysely-neon": "^2.0.0",
-    "next": "^15.0.0",
+    "next": "^16.2.12",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",