@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.388.0

package/dist/subscription-dodo/client.js

@@ -0,0 +1,31 @@
+// Thin JSON-over-fetch client for the Dodo Payments REST API. All traffic goes
+// through the injected `send`, which defaults to the SSRF-safe egress in
+// feature.ts and is replaced by a mock in tests.
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+// Never carries the response body or the key: both can hold customer data or secrets.
+export class DodoHttpError extends Error {
+    status;
+    constructor(request, status) {
+        super(`subscription-dodo: ${request.method} ${request.path} failed with status ${status}`);
+        this.name = "DodoHttpError";
+        this.status = status;
+    }
+}
+export function createDodoHttp(send) {
+    return async (target, request) => {
+        const query = request.query ? `?${new URLSearchParams(request.query).toString()}` : "";
+        const response = await send(`${target.baseUrl}${request.path}${query}`, {
+            method: request.method,
+            headers: {
+                Authorization: `Bearer ${target.apiKey}`,
+                Accept: "application/json",
+                ...(request.body !== undefined && { "Content-Type": "application/json" }),
+            },
+            ...(request.body !== undefined && { body: JSON.stringify(request.body) }),
+        });
+        if (!response.ok)
+            throw new DodoHttpError(request, response.status);
+        const text = await response.text();
+        return text.length === 0 ? null : parseJsonOrThrow(text, "subscription-dodo response");
+    };
+}

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

@@ -0,0 +1,12 @@
+export declare const SUBSCRIPTION_DODO_FEATURE: "subscription-dodo";
+export declare const DODO_PROVIDER_NAME: "dodo";
+export declare const DODO_API_KEY_CONFIG: "api-key";
+export declare const DODO_WEBHOOK_SECRET_CONFIG: "webhook-secret";
+export declare const DODO_BILLING_LIVE_CONFIG: "billingLive";
+export declare const DODO_ENVIRONMENT_CONFIG: "environment";
+export declare const DodoEnvironments: {
+    readonly test: "test";
+    readonly live: "live";
+};
+export type DodoEnvironment = (typeof DodoEnvironments)[keyof typeof DodoEnvironments];
+export declare const DODO_BASE_URLS: Readonly<Record<DodoEnvironment, string>>;

package/dist/subscription-dodo/constants.js

@@ -0,0 +1,19 @@
+export const SUBSCRIPTION_DODO_FEATURE = "subscription-dodo";
+// Must match the path segment in the webhook URL `/api/subscription/webhook/dodo`.
+export const DODO_PROVIDER_NAME = "dodo";
+// Config-key short-names, qualified to `subscription-dodo:config:<name>` at
+// registry-build. api-key + webhook-secret are backing:"secrets".
+export const DODO_API_KEY_CONFIG = "api-key";
+export const DODO_WEBHOOK_SECRET_CONFIG = "webhook-secret";
+export const DODO_BILLING_LIVE_CONFIG = "billingLive";
+export const DODO_ENVIRONMENT_CONFIG = "environment";
+// Separate from billingLive on purpose: staging runs Dodo's test API with
+// billingLive on, production flips both.
+export const DodoEnvironments = {
+    test: "test",
+    live: "live",
+};
+export const DODO_BASE_URLS = {
+    test: "https://test.dodopayments.com",
+    live: "https://live.dodopayments.com",
+};

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

