@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.389.0

package/dist/sessions/index.d.ts

@@ -3,6 +3,6 @@ export type { BindAutoRevokeOnPasswordChange, SessionsFeatureOptions } from "./f
 export { bindAutoRevokeFromFeature, createSessionsFeature } from "./feature.ts";
 export { userSessionEntity, userSessionTable } from "./schema/user-session.ts";
 export type { SessionCallbacks, SessionCallbacksOptions, SessionMassRevoker, } from "./session-callbacks.ts";
-export { createSessionCallbacks, isPrincipalBlocked } from "./session-callbacks.ts";
+export { createSessionCallbacks } from "./session-callbacks.ts";
 export type { SessionRevokedPayload } from "./session-revoked-event.ts";
 export { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN, SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema, } from "./session-revoked-event.ts";

package/dist/sessions/index.js

@@ -1,5 +1,5 @@
 export { DEFAULT_SESSION_CACHE_TTL_MS, DEFAULT_SESSION_EXPIRY_MS, SESSION_MINE_SCREEN_ID, SESSIONS_FEATURE, SessionErrors, SessionHandlers, SessionQueries, } from "./constants.js";
 export { bindAutoRevokeFromFeature, createSessionsFeature } from "./feature.js";
 export { userSessionEntity, userSessionTable } from "./schema/user-session.js";
-export { createSessionCallbacks, isPrincipalBlocked } from "./session-callbacks.js";
+export { createSessionCallbacks } from "./session-callbacks.js";
 export { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN, SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema, } from "./session-revoked-event.js";

package/dist/sessions/session-callbacks.d.ts

