@sesamy/sesamy-js 1.54.0 → 1.56.0

package/README.md

@@ -174,6 +174,7 @@ These are the available configuration options, with their default values:
     domain: null,        // Optional: custom Auth0 domain (e.g., 'auth.example.com')
     domains: []          // Optional: array of auth domain strings for multi-domain setups
   },
+  enablePaywallSettingsUrlFallback: false,  // Optional: enable fallback to sesamy-paywall settings-url
   content: [
     {
       type: 'article',
@@ -1101,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
 
@@ -1161,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
 
@@ -1246,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
 
@@ -1624,6 +1619,8 @@ console.log('Article title:', title);
 
 The content configuration is defined within the `Config` json. The following properties are available:
 
+### Content Node Properties
+
 - `article` (object): Defines the selector for the article element itself.
 - `image` (object): Specifies the selector and attribute for extracting article images.
 - `title` (object): Specifies the selector and attribute for extracting the article title.
@@ -1638,6 +1635,56 @@ Each field object contains the following properties:
 - `selector` (string): A CSS selector to target elements on the page.
 - `attribute` (string, optional): The attribute to retrieve from the selected element. If not specified, the text content of the element is used.
 
+### Feature Flags
+
+#### `enablePaywallSettingsUrlFallback`
+
+**Type:** `boolean`  
+**Default:** `false`
+
+When enabled, this feature flag allows the content module to fall back to checking for a `settings-url` attribute on `<sesamy-paywall>` elements when no `paywallUrl` is found through the standard detection methods (meta tags or article attributes).
+
+**Use Case:** This is useful for pages that use the `<sesamy-paywall>` custom element but don't explicitly set the paywall URL in meta tags or on the article element. The paywall component may have a `settings-url` attribute that points to the paywall configuration.
+
+**Priority Order:**
+
+1. Article element `paywall-url` attribute
+2. Content configuration `paywallUrl` property
+3. Meta tags (`sesamy:paywall-url`, `og:paywall-url`, etc.)
+4. **If `enablePaywallSettingsUrlFallback` is true:** `<sesamy-paywall settings-url="...">` attribute
+
+**Example:**
+
+```javascript
+// Enable the fallback feature
+{
+  clientId: "demo",
+  enablePaywallSettingsUrlFallback: true,
+  content: [
+    {
+      type: 'article',
+      selectors: {
+        article: { selector: 'sesamy-article' }
+      }
+    }
+  ]
+}
+```
+
+```html
+<!-- Page with sesamy-paywall element -->
+<sesamy-paywall settings-url="https://example.com/api/paywalls/123"></sesamy-paywall>
+<sesamy-article item-src="https://example.com/article/456">
+  <!-- Article content -->
+</sesamy-article>
+
+<script>
+  // The content.get() method will now find the paywall URL from the sesamy-paywall element
+  const article = window.sesamy.content.get('sesamy-article');
+  console.log(article.paywallUrl); // "https://example.com/api/paywalls/123"
+</script>
+```
+
 ### Example Configuration
 
 Below is an example configuration for the content module:
@@ -1732,6 +1779,161 @@ console.log(articles);
 
 In this example, `content.list()` will return an array of articles extracted from the page based on the configured selectors. Each article object contains fields such as title, excerpt, image, price, currency, URL, and ID.
 
+#### `get(articleElementOrSelector: Element | string)`
+
+Extracts article data from a specific element on the page.
+
+### Parameters
+
+- `articleElementOrSelector` (Element | string): Either a DOM element or a CSS selector string identifying the article element.
+
+### Returns
+
+- `Article | null`: An article object containing the extracted data, or `null` if the element is not found.
+
+The returned article object contains the following properties:
+
+- `title` (string, optional): The title of the article.
+- `excerpt` (string, optional): The article's excerpt.
+- `image` (string, optional): The source URL of the article's image.
+- `price` (number, optional): The price of the article.
+- `currency` (string, optional): The currency of the article price.
+- `url` (string, optional): The URL of the article.
+- `id` (string, optional): The article's unique ID.
+- `pass` (string, optional): Comma-separated list of passes required for access.
+- `paywallUrl` (string, optional): URL to the paywall configuration.
+- `accessLevel` ('public' | 'logged-in' | 'entitlement', optional): The access level required for the content.
+- `selector` (string): The CSS selector for the article element.
+- `element` (Element): The original DOM element for the article.
+- `hasAccess` (boolean, optional): Whether the user has access to the content. Set by `hasAccess()` method.
+- `entitlement` (Entitlement, optional): The entitlement object if access is granted via entitlement. Set by `hasAccess()` method.
+
+### Example Usage
+
+```js
+// Get article data by CSS selector
+const article = window.sesamy.content.get('article.premium-content');
+console.log('Article:', article);
+
+// Get article data by DOM element
+const element = document.querySelector('.my-article');
+const article = window.sesamy.content.get(element);
+console.log('Article:', article);
+```
+
+#### `hasAccess(articleElementOrSelector: Element | string)`
+
+Checks if the current user has access to the specified article. This method intelligently determines the access requirements based on the article's paywall configuration and decorates the article with access status and entitlement information.
+
+### Parameters
+
+- `articleElementOrSelector` (Element | string): Either a DOM element or a CSS selector string identifying the article element.
+
+### Returns
+
+- `Promise<Article>`: A promise that resolves to the article object decorated with access information:
+  - `hasAccess` (boolean): `true` if the user has access, `false` otherwise
+  - `entitlement` (Entitlement, optional): The entitlement object if access is granted via entitlement
+  - All other article properties (title, url, etc.)
+
+### Behavior
+
+1. **Paywall-based Access**: If the article has a `paywallUrl`, the method fetches the paywall configuration to determine the access type based on the paywall template:
+   - **Login Paywall** (`template: 'LOGIN'`): Sets `accessLevel` to `'logged-in'`, checks if the user is authenticated, and sets `hasAccess` accordingly.
+   - **Entitlement Paywall** (`template: 'BOXES'`): Sets `accessLevel` to `'entitlement'`, checks for entitlement, and sets both `hasAccess` and `entitlement`.
+
+2. **Standard Entitlement Check**: If no `paywallUrl` is specified, the method uses the article's `url` and `pass` properties to check for entitlement access, setting both `hasAccess` and `entitlement`.
+
+### Example Usage
+
+```js
+// Check access for an article
+const article = await window.sesamy.content.hasAccess('.premium-article');
+
+if (article.hasAccess) {
+  console.log('User has access to:', article.title);
+  if (article.entitlement) {
+    console.log('Via entitlement:', article.entitlement.id);
+  }
+  // Show premium content
+} else {
+  console.log('User does not have access');
+  // Show paywall or login prompt
+}
+
+// Use with async/await
+async function checkArticleAccess() {
+  try {
+    const article = await window.sesamy.content.hasAccess('article#main');
+
+    if (article.hasAccess) {
+      // Unlock or display content
+      console.log('Access granted to article:', article.url);
+
+      // Access entitlement details if available
+      if (article.entitlement) {
+        console.log('Entitlement type:', article.entitlement.type);
+        console.log('Entitlement SKU:', article.entitlement.sku);
+      }
+    } else {
+      // Redirect to paywall
+      console.log('Access denied');
+    }
+  } catch (error) {
+    console.error('Error checking access:', error);
+  }
+}
+```
+
+#### `unlock(articleElementOrSelector: Element | string, lockedContentSelector?: string)`
+
+Retrieves and unlocks premium content for an article that the user has entitlement access to.
+
+### Parameters
+
+- `articleElementOrSelector` (Element | string): Either a DOM element or a CSS selector string identifying the article element.
+- `lockedContentSelector` (string, optional): A CSS selector for the specific locked content to retrieve. If not provided, uses the parent element of the article.
+
+### Returns
+
+- `Promise<string>`: A promise that resolves to the unlocked HTML content.
+
+### Throws
+
+- Error if the article element cannot be found.
+- Error if the article doesn't have a URL.
+- Error if the user doesn't have access to the content.
+- Error if the access token cannot be retrieved.
+
+### Example Usage
+
+```js
+// Unlock content and replace the locked element
+async function unlockArticle() {
+  try {
+    const unlockedContent = await window.sesamy.content.unlock('.premium-article');
+
+    // Replace the locked content with the unlocked content
+    const article = document.querySelector('.premium-article');
+    if (article && article.parentElement) {
+      article.parentElement.innerHTML = unlockedContent;
+    }
+  } catch (error) {
+    console.error('Failed to unlock content:', error);
+  }
+}
+
+// Unlock specific content within an article
+async function unlockSpecificContent() {
+  const unlockedContent = await window.sesamy.content.unlock('article.premium', '.locked-section');
+
+  const lockedSection = document.querySelector('.locked-section');
+  if (lockedSection) {
+    lockedSection.innerHTML = unlockedContent;
+  }
+}
+```
+
 ### Flags API
 
 The Flags API allows for client-side feature flag management. These flags are stored in the browser's localStorage and can be used to enable or disable features for specific users.
@@ -2636,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
+
+````