@flopay/js 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# @flopay/js
+
+Browser-side FloPay SDK. Provides `loadFloPay()` to initialize the SDK, a `FloPay` class for managing payment elements and confirmations, `PaymentAPI` for billing API calls, and `createCheckoutSession` for server-initiated checkout flows.
+
+Currently backed by Stripe via the `StripeAdapter`. The adapter pattern (`PaymentProviderAdapter` interface) allows swapping providers without changing consumer code.
+
+## Installation
+
+```bash
+pnpm add @flopay/js @stripe/stripe-js
+```
+
+`@stripe/stripe-js` is an optional peer dependency (required when using the Stripe adapter, which is currently the only adapter).
+
+## Quick Start
+
+### Initialize the SDK
+
+```ts
+import { loadFloPay } from '@flopay/js';
+
+const flopay = await loadFloPay('pk_test_...', {
+  billingApiUrl: 'https://billing.example.com', // optional, enables retrieveSession/retrieveUnifiedSession
+});
+```
+
+`loadFloPay` caches the instance -- calling it again with the same key returns the cached `FloPay` instance. The optional second argument accepts a `FloPayConfig` with `billingApiUrl`, `locale`, and `appearance`.
+
+### Create and Mount Elements
+
+```ts
+const elements = flopay.elements({
+  amount: 2999,       // in cents
+  currency: 'usd',
+});
+
+const cardElement = await elements.create('card');
+cardElement.mount(document.getElementById('card-container')!);
+```
+
+### Tokenize and Confirm Payment
+
+```ts
+// 1. Validate elements
+const { error: submitError } = await flopay.submitElements();
+if (submitError) throw submitError;
+
+// 2. Tokenize card into a PaymentMethod
+const { paymentMethodId, error } = await flopay.createPaymentMethod();
+if (error || !paymentMethodId) throw error;
+
+// 3. Confirm card payment with a client secret from your server
+const result = await flopay.confirmCardPayment({
+  clientSecret: 'pi_xxx_secret_yyy',
+  paymentMethodId,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+} else {
+  console.log('Payment status:', result.status);
+}
+```
+
+### PayPal Payment
+
+```ts
+const result = await flopay.confirmPayPalPayment({
+  billingApiUrl: 'https://billing.example.com',
+  sessionId: 'session_uuid',
+  email: 'user@example.com',
+  returnUrl: window.location.href,
+});
+
+// After redirect return, resume the payment:
+const resumed = await flopay.resumePayPalPayment();
+if (resumed) {
+  console.log('PayPal payment status:', resumed.status);
+}
+```
+
+### Retrieve a Session
+
+```ts
+// Using billingApiUrl from config (set at init time):
+const session = await flopay.retrieveSession('session_uuid');
+console.log(session.amount, session.currency, session.status);
+
+// Or pass billingApiUrl explicitly:
+const session2 = await flopay.retrieveSession('session_uuid', 'https://billing.example.com');
+
+// For provider-specific data (Stripe clientSecret, publishableKey, etc.):
+const unified = await flopay.retrieveUnifiedSession('session_uuid');
+console.log(unified.data.stripe?.clientSecret);
+```
+
+### PaymentAPI (Billing API Client)
+
+```ts
+import { PaymentAPI } from '@flopay/js';
+
+const api = new PaymentAPI('https://billing.example.com');
+
+// Fetch and normalize a checkout session
+const session = await api.getUnifiedCheckoutSession('session_uuid');
+// session.provider === 'stripe' | 'chargebee' | 'recurly'
+// session.data.session contains the normalized CheckoutSession
+
+// Create a PaymentIntent
+const intentResponse = await api.createPaymentIntent(
+  'session_uuid',
+  'user@example.com',
+  'pm_xxx',
+);
+
+// Process a tokenized payment
+const processResponse = await api.processPayment('user_id', {
+  sessionId: 'session_uuid',
+  tokenizedData: { id: 'pm_xxx', type: 'card' },
+  accountData: { userId: 'user_id', email: 'user@example.com', firstName: 'John', lastName: 'Doe' },
+});
+
+// Check for prior payments (saved card UX)
+const payments = await api.getPaymentsByEmail('user@example.com');
+```
+
+### createCheckoutSession
+
+```ts
+import { createCheckoutSession } from '@flopay/js';
+
+const result = 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' },
+});
+// On 201: browser redirects to checkout page
+// On 204: browser redirects to successUrl (payment method on file)
+```
+
+Use `createCheckoutSessionWithRetries` for automatic retry with exponential backoff on timeout errors.
+
+## API Reference
+
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `loadFloPay(publishableKey, options?)` | Initializes the SDK. Returns a `Promise<FloPay>`. Caches by key. |
+| `FloPay` | Main SDK class. Methods: `elements()`, `submitElements()`, `createPaymentMethod()`, `confirmCardPayment()`, `confirmPayment()`, `confirmPayPalPayment()`, `resumePayPalPayment()`, `retrieveSession()`, `retrieveUnifiedSession()`, `getRawProvider()`, `destroy()` |
+| `FloPayElements` | Element group manager. Methods: `create(type, options?)`, `getElement(type)`, `submit()`, `destroy()` |
+| `StripeAdapter` | `PaymentProviderAdapter` implementation for Stripe |
+| `PaymentAPI` | Billing API client. Methods: `getCheckoutSession()`, `getUnifiedCheckoutSession()`, `processPayment()`, `createPaymentIntent()`, `createSetupIntent()`, `getPaymentsByEmail()` |
+| `createCheckoutSession(options)` | Creates a checkout session and redirects. Returns `CheckoutSessionResult`. |
+| `createCheckoutSessionWithRetries(options)` | Same as above with automatic retries (default 3, exponential backoff). |
+
+### FloPay Class Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `elements(options?)` | `FloPayElements` | Creates a new elements group. Destroys previous group. |
+| `submitElements()` | `Promise<{ error? }>` | Validates all mounted elements |
+| `createPaymentMethod()` | `Promise<CreatePaymentMethodResult>` | Tokenizes card fields into a `pm_xxx` ID. Auto-detects split fields vs unified PaymentElement. |
+| `confirmCardPayment(params)` | `Promise<ConfirmCardPaymentResult>` | Confirms with `clientSecret` + `paymentMethodId`. Handles 3DS. |
+| `confirmPayment(params)` | `Promise<PaymentResult>` | Confirms using mounted elements + `clientSecret` |
+| `confirmPayPalPayment(params)` | `Promise<ConfirmCardPaymentResult>` | Full PayPal flow: create PM -> create intent -> confirm/redirect |
+| `resumePayPalPayment()` | `Promise<ConfirmCardPaymentResult \| null>` | Resumes after PayPal redirect. Returns `null` if no PayPal params in URL. |
+| `retrieveSession(sessionId, billingApiUrl?)` | `Promise<CheckoutSession>` | Retrieves a checkout session by ID via `GET /v1/checkouts/sessions/{id}`. Uses `billingApiUrl` from config or the optional second argument. |
+| `retrieveUnifiedSession(sessionId, billingApiUrl?)` | `Promise<NormalizedCheckoutSession>` | Retrieves and normalizes a checkout session, including provider-specific data (Stripe `clientSecret`/`publishableKey`, etc.). |
+| `getRawProvider()` | `unknown` | Returns the raw underlying provider instance (e.g. Stripe object) |
+| `destroy()` | `void` | Tears down elements and provider |
+
+### Supported Element Types
+
+- `payment` -- Unified PaymentElement (cards, wallets, etc.)
+- `card` -- Combined card input (number + expiry + CVC)
+- `cardNumber` -- Card number field (for split card forms)
+- `cardExpiry` -- Card expiry field
+- `cardCvc` -- Card CVC field
+- `address` -- Address input element