fraim 2.0.351 → 2.0.353

package/dist/src/api/payment/webhook.js

@@ -2,21 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDashboardAccessUrl = void 0;
 exports.handleStripeWebhook = handleStripeWebhook;
-exports.resolveSubscriptionNextBillingDate = resolveSubscriptionNextBillingDate;
 exports.isInitialSubscriptionInvoice = isInitialSubscriptionInvoice;
 exports.getInvoiceAmountPaidCents = getInvoiceAmountPaidCents;
-exports.extractSubscriptionPeriodEndDate = extractSubscriptionPeriodEndDate;
-exports.extractInvoicePeriodEndDate = extractInvoicePeriodEndDate;
-exports.resolveSubscriptionNextBillingDateWithInvoiceFallback = resolveSubscriptionNextBillingDateWithInvoiceFallback;
-exports.buildCurrentPeriodEndUpdate = buildCurrentPeriodEndUpdate;
-exports.resolveInvoicePaidNextBillingDate = resolveInvoicePaidNextBillingDate;
 const stripe_1 = require("../../config/stripe");
-const redact_secrets_1 = require("../../core/utils/redact-secrets");
 const feature_flags_1 = require("../../config/feature-flags");
 const email_service_1 = require("../../services/email-service");
 const dashboard_access_1 = require("../../services/dashboard-access");
 Object.defineProperty(exports, "createDashboardAccessUrl", { enumerable: true, get: function () { return dashboard_access_1.createDashboardAccessUrl; } });
 const persona_entitlement_service_1 = require("../../services/persona-entitlement-service");
+const subscription_provisioning_1 = require("../../services/subscription-provisioning");
 async function handleStripeWebhook(req, res, paymentRepo, dbService) {
     const sig = req.headers['stripe-signature'];
     if (!sig) {
@@ -61,8 +55,11 @@ async function handleStripeWebhook(req, res, paymentRepo, dbService) {
                 console.log(`ℹ️ Webhook ${event.id} already processed (race condition), skipping`);
                 return res.json({ received: true, skipped: true });
             }
+            if (error.message === 'Webhook event is processing') {
+                return res.status(503).json({ error: 'Webhook event is still being processed; retry later' });
+            }
             console.error('❌ Error recording webhook event:', error);
-            // Continue processing even if recording fails
+            return res.status(500).json({ error: 'Could not claim webhook event for processing' });
         }
     }
     try {
@@ -132,417 +129,94 @@ async function handleStripeWebhook(req, res, paymentRepo, dbService) {
     }
 }
 // ========== Subscription Lifecycle Handlers ==========
-async function resolveSubscriptionNextBillingDate(subscription, subscriptionRetriever = (subscriptionId) => stripe_1.stripe.subscriptions.retrieve(subscriptionId)) {
-    const directPeriodEnd = extractSubscriptionPeriodEndDate(subscription);
-    if (directPeriodEnd) {
-        return directPeriodEnd;
-    }
-    if (!subscription.id) {
-        return null;
-    }
-    try {
-        const fetchedSubscription = await subscriptionRetriever(subscription.id);
-        const fetchedPeriodEnd = extractSubscriptionPeriodEndDate(fetchedSubscription);
-        if (fetchedPeriodEnd) {
-            return fetchedPeriodEnd;
-        }
-    }
-    catch (error) {
-        console.warn(`⚠️ Failed to retrieve subscription ${subscription.id} for period end: ${error?.message || error}`);
-    }
-    return null;
-}
 function isInitialSubscriptionInvoice(invoice) {
     return invoice.billing_reason === 'subscription_create';
 }
 function getInvoiceAmountPaidCents(invoice) {
     return typeof invoice.amount_paid === 'number' ? Math.max(0, invoice.amount_paid) : null;
 }
