@funnelsgrove/runtime 0.11.2 → 0.11.4

package/README.md

@@ -43,6 +43,57 @@ documented in [`docs/product-specs/funnel-template-runtime.md`](../../docs/produ
 - `components/*`: generic runtime context, subscription handoff/management, editor panel, dev info, and base controls.
 - `content/*` and `steps/types`: shared step content and taxonomy contracts.
 
+## Browser SDK structure
+
+`funnelSdkService` remains the public entry point, with the same eighteen methods
+and exported input/response types. It is a plain object of async functions; methods
+can also be destructured without losing a `this` binding.
+
+Implementation lives in `services/funnel-sdk/`, grouped by `users`, `uploads`,
+`checkout`, and `subscriptions`. Each use case owns its endpoint and sequencing.
+Keep request mappers beside their use cases (for example,
+`checkout/requests.ts`), not in a generic mapping layer. Only runtime identity,
+headers, JSON transport, and API error handling belong in `shared/`.
+
+SDK HTTP requests serve the funnel. Server-to-server integration clients and direct
+payment-provider calls do not belong here. Do not create workflow classes or files
+for these short request sequences. Photo uploads prepare an upload through the API,
+then send the original blob directly to its signed destination, without SDK headers.
+
+The V1/V2 switch, legacy method signatures, field casing, empty-field filtering,
+errors, and retry behavior are compatibility contracts. Mutations are not retried
+automatically and V2 failures do not fall back to V1. Before changing these contracts,
+add focused regressions; `funnel-sdk.contract.test.ts` captures the pre-refactor
+requests, and `funnel-sdk.http.test.ts` exercises real loopback HTTP and signed uploads.
+
+## Session API structure
+
+`apiService` keeps its thirteen public methods and four public type exports. It is
+also a plain object of functions, implemented in `services/session/`:
+
+- `bootstrap/`: verify candidate identity, reuse a request-scoped idempotency key,
+  bootstrap once, clear only the completed record, and map the resulting user.
+- `users/` and `emailCapture/`: profile updates and email capture, with named
+  request/response mappers and email-response validation beside the functions.
+- `uploads/`: delegate the original file to the SDK signed upload, then validate
+  its result; local object URLs are only the no-key fallback.
+- `subscriptions/`: resolve identity from the management URL, validate it, and
+  call the SDK. Never substitute the stored session identity for a missing link.
+- `identity.ts` and `bootstrap/idempotency.ts`: own session storage mechanics.
+- `ping/transport.ts`: owns the same-origin, best-effort ping and its error handling.
+
+These are use-case folders, not another workflow or data layer. Keep request and
+response mappers pure: pass runtime mode/revision explicitly instead of reading
+browser configuration inside a mapping function. SDK requests still go through
+`funnelSdkService`; only the same-origin ping owns a separate HTTP boundary.
+Validate email/canonical identity before persistence. Preserve failed bootstrap
+keys for explicit retry and never add an automatic retry to an uncertain write.
+
+The pre-extraction session tests remain unchanged behavior baselines. Session
+boundary tests protect the facade and infrastructure ownership; real loopback
+tests exercise bootstrap/profile/email, URL-only subscription management, explicit
+bootstrap retry, and binary uploads through both API facades.
+
 ## Storage Conventions
 
 - runtime user ids stay funnel-scoped under `funnel:<funnelId>:user-id`

package/dist/components/ManageSubscriptionScreen.js

@@ -5,6 +5,7 @@ import { apiService } from '../services/api.service.js';
 import { buildPreviewManageSubscriptionsFallback, isPreviewFrameRuntime, } from '../services/preview-frame.service.js';
 import { runtimePublicConfig } from '../services/public-env.js';
 import { useFunnel } from './FunnelContext.js';
+import { useFunnelRuntimeConfig } from './FunnelRuntimeConfigBoundary.js';
 const supportEmail = runtimePublicConfig.supportEmail;
 const isCancellableSubscription = (subscription) => {
     const normalizedStatus = subscription.status.trim().toLowerCase();
@@ -34,6 +35,8 @@ const getRowActionLabel = (subscription, isSelected, content) => {
 export function ManageSubscriptionScreen({ stepId, content, homeStepId, nodeId, }) {
     var _a, _b, _c, _d;
     const { goToStep, setAnswer } = useFunnel();
+    const { config: publishedRuntimeConfig } = useFunnelRuntimeConfig();
+    const paymentsApiVersion = publishedRuntimeConfig === null || publishedRuntimeConfig === void 0 ? void 0 : publishedRuntimeConfig.paymentsApiVersion;
     const supportLinkLabel = supportEmail;
     const supportLinkHref = `mailto:${supportEmail}`;
     const [stage, setStage] = useState('subscriptions');
@@ -60,7 +63,7 @@ export function ManageSubscriptionScreen({ stepId, content, homeStepId, nodeId,
                 return;
             }
             try {
-                const payload = await apiService.getManageSubscriptions();
+                const payload = await apiService.getManageSubscriptions({ paymentsApiVersion });
                 if (!active) {
                     return;
                 }
@@ -93,7 +96,7 @@ export function ManageSubscriptionScreen({ stepId, content, homeStepId, nodeId,
         return () => {
             active = false;
         };
-    }, [content.errorMessages.load]);
+    }, [content.errorMessages.load, paymentsApiVersion]);
     const subscriptions = useMemo(() => { var _a; return (_a = data === null || data === void 0 ? void 0 : data.subscriptions) !== null && _a !== void 0 ? _a : []; }, [data]);
     const cancellableSubscriptions = useMemo(() => {
         return subscriptions.filter(isCancellableSubscription);
@@ -124,7 +127,9 @@ export function ManageSubscriptionScreen({ stepId, content, homeStepId, nodeId,
         try {
             const payload = await apiService.updateSubscription({
                 subscriptionId: selectedSubscription.id,
+                subscriptionRef: selectedSubscription.subscriptionRef,
                 action: 'cancel',
+                runtimeConfig: { paymentsApiVersion },
             });
             setData(payload);
             setAnswer('manageSubscriptionCancelled', true);

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export * from './runtime/step-asset-preloader.js';
 export * from './runtime/url-user-attributes.js';
 export * from './runtime/use-url-user-attributes-sync.js';
 export * from './services/api.service.js';
+export * from './services/checkout-identity.service.js';
 export * from './services/funnel-sdk.service.js';
 export * from './services/funnel-state.service.js';
 export * from './services/logger.js';

package/dist/index.js

@@ -34,6 +34,7 @@ export * from './runtime/url-user-attributes.js';
 export * from './runtime/use-url-user-attributes-sync.js';
 // Browser-safe services.
 export * from './services/api.service.js';
+export * from './services/checkout-identity.service.js';
 export * from './services/funnel-sdk.service.js';
 export * from './services/funnel-state.service.js';
 export * from './services/logger.js';

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

@@ -1,105 +1,29 @@
-import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
-import { type FunnelUserAttribution } from '../runtime/funnel-attribution.js';
-import { type UrlUserAttributes } from '../runtime/url-user-attributes.js';
-export type AppUser = {
-    id: string;
-    name: string;
-    email: string;
-    attributes: FunnelUserAnswers;
-    document: Record<string, unknown>;
+import { getOrCreateClientUserId, persistCanonicalUserId, getBootstrapCandidateUserId } from './session/identity.js';
+import { getSubscriptionManagementUserId, getSubscriptionManagementStripeCustomerId } from './session/subscriptions/identity.js';
+import { bootstrapSession } from './session/bootstrap/bootstrapSession.js';
+import { updateUser } from './session/users/updateUser.js';
+import { syncUrlUserAttributes } from './session/users/syncUrlUserAttributes.js';
+import { captureEmail } from './session/emailCapture/captureEmail.js';
+import { uploadTempPhoto } from './session/uploads/uploadTempPhoto.js';
+import { pingUserContext } from './session/ping/pingUserContext.js';
+import { getManageSubscriptions } from './session/subscriptions/getManageSubscriptions.js';
+import { updateSubscription } from './session/subscriptions/updateSubscription.js';
+export type { AppUser } from './session/users/types.js';
+export type { EmailCaptureResult } from './session/emailCapture/types.js';
+export type { TempPhotoUploadResult } from './session/uploads/types.js';
+export type { ManageSubscriptionsResponse } from './session/subscriptions/types.js';
+export declare const apiService: {
+    getOrCreateClientUserId: typeof getOrCreateClientUserId;
+    persistCanonicalUserId: typeof persistCanonicalUserId;
+    getSubscriptionManagementUserId: typeof getSubscriptionManagementUserId;
+    getSubscriptionManagementStripeCustomerId: typeof getSubscriptionManagementStripeCustomerId;
+    getBootstrapCandidateUserId: typeof getBootstrapCandidateUserId;
+    bootstrapSession: typeof bootstrapSession;
+    updateUser: typeof updateUser;
+    captureEmail: typeof captureEmail;
+    syncUrlUserAttributes: typeof syncUrlUserAttributes;
+    pingUserContext: typeof pingUserContext;
+    uploadTempPhoto: typeof uploadTempPhoto;
+    getManageSubscriptions: typeof getManageSubscriptions;
+    updateSubscription: typeof updateSubscription;
 };
-type AppUserInput = Omit<AppUser, 'document'> & {
-    document?: Record<string, unknown>;
-};
-export type ManageSubscriptionsResponse = {
-    user: {
-        id: string;
-        user_id: string;
-        email: string | null;
-        fullName: string | null;
-        subscriptionStatus: string | null;
-    } | null;
-    subscriptions: Array<{
-        id: string;
-        status: string;
-        providerSubscriptionId: string;
-        providerPlanId: string | null;
-        cancelAtPeriodEnd: boolean;
-        currentPeriodStart: string | null;
-        currentPeriodEnd: string | null;
-        createdAt: string | null;
-        amountCents?: number | null;
-        currency?: string | null;
-        billingInterval?: string | null;
-        billingIntervalCount?: number | null;
-        discountCouponIds?: string[];
-        retentionDiscount?: {
-            couponId: string;
-            discountPercent: number;
-            amountCents: number;
-            discountedAmountCents: number;
-            originalAmountCents: number;
-        };
-        environment: 'test' | 'live';
-    }>;
-    eventsCount: number;
-};
-export type TempPhotoUploadResult = {
-    key: string;
-    publicUrl: string;
-    contentType: string;
-    sizeBytes: number;
-    uploadedAt: string;
-};
-export type EmailCaptureResult = {
-    user: AppUser;
-    eventId: string;
-    eventCreated: boolean;
-    canonicalUser: AppUser | null;
-    activeSubscription: boolean;
-};
-declare class ApiService {
-    getOrCreateClientUserId(): string;
-    persistCanonicalUserId(userId: string): string;
-    getSubscriptionManagementUserId(): string | null;
-    getSubscriptionManagementStripeCustomerId(): string | null;
-    getBootstrapCandidateUserId(fallbackUserId?: string | null): string | null;
-    private fetchCurrentUserState;
-    private resolveBootstrapUserId;
-    bootstrapSession(input?: {
-        userId?: string;
-        email?: string;
-        name?: string;
-        attribution?: FunnelUserAttribution;
-    }): Promise<AppUser>;
-    updateUser(user: AppUser, options?: {
-        attribution?: FunnelUserAttribution;
-        persistClientIdentity?: boolean;
-    }): Promise<AppUser>;
-    captureEmail(input: {
-        userId: string;
-        email: string;
-        environment: 'test' | 'live';
-        answers?: FunnelUserAnswers;
-    }): Promise<EmailCaptureResult>;
-    syncUrlUserAttributes(input: {
-        user: AppUserInput;
-        attributes?: FunnelUserAnswers;
-        urlAttributes?: UrlUserAttributes | null;
-        attribution?: FunnelUserAttribution;
-    }): Promise<AppUser | null>;
-    pingUserContext(userId: string): Promise<AppUser | null>;
-    uploadTempPhoto(input: {
-        file: File;
-        userId?: string;
-        source?: 'camera' | 'upload';
-    }): Promise<TempPhotoUploadResult>;
-    getManageSubscriptions(): Promise<ManageSubscriptionsResponse>;
-    updateSubscription(input: {
-        subscriptionId: string;
-        action: 'cancel' | 'renew' | 'apply-discount';
-        couponId?: string | null;
-    }): Promise<ManageSubscriptionsResponse>;
-}
-export declare const apiService: ApiService;
-export {};