@borealise/pipeline 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,252 @@
+# @borealise/pipeline
+
+Official Borealise realtime pipeline client.
+
+This package provides a typed WebSocket client for Borealise pipeline events, including:
+
+- identify and session bootstrap
+- heartbeat management
+- dispatch event subscriptions
+- reconnect with backoff
+- strongly typed opcodes and payloads
+
+## Runtime support
+
+- Browser: works out of the box using native WebSocket.
+- Node.js: you must provide a WebSocket implementation, usually ws.
+
+## Installation
+
+Install the package:
+
+```bash
+npm install @borealise/pipeline
+```
+
+If you run this in Node.js, install ws too:
+
+```bash
+npm install ws
+```
+
+## Quick start (browser)
+
+```ts
+import { createPipeline, Events } from '@borealise/pipeline'
+
+const pipeline = createPipeline({
+  url: 'wss://prod.borealise.com/ws',
+  tokenProvider: () => localStorage.getItem('token'),
+  loggerName: 'Pipeline',
+})
+
+pipeline.onConnection('onReady', (ready) => {
+  console.log('ready session', ready.session_id)
+  pipeline.subscribe([Events.USER_UPDATE, Events.ROOM_CHAT_MESSAGE])
+})
+
+pipeline.onConnection('onDisconnect', (code, reason) => {
+  console.log('disconnected', code, reason)
+})
+
+pipeline.connect()
+```
+
+## Quick start (Node.js with ws)
+
+Node has no global WebSocket by default. Inject one via webSocketFactory.
+
+```ts
+import WebSocket from 'ws'
+import { createPipeline, Events } from '@borealise/pipeline'
+
+const pipeline = createPipeline({
+  url: 'wss://prod.borealise.com/ws',
+  tokenProvider: () => process.env.BOREALISE_TOKEN,
+  webSocketFactory: (url) => new WebSocket(url) as unknown as WebSocket,
+})
+
+pipeline.on(Events.USER_UPDATE, (payload) => {
+  console.log('user update', payload)
+})
+
+pipeline.connect()
+```
+
+## How the pipeline works
+
+### 1. Connect
+
+When you call connect(), the client opens the WebSocket and moves state to connecting.
+
+### 2. HELLO handshake
+
+Server sends HELLO with:
+
+- session_id
+- heartbeat_interval
+
+Client starts heartbeat timer with jitter and resolves auth token from tokenProvider.
+
+### 3. Identify
+
+If tokenProvider returns a token, the client sends IDENTIFY.
+
+### 4. READY
+
+On successful auth, server sends READY.
+
+Client:
+
+- moves state to identified
+- stores user/session metadata
+- resubscribes previous event subscriptions
+
+### 5. Dispatch
+
+Server emits DISPATCH frames with event code and payload.
+
+Client fan-outs events to:
+
+- event listeners registered via on(event, listener)
+- connection listener onDispatch
+- optional dispatch bridge set via setDispatchHandler
+
+### 6. Reconnect behavior
+
+On non-terminal disconnects, client reconnects automatically with backoff:
+
+- 1000ms
+- 2000ms
+- 5000ms
+- 10000ms
+- 30000ms
+
+Max attempts: 10.
+
+No reconnect for normal/explicit auth close codes.
+
+## State model
+
+Possible connection states:
+
+- disconnected
+- connecting
+- connected
+- reconnecting
+- identified
+
+Useful getters:
+
+- pipeline.state
+- pipeline.user
+- pipeline.isConnected
+- pipeline.isIdentified
+
+## API surface
+
+### Connection
+
+- connect()
+- disconnect()
+
+### Authentication and presence
+
+- identify(token)
+- updatePresence(status, activity?)
+
+### Subscriptions
+
+- subscribe(eventCodes)
+- unsubscribe(eventCodes)
+
+### Chat
+
+- sendChatMessage(roomSlug, content)
+
+### Event listeners
+
+- on(eventCode, listener)
+- off(eventCode, listener)
+- onConnection(eventName, listener)
+- offConnection(eventName, listener)
+
+Connection event names:
+
+- onConnect
+- onDisconnect
+- onReconnect
+- onStateChange
+- onReady
+- onError
+- onDispatch
+
+## Important options
+
+createPipeline options:
+
+- url: required pipeline endpoint
+- tokenProvider: optional callback returning auth token
+- loggerName: optional logger scope
+- webSocketFactory: required for Node.js and custom environments
+
+## Typed constants and helpers
+
+The package exports protocol constants and helper functions:
+
+- Opcodes
+- Events
+- Presence
+- Activity
+- Roles
+- CloseCodes
+- PipelineErrors
+- getEventName(code)
+- getPipelineErrorName(code)
+
+## Dispatch bridge integration
+
+For frameworks with centralized stores, use setDispatchHandler to bridge incoming lifecycle and event actions:
+
+```ts
+pipeline.setDispatchHandler((action, payload) => {
+  // Example: forward to your store dispatcher
+  store.dispatch(action, payload)
+})
+```
+
+Actions emitted by the client:
+
+- pipeline/setConnectionState
+- pipeline/setReady
+- pipeline/setInvalidSession
+- pipeline/handleDispatch
+- pipeline/handleServerError
+
+## Error handling notes
+
+- Server-side protocol errors are emitted through onError with numeric code/message.
+- Client parse/listener failures are logged, not thrown, to keep the connection alive.
+- send methods are safe no-ops if socket is not open.
+
+## Production recommendations
+
+- Always use wss in production.
+- Keep tokenProvider fast and side-effect free.
+- Subscribe only to events your UI or worker actually consumes.
+- Register listeners before connect() when you need first-event guarantees.
+- Call disconnect() on app shutdown or teardown.
+
+## Local development
+
+Build package:
+
+```bash
+npm run build
+```
+
+Watch mode:
+
+```bash
+npm run dev
+```