-function extractSubscriptionPeriodEndDate(subscription) {
-    const rootPeriodEnd = subscription.current_period_end;
-    if (typeof rootPeriodEnd === 'number' && rootPeriodEnd > 0) {
-        return new Date(rootPeriodEnd * 1000);
-    }
-    const itemEnds = (subscription.items?.data || [])
-        .map((item) => item?.current_period_end)
-        .filter((value) => typeof value === 'number' && value > 0);
-    if (itemEnds.length > 0) {
-        // Use the earliest upcoming period boundary across items.
-        return new Date(Math.min(...itemEnds) * 1000);
-    }
-    return null;
-}
-function extractInvoicePeriodEndDate(invoice) {
-    const rootPeriodEnd = invoice.period_end;
-    if (typeof rootPeriodEnd === 'number' && rootPeriodEnd > 0) {
-        return new Date(rootPeriodEnd * 1000);
-    }
-    const linePeriodEnds = (invoice.lines?.data || [])
-        .map((line) => line?.period?.end)
-        .filter((value) => typeof value === 'number' && value > 0);
-    if (linePeriodEnds.length > 0) {
-        // Use the furthest period end across recurring/proration lines.
-        return new Date(Math.max(...linePeriodEnds) * 1000);
-    }
-    return null;
-}
-async function resolveSubscriptionNextBillingDateWithInvoiceFallback(subscription, subscriptionRetriever = (subscriptionId) => stripe_1.stripe.subscriptions.retrieve(subscriptionId), invoiceRetriever = (invoiceId) => stripe_1.stripe.invoices.retrieve(invoiceId)) {
-    const subscriptionDate = await resolveSubscriptionNextBillingDate(subscription, subscriptionRetriever);
-    if (subscriptionDate)
-        return subscriptionDate;
-    const latestInvoiceField = subscription.latest_invoice;
-    if (latestInvoiceField && typeof latestInvoiceField === 'object') {
-        const invoiceDate = extractInvoicePeriodEndDate(latestInvoiceField);
-        if (invoiceDate)
-            return invoiceDate;
-    }
-    if (typeof latestInvoiceField === 'string' && latestInvoiceField) {
-        try {
-            const latestInvoice = await invoiceRetriever(latestInvoiceField);
-            const invoiceDate = extractInvoicePeriodEndDate(latestInvoice);
-            if (invoiceDate)
-                return invoiceDate;
-        }
-        catch (error) {
-            console.warn(`⚠️ Failed to retrieve latest invoice ${latestInvoiceField} for subscription ${subscription.id}: ${error?.message || error}`);
-        }
-    }
-    return null;
-}
-function buildCurrentPeriodEndUpdate(nextBillingDate) {
-    return nextBillingDate ? { currentPeriodEnd: nextBillingDate } : {};
-}
-async function resolveInvoicePaidNextBillingDate(invoice, subscription, subscriptionDateResolver = resolveSubscriptionNextBillingDate) {
-    const subscriptionDate = subscription ? await subscriptionDateResolver(subscription) : null;
-    return subscriptionDate || extractInvoicePeriodEndDate(invoice);
-}
 function extractFounderDiscountFlagFromSubscription(subscription) {
     return subscription.metadata?.founderDiscount === 'true';
 }
