@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

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

@@ -0,0 +1,265 @@
+// 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 type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  access,
+  createSystemConfig,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type FeatureWithEnvSchema, 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.ts";
+import {
+  createPaddleCancelSubscription,
+  createPaddleCheckoutSession,
+  createPaddlePortalSession,
+  createPaddleResumeSubscription,
+} from "./checkout-methods.ts";
+import { servePaddleCheckoutPage } from "./checkout-page.ts";
+import type { PaddleSend } from "./client.ts";
+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.ts";
+import {
+  createPaddleApplyPlanSwitch,
+  createPaddlePreviewPlanSwitch,
+  createPaddleRetrieveSubscription,
+} from "./plan-switch-methods.ts";
+import { createPaddlePriceCache, createPaddleRetrievePrices } from "./price-methods.ts";
+import { createPaddleRuntimes } from "./runtime.ts";
+import { verifyAndParsePaddleWebhook } from "./webhook-events.ts";
+
+/** 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(),
+});
+
+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 function paddleEnvSchema<const TPrice extends string>(options: {
+  readonly prices: readonly TPrice[];
+}) {
+  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.`),
+    ]),
+    // @cast-boundary schema-walk — Object.fromEntries widens to an index signature; the entries are exactly one optional string per listed price.
+  ) as PaddlePriceEnvShape<TPrice>;
+  return z.object({ ...subscriptionPaddleEnvSchema.shape, ...priceShape });
+}
+
+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;
+};
+
+// 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: readonly string[]): void {
+  const seen = new Set<string>();
+  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: SubscriptionPaddleOptions = {},
+): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionPaddleEnvSchema.shape> {
+  validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+  const now = options.now ?? (() => Temporal.Now.instant().epochMilliseconds);
+  const feature: FeatureDefinition = 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: SubscriptionProviderPlugin = {
+      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/packages/bundled-features/src/subscription-paddle/index.ts

@@ -0,0 +1,17 @@
+// 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,
+  type PaddleEnvironment,
+  PaddleEnvironments,
+  SUBSCRIPTION_PADDLE_FEATURE,
+} from "./constants.ts";
+export {
+  createSubscriptionPaddleFeature,
+  paddleEnvSchema,
+  type SubscriptionPaddleOptions,
+  subscriptionPaddleEnvSchema,
+} from "./feature.ts";

package/packages/bundled-features/src/subscription-paddle/plan-switch-methods.ts

@@ -0,0 +1,135 @@
+// Paddle in-app plan switch (preview + apply) and retrieveSubscription.
+
+import type {
+  PlanSwitchPreview,
+  ProviderSubscriptionSnapshot,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { paddleSubscriptionPath } from "./checkout-methods.ts";
+import { PaddleHttpError } from "./client.ts";
+import { paddleAmountSchema } from "./price-methods.ts";
+import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
+import { mapPaddleSubscriptionState, paddleSubscriptionSchema } from "./subscription-state.ts";
+import { signTenantBinding } from "./tenant-binding.ts";
+
+const NOT_FOUND = 404;
+
+function parseAmount(amount: string): number {
+  return Number.parseInt(amount, 10);
+}
+
+const previewResponseSchema = z.object({
+  data: z.object({
+    currency_code: z.string(),
+    immediate_transaction: z
+      .object({
+        details: z.object({
+          totals: z.object({
+            grand_total: paddleAmountSchema,
+            tax: paddleAmountSchema,
+            currency_code: z.string().nullish(),
+          }),
+        }),
+      })
+      .nullish(),
+    recurring_transaction_details: z
+      .object({
+        // `total` is the full period price incl. tax; `grand_total` is already
+        // reduced by credit, so it would understate the recurring price.
+        totals: z.object({
+          total: paddleAmountSchema.nullish(),
+          tax: paddleAmountSchema.nullish(),
+        }),
+      })
+      .nullish(),
+    update_summary: z.object({ credit: z.object({ amount: paddleAmountSchema }) }).nullish(),
+  }),
+});
+
+function changePlanBody(targetPriceId: string) {
+  return {
+    items: [{ price_id: targetPriceId, quantity: 1 }],
+    proration_billing_mode: "prorated_immediately",
+  };
+}
+
+export function createPaddlePreviewPlanSwitch(
+  runtime: PaddleCtxRuntime,
+  now: () => number,
+): PaddlePluginMethod<"previewPlanSwitch"> {
+  return async (ctx, options): Promise<PlanSwitchPreview> => {
+    const { data } = previewResponseSchema.parse(
+      await runtime.call(ctx, {
+        method: "PATCH",
+        path: `${paddleSubscriptionPath(options.providerSubscriptionId)}/preview`,
+        body: changePlanBody(options.targetPriceId),
+      }),
+    );
+    const totals = data.immediate_transaction?.details.totals;
+    const recurring = data.recurring_transaction_details?.totals;
+    return {
+      amountDueNow: totals ? parseAmount(totals.grand_total) : 0,
+      tax: totals ? parseAmount(totals.tax) : null,
+      currency: (totals?.currency_code ?? data.currency_code).toLowerCase(),
+      credit: data.update_summary ? parseAmount(data.update_summary.credit.amount) : 0,
+      ...(recurring?.total != null && {
+        recurringAmount: parseAmount(recurring.total),
+        recurringTax: recurring.tax != null ? parseAmount(recurring.tax) : null,
+      }),
+      effectiveAt: Temporal.Instant.fromEpochMilliseconds(now()).toString(),
+    };
+  };
+}
+
+// The switch itself arrives later as a subscription.updated webhook;
+// prevent_change keeps the old plan if the immediate charge fails. PATCH
+// replaces custom_data as a whole, so the tenant binding is sent again.
+export function createPaddleApplyPlanSwitch(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"applyPlanSwitch"> {
+  return async (ctx, options) => {
+    const bindingKey = await runtime.tenantBindingKey(ctx);
+    await runtime.call(ctx, {
+      method: "PATCH",
+      path: paddleSubscriptionPath(options.providerSubscriptionId),
+      body: {
+        ...changePlanBody(options.targetPriceId),
+        on_payment_failure: "prevent_change",
+        custom_data: {
+          tenantId: options.tenantId,
+          tenantBinding: signTenantBinding(bindingKey, options.tenantId),
+          ...(options.consentId && { consentId: options.consentId }),
+        },
+      },
+    });
+  };
+}
+
+const subscriptionResponseSchema = z.object({ data: paddleSubscriptionSchema });
+
+export function createPaddleRetrieveSubscription(
+  runtime: PaddleCtxRuntime,
+  options: { readonly priceToTier: Readonly<Record<string, string>> },
+): PaddlePluginMethod<"retrieveSubscription"> {
+  return async (ctx, providerSubscriptionId): Promise<ProviderSubscriptionSnapshot | null> => {
+    let raw: unknown;
+    try {
+      raw = await runtime.call(ctx, {
+        method: "GET",
+        path: paddleSubscriptionPath(providerSubscriptionId),
+      });
+    } catch (error) {
+      if (error instanceof PaddleHttpError && error.status === NOT_FOUND) return null;
+      throw error;
+    }
+    const { data: sub } = subscriptionResponseSchema.parse(raw);
+    const state = mapPaddleSubscriptionState(sub, options.priceToTier);
+    if (!state) return null;
+    return {
+      providerCustomerId: sub.customer_id,
+      providerSubscriptionId: sub.id,
+      ...state,
+    };
+  };
+}

package/packages/bundled-features/src/subscription-paddle/price-methods.ts

@@ -0,0 +1,148 @@
+// Paddle price lookup for the billing-plans catalog: one batched request for all
+// cache misses, cached per price id.
+
+import {
+  KNOWN_RECURRING_INTERVALS,
+  type ProviderPrice,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
+
+const PRICES_PER_REQUEST = 200;
+
+/** Paddle sends amounts as integer strings in the smallest currency unit. */
+export const paddleAmountSchema = z.string().regex(/^-?\d+$/);
+
+const customDataSchema = z.record(z.string(), z.unknown()).nullish();
+
+const paddlePriceSchema = z.object({
+  id: z.string().min(1),
+  unit_price: z.object({ amount: paddleAmountSchema, currency_code: z.string() }),
+  billing_cycle: z.object({ interval: z.string(), frequency: z.number() }).nullable(),
+  status: z.string(),
+  custom_data: customDataSchema,
+  product: z.object({ custom_data: customDataSchema }).nullish(),
+});
+type PaddlePrice = z.infer<typeof paddlePriceSchema>;
+
+const pricesResponseSchema = z.object({ data: z.array(paddlePriceSchema) });
+
+function stringEntries(
+  customData: Readonly<Record<string, unknown>> | null | undefined,
+): Array<[string, string]> {
+  return Object.entries(customData ?? {}).flatMap(([key, value]): Array<[string, string]> => {
+    if (typeof value === "string") return [[key, value]];
+    if (typeof value === "number") return [[key, String(value)]];
+    return [];
+  });
+}
+
+// Price custom data wins over the product's.
+function metadataOf(price: PaddlePrice): Record<string, string> {
+  return Object.fromEntries([
+    ...stringEntries(price.product?.custom_data),
+    ...stringEntries(price.custom_data),
+  ]);
+}
+
+function mapPaddlePrice(price: PaddlePrice): ProviderPrice {
+  const base = {
+    priceId: price.id,
+    unitAmount: Number.parseInt(price.unit_price.amount, 10),
+    currency: price.unit_price.currency_code.toLowerCase(),
+    active: price.status === "active",
+    metadata: metadataOf(price),
+  };
+  const cycle = price.billing_cycle;
+  if (!cycle) return { ...base, interval: null, intervalCount: 1 };
+  const interval = KNOWN_RECURRING_INTERVALS.find((known) => known === cycle.interval) ?? null;
+  return { ...base, interval, intervalCount: interval ? cycle.frequency : null };
+}
+
+export type PaddlePriceCache = {
+  readonly get: (priceId: string) => ProviderPrice | undefined;
+  readonly set: (priceId: string, price: ProviderPrice) => void;
+};
+
+export type PaddlePriceCacheOptions = {
+  readonly ttlMs?: number;
+  readonly now?: () => number;
+};
+
+// Keyed by price 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.
+export function createPaddlePriceCache({
+  ttlMs = 600_000,
+  now = () => Temporal.Now.instant().epochMilliseconds,
+}: PaddlePriceCacheOptions = {}): PaddlePriceCache {
+  const store = new Map<string, { readonly price: ProviderPrice; readonly expiresAt: number }>();
+  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 });
+    },
+  };
+}
+
+function chunked<T>(items: readonly T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let start = 0; start < items.length; start += size) {
+    chunks.push(items.slice(start, start + size));
+  }
+  return chunks;
+}
+
+async function fillPriceCache(
+  runtime: PaddleCtxRuntime,
+  cache: PaddlePriceCache,
+  ctx: HandlerContext,
+  priceIds: readonly string[],
+): Promise<void> {
+  const misses = [...new Set(priceIds.filter((priceId) => cache.get(priceId) === undefined))];
+  const settled = await Promise.allSettled(
+    chunked(misses, PRICES_PER_REQUEST).map(async (ids) =>
+      pricesResponseSchema.parse(
+        await runtime.call(ctx, {
+          method: "GET",
+          path: "/prices",
+          query: {
+            id: ids.join(","),
+            include: "product",
+            status: "active,archived",
+            per_page: String(PRICES_PER_REQUEST),
+          },
+        }),
+      ),
+    ),
+  );
+  for (const outcome of settled) {
+    if (outcome.status === "fulfilled") {
+      for (const price of outcome.value.data) cache.set(price.id, mapPaddlePrice(price));
+    } else {
+      const message =
+        outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+      ctx.obs.log?.warn("subscription-paddle: price lookup failed", { message });
+    }
+  }
+}
+
+export function createPaddleRetrievePrices(
+  runtime: PaddleCtxRuntime,
+  cache: PaddlePriceCache,
+): PaddlePluginMethod<"retrievePrices"> {
+  return async (ctx, priceIds) => {
+    await fillPriceCache(runtime, cache, ctx, priceIds);
+    return priceIds.flatMap((priceId) => cache.get(priceId) ?? []);
+  };
+}