@funnelsgrove/sdk

Embed a published FunnelsGrove paywall directly in a web app. No app backend, secret key, or paywall session is required. The package has no framework dependency.

npm install @funnelsgrove/sdk

The implementation is a release candidate. npm currently contains the metadata-only 0.0.0-bootstrap.0 reservation, without executable SDK code.

Mount in your frontend

import { mountPaywall } from '@funnelsgrove/sdk';

const paywall = mountPaywall({
  container: '#paywall',
  paywallUrl: 'https://pay.example.com/paywall',
  ...(currentUser.funnelsGroveUserId
    ? { userId: currentUser.funnelsGroveUserId }
    : { email: currentUser.email }),
  returnUrl: '/billing/complete',
  onReady: ({ userId }) => console.log('Paywall ready for FG user', userId),
  onComplete: () => console.log('Payment confirmed'),
  onError: (error) => showPaymentError(error.message),
});

// On route change, modal close, or component cleanup:
paywall.destroy();

paywallUrl is the published paywall route, without query parameters or a fragment. Use HTTPS in production; localhost HTTP is supported for development. The published funnel supplies its public FG key and funnel configuration.

Provide FG userId or email. userId is the existing FG public user_id, scoped to this funnel and Test/Live environment. It is not your application's account ID or FG's internal row ID. Unknown IDs fail without creating a user or falling back to email. With email only, FG normalizes and reuses or creates the canonical user. Concurrent requests for the same email converge on one user. If both fields are provided, they must match or resolution fails. Resolution does not change an existing user's email or purchase history. onReady({ userId }) exposes the selected FG ID; the mount keeps it for subsequent provider returns. If an email form in the paywall resolves another owner, it shows a conflict inside the iframe and keeps the current buyer; reopen from the app to select a different account.

This follows FG's public checkout identity model. Browser-supplied ID/email is not proof of ownership of an authenticated app account. This SDK does not change the access model of existing public user APIs.

Completion and return URL

returnUrl is optional. Relative URLs resolve against the app page. After FG verifies the successful checkout, the SDK calls onComplete once per mount and navigates the parent window to returnUrl. Without it, the caller handles navigation. Pending or failed payments do not redirect. The destination is kept in the parent; child messages cannot replace it. A configured redirect still runs if onComplete throws; use the callback for synchronous notification and handle callback errors in your app.

Use verified billing webhooks/subscription state to grant and revoke access, including renewals and cancellations. Browser callbacks and redirects only tell the app to refresh that state.

onError receives a PaywallError with code:

• paywall_unavailable: reopen the paywall or correct its configuration/identity.
• confirmation_pending: keep the iframe and use Check payment status.
• payment_failed: keep the iframe to let the buyer try again.

The SDK checks message origin, sender window and iframe instance, and adjusts iframe height. Settings are exchanged using postMessage; user identity and the app return URL are absent from iframe/provider URLs. Provider success/failure returns reload the FG paywall and recover settings from the original mounted parent. Keep that parent mounted during redirects. A replaced parent or a provider return into a top-level window requires reopening from the app. Solidgate return recovery also uses sessionStorage for its checkout ID; blocked storage can prevent redirect recovery. Inline checkout does not need that storage.

Payment setup and rollout

The funnel uses its existing Stripe/Solidgate checkout, including eligible wallets. The iframe has allow="payment *". Register/verify both app and funnel domains for Apple Pay, and configure Google Pay with the provider. Hosting frame-ancestors and app frame-src policies must permit the intended origins. Real wallets and 3DS require provider/browser acceptance; local fixtures do not establish that support.

Publish SDK, runtime, analytics and payments in dependency order, deploy the matching API, then rebuild the target funnel. Older funnels do not understand this embed protocol. The API image builds local SDK/runtime tarballs before their npm release, but promotion's CLI gate needs published package artifacts.

This is an ESM package. TypeScript supports moduleResolution: "NodeNext" or "Bundler". There is no server import; @funnelsgrove/sdk/embed is the internal FG runtime bridge. The canonical behavior and test mapping are in docs/product-specs/sdk.md.