@inline-chat/realtime-sdk 0.0.1

package/dist/ids.d.ts

@@ -0,0 +1,6 @@
+export type InlineId = bigint;
+export type InlineIdLike = InlineId | number;
+export declare class InlineIdError extends Error {
+    constructor(message: string);
+}
+export declare const asInlineId: (value: InlineIdLike, fieldName?: string) => InlineId;

package/dist/ids.js

@@ -0,0 +1,17 @@
+export class InlineIdError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InlineIdError";
+    }
+}
+export const asInlineId = (value, fieldName = "id") => {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value !== "number") {
+        throw new InlineIdError(`invalid ${fieldName}: expected number|bigint`);
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new InlineIdError(`invalid ${fieldName}: number must be a safe integer`);
+    }
+    return BigInt(value);
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { InlineSdkClient } from "./sdk/inline-sdk-client.js";
+export type { InlineSdkClientOptions, InlineSdkState, InlineSdkStateStore, InlineInboundEvent, RpcInputForMethod, RpcResultForMethod, } from "./sdk/types.js";
+export type { InlineSdkLogger } from "./sdk/logger.js";
+export { JsonFileStateStore } from "./state/json-file-state-store.js";
+export { serializeStateV1, deserializeStateV1 } from "./state/serde.js";
+export type { InlineId, InlineIdLike } from "./ids.js";
+export { asInlineId } from "./ids.js";
+export type { InlineUnixSeconds, InlineUnixSecondsLike } from "./time.js";
+export { asInlineUnixSeconds } from "./time.js";
+export * from "@inline-chat/protocol";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { InlineSdkClient } from "./sdk/inline-sdk-client.js";
+export { JsonFileStateStore } from "./state/json-file-state-store.js";
+export { serializeStateV1, deserializeStateV1 } from "./state/serde.js";
+export { asInlineId } from "./ids.js";
+export { asInlineUnixSeconds } from "./time.js";
+// Re-export the full protocol surface for convenience.
+export * from "@inline-chat/protocol";

package/dist/realtime/mock-transport.d.ts

@@ -0,0 +1,17 @@
+import type { ClientMessage, ServerProtocolMessage } from "@inline-chat/protocol/core";
+import { AsyncChannel } from "../utils/async-channel.js";
+import type { TransportEvent } from "./types.js";
+import { type Transport } from "./transport.js";
+export type MockTransportState = "idle" | "connecting" | "connected";
+export declare class MockTransport implements Transport {
+    readonly events: AsyncChannel<TransportEvent>;
+    readonly sent: ClientMessage[];
+    state: MockTransportState;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(message: ClientMessage): Promise<void>;
+    stopConnection(): Promise<void>;
+    reconnect(): Promise<void>;
+    connect(): Promise<void>;
+    emitMessage(message: ServerProtocolMessage): Promise<void>;
+}

package/dist/realtime/mock-transport.js

@@ -0,0 +1,41 @@
+import { AsyncChannel } from "../utils/async-channel.js";
+import { TransportError } from "./transport.js";
+export class MockTransport {
+    events = new AsyncChannel();
+    sent = [];
+    state = "idle";
+    async start() {
+        if (this.state !== "idle")
+            return;
+        this.state = "connecting";
+        await this.events.send({ type: "connecting" });
+    }
+    async stop() {
+        if (this.state === "idle")
+            return;
+        this.state = "idle";
+        await this.events.send({ type: "stopping" });
+    }
+    async send(message) {
+        if (this.state !== "connected") {
+            throw TransportError.notConnected();
+        }
+        this.sent.push(message);
+    }
+    async stopConnection() {
+        if (this.state === "idle")
+            return;
+        this.state = "connecting";
+    }
+    async reconnect() {
+        this.state = "connecting";
+        await this.events.send({ type: "connecting" });
+    }
+    async connect() {
+        this.state = "connected";
+        await this.events.send({ type: "connected" });
+    }
+    async emitMessage(message) {
+        await this.events.send({ type: "message", message });
+    }
+}

package/dist/realtime/ping-pong.d.ts

@@ -0,0 +1,26 @@
+import type { InlineSdkLogger } from "../sdk/logger.js";
+import type { ProtocolClient } from "./protocol-client.js";
+export declare class PingPongService {
+    private readonly log;
+    private readonly crypto;
+    private client;
+    private running;
+    private sleepTimer;
+    private sleepResolver;
+    private pings;
+    constructor(options?: {
+        logger?: InlineSdkLogger;
+        crypto?: Crypto | null;
+    });
+    configure(client: ProtocolClient): void;
+    start(): void;
+    stop(): void;
+    ping(): Promise<void>;
+    pong(nonce: bigint): void;
+    private loop;
+    private reset;
+    private checkConnection;
+    private sleep;
+    private clearSleep;
+    private randomNonce;
+}

