thumbgate 1.5.8 → 1.6.0

package/scripts/billing.js

@@ -16,7 +16,13 @@ function withTimeout(promise, ms = STRIPE_TIMEOUT_MS) {
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { createTraceId } = require('./hosted-config');
+const https = require('https');
+const {
+  DEFAULT_PUBLIC_APP_ORIGIN,
+  createTraceId,
+  joinPublicUrl,
+  normalizeOrigin,
+} = require('./hosted-config');
 const {
   getFeedbackPaths,
   getLegacyFeedbackDir,
@@ -44,6 +50,7 @@ const {
   serializeAnalyticsWindow,
 } = require('./analytics-window');
 const { ensureParentDir } = require('./fs-utils');
+const mailer = require('./mailer');
 
 // ---------------------------------------------------------------------------
 // Config
@@ -74,6 +81,12 @@ const CONFIG = {
   get NEWSLETTER_SUBSCRIBERS_PATH() {
     return process.env._TEST_NEWSLETTER_SUBSCRIBERS_PATH || path.join(getFeedbackPaths().FEEDBACK_DIR, 'newsletter-subscribers.jsonl');
   },
+  get TRIAL_EMAIL_LEDGER_PATH() {
+    return process.env._TEST_TRIAL_EMAIL_LEDGER_PATH || process.env.THUMBGATE_TRIAL_EMAIL_LEDGER_PATH || path.join(getFeedbackPaths().FEEDBACK_DIR, 'trial-emails.jsonl');
+  },
+  RESEND_API_KEY: process.env.RESEND_API_KEY || process.env.THUMBGATE_RESEND_API_KEY || '',
+  TRIAL_EMAIL_FROM: process.env.THUMBGATE_TRIAL_EMAIL_FROM || process.env.RESEND_FROM_EMAIL || process.env.RESEND_FROM || 'onboarding@resend.dev',
+  TRIAL_EMAIL_REPLY_TO: process.env.THUMBGATE_TRIAL_EMAIL_REPLY_TO || 'igor.ganapolsky@gmail.com',
   CREDIT_PACKS: {}
 };
 
@@ -379,6 +392,407 @@ function normalizeText(value) {
   return text || null;
 }
 
+function resolvePublicAppOrigin(appOrigin) {
+  return normalizeOrigin(appOrigin) || normalizeOrigin(process.env.THUMBGATE_PUBLIC_APP_ORIGIN) || DEFAULT_PUBLIC_APP_ORIGIN;
+}
+
+function resolveCheckoutBrandUrls(appOrigin) {
+  const origin = resolvePublicAppOrigin(appOrigin);
+  return {
+    icon: joinPublicUrl(origin, '/assets/brand/thumbgate-icon-512.png'),
+    logo: joinPublicUrl(origin, '/assets/brand/thumbgate-logo-1200x360.png'),
+  };
+}
+
+function buildCheckoutBrandingSettings(appOrigin) {
+  const brandUrls = resolveCheckoutBrandUrls(appOrigin);
+  return {
+    display_name: 'ThumbGate',
+    logo: {
+      type: 'url',
+      url: brandUrls.logo,
+    },
+    background_color: '#ffffff',
+    button_color: '#22d3ee',
+    border_style: 'rounded',
+    font_family: 'inter',
+  };
+}
+
+function buildCheckoutProductData({ name, description, appOrigin }) {
+  const brandUrls = resolveCheckoutBrandUrls(appOrigin);
+  return {
+    name,
+    description,
+    images: [brandUrls.icon],
+  };
+}
+
+function buildSubscriptionPriceData(checkoutSelection, appOrigin) {
+  const isTeam = checkoutSelection.planId === 'team';
+  const annual = checkoutSelection.billingCycle === 'annual';
+  const unitAmount = isTeam
+    ? TEAM_MONTHLY_PRICE_DOLLARS * 100
+    : (annual ? PRO_ANNUAL_PRICE_DOLLARS : PRO_MONTHLY_PRICE_DOLLARS) * 100;
+  return {
+    currency: 'usd',
+    unit_amount: unitAmount,
+    recurring: {
+      interval: annual ? 'year' : 'month',
+    },
+    product_data: buildCheckoutProductData({
+      name: isTeam ? 'ThumbGate Team' : 'ThumbGate Pro',
+      description: isTeam
+        ? 'Shared Pre-Action Gates, team governance, and workflow hardening for AI coding agents.'
+        : 'Local dashboard, DPO export, and Pre-Action Gates for AI coding agents.',
+      appOrigin,
+    }),
+  };
+}
+
+function normalizeEmail(value) {
+  const text = normalizeText(value);
+  if (!text || !text.includes('@')) return null;
+  return text.toLowerCase();
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function findTrialEmailRecord({ sessionId, customerEmail, statuses = null } = {}) {
+  const normalizedEmail = normalizeEmail(customerEmail);
+  const rows = loadJsonlRecords(CONFIG.TRIAL_EMAIL_LEDGER_PATH);
+  return rows.find((row) => {
+    if (!row || typeof row !== 'object') return false;
+    if (statuses && !statuses.includes(row.status)) return false;
+    if (sessionId && row.sessionId === sessionId) return true;
+    return normalizedEmail && row.customerEmail === normalizedEmail;
+  }) || null;
+}
+
+function appendTrialEmailRecord(payload) {
+  return appendJsonlRecord(CONFIG.TRIAL_EMAIL_LEDGER_PATH, {
+    timestamp: new Date().toISOString(),
+    provider: payload.provider || 'resend',
+    ...payload,
+  });
+}
+
+/**
+ * Resolve the trial expiry date for a Stripe checkout session.
+ *
+ * Prefers an explicit `subscription.trial_end` unix timestamp when the session
+ * embeds one (subscriptions with trial_period_days populate it). Falls back to
+ * the session's `expires_at`, and finally to now + 7 days. Always returns a
+ * Date; never throws.
+ */
+function computeTrialEndAt(session) {
+  const TRIAL_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+  if (session && session.subscription && typeof session.subscription === 'object') {
+    const trialEndUnix = session.subscription.trial_end;
+    if (typeof trialEndUnix === 'number' && trialEndUnix > 0) {
+      return new Date(trialEndUnix * 1000);
+    }
+  }
+  if (session && typeof session.trial_end === 'number' && session.trial_end > 0) {
+    return new Date(session.trial_end * 1000);
+  }
+  return new Date(Date.now() + TRIAL_DAYS_MS);
+}
+
+function buildTrialActivationEmail({ customerEmail, apiKey, sessionId, planId, appOrigin } = {}) {
+  const email = normalizeEmail(customerEmail);
+  const origin = resolvePublicAppOrigin(appOrigin);
+  const dashboardUrl = joinPublicUrl(origin, '/dashboard');
+  const docsUrl = 'https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/VERIFICATION_EVIDENCE.md';
+  const command = `npx thumbgate pro --activate --key=${apiKey || ''}`;
+  const subject = 'Your 7-day ThumbGate Pro trial is live';
+  const preheader = 'Activate Pro in one command, open the dashboard, and start blocking repeated AI coding mistakes.';
+  const headline = 'Your 7-day ThumbGate Pro trial is live.';
+  const intro = 'ThumbGate turns thumbs up/down feedback into Pre-Action Gates that stop repeated AI coding mistakes before the next tool call. It keeps lessons local and turns repeated mistakes into Reliability Gateway blocks.';
+  const exampleFeedback = 'thumbs down: the answer skipped exact files and tests; next time include paths, commands, and verification evidence.';
+  const safeDashboardUrl = escapeHtml(dashboardUrl);
+  const safeDocsUrl = escapeHtml(docsUrl);
+  const safeCommand = escapeHtml(command);
+  const safeApiKey = escapeHtml(apiKey || '');
+  return {
+    from: CONFIG.TRIAL_EMAIL_FROM,
+    to: [email],
+    reply_to: CONFIG.TRIAL_EMAIL_REPLY_TO,
+    subject,
+    text: [
+      headline,
+      '',
+      intro,
+      '',
+      'Next 3 minutes:',
+      '1. Activate Pro locally:',
+      command,
+      '',
+      `2. Open your dashboard: ${dashboardUrl}`,
+      '',
+      '3. Give one concrete thumbs up or thumbs down:',
+      exampleFeedback,
+      '',
+      'Your trial key:',
+      apiKey,
+      '',
+      `Verification evidence: ${docsUrl}`,
+      'Keep this key private. Questions? Reply to this email or write hello@thumbgate.app.',
+      sessionId ? `Stripe session: ${sessionId}` : null,
+      planId ? `Plan: ${planId}` : null,
+    ].filter(Boolean).join('\n'),
+    html: `<!doctype html>
+<html>
+  <body style="margin:0;background:#f5f7fb;padding:28px 12px;font-family:Inter,-apple-system,BlinkMacSystemFont,'Segoe UI',Arial,sans-serif;color:#17212b;">
+    <div style="display:none;max-height:0;overflow:hidden;opacity:0;color:transparent;">${escapeHtml(preheader)}</div>
+    <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="border-collapse:collapse;">
+      <tr>
+        <td align="center">
+          <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="border-collapse:collapse;max-width:640px;background:#ffffff;border:1px solid #d8e2ea;border-radius:8px;overflow:hidden;">
+            <tr>
+              <td style="background:#071115;padding:22px 26px;color:#e7fbff;">
+                <div style="font-size:13px;font-weight:700;letter-spacing:0;text-transform:uppercase;color:#73d4e9;">ThumbGate Pro</div>
+                <h1 style="margin:12px 0 10px;font-size:28px;line-height:1.15;color:#ffffff;">${escapeHtml(headline)}</h1>
+                <p style="margin:0;font-size:15px;line-height:1.6;color:#c6d6de;">${escapeHtml(intro)}</p>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:26px;">
+                <p style="margin:0 0 18px;font-size:15px;line-height:1.6;color:#344451;">Run one command, open the dashboard, then give one concrete thumb signal. ThumbGate keeps the lesson local and turns repeated mistakes into Reliability Gateway blocks.</p>
+                <p style="margin:0 0 24px;">
+                  <a href="${safeDashboardUrl}" style="display:inline-block;background:#45bfd8;color:#061015;text-decoration:none;font-weight:700;padding:12px 18px;border-radius:6px;">Open your dashboard</a>
+                </p>
+
+                <h2 style="margin:0 0 8px;font-size:17px;line-height:1.3;color:#17212b;">1. Activate Pro locally</h2>
+                <pre style="margin:0 0 22px;background:#081016;color:#d8f7e4;border:1px solid #23343d;border-radius:6px;padding:14px;font-size:13px;line-height:1.45;white-space:pre-wrap;word-break:break-word;"><code>${safeCommand}</code></pre>
+
+                <h2 style="margin:0 0 8px;font-size:17px;line-height:1.3;color:#17212b;">2. Save your trial key</h2>
+                <pre style="margin:0 0 22px;background:#eef6f7;color:#0b343c;border:1px solid #c7e2e7;border-radius:6px;padding:14px;font-size:13px;line-height:1.45;white-space:pre-wrap;word-break:break-word;"><code>${safeApiKey}</code></pre>
+
+                <h2 style="margin:0 0 8px;font-size:17px;line-height:1.3;color:#17212b;">3. Give one concrete thumbs up or thumbs down</h2>
+                <p style="margin:0 0 14px;font-size:14px;line-height:1.6;color:#344451;">Start with the failure you most want your agent to stop repeating.</p>
+                <pre style="margin:0 0 24px;background:#f1fff2;color:#22602b;border:1px solid #bae7c0;border-radius:6px;padding:14px;font-size:13px;line-height:1.45;white-space:pre-wrap;word-break:break-word;"><code>${escapeHtml(exampleFeedback)}</code></pre>
+
+                <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="border-collapse:collapse;margin:0 0 22px;">
+                  <tr>
+                    <td style="border:1px solid #d8e2ea;border-radius:8px;padding:14px;background:#fbfdff;">
+                      <strong style="display:block;margin:0 0 6px;font-size:14px;color:#17212b;">Why this matters now</strong>
+                      <span style="font-size:13px;line-height:1.55;color:#526273;">One correction should become a permanent pre-action block, not a note the next agent forgets.</span>
+                    </td>
+                  </tr>
+                </table>
+
+                <p style="margin:0;font-size:13px;line-height:1.6;color:#526273;">
+                  Proof trail: <a href="${safeDocsUrl}" style="color:#087a91;">verification evidence</a>.
+                  Keep this key private. Questions? Reply here or write <a href="mailto:hello@thumbgate.app" style="color:#087a91;">hello@thumbgate.app</a>.
+                </p>
+                ${sessionId ? `<p style="margin:12px 0 0;font-size:12px;line-height:1.5;color:#7a8790;">Stripe session: ${escapeHtml(sessionId)}</p>` : ''}
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>`,
+  };
+}
+
+function sendResendEmail(message) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify(message);
+    const req = https.request({
+      hostname: 'api.resend.com',
+      path: '/emails',
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${CONFIG.RESEND_API_KEY}`,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: 10000,
+    }, (res) => {
+      let responseBody = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { responseBody += chunk; });
+      res.on('end', () => {
+        let parsed = {};
+        try {
+          parsed = responseBody ? JSON.parse(responseBody) : {};
+        } catch {
+          parsed = { raw: responseBody };
+        }
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve({ ok: true, statusCode: res.statusCode, body: parsed });
+          return;
+        }
+        const err = new Error(parsed.message || parsed.error || `Resend API returned HTTP ${res.statusCode}`);
+        err.statusCode = res.statusCode;
+        err.body = parsed;
+        reject(err);
+      });
+    });
+    req.on('timeout', () => req.destroy(new Error('Resend API timeout')));
+    req.on('error', reject);
+    req.end(body);
+  });
+}
+
+async function sendTrialActivationEmail(params = {}, options = {}) {
+  const customerEmail = normalizeEmail(params.customerEmail);
+  const sessionId = normalizeText(params.sessionId);
+  const apiKey = normalizeText(params.apiKey);
+  const injectedMailer = module.exports && module.exports._mailer;
+  const mailerTransport = !options.transport && injectedMailer && typeof injectedMailer.sendTrialWelcomeEmail === 'function'
+    ? injectedMailer
+    : null;
+  const transport = options.transport || sendResendEmail;
+  const planId = normalizeText(params.planId);
+
+  if (!customerEmail) {
+    return { status: 'skipped', reason: 'missing_customer_email' };
+  }
+  if (!apiKey) {
+    return { status: 'skipped', reason: 'missing_api_key', customerEmail };
+  }
+
+  const previousSent = findTrialEmailRecord({
+    sessionId,
+    customerEmail,
+    statuses: ['sent'],
+  });
+  if (previousSent) {
+    return {
+      status: 'already_sent',
+      customerEmail,
+      sessionId: previousSent.sessionId || sessionId,
+      providerId: previousSent.providerId || null,
+    };
+  }
+
+  if (!CONFIG.RESEND_API_KEY && !options.transport && !mailerTransport) {
+    const previousSkipped = findTrialEmailRecord({
+      sessionId,
+      customerEmail,
+      statuses: ['skipped'],
+    });
+    if (!previousSkipped) {
+      appendTrialEmailRecord({
+        status: 'skipped',
+        reason: 'missing_resend_api_key',
+        sessionId,
+        customerEmail,
+        planId,
+        source: params.source || 'checkout_session_status',
+      });
+    }
+    return { status: 'skipped', reason: 'missing_resend_api_key', customerEmail, sessionId };
+  }
+
+  try {
+    let providerId = null;
+    if (mailerTransport) {
+      const response = await mailerTransport.sendTrialWelcomeEmail({
+        to: customerEmail,
+        licenseKey: apiKey,
+        customerId: params.customerId,
+        customerName: params.customerName,
+        trialEndAt: params.trialEndAt,
+      });
+      if (!response || response.sent !== true) {
+        const rawReason = normalizeText(response && response.reason) || 'provider_error';
+        // Normalize the mailer module's `no_api_key` to billing.js's legacy
+        // `missing_resend_api_key` reason so downstream consumers (dashboards,
+        // tests, support tooling) see a stable vocabulary regardless of which
+        // transport produced the skip.
+        const reason = rawReason === 'no_api_key' ? 'missing_resend_api_key' : rawReason;
+        const isSkipped = reason === 'missing_resend_api_key';
+        const previousSkipped = isSkipped
+          ? findTrialEmailRecord({ sessionId, customerEmail, statuses: ['skipped'] })
+          : null;
+        if (!isSkipped || !previousSkipped) {
+          appendTrialEmailRecord({
+            status: isSkipped ? 'skipped' : 'failed',
+            reason,
+            sessionId,
+            customerEmail,
+            planId,
+            source: params.source || 'checkout_session_status',
+          });
+        }
+        return {
+          status: isSkipped ? 'skipped' : 'failed',
+          reason,
+          customerEmail,
+          sessionId,
+        };
+      }
+      providerId = response.id || response.providerId || null;
+    } else {
+      const message = buildTrialActivationEmail({
+        customerEmail,
+        apiKey,
+        sessionId,
+        planId,
+        appOrigin: params.appOrigin,
+      });
+      const response = await transport(message, params);
+      providerId = response && response.body ? response.body.id : response && response.id ? response.id : null;
+    }
+    appendTrialEmailRecord({
+      status: 'sent',
+      sessionId,
+      customerEmail,
+      planId,
+      providerId,
+      source: params.source || 'checkout_session_status',
+    });
+    return { status: 'sent', customerEmail, sessionId, providerId };
+  } catch (err) {
+    const reason = mailerTransport ? 'exception' : 'provider_error';
+    appendTrialEmailRecord({
+      status: 'failed',
+      reason,
+      error: err && err.message ? err.message : 'Email provider failed',
+      sessionId,
+      customerEmail,
+      planId,
+      source: params.source || 'checkout_session_status',
+    });
+    return {
+      status: 'failed',
+      reason,
+      error: err && err.message ? err.message : 'Email provider failed',
+      customerEmail,
+      sessionId,
+    };
+  }
+}
+
+function trialEmailToWebhookEmailResult(trialEmail = {}) {
+  if (trialEmail.status === 'sent' || trialEmail.status === 'already_sent') {
+    return {
+      sent: true,
+      id: trialEmail.providerId || null,
+      providerId: trialEmail.providerId || null,
+    };
+  }
+  return {
+    sent: false,
+    reason: trialEmail.reason === 'missing_customer_email'
+      ? 'no_recipient'
+      : trialEmail.reason || trialEmail.status || 'unknown',
+    error: trialEmail.error || undefined,
+  };
+}
+
 function normalizeCurrency(value) {
   const text = normalizeText(value);
   return text ? text.toUpperCase() : null;
@@ -1972,7 +2386,7 @@ function saveKeyStore(store) {
 // Core Exports
 // ---------------------------------------------------------------------------
 
-async function createCheckoutSession({ successUrl, cancelUrl, customerEmail, installId, traceId, packId = null, metadata = {} } = {}) {
+async function createCheckoutSession({ successUrl, cancelUrl, customerEmail, installId, traceId, packId = null, metadata = {}, appOrigin } = {}) {
   const resolvedTraceId = traceId || metadata.traceId || createTraceId('checkout');
   const baseCheckoutMetadata = sanitizeMetadata({
     ...metadata,
@@ -1995,9 +2409,12 @@ async function createCheckoutSession({ successUrl, cancelUrl, customerEmail, ins
     const localSessionId = `test_session_${crypto.randomBytes(8).toString('hex')}`;
     const store = loadLocalCheckoutSessions();
     const pack = packId ? CONFIG.CREDIT_PACKS[packId] : null;
+    const localCustomerEmail = normalizeEmail(customerEmail);
     store.sessions[localSessionId] = {
       id: localSessionId,
       customer: `local_cus_${crypto.randomBytes(4).toString('hex')}`,
+      customer_email: localCustomerEmail,
+      customer_details: localCustomerEmail ? { email: localCustomerEmail } : null,
       metadata: { ...checkoutMetadata, packId: pack ? pack.id : null, credits: pack ? pack.credits : null },
       payment_status: 'paid',
       status: 'complete'
@@ -2022,8 +2439,19 @@ async function createCheckoutSession({ successUrl, cancelUrl, customerEmail, ins
     customerEmail,
     checkoutMetadata,
     packId,
+    appOrigin,
   });
-  const session = await stripe.checkout.sessions.create(sessionPayload);
+  let session;
+  try {
+    session = await stripe.checkout.sessions.create(sessionPayload);
+  } catch (err) {
+    if (!sessionPayload.branding_settings || !String(err && err.message).includes('branding_settings')) {
+      throw err;
+    }
+    const fallbackPayload = { ...sessionPayload };
+    delete fallbackPayload.branding_settings;
+    session = await stripe.checkout.sessions.create(fallbackPayload);
+  }
 
   appendFunnelEvent({
     stage: 'acquisition',
@@ -2036,7 +2464,7 @@ async function createCheckoutSession({ successUrl, cancelUrl, customerEmail, ins
   return { sessionId: session.id, url: session.url, localMode: false, traceId: resolvedTraceId, metadata: checkoutMetadata };
 }
 
-function buildCheckoutSessionPayload({ successUrl, cancelUrl, customerEmail, checkoutMetadata, packId = null } = {}) {
+function buildCheckoutSessionPayload({ successUrl, cancelUrl, customerEmail, checkoutMetadata, packId = null, appOrigin } = {}) {
   const pack = packId ? CONFIG.CREDIT_PACKS[packId] : null;
   const checkoutSelection = pack ? null : resolveSubscriptionCheckoutSelection(checkoutMetadata);
   if (!pack && !checkoutSelection.priceId) {
@@ -2046,12 +2474,19 @@ function buildCheckoutSessionPayload({ successUrl, cancelUrl, customerEmail, che
     ? [{
         price_data: {
           currency: pack.currency.toLowerCase(),
-          product_data: { name: pack.name },
+          product_data: buildCheckoutProductData({
+            name: pack.name,
+            description: 'ThumbGate usage credits for hosted agent governance.',
+            appOrigin,
+          }),
           unit_amount: pack.amountCents,
         },
         quantity: 1,
       }]
-    : [{ price: checkoutSelection.priceId, quantity: checkoutSelection.quantity }];
+    : [{
+        price_data: buildSubscriptionPriceData(checkoutSelection, appOrigin),
+        quantity: checkoutSelection.quantity,
+      }];
 
   const sessionPayload = {
     success_url: successUrl,
@@ -2059,6 +2494,7 @@ function buildCheckoutSessionPayload({ successUrl, cancelUrl, customerEmail, che
     payment_method_types: ['card', 'link'],
     mode: pack ? 'payment' : 'subscription',
     line_items: lineItems,
+    branding_settings: buildCheckoutBrandingSettings(appOrigin),
     metadata: serializeStripeMetadata({
       ...checkoutMetadata,
       planId: pack ? checkoutMetadata.planId : checkoutSelection.planId,
@@ -2092,6 +2528,20 @@ async function getCheckoutSessionStatus(sessionId) {
       credits: session.metadata?.credits,
       source: 'local_checkout_lookup'
     });
+    const customerEmail = session.customer_details?.email || session.customer_email || '';
+    const customerName = session.customer_details?.name || null;
+    const trialEndAt = computeTrialEndAt(session);
+    const trialEmail = await sendTrialActivationEmail({
+      sessionId,
+      customerId: session.customer,
+      customerEmail,
+      customerName,
+      trialEndAt,
+      apiKey: provisioned.key,
+      planId: session.metadata?.planId || session.metadata?.packId || null,
+      appOrigin: process.env.THUMBGATE_PUBLIC_APP_ORIGIN,
+      source: 'local_checkout_lookup',
+    });
     return {
       found: true,
       localMode: true,
@@ -2100,6 +2550,7 @@ async function getCheckoutSessionStatus(sessionId) {
       paymentStatus: 'paid',
       status: 'complete',
       customerId: session.customer,
+      customerEmail,
       installId: session.metadata?.installId,
       traceId: session.metadata?.traceId || null,
       acquisitionId: session.metadata?.acquisitionId || null,
@@ -2112,6 +2563,7 @@ async function getCheckoutSessionStatus(sessionId) {
       referrerHost: session.metadata?.referrerHost || null,
       apiKey: provisioned.key,
       remainingCredits: provisioned.remainingCredits,
+      trialEmail,
     };
   }
 
@@ -2126,6 +2578,20 @@ async function getCheckoutSessionStatus(sessionId) {
     const installId = session.metadata?.installId || null;
     const credits = session.metadata?.credits ? parseInt(session.metadata.credits, 10) : null;
     const provisioned = provisionApiKey(session.customer, { installId, credits, source: 'stripe_checkout_session_lookup' });
+    const customerEmail = session.customer_details?.email || session.customer_email || '';
+    const customerName = session.customer_details?.name || null;
+    const trialEndAt = computeTrialEndAt(session);
+    const trialEmail = await sendTrialActivationEmail({
+      sessionId,
+      customerId: session.customer,
+      customerEmail,
+      customerName,
+      trialEndAt,
+      apiKey: provisioned.key,
+      planId: session.metadata?.planId || session.metadata?.packId || null,
+      appOrigin: process.env.THUMBGATE_PUBLIC_APP_ORIGIN,
+      source: 'stripe_checkout_session_lookup',
+    });
 
     return {
       found: true,
@@ -2134,7 +2600,7 @@ async function getCheckoutSessionStatus(sessionId) {
       paid: true,
       paymentStatus: session.payment_status,
       customerId: session.customer,
-      customerEmail: session.customer_details?.email || '',
+      customerEmail,
       installId,
       traceId,
       acquisitionId: session.metadata?.acquisitionId || null,
@@ -2147,6 +2613,7 @@ async function getCheckoutSessionStatus(sessionId) {
       referrerHost: session.metadata?.referrerHost || null,
       apiKey: provisioned.key,
       remainingCredits: provisioned.remainingCredits,
+      trialEmail,
     };
   } catch {
     return { found: false };
@@ -2312,6 +2779,9 @@ async function handleWebhook(rawBody, signature) {
       const traceId = session.metadata?.traceId || null;
       const credits = session.metadata?.credits ? parseInt(session.metadata.credits, 10) : null;
       const packId = session.metadata?.packId || null;
+      const customerEmail = session.customer_details?.email || session.customer_email || '';
+      const customerName = session.customer_details?.name || null;
+      const trialEndAt = computeTrialEndAt(session);
 
       const attribution = extractAttribution(session.metadata);
       const result = provisionApiKey(customerId, {
@@ -2319,6 +2789,17 @@ async function handleWebhook(rawBody, signature) {
         credits,
         source: 'stripe_webhook_checkout_completed'
       });
+      const trialEmail = await sendTrialActivationEmail({
+        sessionId: session.id,
+        customerId,
+        customerEmail,
+        customerName,
+        trialEndAt,
+        apiKey: result.key,
+        planId: session.metadata?.planId || packId || null,
+        appOrigin: process.env.THUMBGATE_PUBLIC_APP_ORIGIN,
+        source: 'stripe_webhook_checkout_completed',
+      });
       const funnelRecord = {
         stage: 'paid',
         event: 'stripe_checkout_completed',
@@ -2384,7 +2865,13 @@ async function handleWebhook(rawBody, signature) {
           attribution,
         });
       }
-      return { handled: true, action: 'provisioned_api_key', result };
+      return {
+        handled: true,
+        action: 'provisioned_api_key',
+        result,
+        trialEmail,
+        email: trialEmailToWebhookEmailResult(trialEmail),
+      };
     }
     case 'customer.subscription.deleted': {
       const sub = event.data.object;
@@ -2527,11 +3014,19 @@ function handleGithubWebhook(event) {
 module.exports = {
   CONFIG, createCheckoutSession, getCheckoutSessionStatus, provisionApiKey, rotateApiKey, validateApiKey, recordUsage, disableCustomerKeys, handleWebhook, verifyWebhookSignature, verifyGithubWebhookSignature, handleGithubWebhook, loadKeyStore, appendFunnelEvent, appendRevenueEvent, loadFunnelLedger, loadRevenueLedger, loadNewsletterSubscribers, loadResolvedRevenueEvents, getFunnelAnalytics, getBusinessAnalytics, getBillingSummary, getBillingSummaryLive, listStripeReconciledRevenueEvents, repairGithubMarketplaceRevenueLedger,
   _buildCheckoutSessionPayload: buildCheckoutSessionPayload,
+  _buildTrialActivationEmail: buildTrialActivationEmail,
+  _sendTrialActivationEmail: sendTrialActivationEmail,
   _resolveSubscriptionCheckoutSelection: resolveSubscriptionCheckoutSelection,
   _API_KEYS_PATH: () => CONFIG.API_KEYS_PATH,
   _FUNNEL_LEDGER_PATH: () => CONFIG.FUNNEL_LEDGER_PATH,
   _REVENUE_LEDGER_PATH: () => CONFIG.REVENUE_LEDGER_PATH,
   _LOCAL_CHECKOUT_SESSIONS_PATH: () => CONFIG.LOCAL_CHECKOUT_SESSIONS_PATH,
+  _TRIAL_EMAIL_LEDGER_PATH: () => CONFIG.TRIAL_EMAIL_LEDGER_PATH,
   _LOCAL_MODE: () => LOCAL_MODE(),
   _withTimeout: withTimeout,
+  // Default to the real Resend-backed mailer so production webhooks send the
+  // marketing-grade trial-welcome template. Tests overwrite this with a stub
+  // (freshBilling() re-requires the module so the default is restored between
+  // tests — see tests/billing-webhook-email.test.js).
+  _mailer: mailer,
 };

package/scripts/contextfs.js

@@ -90,7 +90,7 @@ const PACK_TEMPLATES = {
     namespaces: ['research', 'memoryLearning', 'rules'],
     maxItems: 12,
     maxChars: 10000,
-    queryPrefix: 'research benchmark experiment reliability',
+    queryPrefix: 'research benchmark experiment holdout proof reward hacking reliability',
   },
   'gtm-research': {
     namespaces: ['research', 'memoryLearning'],