Sesamy JS

The official Sesamy browser JavaScript library (@sesamy/sesamy-js) for handling authentication, analytics, content access, and communication with the Sesamy API.

Difference from Sesamy SDK

This is the browser-focused library for content access control and user experience features. For direct API access in Node.js or server environments, use the Sesamy SDK instead.

Installation

Easiest Setup: Scripts Host

For the simplest integration with automatic configuration and updates, use the Scripts Host service instead of manual installation.

npmyarnpnpm

bash

npm install @sesamy/sesamy-js

bash

yarn add @sesamy/sesamy-js

bash

pnpm add @sesamy/sesamy-js

Requirements

Modern browser with JavaScript enabled
TypeScript 4.5+ (for TypeScript projects)

Quick Start

Recommended: Scripts Host

For production use, we recommend using the Scripts Host for automatic configuration and CDN delivery. The examples below show manual integration.

Script Tag Initialization

The simplest way to use the SDK is via a script tag with JSON configuration:

html

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.sesamy.com/sesamy-js/latest/sesamy-js.min.js"></script>
    <script type="application/json" id="sesamy-js">
      {
        "clientId": "your-client-id"
      }
    </script>
  </head>
  <body>
    <script>
      // Wait for the SDK to be ready
      window.addEventListener('sesamyJsReady', async () => {
        // Check if user is authenticated
        const isAuth = await window.sesamy.auth.isAuthenticated();
        console.log('User authenticated:', isAuth);

        // Get user profile
        if (isAuth) {
          const profile = await window.sesamy.profile.get();
          console.log('User profile:', profile);
        }
      });
    </script>
  </body>
</html>

Programmatic Initialization

You can also initialize the SDK programmatically:

typescript

import { init } from '@sesamy/sesamy-js';

const sesamy = await init({
  clientId: 'your-client-id',
});

// Check authentication
const isAuth = await sesamy.auth.isAuthenticated();

// Get user profile
if (isAuth) {
  const profile = await sesamy.profile.get();
}

Configuration

Basic Configuration

The only required configuration is the clientId:

javascript

{
  "clientId": "your-client-id"
}

Advanced Configuration

javascript

{
  clientId: "your-client-id",
  organization: "org_123",  // Optional: Auth0 organization ID

  // API configuration
  api: {
    namespace: "sesamy",  // Window object namespace (default: "sesamy")
    endpoint: "https://api2.sesamy.com"  // API endpoint
  },

  // Analytics configuration
  analytics: {
    enabled: true,
    endpoint: "https://logs.sesamy.com/events"
  },

  // Authentication configuration
  auth: {
    clientId: "your-client-id",
    organization: "org_123",
    enabled: true,
    domain: "auth.example.com",  // Optional: Custom Auth0 domain
    domains: []  // Optional: Array of auth domains for multi-domain setups
  },

  // Content configuration
  content: [
    {
      type: "article",
      path: "/articles",  // Optional: URL path filter
      pass: "premium",    // Optional: Pass requirement
      price: {
        amount: 9.99,
        currency: "USD"
      },
      paywallUrl: "https://example.com/paywall",
      enablePaywallSettingsUrlFallback: false,  // Optional: Fallback to <sesamy-paywall settings-url>
      selectors: {
        article: { selector: "article" },
        title: { selector: "h1", attribute: "textContent" },
        image: { selector: "img", attribute: "src" },
        // ... other selectors
      }
    }
  ],

  // Transform configuration
  transforms: {
    enabled: false,
    rules: []
  }
}

Multi-Domain Authentication

For applications across multiple domains (white-label, multi-region):

javascript

{
  auth: {
    clientId: "your-client-id",
    domains: [
      "auth.brand1.com",
      "auth.brand2.com",
      "auth.example.co.uk"
    ],
    domain: "default-auth.example.com"  // Fallback domain
  }
}