@@ -1,8 +1,6 @@
 import type { SessionChecker, SessionCreator, SessionMassRevoker, SessionRevoker } from "@cosmicdrift/kumiko-framework/api";
 export type { SessionMassRevoker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { isPrincipalBlocked } from "../user/index.ts";
-export { isPrincipalBlocked };
 export type SessionAllOthersRevoker = (userId: string, currentSid: string | undefined) => Promise<number>;
 export type SessionCallbacksOptions = {
     readonly db: DbConnection;

package/dist/sessions/session-callbacks.js

@@ -5,12 +5,10 @@ import { generateId, parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { encryptForDirectWrite } from "../shared/index.js";
 import { tenantMembershipsTable } from "../tenant/index.js";
-import { isPrincipalBlocked, isPrincipalRowBlocked, userTable, } from "../user/index.js";
+import { isPrincipalRowBlocked, userTable } from "../user/index.js";
 import { DEFAULT_SESSION_EXPIRY_MS, LAST_SEEN_REFRESH_MS, USER_SESSION_ENTITY_NAME, } from "./constants.js";
 import { userSessionEntity, userSessionTable } from "./schema/user-session.js";
 import { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN, sessionRevokedSchema, } from "./session-revoked-event.js";
-// Re-exported so existing `../sessions` importers keep working unchanged.
-export { isPrincipalBlocked };
 function settleLookup(lookup) {
     return lookup.then((value) => ({ ok: true, value }), () => ({ ok: false }));
 }

package/dist/shared/decrypt-stored-pii.d.ts

@@ -1 +1,2 @@
 export declare function decryptStoredPii(value: string, field: string, fallbackRequestId: string): Promise<string>;
+export declare function decryptStoredUserEmail(stored: string, fallbackRequestId: string): Promise<string | null>;

package/dist/shared/decrypt-stored-pii.js

@@ -1,5 +1,5 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
-import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configuredPiiSubjectKms, decryptPiiFieldValues, PII_ERASED_SENTINEL, } from "@cosmicdrift/kumiko-framework/crypto";
 // Raw reads (fetchOne/selectMany) return the stored column value — with an
 // active KMS that is ciphertext (self-describing: it names its own subject,
 // so no entity/field context is needed for key selection). `field` must
@@ -17,3 +17,8 @@ export async function decryptStoredPii(value, field, fallbackRequestId) {
     const decrypted = out[field];
     return typeof decrypted === "string" ? decrypted : value;
 }
+// Null for an erased subject: the sentinel must never be mailed or shown as an address.
+export async function decryptStoredUserEmail(stored, fallbackRequestId) {
+    const email = await decryptStoredPii(stored, "email", fallbackRequestId);
+    return email === PII_ERASED_SENTINEL ? null : email;
+}

package/dist/shared/index.d.ts

@@ -3,7 +3,7 @@ export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-own
 export { attachmentFileNameSchema, sanitizePdfAttachmentFileName, } from "./attachment-file-name.ts";
 export { type ChunkedMigrationOptions, type ChunkedMigrationResult, type ChunkedMigrationStopReason, type MigrationRowOutcome, runChunkedMigration, } from "./chunked-entity-migration.ts";
 export { classifyStoredEnvelope, type StoredEnvelopeClassification, } from "./classify-stored-envelope.ts";
-export { decryptStoredPii } from "./decrypt-stored-pii.ts";
+export { decryptStoredPii, decryptStoredUserEmail } from "./decrypt-stored-pii.ts";
 export { encryptForDirectWrite } from "./encrypt-for-direct-write.ts";
 export { entitiesOf } from "./entities-of.ts";
 export { isWithinGracePeriod } from "./grace-period.ts";

package/dist/shared/index.js

@@ -3,7 +3,7 @@ export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-own
 export { attachmentFileNameSchema, sanitizePdfAttachmentFileName, } from "./attachment-file-name.js";
 export { runChunkedMigration, } from "./chunked-entity-migration.js";
 export { classifyStoredEnvelope, } from "./classify-stored-envelope.js";
-export { decryptStoredPii } from "./decrypt-stored-pii.js";
+export { decryptStoredPii, decryptStoredUserEmail } from "./decrypt-stored-pii.js";
 export { encryptForDirectWrite } from "./encrypt-for-direct-write.js";
 export { entitiesOf } from "./entities-of.js";
 export { isWithinGracePeriod } from "./grace-period.js";

package/dist/shared/mail-template-body.d.ts

@@ -1,7 +1,11 @@
 export declare function mailTextWithSlotsHtml(text: string): string;
-export declare function mailParagraph(text: string): string;
+type MailParagraphOptions = {
+    readonly showIf?: string;
+};
+export declare function mailParagraph(text: string, options?: MailParagraphOptions): string;
 export declare function mailHeading(text: string): string;
 export declare function mailButton(label: string, linkVariable: string): string;
-export declare function mailParagraphWithLink(text: string, linkLabel: string, linkVariable: string): string;
+export declare function mailParagraphWithLink(text: string, linkLabel: string, linkVariable: string, options?: MailParagraphOptions): string;
 export declare function mailRepeatedRows(listName: string, field: string): string;
 export declare function mailSubject(text: string): string;
+export {};

package/dist/shared/mail-template-body.js

@@ -5,8 +5,11 @@ const SLOT_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
 export function mailTextWithSlotsHtml(text) {
     return escapeHtml(text).replace(SLOT_PATTERN, (_, name) => `<span data-variable="${escapeHtmlAttr(name)}"></span>`);
 }
-export function mailParagraph(text) {
-    return `<p>${mailTextWithSlotsHtml(text)}</p>`;
+function paragraphOpenTag(options) {
+    return options?.showIf === undefined ? "<p>" : `<p data-if="${escapeHtmlAttr(options.showIf)}">`;
+}
+export function mailParagraph(text, options) {
+    return `${paragraphOpenTag(options)}${mailTextWithSlotsHtml(text)}</p>`;
 }
 export function mailHeading(text) {
     return `<h2>${mailTextWithSlotsHtml(text)}</h2>`;
@@ -14,8 +17,8 @@ export function mailHeading(text) {
 export function mailButton(label, linkVariable) {
     return `<p><a data-button href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(label)}</a></p>`;
 }
-export function mailParagraphWithLink(text, linkLabel, linkVariable) {
-    return `<p>${mailTextWithSlotsHtml(text)} <a href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(linkLabel)}</a></p>`;
+export function mailParagraphWithLink(text, linkLabel, linkVariable, options) {
+    return `${paragraphOpenTag(options)}${mailTextWithSlotsHtml(text)} <a href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(linkLabel)}</a></p>`;
 }
 // One table row per list entry; the cell shows the entry's `field`.
 export function mailRepeatedRows(listName, field) {

package/dist/shared/purge-files-reaching-subject.d.ts

@@ -7,6 +7,7 @@ export declare class FileSweepError extends Error {
     readonly entityName: string;
     constructor(code: Exclude<FileRefPurgeOutcome, "purged">, entityName: string);
 }
+export declare const PURGE_CANDIDATE_PAGE_SIZE = 200;
 export type DeleteFileBytes = (storageKey: string) => Promise<readonly string[]>;
 export type MissingStoragePolicy = {
     readonly mode: "fail";

package/dist/shared/purge-files-reaching-subject.js

@@ -70,6 +70,24 @@ function fieldsResolvingToSubject(fileEntity, row, rowTenantId, subjectKey) {
         }
     });
 }
+// A user owning many records must not load them all at once; the id cursor keeps each page
+// bounded while rows purged in place stay out of the way.
+export const PURGE_CANDIDATE_PAGE_SIZE = 200;
+async function* candidateRowsPaged(db, table, where) {
+    let cursor;
+    for (;;) {
+        const pageWhere = cursor === undefined ? where : { ...where, id: { gt: cursor } };
+        const page = await selectMany(db, table, pageWhere, {
+            orderBy: { col: "id", direction: "asc" },
+            limit: PURGE_CANDIDATE_PAGE_SIZE,
+        });
+        yield* page;
+        // skip: a short page is the last one
+        if (page.length < PURGE_CANDIDATE_PAGE_SIZE)
+            return;
+        cursor = page[page.length - 1]?.["id"];
+    }
+}
 const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
     entityName: "fileRef",
 });
@@ -99,8 +117,7 @@ export async function purgeFilesReachingSubject(args) {
     for (const fileEntity of fileEntities) {
         const seenRowIds = new Set();
         for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
-            const rows = await selectMany(db, fileEntity.table, where);
-            for (const row of rows) {
+            for await (const row of candidateRowsPaged(db, fileEntity.table, where)) {
                 const rowId = String(row["id"]);
                 const tenantId = parseTenantId(row["tenantId"]);
                 // skip: a row without a tenant cannot own tenant-scoped file refs

package/dist/shared/run-in-sub-transaction.js

@@ -1,9 +1,9 @@
 // Per-unit sub-transaction (one user, one purged row), nesting-aware across both db shapes:
-//   - top-level connection (postgres-js Sql) → `.begin` (BEGIN)
-//   - TransactionSql (inside the dispatcher's outer tx, where every
+//   - top-level connection (Bun.SQL pool) → `.begin` (BEGIN)
+//   - TransactionSQL (inside the dispatcher's outer tx, where every
 //     writeHandler already runs) → `.savepoint` (SAVEPOINT)
-// A TransactionSql has no `.begin`, so the previous unconditional `.begin`
-// threw "is not a function" on every user when invoked through the dispatcher
+// A transaction handle cannot begin another transaction, so the previous unconditional `.begin`
+// threw on every user when invoked through the dispatcher
 // (the cron path) → zero deletions in production, while direct-connection tests
 // stayed green. Selecting the available method makes the sub-tx work in both
 // contexts; on throw the savepoint rolls back just this user (others survive).
@@ -13,7 +13,7 @@ export async function runInSubTransaction(db, fn) {
     // without asRawClient (a test-only escape hatch).
     const runner = db;
     // savepoint-first: empirically (Bun 1.3.14, not re-checked on 1.4.0) the
-    // surfaces are NOT mutually exclusive — a TransactionSql exposes begin AND
+    // surfaces are NOT mutually exclusive — a TransactionSQL exposes begin AND
     // savepoint, only the top-level connection has begin alone. begin-first
     // picked the nested BEGIN inside a tx (the incident class above);
     // savepoint-first hits the savepoint there and falls back to begin top-level.

package/dist/step-dispatcher/deliver-dispatch-request.js

@@ -31,9 +31,16 @@ export async function eraseDispatchKey(aggregateId) {
         eraseReason: "step-dispatch-outcome-recorded",
     });
 }
-// Mail adapter failures carry no status to classify, so every one is retried.
+const SMTP_PERMANENT_REJECTION_MIN = 500;
+const SMTP_PERMANENT_REJECTION_MAX = 599;
+// Without an SMTP code the adapter gave nothing to classify, so the failure counts as transient.
 function mailResultAsDelivery(result) {
-    return result.ok ? result : { ...result, retryable: true };
+    if (result.ok)
+        return result;
+    const isPermanent = result.smtpCode !== undefined &&
+        result.smtpCode >= SMTP_PERMANENT_REJECTION_MIN &&
+        result.smtpCode <= SMTP_PERMANENT_REJECTION_MAX;
+    return { ok: false, error: result.error, retryable: !isPermanent };
 }
 // Outcome events are plaintext and generic; the request payload's per-dispatch
 // key is erased right after, so the PII dies with the dispatch instead of
@@ -137,7 +144,13 @@ async function sendDispatch(dispatchSpec, target) {
             aggregateId: target.aggregateId,
             errorName: err instanceof Error ? err.name : "unknown",
         });
-        return { ok: false, error: DISPATCH_THREW_ERROR, retryable: true };
+        // A mail adapter has no idempotency key: a throw after the provider accepted the message
+        // would send it again, so only the webhook (which carries one) is retried.
+        return {
+            ok: false,
+            error: DISPATCH_THREW_ERROR,
+            retryable: dispatchSpec.stepKind === "webhook.send",
+        };
     }
 }
 async function abortOnFinalAttempt(err, ctx, recorder, aggregateId, requestedPayload) {

package/dist/step-dispatcher/feature.js

@@ -42,6 +42,7 @@ export function createStepDispatcherFeature() {
             retries: DELIVER_RETRIES,
             backoff: "exponential",
             maxPerTenant: { limit: DELIVER_MAX_PER_TENANT, onLimit: "defer" },
+            schema: deliverJobPayloadSchema,
             escapeHatch: { reason: DELIVER_ESCAPE_HATCH_REASON },
         }, async (payload, ctx) => {
             const { aggregateId } = deliverJobPayloadSchema.parse(payload);

package/dist/step-dispatcher/mail-runner.d.ts

@@ -12,6 +12,7 @@ export type MailDispatchResult = {
 } | {
     readonly ok: false;
     readonly error: string;
+    readonly smtpCode?: number;
 };
 export declare function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult>): void;
 export declare function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult>;

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

@@ -0,0 +1,17 @@
+export type DodoSend = (url: string, init?: RequestInit) => Promise<Response>;
+export type DodoRequest = {
+    readonly method: "GET" | "POST" | "PATCH";
+    /** Path segments interpolated into it must already be encodeURIComponent'ed. */
+    readonly path: string;
+    readonly query?: Readonly<Record<string, string>>;
+    readonly body?: unknown;
+};
+export type DodoTarget = {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+};
+export declare class DodoHttpError extends Error {
+    readonly status: number;
+    constructor(request: DodoRequest, status: number);
+}
+export declare function createDodoHttp(send: DodoSend): (target: DodoTarget, request: DodoRequest) => Promise<unknown>;

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 {};