@stardeck-customer-apps/testing 0.27.0 → 0.29.0

package/SKILL.md

@@ -233,6 +233,21 @@ app.payments.setStripePaymentMethods(["card"]);  // merchant turned PromptPay of
 await expect(payments.createStripePaymentIntent({ ...req, method: "promptpay" }))
   .rejects.toMatchObject({ statusCode: 422, code: "method_not_allowed" });
 
+// Provider refunds (payments-sdk >= 4.13.0): same routes, summaries and error codes as the
+// platform. A refund never pays out on its own; you move it, then deliver the event, then the
+// app re-reads the refund (as it must in production).
+const refund = await payments.refundStripePaymentIntent(pi.id, {
+  idempotencyKey: row.id, amount: 5000, refundRowId: row.id,
+}); // status "pending"; app.payments.getStripePaymentIntent(pi.id).amountRefunded === 5000
+app.payments.settleRefund(refund.id, "failed");  // or "succeeded" / "needs_customer"
+await app.payments.deliverStripeEvent(POST, { refundId: refund.id }); // refund.failed
+// amountRefunded drops back to 0 and the payment can be refunded again.
+// Staff refunded in Stripe's dashboard: already succeeded, no refundRowId. It returns the new
+// refund's id; deliver it with deliverStripeEvent(POST, { refundId: dashId }) the same way.
+const dashId = app.payments.dashboardRefund(pi.id, 3000);
+// Beam: refundBeamCharge(chargeId, { idempotencyKey, amount? }) -> PENDING; settleRefund(id,
+// "succeeded" | "failed"); deliverBeamEvent(POST, { refundId }) -> refund.succeeded / refund.failed.
+
 // File upload
 const storage = new StorageClient();
 await storage.upload(new File(["hi"], "note.txt", { type: "text/plain" }));
@@ -467,6 +482,31 @@ externalId })` helper models a trusted platform/channel link, and
   `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.
+  Provider refunds (payments-sdk >= 4.13.0): `refundStripePaymentIntent`, `getStripeRefund`,
+  `findStripeCheckoutSessionByPaymentIntent`, `refundBeamCharge` and `getBeamRefund` answer
+  like the platform (400 `invalid_request`; 404 `payment_not_owned` / `refund_not_found`; 409
+  `payment_not_refundable`, `refund_exceeds_remaining`, `refund_partial_not_allowed`,
+  `refund_in_progress`, `idempotency_conflict`; a repeated `idempotencyKey` returns the same
+  refund). Refunds start Stripe `pending` / Beam `PENDING` and never pay out by themselves:
+  `.settleRefund(refundId, "succeeded" | "failed" | "needs_customer", { failureReason? })`
+  moves one (`needs_customer` is Stripe PromptPay's `requires_action` with
+  `nextActionExpiresAt`, and throws on a card refund or on Beam; a succeeded Stripe refund can
+  still be settled `failed`, as a card refund can fail days later; Beam statuses are final).
+  `.dashboardRefund(paymentRef, amount?)` makes a refund the app never requested (a Stripe
+  PaymentIntent id or a Beam direct-charge id): already succeeded, no `refundRowId`; returns the new refund's id.
+  Neither delivers a webhook: follow with `.deliverStripeEvent(handler, { refundId })`
+  (`refund.created` for a new refund, `refund.updated` after a settle, `refund.failed` once
+  failed; pass `type` to force one, e.g. to test events arriving out of order) or
+  `.deliverBeamEvent(handler, { refundId })` (`refund.succeeded` / `refund.failed`; a PENDING
+  refund has no event). The event carries the refund's id, so handlers re-read it with
+  `getStripeRefund` / `getBeamRefund`. Failed refunds stop counting: the intent's
+  `amountRefunded` (succeeded + pending Stripe refunds) drops back and the amount can be
+  refunded again. Beam follows its rules: partial only on `CARD` / `CARD_TOKEN` charges, one
+  PENDING refund per charge. Inspect with `.stripeRefunds`, `.getStripeRefund(id)`,
+  `.beamRefunds`, `.getBeamRefund(id)`. A paid one-time Stripe Checkout session (`markPaid`)
+  gets a succeeded PaymentIntent: `getCheckoutSessionStatus` returns its `paymentIntentId`
+  (null before payment) and it can be refunded. Refund calls are server-only; the app's
+  payments route does not expose them.
   Bolt+ controls: `.approveBoltIntent(id)`, `.declineBoltIntent(id)`,
   `.expireBoltIntent(id)`, `.listBoltIntents()`, `.getBoltIntent(id)`,
   `.count`, `.clear()`. Approve marks PAID and records a charge; deliver the
