@sesamy/sesamy-js 1.43.0 → 1.45.0

package/README.md

@@ -1057,191 +1057,232 @@ Creates a checkout session with Sesamy. This function initializes a checkout pro
 ### Parameters
 
 - params (CreateCheckoutParams): The parameters for creating the checkout session.
-  - items (Array of objects): An array of items to be included in the checkout.
-    - sku (string): The SKU of the product to be purchased.
-    - purchaseOptionsId (string, optional): The ID of the purchase options for the product.
+  - **items** (Array of objects, **required**): An array of items to be included in the checkout.
+    - sku (string, optional): The SKU of the product to be purchased.
+    - url (string, optional): The URL of the item.
+    - purchaseOptionId (string, optional): The ID of the purchase option for the product.
+    - price (number, optional): The price of the item.
+    - currency (string, optional): The currency code (e.g., 'USD').
+    - geoRestrictions (object, optional): Geographic restrictions for the item.
+      - type ('ALLOW' | 'BLOCK'): Type of restriction.
+      - countries (Array of strings): List of country codes.
+  - **redirectUrl** (string, **required**): The URL to redirect to after the checkout process is completed.
   - language (string, optional): The language for the checkout session. If not set, it will be automatically fetched from the HTML element's `lang` attribute.
-  - redirectUrl (string): The URL to redirect to after the checkout process is completed.
   - givenName (string, optional): The given name of the customer.
   - familyName (string, optional): The family name of the customer.
   - email (string, optional): The email address of the customer.
   - phoneNumber (string, optional): The phone number of the customer.
-  - birthDate (string, optional): The birth date of the customer.
-  - country (string, optional): The country of the customer.
-  - address (Address, optional): The address for the checkout session.
+  - birthDate (string, optional): The birth date of the customer in ISO format.
+  - country (string, optional): The country of the customer (country code).
+  - address (Address, optional): The billing address for the checkout session.
     - street (string, optional): The street address.
     - city (string, optional): The city.
     - zip (string, optional): The postal code.
-    - country (string, optional): The country.
+    - country (string, optional): The country code.
+  - businessAddress (Address, optional): The business address for B2B transactions.
   - isBusiness (boolean, optional): Indicates if the checkout is for a business.
-  - paymentMethodsFilter (Array of objects, optional): The payment methods to be available in the checkout. The payment methods are an object with a provider and a method property, where the method is an optional array.
+  - price (number, optional): Override price for the entire order (takes precedence over item prices).
+  - currency (string, optional): Override currency for the entire order.
+  - paymentMethodsFilter (Array of objects, optional): Filter available payment methods in the checkout.
+    - provider (string): The payment provider (e.g., 'stripe', 'klarna').
+    - methods (Array of strings, optional): Specific payment methods for the provider.
+  - requestedDiscountCodes (Array of strings, optional): Discount codes to apply to the checkout.
+  - attribution (object, optional): Attribution and tracking data.
+    - utmSource (string, optional): UTM source parameter.
+    - utmMedium (string, optional): UTM medium parameter.
+    - utmCampaign (string, optional): UTM campaign parameter.
+    - utmTerm (string, optional): UTM term parameter.
+    - utmContent (string, optional): UTM content parameter.
+    - ref (string, optional): Referral identifier.
+    - referrer (string, optional): Referrer URL.
+    - itemSrc (string, optional): Source of the item.
+    - publisherContentId (string, optional): Publisher content ID.
+    - source ('CHECKOUT' | 'PAYWALL' | 'OTHERS', optional): Source of the checkout.
+    - sourceId (string, optional): Source identifier.
+    - \_ga, \_gid, \_fbp, \_fbc (strings, optional): Analytics tracking cookies.
+  - referralEmail (string, optional): Email of the referrer.
 
 ### Returns
 
-Promise\<CheckoutResponse\>: A promise that resolves to the response JSON object from the Sesamy API, which contains details about the created checkout session.
+Promise\<Checkout\>: A promise that resolves to the response JSON object from the Sesamy API, which contains details about the created checkout session.
 
-### CheckoutResponse Schema
+### Checkout Response Schema
 
 - id (string): The unique identifier of the checkout session.
-- checkoutUrl (string): The URL for the checkout session.
-- status (enum): The status of the checkout session, can be 'PENDING' or 'PAID'.
-- createdAt (string): The creation timestamp of the checkout session.
-- modifiedAt (string): The last modified timestamp of the checkout session.
-- type (enum): The type of checkout session, can be 'RECURRING' or 'SINGLE'.
-- currency (string): The currency used for the checkout session.
-- country (string): The country associated with the checkout session.
-- redirectUrl (string): The URL to redirect to after the checkout process is completed.
-- email (string, optional): The email address for the checkout session.
-- language (string): The language used for the checkout session.
+- checkoutUrl (string): The URL where the user should be redirected to complete the checkout.
+- status ('PENDING' | 'PAID'): The status of the checkout session.
+- type ('RECURRING' | 'SINGLE'): The type of checkout session.
+- createdAt (string): ISO timestamp of when the checkout was created.
+- updatedAt (string): ISO timestamp of when the checkout was last updated.
 - items (Array of objects): The items included in the checkout session.
   - sku (string): The SKU of the product.
