@funnelsgrove/payments 0.7.3 → 0.7.4

package/README.md

@@ -34,6 +34,12 @@ Use these for new one-time paywall plans:
 
 Use `completeStripeOneClickPayment` for normal post-checkout one-click upsells. It delegates the charge to `funnelSdkService.chargeOneClickPayment` and owns any required Stripe confirmation. `chargeStripeOneClickPayment` remains the lower-level charge-only primitive.
 
+Solidgate browser checkout is available for controlled provider-routed funnels through
+`SolidgateCheckoutDialog`, `prepareSolidgateCheckout`, and `pollSolidgateCheckoutStatus`. The dialog
+mounts one official Solidgate form per attempt, destroys the remote form on replacement/unmount,
+and never treats iframe `success` as funnel completion. Its `onSuccess` callback runs only after the
+provider-neutral status endpoint finds canonical shared-ledger payment evidence.
+
 ## Advanced Wallet Primitives
 
 `ApplePaySubscriptionCheckoutSlot`, `GooglePaySubscriptionCheckoutSlot`, and `WalletSubscriptionCheckoutSlot` stay exported and runtime-compatible. They are backward-compatible advanced low-level primitives: reach for them only when a placement needs wiring `StripeSubscriptionWalletSurface` does not cover. Never share one `useStripeSubscriptionCheckoutSession` result across placements; give each visible placement its own session.
@@ -84,6 +90,8 @@ When a live funnel still uses one of these, migrate the funnel deliberately with
 - `providers/stripe/hooks/*`: Stripe-backed plan resolution and isolated card/wallet checkout-session state.
 - `providers/stripe/components/*`: plan selector, checkout dialogs, Express Checkout wrappers, wallet slots, placeholders, and trust assets.
 - `providers/stripe/testing/*`: Stripe wallet checkout smoke assertions.
+- `providers/solidgate/services/*`: strict Solidgate checkout preparation, status, and bounded polling clients.
+- `providers/solidgate/components/*`: the official-SDK checkout dialog and canonical verification lifecycle.
 - `components/ManageSubscriptionScreen`: provider-neutral subscription management UI.
 
 Funnels should call `resolvePublishedBillingRuntime` once at their runtime-provider boundary. Screens consume its resolved view and should not parse offer sets or pricing-experiment variants themselves.

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export * from './services/paywallOffer.service.js';
 export * from './services/paymentMethodAnalytics.service.js';
 export * from './providers/paymentProvider.types.js';
 export * from './providers/stripe/index.js';
+export * from './providers/solidgate/index.js';
 export { ManageSubscriptionScreen, type ManageSubscriptionContent, type ManageSubscriptionScreenProps, } from './components/ManageSubscriptionScreen.js';

package/dist/index.js

@@ -10,5 +10,6 @@ export * from './services/paymentMethodAnalytics.service.js';
 export * from './providers/paymentProvider.types.js';
 // Provider-specific integrations are grouped behind provider barrels.
 export * from './providers/stripe/index.js';
+export * from './providers/solidgate/index.js';
 // Provider-neutral subscription management UI.
 export { ManageSubscriptionScreen, } from './components/ManageSubscriptionScreen.js';

package/dist/providers/solidgate/components/SolidgateCheckoutDialog.d.ts