@@ -0,0 +1,37 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type FeatureWithEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import * as z from "zod";
+import type { DodoSend } from "./client.ts";
+/** Bridge contract: both fields are optional fallbacks for the secrets store. */
+export declare const subscriptionDodoEnvSchema: z.ZodObject<{
+    DODO_PAYMENTS_API_KEY: z.ZodOptional<z.ZodString>;
+    DODO_PAYMENTS_WEBHOOK_KEY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type DodoProductEnvShape<TPrice extends string> = {
+    [Key in `DODO_PRODUCT_${TPrice}`]: z.ZodOptional<z.ZodString>;
+};
+/** Dodo env block plus one `DODO_PRODUCT_<NAME>` slot per plan product the app
+ *  maps to a tier, e.g. `dodoEnvSchema({ prices: ["PRO", "TEAM"] })`.
+ *  Shares its bridge fields with `subscriptionDodoEnvSchema`, so spreading
+ *  it into `composeEnvSchema({ extend })` next to the mounted feature is no
+ *  key clash. */
+export declare function dodoEnvSchema<const TPrice extends string>(options: {
+    readonly prices: readonly TPrice[];
+}): z.ZodObject<{
+    DODO_PAYMENTS_API_KEY: z.ZodOptional<z.ZodString>;
+    DODO_PAYMENTS_WEBHOOK_KEY: z.ZodOptional<z.ZodString>;
+} & DodoProductEnvShape<TPrice> extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strip>;
+export type SubscriptionDodoOptions = {
+    /** Bridge-fallback API key; the `api-key` config key wins when set. */
+    readonly apiKey?: string;
+    /** Bridge-fallback webhook secret; the `webhook-secret` config key wins when set. */
+    readonly webhookSecret?: string;
+    /** Dodo product id → app tier name. Products absent here drop the event. */
+    readonly priceToTier?: Readonly<Record<string, string>>;
+    /** Product ids a mode:"payment" checkout may target; empty = one-off checkouts closed. */
+    readonly oneOffPriceIds?: readonly string[];
+    /** HTTP transport; defaults to the SSRF-safe external egress. Test seam. */
+    readonly send?: DodoSend;
+};
+export declare function createSubscriptionDodoFeature(options?: SubscriptionDodoOptions): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionDodoEnvSchema.shape>;
+export {};

package/dist/subscription-dodo/feature.js

@@ -0,0 +1,144 @@
+// kumiko-feature-version: 1
+//
+// subscription-dodo — Dodo Payments (merchant of record) plugin for the
+// billing-foundation plugin API. Credentials, the billing-live master switch and
+// the API environment (test | live) are config keys resolved at call time, like
+// subscription-stripe. `apiKey` / `webhookSecret` options are env→secrets bridge
+// fallbacks.
+import { access, createSystemConfig, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
+import { featureWithEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { egress } from "@cosmicdrift/kumiko-framework/http";
+import * as z from "zod";
+import { DODO_API_KEY_CONFIG, DODO_BILLING_LIVE_CONFIG, DODO_ENVIRONMENT_CONFIG, DODO_PROVIDER_NAME, DODO_WEBHOOK_SECRET_CONFIG, DodoEnvironments, SUBSCRIPTION_DODO_FEATURE, } from "./constants.js";
+import { createDodoApplyPlanSwitch, createDodoCancelSubscription, createDodoCheckoutSession, createDodoPortalSession, createDodoPreviewPlanSwitch, createDodoPriceCache, createDodoResumeSubscription, createDodoRetrievePrices, createDodoRetrieveSubscription, } from "./plugin-methods.js";
+import { createDodoRuntimes } from "./runtime.js";
+import { verifyAndParseDodoWebhook } from "./verify-webhook.js";
+/** Bridge contract: both fields are optional fallbacks for the secrets store. */
+export const subscriptionDodoEnvSchema = z.object({
+    DODO_PAYMENTS_API_KEY: z
+        .string()
+        .min(1)
+        .describe("Dodo Payments API key. Bridge-fallback — prefer the secret.")
+        .meta({ kumiko: { pulumi: { secret: true } } })
+        .optional(),
+    DODO_PAYMENTS_WEBHOOK_KEY: z
+        .string()
+        .min(1)
+        .describe("Dodo Payments webhook signing key (`whsec_...`). Bridge-fallback — prefer the secret.")
+        .meta({ kumiko: { pulumi: { secret: true } } })
+        .optional(),
+});
+/** Dodo env block plus one `DODO_PRODUCT_<NAME>` slot per plan product the app
+ *  maps to a tier, e.g. `dodoEnvSchema({ prices: ["PRO", "TEAM"] })`.
+ *  Shares its bridge fields with `subscriptionDodoEnvSchema`, so spreading
+ *  it into `composeEnvSchema({ extend })` next to the mounted feature is no
+ *  key clash. */
+export function dodoEnvSchema(options) {
+    const productShape = Object.fromEntries(options.prices.map((price) => [
+        `DODO_PRODUCT_${price}`,
+        z
+            .string()
+            .regex(/^pdt_/, `DODO_PRODUCT_${price} must start with 'pdt_'`)
+            .optional()
+            .describe(`Dodo Payments product id (\`pdt_...\`) of the ${price} plan.`),
+    ]));
+    return z.object({ ...subscriptionDodoEnvSchema.shape, ...productShape });
+}
+// Validated once at feature-build time so a typo fails app startup instead of
+// silently widening or narrowing the one-off allowlist at request time.
+function validateOneOffPriceIds(priceIds) {
+    const seen = new Set();
+    for (const priceId of priceIds) {
+        if (priceId.length === 0) {
+            throw new Error("subscription-dodo: oneOffPriceIds must not contain an empty string");
+        }
+        if (seen.has(priceId)) {
+            throw new Error(`subscription-dodo: duplicate oneOffPriceIds entry "${priceId}"`);
+        }
+        seen.add(priceId);
+    }
+}
+export function createSubscriptionDodoFeature(options = {}) {
+    validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+    const feature = defineFeature(SUBSCRIPTION_DODO_FEATURE, (r) => {
+        r.describe('Dodo Payments provider plugin for `billing-foundation`. Dodo acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key and webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant), plus a `billingLive` master switch and an `environment` key (test | live). `environment` is its own key because Dodo serves test and live mode from different API hosts and a live key must never hit the test host or the other way round; `billingLive` only decides whether checkouts are offered at all. All four are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionDodoFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env to secrets bridge fallbacks (`DODO_PAYMENTS_API_KEY`, `DODO_PAYMENTS_WEBHOOK_KEY`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true. Webhooks arrive at `/api/subscription/webhook/dodo` and are verified per the Standard Webhooks spec (HMAC-SHA256 over id, timestamp and the raw body, 5 minute tolerance); events for products outside `priceToTier` or without tenant metadata are dropped. Implements hosted checkout, customer portal, cancel and resume, `retrievePrices` (10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `plan_changed` webhook to move the tier. A plan switch in Dodo requires all plan products to belong to one Product Collection.');
+        r.uiHints({
+            displayLabel: "Billing · Dodo Payments",
+            category: "billing",
+            recommended: false,
+        });
+        r.requires({ features: ["billing-foundation"] });
+        r.requires({ features: ["config"] });
+        r.requires({ features: ["secrets"] });
+        r.envSchema(subscriptionDodoEnvSchema);
+        const configKeys = r.config({
+            keys: {
+                [DODO_API_KEY_CONFIG]: createSystemConfig("text", {
+                    backing: "secrets",
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-dodo.api-key", icon: "key", order: 1 },
+                }),
+                [DODO_WEBHOOK_SECRET_CONFIG]: createSystemConfig("text", {
+                    backing: "secrets",
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-dodo.webhook-secret", icon: "shield", order: 2 },
+                }),
+                [DODO_ENVIRONMENT_CONFIG]: createSystemConfig("select", {
+                    default: DodoEnvironments.test,
+                    options: [DodoEnvironments.test, DodoEnvironments.live],
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-dodo.environment", icon: "server", order: 3 },
+                }),
+                [DODO_BILLING_LIVE_CONFIG]: createSystemConfig("boolean", {
+                    default: false,
+                    write: access.privileged,
+                    read: access.admin,
+                    mask: { title: "subscription-dodo.billing-live", icon: "rocket", order: 4 },
+                }),
+            },
+        });
+        r.translations({
+            keys: {
+                "subscription-dodo.api-key": { en: "Dodo Payments API key" },
+                "subscription-dodo.webhook-secret": { en: "Dodo Payments webhook secret" },
+                "subscription-dodo.environment": { en: "Dodo Payments environment" },
+                "subscription-dodo.billing-live": { en: "Live billing" },
+                "subscription-dodo.settings": { en: "Dodo Payments" },
+                "screen:subscription-dodo-system.title": { en: "Dodo Payments" },
+            },
+        });
+        const priceToTier = options.priceToTier ?? {};
+        const runtimes = createDodoRuntimes({
+            apiKeyHandle: configKeys[DODO_API_KEY_CONFIG],
+            webhookSecretHandle: configKeys[DODO_WEBHOOK_SECRET_CONFIG],
+            billingLiveHandle: configKeys[DODO_BILLING_LIVE_CONFIG],
+            environmentHandle: configKeys[DODO_ENVIRONMENT_CONFIG],
+            send: options.send ?? egress({ kind: "external" }),
+            fallback: {
+                ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+                ...(options.webhookSecret !== undefined && { webhookSecret: options.webhookSecret }),
+            },
+        });
+        const plugin = {
+            displayName: "Dodo Payments",
+            verifyAndParseWebhook: verifyAndParseDodoWebhook(runtimes.webhook, { priceToTier }),
+            createCheckoutSession: createDodoCheckoutSession(runtimes.ctx),
+            createPortalSession: createDodoPortalSession(runtimes.ctx),
+            cancelSubscription: createDodoCancelSubscription(runtimes.ctx),
+            resumeSubscription: createDodoResumeSubscription(runtimes.ctx),
+            priceToTier,
+            oneOffPriceIds: options.oneOffPriceIds ?? [],
+            isBillingEnabled: runtimes.ctx.isBillingEnabled,
+            retrievePrices: createDodoRetrievePrices(runtimes.ctx, createDodoPriceCache()),
+            retrieveSubscription: createDodoRetrieveSubscription(runtimes.ctx, { priceToTier }),
+            previewPlanSwitch: createDodoPreviewPlanSwitch(runtimes.ctx),
+            applyPlanSwitch: createDodoApplyPlanSwitch(runtimes.ctx),
+        };
+        r.useExtension("subscriptionProvider", DODO_PROVIDER_NAME, plugin);
+        return { configKeys };
+    });
+    return featureWithEnvSchema(feature, subscriptionDodoEnvSchema);
+}

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

@@ -0,0 +1,2 @@
+export { DODO_BASE_URLS, DODO_PROVIDER_NAME, type DodoEnvironment, DodoEnvironments, SUBSCRIPTION_DODO_FEATURE, } from "./constants.ts";
+export { createSubscriptionDodoFeature, dodoEnvSchema, type SubscriptionDodoOptions, subscriptionDodoEnvSchema, } from "./feature.ts";

package/dist/subscription-dodo/index.js

@@ -0,0 +1,4 @@
+// Public API of the subscription-dodo bundled feature. The webhook verifier,
+// client and plugin methods are internal to feature.ts.
+export { DODO_BASE_URLS, DODO_PROVIDER_NAME, DodoEnvironments, SUBSCRIPTION_DODO_FEATURE, } from "./constants.js";
+export { createSubscriptionDodoFeature, dodoEnvSchema, subscriptionDodoEnvSchema, } from "./feature.js";

package/dist/subscription-dodo/plugin-methods.d.ts

@@ -0,0 +1,23 @@
+import { type ProviderPrice, type SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { DodoCtxRuntime } from "./runtime.ts";
+type PluginMethod<TName extends keyof SubscriptionProviderPlugin> = NonNullable<SubscriptionProviderPlugin[TName]>;
+export declare function createDodoCheckoutSession(runtime: DodoCtxRuntime): PluginMethod<"createCheckoutSession">;
+export declare function createDodoPortalSession(runtime: DodoCtxRuntime): PluginMethod<"createPortalSession">;
+export declare function createDodoCancelSubscription(runtime: DodoCtxRuntime): PluginMethod<"cancelSubscription">;
+export declare function createDodoResumeSubscription(runtime: DodoCtxRuntime): PluginMethod<"resumeSubscription">;
+export type DodoPriceCache = {
+    readonly get: (priceId: string) => ProviderPrice | null | undefined;
+    readonly set: (priceId: string, price: ProviderPrice | null) => void;
+};
+export type DodoPriceCacheOptions = {
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+};
+export declare function createDodoPriceCache({ ttlMs, now, }?: DodoPriceCacheOptions): DodoPriceCache;
+export declare function createDodoRetrievePrices(runtime: DodoCtxRuntime, cache: DodoPriceCache): PluginMethod<"retrievePrices">;
+export declare function createDodoPreviewPlanSwitch(runtime: DodoCtxRuntime): PluginMethod<"previewPlanSwitch">;
+export declare function createDodoApplyPlanSwitch(runtime: DodoCtxRuntime): PluginMethod<"applyPlanSwitch">;
+export declare function createDodoRetrieveSubscription(runtime: DodoCtxRuntime, options: {
+    readonly priceToTier: Readonly<Record<string, string>>;
+}): PluginMethod<"retrieveSubscription">;
+export {};

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.`);
+            },
+        },
+    };
+}