Scarif Messaging SDK

Type-safe SDK for the Scarif Messaging service. Embed chat in your app — rooms, members, and real-time messages scoped to your users.

Identity (read this first)

Messaging is not Scarif-platform chat. You (the Scarif customer) embed this SDK in your product. Ids on rooms and messages are your app-user ids (user_abc, a Firebase uid, etc.) — not Scarif dashboard user uuids.

| Who | What | Auth | |-----|------|------| | Customer (you) | Scarif account + API key (sk_live_…) | Mint tokens on your server only | | App user | Your product's logged-in user | Short-lived JWT from mint; never the API key |

The API key must not ship to the browser. Your backend mints a token for the logged-in app user; the client holds that JWT only.

Installation

npm install @scarif/messaging-sdk

Quick Start

1. Your server — mint a token

After your user logs in, mint an app-user JWT with your API key:

import { createClient } from '@scarif/messaging-sdk';

const serverClient = createClient({ apiKey: 'sk_live_…' });
const { token } = await serverClient.authenticate('user_abc'); // your app's user id
// Pass `token` to your frontend (session, API response, etc.)

2. Your app — chat as that user

import { createClient } from '@scarif/messaging-sdk';

const client = createClient({ baseUrl: 'https://stoorplek.onrender.com' });
client.setUserToken(tokenFromYourServer);

const room = await client.createRoom('General Chat');
const rooms = await client.getRooms();

await client.addMembers(room.id, ['user_def456']);

const unsubscribe = client.subscribe(room.id, (message) => {
  console.log(`${message.sender_id}: ${message.content}`);
});

await client.sendMessage(room.id, 'Hello world!');

const { messages, has_more } = await client.getMessages(room.id, { limit: 50 });

unsubscribe();
client.destroy();

Features

• Two-plane auth — API key on your server; app-user JWT in the client.
• Real-time — WebSocket via short-lived tickets (no API key in the WS URL).
• Room management — Create rooms, manage memberships.
• Message history — Paginated access to past messages.
• Type-safe — Full TypeScript support.
• Lightweight — Zero runtime dependencies; works in browser and Node.js.

API Reference

createClient(options)

• options.apiKey (optional): Your Scarif API key. Required only for authenticate() on your server.
• options.baseUrl (optional): API base URL (default: https://stoorplek.onrender.com).

Auth

• authenticate(appUserId): Mint an app-user JWT (server-side). appUserId is your user's id, not a Scarif uuid. Sets the token on this client instance.
• setUserToken(token): Restore a previously minted JWT (typical browser flow).

Rooms

• createRoom(name, metadata?)
• getRooms()
• getRoom(roomId)

Members

• addMembers(roomId, userIds) — userIds are your app-user ids.
• removeMember(roomId, userId)

Messages

• sendMessage(roomId, content, metadata?) — sender_id is set server-side from the JWT.
• getMessages(roomId, options?) — options.limit (default 50, max 100), options.before (ISO cursor).

Real-time

• subscribe(roomId, onMessage, onError?) — Returns an unsubscribe function. Connects via POST /messaging/ws-tickets → wss://…/messaging/rooms/:id/ws?ticket=….
• destroy() — Closes all WebSocket connections.

Authentication

| Layer | Credential | |-------|------------| | Token mint (your server) | Authorization: Bearer sk_live_… | | REST (your app) | Authorization: Bearer <app-user JWT> | | WebSocket | ?ticket=… from ws-tickets endpoint |

Error Handling

All methods throw MessagingError on failure.

import { MessagingError } from '@scarif/messaging-sdk';

try {
  await client.getRoom('invalid-id');
} catch (error) {
  if (error instanceof MessagingError) {
    console.error(`Error ${error.status}: ${error.message}`);
  }
}

License

MIT