@sesamy/sesamy-js 1.13.7 → 1.15.0

package/README.md

@@ -118,6 +118,15 @@ These are the available configuration options, with their default values:
     endpoint: 'https://auth.sesamy.com',
     redirectUri: window.location.origin
   },
+  content: {
+    article: {
+      select: 'article'
+    }
+  },
+  tranforms: {
+    enabled: false,
+    rules: []
+  }
 }
 ```
 
@@ -248,3 +257,176 @@ setToken(accessToken, expiresIn)
     console.error('Failed to set token:', error);
   });
 ```
+
+# Services
+
+## `generateLink(params: GenerateAccountLink | GenerateConsumeLink)`
+
+Generates a link to a Sesamy hosted service such as account or consume. If the user is authenticated, the link will be signed so that the user can access the service without logging in again.
+
+### Parameters
+
+- params (GenerateAccountLink | GenerateConsumeLink): The parameters for generating the link.
+  - target (string): The target service, either 'account' or 'consume'.
+  - sku (string, required for 'consume' target): The SKU of the product to consume.
+  - episodeId (string, optional for 'consume' target): The ID of the episode to consume.
+  - shorten (boolean, optional): If true, the link will be shortened.
+  - ttl (number, optional): The time-to-live for the shortened link in seconds.
+  - redirectUrl (string, optional): The URL to redirect to after the link is accessed.
+
+### Returns
+
+string: The generated link URL. If shorten is true, the shortened URL is returned.
+
+### Example
+
+The following example demonstrates how to generate a link to the Sesamy account page:
+
+```javascript
+import { generateLink } from '@sesamy/sesamy-js';
+
+// Generate a link to the account page
+const linkParams = {
+  target: 'account',
+  shorten: true,
+  ttl: 3600, // 1 hour in seconds
+  redirectUrl: 'https://www.yourdomain.com/account',
+};
+
+generateLink(linkParams)
+  .then(link => {
+    console.log('Generated link:', link);
+  })
+  .catch(error => {
+    console.error('Error generating link:', error);
+  });
+```
+
+And here is an example for generating a link to consume a specific product:
+
+```javascript
+import { generateLink } from '@sesamy/sesamy-js';
+
+// Generate a link to consume a product
+const linkParams = {
+  target: 'consume',
+  sku: 'product-sku',
+  episodeId: 'episode-id',
+  shorten: true,
+  ttl: 3600, // 1 hour in seconds
+  redirectUrl: 'https://www.yourdomain.com/consume',
+};
+
+generateLink(linkParams)
+  .then(link => {
+    console.log('Generated link:', link);
+  })
+  .catch(error => {
+    console.error('Error generating link:', error);
+  });
+```
+
+## Transform
+
+The transform module allows for dynamic content manipulation based on specified rules. This can include inserting, replacing, or removing elements on a webpage.
+
+### Configuration
+
+The transform configuration is defined within the `Config` interface. The following properties are available:
+
+- `enabled` (boolean, optional): Enables or disables the transform module.
+- `rules` (array): An array of rule objects that define the transformations to apply.
+
+Each rule object contains the following properties:
+
+- `selector` (string): A CSS selector to target elements on the page.
+- `transform` (string): The type of transformation to apply. Valid values are 'insert', 'replace', and 'remove'.
+- `content` (string, optional): The content to insert or replace. Required for 'insert' and 'replace' transforms.
+- `contentType` (string): Specifies the type of content. Valid values are 'html', 'selector', and 'url'.
+- `path` (string, optional): A regular expression to match the URL path. If provided, the rule will only apply when the path matches the current URL.
+- `entitlement` (string, optional): Specifies an entitlement required for the rule to apply.
+- `authenticated` (boolean, optional): Specifies if the rule should only apply to authenticated users.
+
+### Example Configuration
+
+Below is an example configuration for the transform module:
+
+```json
+{
+  "transform": {
+    "enabled": true,
+    "rules": [
+      {
+        "selector": "#example",
+        "transform": "replace",
+        "content": "<p>New content</p>",
+        "contentType": "html"
+      },
+      {
+        "selector": ".ad-banner",
+        "transform": "remove"
+      },
+      {
+        "selector": ".insert-content",
+        "transform": "insert",
+        "content": "#source-element",
+        "contentType": "selector"
+      },
+      {
+        "selector": ".load-from-url",
+        "transform": "insert",
+        "content": "https://example.com/content",
+        "contentType": "url"
+      }
+    ]
+  }
+}
+```
+
+### Usage
+
+To use the transform module, include the configuration in your initialization script:
+
+```html
+<script type="application/json" id="sesamy-js">
+  {
+    "clientId": "demo",
+    "transform": {
+      "enabled": true,
+      "rules": [
+        {
+          "selector": "#example",
+          "transform": "replace",
+          "content": "<p>New content</p>",
+          "contentType": "html"
+        },
+        {
+          "selector": ".ad-banner",
+          "transform": "remove"
+        },
+        {
+          "selector": ".insert-content",
+          "transform": "insert",
+          "content": "#source-element",
+          "contentType": "selector"
+        },
+        {
+          "selector": ".load-from-url",
+          "transform": "insert",
+          "content": "https://example.com/content",
+          "contentType": "url"
+        }
+      ]
+    }
+  }
+</script>
+```
+
+This configuration will replace the content of the element with the ID `example`, remove elements with the class `ad-banner`, insert the content of the element with the ID `source-element` into elements with the class `insert-content`, and load content from a URL into elements with the class `load-from-url`.
+
+### Notes
+
+- The `content` property is required for 'insert' and 'replace' transforms.
+- The `contentType` property specifies how to interpret the `content` property: as raw HTML, a CSS selector, or a URL to fetch content from.
+- The `path` property can be used to apply rules conditionally based on the current URL.
+- The `authenticated` property ensures that rules only apply to authenticated users if set to true.