@@ -572,7 +612,7 @@ true })` remains source-compatible but the simulator (like the control plane)
   the returned canonical set. Page directory UIs through `search({ query,
 cursor, limit })`; `list()` intentionally keeps its previous array shape.
 - `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`;
+  charges and card tokenization + Bolt+ connections/intents/charges, product list, provider refunds) — captured in `app.payments`;
   fulfill checkout via `markPaid` (poll) or `deliverStripeEvent` /
   `deliverBeamEvent` (webhook push). Drive a terminal without hardware via
   `approveBoltIntent` / `declineBoltIntent` / `expireBoltIntent`. Beam payment-link
@@ -588,8 +628,9 @@ cursor, limit })`; `list()` intentionally keeps its previous array shape.
   `stripe.createCheckout`, `stripe.getCheckoutSessionStatus`,
   `stripe.createPaymentIntent`, `stripe.getPaymentIntent`, `stripe.findPaymentIntents`,
   `stripe.cancelPaymentIntent`, `stripe.getElementsConfig`, `stripe.getReadiness`,
+  `stripe.refundPaymentIntent`, `stripe.getRefund`, `stripe.findCheckoutSessionByIntent`,
   `beam.createPaymentLink`, `beam.getPaymentLinkStatus`, `beam.createDirectCharge`,
-  and `beam.getCharge`. HTTP failures support
+  `beam.getCharge`, `beam.refundCharge`, and `beam.getRefund`. HTTP failures support
   statuses 400, 402, 409, 429, 500, and 503 plus optional `code`, `details`, and
   `retryAfterSeconds`; `{ kind: "network", message }` rejects fetch instead.
   `app.reset()` clears pending failures.
@@ -624,6 +665,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,7 +217,7 @@ interface CapturedCheckout {
     metadata?: Record<string, string>;
     createdAt: Date;
 }
