@stardeck-customer-apps/testing 0.28.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.

package/dist/index.d.mts

@@ -217,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;
@@ -339,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;
@@ -388,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

package/dist/index.d.ts

@@ -217,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;
@@ -339,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;
@@ -388,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