@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/subscription-dodo/plugin-methods.js

@@ -0,0 +1,260 @@
+// Dodo Payments plugin methods for the post-tenant phase. Option shapes are
+// derived from the plugin contract so a contract change fails at compile time.
+// Every response is validated with Zod; every non-2xx throws a DodoHttpError.
+import { KNOWN_RECURRING_INTERVALS, SubscriptionCancelTimings, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { DodoHttpError } from "./client.js";
+import { dodoSubscriptionSchema, mapDodoSubscriptionState } from "./verify-webhook.js";
+const NOT_FOUND = 404;
+function subscriptionPath(providerSubscriptionId) {
+    return `/subscriptions/${encodeURIComponent(providerSubscriptionId)}`;
+}
+function forcedLanguage(locale) {
+    return (locale.split(/[-_]/)[0] ?? locale).toLowerCase();
+}
+// =============================================================================
+// Checkout + portal + cancel/resume
+// =============================================================================
+const checkoutResponseSchema = z.object({
+    session_id: z.string(),
+    checkout_url: z.string().nullable(),
+});
+export function createDodoCheckoutSession(runtime) {
+    return async (ctx, options) => {
+        // No Dodo session may be created while billing is not live.
+        await runtime.assertBillingLive(ctx);
+        const response = checkoutResponseSchema.parse(await runtime.call(ctx, {
+            method: "POST",
+            path: "/checkouts",
+            body: {
+                product_cart: [{ product_id: options.priceId, quantity: 1 }],
+                ...(options.providerCustomerId && {
+                    customer: { customer_id: options.providerCustomerId },
+                }),
+                return_url: options.successUrl,
+                cancel_url: options.cancelUrl,
+                metadata: {
+                    tenantId: options.tenantId,
+                    ...(options.consentId && { consentId: options.consentId }),
+                },
+                ...(options.locale && {
+                    customization: { force_language: forcedLanguage(options.locale) },
+                }),
+            },
+        }));
+        if (!response.checkout_url) {
+            throw new Error("subscription-dodo: checkout session was created without a checkout_url");
+        }
+        return { url: response.checkout_url };
+    };
+}
+const portalResponseSchema = z.object({ link: z.string() });
+export function createDodoPortalSession(runtime) {
+    return async (ctx, options) => {
+        const response = portalResponseSchema.parse(await runtime.call(ctx, {
+            method: "POST",
+            path: `/customers/${encodeURIComponent(options.providerCustomerId)}/customer-portal/session`,
+            query: { return_url: options.returnUrl },
+        }));
+        return { url: response.link };
+    };
+}
+export function createDodoCancelSubscription(runtime) {
+    return async (ctx, options) => {
+        await runtime.call(ctx, {
+            method: "PATCH",
+            path: subscriptionPath(options.providerSubscriptionId),
+            body: options.when === SubscriptionCancelTimings.periodEnd
+                ? { cancel_at_next_billing_date: true }
+                : { status: "cancelled" },
+        });
+    };
+}
+export function createDodoResumeSubscription(runtime) {
+    return async (ctx, options) => {
+        await runtime.call(ctx, {
+            method: "PATCH",
+            path: subscriptionPath(options.providerSubscriptionId),
+            body: { cancel_at_next_billing_date: false },
+        });
+    };
+}
+// =============================================================================
+// Prices
+// =============================================================================
+const productSchema = z.object({
+    product_id: z.string(),
+    price: z.discriminatedUnion("type", [
+        z.object({
+            type: z.literal("recurring_price"),
+            price: z.number(),
+            currency: z.string(),
+            payment_frequency_interval: z.string(),
+            payment_frequency_count: z.number(),
+        }),
+        z.object({
+            type: z.literal("one_time_price"),
+            price: z.number(),
+            currency: z.string(),
+        }),
+        z.object({ type: z.literal("usage_based_price") }),
+    ]),
+    // nullish: an older product without metadata must not fail the whole price lookup.
+    metadata: z.record(z.string(), z.string()).nullish(),
+});
+function mapDodoProduct(product) {
+    const { price } = product;
+    if (price.type === "usage_based_price")
+        return null;
+    const base = {
+        priceId: product.product_id,
+        unitAmount: price.price,
+        currency: price.currency.toLowerCase(),
+        active: true,
+        metadata: product.metadata ?? {},
+    };
+    if (price.type === "one_time_price")
+        return { ...base, interval: null, intervalCount: 1 };
+    const rawInterval = price.payment_frequency_interval.toLowerCase();
+    const interval = KNOWN_RECURRING_INTERVALS.find((known) => known === rawInterval) ?? null;
+    return {
+        ...base,
+        interval,
+        intervalCount: interval ? price.payment_frequency_count : null,
+    };
+}
+// Keyed by product id alone: ids are unique per account and a cache hit must not
+// trigger an audited secret read on every billing-plans render. Failed lookups
+// are never cached. `null` is a cached "skipped" product (usage-based).
+export function createDodoPriceCache({ ttlMs = 600_000, now = () => Temporal.Now.instant().epochMilliseconds, } = {}) {
+    const store = new Map();
+    return {
+        get: (priceId) => {
+            const entry = store.get(priceId);
+            if (!entry)
+                return undefined;
+            if (entry.expiresAt <= now()) {
+                store.delete(priceId);
+                return undefined;
+            }
+            return entry.price;
+        },
+        set: (priceId, price) => {
+            store.set(priceId, { price, expiresAt: now() + ttlMs });
+        },
+    };
+}
+async function fillPriceCache(runtime, cache, ctx, priceIds) {
+    const misses = priceIds.filter((priceId) => cache.get(priceId) === undefined);
+    const settled = await Promise.allSettled(misses.map(async (priceId) => ({
+        priceId,
+        product: productSchema.parse(await runtime.call(ctx, {
+            method: "GET",
+            path: `/products/${encodeURIComponent(priceId)}`,
+        })),
+    })));
+    for (const outcome of settled) {
+        if (outcome.status === "fulfilled") {
+            cache.set(outcome.value.priceId, mapDodoProduct(outcome.value.product));
+        }
+        else {
+            const message = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            ctx.log?.warn("subscription-dodo: product lookup failed", { message });
+        }
+    }
+}
+export function createDodoRetrievePrices(runtime, cache) {
+    return async (ctx, priceIds) => {
+        await fillPriceCache(runtime, cache, ctx, priceIds);
+        return priceIds.flatMap((priceId) => cache.get(priceId) ?? []);
+    };
+}
+// =============================================================================
+// Plan switch (in-app: preview + apply)
+// =============================================================================
+const previewResponseSchema = z.object({
+    immediate_charge: z.object({
+        summary: z.object({
+            total_amount: z.number(),
+            tax: z.number().nullable(),
+            currency: z.string(),
+            customer_credits: z.number(),
+        }),
+        effective_at: z.string(),
+    }),
+});
+function changePlanBody(targetPriceId) {
+    return {
+        product_id: targetPriceId,
+        quantity: 1,
+        proration_billing_mode: "prorated_immediately",
+        effective_at: "immediately",
+    };
+}
+export function createDodoPreviewPlanSwitch(runtime) {
+    return async (ctx, options) => {
+        const { immediate_charge: charge } = previewResponseSchema.parse(await runtime.call(ctx, {
+            method: "POST",
+            path: `${subscriptionPath(options.providerSubscriptionId)}/change-plan/preview`,
+            body: changePlanBody(options.targetPriceId),
+        }));
+        return {
+            amountDueNow: charge.summary.total_amount,
+            tax: charge.summary.tax,
+            currency: charge.summary.currency.toLowerCase(),
+            credit: charge.summary.customer_credits,
+            effectiveAt: charge.effective_at,
+        };
+    };
+}
+const applyResponseSchema = z.looseObject({
+    payment_id: z.string().nullish(),
+    payment_link: z.string().nullish(),
+});
+// The switch itself arrives later as a subscription.plan_changed webhook;
+// prevent_change keeps the old plan if the immediate charge fails.
+export function createDodoApplyPlanSwitch(runtime) {
+    return async (ctx, options) => {
+        applyResponseSchema.parse(await runtime.call(ctx, {
+            method: "POST",
+            path: `${subscriptionPath(options.providerSubscriptionId)}/change-plan`,
+            body: {
+                ...changePlanBody(options.targetPriceId),
+                on_payment_failure: "prevent_change",
+                metadata: {
+                    tenantId: options.tenantId,
+                    ...(options.consentId && { consentId: options.consentId }),
+                },
+            },
+        }));
+    };
+}
+// =============================================================================
+// retrieveSubscription
+// =============================================================================
+export function createDodoRetrieveSubscription(runtime, options) {
+    return async (ctx, providerSubscriptionId) => {
+        let raw;
+        try {
+            raw = await runtime.call(ctx, {
+                method: "GET",
+                path: subscriptionPath(providerSubscriptionId),
+            });
+        }
+        catch (error) {
+            if (error instanceof DodoHttpError && error.status === NOT_FOUND)
+                return null;
+            throw error;
+        }
+        const sub = dodoSubscriptionSchema.parse(raw);
+        const state = mapDodoSubscriptionState(sub, options.priceToTier);
+        if (!state)
+            return null;
+        return {
+            providerCustomerId: sub.customer.customer_id,
+            providerSubscriptionId: sub.subscription_id,
+            ...state,
+        };
+    };
+}

package/dist/subscription-dodo/runtime.d.ts

@@ -0,0 +1,27 @@
+import { type ConfigKeyHandle, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { type DodoRequest, type DodoSend } from "./client.ts";
+export type DodoRuntimeDeps = {
+    readonly apiKeyHandle: ConfigKeyHandle<"text">;
+    readonly webhookSecretHandle: ConfigKeyHandle<"text">;
+    readonly billingLiveHandle: ConfigKeyHandle<"boolean">;
+    readonly environmentHandle: ConfigKeyHandle<"select">;
+    readonly send: DodoSend;
+    readonly fallback: {
+        readonly apiKey?: string;
+        readonly webhookSecret?: string;
+    };
+};
+export type DodoCtxRuntime = {
+    readonly call: (ctx: HandlerContext, request: DodoRequest) => Promise<unknown>;
+    readonly assertBillingLive: (ctx: HandlerContext, handlerName?: string) => Promise<void>;
+    readonly isBillingEnabled: (ctx: HandlerContext) => Promise<boolean>;
+};
+export type DodoWebhookRuntime = {
+    readonly resolveWebhookSecret: (systemSecrets?: SecretsContext) => Promise<string>;
+};
+export type DodoRuntimes = {
+    readonly ctx: DodoCtxRuntime;
+    readonly webhook: DodoWebhookRuntime;
+};
+export declare function createDodoRuntimes(deps: DodoRuntimeDeps): DodoRuntimes;

package/dist/subscription-dodo/runtime.js

@@ -0,0 +1,89 @@
+// Call-time key/flag resolution for the subscription-dodo plugin, mirroring
+// subscription-stripe/runtime.ts: credentials come from backing:"secrets"
+// config keys under SYSTEM_TENANT_ID, so rotation and go-live need no redeploy.
+// The factory options survive as env-bridge fallbacks.
+//
+// Two read paths: post-tenant handlers read the key audited through the
+// HandlerContext; the pre-tenant webhook reads the secret un-audited from the
+// system SecretsContext the foundation passes in.
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import { createDodoHttp } from "./client.js";
+import { DODO_BASE_URLS, DodoEnvironments, SUBSCRIPTION_DODO_FEATURE } from "./constants.js";
+const API_KEY_HINT = "Set the Dodo Payments API key via config:write:set on `subscription-dodo:config:api-key` (or seed it from DODO_PAYMENTS_API_KEY during the env bridge).";
+// backing:"secrets" values are stored JSON-serialized, so the store read has to
+// be parsed back; the env fallback is a plain string and stays raw. The error
+// must not carry the input: the JSON parser's own message would repeat the
+// credential into logs and, for webhooks, into the 401 body.
+function parseStoredSecret(raw) {
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    const parsed = parseJsonSafe(raw, undefined);
+    if (parsed === undefined) {
+        throw new Error("subscription-dodo credential (backing:secrets) is not valid JSON");
+    }
+    return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
+}
+export function createDodoRuntimes(deps) {
+    const http = createDodoHttp(deps.send);
+    async function ctxApiKey(ctx) {
+        let key;
+        if (ctx.secrets) {
+            const got = await requireSecretsContext(ctx, SUBSCRIPTION_DODO_FEATURE).get(SYSTEM_TENANT_ID, deps.apiKeyHandle.name);
+            key = parseStoredSecret(got?.reveal());
+        }
+        if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
+            key = deps.fallback.apiKey;
+        }
+        if (!key) {
+            throw new UnconfiguredError({
+                feature: SUBSCRIPTION_DODO_FEATURE,
+                key: deps.apiKeyHandle.name,
+                hint: API_KEY_HINT,
+            });
+        }
+        return key;
+    }
+    async function baseUrlFor(ctx) {
+        const environment = ctx.config ? await ctx.config(deps.environmentHandle) : undefined;
+        return DODO_BASE_URLS[environment === DodoEnvironments.live ? "live" : "test"];
+    }
+    return {
+        ctx: {
+            call: async (ctx, request) => http({ baseUrl: await baseUrlFor(ctx), apiKey: await ctxApiKey(ctx) }, request),
+            assertBillingLive: async (ctx, handlerName = "create-checkout-session") => {
+                const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+                if (live !== true)
+                    throw new FeatureDisabledError(SUBSCRIPTION_DODO_FEATURE, handlerName);
+            },
+            isBillingEnabled: async (ctx) => {
+                const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+                if (live !== true)
+                    return false;
+                if (deps.fallback.apiKey !== undefined && deps.fallback.apiKey.length > 0)
+                    return true;
+                // Existence-only probe on every billing-plans render: must stay un-audited.
+                return ctx.secrets
+                    ? await ctx.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
+                    : false;
+            },
+        },
+        webhook: {
+            resolveWebhookSecret: async (systemSecrets) => {
+                if (systemSecrets) {
+                    // No auditCtx: every webhook would otherwise spam the audit trail.
+                    const got = await systemSecrets.get(SYSTEM_TENANT_ID, deps.webhookSecretHandle.name);
+                    const stored = parseStoredSecret(got?.reveal());
+                    if (stored)
+                        return stored;
+                }
+                const fallback = deps.fallback.webhookSecret;
+                if (fallback && fallback.length > 0)
+                    return fallback;
+                throw new Error(`subscription-dodo: '${deps.webhookSecretHandle.name}' unresolved — no system-secret set and no factory fallback. Webhook cannot verify until it is configured.`);
+            },
+        },
+    };
+}

package/dist/subscription-dodo/verify-webhook.d.ts

@@ -0,0 +1,37 @@
+import { type PaymentEvent, type SubscriptionEvent, type SubscriptionStatus } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import * as z from "zod";
+import type { DodoWebhookRuntime } from "./runtime.ts";
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+export type StandardWebhookHeaders = Readonly<Record<string, string>>;
+/** Throws unless the Standard Webhooks signature over `rawBody` is valid and
+ *  the timestamp is within the tolerance in both directions. */
+export declare function verifyStandardWebhook(rawBody: string, headers: StandardWebhookHeaders, secret: string, nowSeconds: number): void;
+export declare const dodoSubscriptionSchema: z.ZodObject<{
+    subscription_id: z.ZodString;
+    product_id: z.ZodString;
+    status: z.ZodString;
+    customer: z.ZodObject<{
+        customer_id: z.ZodString;
+    }, z.core.$strip>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    next_billing_date: z.ZodISODateTime;
+    cancel_at_next_billing_date: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type DodoSubscription = z.infer<typeof dodoSubscriptionSchema>;
+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 declare function mapDodoSubscriptionState(sub: DodoSubscription, priceToTier: Readonly<Record<string, string>>): MappedDodoSubscriptionState | null;
+export type DodoWebhookOptions = {
+    readonly priceToTier: Readonly<Record<string, string>>;
+    /** Test seam: Unix seconds. Defaults to the wall clock. */
+    readonly nowSeconds?: () => number;
+};
+export declare function verifyAndParseDodoWebhook(runtime: DodoWebhookRuntime, options: DodoWebhookOptions): (rawBody: string, headers: Record<string, string>, systemSecrets?: SecretsContext) => Promise<SubscriptionEvent | PaymentEvent | null>;

package/dist/subscription-dodo/verify-webhook.js

@@ -0,0 +1,189 @@
+// 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, parseProviderConsentId, SubscriptionEventTypes, SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+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.js";
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+const SECRET_PREFIX = "whsec_";
+const SIGNATURE_VERSION = "v1";
+const TIMESTAMP_PATTERN = /^\d+$/;
+function signatureFor(secretKey, signedContent) {
+    return createHmac("sha256", secretKey).update(signedContent).digest();
+}
+function matchesAnyV1Signature(header, expected) {
+    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, headers, secret, nowSeconds) {
+    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 = {
+    "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 = {
+    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(),
+});
+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, key) {
+    const value = metadata?.[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** 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, priceToTier) {
+    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,
+    };
+}
+function currentUnixSeconds() {
+    return Math.floor(Temporal.Now.instant().epochMilliseconds / 1000);
+}
+function parsePaymentEvent(providerEventId, data) {
+    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, type, providerEventAt, data, priceToTier) {
+    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, options) {
+    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(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/dist/subscription-mollie/constants.js

@@ -1,31 +1,29 @@
 // Feature name
 export const SUBSCRIPTION_MOLLIE_FEATURE = "subscription-mollie";
-// 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";
 // =============================================================================
-// 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)