@crvouga/mockingbird-service-flex 3.10.0 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @crvouga/mockingbird-service-flex
 
+## 4.0.1 (2026-10-29)
+
+### Fixes and improvements
+
+- send checkout.session.refunded on a refund, as Flex does ([607eb28](https://github.com/crvouga/mockingbird/commit/607eb289587b2096fa5d9de447ccbeb03ea72563))
+
+## 4.0.0 (2026-10-29)
+
+### ⚠️ Breaking changes
+
+- nest webhook objects under their resource key and send refunds as Flex does ([e460af6](https://github.com/crvouga/mockingbird/commit/e460af601280becdf8bd7c4f16dfada2cf181545))
+
 ## 3.10.0 (2026-10-24)
 
 ### Features
@@ -7,10 +19,6 @@
 - add buffered SQL durability ([288bdcc](https://github.com/crvouga/mockingbird/commit/288bdcca84582787a54c4fdf9e803db9aac0b8d7))
 - add efficient browser durability ([a8be579](https://github.com/crvouga/mockingbird/commit/a8be5799a883ddf6f731208e06f399410de4661a))
 
-### Dependencies
-
-- `@crvouga/mockingbird-service-sqlite`
-
 ## 3.9.0 (2026-10-21)
 
 ### Features

package/README.md

@@ -140,10 +140,14 @@ overrides the origin.
 
 Svix-signed (`svix-id`, `svix-timestamp` = wall clock, `svix-signature: v1,<base64
 HMAC-SHA256(key, "<id>.<ts>.<body>")>`, key = base64-decoded secret after `fwhsec_`/`whsec_`).
-Body: `{event: {event_id, event_type, object, event_dt, test_mode, created_at}}`.
-Checkout events carry the session (so `object.checkout_session_id`), payment-intent events the
-intent plus `checkout_session_id`, refund events `checkout_session` and `payment_intent`, and
-`product.updated` the product (`object.product_id`).
+Body: `{event: {event_id, event_type, object, event_dt, test_mode, created_at}}`. As in Flex's
+OpenAPI (`EventObject`) and production deliveries, `object` holds one key named for the
+resource: checkout events `{checkout_session}` (so `object.checkout_session.checkout_session_id`),
+payment-intent events `{payment_intent}`, `charge.*` events `{charge}` (its intent is
+`charge.payment_intent`), `refund.*` and `charge.refund.updated` events `{refund}` (its intent is
+`refund.payment_intent_id`), `customer.subscription.*` `{subscription}` and `product.updated`
+`{product}`. Payment-intent, charge and refund objects name no checkout session: a receiver
+finds the payment through the payment intent.
 
 | Event | When |
 | --- | --- |
@@ -152,10 +156,15 @@ intent plus `checkout_session_id`, refund events `checkout_session` and `payment
 | `checkout.session.async_payment_succeeded` | settling a session whose intent was `processing` |
 | `checkout.session.async_payment_failed` | a decline (page, admin, off-session) |
 | `checkout.session.expired` | `…/expire`, or `expires_at` passing on the emulator clock (default 24 h) |
-| `refund.created`, `charge.refunded`, `checkout.session.refunded`, `refund.updated`, `charge.refund.updated` | each refund |
+| `checkout.session.refunded` (the session, with every refund in `refunds`), then `refund.created` (twice), `charge.refunded`, `refund.updated`, `charge.refund.updated` | each refund, through the API or the dashboard (`POST /__admin/sessions/:id/refund`). The refund and charge events follow the order production delivers a dashboard refund; each refund's `items` name its payment intent |
 | `product.updated` | `PATCH /v1/products/{id}` and `PUT /__admin/products/:id` |
 | `checkout_session.completed`, `checkout_session.expired` | the aliases, with `PUT /__admin/settings {"eventNaming": "underscored"}` |
 
+An endpoint receives only the event types it subscribes to, as in Flex's dashboard: pass
+`webhooks: {events: [...]}` (default: every type) or `PUT /__admin/webhook-endpoints`. Subscribe
+to what your production endpoint subscribes to, so a test cannot pass on an event production
+never receives.
+
 `POST /__admin/events {type, session | product}` emits any type on demand. Non-2xx answers are
 retried (immediately, 5 s, 5 min, 30 min, 2 h); `GET /__admin/webhooks`, `…/events`,
 `POST /__admin/webhooks/flush`, `…/:id/replay`, `PUT /__admin/webhook-endpoints` as usual.
@@ -168,6 +177,7 @@ retried (immediately, 5 s, 5 min, 30 min, 2 h); `GET /__admin/webhooks`, `…/ev
 | `POST /__admin/sessions/:id/complete` | `{card?}`: settle as if paid (HSA card unless `card` is `4242…`). |
 | `POST /__admin/sessions/:id/decline` | Payment intent → `requires_payment_method`. |
 | `POST /__admin/sessions/:id/expire` | Session → `expired`. |
+| `POST /__admin/sessions/:id/refund` | `{amount?}`: a refund made in Flex's dashboard (full by default); emits the refund events. 409 when unpaid, 400 over the unrefunded amount. |
 | `POST /__admin/sessions/:id/require_action` | `{next_action_type?}`: `collect_letter_of_medical_necessity` (default), `provide_second_payment_method`, `provide_alternative_payment_method`, `payment_failed`. |
 | `PUT /__admin/sessions/:id/payment-intent` | `{status, amount_received?}`: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `canceled`. |
 | `GET /__admin/sessions`, `GET /__admin/sessions/:id` | The namespace's sessions. |
@@ -221,11 +231,12 @@ so product names are synthesised.
 
 | Export | Kind | Description |
 | --- | --- | --- |
-| `FlexAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `settle(id)`, `decline(id)`, `expire(id)`, `requireAction(id, type)`, `setPaymentIntent(id, patch)`, `applyRefund(id, amount)`, `putProduct(product)`, `emitFor(type, target)`, `tick()`, `sessions()`, `subscriptions()`, `present(session, view)`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `products`, `settings`, `onEvent`. |
-| `createRuntime` | function | The emulator with the full service contract. Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `products`, `settings`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`. |
+| `FlexAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `settle(id)`, `decline(id)`, `expire(id)`, `requireAction(id, type)`, `setPaymentIntent(id, patch)`, `applyRefund(id, amount)`, `dashboardRefund(id, amount?)`, `putProduct(product)`, `emitFor(type, target)`, `tick()`, `sessions()`, `subscriptions()`, `present(session, view)`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `products`, `settings`, `onEvent`. |
+| `createRuntime` | function | The emulator with the full service contract. Options: `webhooks: {url, secret, events?, retryDelaysMs?, fetch?}`, `products`, `settings`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`. |
 | `FLEX_PRESETS` | object | Every named fault preset. |
 | `FLEX_NAMESPACE` | string | The service name, `"flex"`. |
 | `FLEX_EVENT_TYPES` | array | Every webhook event type, aliases included. |
+| `eventObjectKey` | function | The key an event type's `object` is nested under (`refund.created` → `refund`, `charge.refund.updated` → `refund`). |
 | `keyMode` | function | `"test"` for `fsk_test_…`, `"live"` for `fsk_…`, otherwise `undefined`. |
 | `isNextActionType` | function | Whether a string is a next-action type. |
 | `CARDS`, `classifyCard`, `substituteSessionId` | values | The hosted page's test cards, its card classifier, and the `{CHECKOUT_SESSION_ID}` substitution. |

package/dist/{chunk-NKBXNJ5B.js → chunk-AGWRBLUO.js}

@@ -4097,7 +4097,7 @@ var stateAdminRoutes = (routes) => {
 };
 
 // ../core/dist/version.js
-var PACKAGE_VERSION = true ? "3.10.0" : UNRELEASED_VERSION;
+var PACKAGE_VERSION = true ? "4.0.1" : UNRELEASED_VERSION;
 
 // ../core/dist/signing.js
 var encoder = new TextEncoder();
@@ -7295,6 +7295,17 @@ var adminRoutes = (runtime) => {
         `session ${params.id}`
       );
     },
+    "POST /sessions/:id/refund": ({ namespace, params, body }) => {
+      if (body !== void 0 && body !== null && !isRecord5(body)) {
+        return adminError4(400, 'expected {"amount"?: <cents>}');
+      }
+      const amount = isRecord5(body) ? body.amount : void 0;
+      if (amount !== void 0 && typeof amount !== "number") {
+        return adminError4(400, "amount: integer cents");
+      }
+      const outcome = runtime.instance(namespace).dashboardRefund(params.id, amount);
+      return "session" in outcome ? json5(200, outcome.session) : adminError4(outcome.status, outcome.message);
+    },
     "PUT /sessions/:id/payment-intent": ({ namespace, params, body }) => {
       if (!isRecord5(body) || !PAYMENT_INTENT_STATUSES.includes(String(body.status))) {
         return adminError4(400, `status: ${PAYMENT_INTENT_STATUSES.join(" | ")}`);
@@ -7435,6 +7446,17 @@ var FLEX_EVENT_TYPES = [
   "charge.refunded",
   "charge.refund.updated"
 ];
+var eventObjectKey = (type) => {
+  const prefixes2 = [
+    ["checkout.session.", "checkout_session"],
+    ["checkout_session.", "checkout_session"],
+    ["charge.refund.", "refund"],
+    ["charge.dispute.", "dispute"],
+    ["customer.subscription.", "subscription"]
+  ];
+  const match = prefixes2.find(([prefix]) => type.startsWith(prefix));
+  return match ? match[1] : type.split(".")[0];
+};
 var keyMode = (key) => {
   if (!key) return void 0;
   if (/^fsk_test_[A-Za-z0-9_-]+$/.test(key)) return "test";
@@ -7837,10 +7859,12 @@ var FlexAPI = class {
     const { expiresAtMs: _expires, url, ...rest } = session;
     const customer = session.customer ? view.expandCustomer ? this.state.customers.get(session.customer) ?? session.customer : session.customer : null;
     const intent = session.payment_intent ? view.expandPaymentIntent ? this.state.paymentIntents.get(session.payment_intent) ?? session.payment_intent : session.payment_intent : null;
+    const refunds = this.state.refunds.list().map((row) => row.value).filter((refund) => refund.checkout_session === session.checkout_session_id).map((refund) => this.presentRefund(refund, session.test_mode));
     const out = {
       ...rest,
       customer,
       payment_intent: intent,
+      refunds,
       redirect_url: url,
       url
     };
@@ -7910,7 +7934,13 @@ var FlexAPI = class {
     this.applyRefund(id, amount);
     return this.sessionResponse(context, id);
   }
-  /** Refund part or all of a paid session, emitting the refund events. */
+  /**
+   * Refund part or all of a paid session, emitting the refund events Flex sends:
+   * `checkout.session.refunded` (seen in test mode, carrying the session and its refunds),
+   * then, in the order production delivers a dashboard refund, `refund.created` twice,
+   * `charge.refunded`, `refund.updated` and `charge.refund.updated`. An endpoint receives only
+   * the types it subscribes to.
+   */
   applyRefund(id, amount) {
     const session = this.state.sessions.get(id);
     if (!session) return void 0;
@@ -7925,21 +7955,86 @@ var FlexAPI = class {
       created_at: this.iso()
     };
     this.state.refunds.insert(refund.refund_id, refund);
-    const charge = {
-      charge_id: `fch_${refund.refund_id.slice(4)}`,
-      checkout_session_id: id,
-      payment_intent: session.payment_intent,
-      amount: session.amount_received,
-      amount_refunded: next.amount_refunded,
-      refunded: next.amount_refunded >= (session.amount_received ?? 0)
-    };
-    this.emit("refund.created", { ...refund, status: "pending" }, session.test_mode);
-    this.emit("charge.refunded", charge, session.test_mode);
+    const refundObject = this.presentRefund(refund, session.test_mode);
+    const chargeObject = this.presentCharge(next, refund.refund_id);
     this.emitSession("checkout.session.refunded", id);
-    this.emit("refund.updated", refund, session.test_mode);
-    this.emit("charge.refund.updated", { ...refund, charge: charge.charge_id }, session.test_mode);
+    this.emit("refund.created", refundObject, session.test_mode);
+    this.emit("refund.created", refundObject, session.test_mode);
+    this.emit("charge.refunded", chargeObject, session.test_mode);
+    this.emit("refund.updated", refundObject, session.test_mode);
+    this.emit("charge.refund.updated", refundObject, session.test_mode);
     return this.state.sessions.get(id);
   }
+  /** Refund a paid session from Flex's dashboard (`POST /__admin/sessions/:id/refund`). */
+  dashboardRefund(id, amount) {
+    const session = this.state.sessions.get(id);
+    if (!session) return { status: 404, message: `no session ${id}` };
+    const received = session.amount_received ?? 0;
+    if (session.status !== "complete" || received <= 0) {
+      return { status: 409, message: `session ${id} has no payment to refund` };
+    }
+    const remaining = received - session.amount_refunded;
+    const value = amount ?? remaining;
+    if (!Number.isInteger(value) || value <= 0 || value > remaining) {
+      return { status: 400, message: `amount must be between 1 and ${remaining}` };
+    }
+    return { session: this.applyRefund(id, value) };
+  }
+  presentRefund(refund, testMode) {
+    const intent = refund.payment_intent ? this.state.paymentIntents.get(refund.payment_intent) : void 0;
+    return {
+      refund_id: refund.refund_id,
+      amount: refund.amount,
+      status: refund.status,
+      payment_intent_id: refund.payment_intent,
+      items: [
+        {
+          payment_intent: refund.payment_intent,
+          amount_refunded: refund.amount,
+          payment_method_id: intent?.payment_method ?? null,
+          reference_id: null,
+          reference_type: null,
+          reference_status: null
+        }
+      ],
+      metadata: null,
+      reason: null,
+      reference_id: null,
+      reference_type: null,
+      reference_status: null,
+      balance_transaction: null,
+      failure_balance_transaction: null,
+      test_mode: testMode,
+      created_at: refund.created_at
+    };
+  }
+  presentCharge(session, seed) {
+    const intent = session.payment_intent ? this.state.paymentIntents.get(session.payment_intent) : void 0;
+    const received = session.amount_received ?? 0;
+    return {
+      charge_id: `fch_${seed.slice(4)}`,
+      payment_intent: session.payment_intent,
+      amount: received,
+      amount_captured: received,
+      amount_refunded: session.amount_refunded,
+      refunded: session.amount_refunded >= received,
+      paid: true,
+      captured: true,
+      status: "succeeded",
+      customer: session.customer,
+      payment_method_id: intent?.payment_method ?? null,
+      invoice: null,
+      refunds: null,
+      disputed: false,
+      failure_message: null,
+      balance_transaction: null,
+      failure_balance_transaction: null,
+      application_fee_amount: null,
+      transfer_group: null,
+      test_mode: session.test_mode,
+      created_at: intent?.created_at ?? this.iso()
+    };
+  }
   // --- customers and setup intents ---------------------------------------------------------
   createCustomer(context) {
     const problem = this.validate(context);
@@ -8052,11 +8147,7 @@ var FlexAPI = class {
     const intent = { ...this.paymentIntentFor(session), ...patch };
     this.state.paymentIntents.update(intent.payment_intent_id, intent);
     if (patch.status === "succeeded") {
-      this.emit(
-        "payment_intent.succeeded",
-        { ...intent, checkout_session_id: id },
-        session.test_mode
-      );
+      this.emit("payment_intent.succeeded", { ...intent }, session.test_mode);
     }
     return intent;
   }
@@ -8183,8 +8274,40 @@ var FlexAPI = class {
       const product = this.state.products.get(target.productId);
       return product ? this.emit(type, { ...product }, product.test_mode) : void 0;
     }
-    if (target.sessionId) return this.emitSession(type, target.sessionId);
-    return void 0;
+    if (!target.sessionId) return void 0;
+    const session = this.state.sessions.get(target.sessionId);
+    if (!session) return void 0;
+    const key = eventObjectKey(type);
+    const existingIntent = session.payment_intent ? this.state.paymentIntents.get(session.payment_intent) : void 0;
+    if (key === "payment_intent") {
+      const intent = existingIntent ?? {
+        payment_intent_id: `fpi_${session.checkout_session_id.slice(4)}`,
+        amount: session.amount_total,
+        amount_received: null,
+        customer: session.customer,
+        payment_method: null,
+        status: "requires_payment_method",
+        created_at: session.created_at
+      };
+      return this.emit(type, { ...intent }, session.test_mode);
+    }
+    if (key === "refund" || key === "charge") {
+      const refund = this.state.refunds.list().map((row) => row.value).filter((row) => row.checkout_session === session.checkout_session_id).at(-1) ?? {
+        refund_id: this.state.nextId("fre_"),
+        checkout_session: session.checkout_session_id,
+        payment_intent: session.payment_intent,
+        amount: session.amount_received ?? session.amount_total,
+        status: "succeeded",
+        created_at: this.iso()
+      };
+      const current = this.state.sessions.get(session.checkout_session_id);
+      return this.emit(
+        type,
+        key === "refund" ? this.presentRefund(refund, session.test_mode) : this.presentCharge(current, refund.refund_id),
+        session.test_mode
+      );
+    }
+    return this.emitSession(type, target.sessionId);
   }
   emitSession(type, id) {
     const session = this.state.sessions.get(id);
@@ -8199,7 +8322,7 @@ var FlexAPI = class {
     const event = {
       event_id: this.state.nextId("fevt_"),
       event_type: type,
-      object,
+      object: { [eventObjectKey(type)]: object },
       event_dt: Math.floor(this.now() / 1e3),
       test_mode: testMode,
       created_at: this.iso()
@@ -8327,9 +8450,10 @@ export {
   createRuntime2 as createRuntime,
   FLEX_NAMESPACE,
   FLEX_EVENT_TYPES,
+  eventObjectKey,
   keyMode,
   periodEnd,
   FlexAPI,
   isNextActionType
 };
-//# sourceMappingURL=chunk-NKBXNJ5B.js.map
+//# sourceMappingURL=chunk-AGWRBLUO.js.map