-  - purchaseOptionId (string, optional): The ID of the purchase option for the product.
+  - url (string): The URL of the item.
+  - purchaseOptionId (string, optional): The ID of the purchase option.
+  - price (number, optional): The price of the item.
+  - currency (string, optional): The currency of the item.
+- itemsOwned (Array of objects): Items already owned by the user.
+  - sku (string): The SKU of the product.
+  - purchaseOptionId (string): The purchase option ID.
   - title (string): The title of the product.
-  - cover (string): The cover image URL of the product.
-- itemsOwned (Array of strings): The SKUs of the items already owned by the user.
-- discountCodes (Array of strings): The discount codes applied to the checkout session.
-- paymentOptions (Array of objects): The available payment options.
+- appliedDiscountCodes (Array of objects): Discount codes applied to the checkout.
+  - name (string): Name of the discount.
+  - description (string): Description of the discount.
+  - id (string): ID of the discount code.
+  - code (string): The discount code.
+  - status ('APPLIED' | 'UNAPPLICABLE'): Status of the discount code.
+- availablePaymentMethods (Array of objects): Available payment methods for checkout.
   - provider (string): The payment provider.
-  - methods (Array of strings): The payment methods supported by the provider.
+  - methods (Array of strings, optional): Available payment methods for the provider.
+- email (string, optional): The email address for the checkout session.
+- language (string): The language used for the checkout session.
+- currency (string): The currency used for the checkout session.
+- country (string): The country associated with the checkout session.
+- redirectUrl (string): The redirect URL after completion.
+- fieldSettings (object, optional): Field visibility and requirement settings.
 
 ### Example
 
 The following example demonstrates how to create a checkout session with Sesamy:
 
 ```javascript
-import { createCheckout } from '@sesamy/sesamy-js';
+import { init } from '@sesamy/sesamy-js';
+
+const sesamy = await init({ clientId: 'your-client-id' });
 
-// Create a checkout session with one item
-const checkoutParams = {
+// Create a simple checkout with one item
+const checkout = await sesamy.checkouts.create({
   items: [
     {
-      sku: 'sid:eUv45QXTrcGNhMJpaCQNe',
-      purchaseOptionsId: 'option-id', // optional
+      sku: 'premium_monthly',
+      purchaseOptionId: 'po_123',
+      price: 9.99,
+      currency: 'USD',
     },
   ],
-  language: 'en', // optional
-};
+  email: 'customer@example.com',
+  redirectUrl: 'https://yoursite.com/checkout-complete',
+});
 
-createCheckout(checkoutParams)
-  .then((response) => {
-    console.log('Checkout session created:', response);
-  })
-  .catch((error) => {
-    console.error('Error creating checkout session:', error);
-  });
+// Redirect to checkout
+window.location.href = checkout.checkoutUrl;
 ```
 
-In this example, a checkout session is created with a single item specified by its SKU and an optional purchase options ID. The language is set to English (`'en'`), but if not provided, it will default to the language specified in the HTML `lang` attribute.
+Advanced example with multiple items and tracking:
 
-### Additional Notes
+```javascript
+const checkout = await sesamy.checkouts.create({
+  items: [
+    {
+      sku: 'premium_annual',
+      purchaseOptionId: 'po_456',
+      price: 99.99,
+      currency: 'USD',
+    },
+    {
+      sku: 'addon_feature',
+      price: 9.99,
+      currency: 'USD',
+    },
+  ],
+  email: 'customer@example.com',
+  givenName: 'John',
+  familyName: 'Doe',
+  phoneNumber: '+1234567890',
+  address: {
+    street: '123 Main St',
+    city: 'San Francisco',
+    zip: '94102',
+    country: 'US',
+  },
+  redirectUrl: 'https://yoursite.com/checkout-complete',
+  language: 'en',
+  attribution: {
+    utmSource: 'email',
+    utmMedium: 'newsletter',
+    utmCampaign: 'summer_sale_2024',
+  },
+  requestedDiscountCodes: ['WELCOME10', 'EARLYBIRD'],
+  paymentMethodsFilter: [{ provider: 'stripe', methods: ['card'] }, { provider: 'klarna' }],
+});
 
-- The `language` parameter is optional. If it is not provided, the language will be determined using the `getLanguage` function, which fetches the language from the `lang` attribute of the HTML document element.
-- The `items` array must contain at least one item with a valid `sku`.
+window.location.href = checkout.checkoutUrl;
+```
+
+### Additional Notes
 
