@jusi/light-im-sdk 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Wire types — mirror the Go server's internal/api/ws/frame.go and internal/api/rest/*.
+ *
+ * Field names use snake_case to match the JSON the server emits; callers may map to
+ * camelCase at the application boundary if they prefer.
+ */
+/** WebSocket frame envelope (every WS message follows this shape). */
+interface Frame<P = unknown> {
+    type: string;
+    ts?: number;
+    /** Server-stamped unix-ms; populated on outbound frames. */
+    server_ts?: number;
+    payload?: P;
+}
+/** Frame type registry. Server's internal/api/ws/frame.go ⇄ this. */
+declare const FrameType: {
+    readonly Echo: "echo";
+    readonly System: "system";
+    readonly Msg: "msg";
+    readonly Ack: "ack";
+    readonly Read: "read";
+};
+type FrameTypeValue = (typeof FrameType)[keyof typeof FrameType];
+/** Client → server: send a chat message. */
+interface MsgInPayload {
+    cid: string;
+    body: string;
+    content_type?: string;
+    /** Optional dedup token echoed back in the ack. */
+    client_msg_id?: string;
+}
+/** Server → client: fan-out delivery of a persisted message. */
+interface MsgOutPayload {
+    mid: number;
+    cid: string;
+    sender_uid: string;
+    seq: number;
+    content_type: string;
+    body: string;
+    /** unix ms */
+    created_at: number;
+}
+/** Server → client: ack for a previously-sent msg. */
+interface AckPayload {
+    client_msg_id?: string;
+    mid: number;
+    seq: number;
+    cid: string;
+}
+/** Client → server: mark "I read up to seq N in cid". */
+interface ReadInPayload {
+    cid: string;
+    seq: number;
+}
+/** Server → client: fan-out notice of another member's read marker move. */
+interface ReadOutPayload {
+    cid: string;
+    uid: string;
+    seq: number;
+}
+/** System lifecycle event payload (e.g. {event: 'connected'} or {error: '...'}). */
+type SystemPayload = {
+    event?: string;
+    error?: string;
+    [k: string]: unknown;
+};
+type ConversationType = 'direct' | 'group';
+interface ConversationSummary {
+    cid: string;
+    type: ConversationType;
+    meta: unknown;
+    last_seq: number;
+    unread_count: number;
+}
+interface Message {
+    mid: number;
+    cid: string;
+    sender_uid: string;
+    seq: number;
+    content_type: string;
+    body: string;
+    /** unix ms */
+    ts: number;
+}
+interface MessagesResponse {
+    messages: Message[];
+    has_more: boolean;
+}
+/**
+ * High-level connection lifecycle exposed via Client.onStateChange.
+ *
+ * - `disconnected`    initial; after disconnect() or terminal auth_failed
+ * - `connecting`      attempting first WS upgrade
+ * - `connected`       WS connected and server sent "connected" system frame
+ * - `reconnecting`    WS dropped; awaiting next backoff window
+ * - `auth_failed`     terminal until next explicit connect(); tokenProvider returned a bad token twice
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'auth_failed';
+
+/**
+ * Typed error hierarchy. Callers can `instanceof` discriminate;
+ * the underlying failure is preserved on the standard ES2022 `cause` property.
+ */
+declare class IMError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/** HTTP 401 from /v1/* or WS upgrade refused by Bearer middleware. */
+declare class AuthError extends IMError {
+    constructor(message: string, cause?: unknown);
+}
+/** Underlying fetch/WS transport failure (DNS, connect, timeout, 5xx). */
+declare class NetworkError extends IMError {
+    constructor(message: string, cause?: unknown);
+}
+/** Frame parse failed, unexpected field, or schema mismatch. */
+declare class ProtocolError extends IMError {
+    constructor(message: string, cause?: unknown);
+}
+/** A pending promise (e.g. ack on sendText) did not resolve before the timeout. */
+declare class TimeoutError extends IMError {
+    constructor(message: string, cause?: unknown);
+}
+
+/**
+ * Minimal typed emitter. Each Emitter handles ONE event type — composition over hierarchy.
+ *
+ * Listener exceptions are caught and console.error'd so one bad handler can't break others
+ * or kill the WS pump that may be calling emit() inline.
+ */
+type Listener<T> = (event: T) => void;
+type Unsubscribe = () => void;
+declare class Emitter<T> {
+    private listeners;
+    on(cb: Listener<T>): Unsubscribe;
+    emit(event: T): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Exponential backoff with optional uniform jitter — used by the Client's reconnect loop.
+ *
+ * Sequence (base=1000, factor=2, max=30000, jitter=0):
+ *   1000, 2000, 4000, 8000, 16000, 30000, 30000, ...
+ *
+ * With `jitter` in (0, 1], each value is multiplied by a factor sampled uniformly from
+ * [1 - jitter, 1 + jitter], so `jitter=0.3` keeps actual delay in 0.7× – 1.3× of base.
+ */
+interface BackoffOptions {
+    /** First delay in ms (default 1000). */
+    baseMs?: number;
+    /** Cap on a single delay (default 30000). */
+    maxMs?: number;
+    /** Multiplier between attempts (default 2). */
+    factor?: number;
+    /** 0–1, default 0.3. 0 = deterministic. */
+    jitter?: number;
+    /** Override Math.random for tests. */
+    random?: () => number;
+}
+declare class Backoff {
+    private attempt;
+    private readonly opts;
+    private constructor();
+    static create(opts?: BackoffOptions): Backoff;
+    /**
+     * Compute the next delay (in ms) and increment the internal attempt counter.
+     *
+     * Caller is responsible for sleeping; this method just returns the number.
+     */
+    next(): number;
+    /** Reset attempts to 0; the next call to next() yields baseMs again. */
+    reset(): void;
+    /** Number of times next() has been called since the last reset. */
+    get attempts(): number;
+}
+
+interface RestClientOptions {
+    /**
+     * Origin (no trailing slash). Example: `https://im.we-meet.online`.
+     * REST paths are appended verbatim (e.g. `${baseURL}/v1/conversations`).
+     */
+    baseURL: string;
+    /**
+     * Returns a fresh IM token. Called on first use and whenever the cached token
+     * yields a 401. The implementation MAY itself hit the host application's
+     * /api/v1.0/im/token bridge.
+     */
+    tokenProvider: () => Promise<string>;
+    /**
+     * Optional override for the underlying fetch (test seam / Node polyfill).
+     * Defaults to global fetch.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Minimal typed REST client for jusi-light-im's /v1/* endpoints.
+ *
+ * Caches a single Bearer token between calls. On HTTP 401 the cached token is
+ * dropped, tokenProvider is invoked once for a fresh token, and the request is
+ * retried exactly once. A second 401 surfaces as AuthError.
+ */
+declare class RestClient {
+    private readonly baseURL;
+    private readonly tokenProvider;
+    private readonly fetchImpl;
+    private cachedToken;
+    constructor(opts: RestClientOptions);
+    /** Drop the cached token; next request will call tokenProvider again. */
+    invalidateToken(): void;
+    listConversations(): Promise<ConversationSummary[]>;
+    listMessages(cid: string, opts?: {
+        beforeSeq?: number;
+        limit?: number;
+    }): Promise<MessagesResponse>;
+    markRead(cid: string, seq: number): Promise<void>;
+    private getToken;
+    private request;
+    private doFetch;
+    private parseBody;
+}
+
+interface WsClientOptions {
+    /** wss://im... — caller MUST omit the token query param; WsClient appends it on connect(). */
+    url: string;
+    /** Factory override (tests inject mock-socket). Defaults to `new WebSocket(url)`. */
+    wsFactory?: (url: string) => WebSocket;
+    /** Per-message ack deadline in ms (default 10_000). */
+    ackTimeoutMs?: number;
+}
+/**
+ * Low-level WebSocket wrapper.
+ *
+ * Responsibilities:
+ *  - own one WebSocket instance through connect()/disconnect()
+ *  - parse incoming frames as JSON and route to the right listener
+ *  - track pending acks for client → server msg frames
+ *
+ * Does NOT:
+ *  - reconnect on close (that's Client's job — close events bubble up)
+ *  - know anything about backoff / token refresh
+ *  - cache messages while disconnected (caller should queue at a higher layer)
+ */
+declare class WsClient {
+    private readonly baseURL;
+    private readonly wsFactory;
+    private readonly ackTimeoutMs;
+    private ws;
+    private pendingAcks;
+    private idCounter;
+    private readonly openEmit;
+    private readonly closeEmit;
+    private readonly frameEmit;
+    private readonly errorEmit;
+    constructor(opts: WsClientOptions);
+    /** True when the underlying socket is OPEN. */
+    get isOpen(): boolean;
+    /**
+     * Open a WebSocket with the given token appended as ?token=. Resolves when the
+     * native onopen fires; rejects on transport error (does NOT wait for the
+     * server-side "connected" system frame — that's Client's higher-level concern).
+     */
+    connect(token: string): Promise<void>;
+    /** Send any frame. Throws NetworkError if the socket is not open. */
+    send(frame: Frame): void;
+    /**
+     * Send a TypeMsg frame and resolve when the matching ack arrives (matched on
+     * client_msg_id). Rejects with TimeoutError if no ack within ackTimeoutMs, or
+     * with NetworkError if the connection drops first.
+     */
+    sendMsg(payload: MsgInPayload): Promise<AckPayload>;
+    /** Close the socket and reject any pending acks. Idempotent. */
+    disconnect(code?: number, reason?: string): void;
+    onOpen(cb: () => void): Unsubscribe;
+    onClose(cb: Listener<{
+        code: number;
+        reason: string;
+    }>): Unsubscribe;
+    onFrame(cb: Listener<Frame>): Unsubscribe;
+    onError(cb: Listener<unknown>): Unsubscribe;
+    private handleMessage;
+    private failPendingAcks;
+    private generateClientMsgId;
+}
+
+interface ClientOptions {
+    /** Origin of jusi-light-im (no trailing slash). */
+    baseURL: string;
+    /**
+     * Returns a fresh IM token. Invoked on first connect and on 401 / auth_failed retry.
+     */
+    tokenProvider: () => Promise<string>;
+    /**
+     * Optional explicit WS URL. If omitted, derived from baseURL by swapping the scheme
+     * (http → ws, https → wss) and appending /v1/ws.
+     */
+    wsURL?: string;
+    /** Override the WS factory (test seam — pass mock-socket here). */
+    wsFactory?: WsClientOptions['wsFactory'];
+    /** Override fetch (test seam). */
+    fetch?: typeof fetch;
+    /** Reconnect backoff parameters (default: base 1s, max 30s, factor 2, jitter 0.3). */
+    backoff?: BackoffOptions;
+    /** Called on every state transition. */
+    onStateChange?: Listener<ConnectionState>;
+    /** Per-message ack deadline in ms. */
+    ackTimeoutMs?: number;
+}
+/**
+ * High-level facade: combines REST + WS with a self-managing reconnect loop.
+ *
+ * Lifecycle:
+ *   1. connect() — transitions disconnected → connecting → connected (or auth_failed)
+ *   2. on close (network drop) — connected → reconnecting, schedule backoff retry
+ *   3. on 401 during reconnect — single tokenProvider refresh; second 401 → auth_failed
+ *   4. disconnect() — terminal, cancels pending reconnect, transitions → disconnected
+ *
+ * Send / fetch APIs always operate against the most recently established connection.
+ * Calls made while disconnected throw NetworkError; callers should await connect() first
+ * or listen to onStateChange.
+ */
+declare class Client {
+    private readonly opts;
+    private readonly rest;
+    private readonly wsURL;
+    private readonly backoff;
+    private readonly stateEmit;
+    private readonly msgEmit;
+    private readonly readEmit;
+    private readonly systemEmit;
+    private state_;
+    private ws;
+    private currentToken;
+    private reconnectTimer;
+    private explicitlyDisconnected;
+    constructor(opts: ClientOptions);
+    get state(): ConnectionState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    sendText(cid: string, body: string, opts?: {
+        contentType?: string;
+        clientMsgId?: string;
+    }): Promise<AckPayload>;
+    loadHistory(cid: string, opts?: {
+        beforeSeq?: number;
+        limit?: number;
+    }): Promise<MessagesResponse>;
+    markRead(cid: string, seq: number): Promise<void>;
+    listConversations(): Promise<ConversationSummary[]>;
+    onMessage(cb: Listener<MsgOutPayload>): Unsubscribe;
+    onRead(cb: Listener<ReadOutPayload>): Unsubscribe;
+    onSystem(cb: Listener<SystemPayload>): Unsubscribe;
+    onStateChange(cb: Listener<ConnectionState>): Unsubscribe;
+    private deriveWsURL;
+    private transitionTo;
+    private fetchToken;
+    /**
+     * Try to open one WebSocket. On 401-style failure, retries once with a fresh token
+     * (when allowRefresh is true). Updates state.
+     */
+    private openOnce;
+    private looksLikeAuthFailure;
+    private openWith;
+    private dispatchFrame;
+    private handleClose;
+    private scheduleReconnect;
+    private tryReconnect;
+    private cancelReconnect;
+}
+
+export { type AckPayload, AuthError, Backoff, type BackoffOptions, Client, type ClientOptions, type ConnectionState, type ConversationSummary, type ConversationType, Emitter, type Frame, FrameType, type FrameTypeValue, IMError, type Listener, type Message, type MessagesResponse, type MsgInPayload, type MsgOutPayload, NetworkError, ProtocolError, type ReadInPayload, type ReadOutPayload, RestClient, type RestClientOptions, type SystemPayload, TimeoutError, type Unsubscribe, WsClient, type WsClientOptions };