@tagadapay/headless-sdk 1.8.0-rc.0 → 1.8.0

package/README.md

@@ -1 +1,216 @@
-test
+# @tagadapay/headless-sdk
+
+Use TagadaPay as a **headless checkout and CRM backend** from any website — React, Vue, vanilla JS, or plain HTML. Zero runtime dependencies in core.
+
+## Install
+
+```bash
+npm install @tagadapay/headless-sdk
+# Optional: for card tokenization
+npm install @tagadapay/core-js
+```
+
+## Quick Start (Vanilla JS)
+
+```typescript
+import { createHeadlessClient } from '@tagadapay/headless-sdk';
+
+const tagada = createHeadlessClient({
+  storeId: 'store_abc123',
+  environment: 'production',
+});
+
+// Load checkout session
+const session = await tagada.checkout.loadSession(checkoutToken, sessionToken);
+
+// Set customer info (stored in memory, sent with address)
+await tagada.checkout.updateCustomer(session.id, {
+  email: 'john@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+// Set address — customer fields are included automatically
+await tagada.checkout.updateAddress(session.id, {
+  shippingAddress: { line1: '10 Rue de la Paix', city: 'Paris', postalCode: '75002', country: 'FR' },
+});
+
+// Tokenize card + pay with automatic 3DS / redirect handling
+const { tagadaToken } = await tagada.payment.tokenizeCard({
+  cardNumber: '4242424242424242',
+  expiryDate: '12/28',
+  cvc: '123',
+});
+
+const result = await tagada.payment.processPayment({
+  checkoutSessionId: session.id,
+  tagadaToken,
+});
+
+if (result.status === 'succeeded') {
+  console.log('Payment succeeded!', result.order);
+} else if (result.status === 'requires_redirect') {
+  // SDK handles this automatically in React; in vanilla JS, redirect manually:
+  window.location.href = result.redirectUrl;
+} else if (result.status === 'failed') {
+  console.error(result.error);
+}
+```
+
+## Quick Start (React)
+
+```tsx
+import { TagadaHeadlessProvider, useCheckout, usePayment } from '@tagadapay/headless-sdk/react';
+
+function App() {
+  return (
+    <TagadaHeadlessProvider storeId="store_abc123" environment="production">
+      <CheckoutPage />
+    </TagadaHeadlessProvider>
+  );
+}
+
+function CheckoutPage() {
+  const { session, updateCustomer, updateAddress } = useCheckout(checkoutToken, sessionToken);
+  const { processPayment, isProcessing, tokenizeCard } = usePayment({
+    onPaymentSuccess: (result) => router.push('/thank-you'),
+    onPaymentFailed: (result) => alert(result.error),
+  });
+
+  const handlePay = async () => {
+    // Customer + address (single atomic API call under the hood)
+    await updateCustomer({ email, firstName, lastName });
+    await updateAddress({ shippingAddress: { line1, city, postalCode, country } });
+
+    // Tokenize + pay — 3DS redirects and polling are handled automatically
+    const { tagadaToken } = await tokenizeCard({ cardNumber, expiryDate, cvc });
+    await processPayment({ checkoutSessionId: session.id, tagadaToken });
+    // onPaymentSuccess / onPaymentFailed callbacks fire automatically
+  };
+
+  return <button onClick={handlePay} disabled={isProcessing}>Pay Now</button>;
+}
+```
+
+## Payment Flow
+
+`processPayment()` handles the full payment lifecycle automatically:
+
+1. **Tokenize** → creates a payment instrument from the card
+2. **Pay** → submits payment to the processor
+3. **3DS / Redirect** → if the bank requires authentication, the SDK redirects the user and resumes automatically on return
+4. **Poll** → waits for async processing to complete
+5. **Result** → returns a typed `ProcessPaymentResult`
+
+The return type is a discriminated union:
+
+| Status | Meaning |
+|--------|---------|
+| `succeeded` | Payment confirmed. Show success screen. |
+| `requires_redirect` | User must visit a URL (3DS, bank auth). Auto-handled in React. |
+| `failed` | Payment declined or errored. `result.error` has details. |
+| `pending` | Still processing (rare — polling timed out). |
+
+## Address Handling
+
+The SDK handles both **shipped** and **digital** products:
+
+```typescript
+// Shipped product — billing defaults to shipping
+await tagada.checkout.updateAddress(sessionId, {
+  shippingAddress: { line1: '...', city: '...', country: 'FR' },
+});
+
+// Digital product — billing only, no shipping needed
+await tagada.checkout.updateAddress(sessionId, {
+  billingAddress: { country: 'FR' },
+});
+
+// Separate billing and shipping
+await tagada.checkout.updateAddress(sessionId, {
+  shippingAddress: { line1: '...', city: '...', country: 'FR' },
+  billingAddress: { line1: '...', city: '...', country: 'DE' },
+});
+
+// Or use the combined method
+await tagada.checkout.updateCustomerAndAddress(sessionId, {
+  customer: { email: 'john@example.com', firstName: 'John', lastName: 'Doe' },
+  shippingAddress: { line1: '...', city: '...', country: 'FR' },
+});
+```
+
+## Funnel Navigation
+
+Send a shopper into a TagadaPay funnel using the cart from the loaded checkout
+session — same flow as the WooCommerce / Shopify plugins, in one call.
+
+```typescript
+const tagada = createHeadlessClient({
+  storeId: 'store_abc123',
+  accountId: 'acc_abc123', // required for funnel.navigate()
+  environment: 'production',
+});
+
+// Load (or create) a checkout session so the SDK has a cart.
+await tagada.checkout.loadSession(checkoutToken, sessionToken);
+
+// Get a funnel URL — caller decides how to redirect (SPA-friendly).
+const { url } = await tagada.funnel.navigate({
+  funnelId: 'fnlv2_abc123',
+  stepId:   'step_abc123',
+  returnUrl: 'https://merchant.com/thank-you',
+});
+
+window.location.assign(url);
+```
+
+`funnel.navigate()` bootstraps an anonymous CMS session on first call and
+caches it for subsequent calls in the same page. The cart, currency, customer
+email, and promotion code are sourced from the loaded `CheckoutSession`.
+
+## Modules
+
+| Module | What it does |
+|--------|-------------|
+| `tagada.checkout` | Session management — load, update cart, promo codes, shipping |
+| `tagada.payment` | Full payment lifecycle — APMs, tokenize, 3DS, pay, poll, express checkout |
+| `tagada.offers` | Upsells & order bumps — preview, pay, post-purchase accept/decline |
+| `tagada.customer` | CRM data — profile, orders, subscriptions |
+| `tagada.catalog` | Product browsing — list products, variants, prices |
+| `tagada.funnel` | Funnel navigation — bootstrap session and redirect into a funnel step |
+
+## CDN Usage
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk/dist/tagada-headless.min.js"></script>
+<script>
+  const tagada = TagadaHeadless.create({ storeId: 'store_abc123' });
+</script>
+```
+
+## Example
+
+A complete React checkout app is available as a live demo and open-source reference:
+
+- **Live demo**: [headless-react-eta.vercel.app](https://headless-react-eta.vercel.app)
+- **Source code**: [github.com/TagadaPay/examples/tree/main/headless-react](https://github.com/TagadaPay/examples/tree/main/headless-react)
+
+## Architecture
+
+- **Zero dependencies** in core — native `fetch`, no axios
+- **Tree-shakeable ESM** — unused modules are eliminated by bundlers
+- **Framework-agnostic core** + thin React hooks layer
+- **TypeScript first** — full type coverage, JSDoc on every method
+- **Optional `@tagadapay/core-js`** peer — only needed for client-side card tokenization
+- **Automatic 3DS** — handles redirects, iframe challenges, and polling out of the box
+
+## Package Exports
+
+| Import path | What you get |
+|------------|--------------|
+| `@tagadapay/headless-sdk` | Core client + all modules |
+| `@tagadapay/headless-sdk/react` | React hooks + provider |
+
+## License
+
+MIT

package/dist/core/client.d.ts

@@ -0,0 +1,68 @@
+import { CheckoutModule } from './modules/checkout.js';
+import { PaymentModule } from './modules/payment.js';
+import { OffersModule } from './modules/offers.js';
+import { CustomerModule } from './modules/customer.js';
+import { CatalogModule } from './modules/catalog.js';
+import { FunnelModule } from './modules/funnel.js';
+import { RxModule } from './modules/rx.js';
+import type { HeadlessConfig } from './types.js';
+/**
+ * Main entry point for the TagadaPay Headless SDK.
+ *
+ * Composes all domain modules (checkout, payment, offers, customer, catalog)
+ * over a single lightweight HTTP client built on native fetch.
+ *
+ * **PCI DSS notice:** Card tokenization via `payment.tokenizeCard()` sends
+ * card data directly to Basis Theory — it never reaches TagadaPay servers.
+ * However, because card data passes through your JavaScript environment,
+ * merchants using this SDK are responsible for PCI DSS SAQ-A-EP compliance.
+ * See https://docs.tagada.io/developer-tools/headless-sdk/pci-compliance
+ */
+export declare class HeadlessClient {
+    readonly config: Required<Pick<HeadlessConfig, 'storeId' | 'environment'>> & HeadlessConfig;
+    private readonly http;
+    /** Shared session token used by all modules for authenticated API calls. */
+    private _sessionToken;
+    /** Checkout session management -- load, update cart, apply promos, shipping. */
+    readonly checkout: CheckoutModule;
+    /** Payment processing -- setup config, APMs, tokenize, pay, 3DS, poll. */
+    readonly payment: PaymentModule;
+    /** Offers -- preview, pay, accept/decline upsells and order bumps. */
+    readonly offers: OffersModule;
+    /** Customer data -- profile, orders, subscriptions. */
+    readonly customer: CustomerModule;
+    /** Product catalog -- list products, variants, and prices. */
+    readonly catalog: CatalogModule;
+    /**
+     * Funnel navigation -- bootstrap an anonymous CMS session and produce a
+     * redirect URL into a funnel step using the currently loaded checkout cart.
+     * Requires `config.accountId`.
+     */
+    readonly funnel: FunnelModule;
+    /**
+     * Tagada Rx -- clinical case submission and lookup for telehealth
+     * storefronts. Active only on stores whose merchant has paid the
+     * Tagada Rx setup fee and configured a clinical network.
+     */
+    readonly rx: RxModule;
+    constructor(config: HeadlessConfig);
+    /** Manually set the session token (e.g. from URL params on page load). */
+    setSessionToken(token: string): void;
+}
+/**
+ * Create a new HeadlessClient instance.
+ *
+ * @example
+ * ```ts
+ * import { createHeadlessClient } from '@tagadapay/headless-sdk';
+ *
+ * const tagada = createHeadlessClient({
+ *   storeId: 'store_abc123',
+ *   environment: 'production',
+ * });
+ *
+ * const session = await tagada.checkout.loadSession(checkoutToken);
+ * ```
+ */
+export declare function createHeadlessClient(config: HeadlessConfig): HeadlessClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.js

@@ -0,0 +1,71 @@
+import { HttpClient } from './http.js';
+import { CheckoutModule } from './modules/checkout.js';
+import { PaymentModule } from './modules/payment.js';
+import { OffersModule } from './modules/offers.js';
+import { CustomerModule } from './modules/customer.js';
+import { CatalogModule } from './modules/catalog.js';
+import { FunnelModule } from './modules/funnel.js';
+import { RxModule } from './modules/rx.js';
+/**
+ * Main entry point for the TagadaPay Headless SDK.
+ *
+ * Composes all domain modules (checkout, payment, offers, customer, catalog)
+ * over a single lightweight HTTP client built on native fetch.
+ *
+ * **PCI DSS notice:** Card tokenization via `payment.tokenizeCard()` sends
+ * card data directly to Basis Theory — it never reaches TagadaPay servers.
+ * However, because card data passes through your JavaScript environment,
+ * merchants using this SDK are responsible for PCI DSS SAQ-A-EP compliance.
+ * See https://docs.tagada.io/developer-tools/headless-sdk/pci-compliance
+ */
+export class HeadlessClient {
+    constructor(config) {
+        const environment = config.environment ?? 'production';
+        const baseUrl = HttpClient.resolveBaseUrl(environment, config.baseUrl);
+        this.config = {
+            ...config,
+            environment,
+            baseUrl,
+            timeout: config.timeout ?? 30000,
+        };
+        this.http = new HttpClient({
+            baseUrl,
+            timeout: this.config.timeout,
+            apiKey: config.apiKey,
+            getToken: () => this._sessionToken,
+        });
+        const setToken = (token) => {
+            this._sessionToken = token;
+        };
+        this.checkout = new CheckoutModule(this.http, this.config.storeId, setToken);
+        this.payment = new PaymentModule(this.http, this.config.storeId, environment);
+        this.offers = new OffersModule(this.http, this.config.storeId, this.payment);
+        this.customer = new CustomerModule(this.http, this.config.storeId);
+        this.catalog = new CatalogModule(this.http, this.config.storeId);
+        this.funnel = new FunnelModule(this.http, this.config.storeId, this.checkout, this.config.accountId);
+        this.rx = new RxModule(this.http);
+    }
+    /** Manually set the session token (e.g. from URL params on page load). */
+    setSessionToken(token) {
+        this._sessionToken = token;
+    }
+}
+/**
+ * Create a new HeadlessClient instance.
+ *
+ * @example
+ * ```ts
+ * import { createHeadlessClient } from '@tagadapay/headless-sdk';
+ *
+ * const tagada = createHeadlessClient({
+ *   storeId: 'store_abc123',
+ *   environment: 'production',
+ * });
+ *
+ * const session = await tagada.checkout.loadSession(checkoutToken);
+ * ```
+ */
+export function createHeadlessClient(config) {
+    return new HeadlessClient(config);
+}
+//# sourceMappingURL=client.js.map

package/dist/core/errors.d.ts

@@ -0,0 +1,46 @@
+/** Base error for all TagadaPay headless SDK errors. */
+export declare class TagadaError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+}
+/** Thrown when the API returns 401/403. */
+export declare class TagadaAuthError extends TagadaError {
+    constructor(message?: string);
+}
+/** Thrown when the API returns 422 with validation errors. */
+export declare class TagadaValidationError extends TagadaError {
+    readonly errors: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message: string, errors?: Array<{
+        field: string;
+        message: string;
+    }>);
+}
+/** Thrown when a resource is not found (404). */
+export declare class TagadaNotFoundError extends TagadaError {
+    constructor(resource: string, id: string);
+}
+/** Thrown when the API returns 429. */
+export declare class TagadaRateLimitError extends TagadaError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs?: number);
+}
+/** Thrown when a payment fails or requires action. */
+export declare class TagadaPaymentError extends TagadaError {
+    readonly paymentId?: string;
+    readonly requireAction?: string;
+    constructor(message: string, opts?: {
+        paymentId?: string;
+        requireAction?: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** Thrown on network / fetch failures. */
+export declare class TagadaNetworkError extends TagadaError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.js

@@ -0,0 +1,57 @@
+/** Base error for all TagadaPay headless SDK errors. */
+export class TagadaError extends Error {
+    constructor(message, code, statusCode, details) {
+        super(message);
+        this.name = 'TagadaError';
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}
+/** Thrown when the API returns 401/403. */
+export class TagadaAuthError extends TagadaError {
+    constructor(message = 'Authentication failed. Check your API key or checkout token.') {
+        super(message, 'auth_error', 401);
+        this.name = 'TagadaAuthError';
+    }
+}
+/** Thrown when the API returns 422 with validation errors. */
+export class TagadaValidationError extends TagadaError {
+    constructor(message, errors = []) {
+        super(message, 'validation_error', 422, { errors });
+        this.name = 'TagadaValidationError';
+        this.errors = errors;
+    }
+}
+/** Thrown when a resource is not found (404). */
+export class TagadaNotFoundError extends TagadaError {
+    constructor(resource, id) {
+        super(`${resource} "${id}" not found.`, 'not_found', 404);
+        this.name = 'TagadaNotFoundError';
+    }
+}
+/** Thrown when the API returns 429. */
+export class TagadaRateLimitError extends TagadaError {
+    constructor(retryAfterMs = 1000) {
+        super(`Rate limited. Retry after ${retryAfterMs}ms.`, 'rate_limit', 429);
+        this.name = 'TagadaRateLimitError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** Thrown when a payment fails or requires action. */
+export class TagadaPaymentError extends TagadaError {
+    constructor(message, opts) {
+        super(message, 'payment_error', undefined, opts?.details);
+        this.name = 'TagadaPaymentError';
+        this.paymentId = opts?.paymentId;
+        this.requireAction = opts?.requireAction;
+    }
+}
+/** Thrown on network / fetch failures. */
+export class TagadaNetworkError extends TagadaError {
+    constructor(message = 'Network request failed. Check your connection.') {
+        super(message, 'network_error');
+        this.name = 'TagadaNetworkError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/helpers/autocomplete.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Google Places Autocomplete — script injection + address extraction.
+ * Works standalone (no external dependencies beyond the Google Maps JS API).
+ */
+declare global {
+    interface Window {
+        google?: {
+            maps?: {
+                places?: {
+                    AutocompleteService: new () => any;
+                    PlacesService: new (el: any) => any;
+                    PlacesServiceStatus: {
+                        OK: string;
+                        ZERO_RESULTS: string;
+                    };
+                };
+                Map: new (el: HTMLElement) => any;
+            };
+        };
+    }
+}
+export interface GooglePrediction {
+    place_id: string;
+    description: string;
+    structured_formatting?: {
+        main_text: string;
+        secondary_text: string;
+    };
+}
+export interface GooglePlaceDetails {
+    place_id: string;
+    formatted_address: string;
+    address_components: Array<{
+        long_name: string;
+        short_name: string;
+        types: string[];
+    }>;
+    geometry?: {
+        location: {
+            lat: number;
+            lng: number;
+        };
+    };
+}
+export interface ExtractedAddress {
+    subpremise: string;
+    streetNumber: string;
+    route: string;
+    locality: string;
+    administrativeAreaLevel1: string;
+    administrativeAreaLevel1Long: string;
+    administrativeAreaLevel2: string;
+    administrativeAreaLevel2Long: string;
+    country: string;
+    postalCode: string;
+    fullStreetAddress: string;
+}
+export interface FormattedAddress {
+    address1: string;
+    city: string;
+    country: string;
+    state: string;
+    postal: string;
+}
+/**
+ * Inject the Google Maps JS SDK into the page (idempotent).
+ * Resolves once `window.google.maps.places` is available.
+ */
+export declare function loadGoogleMapsScript(apiKey: string, opts?: {
+    language?: string;
+    region?: string;
+    version?: string;
+}): Promise<void>;
+export declare class GoogleAutocompleteCore {
+    /** Search for address predictions. */
+    static searchPlaces(input: string, options?: {
+        types?: string[];
+        componentRestrictions?: {
+            country: string;
+        };
+    }): Promise<GooglePrediction[]>;
+    /** Get full place details by place_id. */
+    static getPlaceDetails(placeId: string): Promise<GooglePlaceDetails | null>;
+    /** Extract structured address fields from a Google PlaceDetails result. */
+    static extractAddressComponents(place: GooglePlaceDetails): ExtractedAddress;
+    /** Shorthand: extract into the flat shape used by address forms. */
+    static extractFormattedAddress(place: GooglePlaceDetails): FormattedAddress;
+}
+//# sourceMappingURL=autocomplete.d.ts.map