@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/subscription-dodo/verify-webhook.ts

@@ -0,0 +1,262 @@
+// Dodo Payments webhook: Standard Webhooks signature verification plus mapping
+// of Dodo's event envelope onto the foundation's normalized events.
+//
+// Verification always runs against the raw body string; re-serialized JSON
+// would change whitespace and break the HMAC. The signature check happens
+// before any parsing, so no path bypasses it.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  BillingEventKinds,
+  type PaymentEvent,
+  parseProviderConsentId,
+  type SubscriptionEvent,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { DODO_PROVIDER_NAME } from "./constants.ts";
+import type { DodoWebhookRuntime } from "./runtime.ts";
+
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+
+const SECRET_PREFIX = "whsec_";
+const SIGNATURE_VERSION = "v1";
+const TIMESTAMP_PATTERN = /^\d+$/;
+
+export type StandardWebhookHeaders = Readonly<Record<string, string>>;
+
+function signatureFor(secretKey: Buffer, signedContent: string): Buffer {
+  return createHmac("sha256", secretKey).update(signedContent).digest();
+}
+
+function matchesAnyV1Signature(header: string, expected: Buffer): boolean {
+  return header.split(" ").some((entry) => {
+    const [version, encoded] = entry.split(",");
+    if (version !== SIGNATURE_VERSION || !encoded) return false;
+    const candidate = Buffer.from(encoded, "base64");
+    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+  });
+}
+
+/** Throws unless the Standard Webhooks signature over `rawBody` is valid and
+ *  the timestamp is within the tolerance in both directions. */
+export function verifyStandardWebhook(
+  rawBody: string,
+  headers: StandardWebhookHeaders,
+  secret: string,
+  nowSeconds: number,
+): void {
+  const id = headers["webhook-id"];
+  const timestamp = headers["webhook-timestamp"];
+  const signatureHeader = headers["webhook-signature"];
+  if (!id || !timestamp || !signatureHeader) {
+    throw new Error(
+      "subscription-dodo: webhook-id, webhook-timestamp or webhook-signature missing",
+    );
+  }
+  if (!TIMESTAMP_PATTERN.test(timestamp)) {
+    throw new Error("subscription-dodo: webhook-timestamp is not a Unix timestamp in seconds");
+  }
+  if (Math.abs(nowSeconds - Number(timestamp)) > WEBHOOK_TOLERANCE_SECONDS) {
+    throw new Error("subscription-dodo: webhook timestamp outside the tolerance window");
+  }
+  const secretKey = Buffer.from(
+    secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret,
+    "base64",
+  );
+  const expected = signatureFor(secretKey, `${id}.${timestamp}.${rawBody}`);
+  if (!matchesAnyV1Signature(signatureHeader, expected)) {
+    throw new Error("subscription-dodo: webhook signature verify failed");
+  }
+}
+
+// =============================================================================
+// Event mapping
+// =============================================================================
+
+const DODO_SUBSCRIPTION_EVENT_TYPES: Readonly<Record<string, SubscriptionEventType>> = {
+  "subscription.active": SubscriptionEventTypes.created,
+  "subscription.updated": SubscriptionEventTypes.updated,
+  "subscription.plan_changed": SubscriptionEventTypes.updated,
+  "subscription.paused": SubscriptionEventTypes.updated,
+  "subscription.unpaused": SubscriptionEventTypes.updated,
+  "subscription.update_payment_method": SubscriptionEventTypes.updated,
+  "subscription.renewed": SubscriptionEventTypes.invoicePaid,
+  "subscription.past_due": SubscriptionEventTypes.invoicePaymentFailed,
+  "subscription.on_hold": SubscriptionEventTypes.invoicePaymentFailed,
+  "subscription.cancelled": SubscriptionEventTypes.canceled,
+  "subscription.expired": SubscriptionEventTypes.canceled,
+  "subscription.failed": SubscriptionEventTypes.canceled,
+};
+
+const DODO_SUBSCRIPTION_STATUSES: Readonly<Record<string, SubscriptionStatus>> = {
+  pending: SubscriptionStatuses.incomplete,
+  active: SubscriptionStatuses.active,
+  on_hold: SubscriptionStatuses.pastDue,
+  past_due: SubscriptionStatuses.pastDue,
+  paused: SubscriptionStatuses.pastDue,
+  cancelled: SubscriptionStatuses.canceled,
+  failed: SubscriptionStatuses.canceled,
+  expired: SubscriptionStatuses.canceled,
+};
+
+const PAYMENT_SUCCEEDED = "payment.succeeded";
+
+const metadataSchema = z.record(z.string(), z.unknown()).nullish();
+const customerSchema = z.object({ customer_id: z.string().min(1) });
+
+const envelopeSchema = z.object({
+  type: z.string(),
+  timestamp: z.iso.datetime({ offset: true }),
+  data: z.unknown(),
+});
+
+export const dodoSubscriptionSchema = z.object({
+  subscription_id: z.string().min(1),
+  product_id: z.string().min(1),
+  status: z.string(),
+  customer: customerSchema,
+  metadata: metadataSchema,
+  next_billing_date: z.iso.datetime({ offset: true }),
+  cancel_at_next_billing_date: z.boolean().nullish(),
+});
+export type DodoSubscription = z.infer<typeof dodoSubscriptionSchema>;
+
+const dodoPaymentSchema = z.object({
+  subscription_id: z.string().nullish(),
+  checkout_session_id: z.string().nullish(),
+  customer: customerSchema,
+  metadata: metadataSchema,
+  product_cart: z.array(z.object({ product_id: z.string().min(1) })).nullish(),
+});
+
+function metadataString(metadata: DodoSubscription["metadata"], key: string): string | undefined {
+  const value = metadata?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export type MappedDodoSubscriptionState = {
+  readonly status: SubscriptionStatus;
+  readonly tier: string;
+  readonly currentPeriodEnd: string;
+  readonly cancelAt: string | null;
+};
+
+/** Shared by the webhook and retrieveSubscription so both map Dodo state
+ *  identically. Null when the status is unknown or the product is not in
+ *  `priceToTier` (SubscriptionEvent.tier is required). */
+export function mapDodoSubscriptionState(
+  sub: DodoSubscription,
+  priceToTier: Readonly<Record<string, string>>,
+): MappedDodoSubscriptionState | null {
+  const status = DODO_SUBSCRIPTION_STATUSES[sub.status];
+  const tier = priceToTier[sub.product_id];
+  if (!status || !tier) return null;
+  return {
+    status,
+    tier,
+    currentPeriodEnd: sub.next_billing_date,
+    cancelAt: sub.cancel_at_next_billing_date === true ? sub.next_billing_date : null,
+  };
+}
+
+export type DodoWebhookOptions = {
+  readonly priceToTier: Readonly<Record<string, string>>;
+  /** Test seam: Unix seconds. Defaults to the wall clock. */
+  readonly nowSeconds?: () => number;
+};
+
+function currentUnixSeconds(): number {
+  return Math.floor(Temporal.Now.instant().epochMilliseconds / 1000);
+}
+
+function parsePaymentEvent(providerEventId: string, data: unknown): PaymentEvent | null {
+  const parsed = dodoPaymentSchema.safeParse(data);
+  if (!parsed.success) return null;
+  const payment = parsed.data;
+  // A subscription's own payments are covered by its subscription.* events.
+  if (payment.subscription_id) return null;
+  const tenantId = metadataString(payment.metadata, "tenantId");
+  const priceId = payment.product_cart?.[0]?.product_id;
+  if (!tenantId || !priceId) return null;
+  const consentId = parseProviderConsentId(payment.metadata?.["consentId"]);
+  return {
+    kind: BillingEventKinds.payment,
+    providerEventId,
+    providerName: DODO_PROVIDER_NAME,
+    tenantId,
+    ...(consentId !== undefined && { consentId }),
+    ...(payment.checkout_session_id && { providerCheckoutId: payment.checkout_session_id }),
+    providerCustomerId: payment.customer.customer_id,
+    priceId,
+  };
+}
+
+function parseSubscriptionEvent(
+  providerEventId: string,
+  type: SubscriptionEventType,
+  providerEventAt: string,
+  data: unknown,
+  priceToTier: Readonly<Record<string, string>>,
+): SubscriptionEvent | null {
+  const parsed = dodoSubscriptionSchema.safeParse(data);
+  if (!parsed.success) return null;
+  const sub = parsed.data;
+  const tenantId = metadataString(sub.metadata, "tenantId");
+  const state = mapDodoSubscriptionState(sub, priceToTier);
+  if (!tenantId || !state) return null;
+  const consentId = parseProviderConsentId(sub.metadata?.["consentId"]);
+  return {
+    providerEventId,
+    providerName: DODO_PROVIDER_NAME,
+    type,
+    tenantId,
+    ...(consentId !== undefined && { consentId }),
+    providerCustomerId: sub.customer.customer_id,
+    providerSubscriptionId: sub.subscription_id,
+    providerEventAt,
+    ...state,
+  };
+}
+
+export function verifyAndParseDodoWebhook(
+  runtime: DodoWebhookRuntime,
+  options: DodoWebhookOptions,
+): (
+  rawBody: string,
+  headers: Record<string, string>,
+  systemSecrets?: SecretsContext,
+) => Promise<SubscriptionEvent | PaymentEvent | null> {
+  const nowSeconds = options.nowSeconds ?? currentUnixSeconds;
+  return async (rawBody, headers, systemSecrets) => {
+    const secret = await runtime.resolveWebhookSecret(systemSecrets);
+    verifyStandardWebhook(rawBody, headers, secret, nowSeconds());
+
+    // Past verification the body is trusted to be Dodo's; a malformed shape is
+    // schema drift, so it is dropped (200 ignored) instead of answered with a 401.
+    const envelope = envelopeSchema.safeParse(
+      parseJsonOrThrow<unknown>(rawBody, "subscription-dodo webhook body"),
+    );
+    // verifyStandardWebhook has checked webhook-id is present.
+    const providerEventId = headers["webhook-id"];
+    if (!envelope.success || !providerEventId) return null;
+
+    const { type, timestamp, data } = envelope.data;
+    if (type === PAYMENT_SUCCEEDED) return parsePaymentEvent(providerEventId, data);
+    const normalizedType = DODO_SUBSCRIPTION_EVENT_TYPES[type];
+    if (!normalizedType) return null;
+    return parseSubscriptionEvent(
+      providerEventId,
+      normalizedType,
+      timestamp,
+      data,
+      options.priceToTier,
+    );
+  };
+}

package/packages/bundled-features/src/subscription-mollie/constants.ts

@@ -1,33 +1,31 @@
 // Feature name
 export const SUBSCRIPTION_MOLLIE_FEATURE = "subscription-mollie" as const;
 
-// entityName under den der Plugin gegen "subscriptionProvider"
-// registriert. Matcht den path-segment in der webhook-URL
+// Entity name under which the plugin registers against
+// "subscriptionProvider". Matches the path segment in the webhook URL
 // `/api/subscription/webhook/mollie`.
 export const MOLLIE_PROVIDER_NAME = "mollie" as const;
 
 // =============================================================================
-// Mollie-Webhook-Pattern (anders als Stripe!)
+// Mollie webhook pattern (unlike Stripe)
 // =============================================================================
 //
-// Mollie sendet bei JEDEM event nur die ID im body (form-urlencoded
-// oder JSON). Plugin muss IMMER lazy-fetchen via Mollie-API:
-//   - `id=tr_xxx`  → payment-id, fetch payment + subscription
-//   - `id=sub_xxx` → subscription-id, fetch subscription direkt
+// Mollie sends only the ID in the body for EVERY event (form-urlencoded
+// or JSON). The plugin must ALWAYS fetch lazily via the Mollie API:
+//   - `id=tr_xxx`  → payment ID, fetch payment + subscription
+//   - `id=sub_xxx` → subscription ID, fetch subscription directly
 //
-// **Keine native HMAC-sig-verify** in Mollie-SDK 4.5.0. Mollie's
-// Sicherheits-Modell stützt sich auf nicht-guessable IDs (~10^25
-// brute-force-space) + API-Lookup-Validation (garbage-id → 401 von
-// Mollie-API). Plus: App-Builder kann zusätzlich einen URL-Token-
-// Wrapper vor die Foundation-route schalten (eigener extraRoute der
-// einen secret-token im URL-Pfad verifiziert + dann an die Foundation
-// weiterreicht).
+// **No native HMAC signature verification** in Mollie SDK 4.5.0. Mollie's
+// security model relies on non-guessable IDs (~10^25 brute-force space)
+// plus API lookup validation (garbage ID → 401 from the Mollie API). In
+// addition, the app builder can place a URL-token wrapper before the
+// foundation route (a custom extraRoute that verifies a secret token in
+// the URL path and then forwards to the foundation).
 //
-// **Event-Type-Mapping** ist heuristisch — Mollie hat keine explicit-
-// typed events:
+// **Event type mapping** is heuristic—Mollie has no explicitly typed events:
 //   - sub_xxx + status=canceled/completed     → SubscriptionEventTypes.canceled
 //   - sub_xxx + status=active/pending         → SubscriptionEventTypes.updated
 //   - tr_xxx + sequenceType=first + paid      → SubscriptionEventTypes.created
 //   - tr_xxx + sequenceType=recurring + paid  → SubscriptionEventTypes.invoicePaid
 //   - tr_xxx + sequenceType=recurring + failed → SubscriptionEventTypes.invoicePaymentFailed
-//   - alles andere                            → null (foundation 200 ignored)
+//   - everything else                         → null (foundation 200 ignored)

package/packages/bundled-features/src/subscription-mollie/feature.ts

@@ -1,26 +1,26 @@
 // kumiko-feature-version: 1
 //
-// subscription-mollie — Mollie-Plugin für die subscription-foundation
-// Plugin-API (EU-Compliance-Story für DACH-Mid-Market).
+// subscription-mollie — Mollie plugin for subscription-foundation
+// plugin API (EU compliance for the DACH mid-market).
 //
-// **Factory-Pattern (analog subscription-stripe):** liest API-key beim
-// mount-time aus den factory-options (typisch process.env aus dem App-
-// Builder-bin/server.ts). Mollie hat KEIN webhook-secret — Mollie-SDK
-// 4.5.0 bietet keine native HMAC-sig-verify-API. Sicherheit kommt aus
-// nicht-guessable IDs + API-Validation; App-Builder kann optional
-// einen URL-Token-Wrapper davor schalten.
+// **Factory pattern (analogous to subscription-stripe):** reads the API key
+// at mount time from the factory options (typically process.env from the app
+// builder's bin/server.ts). Mollie has NO webhook secret — Mollie SDK
+// 4.5.0 provides no native HMAC signature verification API. Security comes
+// from non-guessable IDs + API validation; the app builder can optionally
+// add a URL-token wrapper in front.
 //
-// **Phase-5.3-Scope:**
+// **Scope:**
 //   - verifyAndParseWebhook ✓ (lazy-fetch payment + subscription via
-//     Mollie-API, heuristisches event-type-mapping)
-//   - createCheckoutSession ✓ (Mollie's mehrstufiger flow: customer
-//     anlegen + first-payment mit sequenceType="first" → redirectUrl)
-//   - createPortalSession ✗ (Mollie hat keinen Customer-Portal)
-//   - cancelSubscription ✗ (Mollie braucht customerId zusätzlich zur
-//     subId; Plugin-Contract reicht's nicht durch — App-Builder cancelt
-//     via Mollie-Dashboard oder custom-route)
+//     Mollie API, heuristic event-type mapping)
+//   - createCheckoutSession ✓ (Mollie's multistep flow: create customer
+//     + first payment with sequenceType="first" → redirectUrl)
+//   - createPortalSession ✗ (Mollie has no customer portal)
+//   - cancelSubscription ✗ (Mollie additionally requires customerId besides
+//     subId; the plugin contract does not pass it through — the app builder
+//     cancels via the Mollie dashboard or a custom route)
 //
-// **Beispiel-Verwendung in run-config.ts:**
+// **Example usage in run-config.ts:**
 //
 //   const features = [
 //     billingFoundationFeature,
@@ -62,29 +62,28 @@ export const subscriptionMollieEnvSchema = z.object({
 });
 
 export type SubscriptionMollieOptions = {
-  /** Mollie-API-key (`test_...` oder `live_...`). App-wide, beim Plugin-
-   *  mount aus process.env oder system-config. */
+  /** Mollie API key (`test_...` or `live_...`). App-wide, mounted from
+   *  process.env or system configuration. */
   readonly apiKey: string;
-  /** Foundation-webhook-URL die der App-Builder unter Mollie-Dashboard
-   *  als webhook eingetragen hat. Plugin reicht das beim payment-
-   *  create an Mollie weiter — Mollie sendet beim payment-event
-   *  webhooks an diese URL. Typisch:
+  /** Foundation webhook URL registered by the app builder in the Mollie
+   *  dashboard. The plugin passes it to Mollie when creating a payment;
+   *  Mollie sends payment-event webhooks to this URL. Typically:
    *  `https://app.example.com/api/subscription/webhook/mollie`. */
   readonly webhookUrl: string;
-  /** Price-to-tier-Map. Plugin liest die priceId aus dem subscription-
-   *  metadata (= `metadata.priceId` den der App-Builder beim
-   *  createCheckoutSession setzt) und mappt auf einen tier-name. */
+  /** Price-to-tier map. The plugin reads the priceId from the subscription
+   *  metadata (= `metadata.priceId` set by the app builder when calling
+   *  createCheckoutSession) and maps it to a tier name. */
   readonly priceToTier: Readonly<Record<string, string>>;
-  /** Mollie-Subscription-Setup pro priceId. Mollie hat keinen nativen
-   *  price-id-Konzept — App-Builder muss pro virtuellem priceId einen
-   *  amount/interval/description bereitstellen. */
+  /** Mollie subscription setup per priceId. Mollie has no native price-ID
+   *  concept, so the app builder must provide an amount/interval/description
+   *  for each virtual priceId. */
   readonly priceToConfig: Readonly<Record<string, MolliePriceConfig>>;
-  /** @internal Test-only injection-port: ersetzt den verify-webhook-
-   *  fetch-client durch eine Mock-instance. Production left undefined —
-   *  factory baut den Adapter aus `createMollieClient(apiKey)`. Wird
-   *  vom IT (mollie-foundation.integration.ts) genutzt damit der echte
-   *  factory-Code (drift-validation, plugin-registration) im Test-pfad
-   *  durchläuft, ohne dass Mollie-API-Calls passieren. */
+  /** @internal Test-only injection port: replaces the verify-webhook fetch
+   *  client with a mock instance. Production leaves this undefined; the
+   *  factory builds the adapter from `createMollieClient(apiKey)`. The
+   *  integration test (mollie-foundation.integration.ts) uses it so the real
+   *  factory code (drift validation, plugin registration) runs in the test
+   *  path without making Mollie API calls. */
   readonly _clientShapeForTests?: MollieClientShape;
 };
 
@@ -102,8 +101,8 @@ export function createSubscriptionMollieFeature(
     );
   }
 
