@taskforcehq/taskforce 0.3.305 → 0.3.306

package/dist/server/routes/authSupport.d.ts

@@ -13,7 +13,7 @@ export declare function buildAuthFlowBehavior(core: TaskforceCore): {
 };
 export declare function buildAuthBehavior(core: TaskforceCore): {
     onboardingPolicyMode: import("../../core/types.js").OnboardingPolicyMode;
-    onboardingPlanVersionId: string | null;
+    onboardingPlanId: string | null;
     allowSelfRegistration: boolean;
     requireVerifiedEmail: boolean;
     defaultNewUserBetaAccess: boolean;

package/dist/server/routes/authSupport.js

@@ -45,7 +45,7 @@ export function buildAuthBehavior(core) {
     return {
         ...authBehavior,
         onboardingPolicyMode: onboardingPolicy.mode,
-        onboardingPlanVersionId: onboardingPolicy.planVersionId
+        onboardingPlanId: onboardingPolicy.planId
     };
 }
 export function buildSiteBehavior(core) {

package/dist/server/routes/billing.js

@@ -8,16 +8,63 @@ const BILLING_DIAGNOSTIC_RETENTION_DAYS = 30;
 const BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES = 8 * 1024;
 const BILLING_CHECKOUT_ATTEMPT_RETENTION_DAYS = 14;
 const BILLING_STATUS_RECONCILIATION_TTL_MS = 30_000;
+const PUBLIC_PRICING_CACHE_TTL_MS = 60_000;
 const TASKFORCE_PROXY_ORIGIN_HOST_HEADER = 'x-taskforce-origin-host';
 const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = 'x-taskforce-origin-proto';
 const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = 'x-taskforce-origin-base-url';
 const TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER = 'x-taskforce-origin-runtime';
+const INTERNAL_PUBLIC_PRICING_FEATURE_KEYS = new Set([
+    'collaboration.invites',
+    'collaboration.seat_limit'
+]);
+const publicPricingCache = new Map();
 function parsePricingType(raw) {
     const value = String(raw || '').trim().toLowerCase();
     if (value === 'stripe' || value === 'free')
         return value;
     return null;
 }
+function readTableVersionStats(core, tableName) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    try {
+        const row = db.prepare(`
+            SELECT COUNT(*) AS count, MAX(updated_at) AS max_updated_at
+            FROM ${tableName}
+            WHERE tenant_id = ?
+        `).get(tenantId);
+        return {
+            count: Number(row?.count || 0),
+            maxUpdatedAt: String(row?.max_updated_at || '')
+        };
+    }
+    catch (error) {
+        const message = String(error?.message || '');
+        if (message.toLowerCase().includes(`no such table: ${tableName}`)) {
+            return { count: 0, maxUpdatedAt: '' };
+        }
+        throw error;
+    }
+}
+function buildPublicPricingCacheVersion(core) {
+    const catalog = readTableVersionStats(core, 'plan_catalog');
+    const versions = readTableVersionStats(core, 'plan_versions');
+    const prices = readTableVersionStats(core, 'billing_price_mappings');
+    const features = readTableVersionStats(core, 'plan_feature_matrix');
+    const featureCatalogOverrides = readTableVersionStats(core, 'plan_feature_catalog_overrides');
+    return [
+        catalog.count,
+        catalog.maxUpdatedAt,
+        versions.count,
+        versions.maxUpdatedAt,
+        prices.count,
+        prices.maxUpdatedAt,
+        features.count,
+        features.maxUpdatedAt,
+        featureCatalogOverrides.count,
+        featureCatalogOverrides.maxUpdatedAt
+    ].join('|');
+}
 function buildFreePricingSyntheticId(planVersionId, interval) {
     return `free:${planVersionId}:${interval}`;
 }
@@ -664,7 +711,11 @@ function resolveCheckoutLifecycleGuard(core, input) {
         : currentOpenAttempt;
     const attemptStatus = String(checkoutAttempt?.status || '').trim().toLowerCase();
     const attemptPlanVersionId = String(checkoutAttempt?.plan_version_id || '').trim();
+    const sourceLabel = String(input.source || 'checkout-confirm').trim() || 'checkout-confirm';
     if (attemptStatus === 'expired') {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked expired checkout for user=${input.userId} source=${sourceLabel} `
+            + `session=${String(input.sessionId || '').trim() || '(none)'} subscription=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} attemptPlanVersionId=${attemptPlanVersionId || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_EXPIRED',
@@ -672,6 +723,9 @@ function resolveCheckoutLifecycleGuard(core, input) {
         };
     }
     if (attemptStatus === 'superseded') {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked superseded checkout for user=${input.userId} source=${sourceLabel} `
+            + `session=${String(input.sessionId || '').trim() || '(none)'} subscription=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} attemptPlanVersionId=${attemptPlanVersionId || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -679,6 +733,9 @@ function resolveCheckoutLifecycleGuard(core, input) {
         };
     }
     if (attemptStatus === 'open' && attemptPlanVersionId && input.planVersionId && attemptPlanVersionId !== input.planVersionId) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked mismatched open checkout for user=${input.userId} source=${sourceLabel} `
+            + `session=${String(input.sessionId || '').trim() || '(none)'} subscription=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} attemptPlanVersionId=${attemptPlanVersionId}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -688,6 +745,9 @@ function resolveCheckoutLifecycleGuard(core, input) {
     const currentBilling = getBillingMirrorRow(core, input.userId);
     const currentSubscriptionId = String(currentBilling?.stripe_subscription_id || '').trim();
     if (!currentOpenAttempt && input.subscriptionId && currentSubscriptionId && currentSubscriptionId !== input.subscriptionId) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked stale subscription linkage for user=${input.userId} source=${sourceLabel} `
+            + `currentSubscriptionId=${currentSubscriptionId} requestedSubscriptionId=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -701,17 +761,28 @@ function resolveCheckoutLifecycleGuard(core, input) {
     const currentPlanVersionId = String(entitlement.plan_version_id || '').trim();
     const updatedBy = String(entitlement.updated_by || '').trim().toLowerCase();
     const expiredPendingCheckout = currentState === 'checkout_pending' && isIsoTimestampExpired(entitlement.effective_until);
-    if (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired')) {
+    const fromStripeWebhook = input.source === 'stripe-webhook';
+    if (!fromStripeWebhook && (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired'))) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked expired entitlement recovery for user=${input.userId} source=${sourceLabel} `
+            + `entitlementState=${currentState || '(none)'} updatedBy=${updatedBy || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} currentPlanVersionId=${currentPlanVersionId || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_EXPIRED',
             message: 'This checkout session expired. Choose a plan and start checkout again.'
         };
     }
+    if (fromStripeWebhook && (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired'))) {
+        console.info(`[Taskforce Billing] Lifecycle guard allowed authoritative webhook recovery for user=${input.userId} `
+            + `subscription=${String(input.subscriptionId || '').trim() || '(none)'} requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} `
+            + `entitlementState=${currentState || '(none)'} updatedBy=${updatedBy || '(none)'}`);
+    }
     if (currentState === 'checkout_pending'
         && currentPlanVersionId
         && input.planVersionId
         && currentPlanVersionId !== input.planVersionId) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked superseded checkout_pending entitlement for user=${input.userId} source=${sourceLabel} `
+            + `currentPlanVersionId=${currentPlanVersionId} requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -1330,11 +1401,18 @@ export function registerBillingRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        res.writeHead(410, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            error: 'Manual Stripe price selection has been removed. Refresh prices from Stripe metadata instead.',
-            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
-        }));
+        try {
+            const requestUrl = parseRequestUrl(req);
+            const interval = parseInterval(requestUrl.searchParams.get('interval'));
+            const options = await listStripePriceOptions(interval);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ options }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to list Stripe prices'), code: error?.code }));
+        }
     });
     addRoute('PUT', '/api/taskforce/admin/billing/price-mappings', async (req, res) => {
         if (!ensureCloudBilling(req, res))
@@ -1344,11 +1422,138 @@ export function registerBillingRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        res.writeHead(410, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            error: 'Manual billing price mappings have been removed. Import Stripe prices instead.',
-            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
-        }));
+        const body = await parseJsonBody(req);
+        const planVersionId = String(body?.planVersionId || '').trim();
+        const interval = parseInterval(body?.interval);
+        const pricingType = parsePricingType(body?.pricingType) || 'stripe';
+        const stripePriceId = String(body?.stripePriceId || '').trim();
+        const setActive = body?.active === false ? false : true;
+        if (!planVersionId || !interval) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId and interval are required.', code: 'BILLING_MAPPING_INPUT_REQUIRED' }));
+            return;
+        }
+        if (pricingType === 'stripe' && !stripePriceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'stripePriceId is required for Stripe pricing.', code: 'BILLING_MAPPING_STRIPE_PRICE_REQUIRED' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const versionExists = db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ?
+            LIMIT 1
+        `).get(tenantId, planVersionId);
+        if (!versionExists?.plan_version_id) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Plan version not found.', code: 'PLAN_VERSION_NOT_FOUND' }));
+            return;
+        }
+        try {
+            const now = new Date().toISOString();
+            const targetStripePriceId = pricingType === 'free'
+                ? buildFreePricingSyntheticId(planVersionId, interval)
+                : stripePriceId;
+            let unitAmount = 0;
+            let currency = null;
+            if (pricingType === 'stripe') {
+                const stripe = getStripeClient();
+                const stripePrice = await stripe.prices.retrieve(stripePriceId);
+                const stripeInterval = parseInterval(stripePrice.recurring?.interval || '');
+                if (!stripePrice.active) {
+                    res.writeHead(422, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Stripe price is not active.', code: 'STRIPE_PRICE_INACTIVE' }));
+                    return;
+                }
+                if (!stripeInterval) {
+                    res.writeHead(422, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Stripe price must be recurring month/year.', code: 'STRIPE_PRICE_INTERVAL_UNSUPPORTED' }));
+                    return;
+                }
+                if (stripeInterval !== interval) {
+                    res.writeHead(422, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `Stripe price interval (${stripeInterval}) does not match requested interval (${interval}).`, code: 'STRIPE_PRICE_INTERVAL_MISMATCH' }));
+                    return;
+                }
+                const conflictingMapping = db.prepare(`
+                    SELECT plan_version_id
+                    FROM billing_price_mappings
+                    WHERE tenant_id = ?
+                      AND stripe_price_id = ?
+                      AND active = 1
+                      AND plan_version_id <> ?
+                    LIMIT 1
+                `).get(tenantId, stripePriceId, planVersionId);
+                if (conflictingMapping?.plan_version_id) {
+                    res.writeHead(409, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        error: `Stripe price ${stripePriceId} is already mapped to ${String(conflictingMapping.plan_version_id)}.`,
+                        code: 'BILLING_PRICE_ALREADY_ASSIGNED'
+                    }));
+                    return;
+                }
+                unitAmount = typeof stripePrice.unit_amount === 'number' ? stripePrice.unit_amount : null;
+                currency = stripePrice.currency || null;
+            }
+            const beforeRows = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+                ORDER BY stripe_price_id ASC
+            `).all(tenantId, planVersionId, interval);
+            if (setActive) {
+                db.prepare(`
+                    UPDATE billing_price_mappings
+                    SET active = 0, updated_at = ?
+                    WHERE tenant_id = ?
+                      AND plan_version_id = ?
+                      AND billing_interval = ?
+                      AND stripe_price_id <> ?
+                      AND active = 1
+                `).run(now, tenantId, planVersionId, interval, targetStripePriceId);
+            }
+            db.prepare(`
+                INSERT INTO billing_price_mappings (
+                    tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (tenant_id, plan_version_id, billing_interval, stripe_price_id) DO UPDATE SET
+                    pricing_type = excluded.pricing_type,
+                    active = excluded.active,
+                    unit_amount = excluded.unit_amount,
+                    currency = excluded.currency,
+                    updated_at = excluded.updated_at
+            `).run(tenantId, planVersionId, interval, targetStripePriceId, pricingType, setActive ? 1 : 0, unitAmount, currency, now, now);
+            const mapping = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ? AND stripe_price_id = ?
+                LIMIT 1
+            `).get(tenantId, planVersionId, interval, targetStripePriceId);
+            const afterRows = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+                ORDER BY stripe_price_id ASC
+            `).all(tenantId, planVersionId, interval);
+            auditAdminAction(req, 'billing-price-mapping-upsert', {
+                planVersionId,
+                interval,
+                pricingType,
+                stripePriceId: pricingType === 'free' ? null : stripePriceId,
+                active: setActive,
+                before: beforeRows,
+                after: afterRows
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ mapping }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to upsert price mapping'), code: error?.code }));
+        }
     });
     addRoute('POST', '/api/taskforce/admin/billing/price-mappings/deactivate', async (req, res) => {
         if (!ensureCloudBilling(req, res))
@@ -1358,11 +1563,51 @@ export function registerBillingRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        res.writeHead(410, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            error: 'Manual billing price mappings have been removed. Refresh Stripe prices instead.',
-            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
-        }));
+        const body = await parseJsonBody(req);
+        const planVersionId = String(body?.planVersionId || '').trim();
+        const interval = parseInterval(body?.interval);
+        const stripePriceId = String(body?.stripePriceId || '').trim();
+        if (!planVersionId || !interval) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId and interval are required.', code: 'BILLING_MAPPING_TARGET_REQUIRED' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const now = new Date().toISOString();
+        const beforeRows = db.prepare(`
+            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+            FROM billing_price_mappings
+            WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+            ORDER BY stripe_price_id ASC
+        `).all(tenantId, planVersionId, interval);
+        const result = stripePriceId
+            ? db.prepare(`
+                UPDATE billing_price_mappings
+                SET active = 0, updated_at = ?
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ? AND stripe_price_id = ?
+            `).run(now, tenantId, planVersionId, interval, stripePriceId)
+            : db.prepare(`
+                UPDATE billing_price_mappings
+                SET active = 0, updated_at = ?
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+            `).run(now, tenantId, planVersionId, interval);
+        const afterRows = db.prepare(`
+            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+            FROM billing_price_mappings
+            WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+            ORDER BY stripe_price_id ASC
+        `).all(tenantId, planVersionId, interval);
+        auditAdminAction(req, 'billing-price-mapping-deactivate', {
+            planVersionId,
+            interval,
+            stripePriceId: stripePriceId || null,
+            changedRows: Number(result?.changes || 0),
+            before: beforeRows,
+            after: afterRows
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, changedRows: Number(result?.changes || 0) }));
     });
     addRoute('GET', '/api/taskforce/admin/billing/webhook-failures', async (req, res) => {
         if (!ensureCloudBilling(req, res))
@@ -1741,10 +1986,17 @@ export function registerBillingRoutes(deps) {
                 planVersionId,
                 interval
             });
+            const successParams = new URLSearchParams({
+                screen: 'plans',
+                checkout: 'success',
+                planId: String(planId || ''),
+                planVersionId,
+                interval
+            });
             const session = await stripe.checkout.sessions.create({
                 mode: 'subscription',
                 line_items: [{ price: priceId, quantity: 1 }],
-                success_url: `${baseUrl}/?screen=plans&checkout=success&session_id={CHECKOUT_SESSION_ID}`,
+                success_url: `${baseUrl}/?${successParams.toString()}&session_id={CHECKOUT_SESSION_ID}`,
                 cancel_url: `${baseUrl}/?${cancelParams.toString()}`,
                 ...(resolvedCustomerId
                     ? { customer: resolvedCustomerId }
@@ -1863,7 +2115,10 @@ export function registerBillingRoutes(deps) {
             }
             if (resolvedUserId !== expectedUserId) {
                 res.writeHead(403, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'Checkout session does not belong to the current account.' }));
+                res.end(JSON.stringify({
+                    error: 'Checkout session does not belong to the current account.',
+                    code: 'CHECKOUT_SESSION_ACCOUNT_MISMATCH'
+                }));
                 return;
             }
             let resolvedPlanVersionId = null;
@@ -1883,7 +2138,8 @@ export function registerBillingRoutes(deps) {
                     userId: resolvedUserId,
                     planVersionId: resolvedPlanVersionId,
                     sessionId,
-                    subscriptionId
+                    subscriptionId,
+                    source: 'checkout-confirm'
                 });
                 if (lifecycleGuard.blocked) {
                     res.writeHead(409, { 'Content-Type': 'application/json' });
@@ -1902,12 +2158,14 @@ export function registerBillingRoutes(deps) {
                 }));
                 return;
             }
-            core.createUserBillingRecord(resolvedUserId);
-            upsertBillingMirror(core, {
-                userId: resolvedUserId,
-                stripeCustomerId: customerId || null,
-                stripeSubscriptionId: subscriptionId || null
-            });
+            if (!resolvedPlanVersionId) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout completed, but the purchased plan could not be resolved yet.',
+                    code: 'CHECKOUT_PLAN_VERSION_UNRESOLVED'
+                }));
+                return;
+            }
             const snapshot = applySubscriptionSnapshot(core, {
                 userId: resolvedUserId,
                 subscription,
@@ -2165,7 +2423,8 @@ export function registerBillingRoutes(deps) {
                     const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
                         userId,
                         planVersionId,
-                        subscriptionId: String(subscription.id || '').trim()
+                        subscriptionId: String(subscription.id || '').trim(),
+                        source: 'stripe-webhook'
                     });
                     if (lifecycleGuard.blocked) {
                         recordWebhookFailure(core, {
@@ -2210,7 +2469,8 @@ export function registerBillingRoutes(deps) {
                     const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
                         userId,
                         planVersionId,
-                        subscriptionId
+                        subscriptionId,
+                        source: 'stripe-webhook'
                     });
                     if (lifecycleGuard.blocked) {
                         recordWebhookFailure(core, {
@@ -2292,6 +2552,15 @@ export function registerBillingRoutes(deps) {
         try {
             const db = core.getDatabaseAdapter();
             const tenantId = core.getTenantId();
+            const environment = requestPricingEnvironment(req);
+            const cacheKey = `${tenantId}:${environment}`;
+            const cacheVersion = buildPublicPricingCacheVersion(core);
+            const cached = publicPricingCache.get(cacheKey);
+            if (cached && cached.version === cacheVersion && cached.expiresAt > Date.now()) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(cached.payload));
+                return;
+            }
             // Get all active plans
             const activePlans = core.listPlanCatalog().filter(p => p.status === 'active');
             // Get all active price mappings with their amounts
@@ -2300,6 +2569,17 @@ export function registerBillingRoutes(deps) {
                 FROM billing_price_mappings
                 WHERE tenant_id = ? AND active = 1
             `).all(tenantId);
+            const pricingByVersionAndInterval = new Map();
+            for (const price of activePrices) {
+                const planVersionId = String(price.plan_version_id || '').trim();
+                const interval = parseInterval(price.billing_interval);
+                if (!planVersionId || !interval)
+                    continue;
+                pricingByVersionAndInterval.set(`${planVersionId}:${interval}`, price);
+            }
+            const featureCatalog = core.listPlanFeatureCatalog();
+            const featureCatalogByKey = new Map(featureCatalog.map((feature) => [feature.featureKey, feature]));
+            const featureCatalogIndexByKey = new Map(featureCatalog.map((feature, index) => [feature.featureKey, index]));
             const plansPayload = activePlans.map((plan) => {
                 const versions = core.listPlanVersions(plan.planId);
                 // Prefer default, else fallback to highest version number
@@ -2307,11 +2587,12 @@ export function registerBillingRoutes(deps) {
                 if (!defaultVersion) {
                     return null; // Skip if no valid version exists (edge case)
                 }
-                const monthPrice = activePrices.find(p => p.plan_version_id === defaultVersion.planVersionId && p.billing_interval === 'month');
-                const yearPrice = activePrices.find(p => p.plan_version_id === defaultVersion.planVersionId && p.billing_interval === 'year');
+                const monthPrice = pricingByVersionAndInterval.get(`${defaultVersion.planVersionId}:month`);
+                const yearPrice = pricingByVersionAndInterval.get(`${defaultVersion.planVersionId}:year`);
                 return {
                     planId: plan.planId,
                     displayName: plan.displayName,
+                    description: plan.description ?? null,
                     status: plan.status,
                     defaultVersion: {
                         planVersionId: defaultVersion.planVersionId,
@@ -2320,9 +2601,48 @@ export function registerBillingRoutes(deps) {
                         trialDays: defaultVersion.trialDays,
                         metadata: defaultVersion.metadata
                     },
-                    features: Object.values(defaultVersion.features || {}).filter((feature) => {
+                    features: Object.values(defaultVersion.features || {})
+                        .reduce((acc, feature) => {
                         const access = String(feature?.access || '').trim().toLowerCase();
-                        return access !== 'disabled';
+                        if (access === 'disabled') {
+                            return acc;
+                        }
+                        const featureKey = String(feature?.featureKey || '').trim();
+                        if (!featureKey || INTERNAL_PUBLIC_PRICING_FEATURE_KEYS.has(featureKey)) {
+                            return acc;
+                        }
+                        const catalogEntry = featureCatalogByKey.get(featureKey);
+                        acc.push({
+                            featureKey,
+                            access,
+                            config: feature?.config && typeof feature.config === 'object'
+                                ? feature.config
+                                : {},
+                            label: catalogEntry?.label ?? null,
+                            description: catalogEntry?.description ?? null,
+                            publicLabel: catalogEntry?.publicLabel ?? null,
+                            publicDescription: catalogEntry?.publicDescription ?? null
+                        });
+                        return acc;
+                    }, [])
+                        .sort((a, b) => {
+                        const orderA = featureCatalogByKey.get(a.featureKey)?.publicDisplayOrder;
+                        const orderB = featureCatalogByKey.get(b.featureKey)?.publicDisplayOrder;
+                        const normalizedOrderA = typeof orderA === 'number' && Number.isFinite(orderA)
+                            ? orderA
+                            : Number.MAX_SAFE_INTEGER;
+                        const normalizedOrderB = typeof orderB === 'number' && Number.isFinite(orderB)
+                            ? orderB
+                            : Number.MAX_SAFE_INTEGER;
+                        if (normalizedOrderA !== normalizedOrderB) {
+                            return normalizedOrderA - normalizedOrderB;
+                        }
+                        const catalogIndexA = featureCatalogIndexByKey.get(a.featureKey) ?? Number.MAX_SAFE_INTEGER;
+                        const catalogIndexB = featureCatalogIndexByKey.get(b.featureKey) ?? Number.MAX_SAFE_INTEGER;
+                        if (catalogIndexA !== catalogIndexB) {
+                            return catalogIndexA - catalogIndexB;
+                        }
+                        return a.featureKey.localeCompare(b.featureKey);
                     }),
                     pricing: {
                         month: monthPrice ? {
@@ -2342,15 +2662,21 @@ export function registerBillingRoutes(deps) {
                     }
                 };
             }).filter(Boolean);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
+            const payload = {
                 asOf: new Date().toISOString(),
                 pricingSource: {
-                    environment: requestPricingEnvironment(req),
+                    environment,
                     runtimeMode: 'cloud'
                 },
                 plans: plansPayload
-            }));
+            };
+            publicPricingCache.set(cacheKey, {
+                payload,
+                version: cacheVersion,
+                expiresAt: Date.now() + PUBLIC_PRICING_CACHE_TTL_MS
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(payload));
         }
         catch (error) {
             const statusCode = resolveErrorStatusCode(error, 500);