@appfunnel-dev/sdk 2.0.0-canary.1 → 2.0.0-canary.3

package/dist/chunk-YY375F2B.js

@@ -0,0 +1,140 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/commerce/capabilities.ts
+var INLINE_SURFACES = /* @__PURE__ */ new Set([
+  "express",
+  "element",
+  "embedded"
+]);
+function isInlineSurface(surface) {
+  return INLINE_SURFACES.has(surface);
+}
+var ON = { purchase: true, wallets: true, offSession: "reliable" };
+var MANAGED = { purchase: true, wallets: true, offSession: "conditional" };
+var ROUTED = { purchase: true, wallets: true, offSession: "conditional" };
+var ALL_UPSELLS = ["subscription", "one-time", "upgrade"];
+var PROVIDER_PROFILES = {
+  // PSP; you hold the PaymentMethod and fire your own off-session PaymentIntent on
+  // the Elements surfaces (reliable). **Managed** Checkout (`embedded`/`redirect`)
+  // upsells too, but as a direct charge against Stripe's vaulted card → conditional.
+  // No provider "popup" surface.
+  stripe: {
+    isMoR: false,
+    offSessionUpsells: ALL_UPSELLS,
+    tokenModel: "merchant",
+    orchestrator: false,
+    status: "full",
+    surfaces: { express: ON, element: ON, sheet: ON, embedded: MANAGED, redirect: MANAGED }
+  },
+  // Merchant-of-Record; card entry is always Paddle's frame → no own element/sheet/
+  // express. Off-session via subscription one-time charge / collection_mode, but
+  // **no 2nd concurrent subscription** (upgrade + one-time only), provider-initiated.
+  paddle: {
+    isMoR: true,
+    offSessionUpsells: ["one-time", "upgrade"],
+    tokenModel: "provider",
+    orchestrator: false,
+    status: "full",
+    surfaces: { embedded: ON, popup: ON, redirect: ON }
+  },
+  // Merchant-of-Record; iframe-only (no raw card field). Off-session works
+  // (provider-initiated, async via webhooks). `sheet` = our chrome hosting their embed.
+  whop: {
+    isMoR: true,
+    offSessionUpsells: ALL_UPSELLS,
+    tokenModel: "provider",
+    orchestrator: false,
+    status: "planned",
+    surfaces: { embedded: ON, redirect: ON, sheet: ON }
+  },
+  // Pure orchestrator (PSP-side); Headless renders express/element/sheet/embedded.
+  // No hosted redirect page, no popup checkout. Off-session is PSP-conditional —
+  // the vault lives with whichever processor Primer routed to (data matches this
+  // comment as of 2026-07-02; it previously said conditional but coded reliable).
+  primer: {
+    isMoR: false,
+    offSessionUpsells: ALL_UPSELLS,
+    tokenModel: "merchant",
+    orchestrator: true,
+    status: "planned",
+    surfaces: { express: ROUTED, element: ROUTED, sheet: ROUTED, embedded: ROUTED }
+  },
+  // PSP **and** orchestrator (own acquiring + connectors routing across Stripe/Adyen/
+  // PayPal). One Payment Form (element/sheet/embedded) + hosted page + wallet button.
+  // Strong native off-session (Recurring API). No popup.
+  solidgate: {
+    isMoR: false,
+    offSessionUpsells: ALL_UPSELLS,
+    tokenModel: "merchant",
+    orchestrator: true,
+    status: "planned",
+    surfaces: { express: ON, element: ON, sheet: ON, embedded: ON, redirect: ON }
+  }
+};
+function surfacesFor(provider) {
+  return Object.keys(PROVIDER_PROFILES[provider]?.surfaces ?? {});
+}
+function isMerchantOfRecord(provider) {
+  return PROVIDER_PROFILES[provider]?.isMoR ?? false;
+}
+function isOrchestrator(provider) {
+  return PROVIDER_PROFILES[provider]?.orchestrator ?? false;
+}
+function validateCheckout(provider, surface) {
+  const cap = PROVIDER_PROFILES[provider]?.surfaces[surface];
+  if (!cap) return { ok: false, reason: `${provider} has no '${surface}' surface` };
+  return cap.purchase ? { ok: true } : { ok: false, reason: `'${surface}' can't take a purchase on ${provider}` };
+}
+function validateUpsell(provider, paywallSurface, kind = "subscription") {
+  const profile = PROVIDER_PROFILES[provider];
+  if (!profile) return { ok: false, reason: `unknown provider '${provider}'` };
+  if (!profile.offSessionUpsells.includes(kind)) {
+    const can = profile.offSessionUpsells.length ? ` (it supports: ${profile.offSessionUpsells.join(", ")})` : "";
+    return { ok: false, reason: `${provider} can't charge a '${kind}' upsell off-session${can}` };
+  }
+  const cap = profile.surfaces[paywallSurface];
+  if (!cap) return { ok: false, reason: `${provider} has no '${paywallSurface}' surface to upsell after` };
+  if (cap.offSession === "none") {
+    return { ok: false, reason: `a purchase on '${paywallSurface}' retains no chargeable method for an upsell` };
+  }
+  if (cap.offSession === "conditional") {
+    return { ok: true, note: `off-session upsell after ${provider} '${paywallSurface}' may decline \u2014 prefer a reliable surface or wire an on-session fallback` };
+  }
+  return { ok: true };
+}
+function checkoutError(category, message, extra = {}) {
+  const retryable = extra.retryable ?? (category === "authentication_required" || category === "requires_payment_method" || category === "processing_error");
+  return { category, message, declineCode: extra.declineCode, retryable };
+}
+
+export { INLINE_SURFACES, PROVIDER_PROFILES, __commonJS, __export, __toESM, checkoutError, isInlineSurface, isMerchantOfRecord, isOrchestrator, surfacesFor, validateCheckout, validateUpsell };
+//# sourceMappingURL=chunk-YY375F2B.js.map
+//# sourceMappingURL=chunk-YY375F2B.js.map