-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 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" | "stripe.refundPaymentIntent" | "stripe.getRefund" | "stripe.findCheckoutSessionByIntent" | "beam.refundCharge" | "beam.getRefund";
 type PaymentSimulatorFailure = {
     kind?: "http";
     status: 400 | 402 | 404 | 409 | 422 | 429 | 500 | 502 | 503;
@@ -338,6 +339,46 @@ interface SimStripePaymentIntent {
     /** Unix seconds. */
     created: number;
 }
+/** A Stripe refund as the simulator holds it. */
+interface SimStripeRefund {
+    id: string;
+    paymentIntentId: string;
+    /** The project that owns the payment; other projects get 404. */
+    projectId: string;
+    amount: number;
+    /** Lowercase. */
+    currency: string;
+    status: _stardeck_customer_apps_payments_sdk.StripeRefundStatus;
+    failureReason: string | null;
+    pendingReason: string | null;
+    /** Unix seconds; set while a PromptPay refund waits for the customer's bank details. */
+    nextActionExpiresAt: number | null;
+    /** The app's local refund row id; null for a refund made in the Stripe dashboard. */
+    refundRowId: string | null;
+    /** The app's metadata, with Stardeck's reserved keys removed. */
+    appMetadata: Record<string, string>;
+    reason: string | null;
+    /** "app" when requested through the SDK, "dashboard" when made by `dashboardRefund`. */
+    origin: "app" | "dashboard";
+    /** How many times `settleRefund` has moved it; picks `refund.created` vs `refund.updated`. */
+    revision: number;
+    /** Unix seconds. */
+    created: number;
+}
+/** A Beam refund as the simulator holds it. */
+interface SimBeamRefund {
+    refundId: string;
+    chargeId: string;
+    amount: number;
+    /** As Beam returns it, e.g. "THB". */
+    currency: string;
+    status: _stardeck_customer_apps_payments_sdk.BeamRefundStatus;
+    failureCode: string | null;
+    reason: string | null;
+    origin: "app" | "dashboard";
+    /** ISO 8601. */
+    createdAt: string;
+}
 interface TestPayments {
     get checkouts(): CapturedCheckout[];
     latest(): CapturedCheckout | undefined;
@@ -387,17 +428,62 @@ interface TestPayments {
         accountId?: string;
     } | {
         paymentIntentId: string;
+    } | {
+        refundId: string;
+        type?: "refund.created" | "refund.updated" | "refund.failed";
     }, options?: {
         path?: string;
         deploymentSecret?: string;
     }): Promise<Response>;
+    /**
+     * Deliver a Beam webhook. Pass `{ refundId }` to send the `refund.succeeded`
+     * or `refund.failed` event for a settled Beam refund, built from the stored
+     * refund. A refund still PENDING has no event: call `settleRefund` first.
+     */
     deliverBeamEvent(handler: PaymentsWebhookHandler, event: {
         type: string;
         payload: Record<string, unknown>;
+    } | {
+        refundId: string;
     }, options?: {
         path?: string;
         deploymentSecret?: string;
     }): Promise<Response>;
+    /** Every Stripe refund so far, oldest first, as stored. */
+    get stripeRefunds(): SimStripeRefund[];
+    getStripeRefund(refundId: string): SimStripeRefund | undefined;
+    /** Every Beam refund so far, oldest first, as stored. */
+    get beamRefunds(): SimBeamRefund[];
+    getBeamRefund(refundId: string): SimBeamRefund | undefined;
+    /**
+     * Move a refund the app requested to its next state, as the provider would
+     * later. Refunds start `pending` (Stripe PromptPay: `requires_action`) and
+     * never pay out on their own.
+     *
+     * - `"succeeded"`: Stripe `succeeded` / Beam `SUCCEEDED`.
+     * - `"failed"`: Stripe `failed` (also from `succeeded`, like a card refund
+     *   that fails days later) / Beam `FAILED`. A failed refund stops counting
+     *   toward `amountRefunded` and toward what the payment can still refund.
+     * - `"needs_customer"`: Stripe PromptPay only (`requires_action`: the
+     *   customer must send bank details). Beam has no such state and throws.
+     *
+     * `failureReason` is Stripe's `failure_reason` or Beam's `failureCode`.
+     * Delivers no webhook: follow with `deliverStripeEvent(handler, { refundId })`
+     * or `deliverBeamEvent(handler, { refundId })`. Read the result back with
+     * `getStripeRefund` / `getBeamRefund` or the SDK.
+     */
+    settleRefund(refundId: string, outcome: "succeeded" | "failed" | "needs_customer", options?: {
+        failureReason?: string;
+    }): void;
+    /**
+     * A refund made in the provider's dashboard, which the app never requested:
+     * no `refundRowId`, already succeeded. `paymentRef` is a Stripe PaymentIntent
+     * id or a Beam charge id; omit `amount` to refund what remains. The provider's
+     * own rules apply (Beam: partial on CARD charges only). Delivers no webhook;
+     * follow with `deliverStripeEvent` / `deliverBeamEvent` and `{ refundId }`.
+     * Returns the new refund's id.
+     */
+    dashboardRefund(paymentRef: string, amount?: number): string;
     /**
      * Mark a PENDING bolt intent PAID and record a SUCCEEDED charge. Does not
      * deliver a webhook — call `deliverBeamEvent` with `charge.succeeded` (reuse
@@ -745,7 +831,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
@@ -799,6 +918,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,7 +217,7 @@ interface CapturedCheckout {
     metadata?: Record<string, string>;
     createdAt: Date;
 }
-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 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" | "stripe.refundPaymentIntent" | "stripe.getRefund" | "stripe.findCheckoutSessionByIntent" | "beam.refundCharge" | "beam.getRefund";
 type PaymentSimulatorFailure = {
     kind?: "http";
     status: 400 | 402 | 404 | 409 | 422 | 429 | 500 | 502 | 503;
@@ -338,6 +339,46 @@ interface SimStripePaymentIntent {
     /** Unix seconds. */
     created: number;
 }
