@stardeck-customer-apps/testing 0.26.0 → 0.28.0

package/SKILL.md

@@ -216,6 +216,23 @@ app.payments.failNext("stripe.getCheckoutSessionStatus", {
 // Beam payment links reject idempotencyKey ("idempotency_unsupported") and echo expiresAt.
 // The simulator does not model Stripe's 24 h key retention.
 
+// Stripe inline payments (payments-sdk >= 4.12.0): PaymentIntents, same routes and shapes as
+// the platform. Card → clientSecret + actionRequired "CLIENT_CONFIRM"; PromptPay (THB only) →
+// qr.imageUrlPng + "ENCODED_IMAGE". Events are built from the stored payment, so the webhook
+// carries the amount, currency and metadata (incl. stardeckReferenceId, projectId) the app sent.
+const pi = await payments.createStripePaymentIntent({
+  amount: 12000, currency: "thb", method: "promptpay",
+  referenceId: order.id, idempotencyKey: `attempt-${order.id}`, metadata: { orderId: order.id },
+});
+expect(pi.qr?.imageUrlPng).toBeTruthy();
+app.payments.markPaid(pi.id);                    // the shopper scanned and paid
+await app.payments.deliverStripeEvent(POST, { paymentIntentId: pi.id }); // payment_intent.succeeded
+// app.payments.failPayment(pi.id, "card_declined") → payment_intent.payment_failed (retryable)
+// app.payments.cancelPayment(pi.id)                 → payment_intent.canceled
+app.payments.setStripePaymentMethods(["card"]);  // merchant turned PromptPay off:
+await expect(payments.createStripePaymentIntent({ ...req, method: "promptpay" }))
+  .rejects.toMatchObject({ statusCode: 422, code: "method_not_allowed" });
+
 // File upload
 const storage = new StorageClient();
 await storage.upload(new File(["hi"], "note.txt", { type: "text/plain" }));
@@ -437,6 +454,19 @@ externalId })` helper models a trusted platform/channel link, and
   `.setSessionStatus(id, status)`, `.setPaymentLinkStatus(id, status)`,
   `.failNext(operation, failure)`,
   `.deliverStripeEvent(handler, event)`, `.deliverBeamEvent(handler, event)`,
+  Stripe inline payments: `.stripePaymentIntents`, `.getStripePaymentIntent(id)`,
+  `.markPaid(piId)` (succeeds the PaymentIntent), `.failPayment(piId, code = "card_declined")`
+  (back to `requires_payment_method` with `lastPaymentError`), `.cancelPayment(piId)`,
+  `.deliverStripeEvent(handler, { paymentIntentId })` (sends `payment_intent.succeeded`,
+  `.payment_failed` or `.canceled` for the payment's current state, built from the stored
+  payment), `.setStripePaymentMethods(methods)` (the merchant's allowed methods, default
+  `["card", "promptpay"]`; readiness lists only these and create refuses others with 422
+  `method_not_allowed`), `.setStripeChargesEnabled(false)` (readiness not ready, create → 503
+  `account_not_ready`). Validation matches the platform (400 `invalid_request`, PromptPay
+  non-THB → 422 `currency_not_supported`, idempotent create, 409 `idempotency_conflict`, 409
+  `already_succeeded` on cancel after payment), and another project's payment id → 404
+  `not_found`. The app's `POST /api/payments/payment-intents` route refuses card (403
+  `CARD_CHARGE_SERVER_ONLY`); create card payments from server code.
   Bolt+ controls: `.approveBoltIntent(id)`, `.declineBoltIntent(id)`,
   `.expireBoltIntent(id)`, `.listBoltIntents()`, `.getBoltIntent(id)`,
   `.count`, `.clear()`. Approve marks PAID and records a charge; deliver the
@@ -541,7 +571,7 @@ 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 + Beam direct
+- `PaymentsServerClient` (Stripe checkout + Stripe inline payments + Beam payment links + Beam direct
   charges and card tokenization + 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
@@ -556,6 +586,8 @@ cursor, limit })`; `list()` intentionally keeps its previous array shape.
   one-shot HTTP or network failures during Stripe checkout creation/status polling
   and Beam payment-link creation/status polling. The operation names are
   `stripe.createCheckout`, `stripe.getCheckoutSessionStatus`,
