@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/subscription-paddle/checkout-methods.js

@@ -0,0 +1,85 @@
+// Paddle plugin methods for checkout, portal, cancel and resume. Every response
+// is validated with Zod; every non-2xx throws a PaddleHttpError.
+import { SubscriptionCancelTimings } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+import { signTenantBinding } from "./tenant-binding.js";
+export function paddleSubscriptionPath(providerSubscriptionId) {
+    return `/subscriptions/${encodeURIComponent(providerSubscriptionId)}`;
+}
+function relativeTarget(url) {
+    const parsed = new URL(url);
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+const checkoutResponseSchema = z.object({
+    data: z.object({
+        id: z.string(),
+        checkout: z.object({ url: z.string().nullable() }).nullish(),
+    }),
+});
+export function createPaddleCheckoutSession(runtime) {
+    return async (ctx, options) => {
+        // No Paddle transaction may be created while billing is not live.
+        await runtime.assertBillingLive(ctx);
+        const bindingKey = await runtime.tenantBindingKey(ctx);
+        // No `checkout.url` in the body: Paddle rejects unapproved domains and otherwise
+        // answers with the dashboard's Default Payment Link plus `?_ptxn=`.
+        const { data } = checkoutResponseSchema.parse(await runtime.call(ctx, {
+            method: "POST",
+            path: "/transactions",
+            body: {
+                items: [{ price_id: options.priceId, quantity: 1 }],
+                ...(options.providerCustomerId && { customer_id: options.providerCustomerId }),
+                custom_data: {
+                    tenantId: options.tenantId,
+                    tenantBinding: signTenantBinding(bindingKey, options.tenantId),
+                    ...(options.consentId && { consentId: options.consentId }),
+                },
+            },
+        }));
+        if (!data.checkout?.url) {
+            throw new Error("subscription-paddle: transaction was created without a checkout url");
+        }
+        const url = new URL(data.checkout.url);
+        url.searchParams.set("success", relativeTarget(options.successUrl));
+        url.searchParams.set("cancel", relativeTarget(options.cancelUrl));
+        if (options.locale)
+            url.searchParams.set("locale", options.locale);
+        return { url: url.href };
+    };
+}
+const portalResponseSchema = z.object({
+    data: z.object({ urls: z.object({ general: z.object({ overview: z.string() }) }) }),
+});
+// Paddle's portal has no return url, so options.returnUrl is not used.
+export function createPaddlePortalSession(runtime) {
+    return async (ctx, options) => {
+        const response = portalResponseSchema.parse(await runtime.call(ctx, {
+            method: "POST",
+            path: `/customers/${encodeURIComponent(options.providerCustomerId)}/portal-sessions`,
+            body: {},
+        }));
+        return { url: response.data.urls.general.overview };
+    };
+}
+export function createPaddleCancelSubscription(runtime) {
+    return async (ctx, options) => {
+        await runtime.call(ctx, {
+            method: "POST",
+            path: `${paddleSubscriptionPath(options.providerSubscriptionId)}/cancel`,
+            body: {
+                effective_from: options.when === SubscriptionCancelTimings.periodEnd
+                    ? "next_billing_period"
+                    : "immediately",
+            },
+        });
+    };
+}
+export function createPaddleResumeSubscription(runtime) {
+    return async (ctx, options) => {
+        await runtime.call(ctx, {
+            method: "PATCH",
+            path: paddleSubscriptionPath(options.providerSubscriptionId),
+            body: { scheduled_change: null },
+        });
+    };
+}

package/dist/subscription-paddle/checkout-page.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from "hono";
+import type { SystemQueryFn } from "../shared/index.ts";
+export declare const PADDLE_INIT_SCRIPT = "(function () {\n  var data = document.getElementById(\"kumiko-paddle-checkout\").dataset;\n  var completed = false;\n  if (data.environment === \"sandbox\") Paddle.Environment.set(\"sandbox\");\n  var settings = { displayMode: \"overlay\", successUrl: new URL(data.successUrl, location.origin).href };\n  if (data.locale) settings.locale = data.locale;\n  Paddle.Initialize({\n    token: data.clientToken,\n    checkout: { settings: settings },\n    eventCallback: function (event) {\n      if (event.name === \"checkout.completed\") completed = true;\n      if (event.name === \"checkout.closed\" && !completed) {\n        location.assign(new URL(data.cancelUrl, location.origin).href);\n      }\n    }\n  });\n})();";
+export declare const PADDLE_CHECKOUT_CSP: string;
+/** Same-origin path only: anything else would make the page an open redirector. */
+export declare function safeRedirectPath(raw: string | undefined): string;
+export declare function safeLocale(raw: string | undefined): string | undefined;
+type CheckoutPageValues = {
+    readonly clientToken: string;
+    readonly environment: string;
+    readonly successUrl: string;
+    readonly cancelUrl: string;
+    readonly locale: string | undefined;
+};
+export declare function renderCheckoutPage(values: CheckoutPageValues): string;
+export declare function servePaddleCheckoutPage(c: Context, { systemQuery }: {
+    readonly systemQuery: SystemQueryFn;
+}): Promise<Response>;
+export {};

package/dist/subscription-paddle/checkout-page.js

@@ -0,0 +1,126 @@
+// The Default Payment Link page. Paddle has no hosted checkout, so Paddle.js
+// runs on this page and opens the overlay for the `?_ptxn=` transaction by
+// itself. The page never reflects `_ptxn`.
+import { createHash } from "node:crypto";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
+import * as z from "zod";
+import { PADDLE_CHECKOUT_CONFIG_QUERY, PaddleEnvironments } from "./constants.js";
+const PADDLE_JS_URL = "https://cdn.paddle.com/paddle/v2/paddle.js";
+const MAX_REDIRECT_LENGTH = 2048;
+const FALLBACK_REDIRECT = "/";
+const LOCALE_PATTERN = /^[a-z]{2}(-[A-Z]{2})?$/;
+// Control characters, which browsers strip or reinterpret inside URLs.
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+// Static on purpose: its sha256 goes into the CSP, so nothing may be interpolated.
+export const PADDLE_INIT_SCRIPT = `(function () {
+  var data = document.getElementById("kumiko-paddle-checkout").dataset;
+  var completed = false;
+  if (data.environment === "sandbox") Paddle.Environment.set("sandbox");
+  var settings = { displayMode: "overlay", successUrl: new URL(data.successUrl, location.origin).href };
+  if (data.locale) settings.locale = data.locale;
+  Paddle.Initialize({
+    token: data.clientToken,
+    checkout: { settings: settings },
+    eventCallback: function (event) {
+      if (event.name === "checkout.completed") completed = true;
+      if (event.name === "checkout.closed" && !completed) {
+        location.assign(new URL(data.cancelUrl, location.origin).href);
+      }
+    }
+  });
+})();`;
+const INIT_SCRIPT_HASH = createHash("sha256").update(PADDLE_INIT_SCRIPT).digest("base64");
+export const PADDLE_CHECKOUT_CSP = [
+    "default-src 'none'",
+    `script-src 'sha256-${INIT_SCRIPT_HASH}' https://cdn.paddle.com`,
+    "style-src 'unsafe-inline' https://cdn.paddle.com",
+    "img-src data: https://*.paddle.com",
+    "connect-src https://*.paddle.com",
+    "frame-src https://buy.paddle.com https://sandbox-buy.paddle.com",
+    "frame-ancestors 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "object-src 'none'",
+].join("; ");
+// Own header set: `securePageHeaders` pins `script-src 'none'`. The global
+// wrapper only fills headers that are absent, so these win.
+function pageHeaders() {
+    return {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+        "x-frame-options": "DENY",
+        "x-content-type-options": "nosniff",
+        "content-security-policy": PADDLE_CHECKOUT_CSP,
+    };
+}
+/** Same-origin path only: anything else would make the page an open redirector. */
+export function safeRedirectPath(raw) {
+    if (raw === undefined ||
+        raw.length > MAX_REDIRECT_LENGTH ||
+        !raw.startsWith("/") ||
+        raw.startsWith("//") ||
+        raw.startsWith("/\\") ||
+        CONTROL_CHARACTERS.test(raw)) {
+        return FALLBACK_REDIRECT;
+    }
+    return raw;
+}
+export function safeLocale(raw) {
+    return raw !== undefined && LOCALE_PATTERN.test(raw) ? raw : undefined;
+}
+export function renderCheckoutPage(values) {
+    const attributesHtml = [
+        ["data-client-token", values.clientToken],
+        ["data-environment", values.environment],
+        ["data-success-url", values.successUrl],
+        ["data-cancel-url", values.cancelUrl],
+        ...(values.locale ? [["data-locale", values.locale]] : []),
+    ]
+        .map(([name, value]) => `${name}="${escapeHtml(value ?? "")}"`)
+        .join(" ");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Checkout</title>
+</head>
+<body>
+<div id="kumiko-paddle-checkout" ${attributesHtml}></div>
+<noscript>JavaScript is required to complete the checkout.</noscript>
+<script src="${PADDLE_JS_URL}"></script>
+<script>${PADDLE_INIT_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+const checkoutConfigSchema = z.object({
+    clientToken: z.string().nullable(),
+    environment: z.string(),
+});
+export async function servePaddleCheckoutPage(c, { systemQuery }) {
+    let config;
+    try {
+        config = checkoutConfigSchema.parse(await systemQuery(PADDLE_CHECKOUT_CONFIG_QUERY, {}, SYSTEM_TENANT_ID));
+    }
+    catch {
+        return unavailable(c);
+    }
+    if (!config.clientToken)
+        return unavailable(c);
+    const html = renderCheckoutPage({
+        clientToken: config.clientToken,
+        environment: config.environment === PaddleEnvironments.live
+            ? PaddleEnvironments.live
+            : PaddleEnvironments.sandbox,
+        successUrl: safeRedirectPath(c.req.query("success")),
+        cancelUrl: safeRedirectPath(c.req.query("cancel")),
+        locale: safeLocale(c.req.query("locale")),
+    });
+    return new Response(html, { status: 200, headers: pageHeaders() });
+}
+function unavailable(c) {
+    return c.text("checkout unavailable", 503, { "cache-control": "no-store" });
+}

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

@@ -0,0 +1,24 @@
+export type PaddleSend = (url: string, init?: RequestInit) => Promise<Response>;
+export type PaddleRequest = {
+    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 PaddleTarget = {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+};
+type PaddleErrorDetails = {
+    readonly type?: string;
+    readonly code?: string;
+};
+export declare class PaddleHttpError extends Error {
+    readonly status: number;
+    readonly paddleErrorType?: string;
+    readonly paddleErrorCode?: string;
+    constructor(request: PaddleRequest, status: number, details?: PaddleErrorDetails);
+}
+export declare function createPaddleHttp(send: PaddleSend): (target: PaddleTarget, request: PaddleRequest) => Promise<unknown>;
+export {};

package/dist/subscription-paddle/client.js

@@ -0,0 +1,60 @@
+// Thin JSON-over-fetch client for the Paddle Billing 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, parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+const PADDLE_API_VERSION = "1";
+const paddleErrorBodySchema = z.object({ error: z.object({ type: z.string(), code: z.string() }) });
+// Both values come from outside; anything beyond a plain identifier is dropped so
+// no customer text reaches the logs.
+const ERROR_IDENTIFIER = /^[a-z0-9_]{1,100}$/;
+function paddleErrorDetails(bodyText) {
+    const parsed = paddleErrorBodySchema.safeParse(parseJsonSafe(bodyText, undefined));
+    if (!parsed.success)
+        return {};
+    const { type, code } = parsed.data.error;
+    return {
+        ...(ERROR_IDENTIFIER.test(type) && { type }),
+        ...(ERROR_IDENTIFIER.test(code) && { code }),
+    };
+}
+// Carries only the status and Paddle's error type and code, never `detail`, the
+// rest of the body or the key: they can hold customer data or secrets.
+export class PaddleHttpError extends Error {
+    status;
+    paddleErrorType;
+    paddleErrorCode;
+    constructor(request, status, details = {}) {
+        const suffix = [details.type && `type ${details.type}`, details.code && `code ${details.code}`]
+            .filter(Boolean)
+            .join(", ");
+        super(`subscription-paddle: ${request.method} ${request.path} failed with status ${status}${suffix ? ` (${suffix})` : ""}`);
+        this.name = "PaddleHttpError";
+        this.status = status;
+        if (details.type)
+            this.paddleErrorType = details.type;
+        if (details.code)
+            this.paddleErrorCode = details.code;
+    }
+}
+export function createPaddleHttp(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",
+                "Content-Type": "application/json",
+                "Paddle-Version": PADDLE_API_VERSION,
+            },
+            ...(request.body !== undefined && { body: JSON.stringify(request.body) }),
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new PaddleHttpError(request, response.status, paddleErrorDetails(text));
+        return text.length === 0
+            ? null
+            : parseJsonOrThrow(text, "subscription-paddle response");
+    };
+}

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

@@ -0,0 +1,16 @@
+export declare const SUBSCRIPTION_PADDLE_FEATURE: "subscription-paddle";
+export declare const PADDLE_PROVIDER_NAME: "paddle";
+export declare const PADDLE_CHECKOUT_PATH: "/billing/paddle-checkout";
+export declare const PADDLE_API_KEY_CONFIG: "api-key";
+export declare const PADDLE_WEBHOOK_SECRET_CONFIG: "webhook-secret";
+export declare const PADDLE_TENANT_BINDING_KEY_CONFIG: "tenant-binding-key";
+export declare const PADDLE_CLIENT_TOKEN_CONFIG: "client-token";
+export declare const PADDLE_ENVIRONMENT_CONFIG: "environment";
+export declare const PADDLE_BILLING_LIVE_CONFIG: "billingLive";
+export declare const PADDLE_CHECKOUT_CONFIG_QUERY: string;
+export declare const PaddleEnvironments: {
+    readonly sandbox: "sandbox";
+    readonly live: "live";
+};
+export type PaddleEnvironment = (typeof PaddleEnvironments)[keyof typeof PaddleEnvironments];
+export declare const PADDLE_BASE_URLS: Readonly<Record<PaddleEnvironment, string>>;

package/dist/subscription-paddle/constants.js

@@ -0,0 +1,25 @@
+export const SUBSCRIPTION_PADDLE_FEATURE = "subscription-paddle";
+// Must match the last path segment of the webhook URL (`/webhooks/subscription/paddle` via the boot option).
+export const PADDLE_PROVIDER_NAME = "paddle";
+// Paddle has no hosted checkout page, so the feature serves the Default Payment
+// Link itself; the same path goes into the Paddle dashboard.
+export const PADDLE_CHECKOUT_PATH = "/billing/paddle-checkout";
+// Config-key short-names, qualified to `subscription-paddle:config:<name>` at
+// registry-build. api-key, webhook-secret and tenant-binding-key are backing:"secrets".
+export const PADDLE_API_KEY_CONFIG = "api-key";
+export const PADDLE_WEBHOOK_SECRET_CONFIG = "webhook-secret";
+export const PADDLE_TENANT_BINDING_KEY_CONFIG = "tenant-binding-key";
+export const PADDLE_CLIENT_TOKEN_CONFIG = "client-token";
+export const PADDLE_ENVIRONMENT_CONFIG = "environment";
+export const PADDLE_BILLING_LIVE_CONFIG = "billingLive";
+export const PADDLE_CHECKOUT_CONFIG_QUERY = `${SUBSCRIPTION_PADDLE_FEATURE}:query:checkout-config`;
+// Separate from billingLive on purpose: staging runs Paddle's sandbox with
+// billingLive on, production flips both.
+export const PaddleEnvironments = {
+    sandbox: "sandbox",
+    live: "live",
+};
+export const PADDLE_BASE_URLS = {
+    sandbox: "https://sandbox-api.paddle.com",
+    live: "https://api.paddle.com",
+};

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

@@ -0,0 +1,49 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type FeatureWithEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import * as z from "zod";
+import type { PaddleSend } from "./client.ts";
+/** Bridge contract: all fields are optional fallbacks for the config store. */
+export declare const subscriptionPaddleEnvSchema: z.ZodObject<{
+    PADDLE_API_KEY: z.ZodOptional<z.ZodString>;
+    PADDLE_WEBHOOK_SECRET: z.ZodOptional<z.ZodString>;
+    PADDLE_TENANT_BINDING_KEY: z.ZodOptional<z.ZodString>;
+    PADDLE_CLIENT_TOKEN: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PaddlePriceEnvShape<TPrice extends string> = {
+    [Key in `PADDLE_PRICE_${TPrice}`]: z.ZodOptional<z.ZodString>;
+};
+/** Paddle env block plus one `PADDLE_PRICE_<NAME>` slot per plan price the app
+ *  maps to a tier, e.g. `paddleEnvSchema({ prices: ["PRO", "TEAM"] })`.
+ *  Shares its bridge fields with `subscriptionPaddleEnvSchema`, so spreading
+ *  it into `composeEnvSchema({ extend })` next to the mounted feature is no
+ *  key clash. */
+export declare function paddleEnvSchema<const TPrice extends string>(options: {
+    readonly prices: readonly TPrice[];
+}): z.ZodObject<{
+    PADDLE_API_KEY: z.ZodOptional<z.ZodString>;
+    PADDLE_WEBHOOK_SECRET: z.ZodOptional<z.ZodString>;
+    PADDLE_TENANT_BINDING_KEY: z.ZodOptional<z.ZodString>;
+    PADDLE_CLIENT_TOKEN: z.ZodOptional<z.ZodString>;
+} & PaddlePriceEnvShape<TPrice> extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strip>;
+export type SubscriptionPaddleOptions = {
+    /** 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;
+    /** Bridge-fallback tenant binding key; the `tenant-binding-key` config key wins when set. */
+    readonly tenantBindingKey?: string;
+    /** Bridge-fallback Paddle.js client token; the `client-token` config key wins when set. */
+    readonly clientToken?: string;
+    /** Paddle price id → app tier name. Prices absent here drop the event. */
+    readonly priceToTier?: Readonly<Record<string, string>>;
+    /** Price 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?: PaddleSend;
+    /** Epoch milliseconds for the plan-switch preview timestamp. Test seam. */
+    readonly now?: () => number;
+    /** Unix seconds for the webhook tolerance window. Test seam. */
+    readonly nowSeconds?: () => number;
+};
+export declare function createSubscriptionPaddleFeature(options?: SubscriptionPaddleOptions): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionPaddleEnvSchema.shape>;
+export {};

package/dist/subscription-paddle/feature.js

@@ -0,0 +1,192 @@
+// kumiko-feature-version: 1
+//
+// subscription-paddle — Paddle Billing (merchant of record) plugin for the
+// billing-foundation plugin API. Credentials, the billing-live master switch and
+// the API environment (sandbox | live) are config keys resolved at call time, like
+// subscription-stripe. The `apiKey` / `webhookSecret` / `tenantBindingKey` /
+// `clientToken` options are env→config 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 { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { makeCheckoutConfigQuery } from "./checkout-config.query.js";
+import { createPaddleCancelSubscription, createPaddleCheckoutSession, createPaddlePortalSession, createPaddleResumeSubscription, } from "./checkout-methods.js";
+import { servePaddleCheckoutPage } from "./checkout-page.js";
+import { PADDLE_API_KEY_CONFIG, PADDLE_BILLING_LIVE_CONFIG, PADDLE_CLIENT_TOKEN_CONFIG, PADDLE_ENVIRONMENT_CONFIG, PADDLE_PROVIDER_NAME, PADDLE_TENANT_BINDING_KEY_CONFIG, PADDLE_WEBHOOK_SECRET_CONFIG, PaddleEnvironments, SUBSCRIPTION_PADDLE_FEATURE, } from "./constants.js";
+import { createPaddleApplyPlanSwitch, createPaddlePreviewPlanSwitch, createPaddleRetrieveSubscription, } from "./plan-switch-methods.js";
+import { createPaddlePriceCache, createPaddleRetrievePrices } from "./price-methods.js";
+import { createPaddleRuntimes } from "./runtime.js";
+import { verifyAndParsePaddleWebhook } from "./webhook-events.js";
+/** Bridge contract: all fields are optional fallbacks for the config store. */
+export const subscriptionPaddleEnvSchema = z.object({
+    PADDLE_API_KEY: z
+        .string()
+        .min(1)
+        .describe("Paddle API key. Bridge-fallback — prefer the secret.")
+        .meta({ kumiko: { pulumi: { secret: true } } })
+        .optional(),
+    PADDLE_WEBHOOK_SECRET: z
+        .string()
+        .min(1)
+        .describe("Paddle notification secret (`pdl_ntfset_...`). Bridge-fallback — prefer the secret.")
+        .meta({ kumiko: { pulumi: { secret: true } } })
+        .optional(),
+    PADDLE_TENANT_BINDING_KEY: z
+        .string()
+        .min(1)
+        .describe("Server-only HMAC key binding a Paddle checkout to its tenant. Bridge-fallback — prefer the secret.")
+        .meta({ kumiko: { pulumi: { secret: true } } })
+        .optional(),
+    PADDLE_CLIENT_TOKEN: z
+        .string()
+        .regex(/^(test|live)_/, "PADDLE_CLIENT_TOKEN must start with 'test_' or 'live_'")
+        .describe("Paddle.js client-side token (public). Bridge-fallback for the config key.")
+        .optional(),
+});
+/** Paddle env block plus one `PADDLE_PRICE_<NAME>` slot per plan price the app
+ *  maps to a tier, e.g. `paddleEnvSchema({ prices: ["PRO", "TEAM"] })`.
+ *  Shares its bridge fields with `subscriptionPaddleEnvSchema`, so spreading
+ *  it into `composeEnvSchema({ extend })` next to the mounted feature is no
+ *  key clash. */
+export function paddleEnvSchema(options) {
+    const priceShape = Object.fromEntries(options.prices.map((price) => [
+        `PADDLE_PRICE_${price}`,
+        z
+            .string()
+            .regex(/^pri_/, `PADDLE_PRICE_${price} must start with 'pri_'`)
+            .optional()
+            .describe(`Paddle price id (\`pri_...\`) of the ${price} plan.`),
+    ]));
+    return z.object({ ...subscriptionPaddleEnvSchema.shape, ...priceShape });
+}
+// 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-paddle: oneOffPriceIds must not contain an empty string");
+        }
+        if (seen.has(priceId)) {
+            throw new Error(`subscription-paddle: duplicate oneOffPriceIds entry "${priceId}"`);
+        }
+        seen.add(priceId);
+    }
+}
+export function createSubscriptionPaddleFeature(options = {}) {
+    validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+    const now = options.now ?? (() => Temporal.Now.instant().epochMilliseconds);
+    const feature = defineFeature(SUBSCRIPTION_PADDLE_FEATURE, (r) => {
+        r.describe('Paddle Billing provider plugin for `billing-foundation`. Paddle 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, webhook secret and tenant binding key from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant), the public Paddle.js `client-token`, a `billingLive` master switch and an `environment` key (sandbox | live). `environment` is its own key because Paddle serves sandbox and live from different API hosts and a live key must never hit the sandbox host or the other way round; `billingLive` only decides whether checkouts are offered at all. All of them 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 `createSubscriptionPaddleFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret`/`tenantBindingKey`/`clientToken` options are env to config bridge fallbacks (`PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TENANT_BINDING_KEY`, `PADDLE_CLIENT_TOKEN`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, and billing counts as enabled only with API key and binding key present. Webhooks arrive at `/webhooks/subscription/paddle` when mounted through the server-runtime `billing.paddle` boot option, or at `/api/subscription/webhook/paddle` when `createSubscriptionWebhookRoute` is mounted by hand and are verified with the `Paddle-Signature` header (HMAC-SHA256 over `ts:rawBody` keyed with the raw secret, any `h1` may match, 5 minute tolerance). Paddle.js can open checkouts with arbitrary `customData` from the browser, so `custom_data.tenantId` is only trusted together with `tenantBinding`, an HMAC of the tenant id under the binding key; events without a valid binding, for prices outside `priceToTier` or without a tenant are dropped. Rotating the binding key makes the webhooks of existing subscriptions fail that check until they are re-bound. Paddle has no hosted checkout page, so the feature serves the Default Payment Link itself at `/billing/paddle-checkout` (the Default Payment Link in the Paddle dashboard must point to `<APP_BASE_URL>/billing/paddle-checkout`; it is the only source, because checkouts are created without a `checkout.url`). Create subscription prices in the Paddle catalog with quantity minimum and maximum 1; for one-off packs set the quantity limits on purpose, because the payment event carries `quantity` and the app has to multiply its credits by it: an anonymous page with its own CSP that loads Paddle.js from cdn.paddle.com, the one external script this framework allows, and opens the overlay for the transaction. Implements checkout, customer portal, cancel and resume, `retrievePrices` (batched, 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 `subscription.updated` webhook to move the tier.');
+        r.uiHints({
+            displayLabel: "Billing · Paddle",
+            category: "billing",
+            recommended: false,
+        });
+        r.requires({ features: ["billing-foundation"] });
+        r.requires({ features: ["config"] });
+        r.requires({ features: ["secrets"] });
+        r.envSchema(subscriptionPaddleEnvSchema);
+        const configKeys = r.config({
+            keys: {
+                [PADDLE_API_KEY_CONFIG]: createSystemConfig("text", {
+                    backing: "secrets",
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-paddle.api-key", icon: "key", order: 1 },
+                }),
+                [PADDLE_WEBHOOK_SECRET_CONFIG]: createSystemConfig("text", {
+                    backing: "secrets",
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-paddle.webhook-secret", icon: "shield", order: 2 },
+                }),
+                [PADDLE_TENANT_BINDING_KEY_CONFIG]: createSystemConfig("text", {
+                    backing: "secrets",
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-paddle.tenant-binding-key", icon: "lock", order: 3 },
+                }),
+                [PADDLE_CLIENT_TOKEN_CONFIG]: createSystemConfig("text", {
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-paddle.client-token", icon: "settings", order: 4 },
+                }),
+                [PADDLE_ENVIRONMENT_CONFIG]: createSystemConfig("select", {
+                    default: PaddleEnvironments.sandbox,
+                    options: [PaddleEnvironments.sandbox, PaddleEnvironments.live],
+                    write: access.systemAdmin,
+                    read: access.admin,
+                    mask: { title: "subscription-paddle.environment", icon: "server", order: 5 },
+                }),
+                [PADDLE_BILLING_LIVE_CONFIG]: createSystemConfig("boolean", {
+                    default: false,
+                    write: access.privileged,
+                    read: access.admin,
+                    mask: { title: "subscription-paddle.billing-live", icon: "rocket", order: 6 },
+                }),
+            },
+        });
+        r.translations({
+            keys: {
+                "subscription-paddle.api-key": { en: "Paddle API key" },
+                "subscription-paddle.webhook-secret": { en: "Paddle webhook secret" },
+                "subscription-paddle.tenant-binding-key": { en: "Paddle tenant binding key" },
+                "subscription-paddle.client-token": { en: "Paddle client-side token" },
+                "subscription-paddle.environment": { en: "Paddle environment" },
+                "subscription-paddle.billing-live": { en: "Live billing" },
+                "subscription-paddle.settings": { en: "Paddle" },
+                "screen:subscription-paddle-system.title": { en: "Paddle" },
+            },
+        });
+        const priceToTier = options.priceToTier ?? {};
+        const runtimes = createPaddleRuntimes({
+            apiKeyHandle: configKeys[PADDLE_API_KEY_CONFIG],
+            webhookSecretHandle: configKeys[PADDLE_WEBHOOK_SECRET_CONFIG],
+            tenantBindingKeyHandle: configKeys[PADDLE_TENANT_BINDING_KEY_CONFIG],
+            clientTokenHandle: configKeys[PADDLE_CLIENT_TOKEN_CONFIG],
+            billingLiveHandle: configKeys[PADDLE_BILLING_LIVE_CONFIG],
+            environmentHandle: configKeys[PADDLE_ENVIRONMENT_CONFIG],
+            send: options.send ?? egress({ kind: "external" }),
+            fallback: {
+                ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+                ...(options.webhookSecret !== undefined && { webhookSecret: options.webhookSecret }),
+                ...(options.tenantBindingKey !== undefined && {
+                    tenantBindingKey: options.tenantBindingKey,
+                }),
+                ...(options.clientToken !== undefined && { clientToken: options.clientToken }),
+            },
+        });
+        r.queryHandler(makeCheckoutConfigQuery(runtimes.readCheckoutConfig));
+        r.httpRoute({
+            method: "GET",
+            // Literal for the feature-AST extractor; must equal PADDLE_CHECKOUT_PATH (integration test).
+            path: "/billing/paddle-checkout",
+            anonymous: true,
+            rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+            handler: (c, deps) => servePaddleCheckoutPage(c, deps),
+        });
+        const plugin = {
+            displayName: "Paddle",
+            verifyAndParseWebhook: verifyAndParsePaddleWebhook(runtimes.webhook, {
+                priceToTier,
+                ...(options.nowSeconds && { nowSeconds: options.nowSeconds }),
+            }),
+            createCheckoutSession: createPaddleCheckoutSession(runtimes.ctx),
+            createPortalSession: createPaddlePortalSession(runtimes.ctx),
+            cancelSubscription: createPaddleCancelSubscription(runtimes.ctx),
+            resumeSubscription: createPaddleResumeSubscription(runtimes.ctx),
+            priceToTier,
+            oneOffPriceIds: options.oneOffPriceIds ?? [],
+            isBillingEnabled: runtimes.ctx.isBillingEnabled,
+            retrievePrices: createPaddleRetrievePrices(runtimes.ctx, createPaddlePriceCache({ now })),
+            retrieveSubscription: createPaddleRetrieveSubscription(runtimes.ctx, { priceToTier }),
+            previewPlanSwitch: createPaddlePreviewPlanSwitch(runtimes.ctx, now),
+            applyPlanSwitch: createPaddleApplyPlanSwitch(runtimes.ctx),
+        };
+        r.useExtension("subscriptionProvider", PADDLE_PROVIDER_NAME, plugin);
+        return { configKeys };
+    });
+    return featureWithEnvSchema(feature, subscriptionPaddleEnvSchema);
+}

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

