@sesamy/sesamy-js 1.55.0 → 1.57.0

package/README.md

@@ -1102,6 +1102,10 @@ Creates a checkout session with Sesamy. This function initializes a checkout pro
     - sourceId (string, optional): Source identifier.
     - \_ga, \_gid, \_fbp, \_fbc (strings, optional): Analytics tracking cookies.
   - referralEmail (string, optional): Email of the referrer.
+  - payerEmail (string, optional): Email of the payer (person paying for the purchase).
+  - requireAddress (boolean, optional): If true, requires the customer to provide an address during checkout.
+  - giftMode (boolean, optional): If true, enables gift mode for the checkout.
+  - metaData (Record<string, string>, optional): Custom metadata to store with the checkout (e.g., { "campaign": "summer2024", "source": "mobile" }).
 
 ### Returns
 
@@ -1162,52 +1166,38 @@ const checkout = await sesamy.checkouts.create({
   ],
   email: 'customer@example.com',
   redirectUrl: 'https://yoursite.com/checkout-complete',
+  requireAddress: true,
+  metaData: {
+    campaignId: 'summer_2024',
+    source: 'mobile_app',
+  },
 });
 
 // Redirect to checkout
 window.location.href = checkout.checkoutUrl;
 ```
 
-Advanced example with multiple items and tracking:
+Advanced example with gift mode and payer email:
 
 ```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,
+      sku: 'premium_gift',
+      purchaseOptionId: 'po_gift',
+      price: 49.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',
-  },
+  email: 'recipient@example.com',
+  payerEmail: 'sender@example.com',
   redirectUrl: 'https://yoursite.com/checkout-complete',
+  giftMode: true,
   language: 'en',
-  attribution: {
-    utmSource: 'email',
-    utmMedium: 'newsletter',
-    utmCampaign: 'summer_sale_2024',
+  metaData: {
+    giftMessage: 'Happy Birthday!',
+    giftFrom: 'John',
   },
-  requestedDiscountCodes: ['WELCOME10', 'EARLYBIRD'],
-  paymentMethodsFilter: [{ provider: 'stripe', methods: ['card'] }, { provider: 'klarna' }],
-});
-
-window.location.href = checkout.checkoutUrl;
-```
 
 ### Additional Notes
 
@@ -1247,6 +1237,10 @@ Updates an existing checkout session with Sesamy. You can update customer inform
   - 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.
+  - payerEmail (string, optional): Updated payer email.
+  - requireAddress (boolean, optional): Updated address requirement.
+  - giftMode (boolean, optional): Updated gift mode status.
+  - metaData (Record<string, string>, optional): Updated metadata.
 
 ### Returns
 
@@ -2844,3 +2838,55 @@ The Events API can be used for various scenarios where you need to communicate b
 4. **Analytics**: Emit events for key user interactions that other scripts might want to track.
 
 Events emitted through this API are also automatically tracked in analytics with the prefix `event:`.
+
+## Using the SDK for Link Generation
+
+While `sesamy-js` provides `generateLink` which automatically signs links if the user is authenticated, you can also use the `@sesamy/sdk` package directly to generate unsigned links without requiring authentication. This is useful for generating shareable links or links for unauthenticated users.
+
+### SDK Link Generation Example
+
+```javascript
+import { client } from '@sesamy/sdk';
+
+// Generate a checkout link (no authentication required)
+const checkoutUrl = client.checkout.generateLink(
+  { apiUrl: 'https://api-proxy.example.com' },
+  {
+    items: [{ sku: 'premium-monthly' }],
+    email: 'user@example.com',
+    language: 'en',
+    redirectUrl: 'https://example.com/success',
+    requireAddress: true,
+    giftMode: false,
+    metaData: {
+      campaignId: 'summer_2024',
+      source: 'newsletter',
+    },
+  }
+);
+
+// Generate account management links
+const accountUrl = client.links.generateAccountLink(
+  { baseUrl: 'https://app.example.com', clientId: 'your-client-id' },
+  { language: 'en', redirectUrl: 'https://example.com' }
+);
+
+// Generate change payment link
+const changePaymentUrl = client.links.generateChangePaymentLink(
+  { baseUrl: 'https://app.example.com', clientId: 'your-client-id' },
+  { contractId: 'contract-123', language: 'en' }
+);
+
+// Generate consume content link
+const consumeUrl = client.links.generateConsumeLink(
+  { baseUrl: 'https://app.example.com', clientId: 'your-client-id' },
+  { sku: 'product-123', language: 'en' }
+);
+```
+
+### Differences Between sesamy-js generateLink and SDK Links
+
+- **sesamy-js `generateLink`**: Includes authentication token in hash if user is authenticated, automatically includes tracking cookies and attribution data, supports link shortening via TTL
+- **SDK `links.*`**: Pure URL generation without authentication, useful for generating shareable links, links for unauthenticated users, or backend link generation
+
+````