+  `stripe.createPaymentIntent`, `stripe.getPaymentIntent`, `stripe.findPaymentIntents`,
+  `stripe.cancelPaymentIntent`, `stripe.getElementsConfig`, `stripe.getReadiness`,
   `beam.createPaymentLink`, `beam.getPaymentLinkStatus`, `beam.createDirectCharge`,
   and `beam.getCharge`. HTTP failures support
   statuses 400, 402, 409, 429, 500, and 503 plus optional `code`, `details`, and
@@ -592,6 +624,24 @@ cursor, limit })`; `list()` intentionally keeps its previous array shape.
   `expect(app.schedules.earliestWake("booking-janitor")!.getTime()).toBeLessThanOrEqual(dueAt.getTime())`.
   `app.schedules.wakesFor(key)` lists them; `reset()` clears them. Run the job's handler
   yourself to test what it does and the `nextRun()` it returns.
+- `getControl` / `getControls` / `setControl` from `@stardeck-customer-apps/controls/server` — the
+  sync (`POST /api/deployments/:id/controls`) and write (`PUT .../controls/:key`) routes are
+  simulated, signature-checked like the others, and served from `app.controls`. Defaults are
+  permissive so existing tests keep passing: `flag.paymentsSetupStep: false`,
+  `plan.locations: { included: 3, max: null, extraMonthly: { amount: 990, currency: "THB" } }`,
+  `plan.multiEntity: true`, `payments.provider: "beam"`, `payments.methods: { card: true, promptPay: true }`.
+  Seed with `createTestApp({ controls: { "plan.multiEntity": false } })`. Then
+  `app.controls.set(key, value)` (the next `getControl` in the same process sees it: the
+  controls cache is dropped on every change and on `reset()`),
+  `app.controls.setUnavailable(key)` (that key reads `{ ok: false }`, like a platform outage),
+  `app.controls.lastUsage()` (the usage the app reported on its latest sync, for example
+  `{ locations: 4 }`), `app.controls.writes()` (each `setControl` the app made:
+  `{ key, value, userToken }`) and `app.controls.refuseNextWrite({ code, message, connectUrl? })`
+  (the next write fails once with that error, for example `PROVIDER_NOT_READY` with a connect
+  link). A write needs the person's session token in `X-Stardeck-User-Token`; without it the
+  simulator answers 401 `UNAUTHENTICATED`. Only `payments.provider` and `payments.methods` are
+  writable (anything else is 400 `NOT_WRITABLE`), and an invalid value is 400 `INVALID_VALUE`.
+  `app.controls.clear()` returns to the seeded values. Test the `ok: false` path of every gate.
 
 ### Receipt layout and printer capabilities
 

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
 import * as next_server from 'next/server';
+import { ControlKey, ControlValue, ControlsUsage, ControlWriteErrorCode } from '@stardeck-customer-apps/controls';
 import { PGlite } from '@electric-sql/pglite';
 import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.mjs';
 export { S as STARDECK_DATA_STORES_ENV, a as TestDataStoreManifestEntry, b as buildTestDataStoreManifest } from './data-store-manifest-Zwgcv0DJ.mjs';
@@ -216,10 +217,10 @@ interface CapturedCheckout {
     metadata?: Record<string, string>;
     createdAt: Date;
 }
-type PaymentSimulatorOperation = "stripe.createCheckout" | "stripe.getCheckoutSessionStatus" | "beam.createPaymentLink" | "beam.getPaymentLinkStatus" | "beam.createDirectCharge" | "beam.getCharge";
+type PaymentSimulatorOperation = "stripe.createCheckout" | "stripe.getCheckoutSessionStatus" | "beam.createPaymentLink" | "beam.getPaymentLinkStatus" | "beam.createDirectCharge" | "beam.getCharge" | "stripe.createPaymentIntent" | "stripe.getPaymentIntent" | "stripe.findPaymentIntents" | "stripe.cancelPaymentIntent" | "stripe.getElementsConfig" | "stripe.getReadiness";
 type PaymentSimulatorFailure = {
     kind?: "http";
-    status: 400 | 402 | 409 | 429 | 500 | 503;
+    status: 400 | 402 | 404 | 409 | 422 | 429 | 500 | 502 | 503;
     message: string;
     code?: string;
     details?: unknown;
@@ -295,19 +296,98 @@ interface SimDirectCharge {
     idempotencyKey: string | null;
     createdAt: string;
 }
+/** Inline Stripe payment methods (mirrors the payments SDK's `StripePaymentMethod`). */
+type SimStripePaymentMethod = "card" | "promptpay";
+/** A Stripe PaymentIntent as the simulator holds it. */
+interface SimStripePaymentIntent {
+    id: string;
+    /** The project whose signed request created it; other projects get 404. */
+    projectId: string;
+    /** The account selector from the request path (`acct_…`, "default", "playground"). */
+    account: string;
+    /** The connected account it lives on; null on the playground. */
+    connectedAccountId: string | null;
+    playground: boolean;
+    status: "requires_payment_method" | "requires_confirmation" | "requires_action" | "processing" | "requires_capture" | "canceled" | "succeeded";
+    amount: number;
+    /** Lowercase. */
+    currency: string;
+    method: SimStripePaymentMethod;
+    referenceId: string;
+    /** The app's metadata, with Stardeck's reserved keys removed. */
+    appMetadata: Record<string, string>;
+    /** What Stripe holds: app metadata plus `projectId` and `stardeckReferenceId`. */
+    metadata: Record<string, string>;
+    description: string | null;
+    receiptEmail: string | null;
+    returnUrl: string | null;
+    clientSecret: string;
+    qr: {
+        imageUrlPng: string;
+        imageUrlSvg: string | null;
+        data: string | null;
+        hostedInstructionsUrl: string | null;
+        expiresAt: number | null;
+    } | null;
+    latestChargeId: string | null;
+    amountRefunded: number;
+    lastPaymentError: {
+        code: string | null;
+        declineCode: string | null;
+        message: string | null;
+    } | null;
+    /** Unix seconds. */
+    created: number;
+}
 interface TestPayments {
     get checkouts(): CapturedCheckout[];
     latest(): CapturedCheckout | undefined;
     setProducts(products: _stardeck_customer_apps_payments_sdk.Product[]): void;
     /** Fail the next matching SDK request once, then resume normal simulator behavior. */
     failNext(operation: PaymentSimulatorOperation, failure: PaymentSimulatorFailure): void;
+    /**
+     * The customer paid. Takes a Stripe Checkout session id, a Beam payment link
+     * id, or a Stripe PaymentIntent id (`pi_sim_…`). For a PaymentIntent, follow
+     * with `deliverStripeEvent(handler, { paymentIntentId })` to send the
+     * `payment_intent.succeeded` webhook.
+     */
     markPaid(id: string): void;
+    /**
+     * A Stripe PaymentIntent's payment attempt failed with `code` (default
+     * "card_declined"). It goes back to `requires_payment_method` with
+     * `lastPaymentError` set; deliver `payment_intent.payment_failed` with
+     * `deliverStripeEvent(handler, { paymentIntentId })`.
+     */
+    failPayment(paymentIntentId: string, code?: string): void;
+    /**
+     * The Stripe PaymentIntent was canceled outside the app (expired QR, merchant
+     * dashboard). Deliver `payment_intent.canceled` with `deliverStripeEvent`.
+     */
+    cancelPayment(paymentIntentId: string): void;
+    /** Every Stripe PaymentIntent created so far, oldest first, as stored. */
+    get stripePaymentIntents(): SimStripePaymentIntent[];
+    getStripePaymentIntent(paymentIntentId: string): SimStripePaymentIntent | undefined;
+    /**
+     * The inline Stripe methods the merchant allows (default `["card", "promptpay"]`).
+     * Create refuses others with 422 `method_not_allowed`; readiness lists only these.
+     */
+    setStripePaymentMethods(methods: SimStripePaymentMethod[]): void;
+    /** Turn Stripe charges off (readiness not ready; create → 503 `account_not_ready`). On by default. */
+    setStripeChargesEnabled(enabled: boolean): void;
     setSessionStatus(id: string, status: Partial<_stardeck_customer_apps_payments_sdk.CheckoutSessionStatus>): void;
     setPaymentLinkStatus(id: string, status: _stardeck_customer_apps_payments_sdk.BeamPaymentLinkStatus): void;
+    /**
+     * Deliver a Stripe webhook to the app's payments route, signed like the
+     * platform. Pass `{ paymentIntentId }` to send the `payment_intent.*` event
+     * for that PaymentIntent's current state, built from the stored intent
+     * (amount, currency, metadata incl. `stardeckReferenceId` and `projectId`).
+     */
     deliverStripeEvent(handler: PaymentsWebhookHandler, event: {
         type: string;
         data: unknown;
         accountId?: string;
+    } | {
+        paymentIntentId: string;
     }, options?: {
         path?: string;
         deploymentSecret?: string;
@@ -666,7 +746,40 @@ interface TestSchedules {
     earliestWake(scheduleKey: string): Date | undefined;
     clear(): void;
 }
+interface CapturedControlWrite {
+    key: ControlKey;
+    value: unknown;
+    /** The person's session token the app sent in `X-Stardeck-User-Token`. */
+    userToken: string;
+}
+interface ControlRefusal {
+    code: ControlWriteErrorCode;
+    message: string;
+    connectUrl?: string;
+}
+/** The simulated app-controls sync and write routes (`@stardeck-customer-apps/controls`). */
+interface TestControls {
+    /**
+     * Set a control's value (the app sees it on its next `getControl`, with no
+     * stale cache). Also makes a key that was forced unavailable available again.
+     */
+    set<K extends ControlKey>(key: K, value: ControlValue<K>): void;
+    /** Make the sync report this control as `{ ok: false }`, like a platform outage for one key. */
+    setUnavailable(key: ControlKey): void;
+    /** The usage the app reported on its latest sync, or null if it reported none. */
+    lastUsage(): ControlsUsage | null;
+    /** Writes the app made through `setControl`, oldest first. */
+    writes(): CapturedControlWrite[];
+    /** The next write is refused with this error, then writes succeed again. */
+    refuseNextWrite(refusal: ControlRefusal): void;
+    /** Back to the values the test app was created with; clears writes, usage and refusals. */
+    clear(): void;
+}
 interface TestAppOptions {
+    /** Control values the simulated platform serves; unlisted keys keep the permissive defaults. */
+    controls?: Partial<{
+        [K in ControlKey]: ControlValue<K>;
+    }>;
     /**
      * The LIFF ID the platform forwards to the app for a LINE MINI App shop. It is
      * what `GET /api/auth/me` returns as `liffId` and what makes `useLiff()` start
@@ -720,6 +833,8 @@ interface TestApp {
     starlens: TestStarlens;
     /** Wakes the app asked of its adaptive schedules (`wakeSchedule`). */
     schedules: TestSchedules;
+    /** Platform-owned app controls: flags, plan limits, payment provider and methods. */
+    controls: TestControls;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
 import * as next_server from 'next/server';
+import { ControlKey, ControlValue, ControlsUsage, ControlWriteErrorCode } from '@stardeck-customer-apps/controls';
 import { PGlite } from '@electric-sql/pglite';
 import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.js';
 export { S as STARDECK_DATA_STORES_ENV, a as TestDataStoreManifestEntry, b as buildTestDataStoreManifest } from './data-store-manifest-Zwgcv0DJ.js';
@@ -216,10 +217,10 @@ interface CapturedCheckout {
     metadata?: Record<string, string>;
     createdAt: Date;
 }
-type PaymentSimulatorOperation = "stripe.createCheckout" | "stripe.getCheckoutSessionStatus" | "beam.createPaymentLink" | "beam.getPaymentLinkStatus" | "beam.createDirectCharge" | "beam.getCharge";
+type PaymentSimulatorOperation = "stripe.createCheckout" | "stripe.getCheckoutSessionStatus" | "beam.createPaymentLink" | "beam.getPaymentLinkStatus" | "beam.createDirectCharge" | "beam.getCharge" | "stripe.createPaymentIntent" | "stripe.getPaymentIntent" | "stripe.findPaymentIntents" | "stripe.cancelPaymentIntent" | "stripe.getElementsConfig" | "stripe.getReadiness";
 type PaymentSimulatorFailure = {
     kind?: "http";
-    status: 400 | 402 | 409 | 429 | 500 | 503;
+    status: 400 | 402 | 404 | 409 | 422 | 429 | 500 | 502 | 503;
     message: string;
     code?: string;
     details?: unknown;
@@ -295,19 +296,98 @@ interface SimDirectCharge {
     idempotencyKey: string | null;
     createdAt: string;
 }
+/** Inline Stripe payment methods (mirrors the payments SDK's `StripePaymentMethod`). */
+type SimStripePaymentMethod = "card" | "promptpay";
+/** A Stripe PaymentIntent as the simulator holds it. */
+interface SimStripePaymentIntent {
+    id: string;
+    /** The project whose signed request created it; other projects get 404. */
+    projectId: string;
+    /** The account selector from the request path (`acct_…`, "default", "playground"). */
+    account: string;
+    /** The connected account it lives on; null on the playground. */
+    connectedAccountId: string | null;
+    playground: boolean;
+    status: "requires_payment_method" | "requires_confirmation" | "requires_action" | "processing" | "requires_capture" | "canceled" | "succeeded";
+    amount: number;
+    /** Lowercase. */
+    currency: string;
+    method: SimStripePaymentMethod;
+    referenceId: string;
+    /** The app's metadata, with Stardeck's reserved keys removed. */
+    appMetadata: Record<string, string>;
+    /** What Stripe holds: app metadata plus `projectId` and `stardeckReferenceId`. */
+    metadata: Record<string, string>;
+    description: string | null;
+    receiptEmail: string | null;
+    returnUrl: string | null;
+    clientSecret: string;
+    qr: {
+        imageUrlPng: string;
+        imageUrlSvg: string | null;
+        data: string | null;
+        hostedInstructionsUrl: string | null;
+        expiresAt: number | null;
+    } | null;
+    latestChargeId: string | null;
+    amountRefunded: number;
+    lastPaymentError: {
+        code: string | null;
+        declineCode: string | null;
+        message: string | null;
+    } | null;
+    /** Unix seconds. */
+    created: number;
+}
 interface TestPayments {
     get checkouts(): CapturedCheckout[];
     latest(): CapturedCheckout | undefined;
     setProducts(products: _stardeck_customer_apps_payments_sdk.Product[]): void;
     /** Fail the next matching SDK request once, then resume normal simulator behavior. */
     failNext(operation: PaymentSimulatorOperation, failure: PaymentSimulatorFailure): void;
+    /**
+     * The customer paid. Takes a Stripe Checkout session id, a Beam payment link
+     * id, or a Stripe PaymentIntent id (`pi_sim_…`). For a PaymentIntent, follow
+     * with `deliverStripeEvent(handler, { paymentIntentId })` to send the
+     * `payment_intent.succeeded` webhook.
+     */
     markPaid(id: string): void;
+    /**
+     * A Stripe PaymentIntent's payment attempt failed with `code` (default
+     * "card_declined"). It goes back to `requires_payment_method` with
+     * `lastPaymentError` set; deliver `payment_intent.payment_failed` with
+     * `deliverStripeEvent(handler, { paymentIntentId })`.
+     */
+    failPayment(paymentIntentId: string, code?: string): void;
+    /**
+     * The Stripe PaymentIntent was canceled outside the app (expired QR, merchant
+     * dashboard). Deliver `payment_intent.canceled` with `deliverStripeEvent`.
+     */
+    cancelPayment(paymentIntentId: string): void;
+    /** Every Stripe PaymentIntent created so far, oldest first, as stored. */
+    get stripePaymentIntents(): SimStripePaymentIntent[];
+    getStripePaymentIntent(paymentIntentId: string): SimStripePaymentIntent | undefined;
+    /**
+     * The inline Stripe methods the merchant allows (default `["card", "promptpay"]`).
+     * Create refuses others with 422 `method_not_allowed`; readiness lists only these.
+     */
+    setStripePaymentMethods(methods: SimStripePaymentMethod[]): void;
+    /** Turn Stripe charges off (readiness not ready; create → 503 `account_not_ready`). On by default. */
+    setStripeChargesEnabled(enabled: boolean): void;
     setSessionStatus(id: string, status: Partial<_stardeck_customer_apps_payments_sdk.CheckoutSessionStatus>): void;
     setPaymentLinkStatus(id: string, status: _stardeck_customer_apps_payments_sdk.BeamPaymentLinkStatus): void;
+    /**
+     * Deliver a Stripe webhook to the app's payments route, signed like the
+     * platform. Pass `{ paymentIntentId }` to send the `payment_intent.*` event
+     * for that PaymentIntent's current state, built from the stored intent
+     * (amount, currency, metadata incl. `stardeckReferenceId` and `projectId`).
+     */
     deliverStripeEvent(handler: PaymentsWebhookHandler, event: {
         type: string;
         data: unknown;
         accountId?: string;
+    } | {
+        paymentIntentId: string;
     }, options?: {
         path?: string;
         deploymentSecret?: string;
@@ -666,7 +746,40 @@ interface TestSchedules {
     earliestWake(scheduleKey: string): Date | undefined;
     clear(): void;
 }
+interface CapturedControlWrite {
+    key: ControlKey;
+    value: unknown;
+    /** The person's session token the app sent in `X-Stardeck-User-Token`. */
+    userToken: string;
+}
+interface ControlRefusal {
+    code: ControlWriteErrorCode;
+    message: string;
+    connectUrl?: string;
+}
+/** The simulated app-controls sync and write routes (`@stardeck-customer-apps/controls`). */
+interface TestControls {
+    /**
+     * Set a control's value (the app sees it on its next `getControl`, with no
+     * stale cache). Also makes a key that was forced unavailable available again.
+     */
+    set<K extends ControlKey>(key: K, value: ControlValue<K>): void;
+    /** Make the sync report this control as `{ ok: false }`, like a platform outage for one key. */
+    setUnavailable(key: ControlKey): void;
+    /** The usage the app reported on its latest sync, or null if it reported none. */
+    lastUsage(): ControlsUsage | null;
+    /** Writes the app made through `setControl`, oldest first. */
+    writes(): CapturedControlWrite[];
+    /** The next write is refused with this error, then writes succeed again. */
+    refuseNextWrite(refusal: ControlRefusal): void;
+    /** Back to the values the test app was created with; clears writes, usage and refusals. */
+    clear(): void;
+}
 interface TestAppOptions {
+    /** Control values the simulated platform serves; unlisted keys keep the permissive defaults. */
+    controls?: Partial<{
+        [K in ControlKey]: ControlValue<K>;
+    }>;
     /**
      * The LIFF ID the platform forwards to the app for a LINE MINI App shop. It is
      * what `GET /api/auth/me` returns as `liffId` and what makes `useLiff()` start
@@ -720,6 +833,8 @@ interface TestApp {
     starlens: TestStarlens;
     /** Wakes the app asked of its adaptive schedules (`wakeSchedule`). */
     schedules: TestSchedules;
+    /** Platform-owned app controls: flags, plan limits, payment provider and methods. */
+    controls: TestControls;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**