@flopay/shared 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,602 @@
+/** Discriminated error types returned by the FloPay SDK. */
+type FloPayErrorType = 'validation_error' | 'api_error' | 'authentication_error' | 'rate_limit_error' | 'network_error';
+/**
+ * Custom error class for all FloPay SDK errors.
+ *
+ * Extends the native `Error` and adds structured fields that mirror
+ * Stripe-style error responses for familiarity.
+ */
+declare class FloPayError extends Error {
+    readonly type: FloPayErrorType;
+    readonly code?: string;
+    readonly declineCode?: string;
+    readonly param?: string;
+    constructor(message: string, type: FloPayErrorType, options?: {
+        code?: string;
+        declineCode?: string;
+        param?: string;
+    });
+}
+/** Create a validation error (e.g. missing required field). */
+declare function validationError(message: string, param?: string): FloPayError;
+/** Create an API error (e.g. upstream provider returned an error). */
+declare function apiError(message: string, code?: string): FloPayError;
+/** Create an authentication error (e.g. invalid publishable key). */
+declare function authenticationError(message: string): FloPayError;
+/** Create a rate limit error. */
+declare function rateLimitError(message: string): FloPayError;
+/** Create a network error (e.g. fetch failed). */
+declare function networkError(message: string): FloPayError;
+
+/** Theme variables that map to CSS custom properties on FloPay elements. */
+interface FloPayThemeVariables {
+    colorPrimary?: string;
+    colorBackground?: string;
+    colorText?: string;
+    colorDanger?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    fontSizeBase?: string;
+    spacingUnit?: string;
+}
+/** Controls the visual appearance of all FloPay elements. */
+interface FloPayAppearance {
+    theme?: 'default' | 'flat' | 'night' | 'none';
+    variables?: FloPayThemeVariables;
+    /** CSS-like rules keyed by selector (e.g. `".Input"`, `".Label"`). */
+    rules?: Record<string, Record<string, string>>;
+}
+/** A customer attached to a checkout session. */
+interface Customer {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    gender?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zip?: string;
+}
+/** Recurring interval configuration for subscription line items. */
+interface RecurringInterval {
+    interval: 'month' | 'year';
+    intervalCount?: number;
+}
+/** Inline product data when no pre-created price is referenced. */
+interface PriceData {
+    currency: string;
+    unitAmount: number;
+    productData: {
+        name: string;
+        description?: string;
+    };
+    recurring?: RecurringInterval;
+}
+/** A single line item within a checkout session. */
+interface LineItem {
+    /** Reference to a pre-created price object on the provider. */
+    price?: string;
+    /** Inline price data (used when no `price` reference exists). */
+    priceData?: PriceData;
+    quantity: number;
+}
+/** Checkout mode controlling the payment UI behavior. */
+type CheckoutMode = 'full' | 'auto' | 'confirm';
+/** A one-time item from a checkout session response. */
+interface CheckoutSessionItem {
+    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;
+}
+/** A subscription plan from a checkout session response. */
+interface CheckoutSessionSubscription {
+    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;
+}
+/** Represents a FloPay checkout session. */
+interface CheckoutSession {
+    id: string;
+    clientSecret: string;
+    mode: 'payment' | 'subscription' | 'setup';
+    status: 'open' | 'complete' | 'expired';
+    amount: number;
+    currency: string;
+    lineItems?: LineItem[];
+    customer?: Customer;
+    metadata?: Record<string, string>;
+    checkoutMode?: CheckoutMode;
+    items?: CheckoutSessionItem[];
+    subscriptions?: CheckoutSessionSubscription[];
+    successUrl?: string;
+    cancelUrl?: string;
+    coupons?: string[];
+    createdAt?: string;
+    gateway?: BillingProvider;
+    gatewayData?: {
+        publishableKey?: string | null;
+    };
+    accountData?: {
+        userId: string;
+        email: string;
+        firstName: string;
+        lastName: string;
+        gender?: string | null;
+        city?: string | null;
+        state?: string | null;
+        country?: string | null;
+        zip?: string | null;
+    };
+    tagsData?: TagsData;
+}
+/** The result of a payment confirmation attempt. */
+interface PaymentResult {
+    status: 'succeeded' | 'processing' | 'requires_action' | 'failed';
+    paymentIntentId?: string;
+    error?: FloPayError;
+}
+/** Parameters for confirming a payment. */
+interface ConfirmPaymentParams {
+    clientSecret: string;
+    /** Optional redirect URL after 3-D Secure or wallet authentication. */
+    returnUrl?: string;
+}
+/** Result from creating a payment method (tokenizing card fields). */
+interface CreatePaymentMethodResult {
+    paymentMethodId: string | null;
+    error?: FloPayError;
+}
+/** Parameters for confirming a card payment with a known client secret. */
+interface ConfirmCardPaymentParams {
+    clientSecret: string;
+    paymentMethodId: string;
+}
+/** Result from confirming a card payment. */
+interface ConfirmCardPaymentResult {
+    status: 'succeeded' | 'processing' | 'requires_action' | 'requires_capture' | 'failed';
+    paymentIntentId?: string;
+    paymentMethodId?: string;
+    error?: FloPayError;
+}
+/** The type of payment element to render. */
+type ElementType = 'payment' | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address';
+/** Emitted when an element's internal state changes. */
+interface ElementChangeEvent {
+    elementType: ElementType;
+    complete: boolean;
+    empty: boolean;
+    error?: {
+        message: string;
+        type: string;
+    };
+    /** Only populated for non-sensitive fields (e.g. address). */
+    value?: Record<string, unknown>;
+}
+/** Configuration options when creating an element. */
+interface ElementOptions {
+    appearance?: FloPayAppearance;
+    /** Client secret for the PaymentIntent or SetupIntent. When present, Stripe uses it directly. */
+    clientSecret?: string;
+    /**
+     * Total amount in the smallest currency unit (e.g. cents).
+     * Used when no `clientSecret` is available — Stripe Elements needs
+     * `mode` + `amount` + `currency` to render without a server-side intent.
+     */
+    amount?: number;
+    /** ISO 4217 currency code (lowercase). Used with `amount` when no `clientSecret`. */
+    currency?: string;
+    /** How payment methods are created. 'manual' = tokenize only, 'auto' = Stripe handles it. */
+    paymentMethodCreation?: 'manual' | 'auto';
+    layout?: 'tabs' | 'accordion' | 'auto';
+    defaultValues?: Record<string, unknown>;
+    readOnly?: boolean;
+    /** Address element mode: 'billing' or 'shipping'. */
+    mode?: 'billing' | 'shipping';
+}
+/**
+ * A payment element that has been created and can be mounted into the DOM.
+ *
+ * TODO: In a future phase, each MountedElement will render inside an iframe
+ * for PCI DSS SAQ-A compliance. For now, it wraps the underlying provider
+ * element directly.
+ */
+interface MountedElement {
+    mount(container: HTMLElement): void;
+    unmount(): void;
+    update(options: Partial<ElementOptions>): void;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    destroy(): void;
+}
+/** Top-level configuration for initializing FloPay. */
+interface FloPayConfig {
+    publishableKey: string;
+    /** Billing API base URL (e.g. https://api.stage.flopay.com). */
+    billingApiUrl?: string;
+    locale?: string;
+    appearance?: FloPayAppearance;
+    apiVersion?: string;
+}
+/**
+ * Abstraction layer for payment providers.
+ *
+ * Currently only Stripe is implemented (`StripeAdapter`). The interface
+ * ensures that adding new providers (Chargebee, Recurly, etc.) will not
+ * require changes in consumer code.
+ */
+interface PaymentProviderAdapter {
+    readonly name: string;
+    initialize(config: FloPayConfig): Promise<void>;
+    createElement(type: ElementType, options: ElementOptions): Promise<MountedElement>;
+    /** Retrieve an existing element by type, or `null` if not yet created. */
+    getElement(type: ElementType): MountedElement | null;
+    /** Submit elements for validation (Stripe `elements.submit()`). */
+    submitElements(): Promise<{
+        error?: 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. */
+    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
+    /**
+     * Create a PayPal payment: create PM → create intent → confirm with redirect.
+     * Returns the confirmed PaymentIntent ID if completed inline, or redirects to PayPal.
+     */
+    confirmPayPalPayment(params: {
+        billingApiUrl: string;
+        sessionId: string;
+        email: string;
+        returnUrl: string;
+    }): Promise<ConfirmCardPaymentResult>;
+    /**
+     * Resume a PayPal payment after redirect return.
+     * Checks URL params for payment_intent + redirect_status.
+     */
+    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
+    /**
+     * Get the raw underlying provider instance (e.g. Stripe object).
+     * Used internally for creating secondary Elements groups (e.g. PayPal).
+     */
+    getRawProvider(): unknown;
+    /**
+     * Create a secondary Elements group for PayPal.
+     * PayPal can't share Elements with card fields that use paymentMethodCreation: 'manual'.
+     */
+    createPayPalElements(options: ElementOptions): unknown;
+    destroy(): void;
+}
+/** Supported upstream billing providers. */
+type BillingProvider = 'recurly' | 'chargebee' | 'stripe';
+/** Token payload produced by client-side tokenization. */
+interface TokenizedBody {
+    id?: string;
+    type?: string;
+    threeDSecureActionResultTokenId?: string;
+    isPaypal?: boolean;
+}
+/** Checkout mode: tokenize client-side or redirect to hosted page. */
+type CheckoutModeKind = 'tokenize' | 'redirect';
+/** Provider-agnostic normalized checkout session. */
+interface NormalizedCheckoutSession {
+    provider: BillingProvider;
+    mode: CheckoutModeKind;
+    data: {
+        hostedUrl?: string;
+        clientToken?: string;
+        session?: CheckoutSession;
+        chargebee?: {
+            site?: string;
+            publishableKey?: string;
+            dropInToken?: string;
+            sessionId?: string;
+        };
+        stripe?: {
+            clientSecret?: string;
+            publishableKey?: string;
+        };
+    };
+    raw?: unknown;
+}
+/** A one-time purchase item for checkout session creation. */
+interface CheckoutItem {
+    /** The provider's item/product ID (e.g. Stripe price ID, Recurly plan code). */
+    providerItemId: string;
+    /** Display name for the item. */
+    providerItemName?: string | null;
+    /** Defaults to 1. */
+    quantity?: number;
+    /** The regular (full) price in the given currency. */
+    totalAmount: number;
+    /** A discounted price to charge instead of totalAmount. */
+    overrideAmount?: number | null;
+    /** ISO 4217 currency code. Defaults to 'USD'. */
+    currency?: string;
+}
+/** A recurring subscription plan for checkout session creation. */
+interface CheckoutSubscription {
+    /** The provider's plan ID. */
+    providerPlanId: string;
+    /** Display name for the plan. */
+    providerPlanName?: string | null;
+    /** Defaults to 1. */
+    quantity?: number;
+    /** The regular (full) price in the given currency. */
+    totalAmount: number;
+    /** A discounted price to charge instead of totalAmount. */
+    overrideAmount?: number | null;
+    /** ISO 4217 currency code. Defaults to 'USD'. */
+    currency?: string;
+}
+/** Buyer's account information for session creation. */
+interface CheckoutAccount {
+    userId: string;
+    firstName?: string;
+    lastName?: string;
+    email: string;
+    country?: string | null;
+    gender?: string | null;
+    city?: string | null;
+    state?: string | null;
+    zip?: string | null;
+}
+/** Analytics / pixel tags forwarded to the checkout page. */
+interface TagsData {
+    googleContainerId?: string | null;
+    sessionId?: string | null;
+    testEventCode?: string | null;
+}
+/**
+ * Parameters for creating a checkout session via the billing API.
+ * Mirrors the `CreateCheckoutSessionOptions` from clicktech-core-ui.
+ */
+interface CreateSessionParams {
+    /** Base URL of the billing API, e.g. https://billing.clicktech.com */
+    billingApiUrl: string;
+    /** Base URL of the checkout frontend, e.g. https://checkout.clicktech.com */
+    checkoutBaseUrl: string;
+    /** The client ID for the checkout session. */
+    clientId: string;
+    /** One-time purchase items. */
+    items?: CheckoutItem[];
+    /** Recurring subscription plans. */
+    subscriptions?: CheckoutSubscription[];
+    /** Buyer's account information. */
+    account: CheckoutAccount;
+    /** URL to redirect to after successful payment. */
+    successUrl: string;
+    /** URL to redirect to if the user cancels. */
+    cancelUrl: string;
+    /**
+     * Checkout mode sent to the billing API.
+     * - 'confirm' – show a payment confirmation page (default)
+     * - 'auto' – skip confirmation when a payment method is already on file
+     * - 'full' – full checkout flow
+     */
+    checkoutMode?: 'confirm' | 'auto' | 'full';
+    /** Coupon codes to apply. */
+    couponCodes?: string[];
+    /** Pixel / analytics tags forwarded to the checkout page. */
+    tagsData?: TagsData;
+    /** Extra query params appended to the checkout redirect URL. */
+    redirectParams?: Record<string, string>;
+    /** Whether to set the checkout_data cookie. Defaults to true. */
+    setCookie?: boolean;
+    /** Request timeout in milliseconds. Defaults to 12000. */
+    timeoutMs?: number;
+    /** UTM and funnel tracking metadata. */
+    utmMetadata?: Record<string, string | null | undefined>[];
+}
+/** Result from creating a checkout session. */
+type CheckoutSessionResult = {
+    status: 201;
+    redirectUrl: string;
+} | {
+    status: 204;
+} | {
+    status: number;
+};
+/**
+ * Data submitted when processing a payment (tokenized card/wallet data).
+ * Mirrors checkout project's ProcessCheckoutBodyDto.
+ */
+interface ProcessPaymentParams {
+    sessionId: string;
+    tokenizedData?: TokenizedBody;
+    accountData: {
+        userId: string;
+        email: string;
+        firstName: string;
+        lastName: string;
+        zip?: string;
+        country?: string;
+    };
+    chv?: string;
+}
+/** Parameters for creating a customer. */
+interface CreateCustomerParams {
+    email: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+/** Parameters for updating a customer. */
+interface UpdateCustomerParams {
+    email?: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+/** A webhook event from FloPay. */
+interface WebhookEvent {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    created: number;
+}
+/** Currency information mapped to a country. */
+interface CurrencyInfo {
+    currency: string;
+    symbol: string;
+    country: string;
+    countryCode: string;
+    /** 0 = no tax, 1 = tax (VAT) applies. */
+    tax: number;
+}
+/** A country option for UI select elements. */
+interface CountryOption {
+    code: string;
+    name: string;
+    flag: string;
+}
+
+/** FloPay environment — determines which billing API URL is used. */
+type FloPayEnvironment = 'staging' | 'production';
+/**
+ * Configure the FloPay SDK globally. Call once at app startup.
+ *
+ * The environment determines which billing API URL is used for all
+ * FloPay operations (session creation, payment processing, etc.).
+ *
+ * @example
+ * ```ts
+ * import { configureFlopay } from '@flopay/shared';
+ *
+ * // In production
+ * configureFlopay({ environment: 'production' });
+ *
+ * // In staging/development
+ * configureFlopay({ environment: 'staging' });
+ * ```
+ *
+ * Alternatively, set the `NEXT_PUBLIC_FLOPAY_ENV` environment variable
+ * to `'staging'` or `'production'` — the SDK reads it automatically.
+ */
+declare function configureFlopay(config: {
+    environment: FloPayEnvironment;
+}): void;
+/** Get the billing API URL for the currently configured environment. */
+declare function getConfiguredBillingApiUrl(): string;
+/** Get the current configured environment. */
+declare function getFloPayEnvironment(): FloPayEnvironment;
+
+/** Current SDK version. */
+declare const SDK_VERSION = "0.1.0";
+/** Billing API URL for staging environment. */
+declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
+/** Billing API URL for production environment. */
+declare const BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
+/** Default FloPay API base URL (used by @flopay/node). Alias for staging. */
+declare const DEFAULT_API_BASE_URL = "https://api.stage.flopay.com";
+/** Default billing API base URL. Alias for staging — prefer `resolveBillingApiUrl()`. */
+declare const BILLING_API_URL = "https://api.stage.flopay.com";
+/**
+ * Resolve the billing API URL from available configuration.
+ *
+ * Priority:
+ * 1. Explicit `billingApiUrl` (prop/param override)
+ * 2. `NEXT_PUBLIC_FLOPAY_ENV` environment variable (`'staging'` | `'production'`)
+ * 3. `configureFlopay()` global environment setting
+ * 4. Fallback: staging URL
+ *
+ * @example
+ * ```ts
+ * import { resolveBillingApiUrl } from '@flopay/shared';
+ *
+ * // Reads from env var or configureFlopay() — no args needed
+ * const url = resolveBillingApiUrl();
+ *
+ * // Explicit override takes priority
+ * const url = resolveBillingApiUrl('https://custom.example.com');
+ * ```
+ */
+declare function resolveBillingApiUrl(billingApiUrl?: string): string;
+/** Default API version header value. */
+declare const DEFAULT_API_VERSION = "2024-01-01";
+/** The default appearance applied when no custom appearance is provided. */
+declare const DEFAULT_APPEARANCE: FloPayAppearance;
+/** Flat theme — minimal borders and shadows. */
+declare const FLAT_APPEARANCE: FloPayAppearance;
+/** Night theme — dark background. */
+declare const NIGHT_APPEARANCE: FloPayAppearance;
+/** All supported element type identifiers. */
+declare const ELEMENT_TYPES: readonly ["payment", "card", "cardNumber", "cardExpiry", "cardCvc", "address"];
+declare const SUPPORTED_CARD_BRANDS: readonly ["visa", "mastercard", "mastercard_debit", "amex", "discover"];
+/** Country code to currency information mapping. */
+declare const CURRENCY_MAP: Record<string, CurrencyInfo>;
+/** Default currency info when country is unknown. */
+declare const DEFAULT_CURRENCY: CurrencyInfo;
+
+/** A single line item formatted for display in the checkout UI. */
+interface DisplayLineItem {
+    name: string;
+    quantity: number;
+    /** Price per unit in the session's currency (major units, e.g. 24.95). */
+    price: number;
+    /** Original price per unit before any discount (major units). */
+    originalPrice: number;
+}
+/** Computed display data for rendering an order summary. */
+interface CheckoutDisplayData {
+    /** Individual items/subscriptions with names, prices, and quantities. */
+    items: DisplayLineItem[];
+    /** ISO 4217 currency code (uppercase). */
+    currency: string;
+    /** Total amount due after discounts (major units, e.g. 24.95). */
+    total: number;
+    /** Sum of original prices before discounts (major units). */
+    originalTotal: number;
+    /** Total savings (originalTotal - total), clamped to >= 0. */
+    totalSave: number;
+    /** Discount percentage (0–100). */
+    discountPercent: number;
+}
+/**
+ * Builds display data from a `CheckoutSession` for rendering an order summary.
+ *
+ * Matches the display logic in checkout/CheckoutModal exactly:
+ * - Subscriptions are always shown
+ * - Items are hidden when the session has both subscriptions AND items
+ * - `overrideAmount` (when not null/undefined) is the discounted price
+ * - Plan name "4-WEEK PLAN" with price <= 1 is renamed to "7-DAY TRIAL: FULL ACCESS"
+ * - Discount percentage and savings are computed from the difference
+ *
+ * All amounts are in **major currency units** (dollars, not cents).
+ *
+ * @example
+ * ```ts
+ * import { buildCheckoutDisplayData } from '@flopay/shared';
+ *
+ * const display = buildCheckoutDisplayData(session);
+ * // display.items → [{ name: 'Starter', price: 24.95, originalPrice: 24.95, quantity: 1 }]
+ * // display.total → 24.95
+ * // display.currency → 'EUR'
+ * ```
+ */
+declare function buildCheckoutDisplayData(session: CheckoutSession): CheckoutDisplayData;
+
+/**
+ * Look up currency information by ISO 3166-1 alpha-2 country code.
+ * Falls back to USD when the country is not in the map.
+ */
+declare function getCurrencyByCountry(countryCode: string): CurrencyInfo;
+/** Returns `true` if the string looks like a Stripe publishable key. */
+declare function isValidPublishableKey(key: string): boolean;
+/** Returns `true` if the string looks like a Stripe secret key. */
+declare function isValidSecretKey(key: string): boolean;
+
+export { BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, type BillingProvider, CURRENCY_MAP, type CheckoutAccount, type CheckoutDisplayData, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutSession, type CheckoutSessionItem, type CheckoutSessionResult, type CheckoutSessionSubscription, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, type LineItem, type MountedElement, NIGHT_APPEARANCE, type NormalizedCheckoutSession, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, SUPPORTED_CARD_BRANDS, type TagsData, type TokenizedBody, type UpdateCustomerParams, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, configureFlopay, getConfiguredBillingApiUrl, getCurrencyByCountry, getFloPayEnvironment, isValidPublishableKey, isValidSecretKey, networkError, rateLimitError, resolveBillingApiUrl, validationError };