@stardeck-customer-apps/testing 0.27.0 → 0.29.0

package/dist/index.mjs

@@ -321,6 +321,12 @@ var state = globalSingleton("state", () => ({
   stripePaymentIntents: /* @__PURE__ */ new Map(),
   stripePaymentIntentCounter: 0,
   stripeIdempotentIntents: /* @__PURE__ */ new Map(),
+  stripeRefunds: /* @__PURE__ */ new Map(),
+  stripeRefundCounter: 0,
+  stripeIdempotentRefunds: /* @__PURE__ */ new Map(),
+  beamRefunds: /* @__PURE__ */ new Map(),
+  beamRefundCounter: 0,
+  beamIdempotentRefunds: /* @__PURE__ */ new Map(),
   stripeAllowedMethods: ["card", "promptpay"],
   stripeChargesEnabled: true,
   uploads: [],
@@ -342,6 +348,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 function requireDb() {
@@ -2087,7 +2101,11 @@ function decodeNextRedirect(error) {
 var SIM_STRIPE_PUBLISHABLE_KEY = "pk_test_sim_stripe";
 var SIM_STRIPE_DEFAULT_ACCOUNT = "acct_sim_default";
 var METHODS = ["card", "promptpay"];
-var RESERVED_METADATA_KEYS = ["projectId", "stardeckReferenceId", "stardeckStagingDeploymentId"];
+var RESERVED_METADATA_KEYS = [
+  "projectId",
+  "stardeckReferenceId",
+  "stardeckStagingDeploymentId"
+];
 var PROMPTPAY_QR_TTL_SECONDS = 15 * 60;
 var PATH_RE = /^\/api\/store\/(?!beam\/)([^/]+)\/(payment-intents(?:\/([^/]+)(?:\/(cancel))?)?|elements-config|readiness)$/;
 function err(error, status, code) {
@@ -2288,6 +2306,36 @@ function createIntent(body, account, projectId) {
   );
   return json({ paymentIntent: toStripePaymentIntentSummary(intent) }, 201);
 }
+function createHostedPaymentIntent(input) {
+  state.stripePaymentIntentCounter += 1;
+  const id = `pi_sim_${state.stripePaymentIntentCounter}`;
+  const metadata = appMetadata(input.metadata);
+  const intent = {
+    id,
+    projectId: input.projectId,
+    account: "default",
+    connectedAccountId: resolveAccount("default"),
+    playground: false,
+    status: "succeeded",
+    amount: input.amount,
+    currency: input.currency.toLowerCase(),
+    method: "card",
+    referenceId: input.sessionId,
+    appMetadata: metadata,
+    metadata: { ...metadata, projectId: input.projectId },
+    description: null,
+    receiptEmail: null,
+    returnUrl: null,
+    clientSecret: `${id}_secret_sim`,
+    qr: null,
+    latestChargeId: `ch_sim_${id}`,
+    amountRefunded: 0,
+    lastPaymentError: null,
+    created: Math.floor(Date.now() / 1e3)
+  };
+  state.stripePaymentIntents.set(id, intent);
+  return intent;
+}
 function ownedIntent(id, projectId) {
   const intent = state.stripePaymentIntents.get(id);
   return intent && intent.projectId === projectId ? intent : void 0;
@@ -2425,6 +2473,485 @@ function stripePaymentIntentEvent(id) {
   };
 }
 
+// src/simulator/refunds.ts
+var REFUND_ROW_KEY = "refundRowId";
+var REFUND_METADATA_MAX_KEYS = 50 - RESERVED_METADATA_KEYS.length - 1;
+var REFUND_REASONS = ["duplicate", "fraudulent", "requested_by_customer"];
+var PROMPTPAY_BANK_DETAILS_WINDOW_SECONDS = 7 * 24 * 60 * 60;
+var BEAM_PARTIAL_METHODS = ["CARD", "CARD_TOKEN"];
+function refundFailure(plan) {
+  return err(plan.message, plan.status, plan.code);
+}
+function isPositiveInt(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function hasValidKey(value) {
+  return typeof value === "string" && value.length >= 1 && value.length <= 255;
+}
+function isValidDeploymentId(value) {
+  return typeof value === "string" && UUID_RE2.test(value);
+}
+function isValidRefundMetadata(value) {
+  if (!isStringRecord(value)) return false;
+  const entries = Object.entries(value);
+  return entries.length <= REFUND_METADATA_MAX_KEYS && entries.every(
+    ([k, v]) => k.length >= 1 && k.length <= 40 && v.length <= 500 && !RESERVED_METADATA_KEYS.includes(k) && k !== REFUND_ROW_KEY
+  );
+}
+var COUNTED_STRIPE_STATUSES = [
+  "pending",
+  "requires_action",
+  "succeeded"
+];
+function refundedAmount(intentId) {
+  let total = 0;
+  for (const refund of state.stripeRefunds.values()) {
+    if (refund.paymentIntentId === intentId && COUNTED_STRIPE_STATUSES.includes(refund.status)) {
+      total += refund.amount;
+    }
+  }
+  return total;
+}
+function syncAmountRefunded(intent) {
+  intent.amountRefunded = refundedAmount(intent.id);
+}
+function validateStripeRefund(body) {
+  const checks = [
+    [isValidDeploymentId(body.deploymentId), "Invalid deployment ID"],
+    [hasValidKey(body.idempotencyKey), "idempotencyKey is required (1 to 255 characters)"],
+    [isOptional(body.amount, isPositiveInt), "amount must be a positive integer in minor units"],
+    [
+      isOptional(body.reason, (v) => typeof v === "string" && REFUND_REASONS.includes(v)),
+      `reason must be one of: ${REFUND_REASONS.join(", ")}`
+    ],
+    [isOptional(body.instructionsEmail, isEmail), "instructionsEmail must be an email address"],
+    [
+      isOptional(
+        body.refundRowId,
+        (v) => typeof v === "string" && v.length >= 1 && v.length <= 500
+      ),
+      "refundRowId must be 1 to 500 characters"
+    ],
+    [
+      isOptional(body.metadata, isValidRefundMetadata),
+      `metadata must map keys (1-40 chars) to strings (max 500), at most ${REFUND_METADATA_MAX_KEYS} keys, without the keys the platform reserves (use refundRowId instead)`
+    ]
+  ];
+  const failed = checks.find(([ok]) => !ok);
+  return failed ? failed[1] : null;
+}
+function planStripeRefund(intent, requested) {
+  if (intent.status !== "succeeded") {
+    return {
+      ok: false,
+      status: 409,
+      code: "payment_not_refundable",
+      message: "This payment hasn't succeeded, so there is nothing to refund"
+    };
+  }
+  const remaining = intent.amount - refundedAmount(intent.id);
+  const amount = requested ?? remaining;
+  if (remaining <= 0 || amount > remaining) {
+    return {
+      ok: false,
+      status: 409,
+      code: "refund_exceeds_remaining",
+      message: `Only ${remaining} can still be refunded on this payment`
+    };
+  }
+  return { ok: true, amount };
+}
+function toStripeRefundSummary(refund) {
+  const intent = state.stripePaymentIntents.get(refund.paymentIntentId);
+  return {
+    id: refund.id,
+    paymentIntentId: refund.paymentIntentId,
+    amount: refund.amount,
+    currency: refund.currency,
+    status: refund.status,
+    failureReason: refund.failureReason,
+    pendingReason: refund.pendingReason,
+    nextActionExpiresAt: refund.nextActionExpiresAt,
+    refundRowId: refund.refundRowId,
+    metadata: { ...refund.appMetadata },
+    created: refund.created,
+    livemode: false,
+    playground: intent?.playground ?? false
+  };
+}
+function newStripeRefund(input) {
+  state.stripeRefundCounter += 1;
+  const refund = {
+    id: `re_sim_${state.stripeRefundCounter}`,
+    paymentIntentId: input.intent.id,
+    projectId: input.intent.projectId,
+    amount: input.amount,
+    currency: input.intent.currency,
+    // A refund made in the Stripe dashboard is already done; the app's waits for `settleRefund`.
+    status: input.origin === "dashboard" ? "succeeded" : "pending",
+    failureReason: null,
+    pendingReason: null,
+    nextActionExpiresAt: null,
+    refundRowId: input.refundRowId ?? null,
+    appMetadata: input.appMetadata ?? {},
+    reason: input.reason ?? null,
+    origin: input.origin,
+    revision: 0,
+    created: Math.floor(Date.now() / 1e3)
+  };
+  state.stripeRefunds.set(refund.id, refund);
+  syncAmountRefunded(input.intent);
+  console.log(
+    `[stardeck-testing] stripe refund ${refund.id} created payment=${refund.paymentIntentId} amount=${refund.amount} origin=${refund.origin}`
+  );
+  return refund;
+}
+function createStripeRefund(body, intent, projectId) {
+  const scopedKey = JSON.stringify(["refund", projectId, intent.account, body.idempotencyKey]);
+  const fingerprint = stableStringify({
+    paymentIntentId: intent.id,
+    amount: body.amount,
+    reason: body.reason,
+    instructionsEmail: body.instructionsEmail,
+    refundRowId: body.refundRowId,
+    metadata: body.metadata
+  });
+  const saved = state.stripeIdempotentRefunds.get(scopedKey);
+  if (saved) {
+    if (saved.fingerprint !== fingerprint) {
+      return err(
+        "This idempotency key was already used with different parameters. Use a new key for a different refund.",
+        409,
+        "idempotency_conflict"
+      );
+    }
+    return json({ refund: toStripeRefundSummary(state.stripeRefunds.get(saved.id)) });
+  }
+  const plan = planStripeRefund(intent, body.amount);
+  if (!plan.ok) return refundFailure(plan);
+  const refund = newStripeRefund({
+    intent,
+    amount: plan.amount,
+    origin: "app",
+    refundRowId: typeof body.refundRowId === "string" ? body.refundRowId : null,
+    appMetadata: appMetadata(body.metadata),
+    reason: typeof body.reason === "string" ? body.reason : null
+  });
+  state.stripeIdempotentRefunds.set(scopedKey, { fingerprint, id: refund.id });
+  return json({ refund: toStripeRefundSummary(refund) });
+}
+var STRIPE_REFUND_PATH = /^\/api\/store\/(?!beam\/)[^/]+\/(?:payment-intents\/([^/]+)\/refunds|refunds\/([^/]+))$/;
+async function handleStripeRefundRequest(request, url, projectId) {
+  const match = url.pathname.match(STRIPE_REFUND_PATH);
+  if (!match) return null;
+  const [, intentId, refundId] = match;
+  const isCreate = request.method === "POST" && intentId !== void 0;
+  const isRead = request.method === "GET" && refundId !== void 0;
+  if (!isCreate && !isRead) return null;
+  if (!projectId) return err("Missing authentication", 401, "unauthorized");
+  if (isRead) {
+    if (!url.searchParams.get("deploymentId")) {
+      return err("deploymentId is required", 400, "invalid_request");
+    }
+    const refund = state.stripeRefunds.get(decode(refundId));
+    if (!refund || refund.projectId !== projectId) {
+      return err("Refund not found", 404, "refund_not_found");
+    }
+    return json({ refund: toStripeRefundSummary(refund) });
+  }
+  const body = await readJsonBody(request);
+  const problem = validateStripeRefund(body);
+  if (problem) return err(problem, 400, "invalid_request");
+  const intent = ownedIntent(decode(intentId), projectId);
+  if (!intent) return err("No such payment for this app", 404, "payment_not_owned");
+  return createStripeRefund(body, intent, projectId);
+}
+function requireStripeRefund(id) {
+  const refund = state.stripeRefunds.get(id);
+  if (!refund) throw new Error(`[stardeck-testing] Unknown Stripe refund id: ${id}`);
+  return refund;
+}
+function settleStripeRefund(refund, outcome, failureReason) {
+  const intent = state.stripePaymentIntents.get(refund.paymentIntentId);
+  const settled = refund.status === "failed" || refund.status === "canceled";
+  if (settled || outcome !== "failed" && refund.status === "succeeded") {
+    throw new Error(
+      `[stardeck-testing] Can't settle Stripe refund ${refund.id} as ${outcome}: it is ${refund.status}`
+    );
+  }
+  if (outcome === "needs_customer") {
+    if (intent.method !== "promptpay") {
+      throw new Error(
+        `[stardeck-testing] Stripe refund ${refund.id} is on a ${intent.method} payment; only PromptPay refunds wait for the customer's bank details`
+      );
+    }
+    refund.status = "requires_action";
+    refund.nextActionExpiresAt = refund.created + PROMPTPAY_BANK_DETAILS_WINDOW_SECONDS;
+  } else {
+    refund.status = outcome;
+    refund.nextActionExpiresAt = null;
+    refund.pendingReason = null;
+    refund.failureReason = outcome === "failed" ? failureReason ?? "unknown" : null;
+  }
+  refund.revision += 1;
+  syncAmountRefunded(intent);
+  return refund;
+}
+function stripeRefundEvent(id, type) {
+  const refund = requireStripeRefund(id);
+  const intent = state.stripePaymentIntents.get(refund.paymentIntentId);
+  let eventType = type;
+  if (!eventType) {
+    if (refund.status === "failed") eventType = "refund.failed";
+    else eventType = refund.revision === 0 ? "refund.created" : "refund.updated";
+  }
+  const metadata = { ...refund.appMetadata };
+  if (refund.origin === "app") metadata.projectId = refund.projectId;
+  if (refund.refundRowId) metadata[REFUND_ROW_KEY] = refund.refundRowId;
+  return {
+    type: eventType,
+    accountId: intent.connectedAccountId ?? "acct_stardeck_playground",
+    data: {
+      id: refund.id,
+      object: "refund",
+      amount: refund.amount,
+      currency: refund.currency,
+      payment_intent: refund.paymentIntentId,
+      charge: intent.latestChargeId,
+      status: refund.status,
+      reason: refund.reason,
+      failure_reason: refund.failureReason,
+      pending_reason: refund.pendingReason,
+      next_action: refund.status === "requires_action" ? {
+        type: "display_details",
+        display_details: { expires_at: refund.nextActionExpiresAt }
+      } : null,
+      metadata,
+      created: refund.created,
+      livemode: false
+    }
+  };
+}
+function refundsOfCharge(chargeId) {
+  return [...state.beamRefunds.values()].filter((r) => r.chargeId === chargeId);
+}
+function planBeamRefund(charge, requested) {
+  if (charge.status !== "SUCCEEDED") {
+    return {
+      ok: false,
+      status: 409,
+      code: "payment_not_refundable",
+      message: "This charge hasn't succeeded, so there is nothing to refund"
+    };
+  }
+  const refunds = refundsOfCharge(charge.id);
+  if (refunds.some((r) => r.status === "PENDING")) {
+    return {
+      ok: false,
+      status: 409,
+      code: "refund_in_progress",
+      message: "This charge already has a refund in progress. Wait for it to finish."
+    };
+  }
+  const refunded = refunds.filter((r) => r.status === "SUCCEEDED").reduce((n, r) => n + r.amount, 0);
+  const remaining = charge.amount - refunded;
+  const amount = requested ?? remaining;
+  if (remaining <= 0 || amount > remaining) {
+    return {
+      ok: false,
+      status: 409,
+      code: "refund_exceeds_remaining",
+      message: `Only ${remaining} can still be refunded on this charge`
+    };
+  }
+  if (amount < charge.amount && !BEAM_PARTIAL_METHODS.includes(charge.paymentMethodType)) {
+    return {
+      ok: false,
+      status: 409,
+      code: "refund_partial_not_allowed",
+      message: `${charge.paymentMethodType} charges can only be refunded in full`
+    };
+  }
+  return { ok: true, amount };
+}
+function toBeamRefundSummary(refund) {
+  return {
+    refundId: refund.refundId,
+    chargeId: refund.chargeId,
+    amount: refund.amount,
+    currency: refund.currency,
+    status: refund.status,
+    failureCode: refund.failureCode,
+    reason: refund.reason,
+    createdAt: refund.createdAt
+  };
+}
+function newBeamRefund(input) {
+  state.beamRefundCounter += 1;
+  const refund = {
+    refundId: `rf_sim_${state.beamRefundCounter}`,
+    chargeId: input.charge.id,
+    amount: input.amount,
+    currency: input.charge.currency,
+    status: input.origin === "dashboard" ? "SUCCEEDED" : "PENDING",
+    failureCode: null,
+    reason: input.reason ?? null,
+    origin: input.origin,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  state.beamRefunds.set(refund.refundId, refund);
+  console.log(
+    `[stardeck-testing] beam refund ${refund.refundId} created charge=${refund.chargeId} amount=${refund.amount} origin=${refund.origin}`
+  );
+  return refund;
+}
+function validateBeamRefund(body) {
+  const checks = [
+    [isValidDeploymentId(body.deploymentId), "Invalid deployment ID"],
+    [hasValidKey(body.idempotencyKey), "idempotencyKey is required (1 to 255 characters)"],
+    [isOptional(body.amount, isPositiveInt), "amount must be a positive integer in satang"],
+    [
+      isOptional(body.reason, (v) => typeof v === "string" && v.length <= 500),
+      "reason must be at most 500 characters"
+    ]
+  ];
+  const failed = checks.find(([ok]) => !ok);
+  return failed ? failed[1] : null;
+}
+function createBeamRefund(body, charge, merchant) {
+  const scopedKey = JSON.stringify(["beam-refund", merchant, body.idempotencyKey]);
+  const fingerprint = stableStringify({
+    chargeId: charge.id,
+    amount: body.amount,
+    reason: body.reason
+  });
+  const saved = state.beamIdempotentRefunds.get(scopedKey);
+  if (saved) {
+    if (saved.fingerprint !== fingerprint) {
+      return err(
+        "This idempotency key was already used with different parameters. Use a new key for a different refund.",
+        409,
+        "idempotency_conflict"
+      );
+    }
+    return json({ refund: toBeamRefundSummary(state.beamRefunds.get(saved.id)) });
+  }
+  const plan = planBeamRefund(charge, body.amount);
+  if (!plan.ok) return refundFailure(plan);
+  const refund = newBeamRefund({
+    charge,
+    amount: plan.amount,
+    origin: "app",
+    reason: typeof body.reason === "string" ? body.reason : null
+  });
+  state.beamIdempotentRefunds.set(scopedKey, { fingerprint, id: refund.refundId });
+  return json({ refund: toBeamRefundSummary(refund) });
+}
+var BEAM_REFUND_PATH = /^\/api\/store\/beam\/([^/]+)\/(?:charges\/([^/]+)\/refunds|refunds\/([^/]+))$/;
+async function handleBeamRefundRequest(request, url) {
+  const match = url.pathname.match(BEAM_REFUND_PATH);
+  if (!match) return null;
+  const [, merchant, chargeId, refundId] = match;
+  const isCreate = request.method === "POST" && chargeId !== void 0;
+  const isRead = request.method === "GET" && refundId !== void 0;
+  if (!isCreate && !isRead) return null;
+  if (isRead) {
+    if (!url.searchParams.get("deploymentId")) {
+      return err("deploymentId is required", 400, "invalid_request");
+    }
+    const refund = state.beamRefunds.get(decode(refundId));
+    if (!refund) return err("Refund not found", 404, "refund_not_found");
+    return json({ refund: toBeamRefundSummary(refund) });
+  }
+  const body = await readJsonBody(request);
+  const problem = validateBeamRefund(body);
+  if (problem) return err(problem, 400, "invalid_request");
+  const charge = state.directCharges.get(decode(chargeId));
+  if (!charge) return err("No such charge for this app", 404, "payment_not_owned");
+  return createBeamRefund(body, charge, decode(merchant));
+}
+function requireBeamRefund(id) {
+  const refund = state.beamRefunds.get(id);
+  if (!refund) throw new Error(`[stardeck-testing] Unknown Beam refund id: ${id}`);
+  return refund;
+}
+function settleBeamRefund(refund, outcome, failureCode) {
+  if (outcome === "needs_customer") {
+    throw new Error(
+      `[stardeck-testing] Beam refund ${refund.refundId} can't need the customer: Beam refunds have no customer step (only Stripe PromptPay does)`
+    );
+  }
+  if (refund.status !== "PENDING") {
+    throw new Error(
+      `[stardeck-testing] Can't settle Beam refund ${refund.refundId} as ${outcome}: it is ${refund.status}, and Beam refund statuses are final`
+    );
+  }
+  refund.status = outcome === "succeeded" ? "SUCCEEDED" : "FAILED";
+  refund.failureCode = outcome === "failed" ? failureCode ?? "REFUND_FAILED" : null;
+  return refund;
+}
+function beamRefundEvent(id) {
+  const refund = requireBeamRefund(id);
+  if (refund.status === "PENDING") {
+    throw new Error(
+      `[stardeck-testing] Beam refund ${id} is PENDING and has no event yet; call settleRefund first`
+    );
+  }
+  return {
+    type: refund.status === "SUCCEEDED" ? "refund.succeeded" : "refund.failed",
+    payload: {
+      refundId: refund.refundId,
+      chargeId: refund.chargeId,
+      merchantId: SIM_BEAM_MERCHANT_ID,
+      status: refund.status,
+      amount: refund.amount,
+      currency: refund.currency,
+      ...refund.failureCode ? { failureCode: refund.failureCode } : {},
+      ...refund.reason ? { reason: refund.reason } : {},
+      createdAt: refund.createdAt
+    }
+  };
+}
+function settleRefund(refundId, outcome, options) {
+  const stripe = state.stripeRefunds.get(refundId);
+  if (stripe) settleStripeRefund(stripe, outcome, options?.failureReason);
+  else settleBeamRefund(requireBeamRefund(refundId), outcome, options?.failureReason);
+}
+function dashboardRefund(paymentRef, amount) {
+  const intent = state.stripePaymentIntents.get(paymentRef);
+  if (intent) {
+    const plan = planStripeRefund(intent, amount);
+    if (!plan.ok) throw dashboardRefused(paymentRef, plan);
+    return newStripeRefund({ intent, amount: plan.amount, origin: "dashboard" }).id;
+  }
+  const charge = state.directCharges.get(paymentRef);
+  if (charge) {
+    const plan = planBeamRefund(charge, amount);
+    if (!plan.ok) throw dashboardRefused(paymentRef, plan);
+    return newBeamRefund({ charge, amount: plan.amount, origin: "dashboard" }).refundId;
+  }
+  throw new Error(
+    `[stardeck-testing] dashboardRefund: unknown payment ${paymentRef}; pass a Stripe PaymentIntent id or a Beam direct charge id`
+  );
+}
+function dashboardRefused(paymentRef, plan) {
+  return new Error(
+    `[stardeck-testing] dashboardRefund of ${paymentRef} refused (${plan.code}): ${plan.message}`
+  );
+}
+function findCheckoutSessionByIntent(url, projectId) {
+  if (!projectId) return err("Missing authentication", 401, "unauthorized");
+  if (!url.searchParams.get("deploymentId")) {
+    return err("deploymentId is required", 400, "invalid_request");
+  }
+  const intentId = url.searchParams.get("paymentIntentId");
+  if (!intentId) return err("paymentIntentId is required", 400, "invalid_request");
+  const intent = state.stripePaymentIntents.get(intentId);
+  if (intent && intent.projectId !== projectId) return json({ session: null });
+  const session = [...state.sessionStatuses.values()].find((s) => s.paymentIntentId === intentId);
+  return json({ session: session ?? null });
+}
+
 // src/simulator/webhook-signing.ts
 import crypto4 from "crypto";
 function signEventDelivery(secret, context, rawBody) {
@@ -2484,6 +3011,15 @@ function paymentOperationForRequest(request, pathname) {
   if (request.method === "GET" && /^\/api\/store\/(?!beam\/)[^/]+\/checkout-sessions\/[^/]+$/.test(pathname)) {
     return "stripe.getCheckoutSessionStatus";
   }
+  if (request.method === "POST" && /^\/api\/store\/beam\/[^/]+\/charges\/[^/]+\/refunds$/.test(pathname)) {
+    return "beam.refundCharge";
+  }
+  if (request.method === "GET" && /^\/api\/store\/beam\/[^/]+\/refunds\/[^/]+$/.test(pathname)) {
+    return "beam.getRefund";
+  }
+  if (request.method === "GET" && /^\/api\/store\/(?!beam\/)[^/]+\/checkout-sessions$/.test(pathname)) {
+    return "stripe.findCheckoutSessionByIntent";
+  }
   return stripeInlineOperation(request.method, pathname);
 }
 var STRIPE_INLINE_OPERATIONS = [
@@ -2495,6 +3031,12 @@ var STRIPE_INLINE_OPERATIONS = [
     /^\/api\/store\/(?!beam\/)[^/]+\/payment-intents\/[^/]+\/cancel$/,
     "stripe.cancelPaymentIntent"
   ],
+  [
+    "POST",
+    /^\/api\/store\/(?!beam\/)[^/]+\/payment-intents\/[^/]+\/refunds$/,
+    "stripe.refundPaymentIntent"
+  ],
+  ["GET", /^\/api\/store\/(?!beam\/)[^/]+\/refunds\/[^/]+$/, "stripe.getRefund"],
   ["GET", /^\/api\/store\/(?!beam\/)[^/]+\/elements-config$/, "stripe.getElementsConfig"],
   ["GET", /^\/api\/store\/(?!beam\/)[^/]+\/readiness$/, "stripe.getReadiness"]
 ];
@@ -2579,7 +3121,8 @@ function seedStripeSession(id, body, expiresAt) {
     currency,
     customerEmail: body.customerEmail ? String(body.customerEmail) : null,
     metadata: body.metadata ?? {},
-    expiresAt
+    expiresAt,
+    paymentIntentId: null
   });
 }
 function seedBeamLink(id, body, merchantId) {
@@ -2685,6 +3228,10 @@ async function handlePaymentsRequest(request, url, signedProjectId = null) {
     signedProjectId
   );
   if (inlineStripeResponse) return inlineStripeResponse;
+  const stripeRefundResponse = await handleStripeRefundRequest(request, url, signedProjectId);
+  if (stripeRefundResponse) return stripeRefundResponse;
+  const beamRefundResponse = await handleBeamRefundRequest(request, url);
+  if (beamRefundResponse) return beamRefundResponse;
   const directChargeResponse = await handleDirectChargeRequest(request, pathname);
   if (directChargeResponse) return directChargeResponse;
   if (/\/billing-portal$/.test(pathname)) {
@@ -3006,6 +3553,9 @@ async function handlePaymentsRequest(request, url, signedProjectId = null) {
       if (scopedKey) state.idempotentCheckouts.set(scopedKey, { fingerprint, response });
       return json(response);
     }
+    if (subPath === "checkout-sessions" && request.method === "GET") {
+      return findCheckoutSessionByIntent(url, signedProjectId);
+    }
     const sessionMatch = subPath.match(/^checkout-sessions\/([^/]+)$/);
     if (sessionMatch && request.method === "GET") {
       const session = state.sessionStatuses.get(sessionMatch[1]);
@@ -3015,6 +3565,17 @@ async function handlePaymentsRequest(request, url, signedProjectId = null) {
   }
   return payErr(`No payments simulator for ${request.method} ${pathname}`, 404);
 }
+function attachHostedPayment(session) {
+  if (session.paymentIntentId || session.mode !== "payment") return;
+  if (session.amountTotal === null || session.currency === null) return;
+  session.paymentIntentId = createHostedPaymentIntent({
+    projectId: TEST_ENV_DEFAULTS.PROJECT_ID,
+    sessionId: session.id,
+    amount: session.amountTotal,
+    currency: session.currency,
+    metadata: session.metadata
+  }).id;
+}
 function requirePendingDirectCharge(chargeId) {
   const charge = state.directCharges.get(chargeId);
   if (!charge) {
@@ -3050,6 +3611,7 @@ function createPayments() {
       if (session) {
         session.status = "complete";
         session.paymentStatus = "paid";
+        attachHostedPayment(session);
         return;
       }
       const link = state.paymentLinks.get(id);
@@ -3092,7 +3654,10 @@ function createPayments() {
       state.stripeChargesEnabled = enabled;
     },
     async deliverStripeEvent(handler, input, options) {
-      const event = "paymentIntentId" in input ? stripePaymentIntentEvent(input.paymentIntentId) : input;
+      let event;
+      if ("paymentIntentId" in input) event = stripePaymentIntentEvent(input.paymentIntentId);
+      else if ("refundId" in input) event = stripeRefundEvent(input.refundId, input.type);
+      else event = input;
       const envelope = {
         id: `evt_test_${crypto5.randomUUID()}`,
         kind: "stripe_webhook",
@@ -3105,7 +3670,8 @@ function createPayments() {
       };
       return deliverEvent(envelope, handler, options);
     },
-    async deliverBeamEvent(handler, event, options) {
+    async deliverBeamEvent(handler, input, options) {
+      const event = "refundId" in input ? beamRefundEvent(input.refundId) : input;
       const envelope = {
         id: `beam_evt_test_${crypto5.randomUUID()}`,
         kind: "beam_webhook",
@@ -3117,6 +3683,20 @@ function createPayments() {
       };
       return deliverEvent(envelope, handler, options);
     },
+    get stripeRefunds() {
+      return [...state.stripeRefunds.values()];
+    },
+    getStripeRefund(refundId) {
+      return state.stripeRefunds.get(refundId);
+    },
+    get beamRefunds() {
+      return [...state.beamRefunds.values()];
+    },
+    getBeamRefund(refundId) {
+      return state.beamRefunds.get(refundId);
+    },
+    settleRefund,
+    dashboardRefund,
     approveBoltIntent(intentId, options) {
       const intent = requirePendingBoltIntent(intentId);
       const chargeId = options?.chargeId ?? nextBoltChargeId();
@@ -3211,6 +3791,12 @@ function createPayments() {
       state.stripePaymentIntents.clear();
       state.stripePaymentIntentCounter = 0;
       state.stripeIdempotentIntents.clear();
+      state.stripeRefunds.clear();
+      state.stripeRefundCounter = 0;
+      state.stripeIdempotentRefunds.clear();
+      state.beamRefunds.clear();
+      state.beamRefundCounter = 0;
+      state.beamIdempotentRefunds.clear();
       state.stripeAllowedMethods = ["card", "promptpay"];
       state.stripeChargesEnabled = true;
     },
@@ -3985,6 +4571,141 @@ function createEdge() {
   };
 }
 
+// src/simulator/controls.ts
+var CONTROLS_STATE_SYMBOL = /* @__PURE__ */ Symbol.for("stardeck.controls.state");
+var USER_TOKEN_HEADER = "x-stardeck-user-token";
+var DEFAULTS = {
+  "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 }
+};
+var REFUSAL_STATUS = {
+  NOT_WRITABLE: 400,
+  INVALID_VALUE: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  WRITE_NOT_ALLOWED_HERE: 403,
+  PROVIDER_NOT_READY: 409,
+  UNAVAILABLE: 503
+};
+var controlsModule = null;
+function loadControls() {
+  controlsModule ??= import("@stardeck-customer-apps/controls");
+  return controlsModule;
+}
+function resetControlsClientCache() {
+  const clientState = globalThis[CONTROLS_STATE_SYMBOL];
+  clientState?.reset?.();
+}
+function initControls(seed) {
+  state.controls.seed = { ...seed };
+  restoreControls();
+}
+function restoreControls() {
+  state.controls.values = { ...DEFAULTS, ...state.controls.seed };
+  state.controls.unavailable = /* @__PURE__ */ new Set();
+  state.controls.lastUsage = null;
+  state.controls.writes = [];
+  state.controls.refusal = null;
+  resetControlsClientCache();
+}
+function clearControls() {
+  restoreControls();
+}
+function currentControlsBody() {
+  const controls = {};
+  for (const [key, value] of Object.entries(state.controls.values)) {
+    controls[key] = state.controls.unavailable.has(key) ? { ok: false, reason: "unavailable (simulated)" } : { ok: true, value };
+  }
+  return controls;
+}
+function refusalResponse(refusal) {
+  return json({ error: refusal }, REFUSAL_STATUS[refusal.code]);
+}
+function handleSync(body) {
+  const usage = body.usage;
+  if (typeof usage === "object" && usage !== null) {
+    const locations = usage.locations;
+    state.controls.lastUsage = typeof locations === "number" && Number.isInteger(locations) && locations >= 0 ? { locations } : {};
+  }
+  return json({ controls: currentControlsBody() });
+}
+async function handleWrite(request, key) {
+  const { CONTROLS, isWritableControl } = await loadControls();
+  if (!isWritableControl(key)) {
+    return refusalResponse({
+      code: "NOT_WRITABLE",
+      message: `${key} cannot be changed from the app`
+    });
+  }
+  const userToken = request.headers.get(USER_TOKEN_HEADER);
+  if (!userToken) {
+    return refusalResponse({
+      code: "UNAUTHENTICATED",
+      message: "A signed-in person is required (X-Stardeck-User-Token)"
+    });
+  }
+  const body = await readJsonBody(request);
+  const parsed = CONTROLS[key].schema.safeParse(body.value);
+  if (!parsed.success) {
+    return refusalResponse({
+      code: "INVALID_VALUE",
+      message: parsed.error.issues[0]?.message ?? "Invalid value"
+    });
+  }
+  const refusal = state.controls.refusal;
+  if (refusal) {
+    state.controls.refusal = null;
+    return refusalResponse(refusal);
+  }
+  state.controls.values[key] = parsed.data;
+  state.controls.unavailable.delete(key);
+  state.controls.writes.push({ key, value: parsed.data, userToken });
+  return json({ controls: currentControlsBody() });
+}
+var CONTROLS_PATH = /^\/api\/deployments\/[^/]+\/controls(?:\/([^/]+))?$/;
+async function handleControlsRequest(request, url) {
+  const match = url.pathname.match(CONTROLS_PATH);
+  const key = match?.[1] ? decodeURIComponent(match[1]) : null;
+  if (!key && request.method === "POST") {
+    return handleSync(await readJsonBody(request));
+  }
+  if (key && request.method === "PUT") {
+    return handleWrite(request, key);
+  }
+  return json(
+    {
+      error: { code: "UNAVAILABLE", message: `No simulator for ${request.method} ${url.pathname}` }
+    },
+    404
+  );
+}
+function createControls() {
+  return {
+    set(key, value) {
+      state.controls.values[key] = value;
+      state.controls.unavailable.delete(key);
+      resetControlsClientCache();
+    },
+    setUnavailable(key) {
+      state.controls.unavailable.add(key);
+      resetControlsClientCache();
+    },
+    lastUsage() {
+      return state.controls.lastUsage;
+    },
+    writes() {
+      return state.controls.writes;
+    },
+    refuseNextWrite(refusal) {
+      state.controls.refusal = refusal;
+    },
+    clear: restoreControls
+  };
+}
+
 // src/simulator/schedules.ts
 async function handleScheduleWake(request, scheduleKey) {
   if (request.method !== "POST") return failure(`Method ${request.method} not allowed`, 405);
@@ -4176,8 +4897,10 @@ function requiresDeploymentHmac(request, url) {
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStarlens = url.pathname === "/api/starlens/extract";
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
-  return !!(isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const controlsMatch = url.pathname.match(CONTROLS_PATH2);
+  return !!(controlsMatch || isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
+var CONTROLS_PATH2 = /^\/api\/deployments\/[^/]+\/controls(\/[^/]+)?$/;
 var SCHEDULE_WAKE_PATH = /^\/api\/deployments\/[^/]+\/schedules\/([^/]+)\/wake$/;
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -4245,6 +4968,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (CONTROLS_PATH2.test(url.pathname)) {
+    return handleControlsRequest(request, url);
+  }
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
   if (scheduleWakeMatch) {
     return handleScheduleWake(request, decodeURIComponent(scheduleWakeMatch[1]));
@@ -4273,7 +4999,7 @@ async function handleSimulatedRequest(request, url) {
     }
   }
   return failure(
-    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
+    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, app controls sync/write, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
     404
   );
 }
@@ -4422,6 +5148,7 @@ async function createTestApp(options = {}) {
   const initialLiffId = options.liffId ?? null;
   state.liffId = initialLiffId;
   installFetchRouter();
+  initControls(options.controls);
   const schemaSql = loadSchemaSql(options) ?? "";
   const db = await bootWithSchema(schemaSql);
   state.db = db;
@@ -4453,6 +5180,7 @@ async function createTestApp(options = {}) {
   const edge = createEdge();
   const starlens = createStarlens();
   const schedules = createSchedules();
+  const controls = createControls();
   const app = {
     db,
     inbox,
@@ -4463,6 +5191,7 @@ async function createTestApp(options = {}) {
     edge,
     starlens,
     schedules,
+    controls,
     async query(sql, params = []) {
       const result = await db.query(sql, params);
       return result.rows;
@@ -4512,6 +5241,7 @@ async function createTestApp(options = {}) {
       edge.clear();
       starlens.clear();
       schedules.clear();
+      clearControls();
     },
     async close() {
       state.db = null;
@@ -4528,6 +5258,7 @@ async function createTestApp(options = {}) {
       edge.clear();
       starlens.clear();
       schedules.clear();
+      clearControls();
       uninstallFetchRouter();
       await db.close();
     }