package/dist/realtime/ping-pong.js

@@ -0,0 +1,105 @@
+export class PingPongService {
+    log;
+    crypto;
+    client = null;
+    running = false;
+    sleepTimer = null;
+    sleepResolver = null;
+    pings = new Map();
+    constructor(options) {
+        this.log = options?.logger ?? {};
+        const cryptoAny = globalThis.crypto;
+        this.crypto = options?.crypto === undefined ? (isCrypto(cryptoAny) ? cryptoAny : null) : options.crypto;
+    }
+    configure(client) {
+        this.client = client;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.reset();
+        void this.loop();
+    }
+    stop() {
+        this.running = false;
+        this.clearSleep();
+        this.reset();
+    }
+    async ping() {
+        const client = this.client;
+        if (!client)
+            return;
+        if (client.state !== "open")
+            return;
+        const nonce = this.randomNonce();
+        await client.sendPing(nonce);
+        this.pings.set(nonce, Date.now());
+    }
+    pong(nonce) {
+        const pingDate = this.pings.get(nonce);
+        if (!pingDate)
+            return;
+        this.pings.delete(nonce);
+    }
+    async loop() {
+        while (this.running) {
+            await this.checkConnection();
+            await this.sleep(10_000);
+            if (!this.running)
+                break;
+            await this.ping();
+        }
+    }
+    reset() {
+        this.pings.clear();
+    }
+    async checkConnection() {
+        const client = this.client;
+        if (!client)
+            return;
+        if (client.state !== "open")
+            return;
+        const now = Date.now();
+        const hasTimedOutPing = [...this.pings.values()].some((timestamp) => now - timestamp > 30_000);
+        if (!hasTimedOutPing)
+            return;
+        this.log.warn?.("Ping timeout, reconnecting");
+        await client.reconnect();
+    }
+    async sleep(ms) {
+        if (ms <= 0)
+            return;
+        await new Promise((resolve) => {
+            this.sleepResolver = resolve;
+            this.sleepTimer = setTimeout(() => {
+                this.sleepTimer = null;
+                this.sleepResolver = null;
+                resolve();
+            }, ms);
+        });
+    }
+    clearSleep() {
+        if (this.sleepTimer) {
+            clearTimeout(this.sleepTimer);
+            this.sleepTimer = null;
+        }
+        if (this.sleepResolver) {
+            this.sleepResolver();
+            this.sleepResolver = null;
+        }
+    }
+    randomNonce() {
+        if (this.crypto) {
+            const buf = new Uint32Array(2);
+            this.crypto.getRandomValues(buf);
+            // Under `noUncheckedIndexedAccess`, `buf[0]` becomes `number | undefined`.
+            // This array is fixed-size (2), so the cast is safe.
+            const hi = buf[0];
+            const lo = buf[1];
+            return (BigInt(hi) << 32n) | BigInt(lo);
+        }
+        return BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER));
+    }
+}
+const isCrypto = (value) => typeof value === "object" && value !== null && "getRandomValues" in value && typeof value.getRandomValues === "function";

package/dist/realtime/protocol-client.d.ts

