Beam Web SDK¶

Beam Web SDK is a library built with TypeScript that can be used in both Node.js and browser environments. It is distributed in multiple module formats (ESM, CommonJS, IIFE) and provides full TypeScript declarations.

Table of Contents¶

Installation
Using the SDK
Documentation
Contributing
License

Installation¶

Install the SDK into your project via npm (or pnpm):

# npm
npm install beamable-sdk
# pnpm
pnpm add beamable-sdk

Using the SDK¶

You can use the Beam SDK across different JavaScript environments:

CommonJS (Node.js)¶

const { Beam } = require('beamable-sdk');
const beam = await Beam.init({
  cid: 'YOUR_CUSTOMER_ID',
  pid: 'YOUR_PROJECT_ID',
});
console.log(beam.player.id);

ES Modules (Node.js)¶

import { Beam } from 'beamable-sdk';
const beam = await Beam.init({
  cid: 'YOUR_CUSTOMER_ID',
  pid: 'YOUR_PROJECT_ID',
});
console.log(beam.player.id);

Browser (IIFE)¶

<script src="https://unpkg.com/beamable-sdk"></script>
<script>
  // global variable exposed as Beamable
  const { Beam, BeamEnvironment } = Beamable;
  const beam = await Beam.init({
    cid: 'YOUR_CUSTOMER_ID',
    pid: 'YOUR_PROJECT_ID',
  });
  console.log(beam.player.id);
</script>

Documentation¶

Find detailed API references, usage examples, and integration guides for the Beam Web SDK:

Beam Web SDK Documentation

Token storage and automatic refresh¶

The SDK stores authentication tokens using a platform-appropriate strategy and automatically handles access token renewal when needed.

Automatic refresh¶

All HTTP requests that receive a 401 response will trigger an automatic access token refresh using the stored refresh token. On successful refresh, the original request is retried with the new access token. If the refresh fails, stored tokens are cleared and the error is propagated.

Refresh failures¶

If the SDK fails to refresh the access token (for example, the refresh token has expired), it throws a RefreshAccessTokenError and stored tokens are cleared. Consumers should catch this error to start a new login flow:

import { RefreshAccessTokenError } from 'beamable-sdk';

try {
  await beam.api.someService.someEndpoint();
} catch (error) {
  if (error instanceof RefreshAccessTokenError) {
    // Refresh failed: redirect user to login
    redirectToLoginPage();
  }
  throw error;
}

Custom token storage¶

If you need a different storage mechanism, implement the TokenStorage interface and pass it in the configuration:

import { TokenStorage } from 'beamable-sdk';

class MyTokenStorage implements TokenStorage {
  /* implement getAccessToken, setAccessToken, ... */
}

const beam = await Beam.init({
  cid: 'YOUR_CUSTOMER_ID',
  pid: 'YOUR_PROJECT_ID',
  tokenStorage: new MyTokenStorage(),
});

License¶

This project is licensed under the MIT License.