@funnelsgrove/payments 0.1.37 → 0.1.38

package/README.md

@@ -2,6 +2,11 @@
 
 Shared billing and checkout helpers for funnels.
 
+Detailed implementation docs:
+
+- [Shared Payments](../../docs/funnel-sdk/shared-payments.md)
+- [Funnel API payment endpoints](../../docs/funnel-sdk/funnel-api.md#checkout-endpoints)
+
 ## Build And Publish
 
 - Build distributable output with `npm run build --workspace @funnelsgrove/payments`.

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './services/planCatalog.service.js';
 export * from './services/runtimeBillingPlanCatalog.service.js';
 export * from './services/paywallOffer.service.js';
 export * from './services/stripe.service.js';
+export * from './services/checkoutCompletionAnalytics.service.js';
 export * from './hooks/useResolvedPaywallPlans.js';
 export * from './providers/paymentProvider.types.js';
 export * from './providers/stripe/useStripeSubscriptionCheckoutSession.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './services/planCatalog.service.js';
 export * from './services/runtimeBillingPlanCatalog.service.js';
 export * from './services/paywallOffer.service.js';
 export * from './services/stripe.service.js';
+export * from './services/checkoutCompletionAnalytics.service.js';
 export * from './hooks/useResolvedPaywallPlans.js';
 export * from './providers/paymentProvider.types.js';
 export * from './providers/stripe/useStripeSubscriptionCheckoutSession.js';

package/dist/services/checkoutCompletionAnalytics.service.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeMode } from '@funnelsgrove/runtime';
+import { type StripeRuntimeConfigOverrides } from './stripe.service.js';
+export type TrackPaidStripeSubscriptionCheckoutCompletedInput = {
+    checkoutSessionId?: string | null;
+    environment?: RuntimeMode;
+    metadata?: Record<string, unknown> | null;
+    runtimeConfig?: StripeRuntimeConfigOverrides;
+    stepId?: string;
+    stepName?: string;
+};
+export type TrackPaidStripeSubscriptionCheckoutCompletedResult = 'already_tracked' | 'missing_checkout_session' | 'tracked' | 'unpaid';
+export declare function trackPaidStripeSubscriptionCheckoutCompleted(input: TrackPaidStripeSubscriptionCheckoutCompletedInput): Promise<TrackPaidStripeSubscriptionCheckoutCompletedResult>;

package/dist/services/checkoutCompletionAnalytics.service.js

@@ -0,0 +1,74 @@
+import { publicAnalyticsSdk, } from '@funnelsgrove/analytics';
+import { verifyStripeSubscriptionCheckoutPayment, } from './stripe.service.js';
+const asRecord = (value) => {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+};
+const activeCheckoutCompletionKeys = new Set();
+const buildCheckoutCompletedStorageKey = (checkoutSessionId, runtimeConfig) => {
+    var _a;
+    const funnelId = ((_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.funnelId) === null || _a === void 0 ? void 0 : _a.trim()) || 'unknown_funnel';
+    return `funnelsgrove:checkout_completed:${funnelId}:${checkoutSessionId}`;
+};
+const hasTrackedCheckoutSession = (checkoutSessionId, runtimeConfig) => {
+    var _a;
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        return Boolean((_a = window.sessionStorage) === null || _a === void 0 ? void 0 : _a.getItem(buildCheckoutCompletedStorageKey(checkoutSessionId, runtimeConfig)));
+    }
+    catch (_b) {
+        return false;
+    }
+};
+const markCheckoutSessionTracked = (checkoutSessionId, runtimeConfig) => {
+    var _a;
+    if (typeof window === 'undefined') {
+        return;
+    }
+    try {
+        (_a = window.sessionStorage) === null || _a === void 0 ? void 0 : _a.setItem(buildCheckoutCompletedStorageKey(checkoutSessionId, runtimeConfig), '1');
+    }
+    catch (_b) {
+        // A stable checkout-session event id still protects provider-side dedupe.
+    }
+};
+export async function trackPaidStripeSubscriptionCheckoutCompleted(input) {
+    var _a;
+    const checkoutSessionId = ((_a = input.checkoutSessionId) === null || _a === void 0 ? void 0 : _a.trim()) || '';
+    if (!checkoutSessionId) {
+        return 'missing_checkout_session';
+    }
+    const completionKey = buildCheckoutCompletedStorageKey(checkoutSessionId, input.runtimeConfig);
+    if (activeCheckoutCompletionKeys.has(completionKey) ||
+        hasTrackedCheckoutSession(checkoutSessionId, input.runtimeConfig)) {
+        return 'already_tracked';
+    }
+    activeCheckoutCompletionKeys.add(completionKey);
+    try {
+        const checkoutStatus = await verifyStripeSubscriptionCheckoutPayment({
+            checkoutSessionId,
+            environment: input.environment,
+            runtimeConfig: input.runtimeConfig,
+        });
+        if (!checkoutStatus.paid) {
+            return 'unpaid';
+        }
+        const analyticsMetadata = asRecord(checkoutStatus.analyticsMetadata);
+        const conversionInput = {
+            eventId: checkoutSessionId,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: Object.assign(Object.assign(Object.assign({}, asRecord(input.metadata)), analyticsMetadata), { checkoutSessionId, checkout_session_id: checkoutSessionId, checkout_session_status: checkoutStatus.status || undefined, payment_status: checkoutStatus.paymentStatus || undefined, environment: checkoutStatus.environment || input.environment || analyticsMetadata.environment }),
+        };
+        publicAnalyticsSdk.trackCheckoutCompleted(conversionInput);
+        markCheckoutSessionTracked(checkoutSessionId, input.runtimeConfig);
+        await publicAnalyticsSdk.flush().catch(() => 0);
+        return 'tracked';
+    }
+    finally {
+        activeCheckoutCompletionKeys.delete(completionKey);
+    }
+}