@@ -0,0 +1,66 @@
+import { type ConnectionInit } from "@inline-chat/protocol/core";
+import type { Method, RpcCall, RpcResult } from "@inline-chat/protocol/core";
+import { AsyncChannel } from "../utils/async-channel.js";
+import { PingPongService } from "./ping-pong.js";
+import type { Transport } from "./transport.js";
+import type { ClientEvent, ClientState } from "./types.js";
+import type { InlineSdkLogger } from "../sdk/logger.js";
+export type ProtocolClientOptions = {
+    transport: Transport;
+    getConnectionInit: () => ConnectionInit | null;
+    logger?: InlineSdkLogger;
+};
+export declare class ProtocolClient {
+    readonly events: AsyncChannel<ClientEvent>;
+    readonly transport: Transport;
+    readonly pingPong: PingPongService;
+    state: ClientState;
+    private readonly log;
+    private readonly getConnectionInit;
+    private rpcContinuations;
+    private seq;
+    private lastTimestamp;
+    private sequence;
+    private readonly epochSeconds;
+    private connectionAttemptNo;
+    private reconnectionTimer;
+    private authenticationTimeout;
+    private listenersStarted;
+    constructor(options: ProtocolClientOptions);
+    startTransport(): Promise<void>;
+    stopTransport(): Promise<void>;
+    sendPing(nonce: bigint): Promise<void>;
+    reconnect(options?: {
+        skipDelay?: boolean;
+    }): Promise<void>;
+    sendRpc(method: Method, input?: RpcCall["input"]): Promise<bigint>;
+    callRpc(method: Method, input?: RpcCall["input"], options?: {
+        timeoutMs?: number;
+    }): Promise<RpcResult["result"]>;
+    private startListeners;
+    private handleTransportMessage;
+    private sendConnectionInit;
+    private authenticate;
+    private connectionOpen;
+    private connecting;
+    private reset;
+    private startAuthenticationTimeout;
+    private stopAuthenticationTimeout;
+    private handleClientFailure;
+    private getReconnectionDelay;
+    private wrapMessage;
+    private advanceSeq;
+    private generateId;
+    private currentTimestamp;
+    private completeRpcResult;
+    private completeRpcError;
+    private failRpcContinuation;
+    private getAndRemoveRpcContinuation;
+    private cancelAllRpcContinuations;
+}
+export declare class ProtocolClientError extends Error {
+    constructor(code: "not-authorized" | "not-connected" | "rpc-error" | "stopped" | "timeout", details?: {
+        code?: number;
+        message?: string;
+    });
+}

package/dist/realtime/protocol-client.js

