@stardeck-customer-apps/testing 0.7.1 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stardeck Inc.
+
+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/SKILL.md

@@ -93,6 +93,47 @@ await app.payments.deliverStripeEvent(POST, {
   data: { object: { id: session.id } },
 });
 
+// Bolt+ terminal: create intent → approve → webhook (same deliverBeamEvent path)
+// Simulator intents are real-shaped (bolti_<n>, isVirtual: false) — not bolti_emu_*.
+// createBoltIntent validates like production: amount > 0, expiryDurationInSec 90–600,
+// paymentMethod enum, deploymentId UUID, boltConnectionId required.
+const connection = await payments.createBoltConnection({ pairingCode: "PAIR01" });
+const intent = await payments.createBoltIntent({
+  amount: 10000,
+  boltConnectionId: connection.beamConnectionId,
+  paymentMethod: "CARD",
+  expiryDurationInSec: 300,
+  referenceId: "order-1",
+});
+expect(app.payments.getBoltIntent(intent.id)?.status).toBe("PENDING");
+expect(app.payments.getBoltIntent(intent.id)?.isVirtual).toBe(false);
+
+const charge = app.payments.approveBoltIntent(intent.id);
+expect(app.payments.getBoltIntent(intent.id)?.status).toBe("PAID");
+
+const { POST: beamPost } = paymentsHandler({
+  provider: "beam",
+  onBeamWebhook: async (event) => {
+    if (event.type === "charge.succeeded") {
+      await fulfillOrder(String(event.payload.referenceId ?? ""));
+    }
+  },
+});
+await app.payments.deliverBeamEvent(beamPost, {
+  type: "charge.succeeded",
+  payload: {
+    id: charge.id,
+    sourceId: intent.id,
+    referenceId: "order-1",
+    amount: 10000,
+    currency: "THB",
+    status: "SUCCEEDED",
+  },
+});
+// declineBoltIntent / expireBoltIntent deliver NO webhook — Beam has no
+// charge-failure or expiry event for bolt payments.
+// EXPIRED is derived from expiresAt on read, never stored.
+
 // File upload
 const storage = new StorageClient();
 await storage.upload(new File(["hi"], "note.txt", { type: "text/plain" }));
@@ -169,7 +210,16 @@ externalId })` helper models a trusted platform/channel link, and
 - `app.payments` — checkouts created through payments-sdk:
   `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
   `.deliverStripeEvent(handler, event)`, `.deliverBeamEvent(handler, event)`,
-  `.count`, `.clear()`.
+  Bolt+ controls: `.approveBoltIntent(id)`, `.declineBoltIntent(id)`,
+  `.expireBoltIntent(id)`, `.listBoltIntents()`, `.getBoltIntent(id)`,
+  `.count`, `.clear()`. Approve marks PAID and records a charge; deliver the
+  `charge.succeeded` webhook yourself via `.deliverBeamEvent` (same signing
+  path as payment links). Decline and expire deliver no webhook. `EXPIRED` is
+  derived from `expiresAt` whenever an intent is read — it is never stored.
+  Simulator-created intents use real Beam id shapes (`bolti_<n>`) with
+  `isVirtual: false`; create/list validation matches the control plane
+  (expiry 90–600s, amount positive int, payment-method enum, deploymentId UUID,
+  list `limit` 1–100, status filter values).
 - `app.storage` — uploads through storage-sdk: `.uploads`, `.latest()`, `.count`, `.clear()`.
 - `app.messages` — outbound Slack/LINE/Facebook sends:
   `.all()`, `.latest()`, `.to(recipient)`, `.channel("line")`, `.count`, `.clear()`.