@@ -0,0 +1,2 @@
+export { PADDLE_BASE_URLS, PADDLE_CHECKOUT_PATH, PADDLE_PROVIDER_NAME, type PaddleEnvironment, PaddleEnvironments, SUBSCRIPTION_PADDLE_FEATURE, } from "./constants.ts";
+export { createSubscriptionPaddleFeature, paddleEnvSchema, type SubscriptionPaddleOptions, subscriptionPaddleEnvSchema, } from "./feature.ts";

package/dist/subscription-paddle/index.js

@@ -0,0 +1,4 @@
+// Public API of the subscription-paddle bundled feature. The webhook verifier,
+// client and plugin methods are internal to feature.ts.
+export { PADDLE_BASE_URLS, PADDLE_CHECKOUT_PATH, PADDLE_PROVIDER_NAME, PaddleEnvironments, SUBSCRIPTION_PADDLE_FEATURE, } from "./constants.js";
+export { createSubscriptionPaddleFeature, paddleEnvSchema, subscriptionPaddleEnvSchema, } from "./feature.js";

package/dist/subscription-paddle/plan-switch-methods.d.ts

@@ -0,0 +1,6 @@
+import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
+export declare function createPaddlePreviewPlanSwitch(runtime: PaddleCtxRuntime, now: () => number): PaddlePluginMethod<"previewPlanSwitch">;
+export declare function createPaddleApplyPlanSwitch(runtime: PaddleCtxRuntime): PaddlePluginMethod<"applyPlanSwitch">;
+export declare function createPaddleRetrieveSubscription(runtime: PaddleCtxRuntime, options: {
+    readonly priceToTier: Readonly<Record<string, string>>;
+}): PaddlePluginMethod<"retrieveSubscription">;