@mitway/sdk 0.2.2 → 0.2.3

package/dist/index.d.cts

@@ -29,6 +29,135 @@ interface User {
     updated_at: string;
 }
 
+/**
+ * Token Manager for the MITWAY-BaaS SDK.
+ *
+ * In-memory storage for the access token + user. Browser CSRF token lives
+ * in a cookie so the cookie-based refresh flow works across page reloads.
+ */
+
+declare class TokenManager {
+    private accessToken;
+    private user;
+    /** Fired when the access token changes (used by long-lived consumers). */
+    onTokenChange: (() => void) | null;
+    saveSession(session: AuthSession): void;
+    getSession(): AuthSession | null;
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getUser(): User | null;
+    setUser(user: User): void;
+    clearSession(): void;
+}
+
+/**
+ * Realtime module — Socket.IO client wrapper for MITWAY-BaaS.
+ *
+ * Provides a thin, typed layer over `socket.io-client` so app code can
+ * subscribe / publish / listen without dealing with the underlying
+ * transport details. The MITWAY-BaaS backend handles auth (JWT / API
+ * key), RLS, rate limiting, and fan-out across replicas — the SDK just
+ * opens one socket per `MitwayBaasClient` instance and routes events.
+ */
+
+/** Standardized meta envelope emitted by the server on every push. */
+interface RealtimeMessageMeta {
+    channel?: string;
+    message_id: string;
+    sender_type: 'system' | 'user';
+    sender_id?: string;
+    timestamp: string;
+}
+/** Subscribe ack returned by the server. */
+type SubscribeResult = {
+    ok: true;
+    channel: string;
+} | {
+    ok: false;
+    channel: string;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Server-pushed unsolicited error. */
+interface RealtimeErrorPayload {
+    channel?: string;
+    code: string;
+    message: string;
+}
+interface RealtimeListener<T = unknown> {
+    (payload: T, meta: RealtimeMessageMeta): void;
+}
+type ConnectionListener = () => void;
+type DisconnectListener = (reason: string) => void;
+type ConnectErrorListener = (error: Error) => void;
+interface RealtimeOptions {
+    /** Override the path on the server. Defaults to the Socket.IO default. */
+    path?: string;
+    /** Transport strategy. Defaults to `['websocket']` — modern browsers
+     *  and Node always support it, no need for the long-polling fallback. */
+    transports?: Array<'websocket' | 'polling'>;
+    /** Handshake timeout in ms. */
+    timeoutMs?: number;
+    /** Extra fields merged into socket.handshake.auth. Advanced usage. */
+    extraAuth?: Record<string, string>;
+}
+/**
+ * MITWAY-BaaS realtime client.
+ *
+ * Public API mirrors the InsForge realtime SDK for familiarity, but the
+ * wire protocol follows our backend (see
+ * `MITWAY-BaaS/backend/src/infra/socket/socket.manager.ts`):
+ *
+ *   - Handshake auth uses `auth.token` containing the JWT (preferred)
+ *     or an opaque API key string.
+ *   - `realtime:subscribe` / `realtime:unsubscribe` / `realtime:publish`
+ *     are the client-to-server events.
+ *   - Server pushes the user-defined `event` name with `{ ...payload,
+ *     meta }` shape.
+ *   - `realtime:error` is the unsolicited error channel for publish
+ *     failures and similar.
+ */
+declare class Realtime {
+    private socket;
+    private baseUrl;
+    private options;
+    private anonKey;
+    private tokenManager;
+    private listeners;
+    private reserved;
+    private connecting;
+    private subscribedChannels;
+    constructor(baseUrl: string, tokenManager: TokenManager, anonKey: string | undefined, options?: RealtimeOptions);
+    get isConnected(): boolean;
+    get socketId(): string | undefined;
+    /** Explicitly open the connection. Safe to call multiple times; only
+     *  opens one socket per instance. Subsequent calls during connection
+     *  return the same in-flight promise. */
+    connect(): Promise<void>;
+    private openSocket;
+    /** Close the socket and clear in-memory subscription state. Reserved
+     *  listeners survive so callers can reconnect later via `connect()`. */
+    disconnect(): void;
+    subscribe(channel: string): Promise<SubscribeResult>;
+    /** Fire-and-forget. No ack from the server. */
+    unsubscribe(channel: string): void;
+    /** Publish via the Socket.IO transport. Subject to RLS INSERT policy
+     *  on `realtime.messages` (disabled by default — the developer must
+     *  add a policy before clients can publish). Returns immediately; any
+     *  server rejection comes through the `error` reserved event. */
+    publish(channel: string, event: string, payload: Record<string, unknown>): void;
+    on(event: 'connect', cb: ConnectionListener): void;
+    on(event: 'disconnect', cb: DisconnectListener): void;
+    on(event: 'connect_error', cb: ConnectErrorListener): void;
+    on(event: 'error', cb: RealtimeListener<RealtimeErrorPayload>): void;
+    on<T = unknown>(event: string, cb: RealtimeListener<T>): void;
+    off(event: string, cb: (...args: any[]) => void): void;
+    private dispatch;
+    private emitReserved;
+}
+
 /**
  * MITWAY-BaaS SDK types — only SDK-specific shapes live here.
  * The `User` shape is inlined in `./lib/user` so this package has zero
@@ -89,6 +218,10 @@ interface MitwayBaasConfig {
      * @default true
      */
     autoRefreshToken?: boolean;
+    /**
+     * Realtime transport options. See `RealtimeOptions`.
+     */
+    realtime?: RealtimeOptions;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -146,27 +279,6 @@ declare class Logger {
     logResponse(method: string, url: string, status: number, durationMs: number, body?: any): void;
 }
 
-/**
- * Token Manager for the MITWAY-BaaS SDK.
- *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
- */
-
-declare class TokenManager {
-    private accessToken;
-    private user;
-    /** Fired when the access token changes (used by long-lived consumers). */
-    onTokenChange: (() => void) | null;
-    saveSession(session: AuthSession): void;
-    getSession(): AuthSession | null;
-    getAccessToken(): string | null;
-    setAccessToken(token: string): void;
-    getUser(): User | null;
-    setUser(user: User): void;
-    clearSession(): void;
-}
-
 /**
  * HttpClient with retry, timeout, abort signal composition, and automatic
  * token refresh on 401 INVALID_TOKEN responses.
@@ -409,6 +521,7 @@ declare class MitwayBaasClient {
     private tokenManager;
     readonly auth: Auth;
     readonly database: Database;
+    readonly realtime: Realtime;
     constructor(config?: MitwayBaasConfig);
     /**
      * Escape hatch for callers that need to make custom requests against the
@@ -423,13 +536,13 @@ declare class MitwayBaasClient {
  * Currently ships:
  *   - auth     (signUp, signInWithPassword, signOut, refreshSession, getSession, getUser)
  *   - database (PostgREST-backed query builder via @supabase/postgrest-js)
+ *   - realtime (Socket.IO transport: subscribe / unsubscribe / publish / on)
  *
  * Not yet included (no backend support):
  *   - storage
  *   - functions
  *   - email
  *   - ai
- *   - realtime
  *
  * @packageDocumentation
  */
@@ -449,4 +562,4 @@ declare class MitwayBaasClient {
  */
 declare function createClient(config: MitwayBaasConfig): MitwayBaasClient;
 
-export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, Database, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type SignInRequest, type SignUpRequest, TokenManager, type User, createClient, MitwayBaasClient as default };
+export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, type ConnectErrorListener, type ConnectionListener, Database, type DisconnectListener, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, Realtime, type RealtimeErrorPayload, type RealtimeListener, type RealtimeMessageMeta, type RealtimeOptions, type SignInRequest, type SignUpRequest, type SubscribeResult, TokenManager, type User, createClient, MitwayBaasClient as default };

