@flopay/js 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import * as _flopay_shared from '@flopay/shared';
+import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingProvider, ProcessPaymentParams, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
+
+/**
+ * Manages the creation and lifecycle of payment elements.
+ *
+ * Each `FloPayElements` instance is bound to a single provider adapter
+ * and tracks all created elements for cleanup.
+ */
+declare class FloPayElements {
+    private readonly provider;
+    private readonly elementMap;
+    private readonly baseOptions;
+    constructor(provider: PaymentProviderAdapter, options?: ElementOptions);
+    /**
+     * Creates a new element of the given type.
+     * If an element of that type already exists, it is destroyed first.
+     */
+    create(type: ElementType, options?: ElementOptions): Promise<MountedElement>;
+    /** Returns a previously created element, or `null`. */
+    getElement(type: ElementType): MountedElement | null;
+    /**
+     * Submits all mounted elements for validation.
+     *
+     * Returns an object with an optional error if validation fails.
+     * This does NOT confirm the payment — call `floPay.confirmPayment()` for that.
+     */
+    submit(): Promise<{
+        error?: FloPayError;
+    }>;
+    /** Destroys all created elements and clears the internal map. */
+    destroy(): void;
+}
+
+/**
+ * The main FloPay SDK instance.
+ *
+ * Created via `loadFloPay(publishableKey)`. Provides element management,
+ * payment confirmation, and session retrieval.
+ */
+declare class FloPay {
+    private readonly provider;
+    private readonly config;
+    private currentElements;
+    constructor(provider: PaymentProviderAdapter, config: FloPayConfig);
+    /**
+     * Creates a new `FloPayElements` group for mounting payment fields.
+     *
+     * Only one elements group is active at a time. Creating a new one
+     * destroys the previous group.
+     */
+    elements(options?: ElementOptions): FloPayElements;
+    /** Submit elements for validation. */
+    submitElements(): Promise<{
+        error?: _flopay_shared.FloPayError;
+    }>;
+    /** Create a payment method from the current elements (tokenize card). */
+    createPaymentMethod(): Promise<CreatePaymentMethodResult>;
+    /** Confirm a card payment with a known client secret and payment method ID. */
+    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    /** Confirm a PayPal payment: create intent via billing API → confirm → redirect if needed. */
+    confirmPayPalPayment(params: {
+        billingApiUrl: string;
+        sessionId: string;
+        email: string;
+        returnUrl: string;
+    }): Promise<ConfirmCardPaymentResult>;
+    /** Resume a PayPal payment after redirect return. Returns null if no PayPal params in URL. */
+    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
+    /** Confirms a payment using the mounted elements. */
+    confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
+    /**
+     * Retrieves a checkout session by ID via the billing API.
+     *
+     * Returns the normalized `CheckoutSession` with amount, currency,
+     * customer data, and status.
+     *
+     * Requires `billingApiUrl` to be set — either via `loadFloPay(key, { billingApiUrl })`
+     * or passed directly as the second argument.
+     */
+    retrieveSession(sessionId: string, billingApiUrl?: string): Promise<CheckoutSession>;
+    /**
+     * Retrieves and normalizes a checkout session, including provider-specific
+     * data (Stripe clientSecret/publishableKey, Chargebee site, etc.).
+     *
+     * The billing API URL is resolved from: explicit param → `loadFloPay()` config
+     * → `NEXT_PUBLIC_FLOPAY_ENV` env var → `configureFlopay()` → staging fallback.
+     */
+    retrieveUnifiedSession(sessionId: string, billingApiUrl?: string): Promise<NormalizedCheckoutSession>;
+    /**
+     * Returns the raw underlying provider instance (e.g. Stripe object).
+     * Used internally by components that need direct provider access,
+     * such as PayPal which requires its own Elements instance.
+     */
+    getRawProvider(): unknown;
+    /** Tears down the SDK instance and releases resources. */
+    destroy(): void;
+}
+
+/**
+ * Loads and initializes the FloPay SDK.
+ *
+ * This is the primary entry point for consumer applications.
+ * It initializes the underlying payment provider (currently Stripe)
+ * and returns a ready-to-use `FloPay` instance.
+ *
+ * @example
+ * ```ts
+ * import { loadFloPay } from '@flopay/js';
+ *
+ * const flopay = await loadFloPay('pk_test_...');
+ * const elements = flopay.elements();
+ * const cardElement = await elements.create('card');
+ * cardElement.mount('#card-container');
+ * ```
+ */
+declare function loadFloPay(publishableKey: string, options?: Omit<FloPayConfig, 'publishableKey'>): Promise<FloPay>;
+
+/**
+ * Payment provider adapter backed by Stripe.
+ *
+ * Implements the `PaymentProviderAdapter` interface so that FloPay consumers
+ * interact with a stable API regardless of the upstream provider.
+ */
+declare class StripeAdapter implements PaymentProviderAdapter {
+    readonly name = "stripe";
+    private stripe;
+    private elements;
+    initialize(config: FloPayConfig): Promise<void>;
+    /** Lazily creates the Stripe Elements group for the given options. */
+    private getElements;
+    createElement(type: ElementType, options: ElementOptions): Promise<MountedElement>;
+    getElement(type: ElementType): MountedElement | null;
+    submitElements(): Promise<{
+        error?: FloPayError;
+    }>;
+    createPaymentMethod(): Promise<CreatePaymentMethodResult>;
+    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
+    confirmPayPalPayment(params: {
+        billingApiUrl: string;
+        sessionId: string;
+        email: string;
+        returnUrl: string;
+    }): Promise<ConfirmCardPaymentResult>;
+    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
+    getRawProvider(): unknown;
+    createPayPalElements(options: ElementOptions): unknown;
+    destroy(): void;
+}
+
+/** Raw billing API response wrapper. */
+interface BillingResponse<T> {
+    data: T;
+}
+/** Raw checkout session from the billing API (includes gateway field). */
+interface RawCheckoutSession {
+    uuid: string;
+    nonce: string;
+    gateway?: BillingProvider;
+    status: 'pending' | 'completed';
+    successUrl: string;
+    cancelUrl: string;
+    createdAt?: string;
+    checkoutUrl?: string;
+    items: Array<{
+        uuid: string;
+        checkoutSessionId: string;
+        providerItemId: string;
+        providerItemName: string;
+        providerItemDescription?: string | null;
+        quantity: number;
+        totalAmount: number;
+        overrideAmount: number | null;
+        currency: string;
+        metadata?: Record<string, unknown> | null;
+    }>;
+    subscriptions: Array<{
+        uuid: string;
+        checkoutSessionId: string;
+        providerPlanId: string;
+        providerPlanName: string;
+        providerPlanDescription?: string | null;
+        quantity: number;
+        totalAmount: number;
+        overrideAmount: number | null;
+        currency: string;
+        isUpdate?: boolean;
+        metadata?: Record<string, unknown> | null;
+    }>;
+    coupons?: string[];
+    checkoutMode?: 'full' | 'auto' | 'confirm';
+    gatewayData: {
+        publishableKey?: string | null;
+    };
+    accountData: {
+        userId: string;
+        firstName: string;
+        lastName: string;
+        email: string;
+        gender?: string | null;
+        city?: string | null;
+        state?: string | null;
+        country?: string | null;
+        zip?: string | null;
+    };
+    tagsData: {
+        googleContainerId?: string | null;
+        sessionId?: string | null;
+        testEventCode?: string | null;
+    };
+}
+/**
+ * Client-side payment API service.
+ *
+ * Mirrors the `PaymentAPI` class from the checkout project's
+ * `src/service/api.ts`. All methods call the billing API endpoints
+ * that the checkout backend exposes.
+ */
+declare class PaymentAPI {
+    private readonly baseUrl;
+    constructor(billingApiUrl: string);
+    /** Fetch a raw checkout session by ID. */
+    getCheckoutSession(checkoutSessionId: string): Promise<BillingResponse<RawCheckoutSession>>;
+    /**
+     * Fetch and normalize a checkout session.
+     *
+     * Reads the backend's `gateway` field to determine the provider,
+     * then wraps the session in a `NormalizedCheckoutSession` for
+     * provider-agnostic consumption.
+     */
+    getUnifiedCheckoutSession(checkoutSessionId: string): Promise<NormalizedCheckoutSession>;
+    /**
+     * Submit a tokenized payment to the billing backend.
+     *
+     * The backend will either succeed, return `type: '3ds_required'`
+     * (with a `threeDSecureToken`), or return `type: 'paypal_redirect_required'`.
+     */
+    processPayment(userId: string, data: ProcessPaymentParams): Promise<Response>;
+    /**
+     * Create a PaymentIntent on the backend.
+     *
+     * Used by the Stripe flow to create a server-side PaymentIntent
+     * with the client's payment method attached.
+     */
+    createPaymentIntent(sessionId: string, email: string, paymentMethodType: string, options?: {
+        signal?: AbortSignal;
+        isPaypal?: string;
+    }): Promise<Response>;
+    /**
+     * Create a SetupIntent for saving payment methods.
+     */
+    createSetupIntent(sessionId: string, email: string, paymentMethodType: 'card' | 'google_pay' | 'apple_pay' | 'paypal_express_checkout', options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * Fetch user's prior payments by email.
+     * Used to determine if saved card UX should be shown.
+     */
+    getPaymentsByEmail(email: string, options?: {
+        signal?: AbortSignal;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        data: Array<{
+            id: string;
+        }>;
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+    /** Convert raw session to the SDK CheckoutSession shape. */
+    private toCheckoutSession;
+}
+
+/**
+ * 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',
+ *   items: [{
+ *     providerItemId: 'prod_abc',
+ *     providerItemName: 'Pro Plan',
+ *     totalAmount: 49.99,
+ *     overrideAmount: 24.99,
+ *   }],
+ *   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.
+ *
+ * Uses exponential backoff: 100ms, 200ms, 400ms, etc.
+ */
+declare function createCheckoutSessionWithRetries(options: CreateSessionParams & {
+    maxRetries?: number;
+}): Promise<CheckoutSessionResult>;
+
+export { FloPay, FloPayElements, PaymentAPI, StripeAdapter, createCheckoutSession, createCheckoutSessionWithRetries, loadFloPay };