@@ -0,0 +1,277 @@
+import { ClientMessage, ServerProtocolMessage } from "@inline-chat/protocol/core";
+import { AsyncChannel } from "../utils/async-channel.js";
+import { PingPongService } from "./ping-pong.js";
+const emptyRpcInput = { oneofKind: undefined };
+export class ProtocolClient {
+    events = new AsyncChannel();
+    transport;
+    pingPong;
+    state = "connecting";
+    log;
+    getConnectionInit;
+    rpcContinuations = new Map();
+    seq = 0;
+    lastTimestamp = 0;
+    sequence = 0;
+    epochSeconds = 1_735_689_600;
+    connectionAttemptNo = 0;
+    reconnectionTimer = null;
+    authenticationTimeout = null;
+    listenersStarted = false;
+    constructor(options) {
+        this.transport = options.transport;
+        this.log = options.logger ?? {};
+        this.getConnectionInit = options.getConnectionInit;
+        this.pingPong = new PingPongService({ logger: this.log });
+        this.pingPong.configure(this);
+        this.startListeners();
+    }
+    async startTransport() {
+        await this.transport.start();
+    }
+    async stopTransport() {
+        await this.transport.stop();
+    }
+    async sendPing(nonce) {
+        const message = this.wrapMessage({
+            oneofKind: "ping",
+            ping: { nonce },
+        });
+        try {
+            await this.transport.send(message);
+        }
+        catch (error) {
+            this.log.error?.("Failed to send ping", error);
+        }
+    }
+    async reconnect(options) {
+        await this.transport.reconnect({ skipDelay: options?.skipDelay });
+    }
+    async sendRpc(method, input = emptyRpcInput) {
+        const message = this.wrapMessage({
+            oneofKind: "rpcCall",
+            rpcCall: { method, input },
+        });
+        await this.transport.send(message);
+        return message.id;
+    }
+    async callRpc(method, input = emptyRpcInput, options) {
+        const message = this.wrapMessage({
+            oneofKind: "rpcCall",
+            rpcCall: { method, input },
+        });
+        return await new Promise((resolve, reject) => {
+            const continuation = { resolve, reject };
+            this.rpcContinuations.set(message.id, continuation);
+            void this.transport.send(message).catch((error) => {
+                this.failRpcContinuation(message.id, error instanceof Error ? error : new Error("send-failed"));
+            });
+            const timeoutMs = options?.timeoutMs ?? 15_000;
+            if (timeoutMs > 0) {
+                continuation.timeout = setTimeout(() => {
+                    this.failRpcContinuation(message.id, new ProtocolClientError("timeout"));
+                }, timeoutMs);
+            }
+        });
+    }
+    async startListeners() {
+        if (this.listenersStarted)
+            return;
+        this.listenersStarted = true;
+        (async () => {
+            for await (const event of this.transport.events) {
+                switch (event.type) {
+                    case "connected":
+                        await this.authenticate();
+                        break;
+                    case "message":
+                        await this.handleTransportMessage(event.message);
+                        break;
+                    case "connecting":
+                        await this.connecting();
+                        break;
+                    case "stopping":
+                        await this.reset();
+                        break;
+                }
+            }
+        })().catch((error) => {
+            this.log.error?.("Protocol client listener crashed", error);
+        });
+    }
+    async handleTransportMessage(message) {
+        switch (message.body.oneofKind) {
+            case "connectionOpen":
+                await this.connectionOpen();
+                break;
+            case "rpcResult":
+                this.completeRpcResult(message.body.rpcResult.reqMsgId, message.body.rpcResult.result);
+                await this.events.send({
+                    type: "rpcResult",
+                    msgId: message.body.rpcResult.reqMsgId,
+                    rpcResult: message.body.rpcResult.result,
+                });
+                break;
+            case "rpcError":
+                this.completeRpcError(message.body.rpcError.reqMsgId, message.body.rpcError);
+                await this.events.send({
+                    type: "rpcError",
+                    msgId: message.body.rpcError.reqMsgId,
+                    rpcError: message.body.rpcError,
+                });
+                break;
+            case "ack":
+                await this.events.send({ type: "ack", msgId: message.body.ack.msgId });
+                break;
+            case "message":
+                if (message.body.message.payload.oneofKind === "update") {
+                    await this.events.send({ type: "updates", updates: message.body.message.payload.update });
+                }
+                break;
+            case "pong":
+                this.pingPong.pong(message.body.pong.nonce);
+                break;
+            case "connectionError":
+                this.handleClientFailure();
+                break;
+            default:
+                break;
+        }
+    }
+    async sendConnectionInit() {
+        const connectionInit = this.getConnectionInit();
+        if (!connectionInit)
+            throw new ProtocolClientError("not-authorized");
+        const message = this.wrapMessage({
+            oneofKind: "connectionInit",
+            connectionInit,
+        });
+        await this.transport.send(message);
+    }
+    async authenticate() {
+        try {
+            await this.sendConnectionInit();
+            this.startAuthenticationTimeout();
+        }
+        catch (error) {
+            this.log.error?.("Failed to authenticate", error);
+            this.handleClientFailure();
+        }
+    }
+    async connectionOpen() {
+        this.state = "open";
+        await this.events.send({ type: "open" });
+        this.stopAuthenticationTimeout();
+        if (this.reconnectionTimer) {
+            clearTimeout(this.reconnectionTimer);
+            this.reconnectionTimer = null;
+        }
+        this.connectionAttemptNo = 0;
+        this.pingPong.start();
+    }
+    async connecting() {
+        this.state = "connecting";
+        await this.events.send({ type: "connecting" });
+    }
+    async reset() {
+        this.pingPong.stop();
+        this.stopAuthenticationTimeout();
+        this.cancelAllRpcContinuations(new ProtocolClientError("stopped"));
+        this.state = "connecting";
+    }
+    startAuthenticationTimeout() {
+        this.stopAuthenticationTimeout();
+        this.authenticationTimeout = setTimeout(() => {
+            if (this.state === "open")
+                return;
+            this.handleClientFailure();
+        }, 10_000);
+    }
+    stopAuthenticationTimeout() {
+        if (!this.authenticationTimeout)
+            return;
+        clearTimeout(this.authenticationTimeout);
+        this.authenticationTimeout = null;
+    }
+    handleClientFailure() {
+        this.pingPong.stop();
+        this.cancelAllRpcContinuations(new ProtocolClientError("not-connected"));
+        this.stopAuthenticationTimeout();
+        if (this.reconnectionTimer) {
+            clearTimeout(this.reconnectionTimer);
+        }
+        this.connectionAttemptNo = (this.connectionAttemptNo + 1) >>> 0;
+        this.reconnectionTimer = setTimeout(() => {
+            if (this.state === "open")
+                return;
+            void this.reconnect({ skipDelay: true });
+        }, this.getReconnectionDelay() * 1000);
+    }
+    getReconnectionDelay() {
+        const attemptNo = this.connectionAttemptNo;
+        if (attemptNo >= 8)
+            return 8.0 + Math.random() * 5.0;
+        return Math.min(8.0, 0.2 + Math.pow(attemptNo, 1.5) * 0.4);
+    }
+    wrapMessage(body) {
+        this.advanceSeq();
+        return ClientMessage.create({
+            id: this.generateId(),
+            seq: this.seq,
+            body,
+        });
+    }
+    advanceSeq() {
+        this.seq = (this.seq + 1) >>> 0;
+    }
+    generateId() {
+        const timestamp = this.currentTimestamp();
+        if (timestamp === this.lastTimestamp) {
+            this.sequence = (this.sequence + 1) >>> 0;
+        }
+        else {
+            this.sequence = 0;
+            this.lastTimestamp = timestamp;
+        }
+        return (BigInt(timestamp) << 32n) | BigInt(this.sequence);
+    }
+    currentTimestamp() {
+        return Math.floor(Date.now() / 1000) - this.epochSeconds;
+    }
+    completeRpcResult(msgId, rpcResult) {
+        const continuation = this.getAndRemoveRpcContinuation(msgId);
+        continuation?.resolve(rpcResult);
+    }
+    completeRpcError(msgId, rpcError) {
+        const error = new ProtocolClientError("rpc-error", { code: rpcError.code, message: rpcError.message });
+        const continuation = this.getAndRemoveRpcContinuation(msgId);
+        continuation?.reject(error);
+    }
+    failRpcContinuation(msgId, error) {
+        const continuation = this.getAndRemoveRpcContinuation(msgId);
+        continuation?.reject(error);
+    }
+    getAndRemoveRpcContinuation(msgId) {
+        const continuation = this.rpcContinuations.get(msgId);
+        if (!continuation)
+            return null;
+        if (continuation.timeout)
+            clearTimeout(continuation.timeout);
+        this.rpcContinuations.delete(msgId);
+        return continuation;
+    }
+    cancelAllRpcContinuations(error) {
+        for (const continuation of this.rpcContinuations.values()) {
+            continuation.reject(error);
+            if (continuation.timeout)
+                clearTimeout(continuation.timeout);
+        }
+        this.rpcContinuations.clear();
+    }
+}
+export class ProtocolClientError extends Error {
+    constructor(code, details) {
+        super(details?.message ?? code);
+        this.name = `ProtocolClientError:${code}`;
+    }
+}

