@tagadapay/headless-sdk 1.3.2 → 1.5.0

package/README.md

@@ -21,19 +21,40 @@ const tagada = createHeadlessClient({
 });
 
 // Load checkout session
-const session = await tagada.checkout.loadSession(checkoutToken);
+const session = await tagada.checkout.loadSession(checkoutToken, sessionToken);
 
-// Tokenize card + pay
+// 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.pay({
+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)
@@ -50,19 +71,74 @@ function App() {
 }
 
 function CheckoutPage() {
-  const { session, isLoading } = useCheckout(checkoutToken);
-  const { pay, isProcessing, tokenizeCard } = usePayment();
+  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 });
-    const result = await pay({ checkoutSessionId: session.id, tagadaToken });
-    if (result.payment.status === 'succeeded') router.push('/thank-you');
+    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' },
+});
+```
+
 ## Modules
 
 | Module | What it does |
@@ -96,6 +172,7 @@ A complete React checkout app is available as a live demo and open-source refere
 - **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
 

package/dist/core/client.d.ts

@@ -9,6 +9,12 @@ import type { HeadlessConfig } from './types.js';
  *
  * 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;

package/dist/core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,aAAa,CAAC,CAAC,GAAG,cAAc,CAAC;IAE5F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAElC,4EAA4E;IAC5E,OAAO,CAAC,aAAa,CAAqB;IAE1C,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBAEpB,MAAM,EAAE,cAAc;IA6BlC,0EAA0E;IAC1E,eAAe,CAAC,KAAK,EAAE,MAAM;CAG9B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAE3E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,aAAa,CAAC,CAAC,GAAG,cAAc,CAAC;IAE5F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAElC,4EAA4E;IAC5E,OAAO,CAAC,aAAa,CAAqB;IAE1C,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBAEpB,MAAM,EAAE,cAAc;IA6BlC,0EAA0E;IAC1E,eAAe,CAAC,KAAK,EAAE,MAAM;CAG9B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAE3E"}

package/dist/core/client.js

@@ -9,6 +9,12 @@ import { CatalogModule } from './modules/catalog.js';
  *
  * 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) {

package/dist/core/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAuBzB,YAAY,MAAsB;QAChC,MAAM,WAAW,GAAgB,MAAM,CAAC,WAAW,IAAI,YAAY,CAAC;QACpE,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAEvE,IAAI,CAAC,MAAM,GAAG;YACZ,GAAG,MAAM;YACT,WAAW;YACX,OAAO;YACP,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAM;SAClC,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC;YACzB,OAAO;YACP,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAQ;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa;SACnC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,EAAE;YACjC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC7B,CAAC,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC7E,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC9E,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/D,IAAI,CAAC,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnE,CAAC;IAED,0EAA0E;IAC1E,eAAe,CAAC,KAAa;QAC3B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB;IACzD,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,cAAc;IAuBzB,YAAY,MAAsB;QAChC,MAAM,WAAW,GAAgB,MAAM,CAAC,WAAW,IAAI,YAAY,CAAC;QACpE,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAEvE,IAAI,CAAC,MAAM,GAAG;YACZ,GAAG,MAAM;YACT,WAAW;YACX,OAAO;YACP,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAM;SAClC,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC;YACzB,OAAO;YACP,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAQ;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa;SACnC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,EAAE;YACjC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC7B,CAAC,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC7E,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC9E,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/D,IAAI,CAAC,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnE,CAAC;IAED,0EAA0E;IAC1E,eAAe,CAAC,KAAa;QAC3B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB;IACzD,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/dist/core/http.js

@@ -1,7 +1,7 @@
 import { TagadaError, TagadaAuthError, TagadaValidationError, TagadaNotFoundError, TagadaRateLimitError, TagadaNetworkError, } from './errors.js';
 const BASE_URLS = {
-    production: 'https://app.tagadapay.com',
-    development: 'https://app.dev.tagadapay.com',
+    production: 'https://api.tagada.io',
+    development: 'https://api.tagada.dev',
     local: 'http://localhost:3000',
 };
 /**

package/dist/core/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -8,5 +8,5 @@ export { HttpClient } from './http.js';
 export { TagadaError, TagadaAuthError, TagadaValidationError, TagadaNotFoundError, TagadaRateLimitError, TagadaPaymentError, TagadaNetworkError, } from './errors.js';
 export { GoogleAutocompleteCore, loadGoogleMapsScript, ISODataCore, AVAILABLE_LANGUAGES, CurrencyUtils, formatMoney, ensureGeoDataLoaded, getCountries, getStatesForCountry, isLanguageLoaded, } from './helpers/index.js';
 export type { GooglePrediction, GooglePlaceDetails, ExtractedAddress, FormattedAddress, SupportedLanguage, ISOCountry, ISORegion, Country, State, Currency, } from './helpers/index.js';
-export type { Environment, HeadlessConfig, HttpRequestOptions, LineItem, CheckoutSession, CheckoutLineItem, CheckoutTotals, CheckoutCustomer, Address, ShippingRate, PaymentMethodConfig, PaymentSetupConfig, ExpressMethod, ExpressMethods, StoreConfig, PayResult, PayOptions, PayDirectOptions, CreateInstrumentOptions, PaymentInstrument, ThreedsSession, PaymentStatus, Offer, OfferLineItem, OfferPreview, OfferPreviewItem, OfferPayResult, Customer, Order, OrderItem, Subscription, CatalogProduct, CatalogVariant, CatalogPrice, CurrencyOption, } from './types.js';
+export type { Environment, HeadlessConfig, HttpRequestOptions, LineItem, CheckoutSession, CheckoutLineItem, CheckoutTotals, CheckoutCustomer, Address, ShippingRate, PaymentMethodConfig, PaymentSetupConfig, ExpressMethod, ExpressMethods, StoreConfig, PayResult, PayOptions, PayDirectOptions, ProcessPaymentOptions, ProcessPaymentResult, CreateInstrumentOptions, PaymentInstrument, ThreedsSession, PaymentStatus, Offer, OfferLineItem, OfferPreview, OfferPreviewItem, OfferPayResult, Customer, Order, OrderItem, Subscription, CatalogProduct, CatalogVariant, CatalogPrice, CurrencyOption, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EACL,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,OAAO,EACP,KAAK,EACL,QAAQ,GACT,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,WAAW,EACX,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,KAAK,EACL,SAAS,EACT,YAAY,EACZ,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EACL,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,OAAO,EACP,KAAK,EACL,QAAQ,GACT,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,WAAW,EACX,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,KAAK,EACL,SAAS,EACT,YAAY,EACZ,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/core/modules/checkout.d.ts

@@ -1,27 +1,64 @@
 import type { HttpClient } from '../http.js';
 import type { CheckoutSession, LineItem, ShippingRate, Address, CheckoutCustomer } from '../types.js';
 /**
- * Manages checkout sessions -- load, update cart, apply promo codes, handle shipping.
+ * Result returned by `updateCart()`. Mirrors the
+ * `POST /checkout-sessions/:id/line-items` payload (mutation stats, NOT
+ * a refreshed session). Call `loadSession()` to get an updated session.
+ */
+export interface UpdateCartResult {
+    success: boolean;
+    /** Number of existing line items updated. */
+    updated: number;
+    /** Number of new line items created. */
+    created: number;
+    /** Total number of line items in the cart after the mutation. */
+    total: number;
+}
+/**
+ * Manages checkout sessions — load, update cart, apply promo codes, handle shipping.
+ *
+ * Works for both **shipped** and **digital** products:
  *
- * All methods talk to the TagadaPay REST API and return typed data.
- * No local state is kept; the server is the source of truth.
+ * **Shipped products** (physical goods):
+ * ```
+ * updateCustomer(id, { email, firstName, lastName })
+ * updateAddress(id, { shippingAddress: { line1, city, ... } })
+ * getShippingRates(id)
+ * selectShippingRate(id, rateId)
+ * ```
+ *
+ * **Digital products** (no shipping needed):
+ * ```
+ * updateCustomer(id, { email, firstName, lastName })
+ * updateAddress(id, { billingAddress: { line1, city, country } })
+ * // Skip shipping rates — go straight to payment
+ * ```
  */
 export declare class CheckoutModule {
     private readonly http;
     private readonly storeId;
     private readonly onTokenChange?;
     private sessionToken;
+    private customerEmail;
+    private customerFirstName;
+    private customerLastName;
+    private customerPhone;
     constructor(http: HttpClient, storeId: string, onTokenChange?: ((token: string) => void) | undefined);
     /**
      * Load an existing checkout session by its checkout token.
      *
      * @param checkoutToken The checkout token (from URL param `checkoutToken`).
      * @param sessionToken The JWT session token (from URL param `token`). Required for auth.
+     * @param opts.currency Optional presentment currency override (e.g. 'EUR').
+     *   Only applied when the session has no currency set yet (first load).
+     *   Once set, currency is locked to the session and this param is ignored.
      *
-     * Both values come from the redirect URL returned by `createSession()`.
+     * Both `checkoutToken` and `sessionToken` come from the redirect URL returned by `createSession()`.
      * Example URL: `/checkout?checkoutToken=abc123&token=eyJ...`
      */
-    loadSession(checkoutToken: string, sessionToken?: string): Promise<CheckoutSession>;
+    loadSession(checkoutToken: string, sessionToken?: string, opts?: {
+        currency?: string;
+    }): Promise<CheckoutSession>;
     /**
      * Create a new checkout session.
      *
@@ -41,34 +78,98 @@ export declare class CheckoutModule {
         sessionToken: string;
         customerId: string;
     }>;
-    /** Replace the cart items for an existing session. */
-    updateCart(sessionId: string, items: LineItem[]): Promise<CheckoutSession>;
     /**
-     * Update customer + address information on the session.
-     * Uses the combined endpoint with `partial: true` so missing fields are tolerated.
+     * Replace the cart items for an existing session.
+     *
+     * Returns a server-side mutation summary (counts of created/updated rows).
+     * It does NOT return the updated `CheckoutSession` — the underlying
+     * `POST /checkout-sessions/:id/line-items` endpoint never has and the
+     * previous typing was a lie that quietly assigned `{ success, updated, ... }`
+     * into a `CheckoutSession` slot in `useCheckout`.
+     *
+     * Call `loadSession()` after this if you need the refreshed session
+     * (the React `useCheckout` hook does this for you).
+     */
+    updateCart(sessionId: string, items: LineItem[]): Promise<UpdateCartResult>;
+    /**
+     * Update customer identity (email, name, phone).
+     *
+     * Call this before `updateAddress()` — the SDK remembers the values and
+     * includes them automatically when addresses are submitted.
+     *
+     * If you prefer a single call, use `updateCustomerAndAddress()` instead.
      */
     updateCustomer(sessionId: string, customer: Partial<CheckoutCustomer>): Promise<void>;
     /**
      * Update shipping and/or billing address on the session.
      *
-     * Address fields use the API's naming: `address1`, `postal`, etc.
+     * Automatically includes customer name/phone stored from `updateCustomer()`.
+     * Uses the same atomic API call as the production checkout, so email,
+     * customer name, and addresses are all persisted together.
+     *
+     * **Shipped products**: pass `shippingAddress`. If `billingAddress` is omitted,
+     * the shipping address is automatically used as billing.
+     *
+     * **Digital products**: pass only `billingAddress` (no shipping needed).
+     *
+     * @example
+     * // Shipped product — billing = shipping automatically
+     * await checkout.updateAddress(sessionId, {
+     *   shippingAddress: { line1: '10 Rue de la Paix', city: 'Paris', postalCode: '75002', country: 'FR' },
+     * });
+     *
+     * @example
+     * // Digital product — billing only
+     * await checkout.updateAddress(sessionId, {
+     *   billingAddress: { country: 'FR' },
+     * });
      */
     updateAddress(sessionId: string, addresses: {
         shippingAddress?: Address;
         billingAddress?: Address;
     }): Promise<void>;
+    /**
+     * Set customer info + addresses in one call (mirrors production checkout).
+     *
+     * Equivalent to calling `updateCustomer()` then `updateAddress()`, but
+     * in a single network request.
+     */
+    updateCustomerAndAddress(sessionId: string, data: {
+        customer: Partial<CheckoutCustomer>;
+        shippingAddress?: Address;
+        billingAddress?: Address;
+    }): Promise<void>;
+    /** Map an SDK Address to the API shape, injecting stored customer fields. */
+    private mapAddress;
     /** Apply a promotion code to the session. */
     applyPromoCode(sessionId: string, code: string): Promise<void>;
     /** Remove a promotion from the session by promotion ID. */
     removePromoCode(sessionId: string, promotionId?: string): Promise<void>;
-    /** Fetch available shipping rates for the session's address. */
+    /**
+     * Fetch available shipping rates for the session's address.
+     * Only relevant for **shipped products** — digital products can skip this step.
+     *
+     * Requires a shipping address to be set first via `updateAddress()`.
+     * Returns an empty array if no rates are configured or address is missing.
+     */
     getShippingRates(sessionId: string): Promise<ShippingRate[]>;
-    /** Select a shipping rate for the session. */
+    /**
+     * Select a shipping rate for the session.
+     * Only relevant for **shipped products** — digital products can skip this step.
+     */
     selectShippingRate(sessionId: string, rateId: string): Promise<void>;
     /**
      * Normalize the raw v2 API response into a cleaner CheckoutSession shape.
      * The raw response has nested `checkoutSession` + `summary` -- we flatten it.
      */
     private normalizeSession;
+    /**
+     * Map the raw API address shape (`address1`, `address2`, `postal`) onto
+     * the SDK's `Address` shape (`line1`, `line2`, `postalCode`). Without
+     * this, `session.shippingAddress.line1` is silently undefined after a
+     * reload — the type was lying about the actual key names — which is
+     * what makes the demo lose form state on refresh.
+     */
+    private normalizeAddress;
 }
 //# sourceMappingURL=checkout.d.ts.map

package/dist/core/modules/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../../src/core/modules/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IALjC,OAAO,CAAC,YAAY,CAAqB;gBAGtB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,aAAA;IAG1D;;;;;;;;OAQG;IACG,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAiBzF;;;;;OAKG;IACG,aAAa,CAAC,IAAI,EAAE;QACxB,KAAK,EAAE,QAAQ,EAAE,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAyCrG,sDAAsD;IAChD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAQhF;;;OAGG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAClC,OAAO,CAAC,IAAI,CAAC;IAqBhB;;;;OAIG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GACjE,OAAO,CAAC,IAAI,CAAC;IA0BhB,6CAA6C;IACvC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpE,2DAA2D;IACrD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7E,gEAAgE;IAC1D,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAQlE,8CAA8C;IACxC,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1E;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAwDzB"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../../src/core/modules/checkout.ts"],"names":[],"mappings":"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"}