-By using the `createCheckout` function, you can easily initialize a checkout process and handle the response from the Sesamy API to complete the transaction.
+- The `items` array must contain at least one item.
+- The `redirectUrl` is required and will be used after the checkout is completed.
+- The `language` parameter is optional. If not provided, it will be determined from the HTML document's `lang` attribute.
+- Attribution data is automatically enhanced with tracking cookies (\_ga, \_gid, \_fbp, \_fbc) if available.
+- Discount codes validation happens on the Sesamy backend; invalid codes will be marked as 'UNAPPLICABLE' in the response.
 
 ## `checkouts.update(id: string, params: Partial<CreateCheckoutParams>)`
 
-Updates a checkout session with Sesamy.
+Updates an existing checkout session with Sesamy. You can update customer information, items, or other checkout details.
 
 ### Parameters
 
-- params (Partial<CreateCheckoutParams>): The updated parameters for the checkout session.
-  - items (Array of objects): An array of items to be included in the checkout.
-    - sku (string): The SKU of the product to be purchased.
-    - purchaseOptionsId (string, optional): The ID of the purchase options for the product.
-  - language (string, optional): The language for the checkout session.
-  - redirectUrl (string): The URL to redirect to after the checkout process is completed.
-  - givenName (string, optional): The given name of the customer.
-  - familyName (string, optional): The family name of the customer.
-  - email (string, optional): The email address for the checkout session.
-  - phoneNumber (string, optional): The phone number of the customer.
-  - birthDate (string, optional): The birth date of the customer.
-  - country (string, optional): The country of the customer.
-  - address (Address, optional): The address for the checkout session.
-    - street (string, optional): The street address.
-    - city (string, optional): The city.
-    - zip (string, optional): The postal code.
-    - country (string, optional): The country.
-  - isBusiness (boolean, optional): Indicates if the checkout is for a business.
+- id (string): The unique identifier of the checkout session to update.
+- params (Partial<CreateCheckoutParams>): The parameters to update. All fields are optional.
+  - items (Array of objects, optional): Updated array of items.
+    - sku (string, optional): The SKU of the product.
+    - url (string, optional): The URL of the item.
+    - purchaseOptionId (string, optional): The ID of the purchase option.
+    - price (number, optional): The price of the item.
+    - currency (string, optional): The currency code.
+  - redirectUrl (string, optional): Updated redirect URL.
+  - language (string, optional): Updated language for the checkout session.
+  - email (string, optional): Updated email address.
+  - givenName (string, optional): Updated given name.
+  - familyName (string, optional): Updated family name.
+  - phoneNumber (string, optional): Updated phone number.
+  - birthDate (string, optional): Updated birth date.
+  - country (string, optional): Updated country.
+  - address (Address, optional): Updated billing address.
+  - businessAddress (Address, optional): Updated business address.
+  - isBusiness (boolean, optional): Updated business status.
+  - price (number, optional): Updated order price.
+  - currency (string, optional): Updated order currency.
+  - paymentMethodsFilter (Array of objects, optional): Updated payment method filters.
+  - requestedDiscountCodes (Array of strings, optional): Updated discount codes to apply.
+  - attribution (object, optional): Updated attribution and tracking data.
 
 ### Returns
 
-Promise\<CheckoutResponse\>: A promise that resolves to the response JSON object from the Sesamy API, which contains details about the updated checkout session.
-
-### CheckoutResponse Schema
-
-- id (string): The unique identifier of the checkout session.
-- checkoutUrl (string): The URL for the checkout session.
-- status (enum): The status of the checkout session, can be 'PENDING' or 'PAID'.
-- createdAt (string): The creation timestamp of the checkout session.
-- modifiedAt (string): The last modified timestamp of the checkout session.
-- type (enum): The type of checkout session, can be 'RECURRING' or 'SINGLE'.
-- currency (string): The currency used for the checkout session.
-- country (string): The country associated with the checkout session.
-- language (string): The language used for the checkout session.
-- items (Array of objects): The items included in the checkout session.
-  - sku (string): The SKU of the product.
-  - purchaseOptionId (string, optional): The ID of the purchase option for the product.
-  - title (string): The title of the product.
-  - cover (string): The cover image URL of the product.
-- itemsOwned (Array of strings): The SKUs of the items already owned by the user.
-- discountCodes (Array of strings): The discount codes applied to the checkout session.
-- paymentOptions (Array of objects): The available payment options.
-  - provider (string): The payment provider.
-  - methods (Array of strings): The payment methods supported by the provider.
+Promise\<Checkout\>: A promise that resolves to the updated checkout session object.
 
 ### Example
 