package/dist/realtime/transport.d.ts

@@ -0,0 +1,16 @@
+import type { ClientMessage } from "@inline-chat/protocol/core";
+import type { TransportEvent } from "./types.js";
+export declare class TransportError extends Error {
+    constructor(message: string);
+    static notConnected(): TransportError;
+}
+export type Transport = {
+    events: AsyncIterable<TransportEvent>;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    send: (message: ClientMessage) => Promise<void>;
+    stopConnection: () => Promise<void>;
+    reconnect: (options?: {
+        skipDelay?: boolean;
+    }) => Promise<void>;
+};

package/dist/realtime/transport.js

@@ -0,0 +1,9 @@
+export class TransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TransportError";
+    }
+    static notConnected() {
+        return new TransportError("Transport is not connected");
+    }
+}

package/dist/realtime/types.d.ts

@@ -0,0 +1,31 @@
+import type { RpcError, RpcResult, ServerProtocolMessage, UpdatesPayload } from "@inline-chat/protocol/core";
+export type ClientState = "connecting" | "open";
+export type TransportEvent = {
+    type: "connecting";
+} | {
+    type: "connected";
+} | {
+    type: "stopping";
+} | {
+    type: "message";
+    message: ServerProtocolMessage;
+};
+export type ClientEvent = {
+    type: "connecting";
+} | {
+    type: "open";
+} | {
+    type: "ack";
+    msgId: bigint;
+} | {
+    type: "rpcResult";
+    msgId: bigint;
+    rpcResult: RpcResult["result"];
+} | {
+    type: "rpcError";
+    msgId: bigint;
+    rpcError: RpcError;
+} | {
+    type: "updates";
+    updates: UpdatesPayload;
+};

package/dist/realtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/realtime/ws-transport.d.ts

@@ -0,0 +1,36 @@
+import { ClientMessage } from "@inline-chat/protocol/core";
+import { AsyncChannel } from "../utils/async-channel.js";
+import { type Transport } from "./transport.js";
+import type { TransportEvent } from "./types.js";
+import type { InlineSdkLogger } from "../sdk/logger.js";
+export type WebSocketTransportOptions = {
+    url: string;
+    logger?: InlineSdkLogger;
+};
+export declare class WebSocketTransport implements Transport {
+    readonly events: AsyncChannel<TransportEvent>;
+    private readonly url;
+    private readonly log;
+    private state;
+    private connectionAttemptNo;
+    private socket;
+    private reconnectionTimer;
+    constructor(options: WebSocketTransportOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(message: ClientMessage): Promise<void>;
+    stopConnection(): Promise<void>;
+    reconnect(options?: {
+        skipDelay?: boolean;
+    }): Promise<void>;
+    private cleanUpPreviousConnection;
+    private getReconnectionDelaySeconds;
+    private openConnection;
+    private connectionDidOpen;
+    private handleMessage;
+    private coerceBinary;
+    private handleClose;
+    private handleError;
+    private setIdle;
+    private setConnecting;
+}