@stardeck-customer-apps/testing 0.3.1 → 0.5.0

package/SKILL.md

@@ -67,6 +67,51 @@ describeWorkflow("checkout", () => {
 });
 ```
 
+Payments, storage, and messaging:
+
+```ts
+import { paymentsHandler } from "@stardeck-customer-apps/payments-sdk";
+import { PaymentsServerClient } from "@stardeck-customer-apps/payments-sdk/server";
+import { StorageClient } from "@stardeck-customer-apps/storage-sdk/server";
+import { createIntegrationsClient } from "@stardeck-customer-apps/integrations-sdk";
+
+// Stripe checkout + webhook fulfillment
+const payments = new PaymentsServerClient({ /* reads CONTROL_PLANE_URL + DEPLOYMENT_SECRET from env */ });
+const session = await payments.createCheckout({ /* lineItems, successUrl, cancelUrl */ });
+const { POST } = paymentsHandler({
+  onStripeWebhook: async (event) => {
+    if (event.type === "checkout.session.completed") {
+      await app.query(`UPDATE orders SET status = 'paid' WHERE session_id = $1`, [
+        (event.data as { object: { id: string } }).object.id,
+      ]);
+    }
+  },
+});
+await app.payments.deliverStripeEvent(POST, {
+  type: "checkout.session.completed",
+  data: { object: { id: session.id } },
+});
+
+// File upload
+const storage = new StorageClient();
+await storage.upload(new File(["hi"], "note.txt", { type: "text/plain" }));
+expect(app.storage.latest()?.filename).toBe("note.txt");
+
+// LINE notification
+const integrations = createIntegrationsClient();
+await integrations.line.push("U123", { type: "text", text: "Your order shipped" });
+expect(app.messages.channel("line").to("U123")[0].body.text).toMatch(/shipped/i);
+
+// Receipt print + display
+import { createEdgeClient } from "@stardeck-customer-apps/edge-sdk/server";
+
+const edge = createEdgeClient();
+await edge.print({ receipt: { total: 42 }, alias: "station-1", openDrawer: true });
+expect(app.edge.latestPrint()?.receipt.total).toBe(42);
+await edge.showDisplay({ alias: "customer-screen", url: "https://app.example.com/kiosk" });
+expect(app.edge.latestDisplay()?.action).toBe("show");
+```
+
 ## API
 
 - `createTestApp(options)` — boots PGlite + the control-plane simulator and
@@ -88,6 +133,16 @@ describeWorkflow("checkout", () => {
 - `app.identities` — the platform-identity directory created through
   integrations-sdk `client.identities`: `.get(id)`, `.links(id)`, `.all()`,
   `.count`, `.clear()`.
+- `app.payments` — checkouts created through payments-sdk:
+  `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
+  `.deliverStripeEvent(handler, event)`, `.deliverBeamEvent(handler, event)`,
+  `.count`, `.clear()`.
+- `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()`.
+- `app.edge` — edge print/display/bindings from edge-sdk: `.prints`, `.displays`,
+  `.testPrints`, `.latestPrint()`, `.latestDisplay()`, `.bindings`,
+  `.seedDevices()`, `.seedPeripherals()`, `.seedBindings()`, `.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
@@ -111,6 +166,16 @@ describeWorkflow("checkout", () => {
   persons, attach channel links) — served offline by the simulated directory;
   `update` replaces the `profile` object (not a merge), like the control plane.
   Inspect via `app.identities`. Merge/archive are dashboard-only — not simulated.
+- `PaymentsServerClient` (Stripe checkout + Beam payment links, product list) —
+  captured in `app.payments`; fulfill via `markPaid` (poll) or
+  `deliverStripeEvent` / `deliverBeamEvent` (webhook push).
+- `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
+  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()`.
 - `next/headers` (`headers()`/`cookies()`) inside handlers under `callRoute`.
 
 ## Rules

package/dist/index.d.mts

@@ -1,6 +1,27 @@
+import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
+import * as next_server from 'next/server';
 import { PGlite } from '@electric-sql/pglite';
-import { ModuleSchemaOp, ModuleDataPort, IdentityClient } from '@stardeck-customer-apps/core';
 
+type RouteHandler<Req extends Request = Request, P = Record<string, string | string[]>> = (request: Req, context: {
+    params: Promise<P>;
+}) => Promise<Response> | Response;
+interface CallRouteOptions {
+    /** Request path, e.g. "/api/orders". Defaults to "/api/test-route". */
+    path?: string;
+    method?: string;
+    /** JSON body. Implies POST unless `method` is set. */
+    body?: unknown;
+    searchParams?: Record<string, string>;
+    /** Next.js dynamic segment params, e.g. { id: "123" }. */
+    params?: Record<string, string | string[]>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    /** Override the active test user for this call only. */
+    user?: TestUser | null;
+}
+declare function callRoute<Req extends Request = Request, P = Record<string, string | string[]>>(handler: RouteHandler<Req, P>, options?: CallRouteOptions): Promise<Response>;
+
+type PaymentsWebhookHandler = RouteHandler<next_server.NextRequest, Record<string, string | string[] | undefined>>;
 /**
  * The user shape returned by project-auth's `getSession()`. Mirrors the
  * `UserSchema` in @stardeck-customer-apps/project-auth — keep in sync.
@@ -85,6 +106,184 @@ interface TestDirectory {
     clear(): void;
     get count(): number;
 }
+interface CapturedCheckout {
+    id: string;
+    url: string;
+    provider: "stripe" | "beam";
+    options: Record<string, unknown>;
+    mode?: "payment" | "subscription";
+    metadata?: Record<string, string>;
+    createdAt: Date;
+}
+interface TestPayments {
+    get checkouts(): CapturedCheckout[];
+    latest(): CapturedCheckout | undefined;
+    setProducts(products: _stardeck_customer_apps_payments_sdk.Product[]): void;
+    markPaid(id: string): void;
+    setSessionStatus(id: string, status: Partial<_stardeck_customer_apps_payments_sdk.CheckoutSessionStatus>): void;
+    setPaymentLinkStatus(id: string, status: _stardeck_customer_apps_payments_sdk.BeamPaymentLinkStatus): void;
+    deliverStripeEvent(handler: PaymentsWebhookHandler, event: {
+        type: string;
+        data: unknown;
+        accountId?: string;
+    }, options?: {
+        path?: string;
+        deploymentSecret?: string;
+    }): Promise<Response>;
+    deliverBeamEvent(handler: PaymentsWebhookHandler, event: {
+        type: string;
+        payload: Record<string, unknown>;
+    }, options?: {
+        path?: string;
+        deploymentSecret?: string;
+    }): Promise<Response>;
+    clear(): void;
+    get count(): number;
+}
+interface CapturedUpload {
+    id: string;
+    key: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    url: string;
+    uploadedAt: string;
+    isPublic: boolean;
+    metadata?: Record<string, string>;
+    method: string;
+    path: string;
+}
+interface TestStorage {
+    get uploads(): CapturedUpload[];
+    latest(): CapturedUpload | undefined;
+    clear(): void;
+    get count(): number;
+}
+interface CapturedMessage {
+    channel: "slack" | "line" | "facebook";
+    recipient: string;
+    body: {
+        text?: string;
+        blocks?: unknown[];
+        threadTs?: string;
+        messagingType?: string;
+        tag?: string;
+    };
+    connectionId?: string;
+    sentAt: Date;
+}
+interface TestMessages {
+    all(): CapturedMessage[];
+    latest(): CapturedMessage | undefined;
+    to(recipient: string): CapturedMessage[];
+    channel(kind: "slack" | "line" | "facebook"): {
+        all(): CapturedMessage[];
+        latest(): CapturedMessage | undefined;
+        to(recipient: string): CapturedMessage[];
+    };
+    clear(): void;
+    get count(): number;
+}
+interface ReceiptPayload {
+    header?: {
+        lines: string[];
+    };
+    items?: Array<{
+        name: string;
+        quantity: number;
+        unitPrice: number;
+        total: number;
+        note?: string;
+    }>;
+    subtotal?: number;
+    tax?: number;
+    discount?: number;
+    total?: number;
+    payments?: Array<{
+        method: string;
+        amount: number;
+    }>;
+    footer?: {
+        lines: string[];
+    };
+    barcode?: {
+        type: "qr" | "code128";
+        data: string;
+    };
+    rawEscPos?: string;
+}
+interface DeviceInfo {
+    id: string;
+    displayName: string;
+    status: "pairing_pending" | "online" | "offline" | "decommissioned";
+    isDefault: boolean;
+    lastHeartbeatAt: string | null;
+}
+interface PeripheralInfo {
+    id: string;
+    displayName: string | null;
+    driver: string | null;
+    transport: "usb_lp" | "serial" | "tcp" | "usb_raw" | "display";
+    connected: boolean;
+    lastSeenAt: string | null;
+    device: {
+        id: string;
+        displayName: string;
+        status: DeviceInfo["status"];
+    };
+}
+type BindingState = "ok" | "peripheral_missing" | "grant_revoked";
+interface BindingInfo {
+    alias: string;
+    state: BindingState;
+    peripheral: {
+        id: string;
+        displayName: string | null;
+        driver: string | null;
+        connected: boolean;
+    } | null;
+    device: {
+        id: string;
+        displayName: string;
+        status: DeviceInfo["status"];
+    } | null;
+    updatedAt: string;
+}
+interface CapturedPrint {
+    jobId: string;
+    deploymentId: string;
+    alias?: string;
+    deviceId?: string;
+    peripheralId?: string;
+    receipt: ReceiptPayload;
+    openDrawer: boolean;
+    logo?: boolean;
+    copies: number;
+}
+interface CapturedDisplay {
+    action: "show" | "clear";
+    alias?: string;
+    peripheralId?: string;
+    url?: string;
+}
+interface CapturedTestPrint {
+    alias?: string;
+    deviceId?: string;
+    peripheralId?: string;
+}
+interface TestEdge {
+    get prints(): CapturedPrint[];
+    get displays(): CapturedDisplay[];
+    get testPrints(): CapturedTestPrint[];
+    latestPrint(): CapturedPrint | undefined;
+    latestDisplay(): CapturedDisplay | undefined;
+    get bindings(): BindingInfo[];
+    seedDevices(devices: DeviceInfo[]): void;
+    seedPeripherals(peripherals: PeripheralInfo[]): void;
+    seedBindings(bindings: BindingInfo[]): void;
+    clear(): void;
+    get count(): number;
+}
 interface TestAppOptions {
     /**
      * Path to the schema.sql snapshot generated by
@@ -114,6 +313,14 @@ interface TestApp {
     inbox: TestInbox;
     /** Inspect the simulated platform-identity directory (`client.identities`). */
     identities: TestDirectory;
+    /** Captured checkouts and webhook delivery helpers for payments-sdk. */
+    payments: TestPayments;
+    /** Captured file uploads from storage-sdk. */
+    storage: TestStorage;
+    /** Captured outbound messages from integrations-sdk messaging channels. */
+    messages: TestMessages;
+    /** Captured edge print/display ops and peripheral bindings from edge-sdk. */
+    edge: TestEdge;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**
@@ -141,71 +348,6 @@ interface TestApp {
  */
 declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
 
-/** The minimal slice of a module definition the harness needs to stand it up. */
-interface MountableModule {
-    schema: ModuleSchemaOp[];
-}
-interface ModuleSeedDeps {
-    /** Raw-SQL data port over the harness PGlite — what the module engine reads/writes through. */
-    data: ModuleDataPort;
-    /** Identity client backed by the simulated platform identity directory. */
-    identities: IdentityClient;
-}
-interface CreateModuleAppOptions {
-    /** Modules whose install schema is rendered to DDL and applied to the test DB. */
-    modules: MountableModule[];
-    /**
-     * Seed run once after the schema is applied, and again on every `reset()`.
-     * Receives the same data port + identity client the module engine uses, so a
-     * module's own `seed*` function drops straight in.
-     */
-    seed?: (deps: ModuleSeedDeps) => Promise<void>;
-    /** Allow real outbound network (default false). */
-    allowNetwork?: boolean;
-}
-interface ModuleApp extends ModuleSeedDeps {
-    /** The underlying harness app (db, identities inspector, callRoute, asUser, …). */
-    app: TestApp;
-    /** Reset to a clean slate: drop + re-apply the module schema, clear the sim, re-run the seed. */
-    reset(): Promise<void>;
-    /** Tear down (restore global fetch, close the db). */
-    close(): Promise<void>;
-}
-/**
- * Stand a capability module up on the in-process platform simulator — the **L2**
- * harness. It renders the module's install schema to real DDL (the SAME renderer
- * the control plane uses, drift-tested in apps/web), applies it to PGlite, wires a
- * raw-SQL data port over it, and a real `integrations-sdk` identity client talking
- * to the simulated identity directory (so scoping + governance behave as in prod).
- *
- * That's a near-end-to-end test of a module's runtime — schema + data port +
- * identity integration + engine — minus the HTTP/RSC shell (those belong to a
- * real-deploy smoke). The same seams back the local dev playground.
- *
- * Adding a module costs one co-located test file calling this with its own
- * definition + seed; there is no per-module harness to maintain.
- */
-declare function createModuleApp(options: CreateModuleAppOptions): Promise<ModuleApp>;
-
-type RouteHandler<Req extends Request, P> = (request: Req, context: {
-    params: Promise<P>;
-}) => Promise<Response> | Response;
-interface CallRouteOptions {
-    /** Request path, e.g. "/api/orders". Defaults to "/api/test-route". */
-    path?: string;
-    method?: string;
-    /** JSON body. Implies POST unless `method` is set. */
-    body?: unknown;
-    searchParams?: Record<string, string>;
-    /** Next.js dynamic segment params, e.g. { id: "123" }. */
-    params?: Record<string, string | string[]>;
-    headers?: Record<string, string>;
-    cookies?: Record<string, string>;
-    /** Override the active test user for this call only. */
-    user?: TestUser | null;
-}
-declare function callRoute<Req extends Request = Request, P = Record<string, string | string[]>>(handler: RouteHandler<Req, P>, options?: CallRouteOptions): Promise<Response>;
-
 /**
  * Tags a describe block as covering a named critical workflow ("checkout",
  * "booking", "inventory"). The platform parses the `workflow:` prefix out of
@@ -219,6 +361,8 @@ declare function parseWorkflowName(describeTitle: string): string | null;
 
 declare const CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 declare const DATA_STORE_TEST_HOST = "db.stardeck.test";
+declare const STORAGE_TEST_URL = "https://storage.stardeck.test";
+declare const STORAGE_TEST_HOST = "storage.stardeck.test";
 declare const TEST_ENV_DEFAULTS: {
     readonly CONTROL_PLANE_URL: "https://control-plane.stardeck.test";
     readonly DEPLOYMENT_SECRET: "stardeck-test-deployment-secret";
@@ -226,8 +370,9 @@ declare const TEST_ENV_DEFAULTS: {
     readonly PROJECT_ID: "00000000-0000-4000-8000-00000000000b";
     readonly DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c";
     readonly DATA_STORE_URL: "postgresql://test:test@db.stardeck.test/main";
+    readonly STORAGE_URL: "https://storage.stardeck.test";
 };
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CreateModuleAppOptions, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type ModuleApp, type ModuleSeedDeps, type MountableModule, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createModuleApp, 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, 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 };