@farm.js/polar 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,1088 @@
+import { Polar } from "@polar-sh/sdk";
+import { ResourceNotFound } from "@polar-sh/sdk/models/errors/resourcenotfound";
+import { validateEvent as validatePolarWebhookEvent, WebhookVerificationError as PolarWebhookVerificationError, } from "@polar-sh/sdk/webhooks";
+import { defineIntegration, integrationRoute, } from "@farm.js/core";
+import { integrationConfig, normalizeWebhookConfig, resolveAppPath, toAbsoluteUrl, } from "@farm.js/integration-utils";
+import { createPolarClientApi, } from "./client.js";
+export { polarClient } from "./client.js";
+const pendingPolarMeterProjection = new Map();
+function headersToObject(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+function createPolarApi(input) {
+    return createPolarClientApi(input);
+}
+function normalizeStatus(value) {
+    switch (value) {
+        case "trialing":
+        case "active":
+        case "past_due":
+        case "canceled":
+        case "unpaid":
+        case "incomplete":
+            return value;
+        default:
+            return "free";
+    }
+}
+function normalizeProducts(products) {
+    return Object.entries(products ?? {}).map(([id, product]) => {
+        const productId = product.polar?.productId ?? product.productId;
+        if (!productId) {
+            throw new Error(`Polar billing product "${id}" requires a productId.`);
+        }
+        return {
+            ...product,
+            productId,
+            id,
+            public: product.public ?? true,
+        };
+    });
+}
+function toCatalogProduct(product, plans) {
+    return {
+        id: product.id,
+        productId: product.productId,
+        name: product.name ?? product.id,
+        description: product.description ?? null,
+        kind: product.kind,
+        planId: product.planId ?? null,
+        trialDays: product.planId ? (plans[product.planId]?.trial?.days ?? null) : null,
+        public: product.public,
+        currency: product.currency ?? null,
+        unitAmount: product.unitAmount ?? null,
+        interval: product.interval ?? null,
+        intervalCount: product.intervalCount ?? null,
+        meterPrices: [],
+        metadata: product.metadata ?? {},
+    };
+}
+function resolvePolarTrialDays(input) {
+    const count = typeof input.trialIntervalCount === "number" && input.trialIntervalCount > 0
+        ? input.trialIntervalCount
+        : null;
+    if (!count) {
+        return null;
+    }
+    switch (input.trialInterval) {
+        case "day":
+            return count;
+        case "week":
+            return count * 7;
+        default:
+            return null;
+    }
+}
+function formatPolarCatalogMoney(amount, currency) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: (currency ?? "usd").toUpperCase(),
+        maximumFractionDigits: amount % 100 === 0 ? 0 : 2,
+    }).format(amount / 100);
+}
+function formatPolarCatalogUnitAmount(value, currency) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        return value;
+    }
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: (currency ?? "usd").toUpperCase(),
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 6,
+    }).format(parsed);
+}
+function summarizePolarCatalogMeterPrice(input) {
+    if (!input.unitAmountDecimal) {
+        return null;
+    }
+    const rate = `${formatPolarCatalogUnitAmount(input.unitAmountDecimal, input.currency)}/${input.unit ?? "unit"}`;
+    if (typeof input.capAmount === "number") {
+        return `${rate}, capped at ${formatPolarCatalogMoney(input.capAmount, input.currency)}`;
+    }
+    return rate;
+}
+async function enrichCatalogProduct(sdk, product, plans, meters) {
+    const base = toCatalogProduct(product, plans);
+    try {
+        const liveProduct = await sdk.products.get({
+            id: product.productId,
+        });
+        const byMeterId = new Map();
+        for (const [key, meter] of Object.entries(meters ?? {})) {
+            const meterId = resolvePolarMeterId(meter);
+            if (meterId) {
+                byMeterId.set(meterId, { key, meter });
+            }
+        }
+        const fixedPrice = (liveProduct.prices?.find((price) => isPolarFixedPrice(price) && typeof price.priceAmount === "number") ?? null);
+        const meterPrices = [];
+        for (const price of liveProduct.prices ?? []) {
+            if (!isPolarMeteredUnitPrice(price)) {
+                continue;
+            }
+            const meteredPrice = price;
+            const match = meteredPrice.meterId ? byMeterId.get(meteredPrice.meterId) : null;
+            if (!match || !meteredPrice.meterId) {
+                continue;
+            }
+            meterPrices.push({
+                key: match.key,
+                eventName: match.meter.eventName,
+                meterId: meteredPrice.meterId,
+                unit: match.meter.unit ?? null,
+                currency: product.currency ?? null,
+                unitAmountDecimal: meteredPrice.unitAmount ?? null,
+                capAmount: typeof meteredPrice.capAmount === "number" ? meteredPrice.capAmount : null,
+                summary: summarizePolarCatalogMeterPrice({
+                    unitAmountDecimal: meteredPrice.unitAmount ?? null,
+                    unit: match.meter.unit ?? null,
+                    capAmount: typeof meteredPrice.capAmount === "number" ? meteredPrice.capAmount : null,
+                    currency: product.currency ?? null,
+                }),
+            });
+        }
+        return {
+            ...base,
+            trialDays: resolvePolarTrialDays({
+                trialInterval: liveProduct.trialInterval,
+                trialIntervalCount: liveProduct.trialIntervalCount,
+            }) ?? base.trialDays,
+            unitAmount: typeof fixedPrice?.priceAmount === "number" ? fixedPrice.priceAmount : base.unitAmount,
+            meterPrices,
+        };
+    }
+    catch (error) {
+        console.warn("Could not load live Polar product pricing for catalog.", {
+            error,
+            productId: product.productId,
+        });
+        return base;
+    }
+}
+function getOwnerExternalCustomerId(owner, billing, tools) {
+    if (billing.resolveExternalCustomerId) {
+        return billing.resolveExternalCustomerId(owner, tools);
+    }
+    return `${owner.kind}:${owner.id}`;
+}
+async function getCustomerStateByExternalId(polar, externalId) {
+    try {
+        return await polar.customers.getStateExternal({
+            externalId,
+        });
+    }
+    catch (error) {
+        if (error instanceof ResourceNotFound) {
+            return null;
+        }
+        throw error;
+    }
+}
+function resolveActiveProduct(state, products) {
+    const byProductId = new Map(products.map((product) => [product.productId, product]));
+    const matched = [...(state?.activeSubscriptions ?? [])]
+        .filter((subscription) => byProductId.has(subscription.productId))
+        .sort((left, right) => right.createdAt.getTime() - left.createdAt.getTime())[0];
+    if (!matched) {
+        return {
+            product: null,
+            subscriptionId: null,
+            status: "free",
+        };
+    }
+    return {
+        product: byProductId.get(matched.productId) ?? null,
+        subscriptionId: matched.id,
+        status: normalizeStatus(matched.status),
+    };
+}
+function findStateMeter(state, meterId) {
+    return state?.activeMeters.find((meter) => meter.meterId === meterId) ?? null;
+}
+function resolvePolarPlanLimitReference(value, defaultKey) {
+    if (!value || value === "plan_limit" || typeof value === "number") {
+        return null;
+    }
+    if (typeof value === "string") {
+        const match = /^plans\.([^.]+)\.limits?\.([^.]+)$/.exec(value);
+        if (!match) {
+            return null;
+        }
+        return {
+            planId: match[1],
+            key: match[2],
+        };
+    }
+    if (typeof value.planId === "string" && value.planId.trim()) {
+        return {
+            planId: value.planId,
+            key: typeof value.key === "string" && value.key.trim() ? value.key : defaultKey,
+        };
+    }
+    return null;
+}
+function resolveSoftLimit(plans, planId, key, includedLimit, guard) {
+    if (!guard?.softLimit) {
+        return null;
+    }
+    if (guard.softLimit === "plan_limit") {
+        return includedLimit;
+    }
+    const reference = resolvePolarPlanLimitReference(guard.softLimit, key);
+    if (reference) {
+        const referencedLimit = plans[reference.planId]?.limits?.[reference.key ?? key] ?? null;
+        return typeof referencedLimit === "number" ? referencedLimit : null;
+    }
+    return typeof guard.softLimit === "number" ? guard.softLimit : null;
+}
+function resolveHardLimit(planId, includedLimit, guard) {
+    if (!guard) {
+        return null;
+    }
+    if (typeof guard.hardLimitByPlan?.[planId] === "number") {
+        return guard.hardLimitByPlan[planId];
+    }
+    if (typeof guard.hardLimit === "number") {
+        return guard.hardLimit;
+    }
+    if (typeof includedLimit === "number" && typeof guard.hardOverageByPlan?.[planId] === "number") {
+        return includedLimit + guard.hardOverageByPlan[planId];
+    }
+    if (typeof includedLimit === "number" && typeof guard.hardOverage === "number") {
+        return includedLimit + guard.hardOverage;
+    }
+    return null;
+}
+function getMeterIncrement(aggregation, quantity) {
+    switch (aggregation) {
+        case "count":
+            return 1;
+        case "last":
+            return quantity;
+        default:
+            return quantity;
+    }
+}
+function resolvePolarMeterId(meter) {
+    if (meter.polar?.meterId && meter.polar.meterId.trim()) {
+        return meter.polar.meterId;
+    }
+    if (meter.meterId && meter.meterId.trim()) {
+        return meter.meterId;
+    }
+    return null;
+}
+function resolvePolarQuantityMetadataKey(meter) {
+    if (meter.polar?.quantityMetadataKey && meter.polar.quantityMetadataKey.trim()) {
+        return meter.polar.quantityMetadataKey;
+    }
+    if (meter.quantityMetadataKey && meter.quantityMetadataKey.trim()) {
+        return meter.quantityMetadataKey;
+    }
+    return "quantity";
+}
+function toEstimatedMeterChargeAmount(input) {
+    const parsedUnitAmount = Number(input.unitAmount ?? Number.NaN);
+    if (!Number.isFinite(parsedUnitAmount)) {
+        return null;
+    }
+    const uncappedAmount = Math.round(input.currentUsed * parsedUnitAmount * 100);
+    if (typeof input.capAmount === "number") {
+        return Math.min(uncappedAmount, input.capAmount);
+    }
+    return uncappedAmount;
+}
+function isPolarMeteredUnitPrice(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        value.amountType === "metered_unit");
+}
+function isPolarFixedPrice(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        value.amountType === "fixed");
+}
+function projectionKey(input) {
+    return `${input.externalCustomerId}:${input.meterId}:${input.currentPeriodEnd ?? "none"}`;
+}
+function getProjectedUsage(input) {
+    const key = projectionKey(input);
+    const projected = pendingPolarMeterProjection.get(key);
+    if (projected == null) {
+        return input.currentPeriodUsed;
+    }
+    if (input.currentPeriodUsed >= projected) {
+        pendingPolarMeterProjection.delete(key);
+        return input.currentPeriodUsed;
+    }
+    return projected;
+}
+function setProjectedUsage(input) {
+    pendingPolarMeterProjection.set(projectionKey(input), input.projectedUsage);
+}
+async function resolveUsageValue(input) {
+    const resolved = await input.billing.usage?.resolve?.(input.owner, input.key, input.tools);
+    if (typeof resolved === "number") {
+        return resolved;
+    }
+    const meter = input.billing.meters?.[input.key];
+    if (!meter) {
+        return null;
+    }
+    const meterId = resolvePolarMeterId(meter);
+    if (!meterId) {
+        return null;
+    }
+    return findStateMeter(input.state, meterId)?.consumedUnits ?? 0;
+}
+async function requireOwner(ctx, billing, polar) {
+    const tools = { ctx, polar };
+    const owner = await billing.resolveOwner(ctx);
+    if (!owner) {
+        throw new Error("Polar billing owner could not be resolved for this request.");
+    }
+    const externalCustomerId = await getOwnerExternalCustomerId(owner, billing, tools);
+    const state = await getCustomerStateByExternalId(polar, externalCustomerId);
+    return {
+        owner,
+        externalCustomerId,
+        state,
+        tools,
+    };
+}
+function computeMeterState(input) {
+    if (!input.customerFound) {
+        return {
+            state: "customer_missing",
+            warning: "No Polar customer exists for the active billing owner yet.",
+        };
+    }
+    if (!input.meterFound) {
+        return {
+            state: "meter_missing",
+            warning: "The configured Polar customer meter is not active for this customer.",
+        };
+    }
+    if (input.guard?.blockOnPastDue &&
+        (input.subscriptionStatus === "past_due" || input.subscriptionStatus === "unpaid")) {
+        return {
+            state: "blocked_past_due",
+            warning: "Usage reporting is blocked while the Polar subscription is past due.",
+        };
+    }
+    if (typeof input.hardLimit === "number" && input.currentUsed >= input.hardLimit) {
+        return {
+            state: "hard_limit_reached",
+            warning: "The configured metered hard cap has been reached for the current billing period.",
+        };
+    }
+    if (typeof input.softLimit === "number" && input.currentUsed >= input.softLimit) {
+        return {
+            state: "soft_limit_reached",
+            warning: typeof input.includedLimit === "number"
+                ? "Included usage has been exhausted. Additional usage is billable."
+                : "The configured soft limit has been reached.",
+        };
+    }
+    return {
+        state: "ok",
+        warning: null,
+    };
+}
+export function polar(input) {
+    const accessToken = input.accessToken ?? process.env.POLAR_ACCESS_TOKEN ?? "";
+    const server = input.server ?? process.env.POLAR_SERVER ?? "sandbox";
+    const appBaseUrl = input.appBaseUrl ?? process.env.APP_BASE_URL ?? undefined;
+    const webhookSecret = process.env.POLAR_WEBHOOK_SECRET ?? undefined;
+    if (!accessToken) {
+        throw new Error("Polar integration requires POLAR_ACCESS_TOKEN.");
+    }
+    const billing = input.billing;
+    const productsPath = (input.productsPath ?? "/billing/products");
+    const statusPath = (input.statusPath ?? "/billing/status");
+    const currentChargesPath = (input.currentChargesPath ??
+        "/billing/current-charges");
+    const featuresPath = (input.featuresPath ?? "/billing/features");
+    const limitsPath = (input.limitsPath ?? "/billing/limits");
+    const usagePath = (input.usagePath ?? "/billing/usage");
+    const meterUsagePath = (input.meterUsagePath ??
+        "/billing/meter-usage");
+    const reportUsagePath = (input.reportUsagePath ??
+        "/billing/report-usage");
+    const checkPath = (input.checkPath ?? "/billing/check");
+    const checkoutPath = (input.checkoutPath ?? "/billing/checkout");
+    const portalPath = (input.portalPath ?? "/billing/portal");
+    const webhookDefinitions = normalizeWebhookConfig({
+        webhooks: input.webhooks,
+        defaultName: "default",
+        defaultPath: "/billing/webhook",
+        defaultSecret: webhookSecret,
+    });
+    const plans = billing.plans ?? {};
+    const products = normalizeProducts(billing.products);
+    for (const [key, meter] of Object.entries(billing.meters ?? {})) {
+        if (!meter.eventName || !meter.eventName.trim()) {
+            throw new Error(`Polar billing meter "${key}" requires a non-empty eventName.`);
+        }
+        if (!resolvePolarMeterId(meter)) {
+            throw new Error(`Polar billing meter "${key}" requires polar.meterId (or legacy meterId).`);
+        }
+    }
+    const sdk = new Polar({
+        accessToken,
+        server,
+    });
+    const webhookRoutes = webhookDefinitions.map((definition) => integrationRoute.post(definition.path, {
+        responseFormat: "json",
+        rawBody: true,
+        async handler(request, context) {
+            const rawBody = await request.text();
+            const webhookContext = {
+                request,
+                route: context,
+                rawBody,
+                headers: request.headers,
+                webhook: {
+                    name: definition.name,
+                    path: definition.path,
+                },
+            };
+            try {
+                if (!definition.secret) {
+                    throw new Error("Polar webhook secret is required to verify webhook events.");
+                }
+                const payload = validatePolarWebhookEvent(rawBody, headersToObject(request.headers), definition.secret);
+                const event = {
+                    provider: "polar",
+                    id: request.headers.get("webhook-id") ??
+                        `${payload.type}:${payload.timestamp.toISOString()}`,
+                    type: payload.type,
+                    data: payload.data,
+                    raw: payload,
+                };
+                await definition.onEvent?.(event, webhookContext);
+                return Response.json({
+                    received: true,
+                    provider: "polar",
+                    webhook: definition.name,
+                    eventId: event.id,
+                    type: event.type,
+                });
+            }
+            catch (error) {
+                const override = await definition.onError?.(error, webhookContext);
+                if (override) {
+                    return override;
+                }
+                return Response.json({
+                    error: error instanceof Error ? error.message : "Polar webhook verification failed.",
+                }, {
+                    status: error instanceof PolarWebhookVerificationError ? 403 : 400,
+                });
+            }
+        },
+    }));
+    return defineIntegration({
+        category: "payment",
+        type: "polar",
+        instance: {
+            server,
+            products: products.map((product) => ({
+                id: product.id,
+                productId: product.productId,
+                kind: product.kind,
+                planId: product.planId ?? null,
+            })),
+        },
+        config: integrationConfig({
+            label: "Polar integration",
+            env: {
+                accessToken: "POLAR_ACCESS_TOKEN",
+                server: "POLAR_SERVER",
+                appBaseUrl: "APP_BASE_URL",
+                webhookSecret: "POLAR_WEBHOOK_SECRET",
+            },
+            input: {
+                accessToken,
+                server,
+                appBaseUrl,
+                webhookSecret,
+            },
+            required: ["accessToken", "server"],
+        }),
+        api: createPolarApi({
+            productsPath,
+            statusPath,
+            currentChargesPath,
+            featuresPath,
+            limitsPath,
+            usagePath,
+            meterUsagePath,
+            reportUsagePath,
+            checkPath,
+            checkoutPath,
+            portalPath,
+        }),
+        log: input.log,
+        routes: [
+            integrationRoute.get(productsPath, {
+                responseFormat: "json",
+                async handler() {
+                    return Response.json(await Promise.all(products
+                        .filter((product) => product.public)
+                        .map((product) => enrichCatalogProduct(sdk, product, plans, billing.meters))));
+                },
+            }),
+            integrationRoute.get(statusPath, {
+                responseFormat: "json",
+                async handler(_request, ctx) {
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    const subscription = resolved.state?.activeSubscriptions.find((entry) => entry.id === active.subscriptionId) ?? null;
+                    return Response.json({
+                        owner: resolved.owner,
+                        externalCustomerId: resolved.externalCustomerId,
+                        customerId: resolved.state?.id ?? null,
+                        planId,
+                        productId: active.product?.id ?? null,
+                        status: active.status,
+                        subscriptionId: active.subscriptionId,
+                        currentPeriodStart: subscription?.currentPeriodStart?.toISOString() ?? null,
+                        currentPeriodEnd: subscription?.currentPeriodEnd?.toISOString() ?? null,
+                        cancelAtPeriodEnd: subscription?.cancelAtPeriodEnd ?? false,
+                        trialEndsAt: subscription?.trialEnd?.toISOString() ?? null,
+                        features: plan.features ?? {},
+                        limits: plan.limits ?? {},
+                        entitlements: plan.entitlements ?? {},
+                    });
+                },
+            }),
+            integrationRoute.get(currentChargesPath, {
+                responseFormat: "json",
+                async handler(_request, ctx) {
+                    const owner = await billing.resolveOwner(ctx);
+                    if (!owner) {
+                        return Response.json({
+                            owner: null,
+                            externalCustomerId: null,
+                            customerId: null,
+                            planId: "free",
+                            productId: null,
+                            subscriptionId: null,
+                            subscriptionStatus: "free",
+                            currency: "usd",
+                            currentPeriodStart: null,
+                            currentPeriodEnd: null,
+                            baseSubscriptionAmount: null,
+                            pendingMeterChargeAmount: null,
+                            estimatedTotalAmount: null,
+                            lineItems: [],
+                        });
+                    }
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    const subscription = resolved.state?.activeSubscriptions.find((entry) => entry.id === active.subscriptionId) ?? null;
+                    const currency = subscription?.currency ?? active.product?.currency ?? "usd";
+                    const baseSubscriptionAmount = typeof subscription?.amount === "number" ? subscription.amount : null;
+                    const lineItems = [];
+                    if (baseSubscriptionAmount != null) {
+                        lineItems.push({
+                            key: null,
+                            kind: "base_subscription",
+                            label: active.product?.name ?? "Base subscription",
+                            amount: baseSubscriptionAmount,
+                            currency,
+                            quantity: 1,
+                            includedUnits: null,
+                            overageUnits: null,
+                            billedBuckets: null,
+                            billingUnits: null,
+                            unitAmountDecimal: null,
+                        });
+                    }
+                    let liveProduct = null;
+                    if (active.product?.productId) {
+                        try {
+                            liveProduct = await sdk.products.get({
+                                id: active.product.productId,
+                            });
+                        }
+                        catch (error) {
+                            console.warn("Could not load live Polar product pricing for current charges.", {
+                                error,
+                                productId: active.product.productId,
+                            });
+                        }
+                    }
+                    let pendingMeterChargeAmount = 0;
+                    let sawMeterLine = false;
+                    for (const [key, meter] of Object.entries(billing.meters ?? {})) {
+                        const meterId = resolvePolarMeterId(meter);
+                        if (!meterId) {
+                            continue;
+                        }
+                        const subscriptionMeter = subscription?.meters.find((entry) => entry.meterId === meterId) ?? null;
+                        const customerMeter = findStateMeter(resolved.state, meterId);
+                        const currentPeriodEnd = subscription?.currentPeriodEnd?.toISOString() ?? null;
+                        const currentUsed = getProjectedUsage({
+                            externalCustomerId: resolved.externalCustomerId,
+                            meterId,
+                            currentPeriodEnd,
+                            currentPeriodUsed: subscriptionMeter?.consumedUnits ?? customerMeter?.consumedUnits ?? 0,
+                        });
+                        const liveMeteredPrice = (liveProduct?.prices?.find((price) => isPolarMeteredUnitPrice(price) &&
+                            price.meterId === meterId) ?? null);
+                        const unitAmountDecimal = liveMeteredPrice?.unitAmount ?? null;
+                        const capAmount = typeof liveMeteredPrice?.capAmount === "number" ? liveMeteredPrice.capAmount : null;
+                        const estimatedMeterChargeAmount = typeof subscriptionMeter?.amount === "number"
+                            ? subscriptionMeter.amount
+                            : toEstimatedMeterChargeAmount({
+                                currentUsed,
+                                unitAmount: unitAmountDecimal,
+                                capAmount,
+                            });
+                        const includedUnits = plan.limits?.[key] ??
+                            subscriptionMeter?.creditedUnits ??
+                            customerMeter?.creditedUnits ??
+                            null;
+                        const overageUnits = typeof includedUnits === "number" ? Math.max(currentUsed - includedUnits, 0) : null;
+                        if (currentUsed <= 0 &&
+                            estimatedMeterChargeAmount == null &&
+                            !subscriptionMeter &&
+                            !customerMeter &&
+                            !liveMeteredPrice) {
+                            continue;
+                        }
+                        sawMeterLine = true;
+                        pendingMeterChargeAmount += estimatedMeterChargeAmount ?? 0;
+                        lineItems.push({
+                            key,
+                            kind: "metered_usage",
+                            label: `${meter.unit ?? key} overage`,
+                            amount: estimatedMeterChargeAmount,
+                            currency,
+                            quantity: currentUsed,
+                            includedUnits,
+                            overageUnits,
+                            billedBuckets: null,
+                            billingUnits: null,
+                            unitAmountDecimal,
+                        });
+                    }
+                    return Response.json({
+                        owner: resolved.owner,
+                        externalCustomerId: resolved.externalCustomerId,
+                        customerId: resolved.state?.id ?? null,
+                        planId,
+                        productId: active.product?.id ?? null,
+                        subscriptionId: active.subscriptionId,
+                        subscriptionStatus: active.status,
+                        currency,
+                        currentPeriodStart: subscription?.currentPeriodStart?.toISOString() ?? null,
+                        currentPeriodEnd: subscription?.currentPeriodEnd?.toISOString() ?? null,
+                        baseSubscriptionAmount,
+                        pendingMeterChargeAmount: sawMeterLine ? pendingMeterChargeAmount : null,
+                        estimatedTotalAmount: (baseSubscriptionAmount ?? 0) + (sawMeterLine ? pendingMeterChargeAmount : 0),
+                        lineItems,
+                    });
+                },
+            }),
+            integrationRoute.get(featuresPath, {
+                responseFormat: "json",
+                async handler(_request, ctx) {
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    return Response.json({
+                        planId,
+                        features: plan.features ?? {},
+                    });
+                },
+            }),
+            integrationRoute.get(limitsPath, {
+                responseFormat: "json",
+                async handler(_request, ctx) {
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    return Response.json({
+                        planId,
+                        limits: plan.limits ?? {},
+                    });
+                },
+            }),
+            integrationRoute.post(usagePath, {
+                responseFormat: "json",
+                async handler(request, ctx) {
+                    const body = (await request.json().catch(() => ({})));
+                    if (!body.key) {
+                        return new Response("A billing usage key is required.", { status: 400 });
+                    }
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    const used = await resolveUsageValue({
+                        owner: resolved.owner,
+                        key: body.key,
+                        tools: resolved.tools,
+                        billing,
+                        state: resolved.state,
+                    });
+                    const limit = plan.limits?.[body.key] ?? null;
+                    const remaining = typeof used === "number" && typeof limit === "number"
+                        ? Math.max(limit - used, 0)
+                        : null;
+                    return Response.json({
+                        planId,
+                        key: body.key,
+                        used,
+                        limit,
+                        remaining,
+                    });
+                },
+            }),
+            integrationRoute.post(meterUsagePath, {
+                responseFormat: "json",
+                async handler(request, ctx) {
+                    const body = (await request.json().catch(() => ({})));
+                    if (!body.key) {
+                        return new Response("A Polar meter key is required.", { status: 400 });
+                    }
+                    const meter = billing.meters?.[body.key];
+                    if (!meter) {
+                        return new Response(`Unknown Polar meter "${body.key}".`, { status: 404 });
+                    }
+                    const meterId = resolvePolarMeterId(meter);
+                    if (!meterId) {
+                        return new Response(`Polar meter "${body.key}" is missing a meterId.`, {
+                            status: 500,
+                        });
+                    }
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    const subscription = resolved.state?.activeSubscriptions.find((entry) => entry.id === active.subscriptionId) ?? null;
+                    const subscriptionMeter = subscription?.meters.find((entry) => entry.meterId === meterId) ?? null;
+                    const customerMeter = findStateMeter(resolved.state, meterId);
+                    const currentUsed = getProjectedUsage({
+                        externalCustomerId: resolved.externalCustomerId,
+                        meterId,
+                        currentPeriodEnd: subscription?.currentPeriodEnd?.toISOString() ?? null,
+                        currentPeriodUsed: subscriptionMeter?.consumedUnits ?? customerMeter?.consumedUnits ?? 0,
+                    });
+                    let meterUnitAmount = null;
+                    let meterCapAmount = null;
+                    let estimatedMeterChargeAmount = typeof subscriptionMeter?.amount === "number" ? subscriptionMeter.amount : null;
+                    let chargeSource = estimatedMeterChargeAmount != null ? "subscription_meter" : "catalog_rate";
+                    let meterName = null;
+                    const baseSubscriptionAmount = typeof subscription?.amount === "number" ? subscription.amount : null;
+                    let currency = subscription?.currency ?? null;
+                    if (active.product?.productId) {
+                        try {
+                            const liveProduct = await sdk.products.get({
+                                id: active.product.productId,
+                            });
+                            const liveMeteredPrice = (liveProduct.prices?.find((price) => isPolarMeteredUnitPrice(price) &&
+                                price.meterId === meterId) ?? null);
+                            meterUnitAmount = liveMeteredPrice?.unitAmount ?? null;
+                            meterCapAmount =
+                                typeof liveMeteredPrice?.capAmount === "number" ? liveMeteredPrice.capAmount : null;
+                            meterName =
+                                liveMeteredPrice?.meter?.name ??
+                                    null;
+                            if (estimatedMeterChargeAmount == null) {
+                                estimatedMeterChargeAmount = toEstimatedMeterChargeAmount({
+                                    currentUsed,
+                                    unitAmount: meterUnitAmount,
+                                    capAmount: meterCapAmount,
+                                });
+                                chargeSource = "catalog_rate";
+                            }
+                        }
+                        catch (error) {
+                            console.warn("Could not load live Polar metered pricing for meter usage.", {
+                                error,
+                                productId: active.product.productId,
+                                meterId,
+                            });
+                        }
+                    }
+                    const includedLimit = plan.limits?.[body.key] ?? null;
+                    const softLimit = resolveSoftLimit(plans, planId, body.key, includedLimit, meter.guard);
+                    const hardLimit = resolveHardLimit(planId, includedLimit, meter.guard);
+                    const state = computeMeterState({
+                        currentUsed,
+                        subscriptionStatus: active.status,
+                        includedLimit,
+                        softLimit,
+                        hardLimit,
+                        guard: meter.guard,
+                        meterFound: !!customerMeter,
+                        customerFound: !!resolved.state,
+                    });
+                    return Response.json({
+                        planId,
+                        productId: active.product?.id ?? null,
+                        key: body.key,
+                        eventName: meter.eventName,
+                        meterId,
+                        meterName,
+                        aggregation: meter.aggregation,
+                        quantityMetadataKey: resolvePolarQuantityMetadataKey(meter),
+                        activeMeterIds: resolved.state?.activeMeters?.map((entry) => entry.meterId) ?? [],
+                        customerId: resolved.state?.id ?? null,
+                        subscriptionId: active.subscriptionId,
+                        subscriptionStatus: active.status,
+                        currentPeriodStart: subscription?.currentPeriodStart?.toISOString() ?? null,
+                        currentPeriodEnd: subscription?.currentPeriodEnd?.toISOString() ?? null,
+                        currentPeriodUsed: currentUsed,
+                        creditedUnits: customerMeter?.creditedUnits ?? null,
+                        balance: customerMeter?.balance ?? null,
+                        currency,
+                        baseSubscriptionAmount,
+                        meterUnitAmount,
+                        meterCapAmount,
+                        chargeSource,
+                        estimatedMeterChargeAmount,
+                        estimatedCombinedAmount: typeof baseSubscriptionAmount === "number" &&
+                            typeof estimatedMeterChargeAmount === "number"
+                            ? baseSubscriptionAmount + estimatedMeterChargeAmount
+                            : null,
+                        includedLimit,
+                        softLimit,
+                        hardLimit,
+                        remainingIncluded: typeof includedLimit === "number" ? Math.max(includedLimit - currentUsed, 0) : null,
+                        remainingHard: typeof hardLimit === "number" ? Math.max(hardLimit - currentUsed, 0) : null,
+                        state: state.state,
+                        warning: state.warning,
+                    });
+                },
+            }),
+            integrationRoute.post(reportUsagePath, {
+                responseFormat: "json",
+                async handler(request, ctx) {
+                    const body = (await request.json().catch(() => ({})));
+                    if (!body.key) {
+                        return new Response("A Polar meter key is required.", { status: 400 });
+                    }
+                    if (!Number.isFinite(body.quantity) || body.quantity <= 0) {
+                        return new Response("Polar reported quantity must be a positive number.", {
+                            status: 400,
+                        });
+                    }
+                    if (!body.idempotencyKey) {
+                        return new Response("An idempotencyKey is required for Polar usage reporting.", {
+                            status: 400,
+                        });
+                    }
+                    const meter = billing.meters?.[body.key];
+                    if (!meter) {
+                        return new Response(`Unknown Polar meter "${body.key}".`, { status: 404 });
+                    }
+                    const meterId = resolvePolarMeterId(meter);
+                    if (!meterId) {
+                        return new Response(`Polar meter "${body.key}" is missing a meterId.`, {
+                            status: 500,
+                        });
+                    }
+                    const occurredAt = typeof body.occurredAt === "string" && body.occurredAt
+                        ? new Date(body.occurredAt)
+                        : new Date();
+                    if (Number.isNaN(occurredAt.getTime())) {
+                        return new Response("occurredAt must be a valid ISO timestamp.", { status: 400 });
+                    }
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    const subscription = resolved.state?.activeSubscriptions.find((entry) => entry.id === active.subscriptionId) ?? null;
+                    const customerMeter = findStateMeter(resolved.state, meterId);
+                    const currentUsed = getProjectedUsage({
+                        externalCustomerId: resolved.externalCustomerId,
+                        meterId,
+                        currentPeriodEnd: subscription?.currentPeriodEnd?.toISOString() ?? null,
+                        currentPeriodUsed: customerMeter?.consumedUnits ?? 0,
+                    });
+                    const includedLimit = plan.limits?.[body.key] ?? null;
+                    const softLimit = resolveSoftLimit(plans, planId, body.key, includedLimit, meter.guard);
+                    const hardLimit = resolveHardLimit(planId, includedLimit, meter.guard);
+                    const state = computeMeterState({
+                        currentUsed,
+                        subscriptionStatus: active.status,
+                        includedLimit,
+                        softLimit,
+                        hardLimit,
+                        guard: meter.guard,
+                        meterFound: !!customerMeter,
+                        customerFound: !!resolved.state,
+                    });
+                    if (state.state === "blocked_past_due" || state.state === "hard_limit_reached") {
+                        return new Response(state.warning ?? "Polar usage reporting is blocked for the current billing period.", { status: 409 });
+                    }
+                    const increment = getMeterIncrement(meter.aggregation, body.quantity);
+                    const projectedCurrentPeriodUsed = currentUsed + increment;
+                    if (typeof hardLimit === "number" && projectedCurrentPeriodUsed > hardLimit) {
+                        return new Response("The configured metered hard cap has been reached for the current billing period. Reported usage is blocked until the next cycle or a plan change.", { status: 409 });
+                    }
+                    const metadata = {
+                        ...body.properties,
+                        [resolvePolarQuantityMetadataKey(meter)]: body.quantity,
+                    };
+                    await sdk.events.ingest({
+                        events: [
+                            {
+                                name: meter.eventName,
+                                externalCustomerId: resolved.externalCustomerId,
+                                externalId: body.idempotencyKey,
+                                timestamp: occurredAt,
+                                metadata,
+                            },
+                        ],
+                    });
+                    setProjectedUsage({
+                        externalCustomerId: resolved.externalCustomerId,
+                        meterId,
+                        currentPeriodEnd: subscription?.currentPeriodEnd?.toISOString() ?? null,
+                        projectedUsage: projectedCurrentPeriodUsed,
+                    });
+                    await billing.hooks?.onUsageReported?.({
+                        owner: resolved.owner,
+                        key: body.key,
+                        quantity: body.quantity,
+                        idempotencyKey: body.idempotencyKey,
+                        occurredAt: occurredAt.toISOString(),
+                        eventName: meter.eventName,
+                        customerId: resolved.state?.id ?? null,
+                        projectedCurrentPeriodUsed,
+                    }, resolved.tools);
+                    const nextState = typeof hardLimit === "number" && projectedCurrentPeriodUsed >= hardLimit
+                        ? "hard_limit_reached"
+                        : typeof softLimit === "number" && projectedCurrentPeriodUsed >= softLimit
+                            ? "soft_limit_reached"
+                            : "ok";
+                    return Response.json({
+                        key: body.key,
+                        quantity: body.quantity,
+                        customerId: resolved.state?.id ?? null,
+                        eventName: meter.eventName,
+                        eventIdentifier: body.idempotencyKey,
+                        occurredAt: occurredAt.toISOString(),
+                        currentPeriodUsed: currentUsed,
+                        projectedCurrentPeriodUsed,
+                        softLimit,
+                        hardLimit,
+                        state: nextState,
+                        warning: nextState === "soft_limit_reached"
+                            ? "Included usage has been exhausted. Additional usage is billable."
+                            : nextState === "hard_limit_reached"
+                                ? "The configured metered hard cap has been reached for the current billing period."
+                                : null,
+                    });
+                },
+            }),
+            integrationRoute.post(checkPath, {
+                responseFormat: "json",
+                async handler(request, ctx) {
+                    const body = (await request.json().catch(() => ({})));
+                    if (!body.key) {
+                        return new Response("A billing check key is required.", { status: 400 });
+                    }
+                    const amount = typeof body.amount === "number" && Number.isFinite(body.amount) && body.amount > 0
+                        ? body.amount
+                        : 1;
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const active = resolveActiveProduct(resolved.state, products);
+                    const planId = active.product?.planId ?? "free";
+                    const plan = plans[planId] ?? {};
+                    const used = await resolveUsageValue({
+                        owner: resolved.owner,
+                        key: body.key,
+                        tools: resolved.tools,
+                        billing,
+                        state: resolved.state,
+                    });
+                    const limit = plan.limits?.[body.key] ?? null;
+                    const remaining = typeof used === "number" && typeof limit === "number"
+                        ? Math.max(limit - used, 0)
+                        : null;
+                    const allowed = typeof used === "number" && typeof limit === "number" ? used + amount <= limit : true;
+                    return Response.json({
+                        planId,
+                        key: body.key,
+                        amount,
+                        used,
+                        limit,
+                        remaining,
+                        allowed,
+                    });
+                },
+            }),
+            integrationRoute.post(checkoutPath, {
+                responseFormat: "json",
+                async handler(request, ctx) {
+                    const body = (await request.json().catch(() => ({})));
+                    if (!body.productId) {
+                        return new Response("A Polar product id is required.", { status: 400 });
+                    }
+                    const product = products.find((entry) => entry.id === body.productId);
+                    if (!product) {
+                        return new Response(`Unknown Polar product "${body.productId}".`, { status: 404 });
+                    }
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const successPath = resolveAppPath(body.successPath ?? "/success", "Polar checkout successPath") ??
+                        "/success";
+                    const cancelPath = resolveAppPath(body.cancelPath ?? "/cancel", "Polar checkout cancelPath") ?? "/cancel";
+                    const successUrl = toAbsoluteUrl(successPath, request, appBaseUrl);
+                    successUrl.searchParams.set("checkout_id", "{CHECKOUT_ID}");
+                    const returnUrl = toAbsoluteUrl(cancelPath, request, appBaseUrl);
+                    const checkout = await sdk.checkouts.create({
+                        products: [product.productId],
+                        successUrl: successUrl.toString(),
+                        returnUrl: returnUrl.toString(),
+                        externalCustomerId: resolved.externalCustomerId,
+                        customerEmail: body.customerEmail ?? resolved.owner.email ?? null,
+                        metadata: body.metadata,
+                    });
+                    return Response.json({
+                        productId: product.id,
+                        planId: product.planId ?? null,
+                        checkoutId: checkout.id,
+                        redirectTo: checkout.url,
+                        mode: product.kind === "subscription" ? "subscription" : "payment",
+                    });
+                },
+            }),
+            integrationRoute.post(portalPath, {
+                responseFormat: "json",
+                async handler(request, ctx) {
+                    const body = (await request.json().catch(() => ({})));
+                    const resolved = await requireOwner(ctx, billing, sdk);
+                    const returnPath = resolveAppPath(body.returnTo ?? "/", "Polar portal returnTo") ?? "/";
+                    const returnUrl = toAbsoluteUrl(returnPath, request, appBaseUrl);
+                    const session = await sdk.customerSessions.create({
+                        externalCustomerId: resolved.externalCustomerId,
+                        returnUrl: returnUrl.toString(),
+                    });
+                    return Response.json({
+                        customerId: session.customerId,
+                        redirectTo: session.customerPortalUrl,
+                    });
+                },
+            }),
+            ...webhookRoutes,
+        ],
+    });
+}