@foony/realtime 0.0.1

package/lib/wire.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Wire protocol types for the Foony Realtime WebSocket service.
+ *
+ * Mirrors `services/realtime-saas/internal/wire/wire.go` exactly — any
+ * change here MUST be mirrored on the Go side and vice versa.
+ *
+ * Conventions:
+ *  - Every frame has a single-character `t` discriminator.
+ *  - Client-originated frames carry a numeric `id`; the server echoes it
+ *    back on the matching `ack` / `err` frame so SDKs can correlate
+ *    requests to responses.
+ *  - Field names favor readability over brevity (`channel`, not `ch`),
+ *    except for `t`, which we keep short because every frame carries it.
+ */
+/** Discriminator values for the `t` field. */
+export type FrameType = 'auth' | 'sub' | 'unsub' | 'pub' | 'pres' | 'hist' | 'ping' | 'connected' | 'ack' | 'msg' | 'presEvt' | 'err' | 'pong' | 'histRes';
+/** Recognized presence transition values. */
+export type PresenceAction = 'enter' | 'leave' | 'update';
+/** First frame after the WebSocket handshake. Carries either a JWT token or API key. */
+export type AuthFrame = {
+    readonly t: 'auth';
+    readonly token?: string;
+    readonly key?: string;
+    readonly clientId?: string;
+};
+/** Start delivering messages + presence for `channel`. */
+export type SubscribeFrame = {
+    readonly t: 'sub';
+    readonly channel: string;
+    readonly id: number;
+    /** Optional resume cursor; when set, replay messages with id > this. */
+    readonly lastMessageId?: string;
+};
+/** Stop delivering messages + presence for `channel`. */
+export type UnsubscribeFrame = {
+    readonly t: 'unsub';
+    readonly channel: string;
+    readonly id: number;
+};
+/** Publish a single application-level message to `channel`. */
+export type PublishFrame = {
+    readonly t: 'pub';
+    readonly channel: string;
+    readonly name: string;
+    readonly data: unknown;
+    readonly id: number;
+};
+/** Mutate the publisher's presence membership in `channel`. */
+export type PresenceFrame = {
+    readonly t: 'pres';
+    readonly channel: string;
+    readonly action: PresenceAction;
+    readonly data?: unknown;
+    readonly id: number;
+};
+/** Application-level liveness probe. Server replies with `pong`. */
+export type PingFrame = {
+    readonly t: 'ping';
+};
+/** Sent once after a successful auth handshake. */
+export type ConnectedFrame = {
+    readonly t: 'connected';
+    readonly connectionId: string;
+    readonly keepAliveMs: number;
+    readonly clientId: string;
+};
+/** Acks a client request that does not need a structured reply. */
+export type AckFrame = {
+    readonly t: 'ack';
+    readonly id: number;
+};
+/** Server-originated channel message. */
+export type MessageFrame = {
+    readonly t: 'msg';
+    readonly channel: string;
+    readonly name: string;
+    readonly data: unknown;
+    readonly timestamp: number;
+    readonly messageId: string;
+    readonly clientId?: string;
+};
+/** Server-originated presence transition. */
+export type PresenceEventFrame = {
+    readonly t: 'presEvt';
+    readonly channel: string;
+    readonly action: PresenceAction;
+    readonly clientId: string;
+    readonly connectionId: string;
+    readonly data?: unknown;
+    readonly timestamp: number;
+};
+/** Protocol or authorization error related to a specific client request. */
+export type ErrorFrame = {
+    readonly t: 'err';
+    readonly id?: number;
+    readonly code: number;
+    readonly message: string;
+};
+/** Response to `ping`. */
+export type PongFrame = {
+    readonly t: 'pong';
+};
+/** Response to `hist`. Messages oldest-first. */
+export type HistoryResponseFrame = {
+    readonly t: 'histRes';
+    readonly id: number;
+    readonly channel: string;
+    readonly messages: readonly MessageFrame[];
+    readonly more?: boolean;
+};
+/** Any frame the client may send. */
+export type ClientFrame = AuthFrame | SubscribeFrame | UnsubscribeFrame | PublishFrame | PresenceFrame | PingFrame;
+/** Any frame the server may send. */
+export type ServerFrame = ConnectedFrame | AckFrame | MessageFrame | PresenceEventFrame | ErrorFrame | PongFrame | HistoryResponseFrame;
+/**
+ * Error codes the server uses on `err` frames. Mirrors the Go
+ * `internal/wire` constants — keep in sync.
+ */
+export declare const ErrorCode: {
+    readonly BadFrame: 40001;
+    readonly BadAuth: 40101;
+    readonly AuthExpired: 40102;
+    readonly Forbidden: 40300;
+    readonly NotFound: 40400;
+    readonly Server: 50000;
+};
+export type ErrorCodeName = keyof typeof ErrorCode;
+//# sourceMappingURL=wire.d.ts.map

package/lib/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"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"}

package/lib/wire.js

@@ -0,0 +1,27 @@
+/**
+ * Wire protocol types for the Foony Realtime WebSocket service.
+ *
+ * Mirrors `services/realtime-saas/internal/wire/wire.go` exactly — any
+ * change here MUST be mirrored on the Go side and vice versa.
+ *
+ * Conventions:
+ *  - Every frame has a single-character `t` discriminator.
+ *  - Client-originated frames carry a numeric `id`; the server echoes it
+ *    back on the matching `ack` / `err` frame so SDKs can correlate
+ *    requests to responses.
+ *  - Field names favor readability over brevity (`channel`, not `ch`),
+ *    except for `t`, which we keep short because every frame carries it.
+ */
+/**
+ * Error codes the server uses on `err` frames. Mirrors the Go
+ * `internal/wire` constants — keep in sync.
+ */
+export const ErrorCode = {
+    BadFrame: 40001,
+    BadAuth: 40101,
+    AuthExpired: 40102,
+    Forbidden: 40300,
+    NotFound: 40400,
+    Server: 50000,
+};
+//# sourceMappingURL=wire.js.map

