git-paid 0.0.0-stage → 2.1.1

package/lib/stripe.js

@@ -0,0 +1,554 @@
+// Stripe Payments, Billing & Invoicing Engine for postbuild (www.postbuild.dev)
+// Follows Stripe Best Practices (API version 2026-10-28.endive, StripeClient instance,
+// dynamic payment methods, integration_identifier, invoice_creation, Customer Portal, and Webhooks).
+
+import Stripe from "stripe";
+import { signLicenseToken } from "./auth.js";
+
+export const STRIPE_API_VERSION = "2026-10-28.endive";
+export const INTEGRATION_IDENTIFIER = "postbuild_checkout_x7k9m2pq";
+
+// Separate Product definitions per plan (never mix tiers on a single Product)
+export const PLANS = {
+  launch_pass: {
+    id: "launch_pass",
+    productName: "postbuild Launch Pass (git paid)",
+    description: "25 Programmatic SEO pages + Dedicated @postbuild.dev verification inbox + 85-Directory Dispatch",
+    amountCents: 2900,
+    mode: "payment",
+    priceEnvVar: "STRIPE_PRICE_LAUNCH_PASS"
+  },
+  studio_monthly: {
+    id: "studio_monthly",
+    productName: "postbuild Studio All-Access",
+    description: "Unlimited projects, weekly programmatic SEO route drops, IndexNow pinging, and Buyer Intent Radar",
+    amountCents: 4900,
+    mode: "subscription",
+    priceEnvVar: "STRIPE_PRICE_STUDIO_MONTHLY"
+  }
+};
+
+export function getStripeClient() {
+  const candidates = [
+    process.env.STRIPE_RESTRICTED_KEY,
+    process.env.STRIPE_SECRET_KEY,
+    process.env.STRIPE_LIVE_KEY,
+    process.env.STRIPE_API_KEY
+  ]
+    .map((k) => (k || "").trim())
+    .filter(Boolean);
+
+  if (candidates.length === 0) return null;
+
+  // Always prefer a live key (rk_live_ or sk_live_) if one is configured alongside a test key
+  const liveKey = candidates.find((k) => k.startsWith("rk_live_") || k.startsWith("sk_live_"));
+  const apiKey = liveKey || candidates[0];
+  return new Stripe(apiKey, { apiVersion: STRIPE_API_VERSION });
+}
+
+export async function createStripeCheckout({
+  planId = "launch_pass",
+  targetDomain = "postbuild.dev",
+  customerEmail = "",
+  coupon = "",
+  origin = "https://postbuild.dev"
+}) {
+  const plan = PLANS[planId] || PLANS.launch_pass;
+
+  // 1. Optional Payment Link override if configured
+  if (plan.id === "launch_pass" && process.env.STRIPE_LAUNCH_PASS_URL) {
+    const link = new URL(process.env.STRIPE_LAUNCH_PASS_URL);
+    link.searchParams.set("client_reference_id", targetDomain);
+    if (customerEmail) link.searchParams.set("prefilled_email", customerEmail);
+    return { ok: true, configured: true, mode: "payment_link", checkoutUrl: link.toString() };
+  }
+  if (plan.id === "studio_monthly" && process.env.STRIPE_STUDIO_URL) {
+    const link = new URL(process.env.STRIPE_STUDIO_URL);
+    link.searchParams.set("client_reference_id", targetDomain);
+    if (customerEmail) link.searchParams.set("prefilled_email", customerEmail);
+    return { ok: true, configured: true, mode: "payment_link", checkoutUrl: link.toString() };
+  }
+
+  // 2. Instantiate Stripe client
+  const stripe = getStripeClient();
+  if (!stripe) {
+    return {
+      ok: false,
+      configured: false,
+      plan,
+      message: "Stripe API key not configured yet. Add STRIPE_RESTRICTED_KEY (rk_...) or STRIPE_SECRET_KEY in Vercel / .env.",
+      setupSteps: [
+        "Recommended: Create a Restricted API Key (rk_live_... or rk_test_...) with Checkout Sessions (Write), Customers (Read/Write), Billing Portal (Write), and Invoices (Read/Write) permissions.",
+        "Set STRIPE_RESTRICTED_KEY and STRIPE_WEBHOOK_SECRET in Vercel -> Settings -> Environment Variables (as Sensitive variables) or local .env."
+      ]
+    };
+  }
+
+  const isFounder100 = String(coupon || "").toUpperCase() === "FOUNDER100";
+  let activeCouponId = null;
+  if (isFounder100) {
+    try {
+      try {
+        const existingCoupon = await stripe.coupons.retrieve("FOUNDER100_COUPON");
+        activeCouponId = existingCoupon.id;
+      } catch {
+        const createdCoupon = await stripe.coupons.create({
+          id: "FOUNDER100_COUPON",
+          percent_off: 100,
+          duration: "forever",
+          name: "postbuild Founder 100% Pass"
+        });
+        activeCouponId = createdCoupon.id;
+      }
+    } catch {
+      activeCouponId = null;
+    }
+  }
+
+  // Build line_item using catalog Price ID if configured, or distinct product_data per tier
+  const configuredPriceId = (process.env[plan.priceEnvVar] || "").trim();
+  const productTaxCode = (process.env.STRIPE_PRODUCT_TAX_CODE || "txcd_10103001").trim();
+  const effectiveUnitAmount = isFounder100 && !activeCouponId ? 0 : plan.amountCents;
+
+  const lineItem =
+    configuredPriceId && !isFounder100
+      ? { price: configuredPriceId, quantity: 1 }
+      : {
+          quantity: 1,
+          price_data: {
+            currency: "usd",
+            unit_amount: effectiveUnitAmount,
+            tax_behavior: "exclusive",
+            ...(plan.mode === "subscription" ? { recurring: { interval: "month" } } : {}),
+            product_data: {
+              name: isFounder100 ? `${plan.productName} (Founder 100% Pass)` : plan.productName,
+              description: plan.description,
+              tax_code: productTaxCode
+            }
+          }
+        };
+
+  // Omit payment_method_types entirely so Stripe Dynamic Payment Methods are active
+  const sessionParams = {
+    mode: plan.mode,
+    line_items: [lineItem],
+    ...(activeCouponId ? { discounts: [{ coupon: activeCouponId }] } : { allow_promotion_codes: true }),
+    ...(plan.mode === "payment" ? { customer_creation: "always" } : {}),
+    success_url: `${origin}/?checkout=success&session_id={CHECKOUT_SESSION_ID}&plan=${encodeURIComponent(plan.id)}&domain=${encodeURIComponent(targetDomain)}`,
+    cancel_url: `${origin}/?checkout=cancelled&domain=${encodeURIComponent(targetDomain)}`,
+    client_reference_id: targetDomain,
+    integration_identifier: INTEGRATION_IDENTIFIER,
+    metadata: {
+      target_domain: targetDomain,
+      plan_id: plan.id,
+      promo_code: isFounder100 ? "FOUNDER100" : ""
+    }
+  };
+
+  if (customerEmail && customerEmail.includes("@")) {
+    sessionParams.customer_email = customerEmail;
+  }
+
+  const session = await stripe.checkout.sessions.create(sessionParams);
+
+  return {
+    ok: true,
+    configured: true,
+    livemode: Boolean(session.livemode),
+    mode: "checkout_session",
+    couponApplied: isFounder100 ? (activeCouponId || "FOUNDER100_ZERO_AMOUNT") : null,
+    amountTotalCents: session.amount_total ?? effectiveUnitAmount,
+    sessionId: session.id,
+    checkoutUrl: session.url
+  };
+}
+
+export async function createCustomerPortalSession({ customerId, customerEmail, returnUrl = "https://postbuild.dev" }) {
+  const stripe = getStripeClient();
+  if (!stripe) {
+    return { ok: false, configured: false, error: "Stripe API key not configured." };
+  }
+
+  let resolvedCustomerId = customerId;
+  const cleanEmail = (customerEmail || "").toLowerCase().trim();
+  if (!resolvedCustomerId && cleanEmail) {
+    const list = await stripe.customers.list({ email: cleanEmail, limit: 1 });
+    if (list.data.length > 0) {
+      resolvedCustomerId = list.data[0].id;
+    } else {
+      // If the user previously checked out as a guest before customer_creation: 'always', create their Customer record now
+      const created = await stripe.customers.create({
+        email: cleanEmail,
+        metadata: { source: "postbuild_portal_auto_link" }
+      });
+      resolvedCustomerId = created.id;
+    }
+  }
+
+  if (!resolvedCustomerId) {
+    return { ok: false, error: "Please sign in with your checkout email first to open the Billing Portal." };
+  }
+
+  const portalSession = await stripe.billingPortal.sessions.create({
+    customer: resolvedCustomerId,
+    return_url: returnUrl
+  });
+
+  return {
+    ok: true,
+    portalUrl: portalSession.url
+  };
+}
+
+export async function getCustomerBillingSummary({ customerEmail, customerId }) {
+  const stripe = getStripeClient();
+  if (!stripe) {
+    return { ok: false, configured: false, receipts: [], subscriptions: [] };
+  }
+
+  const cleanEmail = (customerEmail || "").toLowerCase().trim();
+  const receipts = [];
+  const subscriptions = [];
+  let resolvedCustomerId = customerId || null;
+
+  try {
+    if (!resolvedCustomerId && cleanEmail) {
+      const custList = await stripe.customers.list({ email: cleanEmail, limit: 3 });
+      if (custList.data.length > 0) {
+        resolvedCustomerId = custList.data[0].id;
+      }
+    }
+
+    // 1. Fetch official Stripe Invoices if customer exists
+    if (resolvedCustomerId) {
+      const invList = await stripe.invoices.list({ customer: resolvedCustomerId, limit: 10 });
+      for (const inv of invList.data) {
+        receipts.push({
+          id: inv.id,
+          number: inv.number || inv.id.slice(0, 12),
+          description: inv.lines?.data?.[0]?.description || "postbuild Subscription / Launch Pass",
+          amountFormatted: `$${((inv.amount_paid || inv.total || 0) / 100).toFixed(2)} ${(inv.currency || "usd").toUpperCase()}`,
+          status: inv.status || "paid",
+          createdAt: new Date(inv.created * 1000).toISOString().split("T")[0],
+          receiptUrl: inv.hosted_invoice_url || inv.invoice_pdf || null,
+          pdfUrl: inv.invoice_pdf || null
+        });
+      }
+
+      const subList = await stripe.subscriptions.list({ customer: resolvedCustomerId, status: "all", limit: 5 });
+      for (const sub of subList.data) {
+        subscriptions.push({
+          id: sub.id,
+          status: sub.status,
+          cancelAtPeriodEnd: Boolean(sub.cancel_at_period_end),
+          currentPeriodEnd: sub.current_period_end
+            ? new Date(sub.current_period_end * 1000).toISOString().split("T")[0]
+            : null
+        });
+      }
+    }
+
+    // 2. Also inspect recent completed Checkout Sessions matching this email (catches one-time guest checkouts & PaymentIntent receipts)
+    const sessions = await stripe.checkout.sessions.list({ limit: 25, expand: ["data.payment_intent.latest_charge"] });
+    for (const s of sessions.data) {
+      const sEmail = (s.customer_details?.email || s.customer_email || "").toLowerCase().trim();
+      if (cleanEmail && sEmail !== cleanEmail) continue;
+      if (s.payment_status === "unpaid") continue;
+
+      const charge = s.payment_intent && typeof s.payment_intent === "object" ? s.payment_intent.latest_charge : null;
+      const receiptUrl = charge && typeof charge === "object" ? charge.receipt_url : null;
+      const planId = s.metadata?.plan_id || (s.mode === "subscription" ? "studio_monthly" : "launch_pass");
+      const domain = s.client_reference_id || s.metadata?.target_domain || "postbuild.dev";
+
+      // Avoid duplicating if already added via invoice
+      if (!receipts.some((r) => r.id === s.id)) {
+        receipts.push({
+          id: s.id,
+          number: (charge && typeof charge === "object" && charge.receipt_number) || s.id.slice(-10).toUpperCase(),
+          description:
+            planId === "studio_monthly"
+              ? `postbuild Studio All-Access (${domain})`
+              : `postbuild Single Project Launch Pass (${domain})`,
+          amountFormatted: `$${((s.amount_total || 2900) / 100).toFixed(2)} ${(s.currency || "usd").toUpperCase()}`,
+          status: s.payment_status || "paid",
+          createdAt: new Date(s.created * 1000).toISOString().split("T")[0],
+          receiptUrl: receiptUrl || null,
+          pdfUrl: null
+        });
+      }
+    }
+  } catch (err) {
+    return { ok: false, error: err.message, receipts, subscriptions };
+  }
+
+  return {
+    ok: true,
+    configured: true,
+    customerId: resolvedCustomerId,
+    email: cleanEmail,
+    receipts,
+    subscriptions
+  };
+}
+
+export async function cancelCustomerSubscription({ subscriptionId, customerEmail }) {
+  const stripe = getStripeClient();
+  if (!stripe) {
+    return { ok: false, error: "Stripe API key not configured." };
+  }
+
+  let targetSubId = subscriptionId;
+  const cleanEmail = (customerEmail || "").toLowerCase().trim();
+
+  if (!targetSubId && cleanEmail) {
+    const custList = await stripe.customers.list({ email: cleanEmail, limit: 1 });
+    if (custList.data.length > 0) {
+      const subList = await stripe.subscriptions.list({
+        customer: custList.data[0].id,
+        status: "active",
+        limit: 1
+      });
+      if (subList.data.length > 0) {
+        targetSubId = subList.data[0].id;
+      }
+    }
+  }
+
+  if (!targetSubId) {
+    return { ok: false, error: "No active recurring subscription found for this account." };
+  }
+
+  const updated = await stripe.subscriptions.update(targetSubId, {
+    cancel_at_period_end: true
+  });
+
+  return {
+    ok: true,
+    subscriptionId: updated.id,
+    status: updated.status,
+    cancelAtPeriodEnd: Boolean(updated.cancel_at_period_end),
+    currentPeriodEnd: updated.current_period_end
+      ? new Date(updated.current_period_end * 1000).toISOString().split("T")[0]
+      : null
+  };
+}
+
+export async function fulfillCheckoutSession(session) {
+  // Gate fulfillment strictly on payment_status !== 'unpaid' (handles delayed-notification payment methods safely)
+  if (!session || session.payment_status === "unpaid") {
+    return { fulfilled: false, reason: "Payment status is still unpaid" };
+  }
+
+  const customerEmail = session.customer_details?.email || session.customer_email || "";
+  const targetDomain = session.client_reference_id || session.metadata?.target_domain || "*";
+  const planId = session.metadata?.plan_id || (session.mode === "subscription" ? "studio_monthly" : "launch_pass");
+
+  const licenseToken = signLicenseToken({
+    email: customerEmail,
+    plan: planId,
+    domain: targetDomain
+  });
+
+  return {
+    fulfilled: true,
+    sessionId: session.id,
+    customerId: typeof session.customer === "string" ? session.customer : session.customer?.id || null,
+    customerEmail,
+    planId,
+    targetDomain,
+    licenseToken
+  };
+}
+
+export async function verifyAndHandleStripeWebhook(rawBodyBuffer, signatureHeader) {
+  const stripe = getStripeClient();
+  const webhookSecret = (process.env.STRIPE_WEBHOOK_SECRET || "").trim();
+
+  if (!stripe || !webhookSecret) {
+    return { ok: false, status: 400, error: "Stripe client or STRIPE_WEBHOOK_SECRET is not configured." };
+  }
+
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(rawBodyBuffer, signatureHeader, webhookSecret);
+  } catch (err) {
+    return { ok: false, status: 400, error: `Webhook signature verification failed: ${err.message}` };
+  }
+
+  switch (event.type) {
+    // 1. Checkout & Async Payment Fulfillment
+    case "checkout.session.completed":
+    case "checkout.session.async_payment_succeeded": {
+      const session = event.data.object;
+      const result = await fulfillCheckoutSession(session);
+      return { ok: true, status: 200, eventType: event.type, fulfillment: result };
+    }
+
+    case "checkout.session.async_payment_failed": {
+      const session = event.data.object;
+      return {
+        ok: true,
+        status: 200,
+        eventType: event.type,
+        action: "payment_failed_notification",
+        sessionId: session.id
+      };
+    }
+
+    // 2. Subscription & Invoicing Lifecycle
+    case "customer.subscription.created":
+    case "customer.subscription.updated":
+    case "customer.subscription.deleted": {
+      const subscription = event.data.object;
+      const customerId = typeof subscription.customer === "string" ? subscription.customer : subscription.customer?.id;
+      return {
+        ok: true,
+        status: 200,
+        eventType: event.type,
+        subscriptionId: subscription.id,
+        customerId,
+        subscriptionStatus: subscription.status
+      };
+    }
+
+    case "invoice.paid":
+    case "invoice.payment_failed": {
+      const invoice = event.data.object;
+      const customerId = typeof invoice.customer === "string" ? invoice.customer : invoice.customer?.id;
+      return {
+        ok: true,
+        status: 200,
+        eventType: event.type,
+        invoiceId: invoice.id,
+        customerId,
+        paid: event.type === "invoice.paid"
+      };
+    }
+
+    // 3. Risk-side Events (Disputes, Refunds, Early Fraud Warnings) resolved via Stripe Object Graph
+    case "charge.dispute.created":
+    case "charge.refunded":
+    case "radar.early_fraud_warning.created": {
+      const obj = event.data.object;
+      const chargeId = event.type === "charge.refunded" ? obj.id : obj.charge;
+      let resolvedCustomerId = null;
+      let resolvedPaymentIntentId = null;
+
+      if (chargeId && typeof chargeId === "string") {
+        const charge = await stripe.charges.retrieve(chargeId, { expand: ["payment_intent"] });
+        resolvedCustomerId = typeof charge.customer === "string" ? charge.customer : charge.customer?.id || null;
+        resolvedPaymentIntentId =
+          typeof charge.payment_intent === "string" ? charge.payment_intent : charge.payment_intent?.id || null;
+      }
+
+      return {
+        ok: true,
+        status: 200,
+        eventType: event.type,
+        riskAction: "revoke_or_flag_entitlement",
+        chargeId,
+        customerId: resolvedCustomerId,
+        paymentIntentId: resolvedPaymentIntentId
+      };
+    }
+
+    default:
+      return { ok: true, status: 200, eventType: event.type, ignored: true };
+  }
+}
+
+export async function configureStripeBrandingAndPortal(iconPngBuffer) {
+  const stripe = getStripeClient();
+  if (!stripe) {
+    return { configured: false, reason: "missing_stripe_key" };
+  }
+
+  const results = {
+    iconFileId: null,
+    accountBrandingUpdated: false,
+    portalConfigured: false,
+    portalConfigurationId: null,
+    notes: []
+  };
+
+  if (iconPngBuffer && iconPngBuffer.length > 0) {
+    try {
+      const uploadedIcon = await stripe.files.create({
+        purpose: "business_icon",
+        file: {
+          data: iconPngBuffer,
+          name: "postbuild-icon.png",
+          type: "application/octet-stream"
+        }
+      });
+      results.iconFileId = uploadedIcon.id;
+    } catch (err) {
+      results.notes.push(`icon_upload: ${err.message}`);
+    }
+  }
+
+  try {
+    const account = await stripe.accounts.retrieve();
+    if (account && account.id) {
+      const brandingPayload = {
+        primary_color: "#0f172a",
+        secondary_color: "#10b981"
+      };
+      if (results.iconFileId) {
+        brandingPayload.icon = results.iconFileId;
+        brandingPayload.logo = results.iconFileId;
+      }
+      await stripe.accounts.update(account.id, {
+        settings: {
+          branding: brandingPayload
+        },
+        business_profile: {
+          name: "postbuild",
+          url: "https://postbuild.dev",
+          product_description:
+            "postbuild (postbuild.dev) is a developer SaaS platform and CLI tool (git paid / npx postbuild) that automates post-build technical SEO audits, structured metadata generation, programmatic SEO route packs, and curated SaaS directory launch kits."
+        }
+      });
+      results.accountBrandingUpdated = true;
+    }
+  } catch (err) {
+    results.notes.push(`account_update: ${err.message}`);
+  }
+
+  try {
+    const existingList = await stripe.billingPortal.configurations.list({ limit: 5 });
+    const portalPayload = {
+      business_profile: {
+        headline: "postbuild — Billing, Subscriptions & Tax Receipts",
+        privacy_policy_url: "https://postbuild.dev/privacy",
+        terms_of_service_url: "https://postbuild.dev/terms"
+      },
+      features: {
+        invoice_history: { enabled: true },
+        payment_method_update: { enabled: true },
+        subscription_cancel: {
+          enabled: true,
+          mode: "at_period_end"
+        }
+      }
+    };
+
+    if (existingList.data && existingList.data.length > 0) {
+      const updated = await stripe.billingPortal.configurations.update(existingList.data[0].id, portalPayload);
+      results.portalConfigured = true;
+      results.portalConfigurationId = updated.id;
+    } else {
+      const created = await stripe.billingPortal.configurations.create(portalPayload);
+      results.portalConfigured = true;
+      results.portalConfigurationId = created.id;
+    }
+  } catch (err) {
+    results.notes.push(`portal_config: ${err.message}`);
+  }
+
+  return {
+    configured: true,
+    ...results
+  };
+}
+