@stardeck-customer-apps/testing 0.26.0 → 0.27.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

package/dist/index.d.mts

@@ -216,10 +216,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 +295,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;

package/dist/index.d.ts

@@ -216,10 +216,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 +295,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;