package/dist/chunk-YY375F2B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commerce/capabilities.ts"],"names":[],"mappings":"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","file":"chunk-YY375F2B.js","sourcesContent":["/**\n * The provider capability matrix + checkout error taxonomy — the PURE half of the\n * checkout seam, extracted from checkout.tsx so it ships through the **manifest\n * entry** (no React): the API's publish validation, the editor, AI authoring, and\n * local dev all run the SAME checks the runtime primitives use (phase-3 §3.1b —\n * \"the SDK ships this as data\"). The React half (driver seam, `useCheckout`,\n * `<Checkout>`/`<Upsell>`) stays in ./checkout, which re-exports everything here.\n */\n\nexport type CheckoutSurface =\n  | 'express' // wallet quick-buttons (Apple/Google Pay) — inline\n  | 'element' // inline card form — inline\n  | 'embedded' // provider-managed inline checkout — inline\n  | 'sheet' // bottom-sheet popup — opens on click\n  | 'popup' // provider-hosted overlay — opens on click\n  | 'redirect' // provider-hosted page — opens on click\n\nexport type CheckoutProvider = 'stripe' | 'paddle' | 'whop' | 'primer' | 'solidgate'\nexport type CheckoutIntent = 'purchase' | 'upsell'\n\n/** Surfaces that render inline (vs. those that open on click). */\nexport const INLINE_SURFACES: ReadonlySet<CheckoutSurface> = new Set<CheckoutSurface>([\n  'express',\n  'element',\n  'embedded',\n])\n\nexport function isInlineSurface(surface: CheckoutSurface): boolean {\n  return INLINE_SURFACES.has(surface)\n}\n\n/**\n * The kind of off-session upsell (researched against Funnelfox's changelog, which\n * ships these as distinct features). The discriminating real-world constraint is\n * **stacking a 2nd concurrent subscription** — Paddle can't, SolidGate/Stripe can.\n */\nexport type UpsellKind =\n  | 'subscription' // charge a NEW, 2nd concurrent subscription off-session (stacking)\n  | 'one-time' // charge a one-time add-on off-session\n  | 'upgrade' // change the existing subscription's plan\n\n/** Reliability of an off-session upsell charge AFTER a purchase on a surface. */\nexport type OffSessionReliability =\n  | 'reliable' // we hold the saved method (Stripe Elements / SolidGate) or the provider charges it (Paddle / Whop API)\n  | 'conditional' // possible but may decline — Stripe **managed** checkout (vault charge, SCA not guaranteed) or an orchestrator's PSP-dependent routing (Primer)\n  | 'none'\n\nexport interface SurfaceCapability {\n  purchase: boolean\n  /** Apple/Google Pay available on this surface. */\n  wallets: boolean\n  /** Reliability of an off-session upsell after a purchase on this surface. */\n  offSession: OffSessionReliability\n}\n\nexport interface ProviderProfile {\n  /** Merchant-of-Record (handles tax/compliance) vs. a PSP you settle through. */\n  isMoR: boolean\n  /** Upsell kinds this provider can charge off-session (one-click, no re-entry). */\n  offSessionUpsells: UpsellKind[]\n  /** Who charges the saved method off-session: you (PSP) or the provider (MoR/managed). */\n  tokenModel: 'merchant' | 'provider'\n  /** Routes across multiple processors (Primer; SolidGate also offers this) vs. a single acquirer. */\n  orchestrator: boolean\n  /**\n   * Driver tier (Wave-4 decision, Simon 2026-07-02): `full` = a real driver ships\n   * (Stripe, Paddle); `planned` = profile only — authoring/publish validate against\n   * it, but no charge path exists yet (Whop, Primer, SolidGate). A new provider\n   * becomes buildable by writing a driver; its profile already gates what authors\n   * can express, so funnels written today stay valid when the driver lands.\n   */\n  status: 'full' | 'planned'\n  /** Supported surfaces → per-surface capabilities. **Absent = not supported.** */\n  surfaces: Partial<Record<CheckoutSurface, SurfaceCapability>>\n}\n\n/** Reliable off-session after this surface (we/the provider hold a chargeable method). */\nconst ON: SurfaceCapability = { purchase: true, wallets: true, offSession: 'reliable' }\n/** Stripe-managed checkout: a purchase works, but the off-session upsell may decline. */\nconst MANAGED: SurfaceCapability = { purchase: true, wallets: true, offSession: 'conditional' }\n/** Orchestrator-routed (Primer): off-session depends on which PSP vaulted the method. */\nconst ROUTED: SurfaceCapability = { purchase: true, wallets: true, offSession: 'conditional' }\nconst ALL_UPSELLS: UpsellKind[] = ['subscription', 'one-time', 'upgrade']\n\n/**\n * Provider capabilities (researched 2026-06-23 against provider docs + Funnelfox;\n * trial mechanics re-verified 2026-07-02, doc 09 §4.4).\n *\n * Three real-world corrections to the naive model:\n *  1. **Off-session upsell support is per-provider by *kind*** (`offSessionUpsells`):\n *     Paddle can't stack a 2nd concurrent subscription (upgrade + one-time only);\n *     Stripe/SolidGate/Whop/Primer can do all kinds.\n *  2. **Off-session *reliability* varies by the paywall surface** (`SurfaceCapability.\n *     offSession`): Stripe **managed** checkout (`embedded`/`redirect`) upsells as a\n *     direct charge against Stripe's vault → `conditional` (may decline); Elements\n *     surfaces are `reliable`. Primer is `conditional` everywhere (PSP-dependent).\n *  3. **Surface availability is a hard constraint.** MoR/managed providers can't\n *     expose a raw card field to your own UI: Paddle has no `express`/`element`/your\n *     `sheet`; Whop has no raw `element`/`express`; Primer has no hosted `redirect`;\n *     Stripe/SolidGate have no `popup`. A missing entry means \"not possible.\"\n */\nexport const PROVIDER_PROFILES: Record<CheckoutProvider, ProviderProfile> = {\n  // PSP; you hold the PaymentMethod and fire your own off-session PaymentIntent on\n  // the Elements surfaces (reliable). **Managed** Checkout (`embedded`/`redirect`)\n  // upsells too, but as a direct charge against Stripe's vaulted card → conditional.\n  // No provider \"popup\" surface.\n  stripe: {\n    isMoR: false, offSessionUpsells: ALL_UPSELLS, tokenModel: 'merchant', orchestrator: false, status: 'full',\n    surfaces: { express: ON, element: ON, sheet: ON, embedded: MANAGED, redirect: MANAGED },\n  },\n  // Merchant-of-Record; card entry is always Paddle's frame → no own element/sheet/\n  // express. Off-session via subscription one-time charge / collection_mode, but\n  // **no 2nd concurrent subscription** (upgrade + one-time only), provider-initiated.\n  paddle: {\n    isMoR: true, offSessionUpsells: ['one-time', 'upgrade'], tokenModel: 'provider', orchestrator: false, status: 'full',\n    surfaces: { embedded: ON, popup: ON, redirect: ON },\n  },\n  // Merchant-of-Record; iframe-only (no raw card field). Off-session works\n  // (provider-initiated, async via webhooks). `sheet` = our chrome hosting their embed.\n  whop: {\n    isMoR: true, offSessionUpsells: ALL_UPSELLS, tokenModel: 'provider', orchestrator: false, status: 'planned',\n    surfaces: { embedded: ON, redirect: ON, sheet: ON },\n  },\n  // Pure orchestrator (PSP-side); Headless renders express/element/sheet/embedded.\n  // No hosted redirect page, no popup checkout. Off-session is PSP-conditional —\n  // the vault lives with whichever processor Primer routed to (data matches this\n  // comment as of 2026-07-02; it previously said conditional but coded reliable).\n  primer: {\n    isMoR: false, offSessionUpsells: ALL_UPSELLS, tokenModel: 'merchant', orchestrator: true, status: 'planned',\n    surfaces: { express: ROUTED, element: ROUTED, sheet: ROUTED, embedded: ROUTED },\n  },\n  // PSP **and** orchestrator (own acquiring + connectors routing across Stripe/Adyen/\n  // PayPal). One Payment Form (element/sheet/embedded) + hosted page + wallet button.\n  // Strong native off-session (Recurring API). No popup.\n  solidgate: {\n    isMoR: false, offSessionUpsells: ALL_UPSELLS, tokenModel: 'merchant', orchestrator: true, status: 'planned',\n    surfaces: { express: ON, element: ON, sheet: ON, embedded: ON, redirect: ON },\n  },\n}\n\nexport interface ValidationResult {\n  ok: boolean\n  reason?: string\n  /** Non-fatal caveat (e.g. Paddle upgrade-only). */\n  note?: string\n}\n\n/** Surfaces a provider supports, for the editor/AI to steer authors. */\nexport function surfacesFor(provider: CheckoutProvider): CheckoutSurface[] {\n  return Object.keys(PROVIDER_PROFILES[provider]?.surfaces ?? {}) as CheckoutSurface[]\n}\n\n/** Whether a provider is a Merchant of Record (it owns tax/compliance). */\nexport function isMerchantOfRecord(provider: CheckoutProvider): boolean {\n  return PROVIDER_PROFILES[provider]?.isMoR ?? false\n}\n\n/** Whether a provider routes across multiple processors (Primer, SolidGate). */\nexport function isOrchestrator(provider: CheckoutProvider): boolean {\n  return PROVIDER_PROFILES[provider]?.orchestrator ?? false\n}\n\n/**\n * Validate a (provider, surface) for a **purchase**: the surface must exist for\n * the provider and accept a payment. Surface availability is the real constraint\n * (e.g. Paddle has no `element`).\n */\nexport function validateCheckout(provider: CheckoutProvider, surface: CheckoutSurface): ValidationResult {\n  const cap = PROVIDER_PROFILES[provider]?.surfaces[surface]\n  if (!cap) return { ok: false, reason: `${provider} has no '${surface}' surface` }\n  return cap.purchase ? { ok: true } : { ok: false, reason: `'${surface}' can't take a purchase on ${provider}` }\n}\n\n/**\n * Validate an **off-session upsell** of `kind` after a purchase made on\n * `paywallSurface`. Combines provider support for the kind (Paddle can't stack a\n * 2nd subscription) with the paywall surface's off-session reliability (Stripe\n * managed checkout is `conditional` — returned as a `note`, not a hard block).\n */\nexport function validateUpsell(\n  provider: CheckoutProvider,\n  paywallSurface: CheckoutSurface,\n  kind: UpsellKind = 'subscription',\n): ValidationResult {\n  const profile = PROVIDER_PROFILES[provider]\n  if (!profile) return { ok: false, reason: `unknown provider '${provider}'` }\n  if (!profile.offSessionUpsells.includes(kind)) {\n    const can = profile.offSessionUpsells.length ? ` (it supports: ${profile.offSessionUpsells.join(', ')})` : ''\n    return { ok: false, reason: `${provider} can't charge a '${kind}' upsell off-session${can}` }\n  }\n  const cap = profile.surfaces[paywallSurface]\n  if (!cap) return { ok: false, reason: `${provider} has no '${paywallSurface}' surface to upsell after` }\n  if (cap.offSession === 'none') {\n    return { ok: false, reason: `a purchase on '${paywallSurface}' retains no chargeable method for an upsell` }\n  }\n  if (cap.offSession === 'conditional') {\n    return { ok: true, note: `off-session upsell after ${provider} '${paywallSurface}' may decline — prefer a reliable surface or wire an on-session fallback` }\n  }\n  return { ok: true }\n}\n\n// ── Checkout error taxonomy (pure — drivers + server both normalize into it) ──\n\n/**\n * Normalized failure category — the driver/platform maps each provider's decline\n * codes into one of these so funnels can route/recover by reason. `authentication_\n * required` (3DS/SCA) and `requires_payment_method` are the cases an **off-session**\n * upsell can't satisfy → recover on-session (re-collect a card).\n */\nexport type CheckoutErrorCategory =\n  | 'card_declined'\n  | 'insufficient_funds'\n  | 'expired_card'\n  | 'prepaid_card' // card funding is prepaid — trials/subscriptions commonly decline; route to a real-card recapture page\n  | 'authentication_required' // SCA/3DS needed — off-session can't challenge\n  | 'requires_payment_method' // no usable saved method\n  | 'processing_error'\n  | 'canceled'\n  | 'unknown'\n\nexport interface CheckoutError {\n  category: CheckoutErrorCategory\n  message: string\n  /** Raw provider decline code, if any (e.g. Stripe `card_declined`/`insufficient_funds`). */\n  declineCode?: string\n  /** Whether re-attempting (e.g. an on-session re-collection) may succeed. */\n  retryable: boolean\n}\n\n/** Build a {@link CheckoutError} (driver/test helper). */\nexport function checkoutError(\n  category: CheckoutErrorCategory,\n  message: string,\n  extra: { declineCode?: string; retryable?: boolean } = {},\n): CheckoutError {\n  const retryable = extra.retryable ?? (category === 'authentication_required' || category === 'requires_payment_method' || category === 'processing_error')\n  return { category, message, declineCode: extra.declineCode, retryable }\n}\n"]}