@taskforcehq/taskforce 0.3.168

package/dist/server/routes.billing.js

@@ -0,0 +1,991 @@
+import Stripe from 'stripe';
+import { parseJsonBody } from './routes.js';
+const BILLING_CONFIG_KEY_PLAN = 'billing.config.v1';
+const PRICE_METADATA_PLAN_VERSION = 'taskforce_plan_version_id';
+const BILLING_DIAGNOSTIC_RETENTION_DAYS = 30;
+const BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES = 8 * 1024;
+function isoFromUnixSeconds(raw) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    return new Date(Math.floor(value) * 1000).toISOString();
+}
+function parseInterval(raw) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (value === 'month' || value === 'year')
+        return value;
+    return null;
+}
+function resolveSubscriptionCurrentPeriodEnd(subscription) {
+    const itemPeriods = Array.isArray(subscription.items?.data)
+        ? subscription.items.data
+            .map((item) => isoFromUnixSeconds(item?.current_period_end))
+            .filter((value) => Boolean(value))
+        : [];
+    if (itemPeriods.length === 0)
+        return null;
+    return itemPeriods.sort()[itemPeriods.length - 1] || null;
+}
+function resolveInvoiceSubscriptionId(invoice) {
+    const parentSubscription = String(invoice?.parent?.subscription_details?.subscription || '').trim();
+    if (parentSubscription)
+        return parentSubscription;
+    const lineSubscription = String(invoice.lines?.data?.[0]?.subscription || '').trim();
+    return lineSubscription;
+}
+function requestRuntimeMode(req) {
+    const value = String(req.headers['x-taskforce-runtime-mode'] || '').trim().toLowerCase();
+    return value === 'cloud' ? 'cloud' : 'local';
+}
+function parseBoolean(value, fallback = false) {
+    const normalized = String(value ?? '').trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on')
+        return true;
+    if (normalized === 'false' || normalized === '0' || normalized === 'no' || normalized === 'off')
+        return false;
+    return fallback;
+}
+function parsePositiveIntBounded(raw, fallback, min, max) {
+    const parsed = Number.parseInt(String(raw || '').trim(), 10);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(min, Math.min(max, parsed));
+}
+function resolveBaseUrl(req) {
+    const host = String(req.headers['x-forwarded-host'] || req.headers.host || 'localhost').trim();
+    const proto = String(req.headers['x-forwarded-proto'] || '').trim().toLowerCase() === 'http' ? 'http' : 'https';
+    return `${proto}://${host.replace(/\/+$/, '')}`;
+}
+async function readRawBody(req, maxBytes = 1_048_576) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes) {
+            const error = new Error(`Payload too large (max ${maxBytes} bytes)`);
+            error.statusCode = 413;
+            throw error;
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+function mapStripeStatusToCanonicalState(statusRaw) {
+    const status = String(statusRaw || '').trim().toLowerCase();
+    if (status === 'trialing')
+        return 'trialing';
+    if (status === 'active')
+        return 'active';
+    if (status === 'past_due')
+        return 'grace';
+    return 'canceled';
+}
+function redactStripePayload(input) {
+    const blockedKeys = new Set([
+        'billing_details',
+        'customer_details',
+        'payment_method',
+        'payment_method_details',
+        'payment_intent',
+        'charges',
+        'source',
+        'sources',
+        'card',
+        'default_source'
+    ]);
+    const visit = (value, depth) => {
+        if (depth > 6)
+            return '[truncated-depth]';
+        if (value === null || value === undefined)
+            return value;
+        if (Array.isArray(value))
+            return value.slice(0, 30).map((item) => visit(item, depth + 1));
+        if (typeof value !== 'object')
+            return value;
+        const source = value;
+        const out = {};
+        for (const [key, child] of Object.entries(source)) {
+            if (blockedKeys.has(key))
+                continue;
+            out[key] = visit(child, depth + 1);
+        }
+        return out;
+    };
+    const redacted = visit(input, 0);
+    return redacted && typeof redacted === 'object' && !Array.isArray(redacted)
+        ? redacted
+        : {};
+}
+function boundedPayloadExcerpt(payload) {
+    const raw = JSON.stringify(payload);
+    if (Buffer.byteLength(raw, 'utf8') <= BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES)
+        return raw;
+    const truncated = raw.slice(0, BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES);
+    return `${truncated}...[truncated]`;
+}
+function parseBillingConfig(raw) {
+    const fallback = {
+        trialDays: 30,
+        tiers: {},
+        taxEnabled: false,
+        billingAddress: 'auto'
+    };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return fallback;
+    const record = raw;
+    const trialDaysRaw = Number(record.trial_days);
+    const trialDays = Number.isFinite(trialDaysRaw) ? Math.max(1, Math.min(30, Math.floor(trialDaysRaw))) : 30;
+    const billingAddress = String(record.billing_address || '').trim().toLowerCase() === 'required'
+        ? 'required'
+        : 'auto';
+    return {
+        trialDays,
+        tiers: record.tiers && typeof record.tiers === 'object' && !Array.isArray(record.tiers)
+            ? record.tiers
+            : {},
+        taxEnabled: parseBoolean(record.tax_enabled, false),
+        billingAddress
+    };
+}
+function billingDisabledResponse(res) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Billing is disabled.' }));
+}
+function cloudOnlyResponse(res) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Billing is only available in cloud runtime.' }));
+}
+function getStripeClient() {
+    const key = String(process.env.TASKFORCE_STRIPE_SECRET_KEY || '').trim();
+    if (!key) {
+        const error = new Error('TASKFORCE_STRIPE_SECRET_KEY is not configured.');
+        error.statusCode = 500;
+        throw error;
+    }
+    return new Stripe(key);
+}
+function readBillingConfig(core) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT payload
+        FROM system_settings
+        WHERE tenant_id = ? AND settings_key = ?
+        LIMIT 1
+    `).get(tenantId, BILLING_CONFIG_KEY_PLAN);
+    if (!row?.payload)
+        return parseBillingConfig({});
+    try {
+        return parseBillingConfig(JSON.parse(row.payload));
+    }
+    catch {
+        return parseBillingConfig({});
+    }
+}
+function writeBillingConfig(core, payload) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    db.prepare(`
+        INSERT INTO system_settings (tenant_id, settings_key, payload, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (tenant_id, settings_key) DO UPDATE SET
+            payload = excluded.payload,
+            updated_at = excluded.updated_at
+    `).run(tenantId, BILLING_CONFIG_KEY_PLAN, JSON.stringify({
+        trial_days: payload.trialDays,
+        tiers: payload.tiers,
+        tax_enabled: payload.taxEnabled,
+        billing_address: payload.billingAddress
+    }), now);
+}
+function resolveDefaultPlanVersionId(core, tierRaw) {
+    const tier = String(tierRaw || '').trim().toLowerCase();
+    if (!tier)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT plan_version_id
+        FROM plan_versions
+        WHERE tenant_id = ? AND plan_id = ? AND is_default = 1
+        LIMIT 1
+    `).get(tenantId, tier);
+    return row?.plan_version_id ? String(row.plan_version_id) : null;
+}
+function resolvePriceIdForPlanVersion(core, planVersionIdRaw, intervalRaw) {
+    const planVersionId = String(planVersionIdRaw || '').trim();
+    const interval = parseInterval(intervalRaw);
+    if (!planVersionId || !interval)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT stripe_price_id
+        FROM billing_price_mappings
+        WHERE tenant_id = ?
+          AND plan_version_id = ?
+          AND billing_interval = ?
+          AND active = 1
+        LIMIT 1
+    `).get(tenantId, planVersionId, interval);
+    return row?.stripe_price_id ? String(row.stripe_price_id) : null;
+}
+function resolvePlanVersionIdForPriceId(core, priceIdRaw) {
+    const priceId = String(priceIdRaw || '').trim();
+    if (!priceId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT plan_version_id
+        FROM billing_price_mappings
+        WHERE tenant_id = ?
+          AND stripe_price_id = ?
+          AND active = 1
+        LIMIT 1
+    `).get(tenantId, priceId);
+    return row?.plan_version_id ? String(row.plan_version_id) : null;
+}
+function resolvePlanIdForVersion(core, planVersionIdRaw) {
+    const planVersionId = String(planVersionIdRaw || '').trim();
+    if (!planVersionId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT plan_id
+        FROM plan_versions
+        WHERE tenant_id = ? AND plan_version_id = ?
+        LIMIT 1
+    `).get(tenantId, planVersionId);
+    return row?.plan_id ? String(row.plan_id) : null;
+}
+function getEntitlementRow(core, userIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    if (!userId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT account_id, plan_version_id, entitlement_state
+        FROM account_entitlements
+        WHERE tenant_id = ? AND account_id = ?
+        LIMIT 1
+    `).get(tenantId, userId);
+    return row || null;
+}
+function upsertCanonicalEntitlement(core, input) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    db.prepare(`
+        INSERT INTO account_entitlements (account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (account_id) DO UPDATE SET
+            plan_version_id = excluded.plan_version_id,
+            entitlement_state = excluded.entitlement_state,
+            effective_at = excluded.effective_at,
+            effective_until = excluded.effective_until,
+            updated_by = excluded.updated_by,
+            updated_at = excluded.updated_at
+    `).run(input.userId, tenantId, input.planVersionId, input.state, input.effectiveAt || now, input.effectiveUntil || null, input.updatedBy || 'stripe-webhook', now, now);
+}
+function upsertBillingMirror(core, input) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    const existingRow = db.prepare(`
+        SELECT tier
+        FROM user_billing
+        WHERE tenant_id = ? AND user_id = ?
+        LIMIT 1
+    `).get(tenantId, input.userId);
+    const resolvedTier = String(input.planId || existingRow?.tier || 'free').trim() || 'free';
+    db.prepare(`
+        INSERT INTO user_billing (
+            user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval,
+            entitlement_state, trial_end, current_period_end, effective_until, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (user_id) DO UPDATE SET
+            stripe_customer_id = COALESCE(excluded.stripe_customer_id, user_billing.stripe_customer_id),
+            stripe_subscription_id = COALESCE(excluded.stripe_subscription_id, user_billing.stripe_subscription_id),
+            stripe_price_id = COALESCE(excluded.stripe_price_id, user_billing.stripe_price_id),
+            stripe_status = COALESCE(excluded.stripe_status, user_billing.stripe_status),
+            tier = COALESCE(excluded.tier, user_billing.tier),
+            billing_interval = COALESCE(excluded.billing_interval, user_billing.billing_interval),
+            entitlement_state = COALESCE(excluded.entitlement_state, user_billing.entitlement_state),
+            trial_end = COALESCE(excluded.trial_end, user_billing.trial_end),
+            current_period_end = COALESCE(excluded.current_period_end, user_billing.current_period_end),
+            effective_until = COALESCE(excluded.effective_until, user_billing.effective_until),
+            updated_at = excluded.updated_at
+    `).run(input.userId, tenantId, input.stripeCustomerId || null, input.stripeSubscriptionId || null, input.stripePriceId || null, input.stripeStatus || null, resolvedTier, input.billingInterval || null, input.canonicalState || null, input.trialEnd || null, input.currentPeriodEnd || null, input.effectiveUntil || null, now, now);
+}
+function resolveUserIdByCustomer(core, customerIdRaw) {
+    const customerId = String(customerIdRaw || '').trim();
+    if (!customerId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT user_id
+        FROM user_billing
+        WHERE tenant_id = ? AND stripe_customer_id = ?
+        LIMIT 1
+    `).get(tenantId, customerId);
+    return row?.user_id ? String(row.user_id) : null;
+}
+function resolveUserIdBySubscription(core, subscriptionIdRaw) {
+    const subscriptionId = String(subscriptionIdRaw || '').trim();
+    if (!subscriptionId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT user_id
+        FROM user_billing
+        WHERE tenant_id = ? AND stripe_subscription_id = ?
+        LIMIT 1
+    `).get(tenantId, subscriptionId);
+    return row?.user_id ? String(row.user_id) : null;
+}
+function purgeExpiredWebhookFailures(core) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const result = db.prepare(`
+        DELETE FROM stripe_webhook_failures
+        WHERE tenant_id = ?
+          AND purge_after < ?
+    `).run(tenantId, new Date().toISOString());
+    return Number(result?.changes || 0);
+}
+function recordWebhookFailure(core, input) {
+    try {
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const now = new Date();
+        const purgeAfter = new Date(now.getTime() + BILLING_DIAGNOSTIC_RETENTION_DAYS * 24 * 60 * 60 * 1000).toISOString();
+        const redacted = redactStripePayload(input.payload);
+        const excerpt = boundedPayloadExcerpt(redacted);
+        const id = `whf-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        db.prepare(`
+            INSERT INTO stripe_webhook_failures (id, tenant_id, event_id, event_type, reason, payload_excerpt, purge_after, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(id, tenantId, input.eventId, input.eventType, input.reason, excerpt, purgeAfter, now.toISOString());
+    }
+    catch {
+        // diagnostics are best-effort only
+    }
+}
+function resolvePriceAndIntervalFromInvoice(invoice) {
+    const line = invoice.lines?.data?.find((entry) => !!entry?.price?.id || !!entry?.pricing?.price_details?.price);
+    const legacyPriceId = String(line?.price?.id || '').trim();
+    const modernPriceId = String(line?.pricing?.price_details?.price || '').trim();
+    const priceId = modernPriceId || legacyPriceId || null;
+    const recurringInterval = parseInterval(line?.price?.recurring?.interval || '');
+    return { priceId, interval: recurringInterval };
+}
+function lockWebhookEvent(core, event) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const result = db.prepare(`
+        INSERT INTO stripe_webhook_events (event_id, tenant_id, event_type, processed_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (event_id) DO NOTHING
+    `).run(event.id, tenantId, event.type, new Date().toISOString());
+    return Number(result?.changes || 0) > 0;
+}
+async function importStripePrices(core) {
+    const stripe = getStripeClient();
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    const validPlanVersionIds = new Set(db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ?
+        `).all(tenantId).map((row) => String(row.plan_version_id || '')).filter(Boolean));
+    const importedPriceIds = new Set();
+    const summary = {
+        imported: 0,
+        skipped: 0,
+        deactivated: 0,
+        details: []
+    };
+    let startingAfter;
+    while (true) {
+        const page = await stripe.prices.list({
+            active: true,
+            limit: 100,
+            starting_after: startingAfter,
+            type: 'recurring'
+        });
+        for (const price of page.data) {
+            const interval = parseInterval(price.recurring?.interval || '');
+            const planVersionId = String(price.metadata?.[PRICE_METADATA_PLAN_VERSION] || '').trim();
+            if (!interval || !planVersionId || !validPlanVersionIds.has(planVersionId)) {
+                summary.skipped += 1;
+                summary.details.push({
+                    priceId: price.id,
+                    status: 'skipped',
+                    reason: !planVersionId
+                        ? `Missing metadata ${PRICE_METADATA_PLAN_VERSION}`
+                        : (!interval ? 'Unsupported interval' : 'Unknown plan_version_id')
+                });
+                continue;
+            }
+            db.prepare(`
+                INSERT INTO billing_price_mappings (
+                    tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, 1, ?, ?)
+                ON CONFLICT (tenant_id, stripe_price_id) DO UPDATE SET
+                    plan_version_id = excluded.plan_version_id,
+                    billing_interval = excluded.billing_interval,
+                    active = 1,
+                    updated_at = excluded.updated_at
+            `).run(tenantId, planVersionId, interval, price.id, now, now);
+            importedPriceIds.add(price.id);
+            summary.imported += 1;
+            summary.details.push({ priceId: price.id, status: 'imported' });
+        }
+        if (!page.has_more || page.data.length === 0)
+            break;
+        startingAfter = page.data[page.data.length - 1]?.id;
+        if (!startingAfter)
+            break;
+    }
+    const existing = db.prepare(`
+        SELECT stripe_price_id
+        FROM billing_price_mappings
+        WHERE tenant_id = ? AND active = 1
+    `).all(tenantId);
+    for (const row of existing) {
+        const priceId = String(row.stripe_price_id || '').trim();
+        if (!priceId || importedPriceIds.has(priceId))
+            continue;
+        db.prepare(`
+            UPDATE billing_price_mappings
+            SET active = 0, updated_at = ?
+            WHERE tenant_id = ? AND stripe_price_id = ?
+        `).run(now, tenantId, priceId);
+        summary.deactivated += 1;
+    }
+    return summary;
+}
+export function registerBillingRoutes(deps) {
+    const { addRoute, core, context, ensureAuthenticatedUser, ensureAdminRole, requestUserId, resolveErrorStatusCode, auditAdminAction } = deps;
+    const billingEnabled = () => parseBoolean(process.env.TASKFORCE_BILLING_ENABLED, false);
+    const ensureCloudBilling = (req, res) => {
+        if (!billingEnabled()) {
+            billingDisabledResponse(res);
+            return false;
+        }
+        const runtime = context.authConfig?.runtimeMode || requestRuntimeMode(req);
+        if (runtime !== 'cloud') {
+            cloudOnlyResponse(res);
+            return false;
+        }
+        return true;
+    };
+    addRoute('GET', '/api/taskforce/billing/status', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        try {
+            const userId = requestUserId(req);
+            const entitlement = core.getAccountEntitlement(userId);
+            const db = core.getDatabaseAdapter();
+            const tenantId = core.getTenantId();
+            const row = db.prepare(`
+                SELECT stripe_status, stripe_customer_id, stripe_subscription_id, stripe_price_id, billing_interval, trial_end, current_period_end, effective_until
+                FROM user_billing
+                WHERE tenant_id = ? AND user_id = ?
+                LIMIT 1
+            `).get(tenantId, userId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                stripeStatus: row?.stripe_status || null,
+                stripeCustomerId: row?.stripe_customer_id || null,
+                stripeSubscriptionId: row?.stripe_subscription_id || null,
+                stripePriceId: row?.stripe_price_id || null,
+                billingInterval: row?.billing_interval || null,
+                trialEnd: row?.trial_end || null,
+                currentPeriodEnd: row?.current_period_end || null,
+                effectiveUntil: row?.effective_until || null,
+                entitlementState: entitlement.state,
+                planVersionId: entitlement.planVersionId,
+                planId: entitlement.planId
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to read billing status'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/config', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const config = readBillingConfig(core);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(config));
+    });
+    addRoute('PUT', '/api/taskforce/admin/billing/config', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const trialDaysRaw = Number(body?.trial_days);
+        if (!Number.isFinite(trialDaysRaw) || trialDaysRaw < 1 || trialDaysRaw > 30) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'trial_days must be an integer between 1 and 30.' }));
+            return;
+        }
+        const nextConfig = {
+            trialDays: Math.floor(trialDaysRaw),
+            tiers: body?.tiers && typeof body.tiers === 'object' && !Array.isArray(body.tiers) ? body.tiers : {},
+            taxEnabled: parseBoolean(body?.tax_enabled, false),
+            billingAddress: String(body?.billing_address || '').trim().toLowerCase() === 'required' ? 'required' : 'auto'
+        };
+        writeBillingConfig(core, nextConfig);
+        auditAdminAction(req, 'billing-config-updated', { trialDays: nextConfig.trialDays, billingAddress: nextConfig.billingAddress });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(nextConfig));
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/prices', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const rows = db.prepare(`
+            SELECT plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at
+            FROM billing_price_mappings
+            WHERE tenant_id = ?
+            ORDER BY plan_version_id ASC, billing_interval ASC, stripe_price_id ASC
+        `).all(tenantId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ prices: rows }));
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/webhook-failures', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const queryLimit = req.url
+            ? new URL(req.url, 'https://taskforce.local').searchParams.get('limit')
+            : null;
+        const limit = parsePositiveIntBounded(queryLimit, 50, 1, 200);
+        const now = new Date().toISOString();
+        const purged = purgeExpiredWebhookFailures(core);
+        const rows = db.prepare(`
+            SELECT id, event_id, event_type, reason, payload_excerpt, created_at, purge_after
+            FROM stripe_webhook_failures
+            WHERE tenant_id = ?
+            ORDER BY created_at DESC
+            LIMIT ?
+        `).all(tenantId, limit);
+        const total = db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM stripe_webhook_failures
+            WHERE tenant_id = ?
+        `).get(tenantId);
+        const expiringSoon = db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM stripe_webhook_failures
+            WHERE tenant_id = ?
+              AND purge_after <= ?
+        `).get(tenantId, new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString());
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            asOf: now,
+            purgedExpiredRows: purged,
+            total: Number(total?.count || 0),
+            expiringWithin24h: Number(expiringSoon?.count || 0),
+            rows
+        }));
+    });
+    addRoute('POST', '/api/taskforce/admin/billing/prices/import', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const summary = await importStripePrices(core);
+            auditAdminAction(req, 'billing-prices-import', {
+                imported: summary.imported,
+                skipped: summary.skipped,
+                deactivated: summary.deactivated
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(summary));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to import Stripe prices'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/checkout-session', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const interval = parseInterval(body?.interval);
+        const planVersionId = String(body?.planVersionId || '').trim() || resolveDefaultPlanVersionId(core, body?.tier);
+        if (!interval || !planVersionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId (or tier) and interval are required.' }));
+            return;
+        }
+        const priceId = resolvePriceIdForPlanVersion(core, planVersionId, interval);
+        if (!priceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No active Stripe price mapping found for requested plan/interval.' }));
+            return;
+        }
+        try {
+            const stripe = getStripeClient();
+            const userId = requestUserId(req);
+            const baseUrl = resolveBaseUrl(req);
+            const config = readBillingConfig(core);
+            const session = await stripe.checkout.sessions.create({
+                mode: 'subscription',
+                line_items: [{ price: priceId, quantity: 1 }],
+                success_url: `${baseUrl}/billing/success?session_id={CHECKOUT_SESSION_ID}`,
+                cancel_url: `${baseUrl}/billing/cancel`,
+                subscription_data: {
+                    trial_period_days: config.trialDays
+                },
+                billing_address_collection: config.billingAddress,
+                automatic_tax: { enabled: config.taxEnabled },
+                customer_creation: 'always',
+                client_reference_id: userId,
+                metadata: {
+                    userId,
+                    tenantId: core.getTenantId(),
+                    planVersionId
+                }
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ url: session.url || null, id: session.id }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to create checkout session'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/portal-session', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const userId = requestUserId(req);
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const row = db.prepare(`
+            SELECT stripe_customer_id
+            FROM user_billing
+            WHERE tenant_id = ? AND user_id = ?
+            LIMIT 1
+        `).get(tenantId, userId);
+        const customerId = String(row?.stripe_customer_id || '').trim();
+        if (!customerId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No Stripe customer is linked for this account.' }));
+            return;
+        }
+        try {
+            const stripe = getStripeClient();
+            const baseUrl = resolveBaseUrl(req);
+            const session = await stripe.billingPortal.sessions.create({
+                customer: customerId,
+                return_url: `${baseUrl}/settings`
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ url: session.url }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to create portal session'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/subscription', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const interval = parseInterval(body?.interval);
+        const planVersionId = String(body?.planVersionId || '').trim() || resolveDefaultPlanVersionId(core, body?.tier);
+        if (!interval || !planVersionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId (or tier) and interval are required.' }));
+            return;
+        }
+        const nextPriceId = resolvePriceIdForPlanVersion(core, planVersionId, interval);
+        if (!nextPriceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No active Stripe price mapping found for requested plan/interval.' }));
+            return;
+        }
+        const userId = requestUserId(req);
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const row = db.prepare(`
+            SELECT stripe_subscription_id
+            FROM user_billing
+            WHERE tenant_id = ? AND user_id = ?
+            LIMIT 1
+        `).get(tenantId, userId);
+        const subscriptionId = String(row?.stripe_subscription_id || '').trim();
+        if (!subscriptionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No Stripe subscription is linked for this account.' }));
+            return;
+        }
+        try {
+            const stripe = getStripeClient();
+            const current = await stripe.subscriptions.retrieve(subscriptionId);
+            const itemId = current.items.data[0]?.id;
+            if (!itemId) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Subscription has no updatable line item.' }));
+                return;
+            }
+            const updated = await stripe.subscriptions.update(subscriptionId, {
+                items: [{ id: itemId, price: nextPriceId }],
+                proration_behavior: 'create_prorations',
+                metadata: {
+                    planVersionId
+                }
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ subscription: updated }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to update subscription'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/webhook', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        const webhookSecret = String(process.env.TASKFORCE_STRIPE_WEBHOOK_SECRET || '').trim();
+        if (!webhookSecret) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'TASKFORCE_STRIPE_WEBHOOK_SECRET is not configured.' }));
+            return;
+        }
+        const signature = String(req.headers['stripe-signature'] || '').trim();
+        if (!signature) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing Stripe signature.' }));
+            return;
+        }
+        let event;
+        let rawBody;
+        try {
+            rawBody = await readRawBody(req);
+            const stripe = getStripeClient();
+            event = stripe.webhooks.constructEvent(rawBody, signature, webhookSecret);
+        }
+        catch (error) {
+            const code = Number(error?.statusCode || 400);
+            res.writeHead(code >= 400 && code < 600 ? code : 400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Invalid webhook payload/signature') }));
+            return;
+        }
+        try {
+            const db = core.getDatabaseAdapter();
+            const tenantId = core.getTenantId();
+            purgeExpiredWebhookFailures(core);
+            let duplicate = false;
+            const tx = db.transaction(() => {
+                const acquired = lockWebhookEvent(core, event);
+                if (!acquired) {
+                    duplicate = true;
+                    return;
+                }
+                if (event.type === 'checkout.session.completed') {
+                    const session = event.data.object;
+                    const metadata = session.metadata || {};
+                    const customerId = String(session.customer || '').trim();
+                    const subscriptionId = String(session.subscription || '').trim();
+                    const userId = String(metadata.userId || metadata.user_id || '').trim()
+                        || resolveUserIdByCustomer(core, customerId)
+                        || resolveUserIdBySubscription(core, subscriptionId);
+                    if (!userId || !customerId) {
+                        throw new Error('Unable to link checkout completion to user/customer.');
+                    }
+                    core.createUserBillingRecord(userId);
+                    upsertBillingMirror(core, {
+                        userId,
+                        stripeCustomerId: customerId,
+                        stripeSubscriptionId: subscriptionId || null
+                    });
+                    return;
+                }
+                if (event.type === 'customer.subscription.created' || event.type === 'customer.subscription.updated' || event.type === 'customer.subscription.deleted') {
+                    const subscription = event.data.object;
+                    const customerId = String(subscription.customer || '').trim();
+                    const userId = resolveUserIdByCustomer(core, customerId)
+                        || String(subscription.metadata?.userId || subscription.metadata?.user_id || '').trim();
+                    if (!userId) {
+                        throw new Error('Unable to resolve user for subscription event.');
+                    }
+                    core.createUserBillingRecord(userId);
+                    const stripeStatus = String(subscription.status || '').trim().toLowerCase();
+                    const priceId = String(subscription.items?.data?.[0]?.price?.id || '').trim();
+                    const billingInterval = parseInterval(subscription.items?.data?.[0]?.price?.recurring?.interval || '');
+                    const planVersionId = resolvePlanVersionIdForPriceId(core, priceId);
+                    const existingEntitlement = getEntitlementRow(core, userId);
+                    const nowIso = new Date().toISOString();
+                    const currentPeriodEnd = resolveSubscriptionCurrentPeriodEnd(subscription);
+                    const trialEnd = isoFromUnixSeconds(subscription.trial_end);
+                    const canceledState = stripeStatus === 'canceled'
+                        ? (currentPeriodEnd && currentPeriodEnd > nowIso ? 'active' : 'canceled')
+                        : null;
+                    const canonicalState = canceledState || mapStripeStatusToCanonicalState(stripeStatus);
+                    const effectiveUntil = stripeStatus === 'canceled'
+                        ? currentPeriodEnd
+                        : (currentPeriodEnd || null);
+                    upsertBillingMirror(core, {
+                        userId,
+                        stripeCustomerId: customerId || null,
+                        stripeSubscriptionId: String(subscription.id || '').trim() || null,
+                        stripePriceId: priceId || null,
+                        stripeStatus: stripeStatus || null,
+                        planId: planVersionId ? resolvePlanIdForVersion(core, planVersionId) : null,
+                        billingInterval: billingInterval || null,
+                        canonicalState,
+                        trialEnd,
+                        currentPeriodEnd,
+                        effectiveUntil
+                    });
+                    if (!planVersionId) {
+                        recordWebhookFailure(core, {
+                            eventId: event.id,
+                            eventType: event.type,
+                            reason: `Unknown price mapping for price_id=${priceId || '(empty)'}`,
+                            payload: event
+                        });
+                        return;
+                    }
+                    upsertCanonicalEntitlement(core, {
+                        userId,
+                        planVersionId: planVersionId || existingEntitlement?.plan_version_id || 'free-v1',
+                        state: canonicalState,
+                        effectiveAt: trialEnd || nowIso,
+                        effectiveUntil
+                    });
+                    return;
+                }
+                if (event.type === 'invoice.paid' || event.type === 'invoice.payment_failed') {
+                    const invoice = event.data.object;
+                    const customerId = String(invoice.customer || '').trim();
+                    const subscriptionId = resolveInvoiceSubscriptionId(invoice);
+                    const userId = resolveUserIdByCustomer(core, customerId)
+                        || resolveUserIdBySubscription(core, subscriptionId);
+                    if (!userId) {
+                        throw new Error('Unable to resolve user for invoice event.');
+                    }
+                    core.createUserBillingRecord(userId);
+                    const { priceId, interval } = resolvePriceAndIntervalFromInvoice(invoice);
+                    const planVersionId = resolvePlanVersionIdForPriceId(core, priceId);
+                    const existingEntitlement = getEntitlementRow(core, userId);
+                    const canonicalState = event.type === 'invoice.payment_failed' ? 'grace' : 'active';
+                    const currentPeriodEnd = invoice.lines?.data?.[0]?.period?.end
+                        ? isoFromUnixSeconds(invoice.lines.data[0].period.end)
+                        : null;
+                    upsertBillingMirror(core, {
+                        userId,
+                        stripeCustomerId: customerId || null,
+                        stripeSubscriptionId: subscriptionId || null,
+                        stripePriceId: priceId || null,
+                        stripeStatus: event.type === 'invoice.payment_failed' ? 'past_due' : 'active',
+                        planId: planVersionId ? resolvePlanIdForVersion(core, planVersionId) : null,
+                        billingInterval: interval || null,
+                        canonicalState,
+                        currentPeriodEnd,
+                        effectiveUntil: currentPeriodEnd
+                    });
+                    if (!planVersionId) {
+                        recordWebhookFailure(core, {
+                            eventId: event.id,
+                            eventType: event.type,
+                            reason: `Unknown price mapping for price_id=${priceId || '(empty)'}`,
+                            payload: event
+                        });
+                        return;
+                    }
+                    upsertCanonicalEntitlement(core, {
+                        userId,
+                        planVersionId: planVersionId || existingEntitlement?.plan_version_id || 'free-v1',
+                        state: canonicalState,
+                        effectiveAt: new Date().toISOString(),
+                        effectiveUntil: currentPeriodEnd
+                    });
+                    return;
+                }
+            });
+            tx();
+            if (duplicate) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ received: true, duplicate: true }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ received: true }));
+        }
+        catch (error) {
+            recordWebhookFailure(core, {
+                eventId: event.id,
+                eventType: event.type,
+                reason: String(error?.message || error || 'WEBHOOK_PROCESSING_FAILED'),
+                payload: event
+            });
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Webhook processing failed. Retry expected.' }));
+        }
+    });
+}