package/dist/index.d.mts

@@ -0,0 +1,266 @@
+/**
+ * Pipeline Opcodes and event codes.
+ */
+declare const Opcodes: {
+    readonly IDENTIFY: 0;
+    readonly HEARTBEAT: 1;
+    readonly PRESENCE_UPDATE: 2;
+    readonly SUBSCRIBE: 3;
+    readonly UNSUBSCRIBE: 4;
+    readonly REQUEST: 5;
+    readonly CHAT_SEND: 6;
+    readonly HELLO: 16;
+    readonly HEARTBEAT_ACK: 17;
+    readonly READY: 18;
+    readonly INVALID_SESSION: 19;
+    readonly RECONNECT: 20;
+    readonly DISPATCH: 21;
+    readonly ERROR: 255;
+};
+type Opcode = typeof Opcodes[keyof typeof Opcodes];
+declare const Events: {
+    readonly USER_UPDATE: 0;
+    readonly USER_PRESENCE_UPDATE: 1;
+    readonly USER_TYPING: 2;
+    readonly USER_LEVEL_UP: 3;
+    readonly SESSION_CREATE: 16;
+    readonly SESSION_DELETE: 17;
+    readonly SESSION_UPDATE: 18;
+    readonly NOTIFICATION_CREATE: 32;
+    readonly NOTIFICATION_DELETE: 33;
+    readonly ROOM_JOIN: 48;
+    readonly ROOM_LEAVE: 49;
+    readonly ROOM_UPDATE: 50;
+    readonly ROOM_DELETE: 51;
+    readonly ROOM_USER_JOIN: 64;
+    readonly ROOM_USER_LEAVE: 65;
+    readonly ROOM_USER_KICK: 66;
+    readonly ROOM_USER_BAN: 67;
+    readonly ROOM_USER_MUTE: 68;
+    readonly ROOM_USER_UNMUTE: 69;
+    readonly ROOM_USER_ROLE_UPDATE: 70;
+    readonly ROOM_USER_AVATAR_UPDATE: 71;
+    readonly ROOM_USER_SUBSCRIPTION_UPDATE: 72;
+    readonly ROOM_CHAT_MESSAGE: 80;
+    readonly ROOM_CHAT_DELETE: 81;
+    readonly ROOM_DJ_ADVANCE: 96;
+    readonly ROOM_DJ_UPDATE: 97;
+    readonly ROOM_WAITLIST_JOIN: 98;
+    readonly ROOM_WAITLIST_LEAVE: 99;
+    readonly ROOM_WAITLIST_UPDATE: 100;
+    readonly ROOM_WAITLIST_LOCK: 101;
+    readonly ROOM_WAITLIST_CYCLE: 102;
+    readonly ROOM_TIME_SYNC: 103;
+    readonly ROOM_VOTE: 112;
+    readonly ROOM_GRAB: 113;
+    readonly FRIEND_REQUEST: 128;
+    readonly FRIEND_REQUEST_CANCEL: 129;
+    readonly FRIEND_ACCEPT: 130;
+    readonly FRIEND_REMOVE: 131;
+    readonly SYSTEM_MESSAGE: 240;
+    readonly MAINTENANCE: 241;
+    readonly RATE_LIMIT: 242;
+};
+type EventCode = typeof Events[keyof typeof Events];
+declare const Presence: {
+    readonly ONLINE: 0;
+    readonly IDLE: 1;
+    readonly DND: 2;
+    readonly INVISIBLE: 3;
+    readonly OFFLINE: 4;
+};
+type PresenceCode = typeof Presence[keyof typeof Presence];
+declare const Activity: {
+    readonly NONE: 0;
+    readonly VIEWING: 1;
+    readonly EDITING: 2;
+    readonly IDLE: 3;
+    readonly STREAMING: 4;
+    readonly LISTENING: 5;
+    readonly WATCHING: 6;
+    readonly CUSTOM: 255;
+};
+type ActivityCode = typeof Activity[keyof typeof Activity];
+declare const Roles: {
+    readonly USER: 0;
+    readonly MODERATOR: 1;
+    readonly ADMIN: 2;
+    readonly OWNER: 255;
+};
+type RoleCode = typeof Roles[keyof typeof Roles];
+declare const CloseCodes: {
+    readonly NORMAL: 1000;
+    readonly GOING_AWAY: 1001;
+    readonly PROTOCOL_ERROR: 1002;
+    readonly UNKNOWN_ERROR: 4000;
+    readonly UNKNOWN_OPCODE: 4001;
+    readonly DECODE_ERROR: 4002;
+    readonly NOT_AUTHENTICATED: 4003;
+    readonly AUTHENTICATION_FAILED: 4004;
+    readonly ALREADY_AUTHENTICATED: 4005;
+    readonly INVALID_SESSION: 4006;
+    readonly RATE_LIMITED: 4008;
+    readonly SESSION_TIMEOUT: 4009;
+    readonly SERVER_SHUTDOWN: 4010;
+};
+type CloseCode = typeof CloseCodes[keyof typeof CloseCodes];
+declare const PipelineErrors: {
+    readonly CHAT_MESSAGE_EMPTY: 4100;
+    readonly CHAT_MESSAGE_TOO_LONG: 4101;
+    readonly CHAT_ROOM_NOT_FOUND: 4102;
+    readonly CHAT_NOT_IN_ROOM: 4103;
+    readonly CHAT_USER_MUTED: 4104;
+    readonly ROOM_NOT_FOUND: 4200;
+    readonly ROOM_NOT_ACTIVE: 4201;
+    readonly ROOM_ALREADY_MEMBER: 4202;
+    readonly ROOM_NOT_MEMBER: 4203;
+    readonly ROOM_BANNED: 4204;
+    readonly ROOM_FULL: 4205;
+    readonly WAITLIST_LOCKED: 4300;
+    readonly WAITLIST_FULL: 4301;
+    readonly WAITLIST_ALREADY_IN: 4302;
+    readonly WAITLIST_NOT_IN: 4303;
+    readonly VOTE_INVALID: 4400;
+    readonly VOTE_ALREADY_VOTED: 4401;
+    readonly VOTE_NO_TRACK: 4402;
+};
+type PipelineError = typeof PipelineErrors[keyof typeof PipelineErrors];
+declare function getPipelineErrorName(code: PipelineError): string;
+declare function getEventName(code: EventCode): string;
+
+interface PipelineMessage<T = unknown> {
+    op: Opcode;
+    d: T;
+    t?: EventCode;
+    s?: number;
+}
+interface IdentifyPayload {
+    token: string;
+    properties?: {
+        os?: number;
+        browser?: number;
+        device?: number;
+    };
+}
+interface HeartbeatPayload {
+    seq: number | null;
+}
+interface PresenceUpdatePayload {
+    status: PresenceCode;
+    activity?: {
+        type: ActivityCode;
+        name: string;
+        details?: string;
+        started_at?: number;
+    };
+}
+interface SubscribePayload {
+    events: EventCode[];
+}
+interface UnsubscribePayload {
+    events: EventCode[];
+}
+interface ChatSendPayload {
+    room_slug: string;
+    content: string;
+}
+interface HelloPayload {
+    heartbeat_interval: number;
+    session_id: string;
+}
+interface ReadyPayload {
+    session_id: string;
+    user: {
+        id: number;
+        username: string;
+        display_name: string | null;
+        role: RoleCode;
+        flags: number;
+    };
+    resume_url?: string;
+}
+interface InvalidSessionPayload {
+    resumable: boolean;
+    code: number;
+}
+interface ErrorPayload {
+    code: number;
+    message?: string;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'identified';
+type EventListener<T = unknown> = (data: T) => void;
+interface PipelineEvents {
+    onConnect: () => void;
+    onDisconnect: (code: number, reason: string) => void;
+    onReconnect: (attempt: number) => void;
+    onStateChange: (state: ConnectionState) => void;
+    onReady: (payload: ReadyPayload) => void;
+    onError: (payload: ErrorPayload) => void;
+    onDispatch: (event: EventCode, data: unknown) => void;
+}
+type DispatchHandler = (action: string, payload?: unknown) => void;
+interface PipelineClientOptions {
+    url: string;
+    tokenProvider?: () => string | null | undefined;
+    loggerName?: string;
+    webSocketFactory?: (url: string) => WebSocket;
+}
+
+declare class PipelineClient {
+    private readonly logger;
+    private readonly options;
+    private ws;
+    private sessionId;
+    private heartbeatInterval;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private lastSequence;
+    private subscriptions;
+    private _state;
+    private _user;
+    private eventListeners;
+    private connectionListeners;
+    private dispatchHandler;
+    private readonly maxReconnectAttempts;
+    private readonly reconnectBackoff;
+    constructor(options: PipelineClientOptions);
+    get state(): ConnectionState;
+    get user(): ReadyPayload['user'] | null;
+    get isConnected(): boolean;
+    get isIdentified(): boolean;
+    setDispatchHandler(handler: DispatchHandler): void;
+    connect(): void;
+    disconnect(): void;
+    identify(token: string): void;
+    updatePresence(status: PresenceCode, activity?: PresenceUpdatePayload['activity']): void;
+    subscribe(events: EventCode[]): void;
+    unsubscribe(events: EventCode[]): void;
+    sendChatMessage(roomSlug: string, content: string): boolean;
+    on<T = unknown>(event: EventCode, listener: EventListener<T>): () => void;
+    off<T = unknown>(event: EventCode, listener: EventListener<T>): void;
+    onConnection<K extends keyof PipelineEvents>(event: K, listener: PipelineEvents[K]): () => void;
+    offConnection<K extends keyof PipelineEvents>(event: K, listener: PipelineEvents[K]): void;
+    private setState;
+    private clearTimers;
+    private handleOpen;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private handleHello;
+    private handleReady;
+    private handleInvalidSession;
+    private handleReconnect;
+    private handleDispatch;
+    private handleServerError;
+    private startHeartbeat;
+    private sendHeartbeat;
+    private scheduleReconnect;
+    private send;
+    private emitEvent;
+    private emit;
+    private resolveToken;
+}
+declare function createPipeline(options: PipelineClientOptions): PipelineClient;
+
+export { Activity, type ActivityCode, type ChatSendPayload, type CloseCode, CloseCodes, type ConnectionState, type DispatchHandler, type ErrorPayload, type EventCode, type EventListener, Events, type HeartbeatPayload, type HelloPayload, type IdentifyPayload, type InvalidSessionPayload, type Opcode, Opcodes, PipelineClient, type PipelineClientOptions, type PipelineError, PipelineErrors, type PipelineEvents, type PipelineMessage, Presence, type PresenceCode, type PresenceUpdatePayload, type ReadyPayload, type RoleCode, Roles, type SubscribePayload, type UnsubscribePayload, createPipeline, getEventName, getPipelineErrorName };