@sesamy/sesamy-js 1.35.10 → 1.36.0

package/README.md

@@ -67,6 +67,7 @@ The following methods are available on the `sesamy` object:
   - delete: deletes a feature flag
 - fulfillments
   - list: list the user's fulfillments for a SKU
+  - requestDelivery: requests delivery for a fulfillment by SKU and delivery method
 - generateLink: creates a link to a Sesamy hosted service such as account, change-payment, consume, or checkout. If the user is authenticated, the link will be signed so that the user can access the service without logging in again.
 - getPaymentIssues: returns a list of failed payments and cards that will expire
 - getVersion: returns the version of the sesamy-js library
@@ -749,7 +750,7 @@ import { generateLink } from '@sesamy/sesamy-js';
 // Generate a link to consume a product
 const linkParams = {
   target: 'consume',
-  sku: 'product-sku',
+  sku: 'sid:eUv45QXTrcGNhMJpaCQNe',
   episodeId: 'episode-id',
   shorten: true,
   ttl: 3600, // 1 hour in seconds
@@ -828,7 +829,7 @@ import { createCheckout } from '@sesamy/sesamy-js';
 const checkoutParams = {
   items: [
     {
-      sku: 'product-sku',
+      sku: 'sid:eUv45QXTrcGNhMJpaCQNe',
       purchaseOptionsId: 'option-id', // optional
     },
   ],
@@ -1507,6 +1508,652 @@ window.sesamy.amendments
   });
 ```
 
+# Products API
+
+The Products API provides methods for working with Sesamy products, including retrieving product information and linking accounts.
+
+## `products.get(sku: string)`
+
+Retrieves detailed information about a product by its SKU.
+
+### Parameters
+
+- `sku` (string): The Stock Keeping Unit (SKU) identifier for the product.
+
+### Returns
+
+- `Promise<Product>`: A promise that resolves to the product object.
+
+### Example
+
+```javascript
+// Get product information by SKU
+window.sesamy.products
+  .get('sid:eUv45QXTrcGNhMJpaCQNe')
+  .then(product => {
+    console.log('Product details:', product);
+    console.log('Product name:', product.name);
+    console.log('Product price:', product.price);
+  })
+  .catch(error => {
+    console.error('Error fetching product:', error);
+  });
+```
+
+## `products.autoOnboard(sku: string)`
+
+Triggers the auto-onboarding process for a product by SKU, which helps users get started with a product they've purchased.
+
+### Parameters
+
+- `sku` (string): The Stock Keeping Unit (SKU) identifier for the product.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the auto-onboarding process was successfully initiated.
+
+### Example
+
+```javascript
+// Trigger auto-onboarding for a product
+window.sesamy.products
+  .autoOnboard('sid:eUv45QXTrcGNhMJpaCQNe')
+  .then(success => {
+    if (success) {
+      console.log('Auto-onboarding process initiated successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error triggering auto-onboarding:', error);
+  });
+```
+
+## `products.linkSpotify()`
+
+Links a user's Spotify account to enable Sesamy products that integrate with Spotify.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the Spotify account was successfully linked.
+
+### Example
+
+```javascript
+// Link the user's Spotify account
+window.sesamy.products
+  .linkSpotify()
+  .then(success => {
+    if (success) {
+      console.log('Spotify account linked successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error linking Spotify account:', error);
+  });
+```
+
+# Tags API
+
+The Tags API allows for managing user tags, which can be used for user segmentation and personalization.
+
+## `tags.list()`
+
+Fetches all tags associated with the current user.
+
+### Returns
+
+- `Promise<string[]>`: A promise that resolves to an array of tag strings.
+
+### Example
+
+```javascript
+// Get all tags for the current user
+window.sesamy.tags
+  .list()
+  .then(tags => {
+    console.log('User tags:', tags);
+  })
+  .catch(error => {
+    console.error('Error fetching tags:', error);
+  });
+```
+
+## `tags.set(tag: string)`
+
+Sets a tag for the current user. If the tag already exists, it won't create a duplicate.
+
+### Parameters
+
+- `tag` (string): The tag to associate with the user.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the tag was successfully set.
+
+### Example
+
+```javascript
+// Set a tag for the current user
+window.sesamy.tags
+  .set('premium-subscriber')
+  .then(success => {
+    if (success) {
+      console.log('Tag set successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error setting tag:', error);
+  });
+```
+
+## `tags.delete(tag: string)`
+
+Deletes a specific tag from the current user.
+
+### Parameters
+
+- `tag` (string): The tag to remove from the user.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the tag was successfully deleted.
+
+### Example
+
+```javascript
+// Delete a tag from the current user
+window.sesamy.tags
+  .delete('trial-user')
+  .then(success => {
+    if (success) {
+      console.log('Tag deleted successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error deleting tag:', error);
+  });
+```
+
+# Tallies API
+
+The Tallies API allows for tracking counts of various user activities or metrics.
+
+## `tallies.list()`
+
+Lists all tallies for the current user.
+
+### Returns
+
+- `Promise<Tally[]>`: A promise that resolves to an array of tally objects.
+
+### Example
+
+```javascript
+// List all tallies for the current user
+window.sesamy.tallies
+  .list()
+  .then(tallies => {
+    console.log('User tallies:', tallies);
+  })
+  .catch(error => {
+    console.error('Error listing tallies:', error);
+  });
+```
+
+## `tallies.get(id: string)`
+
+Retrieves a specific tally by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the tally to retrieve.
+
+### Returns
+
+- `Promise<Tally>`: A promise that resolves to the tally object.
+
+### Example
+
+```javascript
+// Get a specific tally by ID
+window.sesamy.tallies
+  .get('article-views')
+  .then(tally => {
+    console.log('Tally:', tally);
+    console.log('Current count:', tally.count);
+  })
+  .catch(error => {
+    console.error('Error getting tally:', error);
+  });
+```
+
+## `tallies.push(id: string, item: any)`
+
+Adds an item to a specific tally, incrementing its count.
+
+### Parameters
+
+- `id` (string): The ID of the tally to update.
+- `item` (any): The item to add to the tally.
+
+### Returns
+
+- `Promise<Tally>`: A promise that resolves to the updated tally object.
+
+### Example
+
+```javascript
+// Increment an article view tally
+window.sesamy.tallies
+  .push('article-views', { articleId: 'sid:eUv45QXTrcGNhMJpaCQNe', timestamp: new Date() })
+  .then(updatedTally => {
+    console.log('Updated tally:', updatedTally);
+    console.log('New count:', updatedTally.count);
+  })
+  .catch(error => {
+    console.error('Error updating tally:', error);
+  });
+```
+
+## `tallies.delete(id: string)`
+
+Deletes a specific tally by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the tally to delete.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the tally was successfully deleted.
+
+### Example
+
+```javascript
+// Delete a specific tally
+window.sesamy.tallies
+  .delete('article-views')
+  .then(success => {
+    if (success) {
+      console.log('Tally deleted successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error deleting tally:', error);
+  });
+```
+
+# User Metadata API
+
+The User Metadata API allows for storing and retrieving custom metadata associated with users.
+
+## `userMetadata.list()`
+
+Lists all metadata items for the current user.
+
+### Returns
+
+- `Promise<Record<string, any>>`: A promise that resolves to an object containing all metadata key-value pairs.
+
+### Example
+
+```javascript
+// List all user metadata
+window.sesamy.userMetadata
+  .list()
+  .then(metadata => {
+    console.log('User metadata:', metadata);
+  })
+  .catch(error => {
+    console.error('Error listing user metadata:', error);
+  });
+```
+
+## `userMetadata.get(id: string)`
+
+Retrieves a specific metadata item by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the metadata item to retrieve.
+
+### Returns
+
+- `Promise<any>`: A promise that resolves to the value of the metadata item.
+
+### Example
+
+```javascript
+// Get a specific metadata item
+window.sesamy.userMetadata
+  .get('preferences')
+  .then(value => {
+    console.log('User preferences:', value);
+  })
+  .catch(error => {
+    console.error('Error getting metadata:', error);
+  });
+```
+
+## `userMetadata.set(id: string, value: any)`
+
+Sets a metadata item for the current user.
+
+### Parameters
+
+- `id` (string): The ID of the metadata item to set.
+- `value` (any): The value to assign to the metadata item.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the metadata item was successfully set.
+
+### Example
+
+```javascript
+// Set a user preference metadata item
+window.sesamy.userMetadata
+  .set('preferences', { theme: 'dark', fontSize: 'large' })
+  .then(success => {
+    if (success) {
+      console.log('User preferences saved successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error setting metadata:', error);
+  });
+```
+
+## `userMetadata.delete(id: string)`
+
+Deletes a specific metadata item by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the metadata item to delete.
+
+### Returns
+
+- `Promise<boolean>`: A promise that resolves to `true` if the metadata item was successfully deleted.
+
+### Example
+
+```javascript
+// Delete a metadata item
+window.sesamy.userMetadata
+  .delete('temporary-setting')
+  .then(success => {
+    if (success) {
+      console.log('Metadata item deleted successfully');
+    }
+  })
+  .catch(error => {
+    console.error('Error deleting metadata:', error);
+  });
+```
+
+# Vendors API
+
+The Vendors API provides methods for retrieving information about vendors (publishers) connected to a user.
+
+## `vendors.get()`
+
+Fetches settings for the current vendor based on the authenticated user context.
+
+### Returns
+
+- `Promise<VendorSettings>`: A promise that resolves to the vendor settings object.
+
+### Example
+
+```javascript
+// Get current vendor settings
+window.sesamy.vendors
+  .get()
+  .then(settings => {
+    console.log('Vendor settings:', settings);
+    console.log('Vendor name:', settings.name);
+    console.log('Vendor currency:', settings.currency);
+  })
+  .catch(error => {
+    console.error('Error fetching vendor settings:', error);
+  });
+```
+
+## `vendors.list()`
+
+Lists all publishers connected to the user. This method is not available for publisher tokens.
+
+### Returns
+
+- `Promise<Vendor[]>`: A promise that resolves to an array of vendor objects.
+
+### Example
+
+```javascript
+// List all vendors connected to the user
+window.sesamy.vendors
+  .list()
+  .then(vendors => {
+    console.log('Connected vendors:', vendors);
+    vendors.forEach(vendor => {
+      console.log('Vendor name:', vendor.name);
+      console.log('Vendor ID:', vendor.id);
+    });
+  })
+  .catch(error => {
+    console.error('Error listing vendors:', error);
+  });
+```
+
+# Contracts API
+
+The Contracts API provides methods for managing user contracts, including subscription services.
+
+## `contracts.list()`
+
+Lists all contracts associated with the current user.
+
+### Returns
+
+- `Promise<Contract[]>`: A promise that resolves to an array of contract objects.
+
+### Example
+
+```javascript
+// List all user contracts
+window.sesamy.contracts
+  .list()
+  .then(contracts => {
+    console.log('User contracts:', contracts);
+    contracts.forEach(contract => {
+      console.log('Contract ID:', contract.id);
+      console.log('Contract status:', contract.status);
+      console.log('Contract start date:', contract.startDate);
+    });
+  })
+  .catch(error => {
+    console.error('Error listing contracts:', error);
+  });
+```
+
+## `contracts.get(id: string)`
+
+Retrieves a specific contract by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the contract to retrieve.
+
+### Returns
+
+- `Promise<Contract>`: A promise that resolves to the contract object.
+
+### Example
+
+```javascript
+// Get a specific contract by ID
+window.sesamy.contracts
+  .get('contract-123')
+  .then(contract => {
+    console.log('Contract details:', contract);
+    console.log('Contract status:', contract.status);
+    console.log('Contract type:', contract.type);
+  })
+  .catch(error => {
+    console.error('Error fetching contract:', error);
+  });
+```
+
+## `contracts.cancel(id: string)`
+
+Cancels a specific contract by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the contract to cancel.
+
+### Returns
+
+- `Promise<Contract>`: A promise that resolves to the updated contract object with its status set to canceling or canceled.
+
+### Example
+
+```javascript
+// Cancel a contract
+window.sesamy.contracts
+  .cancel('contract-123')
+  .then(contract => {
+    console.log('Contract canceled successfully');
+    console.log('Updated contract status:', contract.status);
+  })
+  .catch(error => {
+    console.error('Error canceling contract:', error);
+  });
+```
+
+# Bills API
+
+The Bills API allows for retrieving information about user bills.
+
+## `bills.list()`
+
+Lists all bills associated with the current user.
+
+### Returns
+
+- `Promise<Bill[]>`: A promise that resolves to an array of bill objects.
+
+### Example
+
+```javascript
+// List all user bills
+window.sesamy.bills
+  .list()
+  .then(bills => {
+    console.log('User bills:', bills);
+    bills.forEach(bill => {
+      console.log('Bill ID:', bill.id);
+      console.log('Amount:', bill.amount);
+      console.log('Due date:', bill.dueDate);
+      console.log('Status:', bill.status);
+    });
+  })
+  .catch(error => {
+    console.error('Error listing bills:', error);
+  });
+```
+
+## `bills.get(id: string)`
+
+Retrieves a specific bill by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the bill to retrieve.
+
+### Returns
+
+- `Promise<Bill>`: A promise that resolves to the bill object.
+
+### Example
+
+```javascript
+// Get a specific bill by ID
+window.sesamy.bills
+  .get('bill-123')
+  .then(bill => {
+    console.log('Bill details:', bill);
+    console.log('Amount:', bill.amount);
+    console.log('Status:', bill.status);
+    console.log('Due date:', bill.dueDate);
+  })
+  .catch(error => {
+    console.error('Error fetching bill:', error);
+  });
+```
+
+# Transactions API
+
+The Transactions API allows for retrieving information about user transactions.
+
+## `transactions.list()`
+
+Lists all transactions associated with the current user.
+
+### Returns
+
+- `Promise<Transaction[]>`: A promise that resolves to an array of transaction objects.
+
+### Example
+
+```javascript
+// List all user transactions
+window.sesamy.transactions
+  .list()
+  .then(transactions => {
+    console.log('User transactions:', transactions);
+    transactions.forEach(transaction => {
+      console.log('Transaction ID:', transaction.id);
+      console.log('Amount:', transaction.amount);
+      console.log('Date:', transaction.createdAt);
+      console.log('Status:', transaction.status);
+    });
+  })
+  .catch(error => {
+    console.error('Error listing transactions:', error);
+  });
+```
+
+## `transactions.get(id: string)`
+
+Retrieves a specific transaction by its ID.
+
+### Parameters
+
+- `id` (string): The ID of the transaction to retrieve.
+
+### Returns
+
+- `Promise<Transaction>`: A promise that resolves to the transaction object.
+
+### Example
+
+```javascript
+// Get a specific transaction by ID
+window.sesamy.transactions
+  .get('transaction-123')
+  .then(transaction => {
+    console.log('Transaction details:', transaction);
+    console.log('Amount:', transaction.amount);
+    console.log('Status:', transaction.status);
+    console.log('Date:', transaction.createdAt);
+  })
+  .catch(error => {
+    console.error('Error fetching transaction:', error);
+  });
+```
+
 # Polyfills
 
 The library polyfills the following methods for compatibility with older browsers:
@@ -1534,3 +2181,75 @@ The library tracks the following data for attribution purposes and pass it on to
 - `ref`: The referrer passed in the querystring.
 - `referrer`: The referrer URL of the initial page load.
 - `item-src`: The url of the last locked article viewed.
+
+# Events API
+
+The Events API allows for emitting custom events that can be listened to and optionally canceled by other scripts on the page.
+
+## `events.emit(eventName: string, data?: Record<string, any>, cancelable?: boolean)`
+
+Emits a custom event that can optionally be canceled by event listeners.
+
+### Parameters
+
+- `eventName` (string): The name of the event to emit.
+- `data` (Record<string, any>, optional): Additional data to include with the event.
+- `cancelable` (boolean, optional): Whether the event can be canceled by listeners. Defaults to `false`.
+
+### Returns
+
+- `{ canceled: boolean, message?: string }`: An object indicating if the event was canceled and any cancellation message.
+
+### Example
+
+```javascript
+// Emit a non-cancelable event
+window.sesamy.events.emit('article-viewed', { articleId: '12345' });
+
+// Emit a cancelable event and check if it was canceled
+const result = window.sesamy.events.emit('purchase-initiated', { productId: 'premium-sub' }, true);
+
+if (result.canceled) {
+  console.log(`Purchase was canceled: ${result.message}`);
+} else {
+  // Proceed with purchase flow
+  proceedWithPurchase();
+}
+```
+
+## `events.cancel(event: CustomEvent<CancelableEventDetail>, message?: string)`
+
+Cancels an event with an optional message explaining the reason.
+
+### Parameters
+
+- `event` (CustomEvent): The event to cancel.
+- `message` (string, optional): A message explaining why the event was canceled.
+
+### Returns
+
+- `void`
+
+### Example
+
+```javascript
+// Listen for a cancelable event
+window.addEventListener('purchase-initiated', event => {
+  // Check if user already owns the product
+  if (userOwnsProduct(event.detail.data.productId)) {
+    // Cancel the event with a message
+    window.sesamy.events.cancel(event, 'User already owns this product');
+  }
+});
+```
+
+### Use Cases
+
+The Events API can be used for various scenarios where you need to communicate between different components or scripts:
+
+1. **Purchase Flow Interception**: Allow third-party scripts to intercept and potentially cancel purchase flows.
+2. **Content Locking**: Emit events when content is about to be locked/unlocked and allow other scripts to modify this behavior.
+3. **User Authentication**: Notify when users are about to be authenticated and allow other scripts to intervene.
+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:`.