package/dist/index.d.ts

@@ -29,6 +29,135 @@ interface User {
     updated_at: string;
 }
 
+/**
+ * Token Manager for the MITWAY-BaaS SDK.
+ *
+ * In-memory storage for the access token + user. Browser CSRF token lives
+ * in a cookie so the cookie-based refresh flow works across page reloads.
+ */
+
+declare class TokenManager {
+    private accessToken;
+    private user;
+    /** Fired when the access token changes (used by long-lived consumers). */
+    onTokenChange: (() => void) | null;
+    saveSession(session: AuthSession): void;
+    getSession(): AuthSession | null;
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getUser(): User | null;
+    setUser(user: User): void;
+    clearSession(): void;
+}
+
+/**
+ * Realtime module — Socket.IO client wrapper for MITWAY-BaaS.
+ *
+ * Provides a thin, typed layer over `socket.io-client` so app code can
+ * subscribe / publish / listen without dealing with the underlying
+ * transport details. The MITWAY-BaaS backend handles auth (JWT / API
+ * key), RLS, rate limiting, and fan-out across replicas — the SDK just
+ * opens one socket per `MitwayBaasClient` instance and routes events.
+ */
+
+/** Standardized meta envelope emitted by the server on every push. */
+interface RealtimeMessageMeta {
+    channel?: string;
+    message_id: string;
+    sender_type: 'system' | 'user';
+    sender_id?: string;
+    timestamp: string;
+}
+/** Subscribe ack returned by the server. */
+type SubscribeResult = {
+    ok: true;
+    channel: string;
+} | {
+    ok: false;
+    channel: string;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Server-pushed unsolicited error. */
+interface RealtimeErrorPayload {
+    channel?: string;
+    code: string;
+    message: string;
+}
+interface RealtimeListener<T = unknown> {
+    (payload: T, meta: RealtimeMessageMeta): void;
+}
+type ConnectionListener = () => void;
+type DisconnectListener = (reason: string) => void;
+type ConnectErrorListener = (error: Error) => void;
+interface RealtimeOptions {
+    /** Override the path on the server. Defaults to the Socket.IO default. */
+    path?: string;
+    /** Transport strategy. Defaults to `['websocket']` — modern browsers
+     *  and Node always support it, no need for the long-polling fallback. */
+    transports?: Array<'websocket' | 'polling'>;
+    /** Handshake timeout in ms. */
+    timeoutMs?: number;
+    /** Extra fields merged into socket.handshake.auth. Advanced usage. */
+    extraAuth?: Record<string, string>;
+}
+/**
+ * MITWAY-BaaS realtime client.
+ *
+ * Public API mirrors the InsForge realtime SDK for familiarity, but the
+ * wire protocol follows our backend (see
+ * `MITWAY-BaaS/backend/src/infra/socket/socket.manager.ts`):
+ *
+ *   - Handshake auth uses `auth.token` containing the JWT (preferred)
+ *     or an opaque API key string.
+ *   - `realtime:subscribe` / `realtime:unsubscribe` / `realtime:publish`
+ *     are the client-to-server events.
+ *   - Server pushes the user-defined `event` name with `{ ...payload,
+ *     meta }` shape.
+ *   - `realtime:error` is the unsolicited error channel for publish
+ *     failures and similar.
+ */
+declare class Realtime {
+    private socket;
+    private baseUrl;
+    private options;
+    private anonKey;
+    private tokenManager;
+    private listeners;
+    private reserved;
+    private connecting;
+    private subscribedChannels;
+    constructor(baseUrl: string, tokenManager: TokenManager, anonKey: string | undefined, options?: RealtimeOptions);
+    get isConnected(): boolean;
+    get socketId(): string | undefined;
+    /** Explicitly open the connection. Safe to call multiple times; only
+     *  opens one socket per instance. Subsequent calls during connection
+     *  return the same in-flight promise. */
+    connect(): Promise<void>;
+    private openSocket;
+    /** Close the socket and clear in-memory subscription state. Reserved
+     *  listeners survive so callers can reconnect later via `connect()`. */
+    disconnect(): void;
+    subscribe(channel: string): Promise<SubscribeResult>;
+    /** Fire-and-forget. No ack from the server. */
+    unsubscribe(channel: string): void;
+    /** Publish via the Socket.IO transport. Subject to RLS INSERT policy
+     *  on `realtime.messages` (disabled by default — the developer must
+     *  add a policy before clients can publish). Returns immediately; any
+     *  server rejection comes through the `error` reserved event. */
+    publish(channel: string, event: string, payload: Record<string, unknown>): void;
+    on(event: 'connect', cb: ConnectionListener): void;
+    on(event: 'disconnect', cb: DisconnectListener): void;
+    on(event: 'connect_error', cb: ConnectErrorListener): void;
+    on(event: 'error', cb: RealtimeListener<RealtimeErrorPayload>): void;
+    on<T = unknown>(event: string, cb: RealtimeListener<T>): void;
+    off(event: string, cb: (...args: any[]) => void): void;
+    private dispatch;
+    private emitReserved;
+}
+
 /**
  * MITWAY-BaaS SDK types — only SDK-specific shapes live here.
  * The `User` shape is inlined in `./lib/user` so this package has zero
@@ -89,6 +218,10 @@ interface MitwayBaasConfig {
      * @default true
      */
     autoRefreshToken?: boolean;
+    /**
+     * Realtime transport options. See `RealtimeOptions`.
+     */
+    realtime?: RealtimeOptions;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -146,27 +279,6 @@ declare class Logger {
     logResponse(method: string, url: string, status: number, durationMs: number, body?: any): void;
 }
 
-/**
- * Token Manager for the MITWAY-BaaS SDK.
- *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
- */
-
-declare class TokenManager {
-    private accessToken;
-    private user;
-    /** Fired when the access token changes (used by long-lived consumers). */
-    onTokenChange: (() => void) | null;
-    saveSession(session: AuthSession): void;
-    getSession(): AuthSession | null;
-    getAccessToken(): string | null;
-    setAccessToken(token: string): void;
-    getUser(): User | null;
-    setUser(user: User): void;
-    clearSession(): void;
-}
-
 /**
  * HttpClient with retry, timeout, abort signal composition, and automatic
  * token refresh on 401 INVALID_TOKEN responses.
@@ -409,6 +521,7 @@ declare class MitwayBaasClient {
     private tokenManager;
     readonly auth: Auth;
     readonly database: Database;
+    readonly realtime: Realtime;
     constructor(config?: MitwayBaasConfig);
     /**
      * Escape hatch for callers that need to make custom requests against the
@@ -423,13 +536,13 @@ declare class MitwayBaasClient {
  * Currently ships:
  *   - auth     (signUp, signInWithPassword, signOut, refreshSession, getSession, getUser)
  *   - database (PostgREST-backed query builder via @supabase/postgrest-js)
+ *   - realtime (Socket.IO transport: subscribe / unsubscribe / publish / on)
  *
  * Not yet included (no backend support):
  *   - storage
  *   - functions
  *   - email
  *   - ai
- *   - realtime
  *
  * @packageDocumentation
  */
@@ -449,4 +562,4 @@ declare class MitwayBaasClient {
  */
 declare function createClient(config: MitwayBaasConfig): MitwayBaasClient;
 
-export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, Database, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type SignInRequest, type SignUpRequest, TokenManager, type User, createClient, MitwayBaasClient as default };
+export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, type ConnectErrorListener, type ConnectionListener, Database, type DisconnectListener, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, Realtime, type RealtimeErrorPayload, type RealtimeListener, type RealtimeMessageMeta, type RealtimeOptions, type SignInRequest, type SignUpRequest, type SubscribeResult, TokenManager, type User, createClient, MitwayBaasClient as default };

