@stardeck-customer-apps/testing 0.22.0 → 0.24.0

package/SKILL.md

@@ -208,6 +208,14 @@ app.payments.failNext("stripe.getCheckoutSessionStatus", {
   message: "connection reset",
 });
 
+// Stripe createCheckout idempotency + expiry (payments-sdk >= 4.11.0) is simulated like the
+// platform: same idempotencyKey + same payload replays the same session (one captured
+// checkout); same key + different payload -> PaymentError "idempotency_conflict" (409); keys
+// are scoped per account; expiresAt (unix seconds) must be 30 min - 24 h out or
+// "expiry_out_of_range" (400); the default is 24 h and session.expiresAt is returned.
+// Beam payment links reject idempotencyKey ("idempotency_unsupported") and echo expiresAt.
+// The simulator does not model Stripe's 24 h key retention.
+
 // File upload
 const storage = new StorageClient();
 await storage.upload(new File(["hi"], "note.txt", { type: "text/plain" }));
@@ -218,6 +226,13 @@ 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);
 
+// Signed in through LINE (a shop's LINE MINI App): the session carries the
+// person's shop-provider LINE user ID. Push to the ID on the SESSION.
+app.asUser({ id: "buyer-1", lineUserId: "Ushop-provider-1" });
+// route under test: const s = await getSession(); await integrations.line.push(s.user.lineUserId, ...)
+await callRoute(POST);
+expect(app.messages.channel("line").to("Ushop-provider-1")).toHaveLength(1);
+
 // LINE Flex card — the simulator preserves the complete LINE-native container.
 const card = {
   type: "bubble" as const,
@@ -322,7 +337,18 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
   or the platform's test-run deadline.
 
 - `app.asUser(partial?)` — sign in a test user; `getSession()` in app code
-  resolves to it. `app.signOut()` clears.
+  resolves to it. `app.signOut()` clears. Pass `lineUserId` to sign in as a
+  person who came through LINE sign-in inside the shop's LINE MINI App; it is
+  the same field production sets, so app code reads `session.user.lineUserId`.
+  `issueSession({ lineUserId })` carries it through cookie auth and the real
+  `/api/auth/me` route too.
+- `app.setLiffId(id | null)` / `createTestApp({ liffId })` — the LIFF ID the
+  platform forwards to the app (`null` by default = no LINE MINI App). The real
+  project-auth `/api/auth/me` returns it as `liffId` on every response, signed
+  in or not, which is what makes `useLiff()` start LIFF. `reset()` restores the
+  `createTestApp` value. The simulator does not run LIFF sign-in itself
+  (`POST /api/auth/liff` needs a real LINE ID token), so seed the signed-in
+  state with `asUser`/`issueSession` instead.
 - `app.issueSession(partial?)` — mint access/refresh tokens for cookie-based
   auth flows (`__stardeck:sess`).
 - `app.inbox` — emails sent through the email-sdk: `.latest(addr?)`,
@@ -619,6 +645,20 @@ per-field validation (unit-test the route), login/logout (platform-provided).
   never `waitForTimeout` (web-first assertions auto-wait), every test
   independent of other tests' data and ordering.
 
+## Testing LINE flows
+
+- Sign in as a LINE person with `app.asUser({ lineUserId: "U..." })` and call
+  the route with `callRoute`; assert the push with
+  `app.messages.channel("line").to("U...")`. Cover the person with no LINE
+  identity too (`asUser()` without `lineUserId`): the route must send nothing.
+- The recipient of a LINE push comes from `session.user.lineUserId` on the
+  server, never from a request body, query string or client-side value. A
+  `lineUserId` a browser sends can be forged to message any friend of the shop's
+  LINE Official Account. Do not write a route that takes one, and do not write a
+  test that posts one to make a push happen; sign in with `lineUserId` instead.
+- Whether the person is a friend of the shop's OA is a client concern
+  (`useLiff().isFriend`); a server route checks only that `lineUserId` exists.
+
 ## Rules
 
 - Test **business logic and route handlers**, not framework plumbing. Focus on

package/dist/index.d.mts

@@ -38,6 +38,12 @@ interface TestUser {
     projectId?: string | null;
     /** Cross-app customer ownership key returned by the platform identity resolver. */
     identityId?: string | null;
+    /**
+     * The person's LINE user ID under the shop's own LINE provider. Set it to sign in
+     * as someone who came through LINE sign-in inside the shop's LINE MINI App; app
+     * code reads it from `session.user.lineUserId` and pushes to it.
+     */
+    lineUserId?: string | null;
 }
 interface CapturedEmail {
     resendId: string;
@@ -615,6 +621,12 @@ interface TestStarlens {
     get count(): number;
 }
 interface TestAppOptions {
+    /**
+     * 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
+     * LIFF. Defaults to `null` (the app has no LINE MINI App). Restored by `reset()`.
+     */
+    liffId?: string | null;
     /** Data stores exposed through the production-shaped STARDECK_DATA_STORES manifest. */
     dataStores?: TestDataStoreInput[];
     /**
@@ -669,6 +681,11 @@ interface TestApp {
     asUser(user?: Partial<TestUser>): TestUser;
     /** Clear the active test user. */
     signOut(): void;
+    /**
+     * Set (or clear with `null`) the LIFF ID the platform forwards to the app, for
+     * the rest of the test. The real project-auth `me` route returns it as `liffId`.
+     */
+    setLiffId(liffId: string | null): void;
     /**
      * Mint access/refresh tokens for cookie-based auth flows. The simulated
      * control-plane verify endpoint resolves these tokens back to the user.

package/dist/index.d.ts

@@ -38,6 +38,12 @@ interface TestUser {
     projectId?: string | null;
     /** Cross-app customer ownership key returned by the platform identity resolver. */
     identityId?: string | null;
+    /**
+     * The person's LINE user ID under the shop's own LINE provider. Set it to sign in
+     * as someone who came through LINE sign-in inside the shop's LINE MINI App; app
+     * code reads it from `session.user.lineUserId` and pushes to it.
+     */
+    lineUserId?: string | null;
 }
 interface CapturedEmail {
     resendId: string;
@@ -615,6 +621,12 @@ interface TestStarlens {
     get count(): number;
 }
 interface TestAppOptions {
+    /**
+     * 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
+     * LIFF. Defaults to `null` (the app has no LINE MINI App). Restored by `reset()`.
+     */
+    liffId?: string | null;
     /** Data stores exposed through the production-shaped STARDECK_DATA_STORES manifest. */
     dataStores?: TestDataStoreInput[];
     /**
@@ -669,6 +681,11 @@ interface TestApp {
     asUser(user?: Partial<TestUser>): TestUser;
     /** Clear the active test user. */
     signOut(): void;
+    /**
+     * Set (or clear with `null`) the LIFF ID the platform forwards to the app, for
+     * the rest of the test. The real project-auth `me` route returns it as `liffId`.
+     */
+    setLiffId(liffId: string | null): void;
     /**
      * Mint access/refresh tokens for cookie-based auth flows. The simulated
      * control-plane verify endpoint resolves these tokens back to the user.

package/dist/index.js

@@ -310,6 +310,7 @@ var TEST_ENV_DEFAULTS = {
   DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
   STORAGE_URL: STORAGE_TEST_URL
 };
+var LIFF_ID_HEADER = "x-stardeck-liff-id";
 var DEFAULT_TEST_USER = {
   id: "test-user-1",
   email: "test-user@example.com",
@@ -324,6 +325,7 @@ var state = globalSingleton("state", () => ({
   db: null,
   lastHarnessDataStoreManifest: null,
   currentUser: null,
+  liffId: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
   emails: [],
@@ -338,6 +340,7 @@ var state = globalSingleton("state", () => ({
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
+  idempotentCheckouts: /* @__PURE__ */ new Map(),
   paymentLinks: /* @__PURE__ */ new Map(),
   paymentFailures: [],
   products: [],
@@ -2066,6 +2069,9 @@ async function callRoute(handler, options = {}) {
   if (user && !headers.has("x-stardeck-user")) {
     headers.set("x-stardeck-user", JSON.stringify(user));
   }
+  if (state.liffId && !headers.has(LIFF_ID_HEADER)) {
+    headers.set(LIFF_ID_HEADER, state.liffId);
+  }
   if (options.body !== void 0 && !headers.has("Content-Type")) {
     headers.set("Content-Type", "application/json");
   }
@@ -2126,6 +2132,8 @@ function signEventDelivery(secret, context, rawBody) {
 }
 
 // src/simulator/payments.ts
+var STRIPE_MIN_EXPIRY_SECONDS = 30 * 60;
+var STRIPE_MAX_EXPIRY_SECONDS = 24 * 60 * 60;
 var BEAM_BOLT_PAYMENT_METHODS = [
   "CARD",
   "CARD_INSTALLMENTS",
@@ -2195,6 +2203,15 @@ function isBoltPaymentMethod(value) {
 function isBoltIntentStatus(value) {
   return BEAM_BOLT_INTENT_STATUSES.includes(value);
 }
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+var ISO_8601_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
 function nextCheckoutId() {
   state.checkoutCounter += 1;
   return `cs_test_${state.checkoutCounter}`;
@@ -2215,7 +2232,7 @@ function nextBoltChargeId() {
   state.boltChargeCounter += 1;
   return `chrg_${state.boltChargeCounter}`;
 }
-function seedStripeSession(id, body) {
+function seedStripeSession(id, body, expiresAt) {
   const lineItems = body.lineItems ?? [];
   let amountTotal = null;
   let currency = null;
@@ -2235,7 +2252,7 @@ function seedStripeSession(id, body) {
     currency,
     customerEmail: body.customerEmail ? String(body.customerEmail) : null,
     metadata: body.metadata ?? {},
-    expiresAt: Math.floor(Date.now() / 1e3) + 3600
+    expiresAt
   });
 }
 function seedBeamLink(id, body, merchantId) {
@@ -2255,7 +2272,8 @@ function seedBeamLink(id, body, merchantId) {
     },
     redirectUrl: body.redirectUrl ? String(body.redirectUrl) : void 0,
     linkSettings: body.linkSettings,
-    collectDeliveryAddress: body.collectDeliveryAddress === true
+    collectDeliveryAddress: body.collectDeliveryAddress === true,
+    ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
   });
 }
 function deriveBoltIntentStatus(storedStatus, expiresAt, now3 = /* @__PURE__ */ new Date()) {
@@ -2557,6 +2575,16 @@ async function handlePaymentsRequest(request, url) {
     const linkId = beamProductsMatch[2];
     if (!linkId && request.method === "POST") {
       const body = await readJsonBody(request);
+      if ("idempotencyKey" in body) {
+        return payErr(
+          "idempotencyKey is not supported for Beam payment links.",
+          400,
+          "idempotency_unsupported"
+        );
+      }
+      if (typeof body.expiresAt === "string" && (!ISO_8601_WITH_ZONE.test(body.expiresAt) || Number.isNaN(Date.parse(body.expiresAt)))) {
+        return payErr("expiresAt must be an ISO 8601 timestamp", 400);
+      }
       const id = nextPaymentLinkId();
       const checkoutUrl = `https://beam.test/pay/${id}`;
       const captured = {
@@ -2569,7 +2597,11 @@ async function handlePaymentsRequest(request, url) {
       };
       state.checkouts.push(captured);
       seedBeamLink(id, body, merchantId);
-      return json({ id, url: checkoutUrl });
+      return json({
+        id,
+        url: checkoutUrl,
+        ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
+      });
     }
     if (linkId && request.method === "GET") {
       const link = state.paymentLinks.get(linkId);
@@ -2595,6 +2627,34 @@ async function handlePaymentsRequest(request, url) {
     }
     if (subPath === "checkout" && request.method === "POST") {
       const body = await readJsonBody(request);
+      const nowSeconds = Math.floor(Date.now() / 1e3);
+      const requestedExpiry = typeof body.expiresAt === "number" ? body.expiresAt : void 0;
+      const callerKey = typeof body.idempotencyKey === "string" ? body.idempotencyKey : void 0;
+      const scopedKey = callerKey ? JSON.stringify(["stripe", accountId, callerKey]) : void 0;
+      const comparable = { ...body };
+      delete comparable.deploymentId;
+      delete comparable.idempotencyKey;
+      const fingerprint = stableStringify(comparable);
+      if (scopedKey) {
+        const saved = state.idempotentCheckouts.get(scopedKey);
+        if (saved) {
+          if (saved.fingerprint !== fingerprint) {
+            return payErr(
+              "This idempotency key was already used with different checkout parameters. Use a new key for a different checkout.",
+              409,
+              "idempotency_conflict"
+            );
+          }
+          return json(saved.response);
+        }
+      }
+      if (requestedExpiry !== void 0 && (requestedExpiry < nowSeconds + STRIPE_MIN_EXPIRY_SECONDS || requestedExpiry > nowSeconds + STRIPE_MAX_EXPIRY_SECONDS)) {
+        return payErr(
+          "expiresAt must be between 30 minutes and 24 hours after the checkout is created (Unix seconds).",
+          400,
+          "expiry_out_of_range"
+        );
+      }
       const id = nextCheckoutId();
       const checkoutUrl = `https://checkout.stripe.test/c/pay/${id}`;
       const captured = {
@@ -2607,8 +2667,11 @@ async function handlePaymentsRequest(request, url) {
         createdAt: /* @__PURE__ */ new Date()
       };
       state.checkouts.push(captured);
-      seedStripeSession(id, body);
-      return json({ id, url: checkoutUrl });
+      const expiresAt = requestedExpiry ?? nowSeconds + STRIPE_MAX_EXPIRY_SECONDS;
+      seedStripeSession(id, body, expiresAt);
+      const response = { id, url: checkoutUrl, expiresAt };
+      if (scopedKey) state.idempotentCheckouts.set(scopedKey, { fingerprint, response });
+      return json(response);
     }
     const sessionMatch = subPath.match(/^checkout-sessions\/([^/]+)$/);
     if (sessionMatch && request.method === "GET") {
@@ -2773,6 +2836,7 @@ function createPayments() {
       state.checkouts = [];
       state.checkoutCounter = 0;
       state.sessionStatuses.clear();
+      state.idempotentCheckouts.clear();
       state.paymentLinks.clear();
       state.paymentFailures = [];
       state.products = [];
@@ -3856,6 +3920,8 @@ async function createTestApp(options = {}) {
   }
   applyTestEnv(options);
   state.allowNetwork = options.allowNetwork ?? false;
+  const initialLiffId = options.liffId ?? null;
+  state.liffId = initialLiffId;
   installFetchRouter();
   const schemaSql = loadSchemaSql(options) ?? "";
   const db = await bootWithSchema(schemaSql);
@@ -3908,6 +3974,9 @@ async function createTestApp(options = {}) {
     signOut() {
       state.currentUser = null;
     },
+    setLiffId(liffId) {
+      state.liffId = liffId;
+    },
     issueSession(user) {
       const fullUser = buildUser(user);
       const tokens = {
@@ -3930,6 +3999,7 @@ async function createTestApp(options = {}) {
         }
       }
       state.currentUser = null;
+      state.liffId = initialLiffId;
       state.sessions.clear();
       state.refreshSessions.clear();
       state.emails = [];
@@ -3944,6 +4014,7 @@ async function createTestApp(options = {}) {
     async close() {
       state.db = null;
       state.currentUser = null;
+      state.liffId = null;
       state.sessions.clear();
       state.refreshSessions.clear();
       state.emails = [];

package/dist/index.mjs

@@ -271,6 +271,7 @@ var TEST_ENV_DEFAULTS = {
   DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
   STORAGE_URL: STORAGE_TEST_URL
 };
+var LIFF_ID_HEADER = "x-stardeck-liff-id";
 var DEFAULT_TEST_USER = {
   id: "test-user-1",
   email: "test-user@example.com",
@@ -285,6 +286,7 @@ var state = globalSingleton("state", () => ({
   db: null,
   lastHarnessDataStoreManifest: null,
   currentUser: null,
+  liffId: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
   emails: [],
@@ -299,6 +301,7 @@ var state = globalSingleton("state", () => ({
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
+  idempotentCheckouts: /* @__PURE__ */ new Map(),
   paymentLinks: /* @__PURE__ */ new Map(),
   paymentFailures: [],
   products: [],
@@ -2027,6 +2030,9 @@ async function callRoute(handler, options = {}) {
   if (user && !headers.has("x-stardeck-user")) {
     headers.set("x-stardeck-user", JSON.stringify(user));
   }
+  if (state.liffId && !headers.has(LIFF_ID_HEADER)) {
+    headers.set(LIFF_ID_HEADER, state.liffId);
+  }
   if (options.body !== void 0 && !headers.has("Content-Type")) {
     headers.set("Content-Type", "application/json");
   }
@@ -2087,6 +2093,8 @@ function signEventDelivery(secret, context, rawBody) {
 }
 
 // src/simulator/payments.ts
+var STRIPE_MIN_EXPIRY_SECONDS = 30 * 60;
+var STRIPE_MAX_EXPIRY_SECONDS = 24 * 60 * 60;
 var BEAM_BOLT_PAYMENT_METHODS = [
   "CARD",
   "CARD_INSTALLMENTS",
@@ -2156,6 +2164,15 @@ function isBoltPaymentMethod(value) {
 function isBoltIntentStatus(value) {
   return BEAM_BOLT_INTENT_STATUSES.includes(value);
 }
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+var ISO_8601_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
 function nextCheckoutId() {
   state.checkoutCounter += 1;
   return `cs_test_${state.checkoutCounter}`;
@@ -2176,7 +2193,7 @@ function nextBoltChargeId() {
   state.boltChargeCounter += 1;
   return `chrg_${state.boltChargeCounter}`;
 }
-function seedStripeSession(id, body) {
+function seedStripeSession(id, body, expiresAt) {
   const lineItems = body.lineItems ?? [];
   let amountTotal = null;
   let currency = null;
@@ -2196,7 +2213,7 @@ function seedStripeSession(id, body) {
     currency,
     customerEmail: body.customerEmail ? String(body.customerEmail) : null,
     metadata: body.metadata ?? {},
-    expiresAt: Math.floor(Date.now() / 1e3) + 3600
+    expiresAt
   });
 }
 function seedBeamLink(id, body, merchantId) {
@@ -2216,7 +2233,8 @@ function seedBeamLink(id, body, merchantId) {
     },
     redirectUrl: body.redirectUrl ? String(body.redirectUrl) : void 0,
     linkSettings: body.linkSettings,
-    collectDeliveryAddress: body.collectDeliveryAddress === true
+    collectDeliveryAddress: body.collectDeliveryAddress === true,
+    ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
   });
 }
 function deriveBoltIntentStatus(storedStatus, expiresAt, now3 = /* @__PURE__ */ new Date()) {
@@ -2518,6 +2536,16 @@ async function handlePaymentsRequest(request, url) {
     const linkId = beamProductsMatch[2];
     if (!linkId && request.method === "POST") {
       const body = await readJsonBody(request);
+      if ("idempotencyKey" in body) {
+        return payErr(
+          "idempotencyKey is not supported for Beam payment links.",
+          400,
+          "idempotency_unsupported"
+        );
+      }
+      if (typeof body.expiresAt === "string" && (!ISO_8601_WITH_ZONE.test(body.expiresAt) || Number.isNaN(Date.parse(body.expiresAt)))) {
+        return payErr("expiresAt must be an ISO 8601 timestamp", 400);
+      }
       const id = nextPaymentLinkId();
       const checkoutUrl = `https://beam.test/pay/${id}`;
       const captured = {
@@ -2530,7 +2558,11 @@ async function handlePaymentsRequest(request, url) {
       };
       state.checkouts.push(captured);
       seedBeamLink(id, body, merchantId);
-      return json({ id, url: checkoutUrl });
+      return json({
+        id,
+        url: checkoutUrl,
+        ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
+      });
     }
     if (linkId && request.method === "GET") {
       const link = state.paymentLinks.get(linkId);
@@ -2556,6 +2588,34 @@ async function handlePaymentsRequest(request, url) {
     }
     if (subPath === "checkout" && request.method === "POST") {
       const body = await readJsonBody(request);
+      const nowSeconds = Math.floor(Date.now() / 1e3);
+      const requestedExpiry = typeof body.expiresAt === "number" ? body.expiresAt : void 0;
+      const callerKey = typeof body.idempotencyKey === "string" ? body.idempotencyKey : void 0;
+      const scopedKey = callerKey ? JSON.stringify(["stripe", accountId, callerKey]) : void 0;
+      const comparable = { ...body };
+      delete comparable.deploymentId;
+      delete comparable.idempotencyKey;
+      const fingerprint = stableStringify(comparable);
+      if (scopedKey) {
+        const saved = state.idempotentCheckouts.get(scopedKey);
+        if (saved) {
+          if (saved.fingerprint !== fingerprint) {
+            return payErr(
+              "This idempotency key was already used with different checkout parameters. Use a new key for a different checkout.",
+              409,
+              "idempotency_conflict"
+            );
+          }
+          return json(saved.response);
+        }
+      }
+      if (requestedExpiry !== void 0 && (requestedExpiry < nowSeconds + STRIPE_MIN_EXPIRY_SECONDS || requestedExpiry > nowSeconds + STRIPE_MAX_EXPIRY_SECONDS)) {
+        return payErr(
+          "expiresAt must be between 30 minutes and 24 hours after the checkout is created (Unix seconds).",
+          400,
+          "expiry_out_of_range"
+        );
+      }
       const id = nextCheckoutId();
       const checkoutUrl = `https://checkout.stripe.test/c/pay/${id}`;
       const captured = {
@@ -2568,8 +2628,11 @@ async function handlePaymentsRequest(request, url) {
         createdAt: /* @__PURE__ */ new Date()
       };
       state.checkouts.push(captured);
-      seedStripeSession(id, body);
-      return json({ id, url: checkoutUrl });
+      const expiresAt = requestedExpiry ?? nowSeconds + STRIPE_MAX_EXPIRY_SECONDS;
+      seedStripeSession(id, body, expiresAt);
+      const response = { id, url: checkoutUrl, expiresAt };
+      if (scopedKey) state.idempotentCheckouts.set(scopedKey, { fingerprint, response });
+      return json(response);
     }
     const sessionMatch = subPath.match(/^checkout-sessions\/([^/]+)$/);
     if (sessionMatch && request.method === "GET") {
@@ -2734,6 +2797,7 @@ function createPayments() {
       state.checkouts = [];
       state.checkoutCounter = 0;
       state.sessionStatuses.clear();
+      state.idempotentCheckouts.clear();
       state.paymentLinks.clear();
       state.paymentFailures = [];
       state.products = [];
@@ -3817,6 +3881,8 @@ async function createTestApp(options = {}) {
   }
   applyTestEnv(options);
   state.allowNetwork = options.allowNetwork ?? false;
+  const initialLiffId = options.liffId ?? null;
+  state.liffId = initialLiffId;
   installFetchRouter();
   const schemaSql = loadSchemaSql(options) ?? "";
   const db = await bootWithSchema(schemaSql);
@@ -3869,6 +3935,9 @@ async function createTestApp(options = {}) {
     signOut() {
       state.currentUser = null;
     },
+    setLiffId(liffId) {
+      state.liffId = liffId;
+    },
     issueSession(user) {
       const fullUser = buildUser(user);
       const tokens = {
@@ -3891,6 +3960,7 @@ async function createTestApp(options = {}) {
         }
       }
       state.currentUser = null;
+      state.liffId = initialLiffId;
       state.sessions.clear();
       state.refreshSessions.clear();
       state.emails = [];
@@ -3905,6 +3975,7 @@ async function createTestApp(options = {}) {
     async close() {
       state.db = null;
       state.currentUser = null;
+      state.liffId = null;
       state.sessions.clear();
       state.refreshSessions.clear();
       state.emails = [];

package/dist/next/headers-shim.js

@@ -28,6 +28,12 @@ __export(headers_shim_exports, {
 module.exports = __toCommonJS(headers_shim_exports);
 var import_node_async_hooks = require("async_hooks");
 
+// src/constants.ts
+var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
+var APP_TEST_ORIGIN = "http://localhost:3333";
+var LIFF_ID_HEADER = "x-stardeck-liff-id";
+
 // src/global-singleton.ts
 function globalSingleton(key, create) {
   const symbol = /* @__PURE__ */ Symbol.for(`stardeck-testing.${key}`);
@@ -36,16 +42,12 @@ function globalSingleton(key, create) {
   return holder[symbol];
 }
 
-// src/constants.ts
-var DATA_STORE_TEST_HOST = "db.stardeck.test";
-var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
-var APP_TEST_ORIGIN = "http://localhost:3333";
-
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
   lastHarnessDataStoreManifest: null,
   currentUser: null,
+  liffId: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
   emails: [],
@@ -60,6 +62,7 @@ var state = globalSingleton("state", () => ({
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
+  idempotentCheckouts: /* @__PURE__ */ new Map(),
   paymentLinks: /* @__PURE__ */ new Map(),
   paymentFailures: [],
   products: [],
@@ -105,6 +108,7 @@ function ambientScope() {
   if (state.currentUser) {
     headers2.set("x-stardeck-user", JSON.stringify(state.currentUser));
   }
+  if (state.liffId) headers2.set(LIFF_ID_HEADER, state.liffId);
   return { headers: headers2, cookies: /* @__PURE__ */ new Map() };
 }
 function currentScope() {

package/dist/next/headers-shim.mjs

@@ -1,6 +1,12 @@
 // src/next/headers-shim.ts
 import { AsyncLocalStorage } from "async_hooks";
 
+// src/constants.ts
+var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
+var APP_TEST_ORIGIN = "http://localhost:3333";
+var LIFF_ID_HEADER = "x-stardeck-liff-id";
+
 // src/global-singleton.ts
 function globalSingleton(key, create) {
   const symbol = /* @__PURE__ */ Symbol.for(`stardeck-testing.${key}`);
@@ -9,16 +15,12 @@ function globalSingleton(key, create) {
   return holder[symbol];
 }
 
-// src/constants.ts
-var DATA_STORE_TEST_HOST = "db.stardeck.test";
-var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
-var APP_TEST_ORIGIN = "http://localhost:3333";
-
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
   lastHarnessDataStoreManifest: null,
   currentUser: null,
+  liffId: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
   emails: [],
@@ -33,6 +35,7 @@ var state = globalSingleton("state", () => ({
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
+  idempotentCheckouts: /* @__PURE__ */ new Map(),
   paymentLinks: /* @__PURE__ */ new Map(),
   paymentFailures: [],
   products: [],
@@ -78,6 +81,7 @@ function ambientScope() {
   if (state.currentUser) {
     headers2.set("x-stardeck-user", JSON.stringify(state.currentUser));
   }
+  if (state.liffId) headers2.set(LIFF_ID_HEADER, state.liffId);
   return { headers: headers2, cookies: /* @__PURE__ */ new Map() };
 }
 function currentScope() {

package/dist/setup.js

@@ -52,6 +52,7 @@ var state = globalSingleton("state", () => ({
   db: null,
   lastHarnessDataStoreManifest: null,
   currentUser: null,
+  liffId: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
   emails: [],
@@ -66,6 +67,7 @@ var state = globalSingleton("state", () => ({
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
+  idempotentCheckouts: /* @__PURE__ */ new Map(),
   paymentLinks: /* @__PURE__ */ new Map(),
   paymentFailures: [],
   products: [],
@@ -1535,6 +1537,8 @@ var requestScopeStorage = globalSingleton(
 var import_node_crypto4 = __toESM(require("crypto"));
 
 // src/simulator/payments.ts
+var STRIPE_MIN_EXPIRY_SECONDS = 30 * 60;
+var STRIPE_MAX_EXPIRY_SECONDS = 24 * 60 * 60;
 var BEAM_BOLT_PAYMENT_METHODS = [
   "CARD",
   "CARD_INSTALLMENTS",
@@ -1604,6 +1608,15 @@ function isBoltPaymentMethod(value) {
 function isBoltIntentStatus(value) {
   return BEAM_BOLT_INTENT_STATUSES.includes(value);
 }
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+var ISO_8601_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
 function nextCheckoutId() {
   state.checkoutCounter += 1;
   return `cs_test_${state.checkoutCounter}`;
@@ -1620,7 +1633,7 @@ function nextBoltIntentId() {
   state.boltIntentCounter += 1;
   return `bolti_${state.boltIntentCounter}`;
 }
-function seedStripeSession(id, body) {
+function seedStripeSession(id, body, expiresAt) {
   const lineItems = body.lineItems ?? [];
   let amountTotal = null;
   let currency = null;
@@ -1640,7 +1653,7 @@ function seedStripeSession(id, body) {
     currency,
     customerEmail: body.customerEmail ? String(body.customerEmail) : null,
     metadata: body.metadata ?? {},
-    expiresAt: Math.floor(Date.now() / 1e3) + 3600
+    expiresAt
   });
 }
 function seedBeamLink(id, body, merchantId) {
@@ -1660,7 +1673,8 @@ function seedBeamLink(id, body, merchantId) {
     },
     redirectUrl: body.redirectUrl ? String(body.redirectUrl) : void 0,
     linkSettings: body.linkSettings,
-    collectDeliveryAddress: body.collectDeliveryAddress === true
+    collectDeliveryAddress: body.collectDeliveryAddress === true,
+    ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
   });
 }
 function deriveBoltIntentStatus(storedStatus, expiresAt, now3 = /* @__PURE__ */ new Date()) {
@@ -1931,6 +1945,16 @@ async function handlePaymentsRequest(request, url) {
     const linkId = beamProductsMatch[2];
     if (!linkId && request.method === "POST") {
       const body = await readJsonBody(request);
+      if ("idempotencyKey" in body) {
+        return payErr(
+          "idempotencyKey is not supported for Beam payment links.",
+          400,
+          "idempotency_unsupported"
+        );
+      }
+      if (typeof body.expiresAt === "string" && (!ISO_8601_WITH_ZONE.test(body.expiresAt) || Number.isNaN(Date.parse(body.expiresAt)))) {
+        return payErr("expiresAt must be an ISO 8601 timestamp", 400);
+      }
       const id = nextPaymentLinkId();
       const checkoutUrl = `https://beam.test/pay/${id}`;
       const captured = {
@@ -1943,7 +1967,11 @@ async function handlePaymentsRequest(request, url) {
       };
       state.checkouts.push(captured);
       seedBeamLink(id, body, merchantId);
-      return json({ id, url: checkoutUrl });
+      return json({
+        id,
+        url: checkoutUrl,
+        ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
+      });
     }
     if (linkId && request.method === "GET") {
       const link = state.paymentLinks.get(linkId);
@@ -1969,6 +1997,34 @@ async function handlePaymentsRequest(request, url) {
     }
     if (subPath === "checkout" && request.method === "POST") {
       const body = await readJsonBody(request);
+      const nowSeconds = Math.floor(Date.now() / 1e3);
+      const requestedExpiry = typeof body.expiresAt === "number" ? body.expiresAt : void 0;
+      const callerKey = typeof body.idempotencyKey === "string" ? body.idempotencyKey : void 0;
+      const scopedKey = callerKey ? JSON.stringify(["stripe", accountId, callerKey]) : void 0;
+      const comparable = { ...body };
+      delete comparable.deploymentId;
+      delete comparable.idempotencyKey;
+      const fingerprint = stableStringify(comparable);
+      if (scopedKey) {
+        const saved = state.idempotentCheckouts.get(scopedKey);
+        if (saved) {
+          if (saved.fingerprint !== fingerprint) {
+            return payErr(
+              "This idempotency key was already used with different checkout parameters. Use a new key for a different checkout.",
+              409,
+              "idempotency_conflict"
+            );
+          }
+          return json(saved.response);
+        }
+      }
+      if (requestedExpiry !== void 0 && (requestedExpiry < nowSeconds + STRIPE_MIN_EXPIRY_SECONDS || requestedExpiry > nowSeconds + STRIPE_MAX_EXPIRY_SECONDS)) {
+        return payErr(
+          "expiresAt must be between 30 minutes and 24 hours after the checkout is created (Unix seconds).",
+          400,
+          "expiry_out_of_range"
+        );
+      }
       const id = nextCheckoutId();
       const checkoutUrl = `https://checkout.stripe.test/c/pay/${id}`;
       const captured = {
@@ -1981,8 +2037,11 @@ async function handlePaymentsRequest(request, url) {
         createdAt: /* @__PURE__ */ new Date()
       };
       state.checkouts.push(captured);
-      seedStripeSession(id, body);
-      return json({ id, url: checkoutUrl });
+      const expiresAt = requestedExpiry ?? nowSeconds + STRIPE_MAX_EXPIRY_SECONDS;
+      seedStripeSession(id, body, expiresAt);
+      const response = { id, url: checkoutUrl, expiresAt };
+      if (scopedKey) state.idempotentCheckouts.set(scopedKey, { fingerprint, response });
+      return json(response);
     }
     const sessionMatch = subPath.match(/^checkout-sessions\/([^/]+)$/);
     if (sessionMatch && request.method === "GET") {

package/dist/setup.mjs

@@ -28,6 +28,7 @@ var state = globalSingleton("state", () => ({
   db: null,
   lastHarnessDataStoreManifest: null,
   currentUser: null,
+  liffId: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
   emails: [],
@@ -42,6 +43,7 @@ var state = globalSingleton("state", () => ({
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
+  idempotentCheckouts: /* @__PURE__ */ new Map(),
   paymentLinks: /* @__PURE__ */ new Map(),
   paymentFailures: [],
   products: [],
@@ -1511,6 +1513,8 @@ var requestScopeStorage = globalSingleton(
 import crypto4 from "crypto";
 
 // src/simulator/payments.ts
+var STRIPE_MIN_EXPIRY_SECONDS = 30 * 60;
+var STRIPE_MAX_EXPIRY_SECONDS = 24 * 60 * 60;
 var BEAM_BOLT_PAYMENT_METHODS = [
   "CARD",
   "CARD_INSTALLMENTS",
@@ -1580,6 +1584,15 @@ function isBoltPaymentMethod(value) {
 function isBoltIntentStatus(value) {
   return BEAM_BOLT_INTENT_STATUSES.includes(value);
 }
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+var ISO_8601_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
 function nextCheckoutId() {
   state.checkoutCounter += 1;
   return `cs_test_${state.checkoutCounter}`;
@@ -1596,7 +1609,7 @@ function nextBoltIntentId() {
   state.boltIntentCounter += 1;
   return `bolti_${state.boltIntentCounter}`;
 }
-function seedStripeSession(id, body) {
+function seedStripeSession(id, body, expiresAt) {
   const lineItems = body.lineItems ?? [];
   let amountTotal = null;
   let currency = null;
@@ -1616,7 +1629,7 @@ function seedStripeSession(id, body) {
     currency,
     customerEmail: body.customerEmail ? String(body.customerEmail) : null,
     metadata: body.metadata ?? {},
-    expiresAt: Math.floor(Date.now() / 1e3) + 3600
+    expiresAt
   });
 }
 function seedBeamLink(id, body, merchantId) {
@@ -1636,7 +1649,8 @@ function seedBeamLink(id, body, merchantId) {
     },
     redirectUrl: body.redirectUrl ? String(body.redirectUrl) : void 0,
     linkSettings: body.linkSettings,
-    collectDeliveryAddress: body.collectDeliveryAddress === true
+    collectDeliveryAddress: body.collectDeliveryAddress === true,
+    ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
   });
 }
 function deriveBoltIntentStatus(storedStatus, expiresAt, now3 = /* @__PURE__ */ new Date()) {
@@ -1907,6 +1921,16 @@ async function handlePaymentsRequest(request, url) {
     const linkId = beamProductsMatch[2];
     if (!linkId && request.method === "POST") {
       const body = await readJsonBody(request);
+      if ("idempotencyKey" in body) {
+        return payErr(
+          "idempotencyKey is not supported for Beam payment links.",
+          400,
+          "idempotency_unsupported"
+        );
+      }
+      if (typeof body.expiresAt === "string" && (!ISO_8601_WITH_ZONE.test(body.expiresAt) || Number.isNaN(Date.parse(body.expiresAt)))) {
+        return payErr("expiresAt must be an ISO 8601 timestamp", 400);
+      }
       const id = nextPaymentLinkId();
       const checkoutUrl = `https://beam.test/pay/${id}`;
       const captured = {
@@ -1919,7 +1943,11 @@ async function handlePaymentsRequest(request, url) {
       };
       state.checkouts.push(captured);
       seedBeamLink(id, body, merchantId);
-      return json({ id, url: checkoutUrl });
+      return json({
+        id,
+        url: checkoutUrl,
+        ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
+      });
     }
     if (linkId && request.method === "GET") {
       const link = state.paymentLinks.get(linkId);
@@ -1945,6 +1973,34 @@ async function handlePaymentsRequest(request, url) {
     }
     if (subPath === "checkout" && request.method === "POST") {
       const body = await readJsonBody(request);
+      const nowSeconds = Math.floor(Date.now() / 1e3);
+      const requestedExpiry = typeof body.expiresAt === "number" ? body.expiresAt : void 0;
+      const callerKey = typeof body.idempotencyKey === "string" ? body.idempotencyKey : void 0;
+      const scopedKey = callerKey ? JSON.stringify(["stripe", accountId, callerKey]) : void 0;
+      const comparable = { ...body };
+      delete comparable.deploymentId;
+      delete comparable.idempotencyKey;
+      const fingerprint = stableStringify(comparable);
+      if (scopedKey) {
+        const saved = state.idempotentCheckouts.get(scopedKey);
+        if (saved) {
+          if (saved.fingerprint !== fingerprint) {
+            return payErr(
+              "This idempotency key was already used with different checkout parameters. Use a new key for a different checkout.",
+              409,
+              "idempotency_conflict"
+            );
+          }
+          return json(saved.response);
+        }
+      }
+      if (requestedExpiry !== void 0 && (requestedExpiry < nowSeconds + STRIPE_MIN_EXPIRY_SECONDS || requestedExpiry > nowSeconds + STRIPE_MAX_EXPIRY_SECONDS)) {
+        return payErr(
+          "expiresAt must be between 30 minutes and 24 hours after the checkout is created (Unix seconds).",
+          400,
+          "expiry_out_of_range"
+        );
+      }
       const id = nextCheckoutId();
       const checkoutUrl = `https://checkout.stripe.test/c/pay/${id}`;
       const captured = {
@@ -1957,8 +2013,11 @@ async function handlePaymentsRequest(request, url) {
         createdAt: /* @__PURE__ */ new Date()
       };
       state.checkouts.push(captured);
-      seedStripeSession(id, body);
-      return json({ id, url: checkoutUrl });
+      const expiresAt = requestedExpiry ?? nowSeconds + STRIPE_MAX_EXPIRY_SECONDS;
+      seedStripeSession(id, body, expiresAt);
+      const response = { id, url: checkoutUrl, expiresAt };
+      if (scopedKey) state.idempotentCheckouts.set(scopedKey, { fingerprint, response });
+      return json(response);
     }
     const sessionMatch = subPath.match(/^checkout-sessions\/([^/]+)$/);
     if (sessionMatch && request.method === "GET") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Vitest test harness for Stardeck customer apps — in-process Postgres (PGlite) plus a control-plane simulator so the real Stardeck SDKs run unmodified in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",