@flopay/js 1.3.4 → 1.4.1

package/dist/index.d.cts

@@ -41,7 +41,10 @@ declare class FloPayElements {
 declare class FloPay {
     private readonly provider;
     private readonly config;
+    private readonly telemetryReporter?;
     private currentElements;
+    private readonly cardThreeDsStartedAt;
+    private now;
     constructor(provider: PaymentProviderAdapter, config: FloPayConfig);
     /**
      * Creates a new `FloPayElements` group for mounting payment fields.
@@ -58,6 +61,9 @@ declare class FloPay {
     createPaymentMethod(billingDetails?: _flopay_shared.BillingDetails): Promise<CreatePaymentMethodResult>;
     /** Confirm a card payment with a known client secret and payment method ID. */
     confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    private trackCardThreeDsAttempt;
+    private takeCardThreeDsAttempt;
+    private pruneExpiredCardThreeDsAttempts;
     /**
      * Create a {@link CardCaptureAdapter} for collecting card details through the
      * backend-rendered hosted vault PCI widget instead of provider-owned (Stripe)
@@ -126,9 +132,10 @@ declare class FloPay {
  * It initializes the underlying payment provider (currently Stripe)
  * and returns a ready-to-use `FloPay` instance.
  *
- * Instances are cached per `publishableKey`, so calling `loadFloPay` twice
- * with the same key returns the same instance. Different keys produce
- * independent instances that can run side-by-side.
+ * Instances are cached per complete behavior-affecting configuration.
+ * Matching calls return the same instance; calls with different billing API,
+ * telemetry, locale, API version, or appearance options receive independent
+ * instances.
  *
  * @example
  * ```ts
@@ -152,6 +159,8 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     readonly name = "stripe";
     private stripe;
     private elements;
+    private readonly pendingCardThreeDsAttempts;
+    private cardThreeDsAttemptSequence;
     private appliedAppearanceKey;
     initialize(config: FloPayConfig): Promise<void>;
     /** Lazily creates the Stripe Elements group for the given options. */
@@ -163,6 +172,13 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     }>;
     createPaymentMethod(billingDetails?: BillingDetails): Promise<CreatePaymentMethodResult>;
     confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    /**
+     * Bind provider-observed 3DS milestones to the exact confirmation context.
+     * The sensitive client secret/payment method pair stays only in this private,
+     * in-memory key; callers and telemetry receive an unrelated opaque id.
+     */
+    private withCardThreeDsLifecycle;
+    private pruneExpiredCardThreeDsAttempts;
     confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
     private extractPaymentMethodId;
     confirmPayPalPayment(params: {
@@ -295,6 +311,10 @@ interface RawCheckoutSession {
         testEventCode?: string | null;
     };
 }
+interface PaymentAPIOptions {
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
+}
 /**
  * Client-side payment API service.
  *
@@ -304,7 +324,17 @@ interface RawCheckoutSession {
  */
 declare class PaymentAPI {
     private readonly baseUrl;
-    constructor(billingApiUrl: string);
+    private readonly directTelemetry?;
+    private readonly telemetryHooks?;
+    private directTelemetryCheckoutId?;
+    constructor(billingApiUrl: string, options?: PaymentAPIOptions);
+    /** Dispose the reporter owned by direct public usage. Internal hooks are never disposed here. */
+    destroy(): void;
+    private reportDirectFailure;
+    private telemetryTimestamp;
+    private beginDirectTelemetryCheckout;
+    private beginDirectTelemetryOperation;
+    private adoptDirectTelemetryCheckout;
     /**
      * Fetch a raw checkout session by ID.
      *
@@ -493,6 +523,7 @@ declare class PaymentAPI {
      * Falls back to create + GET if the backend doesn't support `expand`.
      */
     createAndFetchSession(params: InlineSessionDraft): Promise<NormalizedCheckoutSession>;
+    private createAndFetchSessionRequest;
     waitForCheckoutSessionCompletion(checkoutSessionId: string, options?: {
         initialDelayMs?: number;
         timeoutMs?: number;
@@ -544,6 +575,8 @@ interface PciVaultCardCaptureConfig {
      * same-window in the Model-A flow).
      */
     expectedOrigin?: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
 }
 /**
  * {@link CardCaptureAdapter} backed by the backend-rendered PCIVault hosted
@@ -557,6 +590,9 @@ interface PciVaultCardCaptureConfig {
 declare class PciVaultCardCapture implements CardCaptureAdapter {
     readonly provider: CardCaptureProviderId;
     private readonly config;
+    private telemetryReporter?;
+    private readonly ownsTelemetryReporter;
+    private readonly requestedAt?;
     private container;
     private messageHandler;
     /**
@@ -587,9 +623,14 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
     /** Latest card-field order + autofocus directive to push into the widget. */
     private cardFieldOrder;
     private cardAutoFocus;
+    private captureRequestedAt;
+    private vaultReadyReported;
+    private submissionStarted;
+    private submissionStartedAt;
     private readonly listeners;
     constructor(config?: PciVaultCardCaptureConfig);
     mount(container: HTMLElement, options: CardCaptureMountOptions): Promise<void>;
+    private reportVaultLoadFailure;
     on(event: CardCaptureEventType, handler: (event: CardCaptureOutcomeEvent) => void): () => void;
     unmount(): void;
     /**
@@ -600,6 +641,7 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
      */
     private injectWidget;
     private attachMessageListener;
+    private reportOutcome;
     /**
      * Push merchant theme colors into the hosted widget (live). The host calls
      * this on a runtime theme switch; the widget applies them to its CSS variables
@@ -648,6 +690,7 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
      * waiting for the eventual provider webhook.
      */
     private postActionCompleted;
+    private abandonActionRequiredOverlay;
     private hideActionRequiredOverlay;
     /**
      * Size the hosted-widget iframe to the height reported by the form inside it.
@@ -659,37 +702,6 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
     private applyHeight;
 }
 
-/**
- * Creates a checkout session via the billing API and redirects the user
- * to the hosted checkout page.
- *
- * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.
- *
- * - On 201: Redirects to `{checkoutBaseUrl}/secure?id={uuid}&...redirectParams`
- * - On 204: Redirects directly to `successUrl` (payment method already on file)
- * - On other: Returns `{ status }` without redirecting
- *
- * @example
- * ```ts
- * import { createCheckoutSession } from '@flopay/js';
- *
- * await createCheckoutSession({
- *   billingApiUrl: 'https://billing.example.com',
- *   checkoutBaseUrl: 'https://checkout.example.com',
- *   clientId: 'client_123',
- *   currency: 'USD',
- *   items: [{
- *     code: 'initial_charge',
- *     quantity: 1,
- *     metadata: { source: 'web' },
- *   }],
- *   account: { userId: 'user_1', email: 'user@example.com' },
- *   successUrl: '/success',
- *   cancelUrl: '/cancel',
- *   redirectParams: { email: 'user@example.com', bg: 'courses', mode: 'confirm' },
- * });
- * ```
- */
 declare function createCheckoutSession(options: CreateSessionParams): Promise<CheckoutSessionResult>;
 /**
  * Creates a checkout session with automatic retry on timeout/abort errors.

package/dist/index.d.ts

@@ -41,7 +41,10 @@ declare class FloPayElements {
 declare class FloPay {
     private readonly provider;
     private readonly config;
+    private readonly telemetryReporter?;
     private currentElements;
+    private readonly cardThreeDsStartedAt;
+    private now;
     constructor(provider: PaymentProviderAdapter, config: FloPayConfig);
     /**
      * Creates a new `FloPayElements` group for mounting payment fields.
@@ -58,6 +61,9 @@ declare class FloPay {
     createPaymentMethod(billingDetails?: _flopay_shared.BillingDetails): Promise<CreatePaymentMethodResult>;
     /** Confirm a card payment with a known client secret and payment method ID. */
     confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    private trackCardThreeDsAttempt;
+    private takeCardThreeDsAttempt;
+    private pruneExpiredCardThreeDsAttempts;
     /**
      * Create a {@link CardCaptureAdapter} for collecting card details through the
      * backend-rendered hosted vault PCI widget instead of provider-owned (Stripe)
@@ -126,9 +132,10 @@ declare class FloPay {
  * It initializes the underlying payment provider (currently Stripe)
  * and returns a ready-to-use `FloPay` instance.
  *
- * Instances are cached per `publishableKey`, so calling `loadFloPay` twice
- * with the same key returns the same instance. Different keys produce
- * independent instances that can run side-by-side.
+ * Instances are cached per complete behavior-affecting configuration.
+ * Matching calls return the same instance; calls with different billing API,
+ * telemetry, locale, API version, or appearance options receive independent
+ * instances.
  *
  * @example
  * ```ts
@@ -152,6 +159,8 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     readonly name = "stripe";
     private stripe;
     private elements;
+    private readonly pendingCardThreeDsAttempts;
+    private cardThreeDsAttemptSequence;
     private appliedAppearanceKey;
     initialize(config: FloPayConfig): Promise<void>;
     /** Lazily creates the Stripe Elements group for the given options. */
@@ -163,6 +172,13 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     }>;
     createPaymentMethod(billingDetails?: BillingDetails): Promise<CreatePaymentMethodResult>;
     confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    /**
+     * Bind provider-observed 3DS milestones to the exact confirmation context.
+     * The sensitive client secret/payment method pair stays only in this private,
+     * in-memory key; callers and telemetry receive an unrelated opaque id.
+     */
+    private withCardThreeDsLifecycle;
+    private pruneExpiredCardThreeDsAttempts;
     confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
     private extractPaymentMethodId;
     confirmPayPalPayment(params: {
@@ -295,6 +311,10 @@ interface RawCheckoutSession {
         testEventCode?: string | null;
     };
 }
+interface PaymentAPIOptions {
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
+}
 /**
  * Client-side payment API service.
  *
@@ -304,7 +324,17 @@ interface RawCheckoutSession {
  */
 declare class PaymentAPI {
     private readonly baseUrl;
-    constructor(billingApiUrl: string);
+    private readonly directTelemetry?;
+    private readonly telemetryHooks?;
+    private directTelemetryCheckoutId?;
+    constructor(billingApiUrl: string, options?: PaymentAPIOptions);
+    /** Dispose the reporter owned by direct public usage. Internal hooks are never disposed here. */
+    destroy(): void;
+    private reportDirectFailure;
+    private telemetryTimestamp;
+    private beginDirectTelemetryCheckout;
+    private beginDirectTelemetryOperation;
+    private adoptDirectTelemetryCheckout;
     /**
      * Fetch a raw checkout session by ID.
      *
@@ -493,6 +523,7 @@ declare class PaymentAPI {
      * Falls back to create + GET if the backend doesn't support `expand`.
      */
     createAndFetchSession(params: InlineSessionDraft): Promise<NormalizedCheckoutSession>;
+    private createAndFetchSessionRequest;
     waitForCheckoutSessionCompletion(checkoutSessionId: string, options?: {
         initialDelayMs?: number;
         timeoutMs?: number;
@@ -544,6 +575,8 @@ interface PciVaultCardCaptureConfig {
      * same-window in the Model-A flow).
      */
     expectedOrigin?: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
 }
 /**
  * {@link CardCaptureAdapter} backed by the backend-rendered PCIVault hosted
@@ -557,6 +590,9 @@ interface PciVaultCardCaptureConfig {
 declare class PciVaultCardCapture implements CardCaptureAdapter {
     readonly provider: CardCaptureProviderId;
     private readonly config;
+    private telemetryReporter?;
+    private readonly ownsTelemetryReporter;
+    private readonly requestedAt?;
     private container;
     private messageHandler;
     /**
@@ -587,9 +623,14 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
     /** Latest card-field order + autofocus directive to push into the widget. */
     private cardFieldOrder;
     private cardAutoFocus;
+    private captureRequestedAt;
+    private vaultReadyReported;
+    private submissionStarted;
+    private submissionStartedAt;
     private readonly listeners;
     constructor(config?: PciVaultCardCaptureConfig);
     mount(container: HTMLElement, options: CardCaptureMountOptions): Promise<void>;
+    private reportVaultLoadFailure;
     on(event: CardCaptureEventType, handler: (event: CardCaptureOutcomeEvent) => void): () => void;
     unmount(): void;
     /**
@@ -600,6 +641,7 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
      */
     private injectWidget;
     private attachMessageListener;
+    private reportOutcome;
     /**
      * Push merchant theme colors into the hosted widget (live). The host calls
      * this on a runtime theme switch; the widget applies them to its CSS variables
@@ -648,6 +690,7 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
      * waiting for the eventual provider webhook.
      */
     private postActionCompleted;
+    private abandonActionRequiredOverlay;
     private hideActionRequiredOverlay;
     /**
      * Size the hosted-widget iframe to the height reported by the form inside it.
@@ -659,37 +702,6 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
     private applyHeight;
 }
 
-/**
- * Creates a checkout session via the billing API and redirects the user
- * to the hosted checkout page.
- *
- * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.
- *
- * - On 201: Redirects to `{checkoutBaseUrl}/secure?id={uuid}&...redirectParams`
- * - On 204: Redirects directly to `successUrl` (payment method already on file)
- * - On other: Returns `{ status }` without redirecting
- *
- * @example
- * ```ts
- * import { createCheckoutSession } from '@flopay/js';
- *
- * await createCheckoutSession({
- *   billingApiUrl: 'https://billing.example.com',
- *   checkoutBaseUrl: 'https://checkout.example.com',
- *   clientId: 'client_123',
- *   currency: 'USD',
- *   items: [{
- *     code: 'initial_charge',
- *     quantity: 1,
- *     metadata: { source: 'web' },
- *   }],
- *   account: { userId: 'user_1', email: 'user@example.com' },
- *   successUrl: '/success',
- *   cancelUrl: '/cancel',
- *   redirectParams: { email: 'user@example.com', bg: 'courses', mode: 'confirm' },
- * });
- * ```
- */
 declare function createCheckoutSession(options: CreateSessionParams): Promise<CheckoutSessionResult>;
 /**
  * Creates a checkout session with automatic retry on timeout/abort errors.