package/dist/index.js

@@ -854,18 +854,239 @@ var Database = class {
   }
 };
 
+// src/modules/realtime.ts
+import { io } from "socket.io-client";
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+var Realtime = class {
+  socket = null;
+  baseUrl;
+  options;
+  anonKey;
+  tokenManager;
+  listeners = /* @__PURE__ */ new Map();
+  reserved = {
+    connect: /* @__PURE__ */ new Set(),
+    disconnect: /* @__PURE__ */ new Set(),
+    connect_error: /* @__PURE__ */ new Set(),
+    error: /* @__PURE__ */ new Set()
+  };
+  connecting = null;
+  subscribedChannels = /* @__PURE__ */ new Set();
+  constructor(baseUrl, tokenManager, anonKey, options = {}) {
+    this.baseUrl = baseUrl;
+    this.tokenManager = tokenManager;
+    this.anonKey = anonKey;
+    this.options = options;
+  }
+  // -----------------------------------------------------------------
+  // Connection lifecycle
+  // -----------------------------------------------------------------
+  get isConnected() {
+    return this.socket?.connected === true;
+  }
+  get socketId() {
+    return this.socket?.id;
+  }
+  /** Explicitly open the connection. Safe to call multiple times; only
+   *  opens one socket per instance. Subsequent calls during connection
+   *  return the same in-flight promise. */
+  connect() {
+    if (this.isConnected) {
+      return Promise.resolve();
+    }
+    if (this.connecting) {
+      return this.connecting;
+    }
+    this.connecting = this.openSocket();
+    return this.connecting;
+  }
+  openSocket() {
+    const token = this.tokenManager.getAccessToken() ?? this.anonKey;
+    if (!token) {
+      const err = new MitwayBaasError(
+        "Realtime requires an access token or anonKey",
+        401,
+        "AUTH_INVALID_API_KEY"
+      );
+      this.connecting = null;
+      return Promise.reject(err);
+    }
+    const timeoutMs = this.options.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    const socket = io(this.baseUrl, {
+      path: this.options.path,
+      transports: this.options.transports ?? ["websocket"],
+      auth: { token, ...this.options.extraAuth ?? {} },
+      reconnection: true,
+      timeout: timeoutMs
+    });
+    this.socket = socket;
+    socket.onAny((event, ...args) => this.dispatch(event, args));
+    socket.on("connect", () => this.emitReserved("connect"));
+    socket.on("disconnect", (reason) => this.emitReserved("disconnect", reason));
+    socket.on("connect_error", (err) => this.emitReserved("connect_error", err));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        socket.off("connect", onConnect);
+        socket.off("connect_error", onConnectError);
+        reject(
+          new MitwayBaasError(
+            `Realtime connection timeout after ${timeoutMs}ms`,
+            408,
+            "CONNECTION_TIMEOUT"
+          )
+        );
+        this.connecting = null;
+      }, timeoutMs);
+      const clear = () => {
+        clearTimeout(timer);
+        socket.off("connect", onConnect);
+        socket.off("connect_error", onConnectError);
+      };
+      const onConnect = () => {
+        clear();
+        this.connecting = null;
+        resolve();
+      };
+      const onConnectError = (err) => {
+        clear();
+        this.connecting = null;
+        reject(
+          new MitwayBaasError(err.message, 0, "CONNECTION_FAILED")
+        );
+      };
+      socket.once("connect", onConnect);
+      socket.once("connect_error", onConnectError);
+    });
+  }
+  /** Close the socket and clear in-memory subscription state. Reserved
+   *  listeners survive so callers can reconnect later via `connect()`. */
+  disconnect() {
+    if (!this.socket) {
+      return;
+    }
+    this.socket.disconnect();
+    this.socket = null;
+    this.subscribedChannels.clear();
+  }
+  // -----------------------------------------------------------------
+  // Subscribe / Unsubscribe / Publish
+  // -----------------------------------------------------------------
+  async subscribe(channel) {
+    await this.connect();
+    const socket = this.socket;
+    if (!socket) {
+      return {
+        ok: false,
+        channel,
+        error: { code: "NOT_CONNECTED", message: "Socket is not connected" }
+      };
+    }
+    const result = await new Promise((resolve) => {
+      socket.emit("realtime:subscribe", { channel }, (ack) => {
+        resolve(ack);
+      });
+    });
+    if (result.ok) {
+      this.subscribedChannels.add(channel);
+    }
+    return result;
+  }
+  /** Fire-and-forget. No ack from the server. */
+  unsubscribe(channel) {
+    this.subscribedChannels.delete(channel);
+    this.socket?.emit("realtime:unsubscribe", { channel });
+  }
+  /** Publish via the Socket.IO transport. Subject to RLS INSERT policy
+   *  on `realtime.messages` (disabled by default — the developer must
+   *  add a policy before clients can publish). Returns immediately; any
+   *  server rejection comes through the `error` reserved event. */
+  publish(channel, event, payload) {
+    this.socket?.emit("realtime:publish", { channel, event, payload });
+  }
+  // TypeScript overload impl signature must be assignable from every
+  // public overload. The public overloads take arg lists of different
+  // shapes (ConnectionListener: 0 args, DisconnectListener: 1 string
+  // arg, RealtimeListener: 2 args), so the implementation uses the
+  // widest possible signature. This matches the pattern in socket.io
+  // itself and is the standard TypeScript overload idiom.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(event, cb) {
+    if (isReserved(event)) {
+      this.reserved[event].add(cb);
+      return;
+    }
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(cb);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  off(event, cb) {
+    if (isReserved(event)) {
+      this.reserved[event].delete(cb);
+      return;
+    }
+    this.listeners.get(event)?.delete(cb);
+  }
+  // -----------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------
+  dispatch(event, args) {
+    if (isReserved(event)) {
+      return;
+    }
+    if (event === "realtime:error") {
+      const err = args[0] ?? {};
+      this.reserved.error.forEach(
+        (cb) => cb(err, {
+          message_id: "",
+          sender_type: "system",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+      return;
+    }
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) {
+      return;
+    }
+    const envelope = args[0] ?? {};
+    const { meta, ...payload } = envelope;
+    const metaOrStub = meta ?? {
+      message_id: "",
+      sender_type: "system",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    set.forEach((cb) => cb(payload, metaOrStub));
+  }
+  emitReserved(event, ...args) {
+    const set = this.reserved[event];
+    set.forEach((cb) => cb(...args));
+  }
+};
+function isReserved(event) {
+  return event === "connect" || event === "disconnect" || event === "connect_error" || event === "error";
+}
+
 // src/client.ts
 var MitwayBaasClient = class {
   http;
   tokenManager;
   auth;
   database;
+  realtime;
   constructor(config = {}) {
     const logger = new Logger(config.debug);
     this.tokenManager = new TokenManager();
     this.http = new HttpClient(config, this.tokenManager, logger);
     this.auth = new Auth(this.http, this.tokenManager);
     this.database = new Database(this.http, this.tokenManager, config.anonKey);
+    this.realtime = new Realtime(
+      this.http.baseUrl,
+      this.tokenManager,
+      config.anonKey,
+      config.realtime
+    );
   }
   /**
    * Escape hatch for callers that need to make custom requests against the
@@ -888,6 +1109,7 @@ export {
   Logger,
   MitwayBaasClient,
   MitwayBaasError,
+  Realtime,
   TokenManager,
   createClient,
   index_default as default