-The following example demonstrates how to create a checkout session with Sesamy:
+Basic update example:
 
 ```javascript
-import { updateCheckout } from '@sesamy/sesamy-js';
-
-// Create a checkout session with one item
-const checkoutParams = {
-  email: 'test@example.com',
-};
-
-updateCheckout('checkoutId', checkoutParams)
-  .then((response) => {
-    console.log('Checkout session updated:', response);
-  })
-  .catch((error) => {
-    console.error('Error updating checkout session:', error);
-  });
-```
-
-In this example, a checkout session is created with a single item specified by its SKU and an optional purchase options ID. The language is set to English (`'en'`), but if not provided, it will default to the language specified in the HTML `lang` attribute.
-
-### Additional Notes
-
-- The `language` parameter is optional. If it is not provided, the language will be determined using the `getLanguage` function, which fetches the language from the `lang` attribute of the HTML document element.
-- The `items` array must contain at least one item with a valid `sku`.
+import { init } from '@sesamy/sesamy-js';
 
-By using the `createCheckout` function, you can easily initialize a checkout process and handle the response from the Sesamy API to complete the transaction.
+const sesamy = await init({ clientId: 'your-client-id' });
 
-## `checkouts.get(id: string)`
+const updated = await sesamy.checkouts.update('checkout_123', {
+  email: 'newemail@example.com',
+  givenName: 'Jane',
+});
 
-Retrieves the details of a specific checkout session from Sesamy. This function fetches the checkout session information based on the provided checkout session ID.
+console.log('Checkout updated:', updated);
+```
 
-### Parameters
+Update with new discount codes:
 
-- id (string): The unique identifier of the checkout session to retrieve.
-
-### Returns
+```javascript
+const updated = await sesamy.checkouts.update('checkout_123', {
+  requestedDiscountCodes: ['NEWCODE', 'SUMMER20'],
+});
 
-Promise\<CheckoutResponse\>: A promise that resolves to the response JSON object from the Sesamy API, which contains details about the requested checkout session.
+console.log('Applied discount codes:', updated.appliedDiscountCodes);
+```
 
-### CheckoutResponse Schema
+### Additional Notes
 
-- id (string): The unique identifier of the checkout session.
-- checkoutUrl (string): The URL for the checkout session.
-- status (enum): The status of the checkout session, can be 'PENDING' or 'PAID'.
-- createdAt (string): The creation timestamp of the checkout session.
-- modifiedAt (string): The last modified timestamp of the checkout session.
-- type (enum): The type of checkout session, can be 'RECURRING' or 'SINGLE'.
-- currency (string): The currency used for the checkout session.
+- Only provide the fields you want to update; omitted fields will remain unchanged.
+- Discount codes are validated on the Sesamy backend.
+- Changes to payment method filters will be reflected in the checkout session immediately.
 - country (string): The country associated with the checkout session.
 - language (string): The language used for the checkout session.
 - items (Array of objects): The items included in the checkout session.
@@ -1255,32 +1296,36 @@ Promise\<CheckoutResponse\>: A promise that resolves to the response JSON object
   - provider (string): The payment provider.
   - methods (Array of strings): The payment methods supported by the provider.
 
-### Example
+## `checkouts.get(id: string)`
 
-The following example demonstrates how to retrieve the details of a specific checkout session with Sesamy:
+Retrieves the details of a specific checkout session from Sesamy.
+
+### Parameters
+
+- id (string): The unique identifier of the checkout session to retrieve.
+
+### Returns
+
+Promise\<Checkout\>: A promise that resolves to the checkout session object with all details.
+
+### Example
 
 ```javascript
-import { getCheckout } from '@sesamy/sesamy-js';
+import { init } from '@sesamy/sesamy-js';
 
-// Retrieve the details of a checkout session by ID
-const checkoutId = 'checkout-session-id';
+const sesamy = await init({ clientId: 'your-client-id' });
 
-getCheckout(checkoutId)
-  .then((response) => {
-    console.log('Checkout session details:', response);
-  })
-  .catch((error) => {
-    console.error('Error retrieving checkout session:', error);
-  });
+const checkout = await sesamy.checkouts.get('checkout_123');
+console.log('Checkout status:', checkout.status);
+console.log('Checkout URL:', checkout.checkoutUrl);
+console.log('Applied discounts:', checkout.appliedDiscountCodes);
+console.log('Items owned:', checkout.itemsOwned);
 ```
 
-In this example, the details of a specific checkout session are retrieved using its unique ID. The function returns a promise that resolves to the details of the checkout session.
-
 ### Additional Notes
 
 - The `id` parameter is required and must be a valid checkout session identifier.
-
-By using the `getCheckout` function, you can easily fetch the details of a specific checkout session from the Sesamy API to view or process the transaction information.
+- Returns the complete checkout session data including status, items, and applied discounts.
 
 # Browser API