Helpers

function configureFlopay(config: { environment: FloPayEnvironment }): void

import { configureFlopay } from '@flopay/shared';

// In production
configureFlopay({ environment: 'production' });

// In staging/development
configureFlopay({ environment: 'staging' });

function resolveBillingApiUrl(billingApiUrl?: string): string

import { resolveBillingApiUrl } from '@flopay/shared';

// No args — reads from configureFlopay() or falls back to staging
const url = resolveBillingApiUrl();

// Explicit override
const url = resolveBillingApiUrl('https://custom.example.com');

function buildCheckoutDisplayData(
  session: CheckoutSession,
  options?: BuildCheckoutDisplayDataOptions,
): CheckoutDisplayData

import { buildCheckoutDisplayData } from '@flopay/shared';

const display = buildCheckoutDisplayData(session);

display.items;          // [{ name: 'Starter', price: 24.95, originalPrice: 24.95, quantity: 1 }]
display.currency;       // 'EUR'
display.total;          // 24.95
display.originalTotal;  // 24.95
display.totalSave;      // 0
display.discountPercent; // 0

// Default -- items show alongside subscriptions
buildCheckoutDisplayData(session);

// Legacy behavior -- hide bundled items when the session has subscriptions too
buildCheckoutDisplayData(session, { hideBundledItems: true });

import { buildCheckoutDisplayData } from '@flopay/shared';
import { useCheckout } from '@flopay/react';

function OrderSummary() {
  const { session } = useCheckout();
  if (!session) return null;

  const { items, currency, total, totalSave, discountPercent } = buildCheckoutDisplayData(session);
  const fmt = (n: number) =>
    new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(n);

  return (
    <div>
      {items.map((item, i) => (
        <div key={i}>
          <span>{item.name} (x{item.quantity})</span>
          <span>{fmt(item.originalPrice)}</span>
        </div>
      ))}
      {totalSave > 0 && <div>{discountPercent}% OFF — you save {fmt(totalSave)}</div>}
      <div>Total: {fmt(total)}</div>
    </div>
  );
}

function getCurrencyByCountry(countryCode: string): CurrencyInfo

import { getCurrencyByCountry } from '@flopay/shared';

getCurrencyByCountry('DE');
// { currency: 'EUR', symbol: '\u20ac', country: 'Germany', countryCode: 'DE', tax: 1 }

getCurrencyByCountry('US');
// { currency: 'USD', symbol: '$', country: 'United States', countryCode: 'US', tax: 0 }

getCurrencyByCountry('XX');
// Falls back to DEFAULT_CURRENCY (USD)

function resolveAVSConfig(enableAVS?: boolean | AVSFieldConfig): AVSFieldConfig | null

import { resolveAVSConfig } from '@flopay/shared';

resolveAVSConfig(true);                 // { country: true, postal_code: true }
resolveAVSConfig(false);                // null
resolveAVSConfig({ country: true });    // { country: true }

function isAVSFieldVisible(
  field: boolean | string[] | undefined,
  country: string,
): boolean

import { isAVSFieldVisible } from '@flopay/shared';

isAVSFieldVisible(true, 'XX');              // true (always visible)
isAVSFieldVisible(false, 'US');             // false
isAVSFieldVisible(undefined, 'US');         // false
isAVSFieldVisible(['US', 'CA'], 'us');      // true
isAVSFieldVisible(['US', 'CA'], 'GB');      // false

function isAVSEnabled(enableAVS?: boolean | AVSFieldConfig): boolean

import { isAVSEnabled } from '@flopay/shared';

isAVSEnabled(true);                  // true
isAVSEnabled(false);                 // false
isAVSEnabled(undefined);             // false
isAVSEnabled({});                    // false  (no fields configured)
isAVSEnabled({ country: true });     // true
isAVSEnabled({ city: ['US'] });      // true

function getStateOptions(country: string): StateOption[] | null

import { getStateOptions } from '@flopay/shared';

getStateOptions('US');   // [{ code: 'AL', name: 'Alabama' }, …]  (51 entries incl. DC)
getStateOptions('CA');   // [{ code: 'AB', name: 'Alberta' }, …]   (13 entries)
getStateOptions('GB');   // null

function getStateLabel(countryCode: string): string

function getStateFromPostalCode(
  country: string,
  postalCode: string,
): string | null

import { getStateFromPostalCode } from '@flopay/shared';

getStateFromPostalCode('US', '90210');      // 'CA'
getStateFromPostalCode('US', '10001-9999'); // 'NY' (ZIP+4)
getStateFromPostalCode('CA', 'M5V 2T6');    // 'ON'
getStateFromPostalCode('CA', 'm5v2t6');     // 'ON' (case-insensitive, compact)
getStateFromPostalCode('GB', 'SW1A 1AA');   // null
getStateFromPostalCode('US', '71500');      // null (unmapped 3-digit prefix)

function getPostalCodeLabel(countryCode: string): string

function getCountryByCode(code: string): CountryOption | undefined

import { getCountryByCode } from '@flopay/shared';

getCountryByCode('DE'); // { code: 'DE', name: 'Germany', flag: '🇩🇪' }
getCountryByCode('XX'); // undefined

function isValidPublishableKey(key: string): boolean

import { isValidPublishableKey } from '@flopay/shared';

isValidPublishableKey('pk_test_abc123');  // true
isValidPublishableKey('pk_live_XYZ789'); // true
isValidPublishableKey('sk_test_abc123'); // false
isValidPublishableKey('invalid');        // false

function isValidSecretKey(key: string): boolean

import { isValidSecretKey } from '@flopay/shared';

isValidSecretKey('sk_test_abc123');  // true
isValidSecretKey('sk_live_XYZ789'); // true
isValidSecretKey('pk_test_abc123'); // false