package/lib/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsJH;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,QAAQ,EAAE,KAAK;IACf,OAAO,EAAE,KAAK;IACd,WAAW,EAAE,KAAK;IAClB,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;IACf,MAAM,EAAE,KAAK;CACL,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@foony/realtime",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for the Foony Realtime service.",
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Foony-Limited/realtime-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Foony-Limited/realtime-js/issues"
+  },
+  "homepage": "https://github.com/Foony-Limited/realtime-js#readme",
+  "keywords": [
+    "foony",
+    "realtime",
+    "websocket",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "lib",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./server": {
+      "types": "./lib/server.d.ts",
+      "import": "./lib/server.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "6.0.3",
+    "vitest": "^4.0.14",
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,138 @@
+/**
+ * Channel + Presence public API. Wraps the Connection layer with
+ * per-channel state.
+ */
+
+import type { Connection, MessageListener, PresenceEventListener } from './connection.js';
+import type { PresenceAction } from './wire.js';
+
+/** Listener handle returned by `subscribe` — call to remove the listener. */
+export type UnsubscribeFn = () => void;
+
+/**
+ * One subscription handle per (channel, listener) pair. Channels are
+ * value-equal by name on a given Realtime client — calling
+ * `client.channels.get('chat:1')` twice returns the same instance.
+ */
+export class Channel {
+  readonly name: string;
+  readonly presence: Presence;
+  private readonly connection: Connection;
+  private attachPromise: Promise<void> | null = null;
+  private attached = false;
+
+  constructor(connection: Connection, name: string) {
+    this.connection = connection;
+    this.name = name;
+    this.presence = new Presence(connection, name, this);
+  }
+
+  /**
+   * Ensure the server is subscribed to this channel. Called implicitly
+   * by `subscribe()` and `presence.subscribe()`; expose it so callers
+   * can pre-attach if they want to surface attach errors before the
+   * first message arrives.
+   */
+  async attach(): Promise<void> {
+    if (this.attached) return;
+    if (this.attachPromise) return this.attachPromise;
+    this.attachPromise = this.connection
+      .request({ t: 'sub', channel: this.name })
+      .then(() => {
+        this.attached = true;
+        this.connection.rememberSubscription(this.name);
+      })
+      .finally(() => {
+        this.attachPromise = null;
+      });
+    return this.attachPromise;
+  }
+
+  /**
+   * Detach from the server (stop receiving messages and presence
+   * events). Local listeners are preserved — call `unsubscribe()` to
+   * clear them.
+   */
+  async detach(): Promise<void> {
+    if (!this.attached) return;
+    await this.connection.request({ t: 'unsub', channel: this.name });
+    this.attached = false;
+    this.connection.forgetSubscription(this.name);
+  }
+
+  /**
+   * Register a listener for message frames on this channel. Implicitly
+   * attaches if needed. Returns an unsubscribe function.
+   */
+  subscribe(listener: MessageListener): UnsubscribeFn {
+    const listeners = this.connection.addChannelListeners(this.name);
+    listeners.messages.add(listener);
+    // Fire-and-forget attach; the listener stays registered even if
+    // attach fails so a retry-on-reconnect surfaces the right state.
+    this.attach().catch(() => {});
+    return () => {
+      listeners.messages.delete(listener);
+    };
+  }
+
+  /** Publish one application-level message to the channel. */
+  async publish(name: string, data: unknown): Promise<void> {
+    await this.attach();
+    await this.connection.request({ t: 'pub', channel: this.name, name, data });
+  }
+}
+
+/**
+ * Per-channel presence facade. Wraps the `pres` frame and `presEvt`
+ * listener dispatch.
+ */
+export class Presence {
+  private readonly connection: Connection;
+  private readonly channelName: string;
+  private readonly channel: Channel;
+
+  constructor(connection: Connection, channelName: string, channel: Channel) {
+    this.connection = connection;
+    this.channelName = channelName;
+    this.channel = channel;
+  }
+
+  /**
+   * Register a listener for presence events. Implicitly attaches the
+   * underlying channel — presence events arrive on the same WebSocket
+   * subscription as message frames.
+   */
+  subscribe(listener: PresenceEventListener): UnsubscribeFn {
+    const listeners = this.connection.addChannelListeners(this.channelName);
+    listeners.presence.add(listener);
+    this.channel.attach().catch(() => {});
+    return () => {
+      listeners.presence.delete(listener);
+    };
+  }
+
+  /** Announce this connection as present in the channel. */
+  async enter(data?: unknown): Promise<void> {
+    await this.send('enter', data);
+  }
+
+  /** Update the data attached to this connection's presence entry. */
+  async update(data?: unknown): Promise<void> {
+    await this.send('update', data);
+  }
+
+  /** Remove this connection's presence entry. */
+  async leave(): Promise<void> {
+    await this.send('leave', undefined);
+  }
+
+  private async send(action: PresenceAction, data: unknown): Promise<void> {
+    await this.channel.attach();
+    await this.connection.request({
+      t: 'pres',
+      channel: this.channelName,
+      action,
+      ...(data === undefined ? {} : { data }),
+    });
+  }
+}