package/dist/services/stripe.service.d.ts

@@ -119,8 +119,22 @@ type UpdateSubscriptionCheckoutPlanResponse = {
     checkoutSessionId: string;
     environment?: 'test' | 'live';
 };
+export type VerifySubscriptionCheckoutPaymentInput = {
+    checkoutSessionId: string;
+    environment?: RuntimeMode;
+    runtimeConfig?: StripeRuntimeConfigOverrides;
+};
+export type VerifySubscriptionCheckoutPaymentResponse = {
+    checkoutSessionId: string;
+    paid: boolean;
+    paymentStatus?: string | null;
+    status?: string | null;
+    environment?: 'test' | 'live';
+    analyticsMetadata?: Record<string, unknown>;
+};
 export declare function createStripeSubscriptionCheckout(input: CreateSubscriptionCheckoutInput): Promise<CreateSubscriptionCheckoutResponse>;
 export declare function updateStripeSubscriptionCheckoutPlan(input: UpdateSubscriptionCheckoutPlanInput): Promise<UpdateSubscriptionCheckoutPlanResponse>;
+export declare function verifyStripeSubscriptionCheckoutPayment(input: VerifySubscriptionCheckoutPaymentInput): Promise<VerifySubscriptionCheckoutPaymentResponse>;
 type CreateCheckoutSessionInput = {
     plan: CheckoutSessionPlanInput;
     successUrl: string;

package/dist/services/stripe.service.js

@@ -714,6 +714,31 @@ export async function updateStripeSubscriptionCheckoutPlan(input) {
     }
     return (await response.json());
 }
+export async function verifyStripeSubscriptionCheckoutPayment(input) {
+    const checkoutSessionId = input.checkoutSessionId.trim();
+    if (!checkoutSessionId) {
+        throw new Error('checkoutSessionId is required');
+    }
+    const runtimeConfig = resolveStripeRuntimeConfig(input.runtimeConfig);
+    const response = await fetch(buildStripeRuntimeApiUrl('/sdk/public/payments/subscriptions/checkout-session-status', runtimeConfig), {
+        method: 'POST',
+        headers: buildStripeRuntimeHeaders(runtimeConfig, {
+            'Content-Type': 'application/json',
+        }),
+        body: JSON.stringify({
+            publishableKey: runtimeConfig.funnelSdkPublishableKey || undefined,
+            funnelId: runtimeConfig.funnelId || undefined,
+            funnelVersionId: runtimeConfig.funnelVersionId || undefined,
+            checkoutSessionId,
+            environment: input.environment || undefined,
+        }),
+    });
+    if (!response.ok) {
+        const errorMessage = await parseErrorMessage(response, 'Unable to verify subscription checkout');
+        throw new Error(errorMessage);
+    }
+    return (await response.json());
+}
 export async function createStripeCheckoutSession(input) {
     var _a, _b, _c, _d, _e;
     const recurring = resolveCheckoutPlanRecurringConfig(input.plan);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/payments",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",
@@ -27,6 +27,7 @@
     "test:run": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@funnelsgrove/analytics": "^0.1.13",
     "@funnelsgrove/runtime": "^0.1.18",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",