@@ -0,0 +1,25 @@
+import { type PrepareSolidgateCheckoutInput, type SolidgateCheckoutPreparation } from '../services/solidgate.service.js';
+export type SolidgateCheckoutDialogState = 'loading' | 'ready' | 'submitting' | 'verifying' | 'success' | 'recoverable_error' | 'expired';
+export type SolidgateCheckoutDialogContent = {
+    title: string;
+    closeAriaLabel: string;
+    loading: string;
+    submitting: string;
+    verifying: string;
+    success: string;
+    error: string;
+    expired: string;
+    retry: string;
+    resumeVerification: string;
+};
+export type SolidgateCheckoutDialogProps = {
+    open: boolean;
+    request: Omit<PrepareSolidgateCheckoutInput, 'signal'>;
+    content?: Partial<SolidgateCheckoutDialogContent>;
+    onClose: () => void;
+    onSuccess?: (checkout: SolidgateCheckoutPreparation) => void | Promise<void>;
+    onRetry?: () => void;
+    onError?: (message: string) => void;
+    onStateChange?: (state: SolidgateCheckoutDialogState) => void;
+};
+export declare function SolidgateCheckoutDialog({ open, request, content, onClose, onSuccess, onRetry, onError, onStateChange, }: SolidgateCheckoutDialogProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/providers/solidgate/components/SolidgateCheckoutDialog.js

@@ -0,0 +1,250 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { pollSolidgateCheckoutStatus, prepareSolidgateCheckout, } from '../services/solidgate.service.js';
+const SolidgatePayment = lazy(async () => ({
+    default: (await import('@solidgate/react-sdk')).default,
+}));
+const defaultContent = {
+    title: 'Secure checkout',
+    closeAriaLabel: 'Close checkout',
+    loading: 'Preparing your secure checkout…',
+    submitting: 'Submitting payment…',
+    verifying: 'Verifying payment securely…',
+    success: 'Payment confirmed.',
+    error: 'Payment could not be completed. Please try again.',
+    expired: 'This checkout has expired. Start a new payment to continue.',
+    retry: 'Try again',
+    resumeVerification: 'Check payment status',
+};
+const initialView = {
+    state: 'loading',
+    checkout: null,
+    canResumeVerification: false,
+};
+const isAbortError = (error) => (error instanceof DOMException && error.name === 'AbortError');
+const safeDestroyPaymentForm = (instance) => {
+    var _a;
+    try {
+        instance === null || instance === void 0 ? void 0 : instance.unsubscribeAll();
+    }
+    catch (_b) {
+        // The global destroy below is the final cleanup boundary.
+    }
+    try {
+        (_a = window.PaymentFormSdk) === null || _a === void 0 ? void 0 : _a.destroy();
+    }
+    catch (_c) {
+        // Cleanup must stay safe when the remote SDK is partially initialized.
+    }
+};
+function SolidgatePaymentForm({ checkout, hidden, loadingLabel, onError, onMounted, onSubmit, onVerify, }) {
+    const instanceRef = useRef(null);
+    useEffect(() => () => {
+        safeDestroyPaymentForm(instanceRef.current);
+        instanceRef.current = null;
+    }, [checkout.attemptId]);
+    return (_jsx("div", { className: hidden ? 'hidden' : 'block', "data-solidgate-attempt-id": checkout.attemptId, "aria-hidden": hidden || undefined, children: _jsx(Suspense, { fallback: (_jsx("p", { role: 'status', className: 'text-sm text-muted-foreground', children: loadingLabel })), children: _jsx(SolidgatePayment, { merchantData: checkout.initialization.merchantData, width: '100%', formParams: { isSolidLogoVisible: true }, onReadyPaymentInstance: (instance) => {
+                    if (instanceRef.current && instanceRef.current !== instance) {
+                        try {
+                            instanceRef.current.unsubscribeAll();
+                        }
+                        catch (_a) {
+                            // The active instance remains usable even if stale-listener cleanup fails.
+                        }
+                    }
+                    instanceRef.current = instance;
+                }, onMounted: onMounted, onSubmit: onSubmit, onVerify: onVerify, onSuccess: onVerify, onFail: onVerify, onError: onError }, checkout.attemptId) }) }));
+}
+export function SolidgateCheckoutDialog({ open, request, content, onClose, onSuccess, onRetry, onError, onStateChange, }) {
+    const copy = useMemo(() => (Object.assign(Object.assign({}, defaultContent), content)), [content]);
+    const [view, setView] = useState(initialView);
+    const prepareAbortRef = useRef(null);
+    const statusAbortRef = useRef(null);
+    const successAttemptRef = useRef(null);
+    const closeButtonRef = useRef(null);
+    const copyRef = useRef(copy);
+    const onErrorRef = useRef(onError);
+    const onStateChangeRef = useRef(onStateChange);
+    const onSuccessRef = useRef(onSuccess);
+    useEffect(() => {
+        copyRef.current = copy;
+        onErrorRef.current = onError;
+        onStateChangeRef.current = onStateChange;
+        onSuccessRef.current = onSuccess;
+    }, [copy, onError, onStateChange, onSuccess]);
+    const { discountKeyOrProviderId, failUrl, funnelEndUserId, funnelId, idempotencyKey, offerSetId, projectBillingPlanId, returnUrl, runtimeConfig, successUrl, } = request;
+    const { apiBaseUrl, funnelId: runtimeFunnelId, funnelSdkPublishableKey, funnelVersionId, } = runtimeConfig || {};
+    const hasRuntimeConfig = runtimeConfig !== undefined;
+    const normalizedRequest = useMemo(() => ({
+        funnelId: (funnelId === null || funnelId === void 0 ? void 0 : funnelId.trim()) || null,
+        funnelEndUserId: funnelEndUserId.trim(),
+        offerSetId: offerSetId.trim(),
+        projectBillingPlanId: projectBillingPlanId.trim(),
+        idempotencyKey: idempotencyKey.trim(),
+        discountKeyOrProviderId: (discountKeyOrProviderId === null || discountKeyOrProviderId === void 0 ? void 0 : discountKeyOrProviderId.trim()) || null,
+        returnUrl: returnUrl.trim(),
+        successUrl: successUrl.trim(),
+        failUrl: failUrl.trim(),
+        runtimeConfig: hasRuntimeConfig ? {
+            apiBaseUrl: (apiBaseUrl === null || apiBaseUrl === void 0 ? void 0 : apiBaseUrl.trim()) || null,
+            funnelId: (runtimeFunnelId === null || runtimeFunnelId === void 0 ? void 0 : runtimeFunnelId.trim()) || null,
+            funnelVersionId: (funnelVersionId === null || funnelVersionId === void 0 ? void 0 : funnelVersionId.trim()) || null,
+            funnelSdkPublishableKey: (funnelSdkPublishableKey === null || funnelSdkPublishableKey === void 0 ? void 0 : funnelSdkPublishableKey.trim()) || null,
+        } : undefined,
+    }), [
+        apiBaseUrl,
+        discountKeyOrProviderId,
+        failUrl,
+        funnelEndUserId,
+        funnelId,
+        funnelSdkPublishableKey,
+        funnelVersionId,
+        idempotencyKey,
+        offerSetId,
+        projectBillingPlanId,
+        returnUrl,
+        hasRuntimeConfig,
+        runtimeFunnelId,
+        successUrl,
+    ]);
+    const setState = useCallback((nextView) => {
+        var _a;
+        setView(nextView);
+        (_a = onStateChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStateChangeRef, nextView.state);
+    }, []);
+    useEffect(() => {
+        var _a, _b, _c, _d;
+        if (!open) {
+            (_a = prepareAbortRef.current) === null || _a === void 0 ? void 0 : _a.abort();
+            (_b = statusAbortRef.current) === null || _b === void 0 ? void 0 : _b.abort();
+            return;
+        }
+        const controller = new AbortController();
+        (_c = prepareAbortRef.current) === null || _c === void 0 ? void 0 : _c.abort();
+        (_d = statusAbortRef.current) === null || _d === void 0 ? void 0 : _d.abort();
+        prepareAbortRef.current = controller;
+        successAttemptRef.current = null;
+        queueMicrotask(() => {
+            if (!controller.signal.aborted) {
+                setState(initialView);
+            }
+        });
+        void prepareSolidgateCheckout(Object.assign(Object.assign({}, normalizedRequest), { signal: controller.signal }))
+            .then((checkout) => {
+            if (!controller.signal.aborted) {
+                setState({ state: 'ready', checkout, canResumeVerification: false });
+            }
+        })
+            .catch((error) => {
+            var _a;
+            if (!controller.signal.aborted && !isAbortError(error)) {
+                setState({ state: 'recoverable_error', checkout: null, canResumeVerification: false });
+                (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, copyRef.current.error);
+            }
+        });
+        return () => controller.abort();
+    }, [normalizedRequest, open, setState]);
+    useEffect(() => {
+        var _a;
+        if (!open) {
+            return;
+        }
+        const previouslyFocused = document.activeElement instanceof HTMLElement
+            ? document.activeElement
+            : null;
+        const handleKeyDown = (event) => {
+            if (event.key === 'Escape') {
+                onClose();
+            }
+        };
+        window.addEventListener('keydown', handleKeyDown);
+        (_a = closeButtonRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+        return () => {
+            window.removeEventListener('keydown', handleKeyDown);
+            previouslyFocused === null || previouslyFocused === void 0 ? void 0 : previouslyFocused.focus();
+        };
+    }, [onClose, open]);
+    useEffect(() => () => {
+        var _a, _b;
+        (_a = prepareAbortRef.current) === null || _a === void 0 ? void 0 : _a.abort();
+        (_b = statusAbortRef.current) === null || _b === void 0 ? void 0 : _b.abort();
+    }, []);
+    const verifyCanonicalStatus = useCallback(async () => {
+        var _a, _b, _c, _d;
+        const checkout = view.checkout;
+        if (!checkout || view.state === 'success') {
+            return;
+        }
+        (_a = statusAbortRef.current) === null || _a === void 0 ? void 0 : _a.abort();
+        const controller = new AbortController();
+        statusAbortRef.current = controller;
+        setState({ state: 'verifying', checkout, canResumeVerification: false });
+        try {
+            const result = await pollSolidgateCheckoutStatus({
+                attemptId: checkout.attemptId,
+                funnelId: normalizedRequest.funnelId,
+                funnelEndUserId: normalizedRequest.funnelEndUserId,
+                runtimeConfig: normalizedRequest.runtimeConfig,
+                signal: controller.signal,
+            });
+            if (controller.signal.aborted) {
+                return;
+            }
+            if (result.status === 'succeeded') {
+                setState({ state: 'success', checkout, canResumeVerification: false });
+                if (successAttemptRef.current !== checkout.attemptId) {
+                    successAttemptRef.current = checkout.attemptId;
+                    await ((_b = onSuccessRef.current) === null || _b === void 0 ? void 0 : _b.call(onSuccessRef, checkout));
+                }
+            }
+            else if (result.status === 'expired') {
+                setState({ state: 'expired', checkout, canResumeVerification: false });
+            }
+            else if (result.status === 'failed') {
+                setState({ state: 'recoverable_error', checkout, canResumeVerification: false });
+                (_c = onErrorRef.current) === null || _c === void 0 ? void 0 : _c.call(onErrorRef, copyRef.current.error);
+            }
+            else if (result.status === 'requires_payment') {
+                setState({ state: 'ready', checkout, canResumeVerification: false });
+            }
+            else {
+                setState({ state: 'verifying', checkout, canResumeVerification: result.timedOut });
+            }
+        }
+        catch (error) {
+            if (!controller.signal.aborted && !isAbortError(error)) {
+                setState({ state: 'recoverable_error', checkout, canResumeVerification: true });
+                (_d = onErrorRef.current) === null || _d === void 0 ? void 0 : _d.call(onErrorRef, copyRef.current.error);
+            }
+        }
+    }, [normalizedRequest, setState, view]);
+    if (!open) {
+        return null;
+    }
+    const showForm = view.state === 'ready'
+        || view.state === 'submitting'
+        || view.state === 'verifying';
+    const statusMessage = view.state === 'loading'
+        ? copy.loading
+        : view.state === 'submitting'
+            ? copy.submitting
+            : view.state === 'verifying'
+                ? copy.verifying
+                : view.state === 'success'
+                    ? copy.success
+                    : view.state === 'expired'
+                        ? copy.expired
+                        : view.state === 'recoverable_error'
+                            ? copy.error
+                            : null;
+    return (_jsx("div", { className: 'fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4', children: _jsxs("div", { role: 'dialog', "aria-modal": 'true', "aria-labelledby": 'solidgate-checkout-title', "data-checkout-state": view.state, className: 'w-full max-w-lg rounded-2xl border border-border bg-card p-5 text-foreground shadow-xl', children: [_jsxs("div", { className: 'mb-4 flex items-center justify-between gap-4', children: [_jsx("h2", { id: 'solidgate-checkout-title', className: 'text-lg font-semibold text-foreground', children: copy.title }), _jsx("button", { ref: closeButtonRef, type: 'button', onClick: onClose, "aria-label": copy.closeAriaLabel, className: 'rounded-md border border-border bg-background px-3 py-1.5 text-foreground hover:bg-accent', children: "\u00D7" })] }), view.checkout ? (_jsx(SolidgatePaymentForm, { checkout: view.checkout, hidden: !showForm, loadingLabel: copy.loading, onMounted: () => {
+                        if (view.state === 'loading') {
+                            setState(Object.assign(Object.assign({}, view), { state: 'ready' }));
+                        }
+                    }, onSubmit: () => setState(Object.assign(Object.assign({}, view), { state: 'submitting' })), onVerify: () => void verifyCanonicalStatus(), onError: () => {
+                        var _a;
+                        setState(Object.assign(Object.assign({}, view), { state: 'recoverable_error', canResumeVerification: false }));
+                        (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, copyRef.current.error);
+                    } }, view.checkout.attemptId)) : null, statusMessage && view.state !== 'ready' ? (_jsx("div", { className: 'rounded-xl border border-border bg-background p-4 text-sm text-muted-foreground', children: _jsx("p", { role: 'status', "aria-live": 'polite', children: statusMessage }) })) : null, view.state === 'verifying' && view.canResumeVerification ? (_jsx("button", { type: 'button', onClick: () => void verifyCanonicalStatus(), className: 'mt-4 w-full rounded-lg border border-border bg-accent px-4 py-2 font-medium text-foreground', children: copy.resumeVerification })) : null, (view.state === 'recoverable_error' || view.state === 'expired') && onRetry ? (_jsx("button", { type: 'button', onClick: onRetry, className: 'mt-4 w-full rounded-lg border border-border bg-accent px-4 py-2 font-medium text-foreground', children: copy.retry })) : null] }) }));
+}

package/dist/providers/solidgate/components/index.d.ts

@@ -0,0 +1 @@
+export * from './SolidgateCheckoutDialog.js';

package/dist/providers/solidgate/components/index.js

@@ -0,0 +1 @@
+export * from './SolidgateCheckoutDialog.js';

package/dist/providers/solidgate/index.d.ts

@@ -0,0 +1,2 @@
+export * from './components/index.js';
+export * from './services/index.js';

package/dist/providers/solidgate/index.js

@@ -0,0 +1,2 @@
+export * from './components/index.js';
+export * from './services/index.js';

package/dist/providers/solidgate/services/index.d.ts

@@ -0,0 +1 @@
+export * from './solidgate.service.js';

package/dist/providers/solidgate/services/index.js

@@ -0,0 +1 @@
+export * from './solidgate.service.js';

package/dist/providers/solidgate/services/solidgate.service.d.ts

@@ -0,0 +1,59 @@
+import { type FunnelSdkRuntimeConfigOverrides } from '@funnelsgrove/runtime';
+export type SolidgateCheckoutStatus = 'preparing' | 'requires_payment' | 'verifying' | 'succeeded' | 'failed' | 'expired';
+export type SolidgateCheckoutPreparation = {
+    attemptId: string;
+    display: {
+        title: string;
+        amountMinor: number;
+        currency: string;
+        billingInterval: string | null;
+        billingIntervalCount: number | null;
+    };
+    statusVerification: {
+        attemptId: string;
+    };
+    initialization: {
+        kind: 'solidgate';
+        merchantData: {
+            merchant: string;
+            signature: string;
+            paymentIntent: string;
+        };
+    };
+};
+export type PrepareSolidgateCheckoutInput = {
+    funnelId?: string | null;
+    funnelEndUserId: string;
+    offerSetId: string;
+    projectBillingPlanId: string;
+    idempotencyKey: string;
+    discountKeyOrProviderId?: string | null;
+    returnUrl: string;
+    successUrl: string;
+    failUrl: string;
+    runtimeConfig?: FunnelSdkRuntimeConfigOverrides;
+    signal?: AbortSignal;
+};
+export type RetrieveSolidgateCheckoutStatusInput = {
+    funnelId?: string | null;
+    funnelEndUserId: string;
+    attemptId: string;
+    runtimeConfig?: FunnelSdkRuntimeConfigOverrides;
+    signal?: AbortSignal;
+};
+export type SolidgateCheckoutStatusResponse = {
+    attemptId: string;
+    status: SolidgateCheckoutStatus;
+    retryAfterMs: number | null;
+};
+export type PollSolidgateCheckoutStatusResult = SolidgateCheckoutStatusResponse & {
+    timedOut: boolean;
+};
+export declare const prepareSolidgateCheckout: (input: PrepareSolidgateCheckoutInput) => Promise<SolidgateCheckoutPreparation>;
+export declare const retrieveSolidgateCheckoutStatus: (input: RetrieveSolidgateCheckoutStatusInput) => Promise<SolidgateCheckoutStatusResponse>;
+export declare const pollSolidgateCheckoutStatus: (input: RetrieveSolidgateCheckoutStatusInput, options?: {
+    maxDurationMs?: number;
+    now?: () => number;
+    delay?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    retrieveStatus?: typeof retrieveSolidgateCheckoutStatus;
+}) => Promise<PollSolidgateCheckoutStatusResult>;

package/dist/providers/solidgate/services/solidgate.service.js

@@ -0,0 +1,196 @@
+import { FUNNEL_ID, FUNNEL_SDK_PUBLISHABLE_KEY, buildMainApiUrl, resolvePreviewPaymentPublishableKey, } from '@funnelsgrove/runtime';
+const trimTrailingSlash = (value) => value.replace(/\/+$/, '');
+const requiredString = (value, name) => {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (!normalized) {
+        throw new Error(`Solidgate checkout response is missing ${name}`);
+    }
+    return normalized;
+};
+const resolveFunnelId = (inputFunnelId, runtimeConfig) => requiredString(inputFunnelId || (runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.funnelId) || FUNNEL_ID, 'funnelId');
+const resolveApiUrl = (path, runtimeConfig) => {
+    var _a;
+    const configuredBaseUrl = (_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.apiBaseUrl) === null || _a === void 0 ? void 0 : _a.trim();
+    return configuredBaseUrl
+        ? `${trimTrailingSlash(configuredBaseUrl)}${path}`
+        : buildMainApiUrl(path);
+};
+const resolvePublishableKey = (runtimeConfig) => {
+    var _a;
+    return resolvePreviewPaymentPublishableKey((_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.funnelSdkPublishableKey) !== null && _a !== void 0 ? _a : FUNNEL_SDK_PUBLISHABLE_KEY) || null;
+};
+const postJson = async (path, body, runtimeConfig, signal) => {
+    const publishableKey = resolvePublishableKey(runtimeConfig);
+    const response = await fetch(resolveApiUrl(path, runtimeConfig), {
+        method: 'POST',
+        headers: Object.assign({ 'content-type': 'application/json' }, (publishableKey ? { 'x-sdk-publishable-key': publishableKey } : {})),
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error('Solidgate checkout is temporarily unavailable');
+    }
+    return response.json();
+};
+const isRecord = (value) => (Boolean(value) && typeof value === 'object' && !Array.isArray(value));
+const parsePreparation = (value) => {
+    if (!isRecord(value) || !isRecord(value.display) || !isRecord(value.initialization)) {
+        throw new Error('Solidgate checkout returned an invalid response');
+    }
+    if (value.initialization.kind !== 'solidgate' || !isRecord(value.initialization.merchantData)) {
+        throw new Error('Solidgate checkout returned an invalid provider');
+    }
+    const amountMinor = value.display.amountMinor;
+    if (typeof amountMinor !== 'number' || !Number.isSafeInteger(amountMinor) || amountMinor < 0) {
+        throw new Error('Solidgate checkout returned an invalid amount');
+    }
+    const billingInterval = value.display.billingInterval;
+    const billingIntervalCount = value.display.billingIntervalCount;
+    if (billingInterval !== null && typeof billingInterval !== 'string') {
+        throw new Error('Solidgate checkout returned an invalid billing interval');
+    }
+    if (billingIntervalCount !== null
+        && (typeof billingIntervalCount !== 'number' || !Number.isSafeInteger(billingIntervalCount))) {
+        throw new Error('Solidgate checkout returned an invalid billing interval count');
+    }
+    const attemptId = requiredString(value.attemptId, 'attemptId');
+    return {
+        attemptId,
+        display: {
+            title: requiredString(value.display.title, 'display.title'),
+            amountMinor,
+            currency: requiredString(value.display.currency, 'display.currency'),
+            billingInterval,
+            billingIntervalCount,
+        },
+        statusVerification: { attemptId },
+        initialization: {
+            kind: 'solidgate',
+            merchantData: {
+                merchant: requiredString(value.initialization.merchantData.merchant, 'merchant'),
+                signature: requiredString(value.initialization.merchantData.signature, 'signature'),
+                paymentIntent: requiredString(value.initialization.merchantData.paymentIntent, 'paymentIntent'),
+            },
+        },
+    };
+};
+const statuses = new Set([
+    'preparing',
+    'requires_payment',
+    'verifying',
+    'succeeded',
+    'failed',
+    'expired',
+]);
+const parseStatus = (value) => {
+    if (!isRecord(value) || typeof value.status !== 'string' || !statuses.has(value.status)) {
+        throw new Error('Solidgate checkout status returned an invalid response');
+    }
+    const retryAfterMs = value.retryAfterMs;
+    if (retryAfterMs !== null
+        && (typeof retryAfterMs !== 'number' || !Number.isFinite(retryAfterMs) || retryAfterMs < 0)) {
+        throw new Error('Solidgate checkout status returned an invalid retry delay');
+    }
+    return {
+        attemptId: requiredString(value.attemptId, 'attemptId'),
+        status: value.status,
+        retryAfterMs,
+    };
+};
+export const prepareSolidgateCheckout = async (input) => {
+    var _a;
+    return parsePreparation(await postJson('/sdk/public/payments/solidgate/checkout', {
+        funnelId: resolveFunnelId(input.funnelId, input.runtimeConfig),
+        funnelEndUserId: requiredString(input.funnelEndUserId, 'funnelEndUserId'),
+        offerSetId: requiredString(input.offerSetId, 'offerSetId'),
+        projectBillingPlanId: requiredString(input.projectBillingPlanId, 'projectBillingPlanId'),
+        idempotencyKey: requiredString(input.idempotencyKey, 'idempotencyKey'),
+        discountKeyOrProviderId: ((_a = input.discountKeyOrProviderId) === null || _a === void 0 ? void 0 : _a.trim()) || null,
+        returnUrl: requiredString(input.returnUrl, 'returnUrl'),
+        successUrl: requiredString(input.successUrl, 'successUrl'),
+        failUrl: requiredString(input.failUrl, 'failUrl'),
+    }, input.runtimeConfig, input.signal));
+};
+export const retrieveSolidgateCheckoutStatus = async (input) => {
+    const attemptId = requiredString(input.attemptId, 'attemptId');
+    const result = parseStatus(await postJson('/sdk/public/payments/solidgate/checkout/status', {
+        funnelId: resolveFunnelId(input.funnelId, input.runtimeConfig),
+        funnelEndUserId: requiredString(input.funnelEndUserId, 'funnelEndUserId'),
+        attemptId,
+    }, input.runtimeConfig, input.signal));
+    if (result.attemptId !== attemptId) {
+        throw new Error('Solidgate checkout status returned the wrong attempt');
+    }
+    return result;
+};
+const terminalStatuses = new Set(['succeeded', 'failed', 'expired']);
+const abortableDelay = (delayMs, signal) => new Promise((resolve, reject) => {
+    const cleanup = () => signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
+    const timeout = setTimeout(() => {
+        cleanup();
+        resolve();
+    }, delayMs);
+    const onAbort = () => {
+        clearTimeout(timeout);
+        cleanup();
+        reject((signal === null || signal === void 0 ? void 0 : signal.reason) || new DOMException('Aborted', 'AbortError'));
+    };
+    if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+        onAbort();
+        return;
+    }
+    signal === null || signal === void 0 ? void 0 : signal.addEventListener('abort', onAbort, { once: true });
+});
+export const pollSolidgateCheckoutStatus = async (input, options = {}) => {
+    var _a, _b, _c, _d, _e;
+    const maxDurationMs = Math.min(60000, Math.max(0, (_a = options.maxDurationMs) !== null && _a !== void 0 ? _a : 60000));
+    const now = options.now || Date.now;
+    const delay = options.delay || abortableDelay;
+    const retrieveStatus = options.retrieveStatus || retrieveSolidgateCheckoutStatus;
+    const startedAt = now();
+    let fallbackDelayMs = 1000;
+    const deadlineController = new AbortController();
+    const forwardAbort = () => {
+        var _a;
+        return deadlineController.abort(((_a = input.signal) === null || _a === void 0 ? void 0 : _a.reason) || new DOMException('Aborted', 'AbortError'));
+    };
+    if ((_b = input.signal) === null || _b === void 0 ? void 0 : _b.aborted) {
+        forwardAbort();
+    }
+    else {
+        (_c = input.signal) === null || _c === void 0 ? void 0 : _c.addEventListener('abort', forwardAbort, { once: true });
+    }
+    const deadline = setTimeout(() => deadlineController.abort(new DOMException('Checkout status polling timed out', 'TimeoutError')), maxDurationMs);
+    try {
+        while (true) {
+            const observation = await retrieveStatus(Object.assign(Object.assign({}, input), { signal: deadlineController.signal }));
+            if (terminalStatuses.has(observation.status) || observation.status === 'requires_payment') {
+                return Object.assign(Object.assign({}, observation), { timedOut: false });
+            }
+            const elapsedMs = now() - startedAt;
+            if (elapsedMs >= maxDurationMs) {
+                return Object.assign(Object.assign({}, observation), { timedOut: true });
+            }
+            const requestedDelayMs = (_d = observation.retryAfterMs) !== null && _d !== void 0 ? _d : fallbackDelayMs;
+            const delayMs = Math.min(Math.max(250, requestedDelayMs), 5000, Math.max(0, maxDurationMs - elapsedMs));
+            await delay(delayMs, deadlineController.signal);
+            fallbackDelayMs = Math.min(fallbackDelayMs * 2, 5000);
+        }
+    }
+    catch (error) {
+        if (deadlineController.signal.reason instanceof DOMException
+            && deadlineController.signal.reason.name === 'TimeoutError') {
+            return {
+                attemptId: input.attemptId,
+                status: 'verifying',
+                retryAfterMs: 3000,
+                timedOut: true,
+            };
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(deadline);
+        (_e = input.signal) === null || _e === void 0 ? void 0 : _e.removeEventListener('abort', forwardAbort);
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/payments",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/The-Solid-Grove/funnelsgrove.git",
@@ -34,6 +34,7 @@
   "dependencies": {
     "@funnelsgrove/analytics": "^0.1.52",
     "@funnelsgrove/runtime": "^0.7.3",
+    "@solidgate/react-sdk": "1.34.0",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",
     "react": "19.2.3",
@@ -44,6 +45,7 @@
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "jsdom": "20.0.3",
     "typescript": "^5",
     "vitest": "^3.2.4"
   }