-  // Drift-Guard: priceToTier + priceToConfig müssen identische Keys
-  // haben — sonst silent-null-returns aus verifyAndParseWebhook.
+  // Drift guard: priceToTier and priceToConfig must have identical keys;
+  // otherwise verifyAndParseWebhook silently returns null.
   const tierKeys = new Set(Object.keys(options.priceToTier));
   const configKeys = new Set(Object.keys(options.priceToConfig));
   const missingInConfig = [...tierKeys].filter((k) => !configKeys.has(k));
@@ -118,9 +117,9 @@ export function createSubscriptionMollieFeature(
 
   const client = createMollieClient({ apiKey: options.apiKey });
 
-  // Adapter um den Plugin's verify-fetch-client an den vollen Mollie-
-  // Client zu binden. Plugin-fetch-API ist minimal damit Tests ohne
-  // den vollen MollieClient mocken können.
+  // Adapter that binds the plugin's minimal fetch client to the full Mollie
+  // client. The minimal plugin fetch API lets tests mock it without mocking
+  // the full MollieClient.
   const fetchAdapter: MollieClientShape = options._clientShapeForTests ?? {
     payments: { get: (id: string) => client.payments.get(id) },
     customerSubscriptions: {
@@ -160,8 +159,8 @@ export function createSubscriptionMollieFeature(
     const plugin: SubscriptionProviderPlugin = {
       verifyAndParseWebhook: verifyAndParse,
       createCheckoutSession: checkoutSession,
-      // createPortalSession + cancelSubscription bewusst nicht — siehe
-      // plugin-methods.ts für Begründung.
+      // createPortalSession and cancelSubscription are intentionally omitted;
+      // see plugin-methods.ts for why.
       priceToTier: options.priceToTier,
     };
     r.useExtension("subscriptionProvider", MOLLIE_PROVIDER_NAME, plugin);

package/packages/bundled-features/src/subscription-mollie/index.ts

@@ -1,9 +1,9 @@
 // Public API of the subscription-mollie bundled-feature.
 //
-// **Internal-only** (NICHT im public-barrel — App-Builder nutzt das nie direkt):
-//   - verifyAndParseMollieWebhook (intern vom feature.ts factory aufgerufen)
+// **Internal-only** (not in the public barrel—the App Builder never uses it directly):
+//   - verifyAndParseMollieWebhook (called internally by the feature.ts factory)
 //   - mapMollieEventType / mapMollieStatus / extractMollieId (pure helpers,
-//     test-only — direct-import aus dem File wenn echt mal extern gebraucht)
+//     test-only—direct-import from the file if ever genuinely needed externally)
 
 export { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants.ts";
 export {

package/packages/bundled-features/src/subscription-mollie/plugin-methods.ts

@@ -1,17 +1,18 @@
-// Mollie-Plugin-Methoden für die POST-tenant-resolution-Phase:
-// createCheckoutSession (only). createPortalSession + cancelSubscription
-// nicht implementiert weil Mollie's API die Patterns nicht 1:1 bietet:
+// Mollie plugin methods for the POST-tenant-resolution phase:
+// createCheckoutSession only. createPortalSession and cancelSubscription
+// are not implemented because Mollie's API does not provide these patterns
+// 1:1:
 //
-// - **Portal:** Mollie hat keinen Customer-Portal — App-Builder UI muss
-//   das selbst rendern.
-// - **Cancel:** Mollie braucht (customerId, subId), Plugin-Contract
-//   reicht aber nur subId durch — App-Builder cancelt via Mollie-
-//   Dashboard oder eigener Route bis Foundation-Contract erweitert ist.
+// - **Portal:** Mollie has no customer portal, so the App Builder UI must
+//   render it itself.
+// - **Cancel:** Mollie requires (customerId, subId), but the plugin contract
+//   passes through only subId. The App Builder cancels through the Mollie
+//   dashboard or a custom route until the Foundation contract is extended.
 //
-// **Mollie-Checkout-Flow ist mehrstufig:** Customer anlegen → first-
-// payment mit sequenceType="first" (= Mandate-setup) → User bezahlt →
-// Mollie-webhook → verify-webhook erstellt die Mollie-Subscription
-// idempotent (siehe verify-webhook.ts ensureSubscriptionForMandate).
+// **The Mollie checkout flow has multiple steps:** create customer → first
+// payment with sequenceType="first" (= mandate setup) → user pays →
+// Mollie webhook → verify-webhook creates the Mollie subscription
+// idempotently (see verify-webhook.ts ensureSubscriptionForMandate).
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
@@ -22,8 +23,8 @@ export type MollieCheckoutOptions = Parameters<
   NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
 >[1];
 
-/** Mollie hat keinen nativen price-id-Konzept — App-Builder pflegt
- *  pro virtuellem priceId einen amount/interval/description. */
+/** Mollie has no native price ID concept; the App Builder maintains
+ *  an amount/interval/description for each virtual priceId. */
 export type MolliePriceConfig = {
   /** Mollie-format: 2-decimal string, z.B. `"9.99"`. */
   readonly amountValue: string;
@@ -67,8 +68,8 @@ export function createMollieCheckoutSession(
     // any mandate/subscription handling.
     const sequenceType = options.mode === "payment" ? SequenceType.oneoff : SequenceType.first;
 
-    // payments.create ist overloaded (Promise OR void mit callback);
-    // explicit cast auf Promise<Payment>-overload.
+    // payments.create is overloaded (Promise or void with a callback);
+    // explicitly cast to the Promise<Payment> overload.
     const payment = (await (client.payments.create({
       amount: { currency: priceCfg.amountCurrency, value: priceCfg.amountValue },
       description: priceCfg.description,