npm - @sesamy/sesamy-js - Versions diffs - 1.119.1 → 1.120.0 - Mend

@sesamy/sesamy-js 1.119.1 → 1.120.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -1,22 +1,533 @@
 # sesamy-js
-The Sesamy browser javascript API
+The Sesamy browser JavaScript API.
-The project handles analytics, authentication and communication with the Sesamy API
+`@sesamy/sesamy-js` is the publisher-side runtime that powers paywalls,
+authentication, content gating, and analytics on Sesamy-integrated sites. It
+exposes a single `window.sesamy` object (the namespace is configurable) with
+~30 namespaced services backed by the Sesamy API, plus ready-made handlers for
+URL/hash triggers, content selectors, DOM transforms, consent, and DCA
+(Capsule) decryption.
-## Analytics
+# Installation
-The analytics module is used to track events and page views. It is using the [GetAnalytics](https://getanalytics.io/) library to send events to the Sesamy interaction endpoint.
+```bash
+npm install @sesamy/sesamy-js
+# or
+pnpm add @sesamy/sesamy-js
+```
+The package ships several entry points so you can pick the build that fits
+your integration:
+| Import                             | Purpose                                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `@sesamy/sesamy-js`                | Core library — `init()` and the `SesamyAPI` surface (ESM/CJS).                                                                       |
+| `@sesamy/sesamy-js/auth0-plugin`   | Auth0 SPA auth plugin. Required for SPA login unless using BFF cookies.                                                              |
+| `@sesamy/sesamy-js/capsule-plugin` | Capsule (DCA) decryption plugin. Required when `capsule.enabled` is `true`.                                                          |
+| `@sesamy/sesamy-js/bootstrap`      | Tiny inline loader (`sesamyBootstrap` + `renderBootstrapScript`) that orchestrates the script chain and prefetches `/auth/userinfo`. |
+Pre-built IIFE bundles for classic `<script>` tags are also published:
+- `dist/sesamy-js.iife.js` — core, all-in-one (loadable directly without ESM).
+- `dist/auth0-plugin.iife.js` — auth plugin as an IIFE that registers
+  `window.auth0Plugin.createAuth0Plugin`.
+- `dist/capsule-plugin.iife.js` — capsule plugin as an IIFE that registers
+  `window.capsulePlugin.createCapsulePlugin`.
+- `dist/bootstrap.iife.js` — bootstrap loader as an IIFE.
+Publishers using Sesamy's hosted scripts host typically don't reference these
+files directly; instead they let the bootstrap loader resolve them from
+`https://scripts.sesamy.com/s/{clientId}/{name}/{version}.js`.
+# Quick start
+The recommended way to embed sesamy-js on a publisher site is via the
+**bootstrap loader**. It downloads the auth/capsule plugins, the components
+package, and the core bundle in parallel (in the right execution order) and
+prefetches `/auth/userinfo` so the user's session is hydrated by the time the
+core finishes loading.
+Drop this in `<head>`:
+```html
+<script type="application/json" id="sesamy-js">
+  {
+    "clientId": "your-client-id",
+    "environment": "prod"
+  }
+</script>
+<script src="https://scripts.sesamy.com/s/your-client-id/bootstrap/stable.js"></script>
+```
+The bootstrap script auto-detects the `<script id="sesamy-js">` config element
+and pulls forward `clientId`, `environment`, `version`, `src`, plugin-version
+overrides, fallback options, and the plugin/component flags below. No extra
+inline call is needed.
+Once the chain finishes, sesamy-js is reachable as `window.sesamy` (or the
+namespace you set in `api.namespace`) and the `sesamyJsReady` event fires.
+```javascript
+window.addEventListener('sesamyJsReady', () => {
+  console.log('Authenticated?', window.sesamy.auth.isAuthenticated());
+});
+```
+# Integration modes
+sesamy-js supports several distinct integration shapes. Pick the one that
+matches your stack — they are not mutually exclusive (e.g. you can use the
+bootstrap loader together with BFF cookie auth).
+## Bootstrap loader (recommended)
+Use when: you embed sesamy-js on a server-rendered publisher site and want a
+single `<script>` in `<head>` that handles everything. Sets
+`window.__sesamyBoot` with a parallel userinfo prefetch promise that the core
+reuses, eliminating a round-trip from the critical path.
+The bootstrap loader (`@sesamy/sesamy-js/bootstrap`) ships a
+`sesamyBootstrap(options)` function that:
+1. Optionally fetches `/auth/userinfo` in parallel with the bundle download
+   when the `sesamy_is_authenticated=true` hint cookie is present (or skips
+   if `skipAuthPrefetch` is `true`).
+2. Injects the auth0-plugin, capsule-plugin (if enabled), sesamy-components,
+   and the sesamy-js core as `<script async=false>` tags so they execute in
+   order while downloading in parallel.
+3. Falls back to `fallbackSrc` if the primary core never installs
+   `window[namespace]` within `fallbackTimeoutMs` (default 3000ms).
+Auto-run from the config element:
+```html
+<script type="application/json" id="sesamy-js">
+  { "clientId": "demo", "environment": "prod" }
+</script>
+<script src="https://scripts.sesamy.com/s/demo/bootstrap/stable.js"></script>
+```
+Or call it manually (useful from SSR templates, before the config element is
+in the DOM):
+```html
+<script>
+  sesamyBootstrap({
+    clientId: 'demo',
+    environment: 'prod',
+    version: 'stable',
+    fallbackSrc: 'https://scripts-fallback.sesamy.com/.../sesamy-js.iife.js',
+    debug: false,
+  });
+</script>
+```
+For server-rendered pages, use `renderBootstrapScript()` to serialise the
+function plus its options into an inline script body:
+```typescript
+import { renderBootstrapScript } from '@sesamy/sesamy-js/bootstrap';
+const inline = renderBootstrapScript({
+  clientId: 'demo',
+  environment: 'prod',
+  skipAuthPrefetch: false,
+});
+// emit `<script>${inline}</script>` in your HTML response
+```
+### `BootstrapOptions`
+| Option                 | Type              | Default     | Purpose                                                                                                                    |
+| ---------------------- | ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `clientId`             | `string`          | —           | Resolves script chain URLs to `https://scripts.sesamy.com/s/{clientId}/{name}/{version}.js`. Required unless `src` is set. |
+| `version`              | `string`          | `'stable'`  | Version channel served by scripts-host.                                                                                    |
+| `componentsVersion`    | `string`          | `version`   | Per-entry override for `sesamy-components`.                                                                                |
+| `auth0PluginVersion`   | `string`          | `version`   | Per-entry override for `auth0-plugin`.                                                                                     |
+| `capsulePluginVersion` | `string`          | `version`   | Per-entry override for `capsule-plugin`.                                                                                   |
+| `src`                  | `string`          | —           | Override the core bundle URL. Disables plugin/component chaining (escape hatch for self-contained bundles).                |
+| `environment`          | `'dev' \| 'prod'` | `'prod'`    | Origin to resolve `clientId` against (`scripts.sesamy.com` vs `scripts.sesamy.dev`).                                       |
+| `fallbackSrc`          | `string`          | —           | Secondary bundle URL loaded if the core fails or doesn't install `window[namespace]` in time.                              |
+| `fallbackTimeoutMs`    | `number`          | `3000`      | Timeout before the fallback fires.                                                                                         |
+| `apiBaseUrl`           | `string`          | inferred    | Base URL for the userinfo prefetch. When unset, falls back to `auth.baseUrl` from the page config (so the prefetch matches the runtime BFF plugin) and then to same-origin. |
+| `namespace`            | `string`          | `'sesamy'`  | Window namespace the core installs onto.                                                                                   |
+| `skipAuthPrefetch`     | `boolean`         | `false`     | Skip the `/auth/userinfo` prefetch (e.g. when injecting the id-token via SSR).                                             |
+| `skipComponents`       | `boolean`         | `false`     | Skip loading `sesamy-components`.                                                                                          |
+| `loadAuth0Plugin`      | `boolean`         | inferred    | Force auth0-plugin loading on/off. Default: load unless `auth.useHttpCookies === true` in the config element.              |
+| `loadCapsulePlugin`    | `boolean`         | inferred    | Force capsule-plugin loading on/off. Default: load when `capsule.enabled === true` in the config element.                  |
+| `debug`                | `boolean`         | `false`     | Emit `[sesamy-boot]` log lines for chain decisions, prefetch source, load/error events, and fallback triggers.             |
+## Auto-init from `<script id="sesamy-js">`
+Use when: you've already loaded the core bundle some other way (custom CDN,
+self-host) and just want sesamy-js to bootstrap itself from a JSON config
+block.
+The core looks for a `<script type="application/json" id="sesamy-js">` element
+and, if found, calls `init()` with the parsed config. Only `clientId` is
+required.
+```html
+<script type="application/json" id="sesamy-js">
+  {
+    "clientId": "demo",
+    "environment": "prod",
+    "auth": { "domain": "auth.example.com" },
+    "api": { "namespace": "sesamy" }
+  }
+</script>
+<script src="/path/to/sesamy-js.iife.js"></script>
+```
+## Programmatic `init(config)`
+Use when: your app is an SPA that already manages its own bootstrapping (e.g.
+you import sesamy-js from npm and want full control over when it initialises).
+```typescript
+import { init } from '@sesamy/sesamy-js';
+const sesamy = await init({
+  clientId: 'demo',
+  vendorId: 'demo',
+  environment: 'prod',
+  auth: { domain: 'auth.example.com' },
+});
+if (await sesamy.auth.isAuthenticated()) {
+  const profile = await sesamy.profile.get();
+}
+```
+`init()` returns the `SesamyAPI` object and also installs it on
+`window[namespace]` for parity with the auto-init path. Pass `awaitAllServices:
+true` in the config to make the returned promise wait for analytics, auth,
+content, transforms, and capsule to finish initialising; the default is to
+return early and run those services in the background.
+You can also pass plugins explicitly instead of relying on
+`window.auth0Plugin` / `window.capsulePlugin` auto-detection:
+```typescript
+import { init } from '@sesamy/sesamy-js';
+import { createAuth0Plugin } from '@sesamy/sesamy-js/auth0-plugin';
+import { createCapsulePlugin } from '@sesamy/sesamy-js/capsule-plugin';
+await init(config, {
+  authPlugin: createAuth0Plugin(),
+  capsulePlugin: createCapsulePlugin(),
+});
+```
+## BFF / cookie-based authentication
+Use when: your backend already terminates Sesamy auth (the API proxy's Token
+Handler) and you want sesamy-js to use HttpOnly cookies instead of the SPA
+Auth0 plugin. The auth0-plugin is **not** loaded; login/logout/refresh go
+through `/auth/login`, `/auth/callback`, `/auth/logout`, and `/auth/userinfo`
+on the same origin by default.
+```html
+<script type="application/json" id="sesamy-js">
+  {
+    "clientId": "demo",
+    "vendorId": "demo",
+    "auth": { "useHttpCookies": true },
+    "api": { "endpoint": "" }
+  }
+</script>
+```
+To namespace auth under a sub-path (e.g. when running behind a first-party
+proxy that reserves the top-level `/auth/*` path for something else), set
+`auth.baseUrl`:
+```html
+<script type="application/json" id="sesamy-js">
+  {
+    "clientId": "acme",
+    "auth": { "useHttpCookies": true, "baseUrl": "/sesamy" }
+  }
+</script>
+```
+The plugin then calls `/sesamy/auth/userinfo`, `/sesamy/auth/{vendor}/login`,
+and `/sesamy/auth/logout`. `auth.baseUrl` is independent of `api.endpoint` —
+the API and auth proxies may live on different sub-paths or hosts.
+Notes:
+- When `useHttpCookies` is `true` and no `api.endpoint` is set, sesamy-js
+  defaults the API endpoint to `/api` on the current origin (cross-origin
+  cookies can't reach `api2.sesamy.com`).
+- For SSR, set `auth.idToken` to a server-injected id-token and sesamy-js
+  treats the user as authenticated immediately, skipping `/auth/userinfo`.
+  Alternatively include
+  `<script type="application/json" id="sesamy-server-state">{"idToken":"eyJ..."}</script>` —
+  the cookie-auth plugin reads it automatically.
+- The bootstrap loader detects `useHttpCookies === true` in the config element
+  and skips the auth0-plugin entry in the chain.
+## Capsule (DCA) decryption
+Use when: your articles ship as encrypted DCA payloads and you need
+sesamy-js to fetch unlock tokens, decrypt the manifest, and inject the
+plaintext into `data-dca-content-name="..."` placeholders.
+```html
+<script type="application/json" id="sesamy-js">
+  {
+    "clientId": "demo",
+    "auth": { "useHttpCookies": true },
+    "capsule": { "enabled": true, "autoProcess": true }
+  }
+</script>
+<!-- Register the capsule plugin before sesamy-js auto-inits -->
+<script type="module">
+  import { createCapsulePlugin } from '@sesamy/sesamy-js/capsule-plugin';
+  window.capsulePlugin = { createCapsulePlugin };
+</script>
+<script src="/path/to/sesamy-js.iife.js"></script>
+```
+When `autoProcess` is `true` (the default), sesamy-js detects the DCA
+manifest on page load, calls the unlock endpoint, decrypts every
+`data-dca-content-name` block, and starts a `MutationObserver` for SPA
+navigation. To process content manually call `sesamy.capsule.processPage()`,
+or call `sesamy.content.unlock(selector)` for per-article control.
+## IIFE / classic `<script>` tag
+Use when: the host site has no build step. Drop the IIFE bundle in directly:
+```html
+<script type="application/json" id="sesamy-js">
+  { "clientId": "demo" }
+</script>
+<script src="https://scripts.sesamy.com/s/demo/sesamy-js/stable.js"></script>
+```
+The IIFE bundle assumes the auth0-plugin / capsule-plugin IIFEs (if needed)
+have already executed and registered their factories on `window`. The
+bootstrap loader automates that ordering — using IIFEs without the bootstrap
+means you're responsible for inserting plugin scripts before the core script.
+# Configuration
+`init()` and the auto-init JSON block accept the same `Config` shape:
+```typescript
+interface Config {
+  clientId: string; // required
+  vendorId: string; // required
+  environment?: 'dev' | 'prod';
+  organization?: string; // Auth0 org id
+  api?: Partial<ApiConfig>;
+  analytics?: Partial<AnalyticsConfig>;
+  auth?: Partial<AuthConfig>;
+  content?: ContentNode[];
+  transform?: TransformConfig;
+  capsule?: CapsuleConfig;
+  consent?: ConsentConfig;
+  awaitAllServices?: boolean; // default: false
+}
+```
+## `api`
+| Field         | Type              | Default                       | Purpose                                                                                                  |
+| ------------- | ----------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `namespace`   | `string`          | `'sesamy'`                    | Property on `window` where the API is installed.                                                         |
+| `endpoint`    | `string`          | `https://api2.sesamy.com`     | Absolute URL or relative path. Use a relative path (e.g. `/api`) when proxying through your own backend. |
+| `environment` | `'dev' \| 'prod'` | inherits `Config.environment` | Picks `api2.sesamy.com` vs `api2.sesamy.dev`.                                                            |
+When `auth.useHttpCookies` is `true` the API client switches to
+`credentials: 'include'` and drops the `Authorization` header.
+## `auth`
+| Field              | Type       | Default | Purpose                                                                                                                                                           |
+| ------------------ | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`          | `boolean`  | `true`  | Disable auth entirely (anonymous-only mode).                                                                                                                      |
+| `domain`           | `string`   | —       | Single custom Auth0 domain.                                                                                                                                       |
+| `domains`          | `string[]` | —       | Multiple auth domains for multi-tenant / white-label setups. The library picks the entry whose top-level domain matches the current page; falls back to `domain`. |
+| `useRefreshTokens` | `boolean`  | `false` | Enable refresh-token rotation in the auth0-plugin.                                                                                                                |
+| `useHttpCookies`   | `boolean`  | `false` | Switch to cookie-based BFF auth. Skips the auth0-plugin even if registered.                                                                                       |
+| `baseUrl`          | `string`   | `""`    | Base URL the BFF plugin prepends to its `/auth/*` paths. Set when running behind a first-party proxy that namespaces auth under a sub-path (e.g. `"/sesamy"` → `/sesamy/auth/userinfo`, `/sesamy/auth/{vendor}/login`). Independent of `api.endpoint`.                            |
+| `idToken`          | `string`   | —       | Server-injected id-token for SSR. When set, sesamy-js treats the user as authenticated without calling `/auth/userinfo`.                                          |
+See [Cross-domain authentication](#cross-domain-authentication) below for how
+the library picks between popup and redirect login on cross-domain setups.
+## `analytics`
+| Field         | Type              | Default  | Purpose                                       |
+| ------------- | ----------------- | -------- | --------------------------------------------- |
+| `enabled`     | `boolean`         | `true`   | Toggle the analytics service.                 |
+| `environment` | `'dev' \| 'prod'` | inherits | Picks `logs.sesamy.com` vs `logs.sesamy.dev`. |
+The analytics service is built on [GetAnalytics](https://getanalytics.io/) and
+ships these events to the Sesamy interaction endpoint:
+- Page views, triggered on router updates.
+- Scroll events at 25%, 50%, 75%, 100%.
+- Active vs idle duration.
+- Custom events emitted via `analytics.track(name, properties)`.
+- All events emitted through `events.emit(...)` (prefixed with `event:`).
+When `consent.enabled` is `true`, analytics storage is gated on the
+`statistics` consent flag — see [Consent](#consent) below.
+## `content`
+An array of `ContentNode` objects describing how to discover articles in the
+DOM and (optionally) what paywall rules apply. Each node currently has
+`type: 'article'` and supports the following matchers and selectors:
+```typescript
+{
+  type: 'article',
+  // Matchers — all optional, AND-ed together
+  path?: string,                           // current URL contains this path
+  queryParam?: { key: string; value: string },
+  headers?: { name: string; contains: string },
+  userAgentContains?: string,
+  // Pricing / paywall metadata (forwarded to checkout)
+  pass?: string,
+  price?: { amount: number; currency: string },
+  paywallUrl?: string,
+  enablePaywallSettingsUrlFallback?: boolean,
+  // DOM selectors (defaults provided — override per site)
+  selectors?: {
+    article?:     { selector: string; attribute?: string },
+    image?:       { selector: string; attribute?: string },
+    title?:       { selector: string; attribute?: string },
+    excerpt?:     { selector: string; attribute?: string },
+    price?:       { selector: string; attribute?: string },
+    currency?:    { selector: string; attribute?: string },
+    accessLevel?: { selector: string; attribute?: string },
+    url?:         { selector: string; attribute?: string },
+    pass?:        { selector: string; attribute?: string },
+    id?:          { selector: string; attribute?: string },
+    paywallUrl?:  { selector: string; attribute?: string },
+  }
+}
+```
+See the [Content](#content-1) section below for `content.list/get/hasAccess/unlock`
+and the modal/notification-bar UI helpers.
+## `transform`
+Selector-based DOM rules applied after content discovery (and after Capsule
+decryption when DCA is enabled).
+```typescript
+{
+  enabled?: boolean,
+  rules: Array<{
+    selector: string,
+    transform: 'insert' | 'replace' | 'remove' | 'gradient' | 'wrap',
+    contentType: 'html' | 'selector' | 'url',
+    content?: string,
+    insertionPoint?: 'before' | 'after' | 'inside',
+    path?: string,                       // only apply on matching URLs
+    entitlement?: string,                // only apply when user has this entitlement
+    authenticated?: boolean,             // only apply for logged-in users
+  }>
+}
+```
+See [Transforms](#transforms) below for full semantics and examples.
+## `capsule`
+| Field         | Type           | Default | Purpose                                                                          |
+| ------------- | -------------- | ------- | -------------------------------------------------------------------------------- |
+| `enabled`     | `boolean`      | `false` | Initialise the DCA client. Required for any decryption to happen.                |
+| `clientBound` | `boolean`      | `false` | Wrap the unlock key with RSA-OAEP for client-bound transport.                    |
+| `rsaKeySize`  | `2048 \| 4096` | `2048`  | RSA key size when `clientBound` is `true`.                                       |
+| `autoProcess` | `boolean`      | `true`  | Auto-detect DCA manifests and decrypt on page load + observe for SPA navigation. |
+When `enabled` is `true` the bootstrap loader pulls in
+`@sesamy/sesamy-js/capsule-plugin` automatically. If you self-host, register
+the plugin on `window.capsulePlugin` before sesamy-js auto-inits or pass it
+via `init(config, { capsulePlugin })`.
-The following events are tracked:
+## `consent`
-- Page views, with events triggered on router updates
-- Scroll events, with events triggered on scroll at 25%, 50%, 75%, and 100%
-- Active and idle duration
+| Field             | Type                                                   | Default                                   | Purpose                                                                                           |
+| ----------------- | ------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `enabled`         | `boolean`                                              | —                                         | Required. When `true`, analytics storage is gated on consent.                                     |
+| `cmp`             | `'cookiebot' \| 'onetrust' \| 'google-consent-mode'`   | —                                         | Auto-integrate with the named consent management platform.                                        |
+| `defaultConsent`  | `Partial<ConsentState>`                                | `{ statistics: false, marketing: false }` | Initial consent state before the CMP responds.                                                    |
+| `onConsentChange` | `(update: (c: Partial<ConsentState>) => void) => void` | —                                         | Custom CMP integration — the callback receives a function to push consent updates into sesamy-js. |
-## API
+`ConsentState` has two fields: `statistics` and `marketing`. Read/write at
+runtime via `sesamy.consent.get/set/has` — see [Consent](#consent-api) below.
-The following methods are available on the `sesamy` object:
+## `awaitAllServices`
+When `true`, the promise returned by `init()` resolves only after analytics,
+auth, content, transforms, and capsule have finished initialising. Default
+`false` so the page can keep rendering while those services start in the
+background.
+# Authentication configuration
+## Custom domains
+For a single custom Auth0 domain:
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',
+    domain: 'auth.example.com',
+  },
+}
+```
+### Multiple domains (multi-tenant / white-label)
+For applications that operate across multiple domains, use the `domains`
+array. The library extracts the top-level domain from the current page URL
+and picks the matching entry; if no entry matches, it falls back to `domain`,
+then to the default Sesamy auth domain.
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',
+    domains: [
+      'auth.brand1.com',
+      'auth.brand2.com',
+      'auth.example.co.uk',
+    ],
+    domain: 'default-auth.example.com',  // fallback if no match
+  },
+}
+```
+## Cross-domain authentication
+When the application domain differs from the auth domain's top-level domain,
+the library automatically uses popup-based login on Safari/iOS and Android
+to handle the cross-domain cookies properly. Desktop browsers stay on
+redirect-based login regardless.
+| App domain        | Auth domain          | Mobile   | Desktop  |
+| ----------------- | -------------------- | -------- | -------- |
+| `app.example.com` | `auth.different.com` | Popup    | Redirect |
+| `app.example.com` | `auth.example.com`   | Redirect | Redirect |
+# API reference
+All services hang off `window[namespace]` (default `window.sesamy`) and the
+object returned by `init()`. The following methods are available — full
+per-method documentation follows below.
 - amendments
   - create: create an amendment to a contract
@@ -28,12 +539,14 @@ The following methods are available on the `sesamy` object:
   - set: set the attributions for a user
 - auth
   - getUser: fetches the user's profile
+  - getTokenSilently: retrieves a token without user interaction
   - isAuthenticated: checks if the user is authenticated
   - login: smart login that automatically chooses popup or redirect based on browser context
+  - loginWithPopup: opens a popup window to complete the login
   - loginWithRedirect: redirects the user to the login page
   - logout: logs the user out
-  - setToken: stores a token in session storage
-  - getTokenSilently: retrieves a token without user interaction
+  - refresh: re-checks the authentication state from the auth provider
+  - setToken: stores a token in local storage and triggers the authenticated event
 - bills
   - get: get a bill by id
   - list: lists all the user's bills
@@ -41,27 +554,43 @@ The following methods are available on the `sesamy` object:
   - detectAdblock: detects if an ad blocker is enabled
   - isInAppBrowser: detects if the browser is an in-app browser
   - isIncognito: detects if the browser is in incognito mode
+- capsule
+  - getClient: returns the underlying DCA client (when `capsule.enabled` is true)
+  - processPage: detect and decrypt every DCA manifest on the current page
 - checkouts
   - create: creates a checkout session
   - get: gets a checkout session by id
   - update: updates a checkout session
 - clearCache: clears the cache for the sesamy-js library
+- consent
+  - get: returns the current consent state
+  - has: checks whether a specific consent flag is granted
+  - set: updates the consent state and re-evaluates analytics storage
 - content
-  - list: get all articles based on the configured selectors
   - get: get an article based on an element or a selector
   - getLanguage: get the current language
-  - unlock: retrieves the locked content using an element or a css selector
   - getPropertyFromHTML: extracts a property from HTML content
+  - hasAccess: checks if the user has access to a specific article element
+  - list: get all articles based on the configured selectors
+  - showModal: opens the paywall modal (requires sesamy-components)
+  - showNotificationBar: shows an inline notification bar above/below content
+  - unlock: retrieves the locked content using an element or a css selector
 - contracts
   - cancel: cancel a contract by id
   - get: get a contract by id
   - list: lists all the user's contracts
+- diagnostics
+  - collect: gathers a snapshot of profile, entitlements, contracts, tags, and tallies for support tickets
+  - send: collects diagnostics and uploads them to the Sesamy diagnostics endpoint
 - entitlements
   - access: fetches the user's access URL for an entitlement
   - get: gets a single entitlement by id
   - hasAccess: checks if the user has access to a specific item
   - list: lists the user's entitlements
   - signedLinks: lists signed links registered in the current session
+- events
+  - cancel: cancels a cancelable event with an optional reason message
+  - emit: emits a custom event that can optionally be canceled by listeners
 - flags
   - get: gets a feature flag value
   - set: sets a feature flag value
@@ -139,189 +668,6 @@ The library can trigger actions based on query parameters. The following query p
 The library can read the access token from the hash. It is not the preferred way of logging in a user but can be used when redirecting the user across domains where a cookie-based solution is not possible. The hash is not sent to the server so the is no risk of leaking the token. The token hash is passed like this: `#access_token=<token>`
-## Usage
-The script can either be initiated with a JSON object in a script tag or by calling the init method.
-The script will look for a script tag with the id `sesamy-js`, and if it isn't found it will wait for a call to the init function before initializing. The only required part is the `clientId` attribute.
-```html
-<script type="application/json" id="sesamy-js">
-  {
-    "clientId": "demo"
-  }
-</script>
-```
-These are the available configuration options, with their default values:
-```javascript
-{
-  clientId: null,
-  organization: null,
-  api: {
-    namespace: 'sesamy',
-    endpoint: 'https://api2.sesamy.com'
-  },
-  analytics: {
-    enabled: true,
-    endpoint: 'https://logs.sesamy.com/events'
-  },
-  auth: {
-    clientId: null,
-    organization: null,
-    enabled: true,
-    domain: null,        // Optional: custom Auth0 domain (e.g., 'auth.example.com')
-    domains: []          // Optional: array of auth domain strings for multi-domain setups
-  },
-  content: [
-    {
-      type: 'article',
-      path: '/articles',  // Optional: matches URLs containing this path
-      pass: 'premium',    // Optional: pass requirement
-      price: {           // Optional: price information
-        amount: 9.99,
-        currency: 'USD'
-      },
-      paywallUrl: 'https://example.com/paywall',  // Optional: custom paywall URL
-      enablePaywallSettingsUrlFallback: false,  // Optional: enable fallback to sesamy-paywall settings-url
-      selectors: {
-        article: { selector: 'article' },
-        image: { selector: 'img', attribute: 'src' },
-        title: { selector: 'h1', attribute: 'textContent' },
-        excerpt: { selector: 'p', attribute: 'textContent' },
-        price: { selector: 'article', attribute: 'data-price' },
-        currency: { selector: 'article', attribute: 'data-currency' },
-        url: { selector: 'link', attribute: 'href' },
-        id: { selector: 'article', attribute: 'data-id' },
-        pass: { selector: 'article', attribute: 'data-pass' },
-        }
-      }
-    ],
-  tranforms: {
-    enabled: false,
-    rules: []
-  }
-}
-```
-# Authentication Configuration
-The `auth` configuration object controls how the Sesamy library handles user authentication. Below are the available options:
-## Basic Configuration
-```javascript
-{
-  auth: {
-    clientId: 'your-client-id',  // Required: Your Auth0 client ID
-    organization: 'org_123',      // Optional: Auth0 organization ID
-    enabled: true                  // Optional: Enable/disable authentication (default: true)
-  }
-}
-```
-## Custom Domain Configuration
-### Single Domain
-For custom Auth0 domains, use the `domain` property:
-```javascript
-{
-  auth: {
-    clientId: 'your-client-id',
-    domain: 'auth.example.com'    // Optional: Custom Auth0 domain
-  }
-}
-```
-### Multiple Domains (Multi-tenant/White-label)
-For applications that operate across multiple domains (e.g., white-label solutions, multi-region setups), use the `domains` array. The library will automatically select the appropriate auth domain based on the current page's top-level domain:
-```javascript
-{
-  auth: {
-    clientId: 'your-client-id',
-    domains: [
-      'auth.brand1.com',
-      'auth.brand2.com',
-      'auth.example.co.uk'
-    ],
-    domain: 'default-auth.example.com'  // Optional: fallback if no match found
-  }
-}
-```
-**How it works:**
-1. The library extracts the top-level domain from the current page URL
-2. Each domain in the `domains` array is checked - the library derives its top-level domain (e.g., `auth.brand1.com` → `brand1.com`)
-3. If the current page's top-level domain matches a domain in the array, that auth domain is used
-4. If no match is found, it falls back to the `domain` property
-5. If neither is available, it uses the default Sesamy auth domain
-**Example scenarios:**
-```javascript
-// Multi-region setup
-{
-  auth: {
-    clientId: 'your-client-id',
-    domains: [
-      'auth.us.example.com',    // Used when on any *.example.com page
-      'auth.uk.example.co.uk',  // Used when on any *.example.co.uk page
-      'auth.au.example.com.au'  // Used when on any *.example.com.au page
-    ]
-  }
-}
-// White-label setup
-{
-  auth: {
-    clientId: 'your-client-id',
-    domains: [
-      'auth.client1.com',
-      'auth.client2.com',
-      'auth.client3.com'
-    ],
-    domain: 'auth.myplatform.com'  // Default for unlisted domains
-  }
-}
-```
-## Complete Example
-```javascript
-{
-  clientId: "demo",
-  organization: "org_abc123",
-  auth: {
-    clientId: "demo",
-    organization: "org_abc123",
-    enabled: true,
-    domains: [
-      'auth.example.com',
-      'auth.example.co.uk'
-    ],
-    domain: 'auth.fallback.com'
-  }
-}
-```
-## Cross-Domain Authentication
-When your application domain differs from your Auth0 domain's top-level domain, the library automatically uses popup-based login on mobile browsers (Safari/iOS and Android) to handle cross-domain authentication properly. Desktop browsers will use redirect-based login even when cross-domain.
-**Examples:**
-- Your app: `app.example.com`, Auth domain: `auth.different.com`
-  - Mobile (Safari/iOS/Android): Popup login
-  - Desktop: Redirect login
-- Your app: `app.example.com`, Auth domain: `auth.example.com` (same TLD)
-  - All browsers: Redirect login
 # Custom HTML Attributes
 ## Visibility
@@ -702,6 +1048,26 @@ getTokenSilently()
 - If the publisher uses a custom domain for authentication (so the auth domain matches the publisher's top-level domain), the session token will be stored in an `httpOnly` cookie. In this case, malicious scripts can only access short-lived access tokens, not the session token itself.
 - Always ensure you trust third-party scripts running on your site, as they may be able to access tokens stored in local storage.
+## `auth.refresh()`
+Forces sesamy-js to re-check the authentication state from the configured auth
+plugin (Auth0 SPA or BFF cookie). Useful after an external login or logout has
+changed cookies/storage outside the SDK's awareness, or after a window
+re-focus where you suspect the session may have been invalidated server-side.
+### Returns
+`Promise<void>` — resolves once the auth state has been re-evaluated and any
+state-change events (`sesamyJsAuthenticated`, `sesamyJsLogout`) have fired.
+### Example
+```javascript
+window.addEventListener('focus', async () => {
+  await window.sesamy.auth.refresh();
+});
+```
 # Entitlements API
 ## `entitlements.get(entitlementId: string)`
@@ -1933,6 +2299,68 @@ async function unlockSpecificContent() {
 }
 ```
+#### `content.showModal(options: ModalOptions)`
+Opens the Sesamy paywall modal. Requires `sesamy-components` to be loaded
+(included by the bootstrap loader by default; otherwise load
+`@sesamy/open-web-components` yourself).
+### Parameters
+- `options` (`ModalOptions`):
+  - `articleElementOrSelector` (`Element | string`, optional): Article whose
+    metadata seeds the modal. Defaults to the first matched article.
+  - `paywallId` (`string`, optional): Paywall configuration to render. Falls
+    back to the article's `paywallUrl` selector.
+  - `onClose` (`() => void`, optional): Called when the user dismisses the
+    modal.
+### Returns
+- `Promise<ModalResult>`: Resolves with `{ action: 'purchased' | 'closed' | 'login' }`
+  when the modal is closed.
+### Example
+```javascript
+const result = await window.sesamy.content.showModal({
+  articleElementOrSelector: 'article#main',
+});
+if (result.action === 'purchased') {
+  await window.sesamy.content.unlock('article#main');
+}
+```
+#### `content.showNotificationBar(options: NotificationBarOptions)`
+Shows an inline notification bar pinned to the top or bottom of the viewport.
+Useful for unobtrusive prompts (e.g. "Subscribe for unlimited access") that
+don't block reading.
+### Parameters
+- `options` (`NotificationBarOptions`):
+  - `position` (`'top' | 'bottom'`): Where to attach the bar.
+  - `articleElementOrSelector` (`Element | string`, optional): Source of
+    metadata.
+  - `paywallId` (`string`, optional): Paywall configuration.
+  - `onClose` (`() => void`, optional): Called on dismissal.
+### Returns
+- `Promise<NotificationBarResult>`: Resolves with the user action when the
+  bar is dismissed.
+### Example
+```javascript
+window.sesamy.content.showNotificationBar({
+  position: 'bottom',
+  articleElementOrSelector: 'article#main',
+});
+```
 ### 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.
@@ -2738,6 +3166,145 @@ window.sesamy.transactions
   });
 ```
+# Capsule (DCA) API
+Available when `capsule.enabled` is `true` in the config and the capsule
+plugin is registered (auto-loaded by the bootstrap, or registered via
+`window.capsulePlugin` / `init(config, { capsulePlugin })`).
+## `capsule.processPage()`
+Detects every DCA manifest currently in the DOM, calls the unlock endpoint
+for each, decrypts the payload, and injects the plaintext into the matching
+`data-dca-content-name` placeholder. Called automatically on page load when
+`capsule.autoProcess` is `true` (default) and again whenever the SPA mutates
+new DCA blocks into the DOM.
+### Returns
+`Promise<void>` — resolves once every detected manifest has been processed
+(or has failed gracefully).
+### Example
+```javascript
+// Manually retry decryption after a login completes
+window.addEventListener('sesamyJsAuthenticated', async () => {
+  await window.sesamy.capsule.processPage();
+});
+```
+## `capsule.getClient()`
+Returns the underlying [`@sesamy/capsule`](https://www.npmjs.com/package/@sesamy/capsule)
+DCA client. Use this if you need lower-level access (custom resource fetchers,
+manual decryption, advanced introspection). Returns `undefined` when capsule
+is disabled or the plugin failed to load.
+### Example
+```javascript
+const dca = window.sesamy.capsule.getClient();
+const decoded = dca?.decodeManifest(rawManifest);
+```
+# Consent API
+Available always; gates analytics storage when `consent.enabled` is `true` in
+the config. Integrate with your CMP via the `consent.cmp` config or the
+`onConsentChange` callback, or drive consent imperatively from these
+functions.
+## `consent.get()`
+Returns the current consent state — an object with `statistics` and
+`marketing` booleans.
+### Example
+```javascript
+const state = window.sesamy.consent.get();
+if (state.statistics) {
+  // analytics storage is allowed
+}
+```
+## `consent.set(state: Partial<ConsentState>)`
+Updates one or more consent flags and re-evaluates analytics storage
+immediately.
+### Parameters
+- `state` (`Partial<ConsentState>`): Partial consent object — only the keys
+  you want to change need to be provided.
+### Example
+```javascript
+// User accepted statistics but not marketing
+window.sesamy.consent.set({ statistics: true, marketing: false });
+```
+## `consent.has(type: 'statistics' | 'marketing')`
+Returns `true` when the named consent flag is granted.
+### Example
+```javascript
+if (window.sesamy.consent.has('marketing')) {
+  loadMarketingPixel();
+}
+```
+# Diagnostics API
+Tools to capture a snapshot of the user's runtime state for support tickets.
+Both methods read profile, entitlements, contracts, tags, and tallies via the
+already-initialised API.
+## `diagnostics.collect(fallbackId?: string)`
+Returns the diagnostics payload as an object without uploading it — useful if
+you want to render it in your own support form.
+### Parameters
+- `fallbackId` (`string`, optional): Identifier used in the payload when no
+  authenticated user id is available.
+### Returns
+`Promise<DiagnosticsPayload>` — profile, entitlements, contracts, tags,
+tallies, library version, and environment metadata.
+## `diagnostics.send(fallbackId?: string)`
+Collects diagnostics and uploads them to the Sesamy diagnostics endpoint.
+Returns the diagnostics id you can paste into a support ticket.
+### Parameters
+- `fallbackId` (`string`, optional): Same as `collect`.
+### Returns
+`Promise<{ id: string }>`.
+### Example
+```javascript
+async function reportProblem() {
+  const { id } = await window.sesamy.diagnostics.send();
+  alert(`Diagnostics submitted — reference: ${id}`);
+}
+```
+You can also trigger this without writing any code by appending
+`?sesamy-user-diagnostics=true` to the URL — sesamy-js will collect and
+submit automatically once initialisation completes.
 # Polyfills
 The library polyfills the following methods for compatibility with older browsers:
@@ -2887,3 +3454,23 @@ const consumeUrl = client.links.generateConsumeLink(
 - **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
+# Debugging
+sesamy-js has several debug surfaces that are off by default and zero-cost
+when off:
+- **Verbose runtime logs.** Append `?sesamy-debug=true` to the URL or set
+  `localStorage.debug = true`. Calls to `sesamy.log(...)` and the SDK's
+  internal logger flush to the console.
+- **Bootstrap logs.** Pass `debug: true` to `sesamyBootstrap(...)` (or the
+  bootstrap config element). Emits `[sesamy-boot]` lines for chain entry
+  selection, userinfo prefetch source, script load/error events, and
+  fallback trigger reasons. Useful for diagnosing chain regressions without
+  a HAR capture.
+- **User diagnostics.** Append `?sesamy-user-diagnostics=true` to collect a
+  snapshot of profile, entitlements, contracts, tags, and tallies and upload
+  it to the Sesamy diagnostics endpoint. The payload id is logged to the
+  console for support tickets — see [Diagnostics API](#diagnostics-api).
+- **Library version.** `sesamy.getVersion()` returns the running version, in
+  case multiple bundles end up on the page.