+/** A Stripe refund as the simulator holds it. */
+interface SimStripeRefund {
+    id: string;
+    paymentIntentId: string;
+    /** The project that owns the payment; other projects get 404. */
+    projectId: string;
+    amount: number;
+    /** Lowercase. */
+    currency: string;
+    status: _stardeck_customer_apps_payments_sdk.StripeRefundStatus;
+    failureReason: string | null;
+    pendingReason: string | null;
+    /** Unix seconds; set while a PromptPay refund waits for the customer's bank details. */
+    nextActionExpiresAt: number | null;
+    /** The app's local refund row id; null for a refund made in the Stripe dashboard. */
+    refundRowId: string | null;
+    /** The app's metadata, with Stardeck's reserved keys removed. */
+    appMetadata: Record<string, string>;
+    reason: string | null;
+    /** "app" when requested through the SDK, "dashboard" when made by `dashboardRefund`. */
+    origin: "app" | "dashboard";
+    /** How many times `settleRefund` has moved it; picks `refund.created` vs `refund.updated`. */
+    revision: number;
+    /** Unix seconds. */
+    created: number;
+}
+/** A Beam refund as the simulator holds it. */
+interface SimBeamRefund {
+    refundId: string;
+    chargeId: string;
+    amount: number;
+    /** As Beam returns it, e.g. "THB". */
+    currency: string;
+    status: _stardeck_customer_apps_payments_sdk.BeamRefundStatus;
+    failureCode: string | null;
+    reason: string | null;
+    origin: "app" | "dashboard";
+    /** ISO 8601. */
+    createdAt: string;
+}
 interface TestPayments {
     get checkouts(): CapturedCheckout[];
     latest(): CapturedCheckout | undefined;
@@ -387,17 +428,62 @@ interface TestPayments {
         accountId?: string;
     } | {
         paymentIntentId: string;
+    } | {
+        refundId: string;
+        type?: "refund.created" | "refund.updated" | "refund.failed";
     }, options?: {
         path?: string;
         deploymentSecret?: string;
     }): Promise<Response>;
+    /**
+     * Deliver a Beam webhook. Pass `{ refundId }` to send the `refund.succeeded`
+     * or `refund.failed` event for a settled Beam refund, built from the stored
+     * refund. A refund still PENDING has no event: call `settleRefund` first.
+     */
     deliverBeamEvent(handler: PaymentsWebhookHandler, event: {
         type: string;
         payload: Record<string, unknown>;
+    } | {
+        refundId: string;
     }, options?: {
         path?: string;
         deploymentSecret?: string;
     }): Promise<Response>;
+    /** Every Stripe refund so far, oldest first, as stored. */
+    get stripeRefunds(): SimStripeRefund[];
+    getStripeRefund(refundId: string): SimStripeRefund | undefined;
+    /** Every Beam refund so far, oldest first, as stored. */
+    get beamRefunds(): SimBeamRefund[];
+    getBeamRefund(refundId: string): SimBeamRefund | undefined;
+    /**
+     * Move a refund the app requested to its next state, as the provider would
+     * later. Refunds start `pending` (Stripe PromptPay: `requires_action`) and
+     * never pay out on their own.
+     *
+     * - `"succeeded"`: Stripe `succeeded` / Beam `SUCCEEDED`.
+     * - `"failed"`: Stripe `failed` (also from `succeeded`, like a card refund
+     *   that fails days later) / Beam `FAILED`. A failed refund stops counting
+     *   toward `amountRefunded` and toward what the payment can still refund.
+     * - `"needs_customer"`: Stripe PromptPay only (`requires_action`: the
+     *   customer must send bank details). Beam has no such state and throws.
+     *
+     * `failureReason` is Stripe's `failure_reason` or Beam's `failureCode`.
+     * Delivers no webhook: follow with `deliverStripeEvent(handler, { refundId })`
+     * or `deliverBeamEvent(handler, { refundId })`. Read the result back with
+     * `getStripeRefund` / `getBeamRefund` or the SDK.
+     */
+    settleRefund(refundId: string, outcome: "succeeded" | "failed" | "needs_customer", options?: {
+        failureReason?: string;
+    }): void;
+    /**
+     * A refund made in the provider's dashboard, which the app never requested:
+     * no `refundRowId`, already succeeded. `paymentRef` is a Stripe PaymentIntent
+     * id or a Beam charge id; omit `amount` to refund what remains. The provider's
+     * own rules apply (Beam: partial on CARD charges only). Delivers no webhook;
+     * follow with `deliverStripeEvent` / `deliverBeamEvent` and `{ refundId }`.
+     * Returns the new refund's id.
+     */
+    dashboardRefund(paymentRef: string, amount?: number): string;
     /**
      * Mark a PENDING bolt intent PAID and record a SUCCEEDED charge. Does not
      * deliver a webhook — call `deliverBeamEvent` with `charge.succeeded` (reuse
@@ -745,7 +831,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
@@ -799,6 +918,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[]>;
     /**