+async function reconcileSubscription(subscription, dbService) {
+    const customerId = (0, subscription_provisioning_1.subscriptionCustomerId)(subscription);
+    const customer = await stripe_1.stripe.customers.retrieve(customerId);
+    const email = !('deleted' in customer) && customer.id === customerId ? customer.email?.trim().toLowerCase() : null;
+    if (!email)
+        throw new Error('Could not verify subscription customer identity');
+    return (0, subscription_provisioning_1.provisionSubscriptionApiKey)(dbService, email, subscription, (0, subscription_provisioning_1.subscriptionPeriodEnd)(subscription));
+}
 async function handleSubscriptionCreatedOrUpdated(subscription, dbService) {
-    console.log(`✅ Subscription ${subscription.status}: ${subscription.id}`);
-    if (subscription.metadata?.plan === 'persona-hire') {
-        if ((0, feature_flags_1.isPersonaEntitlementsEnabled)()) {
-            const customerId = typeof subscription.customer === 'string'
-                ? subscription.customer
-                : subscription.customer.id;
-            const customer = await stripe_1.stripe.customers.retrieve(customerId);
-            const email = !('deleted' in customer) ? customer.email : null;
-            if (email && subscription.metadata.personaKey && (subscription.metadata.hireMode === 'job' || subscription.metadata.hireMode === 'fulltime')) {
-                const nextBillingDate = await resolveSubscriptionNextBillingDateWithInvoiceFallback(subscription);
-                await (0, persona_entitlement_service_1.syncPersonaEntitlementPurchase)(dbService, {
-                    userId: email,
-                    stripeCustomerId: customerId,
-                    stripeSubscriptionId: subscription.id,
-                    stripeCheckoutSessionId: null,
-                    personaKey: subscription.metadata.personaKey,
-                    hireMode: subscription.metadata.hireMode,
-                    purchaseSource: 'stripe-webhook',
-                    status: subscription.status === 'active' ? 'active' : 'suspended',
-                    expiresAt: nextBillingDate,
-                    metadata: subscription.metadata
-                });
-            }
-        }
-        console.log(`ℹ️ Skipping API-key provisioning for persona hire subscription: ${subscription.id}`);
-        return;
+    const current = await stripe_1.stripe.subscriptions.retrieve(subscription.id);
+    if (current.id !== subscription.id || (0, subscription_provisioning_1.subscriptionCustomerId)(current) !== (0, subscription_provisioning_1.subscriptionCustomerId)(subscription)) {
+        throw new Error('Subscription event customer does not match current subscription');
     }
-    const customerId = typeof subscription.customer === 'string'
-        ? subscription.customer
-        : subscription.customer.id;
-    // Get or create API key for this customer
-    let apiKey = await dbService.getApiKeyByStripeCustomerId(customerId);
-    if (!apiKey) {
-        // Check if subscription has customer email in metadata
-        const customer = await stripe_1.stripe.customers.retrieve(customerId);
-        const email = customer.email;
-        if (!email) {
-            console.error(`❌ No email found for customer ${customerId}`);
-            return;
-        }
-        // Check if user already has an API key (trial user upgrading)
-        apiKey = await dbService.getApiKeyByUserId(email);
-        const nextBillingDate = await resolveSubscriptionNextBillingDateWithInvoiceFallback(subscription);
-        if (apiKey) {
-            // Upgrade trial key to paid subscription
-            await dbService.updateApiKey(apiKey.key, {
-                tier: 'paid-subscription',
-                status: subscription.status === 'active' ? 'active' : 'suspended',
-                stripeCustomerId: customerId,
-                stripeSubscriptionId: subscription.id,
-                ...buildCurrentPeriodEndUpdate(nextBillingDate),
-                expiresAt: null, // Subscriptions don't have fixed expiration
-                cancelAt: subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null
-            });
-            console.log(`✅ Upgraded trial key to paid subscription: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
-        }
-        else {
-            // Create new API key for subscription (shouldn't happen in normal flow)
-            const newKey = dbService.generateApiKey(email, 'default');
-            await dbService.createApiKey({
-                key: newKey,
-                userId: email,
-                orgId: 'default',
-                tier: 'paid-subscription',
-                status: subscription.status === 'active' ? 'active' : 'suspended',
-                expiresAt: null,
-                stripeCustomerId: customerId,
-                stripeSubscriptionId: subscription.id,
-                currentPeriodEnd: nextBillingDate,
-                cancelAt: subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null,
-                suspendedAt: null,
-                suspensionReason: null,
-                lastUsedAt: null,
-                apiCallCount: 0,
-                personaSystemActive: (0, feature_flags_1.isPersonaEntitlementsEnabled)() || undefined
-            });
-            console.log(`✅ Created new API key for subscription: ${(0, redact_secrets_1.redactApiKey)(newKey)}`);
-            apiKey = { key: newKey, userId: email };
-        }
-    }
-    else {
-        // Update existing subscription key
-        const nextBillingDate = await resolveSubscriptionNextBillingDateWithInvoiceFallback(subscription);
-        await dbService.updateApiKey(apiKey.key, {
-            tier: 'paid-subscription',
-            status: subscription.status === 'active' ? 'active' : 'suspended',
-            stripeCustomerId: customerId,
-            stripeSubscriptionId: subscription.id,
-            ...buildCurrentPeriodEndUpdate(nextBillingDate),
-            expiresAt: null,
-            cancelAt: subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null,
-            suspendedAt: subscription.status !== 'active' ? new Date() : null,
-            suspensionReason: subscription.status !== 'active' ? subscription.status : null
-        });
-    }
-    // Intentionally no activation email here.
-    // Billing-confirmed messaging is sent from invoice.paid for Stripe source-of-truth amounts.
+    await reconcileSubscription(current, dbService);
 }
 async function handleSubscriptionDeleted(subscription, dbService) {
-    if (subscription.metadata?.plan === 'persona-hire' && (0, feature_flags_1.isPersonaEntitlementsEnabled)()) {
-        const customerId = typeof subscription.customer === 'string'
-            ? subscription.customer
-            : subscription.customer.id;
-        const customer = await stripe_1.stripe.customers.retrieve(customerId);
-        const email = !('deleted' in customer) ? customer.email : null;
-        if (email && subscription.metadata.personaKey && subscription.metadata.hireMode === 'fulltime') {
-            await (0, persona_entitlement_service_1.syncPersonaEntitlementPurchase)(dbService, {
-                userId: email,
-                stripeCustomerId: customerId,
-                stripeSubscriptionId: subscription.id,
-                stripeCheckoutSessionId: null,
-                personaKey: subscription.metadata.personaKey,
-                hireMode: 'fulltime',
-                purchaseSource: 'stripe-webhook',
-                status: 'expired',
-                expiresAt: new Date(),
-                metadata: subscription.metadata
-            });
-        }
-    }
-    console.log(`❌ Subscription cancelled: ${subscription.id}`);
-    if (subscription.metadata?.plan === 'persona-hire') {
-        console.log(`ℹ️ Skipping persona hire cancellation handling for subscription: ${subscription.id}`);
-        return;
-    }
-    const apiKey = await dbService.getApiKeyByStripeSubscriptionId(subscription.id);
-    if (!apiKey) {
-        console.warn(`⚠️ No API key found for subscription: ${subscription.id}`);
-        return;
+    const key = await reconcileSubscription({ ...subscription, status: 'canceled' }, dbService);
+    await new email_service_1.EmailService().sendSubscriptionCancelled(key.userId, key.stripeSubscriptionEndedAt || new Date());
+}
+async function subscriptionForInvoice(invoice) {
+    const field = invoice.subscription || invoice.parent?.subscription_details?.subscription;
+    const id = typeof field === 'string' ? field : field?.id;
+    if (!id)
+        return null;
+    const customerId = typeof invoice.customer === 'string' ? invoice.customer : invoice.customer?.id;
+    const subscription = await stripe_1.stripe.subscriptions.retrieve(id);
+    if (!customerId || subscription.id !== id || (0, subscription_provisioning_1.subscriptionCustomerId)(subscription) !== customerId) {
+        throw new Error('Invoice subscription customer does not match');
     }
-    // Mark key as expired
-    await dbService.updateApiKey(apiKey.key, {
-        status: 'expired',
-        expiresAt: new Date(), // Expired now
-        cancelAt: null
-    });
-    // Send cancellation email
-    const emailService = new email_service_1.EmailService();
-    await emailService.sendSubscriptionCancelled(apiKey.userId, new Date());
-    console.log(`✅ API key expired due to subscription cancellation: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
+    return subscription;
 }
 async function handleInvoicePaid(invoice, dbService) {
-    console.log(`✅ Invoice paid: ${invoice.id}`);
-    const subscriptionField = invoice.subscription;
-    if (!subscriptionField) {
-        console.log(`ℹ️ Invoice is not for a subscription, skipping`);
-        return;
-    }
-    const subscriptionId = typeof subscriptionField === 'string'
-        ? subscriptionField
-        : subscriptionField.id;
-    const customerId = typeof invoice.customer === 'string'
-        ? invoice.customer
-        : invoice.customer?.id;
-    let apiKey = await dbService.getApiKeyByStripeSubscriptionId(subscriptionId);
-    if (!apiKey && customerId) {
-        apiKey = await dbService.getApiKeyByStripeCustomerId(customerId);
-        if (apiKey) {
-            await dbService.updateApiKey(apiKey.key, { stripeSubscriptionId: subscriptionId });
-        }
-    }
-    if (!apiKey && (0, feature_flags_1.isPersonaEntitlementsEnabled)() && invoice.customer_email) {
-        try {
-            const subscription = await stripe_1.stripe.subscriptions.retrieve(subscriptionId);
-            if (subscription.metadata?.plan === 'persona-hire') {
-                apiKey = { userId: invoice.customer_email };
-            }
-        }
-        catch (error) {
-            console.warn(`⚠️ Failed persona entitlement prefetch for invoice ${invoice.id}: ${error?.message || error}`);
-        }
-    }
-    if (!apiKey) {
-        console.warn(`⚠️ No API key found for subscription: ${subscriptionId}`);
+    const subscription = await subscriptionForInvoice(invoice);
+    if (!subscription)
         return;
-    }
-    const isInitialSubscriptionCharge = isInitialSubscriptionInvoice(invoice);
-    const amountPaidCents = getInvoiceAmountPaidCents(invoice);
-    let subscriptionForInvoice = null;
-    try {
-        subscriptionForInvoice = await stripe_1.stripe.subscriptions.retrieve(subscriptionId);
-    }
-    catch (error) {
-        console.warn(`⚠️ Failed to retrieve subscription ${subscriptionId} during invoice.paid: ${error?.message || error}`);
-    }
-    if (subscriptionForInvoice?.metadata?.plan === 'persona-hire') {
-        if ((0, feature_flags_1.isPersonaEntitlementsEnabled)() && subscriptionForInvoice.metadata.personaKey && subscriptionForInvoice.metadata.hireMode === 'fulltime') {
-            const email = apiKey?.userId || invoice.customer_email;
-            if (email) {
-                await (0, persona_entitlement_service_1.syncPersonaEntitlementPurchase)(dbService, {
-                    userId: email,
-                    stripeCustomerId: customerId || null,
-                    stripeSubscriptionId: subscriptionId,
-                    stripeCheckoutSessionId: null,
-                    personaKey: subscriptionForInvoice.metadata.personaKey,
-                    hireMode: 'fulltime',
-                    purchaseSource: 'stripe-webhook',
-                    status: 'active',
-                    expiresAt: await resolveInvoicePaidNextBillingDate(invoice, subscriptionForInvoice),
-                    metadata: {
-                        ...subscriptionForInvoice.metadata,
-                        latestInvoiceId: invoice.id
-                    }
-                });
-            }
-        }
-        console.log(`ℹ️ Skipping API-key activation emails for persona hire subscription: ${subscriptionId}`);
-        return;
-    }
-    const nextBillingDate = await resolveInvoicePaidNextBillingDate(invoice, subscriptionForInvoice);
-    const currentPeriodPatch = buildCurrentPeriodEndUpdate(nextBillingDate);
-    // Restore key if it was suspended due to payment failure
-    if (apiKey.status === 'suspended') {
-        await dbService.updateApiKey(apiKey.key, {
-            status: 'active',
-            ...currentPeriodPatch,
-            suspendedAt: null,
-            suspensionReason: null
-        });
-        console.log(`✅ API key restored after payment: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
-        // Send restoration email
-        const emailService = new email_service_1.EmailService();
-        const restorationBillingDate = nextBillingDate || new Date();
-        await emailService.sendPaymentRestored(apiKey.userId, restorationBillingDate);
+    const prior = await dbService.getApiKeyByStripeSubscriptionId(subscription.id);
+    const key = await reconcileSubscription(subscription, dbService);
+    // Notifications trigger reconciliation; only verified collection authorizes a receipt.
+    if (key.stripeSubscriptionEndedAt || key.paymentStatus !== 'paid'
+        || key.paidInvoiceId !== invoice.id || !key.paidThrough || key.status !== 'active')
         return;
+    const emailService = new email_service_1.EmailService();
+    if (prior?.status === 'suspended') {
+        await emailService.sendPaymentRestored(key.userId, key.paidThrough);
     }
-    if (isInitialSubscriptionCharge) {
-        // First paid subscription charge: send activation using Stripe invoice + subscription data
-        const emailService = new email_service_1.EmailService();
-        const subscription = subscriptionForInvoice || await stripe_1.stripe.subscriptions.retrieve(subscriptionId);
-        const activationBillingDate = nextBillingDate || await resolveSubscriptionNextBillingDate(subscription);
-        const billingCycle = subscription.items.data[0]?.price?.recurring?.interval === 'year' ? 'annual' : 'monthly';
-        const plan = subscription.items.data[0]?.price?.nickname ||
-            (subscription.metadata?.plan === 'managed' ? 'FRAIM Managed' : 'FRAIM Self-Serve');
-        const founderDiscount = extractFounderDiscountFlagFromSubscription(subscription);
-        if (activationBillingDate) {
-            await dbService.updateApiKey(apiKey.key, buildCurrentPeriodEndUpdate(activationBillingDate));
-        }
-        if (amountPaidCents === null || !activationBillingDate) {
-            console.warn(`⚠️ Skipping subscription activation email due to missing Stripe invoice/subscription data for ${subscriptionId}`);
+    else if (isInitialSubscriptionInvoice(invoice)) {
+        const recurring = subscription.items.data[0]?.price?.recurring;
+        const amount = getInvoiceAmountPaidCents(invoice);
+        if (amount === null)
+            return;
+        const cadence = recurring?.interval === 'year' ? 'annual' : recurring?.interval === 'month' ? 'monthly' : null;
+        if (!cadence || (recurring?.interval_count || 1) !== 1) {
+            await emailService.sendRenewalReceipt(key.userId, amount, key.paidThrough, invoice.hosted_invoice_url || undefined);
             return;
         }
-        const dashboardUrl = await (0, dashboard_access_1.createDashboardAccessUrl)(dbService, apiKey.userId, apiKey.key);
-        await emailService.sendSubscriptionActivated(apiKey.userId, plan, amountPaidCents, billingCycle, activationBillingDate, dashboardUrl, founderDiscount);
-        return;
+        const plan = subscription.items.data[0]?.price?.nickname
+            || (subscription.metadata.plan === 'persona-hire' ? subscription.metadata.personaKey : 'FRAIM');
+        await emailService.sendSubscriptionActivated(key.userId, plan, amount, cadence, key.paidThrough, await (0, dashboard_access_1.createDashboardAccessUrl)(dbService, key.userId, key.key), extractFounderDiscountFlagFromSubscription(subscription));
     }
-    // Regular renewal
-    {
-        console.log(`✅ Subscription renewed: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
-        if (nextBillingDate) {
-            await dbService.updateApiKey(apiKey.key, buildCurrentPeriodEndUpdate(nextBillingDate));
-        }
-        // Send renewal receipt
-        const emailService = new email_service_1.EmailService();
-        const amount = (invoice.amount_paid || 0) / 100;
-        const renewalBillingDate = nextBillingDate || new Date();
-        await emailService.sendRenewalReceipt(apiKey.userId, amount, renewalBillingDate, invoice.hosted_invoice_url || undefined);
+    else {
+        await emailService.sendRenewalReceipt(key.userId, invoice.amount_paid || 0, key.paidThrough, invoice.hosted_invoice_url || undefined);
     }
 }
 async function handleInvoicePaymentFailed(invoice, dbService) {
-    console.log(`❌ Invoice payment failed: ${invoice.id}`);
-    const subscriptionField = invoice.subscription;
-    if (!subscriptionField) {
-        console.log(`ℹ️ Invoice is not for a subscription, skipping`);
+    const subscription = await subscriptionForInvoice(invoice);
+    if (!subscription)
         return;
-    }
-    const subscriptionId = typeof subscriptionField === 'string'
-        ? subscriptionField
-        : subscriptionField.id;
-    try {
-        const subscription = await stripe_1.stripe.subscriptions.retrieve(subscriptionId);
-        if (subscription.metadata?.plan === 'persona-hire') {
-            if ((0, feature_flags_1.isPersonaEntitlementsEnabled)()) {
-                const customerId = typeof subscription.customer === 'string'
-                    ? subscription.customer
-                    : subscription.customer.id;
-                const customer = await stripe_1.stripe.customers.retrieve(customerId);
-                const email = !('deleted' in customer) ? customer.email : null;
-                if (email && subscription.metadata.personaKey && subscription.metadata.hireMode === 'fulltime') {
-                    await (0, persona_entitlement_service_1.syncPersonaEntitlementPurchase)(dbService, {
-                        userId: email,
-                        stripeCustomerId: customerId,
-                        stripeSubscriptionId: subscriptionId,
-                        stripeCheckoutSessionId: null,
-                        personaKey: subscription.metadata.personaKey,
-                        hireMode: 'fulltime',
-                        purchaseSource: 'stripe-webhook',
-                        status: 'suspended',
-                        metadata: {
-                            ...subscription.metadata,
-                            latestFailedInvoiceId: invoice.id
-                        }
-                    });
-                }
-            }
-            console.log(`ℹ️ Skipping persona hire payment-failure handling for subscription: ${subscriptionId}`);
-            return;
-        }
-    }
-    catch (error) {
-        console.warn(`⚠️ Failed to retrieve subscription ${subscriptionId} during invoice.payment_failed: ${error?.message || error}`);
-    }
-    const apiKey = await dbService.getApiKeyByStripeSubscriptionId(subscriptionId);
-    if (!apiKey) {
-        console.warn(`⚠️ No API key found for subscription: ${subscriptionId}`);
+    const key = await reconcileSubscription(subscription, dbService);
+    if (key.stripeSubscriptionEndedAt || key.paymentStatus !== 'unpaid')
         return;
-    }
-    // Suspend API key
-    await dbService.updateApiKey(apiKey.key, {
-        status: 'suspended',
-        suspendedAt: new Date(),
-        suspensionReason: 'payment_failed'
-    });
-    console.log(`✅ API key suspended due to payment failure: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
-    // Send payment failure email with 7-day grace period
-    const emailService = new email_service_1.EmailService();
-    const gracePeriodEndsAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
-    const billingPortalUrl = process.env.STRIPE_BILLING_PORTAL_URL || 'https://fraimworks.ai/billing';
-    await emailService.sendPaymentFailed(apiKey.userId, billingPortalUrl, gracePeriodEndsAt);
+    await new email_service_1.EmailService().sendPaymentFailed(key.userId, process.env.STRIPE_BILLING_PORTAL_URL || 'https://fraimworks.ai/billing', key.expiresAt);
 }
 // ========== Legacy Payment Handlers ==========
 async function handleCheckoutSessionCompleted(session, paymentRepo, dbService) {
-    if (dbService && (0, feature_flags_1.isPersonaEntitlementsEnabled)() && session.metadata?.plan === 'persona-hire') {
+    if (dbService && session.subscription) {
+        const id = typeof session.subscription === 'string' ? session.subscription : session.subscription.id;
+        await handleSubscriptionCreatedOrUpdated(await stripe_1.stripe.subscriptions.retrieve(id), dbService);
+    }
+    else if (dbService && (0, feature_flags_1.isPersonaEntitlementsEnabled)() && session.metadata?.plan === 'persona-hire') {
         await (0, persona_entitlement_service_1.syncPersonaEntitlementFromCheckoutSession)(dbService, session, 'stripe-checkout');
     }
     console.log(`✅ Checkout session completed: ${session.id}`);

package/dist/src/api/personas/me.js

@@ -10,16 +10,13 @@ async function getMyPersonas(req, res, dbService) {
             res.status(401).json({ error: 'Authentication required' });
             return;
         }
-        // Feature OFF => the persona system isn't gating anything, so report the
-        // ungated state (every persona accessible) rather than a 404. This makes the
-        // authenticated persona view a single source of truth the Hub renders
-        // verbatim, and matches the execution gate (maybeBuildPersonaLockResponse),
-        // which also treats "flag off" as "allowed". No DB lookup needed.
-        if (!(0, feature_flags_1.isPersonaEntitlementsEnabled)()) {
+        // General licenses keep their rollout behavior. A purchased persona-only
+        // license always reports its purchased scope, even while the flag is off.
+        if (!(0, feature_flags_1.isPersonaEntitlementsEnabled)() && apiKeyData.accessScope !== 'persona') {
             res.json((0, persona_entitlement_service_1.buildUngatedPersonaWorkspaceState)(apiKeyData.userId, apiKeyData.key));
             return;
         }
-        const state = await (0, persona_entitlement_service_1.getWorkspacePersonaState)(dbService, apiKeyData.userId, apiKeyData.key);
+        const state = await (0, persona_entitlement_service_1.getWorkspacePersonaState)(dbService, apiKeyData.userId, apiKeyData.key, (0, feature_flags_1.isPersonaEntitlementsEnabled)());
         res.json(state);
     }
     catch (error) {

package/dist/src/cli/commands/sync.js

@@ -272,10 +272,11 @@ const runSync = async (options) => {
     // fix reaches an installed machine up to a window late and nothing the user can run shortens
     // that. Writing the record here makes `npx fraim@latest sync` the deliberate way to pull a
     // release through immediately: it resolves latest, runs as latest, and records latest, which
-    // the next MCP server spawn picks up at once.
+    // the next MCP server spawn picks up at once. Automatic catalog sync does not select a
+    // launcher version: an older running server must not overwrite a background update.
     const { ensureFraimMcpLatestLauncher, recordFraimMcpLauncherVersion } = await Promise.resolve().then(() => __importStar(require('../mcp/fraim-mcp-latest-launcher')));
     ensureFraimMcpLatestLauncher();
-    if (recordFraimMcpLauncherVersion((0, version_utils_1.getFraimVersion)())) {
+    if (recordFraimMcpLauncherVersion((0, version_utils_1.getFraimVersion)(), options.automatic ? 'automatic-sync' : 'explicit-sync')) {
         console.log(chalk_1.default.green(`  MCP launcher will use fraim@${(0, version_utils_1.getFraimVersion)()} on its next launch`));
     }
     // 1f. Ensure user-level directories and runtime dependencies (Issue #1508: