@sesamy/sesamy-js

sesamy-js

The Sesamy browser javascript API

The project handles analytics, authentication and communication with the Seasmy API

Analytics

The analytics module is used to track events and page views. It is using the GetAnalytics library to send events to the Sesamy interaction endpoint.

The following events are tracked:

• Page views, with events triggered on router updates

API

The following methods are available on the sesamy object:

• init: Initializes the sesamy-js library
• auth
  • getUser: fetches the user's profile
  • isAuthenticated: checks if the user is authenticated
  • loginWithRedirect: redirects the user to the login page
  • logout: logs the user out
  • setToken: stores a token in session storage
• entitlements
  • get: gets a single entitlement by id
  • list: lists the user's entitlements
  • access: fetches the user's access url for an entitlement
  • signedLinks: lists and signedLinks registered in the current session
• profile
  • get: fetches the user's profile
  • update: updates the user's profile
  • openHostedAccountPage: opens the hosted account page
  • isSpotifyLinked: returns true if the user has linked their Spotify account
  • unlinkSpotify: unlinks the user's Spotify account
• tags
  • get: fetches the user's tags
  • set: sets a tag for the user
  • delete: deletes a tag for the user
• userMetadata
  • get: get the user's metadata by id
  • list: list all the user's metadata
  • set: sets the user's metadata
  • delete: deletes the user's metadata by id
• tallies
  • get: get a tally for a user by id
  • list: list all tallies for a user
  • push: push an item to a tally
  • delete: delete a tally by id
• bills
  • get: get a bill by id
  • list: lists all the user's bills
• contracts
  • get: get a contract by id
  • list: lists all the user's contracts
• subscriptions:
  • list: lists all the user's subscriptions
• product
  • get: get a product by sku
  • autoOnboard: trigger the auto-onboarding process for a product by sku
• getVersion: returns the version of the sesamy-js library
• getPaymentIssues: returns a list of failed payments and cards that will expire
• generateLink: creates 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.
• clearCache: clears the cache for the sesamy-js library

Events

The following events are emitted by the sesamy-js library:

• sesamyJsReady - Emitted when the sesamy-js library is ready to be used
• sesamyJsAuthenticated - Emitted when the user is authenticated
• sesamyJsClearCache - Emitted when the cache is cleared
• sesamyJsLogout - Emitted when the user logs out
• sesamyJsPurchase - Emitted after a purchase is completed and passes an itemSrc property with the source of the purchase

Query parameters

The library can trigger actions based on query parameters. The following query parameters are supported:

• sesamy-refresh. If present, the library will clear the cache and emit a sesamyJsClearCache event.
• sesamy-user. If present, the library will validate that the user is authenticated with the correct email. If not, the user will be logged out and a new login with be initiated.
• sesamy-login. If present, the library will validate that the user is authenticated. If not, the user will be logged out and a new login with be initiated.
• sesamy-purchase. Triggers a sesamyJsPurchase event.

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.

<script type="application/json" id="sesamy-js">
  {
    "clientId": "demo"
  }
</script>

These are the available configuration options, with their default values:

{
  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,
    endpoint: 'https://auth.sesamy.com',
    redirectUri: window.location.origin
  },
}

Auth API

isAuthenticated()

Checks if the user is currently authenticated. This function verifies the existence of a valid session by checking both the local storage for an access token and the state of the Auth0 client.

Returns

• boolean: Returns true if the user is authenticated either via local storage tokens or the Auth0 client; otherwise, it returns false.

Example

The following example demonstrates how to check if a user is currently authenticated:

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

isAuthenticated()
  .then(isAuth => {
    if (isAuth) {
      console.log('User is authenticated.');
    } else {
      console.log('User is not authenticated.');
    }
  })
  .catch(error => {
    console.error('Error checking authentication status:', error);
  });

loginWithRedirect(options?: LoginWithRedirectOptions)

Initiates a login flow that redirects the user to an Auth0 hosted login page. Once the user authenticates, they will be redirected back to the specified redirect_uri within your application.

Parameters

• options (optional): An object containing customization options for the login flow.
  • appState: (optional, object) Used to store state before doing the redirect.
  • authorizationParams: (optional, object) Additional parameters to include in the authorization request.
    • audience: (optional, string) The audience to request access to.
    • scope: (optional, string) The scope of the access request.
    • login_hint: (optional, string) A hint to pre-fill the username on the login page.
    • organization: (optional, string) The organization to authenticate with.
    • redirect_uri: (optional, string) The URL to redirect the user to after login.

Returns

This function returns a Promise that resolves when the redirect is successfully initiated.

Example

The following example demonstrates how to use loginWithRedirect to initiate a login flow with an email address pre-filled:

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

// Optionally pass the user's email to pre-fill on the login form
const loginOptions = {
  authorizationParams: {
    login_hint: '[e-mail]',
  },
};

// Redirect the user to the login page
loginWithRedirect(loginOptions);

logout(options?: LogoutOptions)

Terminates the user's session and optionally redirects the user to a specified URL after logout. This function clears any local session tokens and interacts with the Auth0 API to end the session.

Parameters

• options (optional): An object containing customization options for the logout process.
  • returnTo: (optional, string) The URL to redirect users to after logging out. Defaults to the current page URL if not provided.

Returns

This function does not return a value. It causes a redirect to the specified returnTo URL or performs a page refresh if no URL is provided.

Example

The following example demonstrates how to log out a user and redirect them to the homepage:

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

// Specify the URL to redirect to after logout
const logoutOptions = {
  returnTo: 'https://www.yourdomain.com',
};
// Redirects the user to the auth server to log out
logout(logoutOptions);

setToken(accessToken: string, expiresIn?: number)

Stores the provided access token in local storage and optionally sets an expiration time for it. Additionally, this function parses the access token to extract user information and triggers an authentication event.

Parameters

• accessToken (string): The access token to store and use for session management.
• expiresIn (optional, number): The time in seconds from now when the token should expire.

Returns

This function does not return a value but triggers an event indicating that a user has been authenticated with the new token.

Example

The following example demonstrates how to store an access token and set an expiration time:

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

// Example access token and expiration period
const accessToken = 'your.access.token';
const expiresIn = 3600; // 1 hour in seconds

setToken(accessToken, expiresIn)
  .then(() => {
    console.log('Token set successfully and user authenticated.');
  })
  .catch(error => {
    console.error('Failed to set token:', error);
  });