@@ -235,9 +285,11 @@ true })` remains source-compatible but the simulator (like the control plane)
 - For merge-correct reads, request aliases in batches and include every id in
   the returned canonical set. Page directory UIs through `search({ query,
 cursor, limit })`; `list()` intentionally keeps its previous array shape.
-- `PaymentsServerClient` (Stripe checkout + Beam payment links, product list) —
-  captured in `app.payments`; fulfill via `markPaid` (poll) or
-  `deliverStripeEvent` / `deliverBeamEvent` (webhook push).
+- `PaymentsServerClient` (Stripe checkout + Beam payment links + Bolt+
+  connections/intents/charges, product list) — captured in `app.payments`;
+  fulfill checkout via `markPaid` (poll) or `deliverStripeEvent` /
+  `deliverBeamEvent` (webhook push). Drive a terminal without hardware via
+  `approveBoltIntent` / `declineBoltIntent` / `expireBoltIntent`.
 - `StorageClient` (upload/list/get/patch/delete, presigned upload) — captured
   in `app.storage` against the simulated `STORAGE_URL` host.
 - `client.slack` / `client.line` / `client.facebook` send endpoints — captured

package/dist/index.d.mts

@@ -131,6 +131,53 @@ interface CapturedCheckout {
     metadata?: Record<string, string>;
     createdAt: Date;
 }
+/** Simulated Bolt+ connection as returned by the control-plane store API. */
+interface SimBoltConnection {
+    id: string;
+    projectId: string;
+    beamConnectionId: string;
+    displayName: string | null;
+    pairingCode: string;
+    status: string;
+    isSandbox: boolean;
+    environments: Array<"sandbox" | "preview" | "production">;
+    createdAt: string;
+    updatedAt: string;
+}
+type SimBoltIntentStoredStatus = "PENDING" | "PAID" | "FAILED" | "CANCELED";
+type SimBoltIntentStatus = SimBoltIntentStoredStatus | "EXPIRED";
+/**
+ * Stored Bolt+ intent. `EXPIRED` is never written — derive it from
+ * `expiresAt` on read, matching the real control plane.
+ */
+type SimBoltPaymentMethod = _stardeck_customer_apps_payments_sdk.BeamBoltPaymentMethod;
+/** Bolt intent as returned by list/get helpers (timestamps ISO; nullables are null). */
+interface SimBoltIntentRecord {
+    id: string;
+    beamIntentId: string;
+    boltConnectionId: string;
+    amount: number;
+    currency: string;
+    paymentMethodType: SimBoltPaymentMethod;
+    referenceId: string | null;
+    internalNote: string | null;
+    status: SimBoltIntentStatus;
+    isVirtual: boolean;
+    environment: "sandbox" | "preview" | "production";
+    expiresAt: string;
+    settledAt: string | null;
+    chargeId: string | null;
+    failureReason: string | null;
+    createdAt: string;
+}
+interface SimBoltCharge {
+    id: string;
+    status: "SUCCEEDED" | "FAILED" | "PENDING";
+    amount?: number;
+    currency?: string;
+    sourceId?: string;
+    createdAt?: string;
+}
 interface TestPayments {
     get checkouts(): CapturedCheckout[];
     latest(): CapturedCheckout | undefined;
@@ -153,6 +200,30 @@ interface TestPayments {
         path?: string;
         deploymentSecret?: string;
     }): Promise<Response>;
+    /**
+     * Mark a PENDING bolt intent PAID and record a SUCCEEDED charge. Does not
+     * deliver a webhook — call `deliverBeamEvent` with `charge.succeeded` (reuse
+     * the existing signing path) after approving, the same way `markPaid` pairs
+     * with `deliverStripeEvent` / `deliverBeamEvent`.
+     */
+    approveBoltIntent(intentId: string, options?: {
+        chargeId?: string;
+    }): SimBoltCharge;
+    /**
+     * Mark a PENDING bolt intent FAILED and record a FAILED charge.
+     * Delivers no webhook: Beam's catalog has no charge-failure event for bolt
+     * payments, and the real product notifies the app of nothing on decline.
+     */
+    declineBoltIntent(intentId: string, options?: {
+        failureReason?: string;
+    }): SimBoltCharge;
+    /**
+     * Backdate `expiresAt` so the intent derives as EXPIRED on the next read.
+     * Delivers no webhook: Beam does not notify apps when a bolt intent expires.
+     */
+    expireBoltIntent(intentId: string): void;
+    listBoltIntents(): SimBoltIntentRecord[];
+    getBoltIntent(intentId: string): SimBoltIntentRecord | undefined;
     clear(): void;
     get count(): number;
 }
@@ -241,6 +312,9 @@ type ReceiptBlock = {
     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";
@@ -457,4 +531,4 @@ declare const TEST_ENV_DEFAULTS: {
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.d.ts

@@ -131,6 +131,53 @@ interface CapturedCheckout {
     metadata?: Record<string, string>;
     createdAt: Date;
 }
+/** Simulated Bolt+ connection as returned by the control-plane store API. */
+interface SimBoltConnection {
+    id: string;
+    projectId: string;
+    beamConnectionId: string;
+    displayName: string | null;
+    pairingCode: string;
+    status: string;
+    isSandbox: boolean;
+    environments: Array<"sandbox" | "preview" | "production">;
+    createdAt: string;
+    updatedAt: string;
+}
+type SimBoltIntentStoredStatus = "PENDING" | "PAID" | "FAILED" | "CANCELED";
+type SimBoltIntentStatus = SimBoltIntentStoredStatus | "EXPIRED";
+/**
+ * Stored Bolt+ intent. `EXPIRED` is never written — derive it from
+ * `expiresAt` on read, matching the real control plane.
+ */
+type SimBoltPaymentMethod = _stardeck_customer_apps_payments_sdk.BeamBoltPaymentMethod;
+/** Bolt intent as returned by list/get helpers (timestamps ISO; nullables are null). */
+interface SimBoltIntentRecord {
+    id: string;
+    beamIntentId: string;
+    boltConnectionId: string;
+    amount: number;
+    currency: string;
+    paymentMethodType: SimBoltPaymentMethod;
+    referenceId: string | null;
+    internalNote: string | null;
+    status: SimBoltIntentStatus;
+    isVirtual: boolean;
+    environment: "sandbox" | "preview" | "production";
+    expiresAt: string;
+    settledAt: string | null;
+    chargeId: string | null;
+    failureReason: string | null;
+    createdAt: string;
+}
+interface SimBoltCharge {
+    id: string;
+    status: "SUCCEEDED" | "FAILED" | "PENDING";
+    amount?: number;
+    currency?: string;
+    sourceId?: string;
+    createdAt?: string;
+}
 interface TestPayments {
     get checkouts(): CapturedCheckout[];
     latest(): CapturedCheckout | undefined;
@@ -153,6 +200,30 @@ interface TestPayments {
         path?: string;
         deploymentSecret?: string;
     }): Promise<Response>;
+    /**
+     * Mark a PENDING bolt intent PAID and record a SUCCEEDED charge. Does not
+     * deliver a webhook — call `deliverBeamEvent` with `charge.succeeded` (reuse
+     * the existing signing path) after approving, the same way `markPaid` pairs
+     * with `deliverStripeEvent` / `deliverBeamEvent`.
+     */
+    approveBoltIntent(intentId: string, options?: {
+        chargeId?: string;
+    }): SimBoltCharge;
+    /**
+     * Mark a PENDING bolt intent FAILED and record a FAILED charge.
+     * Delivers no webhook: Beam's catalog has no charge-failure event for bolt
+     * payments, and the real product notifies the app of nothing on decline.
+     */
+    declineBoltIntent(intentId: string, options?: {
+        failureReason?: string;
+    }): SimBoltCharge;
+    /**
+     * Backdate `expiresAt` so the intent derives as EXPIRED on the next read.
+     * Delivers no webhook: Beam does not notify apps when a bolt intent expires.
+     */
+    expireBoltIntent(intentId: string): void;
+    listBoltIntents(): SimBoltIntentRecord[];
+    getBoltIntent(intentId: string): SimBoltIntentRecord | undefined;
     clear(): void;
     get count(): number;
 }
@@ -241,6 +312,9 @@ type ReceiptBlock = {
     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";
@@ -457,4 +531,4 @@ declare const TEST_ENV_DEFAULTS: {
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };