@bridgecord/sdk

Framework-agnostic SDK for embedding Bridgecord chat into any web application. Zero dependencies for iframe mode; uses socket.io-client only when using direct connections.

Installation

npm install @bridgecord/sdk

Quick Start — Iframe (Simple)

The easiest way to add Bridgecord to your app. The SDK renders an iframe that handles everything for you.

import { Bridgecord } from '@bridgecord/sdk';

const bc = new Bridgecord({ embedId: 'your-embed-id' });

// Mount the full embed (channels + chat + rewards)
bc.mount(document.getElementById('chat'), { height: 600 });

// Listen for events from the embed
bc.on('message', (msg) => {
  console.log('New message:', msg.content);
});

bc.on('auth', (user) => {
  console.log('User authenticated:', user.displayName);
});

// Clean up when done
bc.destroy();

Mount a single-channel chat view

bc.mountChat(document.getElementById('chat'), {
  channelId: 'channel-id', // optional — defaults to first channel
  height: 400,
});

Pre-authenticated users

const bc = new Bridgecord({
  embedId: 'your-embed-id',
  sessionToken: 'user-jwt-token',
});

Advanced — Direct Socket.io Connection (Headless)

For developers who want complete rendering control. No iframe — you get raw data and render it yourself.

import { Bridgecord } from '@bridgecord/sdk';

// Requires socket.io-client as a peer dependency for this mode
const conn = await Bridgecord.connect({
  embedId: 'your-embed-id',
  sessionToken: 'user-jwt-token',
});

// Access embed config
console.log(conn.config.channels);

// Join a channel
conn.joinChannel(conn.config.channels[0].id);

// Listen for messages
conn.on('messages:initial', (msgs) => {
  console.log('History:', msgs);
});

conn.on('message', (msg) => {
  console.log('New:', msg.content);
});

// Send a message
await conn.sendMessage('Hello from the SDK!');

// Fetch rewards
const rewards = await conn.fetchRewards();
const leaderboard = await conn.fetchLeaderboard(10);

// Clean up
conn.destroy();

API Reference

new Bridgecord(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | embedId | string | Yes | Your embed ID from the dashboard | | sessionToken | string | No | Pre-auth JWT token | | apiUrl | string | No | API base URL (default: https://api.bridgecord.io) | | embedUrl | string | No | Embed app URL (default: https://embed.bridgecord.io) |

Instance Methods

• mount(container, options?) — Render full embed iframe
• mountChat(container, options?) — Render single-channel chat iframe
• on(event, handler) — Subscribe to events
• off(event, handler) — Unsubscribe from events
• destroy() — Remove iframe and clean up

Bridgecord.connect(options) (Static)

Returns a BridgecordConnection with:

• config — Embed configuration
• currentChannel — Currently joined channel ID
• joinChannel(id) — Join a channel
• leaveChannel() — Leave current channel
• sendMessage(content) — Send a message
• fetchRewards() — Get user's reward profile
• fetchLeaderboard(limit?, offset?) — Get leaderboard
• on(event, handler) / off(event, handler) — Event listeners
• destroy() — Disconnect and clean up

Events

| Event | Payload | Description | |-------|---------|-------------| | message | BridgecordMessage | New message received | | messages:initial | BridgecordMessage[] | Channel history loaded | | auth | BridgecordUser | User authenticated | | reward | BridgecordRewardEvent | Reward earned | | ready | void | Embed/connection ready | | error | Error | Error occurred | | channel:changed | BridgecordChannel | Channel switched |

TypeScript

Full TypeScript support with exported types for all events, messages, users, channels, and rewards. Import any type directly:

import type { BridgecordMessage, BridgecordUser, BridgecordChannel } from '@bridgecord/sdk';