@pulsebeam/server: Open-Source Server-Side SDK

Provides a server-side SDK for generating secure tokens that your client-side applications can use. For example, clients using the @pulsebeam/peer WebRTC Peer-to-Peer Communication SDK.

Simplifying WebRTC Development

PulseBeam simplifies real-time application development by managing the complexities of WebRTC, including:

• Signaling Protocol: Handles the exchange of information required to set up WebRTC connections.
• Automatic Reconnection: Maintains stability by automatically re-establishing connections when disruptions occur.
• Media & Data Support: Transmit audio, video, and/or data channels within your applications.
• Infrastructure: Provides the underlying structure for reliable communication.

Why Use @pulsebeam/server?

• Secure Client Authentication: Generate JWT tokens to control access and prevent unauthorized connections.
• Simplified Integration: Seamlessly integrate @pulsebeam/server into your existing server-side infrastructure or deploy serverlessly.
• Reduced Server Load: Offload WebRTC signaling, TURN, and media routing to PulseBeam's infrastructure.

Before You Begin

Because PulseBeam usage and potential charges are incurred based on client consumption, you may want to authenticate and/or authorize users before issuing them tokens.

Refer to the PulseBeam pricing page for more details: https://pulsebeam.dev

TURN is one kind of usage you will incur from clients. The underlying WebRTC connection will at times use TURN servers to relay data between peers instead of flowing directly peer to peer. Becuase TURN servers are able to traverse and overcome client network limitations to ensure a connection between your peers. You can expect TURN to be required 6-14% of the time but this will vary based on demographics of your user base. PulseBeam offers hosted TURN servers, data usage associated with cost of ingress and egress on these servers will be reflected in your PulseBeam account.

Installation

Install and import the package using npm, deno, or yarn:

Use with npm:

npm i @pulsebeam/server

Using deno:

deno add jsr:@pulsebeam/server

Using yarn:

yarn add @pulsebeam/server

Import Symbol

Use with Node.js runtime

import * as server from "@pulsebeam/server/node";

Use with Deno runtime

import * as server from "@pulsebeam/server/deno";

Use with Cloudflare Workerd runtime

import * as server from "@pulsebeam/server/workerd";

Usage

Here's a step-by-step guide to using @pulsebeam/server to generate a token:

Example

import { AccessToken, PeerPolicy, PeerClaims } from "@pulsebeam/server";

// Step 1: Initialize app
const { API_KEY, API_SECRET } = process.env;
const app = new AccessToken(API_KEY, API_SECRET);

// Step 2: Listen for JWT requests from your clients'
router.post('/auth', (req, res) => {
  // Step 3: Generate JWT and respond with JWT
  const claims = new PeerClaims("myGroup1", "myPeer1");
  const policy = new PeerPolicy("*", "*");
  claims.setAllowPolicy(policy);
  
  const ttlSeconds = 3600;
  const token = app.createToken(claims, ttlSeconds);
  res.json({ groupId, peerId, token });
});

Explanation

• Set <API_KEY> and <API_SECRET> with your credentials obtained from PulseBeam.
• PeerClaims specify the peer's group and ID within your application.
• PeerPolicy define which peers this peer can connect to.
• createToken generates a JWT token based on the provided claims and expiration time.
• Respond to your client's request with the generated JWT token, group ID, and peer ID.

Another Example

Here: https://github.com/PulseBeamDev/pulsebeam-js/blob/main/demo-cdn/main.js

Documentation

PulseBeam Resources

For documentation, API keys, and usage scenarios, please refer to the official PulseBeam documentation:

• @pulsebeam/server: https://jsr.io/@pulsebeam/server
• @pulsebeam/peer: https://jsr.io/@pulsebeam/peer
• PulseBeam Documentation: https://pulsebeam.dev

JWT Resources

For a deeper understanding of JWT (JSON web token) concepts, consult the RFC: https://datatracker.ietf.org/doc/html/rfc7519

WebRTC Resources

For a deeper understanding of WebRTC concepts, consult the official WebRTC documentation: https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API

⚠️ Security Warning

Keep your API credentials secure!

• The <API_KEY> and <API_SECRET> are sensitive credentials that grant access to your application’s PulseBeam resources. Do not expose these credentials in:

  • Public repositories.
  • Client-side code.
  • Shared or unencrypted environments.

• Treat tokens generated by this CLI as sensitive data. Tokens should only be shared with trusted clients.

Recommended Practices:

1. Environment Variables: Store your API credentials securely in environment variables instead of hardcoding them in your codebase.

   export PULSEBEAM_API_KEY="your_api_key"
   export PULSEBEAM_API_SECRET="your_api_secret"

2. Access Controls: Regularly rotate API credentials and limit their scope to only necessary permissions.

3. Auditing: Monitor usage of your credentials and investigate any unauthorized activity.

💳 Billing and Token Usage

Be aware: Generating and using tokens can incur billing charges. Each token enables interactions with PulseBeam's infrastructure, which may contribute to your account’s usage costs.

Billing Best Practices:

1. Understand Your Plan: Familiarize yourself with the details of your billing plan. For more information, visit our Billing Page.
2. Monitor Usage: Keep track of token usage to avoid unexpected charges. Utilize PulseBeam’s dashboards and APIs for real-time monitoring.
3. Token Expiration: Set appropriate duration values for tokens to limit unnecessary usage. Tokens with a longer duration may result in increased billing if misused.
4. Audit Token Distribution: Ensure tokens are only distributed to trusted clients to avoid misuse that could drive up costs.

⚠️ Important Billing Warning

• Tokens allow access to PulseBeam's infrastructure and may result in charges depending on your usage.
• Misuse or unauthorized distribution of tokens can lead to unexpected billing costs.
• Ensure you monitor your account's activity regularly and revoke tokens that are no longer needed.

For detailed information on billing and usage policies, visit our Billing Page.