The SDK automatically selects the appropriate auth domain based on the current page's top-level domain.

Core API

Safely Accessing the API

When building components or modules that need to access Sesamy JS, use this helper function to safely wait for the SDK to be ready:

typescript

export async function getApi(): Promise<SesamyAPI> {
  // If already ready, return immediately
  if (window.sesamy?.isReady()) {
    return window.sesamy;
  }

  // Wait for the ready event with timeout
  return new Promise((resolve, reject) => {
    const timeout = setTimeout(() => {
      window.removeEventListener('sesamyJsReady', onSesamyJsReady);
      if (window.sesamy) {
        resolve(window.sesamy);
      } else {
        reject(new Error('sesamyJsReady event did not occur within the expected time.'));
      }
    }, 5000);

    function onSesamyJsReady() {
      if (!window.sesamy) {
        reject(new Error('Sesamy API is not available'));
      } else {
        clearTimeout(timeout);
        window.removeEventListener('sesamyJsReady', onSesamyJsReady);
        resolve(window.sesamy);
      }
    }

    window.addEventListener('sesamyJsReady', onSesamyJsReady);
  });
}

Usage:

typescript

// In your component or module
async function initComponent() {
  try {
    const sesamy = await getApi();

    // Now safely use the API
    const isAuth = await sesamy.auth.isAuthenticated();
    if (isAuth) {
      const profile = await sesamy.profile.get();
      console.log('User profile:', profile);
    }
  } catch (error) {
    console.error('Failed to initialize Sesamy:', error);
  }
}

initComponent();

This approach:

Returns immediately if the SDK is already ready
Waits for the sesamyJsReady event if not ready yet
Includes a 5-second timeout to prevent hanging
Properly cleans up event listeners

Checking SDK Readiness

For simple synchronous checks:

javascript

// Check if SDK is ready
if (window.sesamy?.isReady()) {
  console.log('SDK is ready');
}

// Or listen for the ready event
window.addEventListener('sesamyJsReady', () => {
  console.log('SDK is ready');
});

API Documentation

Sesamy JS provides a comprehensive set of APIs organized by functionality:

Entitlements - Check and manage user access to content
Subscriptions (Contracts) - Manage user subscriptions
Checkouts - Create and manage purchase flows
Products - Retrieve product information
Bills & Transactions - Access billing history
Attribution - Manage tracking attribution

These are grouped together as they're all SDK wrapper methods providing similar functionality.

Analytics

Event tracking and analytics. Separate because it's an optional feature that can be enabled/disabled independently.

TypeScript Support

The library includes comprehensive TypeScript definitions:

typescript

import { init, SesamyAPI } from '@sesamy/sesamy-js';

const sesamy: SesamyAPI = await init({
  clientId: 'your-client-id',
});

// Full type safety
const profile: Profile | null = await sesamy.profile.get();
const entitlements: Entitlement[] = await sesamy.entitlements.list();

Next Steps

Authentication Guide - Learn about login flows and user management
Content Management - Set up paywalls and locked content
API Reference - Complete API documentation for all methods
Scripts Host API - Use the CDN for automatic configuration

Sesamy JS ​

Installation ​

Requirements ​

Quick Start ​

Script Tag Initialization ​

Programmatic Initialization ​

Configuration ​

Basic Configuration ​

Advanced Configuration ​

Multi-Domain Authentication ​

Core API ​

Safely Accessing the API ​

Checking SDK Readiness ​

API Documentation ​

Authentication ​

Content ​

API Reference ​

Analytics ​

TypeScript Support ​

Next Steps ​

Sesamy JS

Installation

Requirements

Quick Start

Script Tag Initialization

Programmatic Initialization

Configuration

Basic Configuration

Advanced Configuration

Multi-Domain Authentication

Core API

Safely Accessing the API

Checking SDK Readiness

API Documentation

Authentication

Content

API Reference

Analytics

TypeScript Support

Next Steps