@noverachat/sdk-web 0.0.3

package/src/generated/README.ko.md

@@ -0,0 +1,15 @@
+[English](README.md) | [한국어](README.ko.md)
+
+# `generated/` — 편집 금지
+
+이 폴더의 모든 파일은 [`packages/protocol`](../../../protocol/README.ko.md)의 와이어 프로토콜 스키마에서 **자동 생성**된다. 손으로 고치지 마라 — 다음 생성 때 덮어써진다.
+
+- **`wire.ts`** — 와이어 위 프레임 타입(`Ws*` in/out) + 공유 문자열 enum(`MessageType`, `DeleteScope`, `FileKind`, `FileThumbnailStatus`). `src/types.ts`가 이걸 재노출하므로, SDK의 나머지는 평소처럼 `./types.js`에서 import한다.
+
+## 와이어 타입을 바꾸려면
+
+1. `packages/protocol/schema/wire.schema.json`(단일 출처) 편집.
+2. `pnpm gen` 실행 (레포 루트에서).
+3. `sdk-web`(이 파일)과 `sdk-dart`가 함께 재생성된다.
+
+전체 파이프라인·설계 결정·함정은 [`packages/protocol`](../../../protocol/README.ko.md) 참고. CI는 `pnpm gen:check`로 커밋된 생성물이 stale이면 실패시킨다.

package/src/generated/README.md

@@ -0,0 +1,15 @@
+[English](README.md) | [한국어](README.ko.md)
+
+# `generated/` — do not edit
+
+Everything in this folder is **auto-generated** from the wire-protocol schema in [`packages/protocol`](../../../protocol/README.md). Don't hand-edit these files — your changes will be overwritten on the next generate.
+
+- **`wire.ts`** — the on-the-wire frame types (`Ws*` in/out) + shared string enums (`MessageType`, `DeleteScope`, `FileKind`, `FileThumbnailStatus`). `src/types.ts` re-exports them, so the rest of the SDK imports from `./types.js` as usual.
+
+## To change a wire type
+
+1. Edit `packages/protocol/schema/wire.schema.json` (the single source of truth).
+2. Run `pnpm gen` (from the repo root).
+3. Both `sdk-web` (this file) and `sdk-dart` regenerate together.
+
+See [`packages/protocol`](../../../protocol/README.md) for the full pipeline, design decisions, and gotchas. CI runs `pnpm gen:check` to fail if these committed files are stale.

package/src/generated/wire.ts

@@ -0,0 +1,224 @@
+/* GENERATED — do not edit. Source: packages/protocol/schema/. Run `pnpm gen` (repo root). */
+export type WsInbound =
+  | WsConnected
+  | WsAck
+  | WsChatReceive
+  | WsMessageUpdated
+  | WsMessageDeleted
+  | WsMessagesCleared
+  | WsReactionAdded
+  | WsReactionRemoved
+  | WsSyncTick
+  | WsTypingBroadcast
+  | WsRoomEvent
+  | WsAnnouncementEvent
+  | WsPresence
+  | WsPong
+  | WsError
+  | WsCloseNotice;
+export type MessageType = "TEXT" | "FILE" | "EMOTICON" | "ADMIN" | "SYSTEM";
+export type FileKind = "image" | "video" | "file";
+export type FileThumbnailStatus = "pending" | "ready" | "failed" | "skipped";
+export type DeleteScope = "MY" | "ALL";
+export type WsOutbound = WsChatSend | WsReadWatermark | WsTypingSend | WsPing;
+
+export interface WsConnected {
+  type: "connected";
+  session_id: string;
+  server_ts: number;
+  protocol_version: string;
+  gap_fill_url: string;
+}
+export interface WsAck {
+  type: "ack";
+  temp_id: string | null;
+  message_id: string;
+  room_id: string;
+  server_ts: number;
+}
+export interface WsChatReceive {
+  type: "chat_receive";
+  room_id: string;
+  /**
+   * Snowflake id as string
+   */
+  message_id: string;
+  sender_id: string | null;
+  message_type: MessageType;
+  custom_type?: string | null;
+  content?: string | null;
+  data?: {
+    [k: string]: unknown;
+  } | null;
+  meta?: {
+    [k: string]: unknown;
+  } | null;
+  file_id?: string | null;
+  file?: FileInlineWire | null;
+  files?: FileInlineWire[] | null;
+  reply_to_id?: string | null;
+  /**
+   * unix ms
+   */
+  created_at: number;
+  /**
+   * unix ms
+   */
+  server_ts: number;
+  /**
+   * server-echoed on self-echo only
+   */
+  temp_id?: string | null;
+}
+export interface FileInlineWire {
+  id: string;
+  kind: FileKind;
+  mime: string;
+  size: number;
+  name?: string | null;
+  width?: number | null;
+  height?: number | null;
+  duration_sec?: number | null;
+  thumbnail_status: FileThumbnailStatus;
+  forward_blocked?: boolean;
+}
+export interface WsMessageUpdated {
+  type: "message_updated";
+  room_id: string;
+  message_id: string;
+  content?: string | null;
+  data?: {
+    [k: string]: unknown;
+  } | null;
+  meta?: {
+    [k: string]: unknown;
+  } | null;
+  updated_at: number;
+}
+export interface WsMessageDeleted {
+  type: "message_deleted";
+  room_id: string;
+  message_id: string;
+  scope: DeleteScope;
+  deleted_by_user_id?: string | null;
+  deleted_at: number;
+}
+export interface WsMessagesCleared {
+  type: "messages_cleared";
+  room_id: string;
+  up_to_message_id: string | null;
+  cleared_by_user_id: string | null;
+  cleared_count: number;
+  cleared_at: number;
+}
+export interface WsReactionAdded {
+  type: "reaction_added";
+  room_id: string;
+  message_id: string;
+  reaction_key: string;
+  user_id: string;
+  updated_at: number;
+}
+export interface WsReactionRemoved {
+  type: "reaction_removed";
+  room_id: string;
+  message_id: string;
+  reaction_key: string;
+  user_id: string;
+  updated_at: number;
+}
+export interface WsSyncTick {
+  type: "sync_tick";
+  room_id: string;
+  read_states: {
+    [k: string]: string;
+  };
+}
+export interface WsTypingBroadcast {
+  type: "typing";
+  room_id: string;
+  user_id: string;
+  is_typing: boolean;
+}
+export interface WsRoomEvent {
+  type: "room_event";
+  event: string;
+  room_id: string;
+  target_user_id: string;
+  by_user_id: string | null;
+  server_ts: number;
+}
+export interface WsAnnouncementEvent {
+  type: "announcement_event";
+  event: "CREATED" | "UPDATED" | "DELETED";
+  room_id: string;
+  announcement: AnnouncementWire | null;
+  announcement_id: number;
+  by: string;
+  at: number;
+}
+export interface AnnouncementWire {
+  id: number;
+  room_id: string;
+  content: string;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+export interface WsPresence {
+  type: "presence";
+  user_id: string;
+  online: boolean;
+  at: number;
+}
+export interface WsPong {
+  type: "pong";
+  server_ts: number;
+  client_ts?: number | null;
+}
+export interface WsError {
+  type: "error";
+  code: string;
+  message: string;
+  details?: {
+    [k: string]: unknown;
+  } | null;
+}
+export interface WsCloseNotice {
+  type: "close_notice";
+  reason: string;
+  retry_after_ms?: number;
+}
+export interface WsChatSend {
+  type: "chat_send";
+  room_id: string;
+  content?: string | null;
+  message_type: "TEXT" | "FILE" | "EMOTICON";
+  custom_type?: string | null;
+  data?: {
+    [k: string]: unknown;
+  } | null;
+  meta?: {
+    [k: string]: unknown;
+  } | null;
+  file_id?: string | null;
+  reply_to_id?: string | null;
+  forward_of_message_id?: string | null;
+  temp_id?: string | null;
+  client_ts: number;
+}
+export interface WsReadWatermark {
+  type: "read_watermark";
+  room_id: string;
+  last_read_message_id: string;
+}
+export interface WsTypingSend {
+  type: "typing";
+  room_id: string;
+  is_typing: boolean;
+}
+export interface WsPing {
+  type: "ping";
+  client_ts: number;
+}
+

package/src/index.ts

@@ -0,0 +1,27 @@
+export { NoveraChat } from "./client.js";
+export { Room, type RoomEvents } from "./features/room.js";
+export {
+  ErrorCode,
+  NoveraChatError,
+  type ErrorCodeValue,
+} from "./errors.js";
+export type {
+  AcceptInviteResult,
+  Announcement,
+  AppPolicy,
+  Block,
+  ClientOptions,
+  DeleteScope,
+  InviteToken,
+  MessageOut,
+  MessageType,
+  ReactionEntry,
+  RoomUnread,
+  SendParams,
+  SenderMini,
+  UnreadRoomItem,
+  UnreadSummary,
+  WsAnnouncementEvent,
+  WsInbound,
+  WsOutbound,
+} from "./types.js";

package/src/internal/event-bus.ts

@@ -0,0 +1,42 @@
+/** Tiny typed EventEmitter. No deps. */
+
+type Handler<T> = (payload: T) => void;
+
+// NOTE: constraint is `object` rather than `Record<string, unknown>` because
+// `interface RoomEvents { ... }` (no explicit index signature) does not
+// satisfy the latter under modern TS strictness — interfaces aren't
+// considered assignable to index-signature types. `object` is enough since
+// we only key into Events via its declared keys.
+export class EventBus<Events extends object> {
+  private handlers: { [K in keyof Events]?: Set<Handler<Events[K]>> } = {};
+
+  on<K extends keyof Events>(event: K, fn: Handler<Events[K]>): () => void {
+    let set = this.handlers[event];
+    if (!set) {
+      set = new Set();
+      this.handlers[event] = set;
+    }
+    set.add(fn);
+    return () => this.off(event, fn);
+  }
+
+  off<K extends keyof Events>(event: K, fn: Handler<Events[K]>): void {
+    this.handlers[event]?.delete(fn);
+  }
+
+  emit<K extends keyof Events>(event: K, payload: Events[K]): void {
+    const set = this.handlers[event];
+    if (!set) return;
+    for (const h of set) {
+      try {
+        h(payload);
+      } catch {
+        // user handler error must not break the bus
+      }
+    }
+  }
+
+  removeAll(): void {
+    this.handlers = {};
+  }
+}

package/src/internal/temp-id.ts

@@ -0,0 +1,10 @@
+/** Lightweight client-side UUID-ish for optimistic UI keys. */
+
+export function tempId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return `tmp_${crypto.randomUUID()}`;
+  }
+  // fallback — collision-resistant enough for UI tracking
+  const bytes = Array.from({ length: 16 }, () => Math.floor(Math.random() * 256));
+  return "tmp_" + bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/transport/http.ts

@@ -0,0 +1,81 @@
+import { NoveraChatError } from "../errors.js";
+
+export interface HttpOptions {
+  baseUrl: string;
+  appId: string;
+  tokenProvider: () => Promise<string>;
+  fetch?: typeof fetch;
+  // Optional structured logger — same signature as the WS transport's
+  // so the demo / consumers can attach a single sink for both pipes.
+  // Frame/request-level lines come in at ``debug``; non-2xx responses
+  // and exceptions at ``warn`` / ``error``.
+  logger?: (
+    lvl: "debug" | "info" | "warn" | "error",
+    msg: string,
+    ctx?: unknown,
+  ) => void;
+}
+
+export class HttpClient {
+  constructor(private opts: HttpOptions) {}
+
+  async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    query?: Record<string, string | number | undefined>,
+  ): Promise<T> {
+    const token = await this.opts.tokenProvider();
+    const url = this.buildUrl(path, query);
+    // Build RequestInit conditionally — under `exactOptionalPropertyTypes`,
+    // assigning `body: undefined` is not the same as omitting `body`.
+    const init: RequestInit = {
+      method,
+      headers: {
+        "Authorization": `Bearer ${token}`,
+        "X-Noverachat-App-Id": this.opts.appId,
+        ...(body != null ? { "Content-Type": "application/json" } : {}),
+      },
+    };
+    if (body != null) init.body = JSON.stringify(body);
+    // Native browser `fetch` is bound to `window`/`globalThis` — calling it
+    // as `this._fetch(...)` (method-style on HttpClient) makes `this` the
+    // HttpClient and triggers "Failed to execute 'fetch' on 'Window':
+    // Illegal invocation". Detach into a local variable so the call is
+    // plain function invocation.
+    const fetchFn = this.opts.fetch ?? globalThis.fetch;
+    // Per-request trace. Body is logged as-is (not redacted) — the
+    // SDK doesn't see secrets at this layer (the bearer token is in
+    // the Authorization header which we don't echo).
+    this.opts.logger?.("debug", `rest_req ${method} ${path}`,
+      body != null ? { body, query } : { query });
+    const startedAt = Date.now();
+    const res = await fetchFn(url, init);
+    const elapsedMs = Date.now() - startedAt;
+    if (res.status === 204) {
+      this.opts.logger?.("debug",
+        `rest_res ${method} ${path} 204 ${elapsedMs}ms`);
+      return undefined as unknown as T;
+    }
+    const text = await res.text();
+    const parsed = text ? (JSON.parse(text) as unknown) : null;
+    this.opts.logger?.("debug",
+      `rest_res ${method} ${path} ${res.status} ${elapsedMs}ms`,
+      parsed);
+    if (!res.ok) {
+      throw NoveraChatError.fromResponse(res.status, parsed);
+    }
+    return parsed as T;
+  }
+
+  private buildUrl(path: string, query?: Record<string, string | number | undefined>): string {
+    const base = this.opts.baseUrl.replace(/\/+$/, "");
+    const url = new URL(base + path);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+}

package/src/transport/ws.ts

@@ -0,0 +1,200 @@
+/**
+ * Reconnecting WebSocket — state machine per docs/ws_protocol.md §6.
+ *
+ *   IDLE → CONNECTING → OPEN → RECONNECTING → CONNECTING …
+ *
+ * - Exponential backoff with jitter (500ms → 30s cap)
+ * - Refuses to reconnect on 1008/4001/4002 (policy / app-inactive / user-banned)
+ * - Emits typed events via callbacks
+ */
+
+import type { WsInbound, WsOutbound } from "../types.js";
+
+export type WsState = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+
+export interface ReconnectingWsOptions {
+  urlBuilder: () => Promise<string>;
+  onMessage: (msg: WsInbound) => void;
+  onStateChange?: (s: WsState) => void;
+  onOpen?: () => void;
+  pingIntervalMs: number;
+  maxReconnectDelayMs: number;
+  autoReconnect: boolean;
+  WebSocketImpl?: typeof WebSocket;
+  logger?: (lvl: "debug" | "info" | "warn" | "error", msg: string, ctx?: unknown) => void;
+}
+
+// Codes on which we must NOT try to reconnect
+const NO_RECONNECT = new Set<number>([1008, 4001, 4002, 4003]);
+
+export class ReconnectingWs {
+  private ws: WebSocket | null = null;
+  private state: WsState = "idle";
+  private attempt = 0;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private explicitClose = false;
+  // Outbound buffer used while the socket is transiently down (reconnect
+  // window between a server-side close and the next successful open). FIFO.
+  // Capped to avoid an unbounded queue if the server is hard-down — chat_send
+  // bursts past the cap are dropped (caller sees `send -> false` the usual
+  // way). Pings and typing frames are NOT queued: pings are stateless
+  // heartbeats and a stale typing event is worse than no event.
+  private outboundQueue: WsOutbound[] = [];
+  private static readonly OUTBOUND_QUEUE_CAP = 200;
+
+  constructor(private opts: ReconnectingWsOptions) {}
+
+  get currentState(): WsState {
+    return this.state;
+  }
+
+  async connect(): Promise<void> {
+    this.explicitClose = false;
+    await this.openOnce();
+  }
+
+  close(): void {
+    this.explicitClose = true;
+    this.setState("closed");
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.pingTimer = null;
+    this.outboundQueue = [];
+    this.ws?.close(1000, "client close");
+    this.ws = null;
+  }
+
+  send(msg: WsOutbound): boolean {
+    if (this.ws && this.ws.readyState === 1 /* OPEN */) {
+      this.ws.send(JSON.stringify(msg));
+      // Frame-level trace. Pings are tagged ``debug`` so they don't drown
+      // the log at the default verbosity — other frames are ``debug`` too
+      // but they're rare enough per second that consumers (e.g. the demo
+      // log panel) usually want to see them with a toggle.
+      this.opts.logger?.("debug", `ws_send ${msg.type}`, msg);
+      return true;
+    }
+    // Socket not open right now. For frame types where late-delivery is
+    // worse than non-delivery, fail fast and let the caller decide. For
+    // chat_send and read_watermark we buffer and replay on next open so
+    // brief reconnect windows (sub-second) don't surface as "send failed"
+    // noise in the UI.
+    if (msg.type === "ping" || msg.type === "typing") return false;
+    if (this.explicitClose || this.state === "closed") return false;
+    if (this.outboundQueue.length >= ReconnectingWs.OUTBOUND_QUEUE_CAP) {
+      this.opts.logger?.("warn", "ws_outbound_queue_full",
+        { cap: ReconnectingWs.OUTBOUND_QUEUE_CAP, dropping: msg.type });
+      return false;
+    }
+    this.outboundQueue.push(msg);
+    this.opts.logger?.("debug", `ws_send_queued ${msg.type}`,
+      { queueLen: this.outboundQueue.length });
+    return true;
+  }
+
+  private async openOnce(): Promise<void> {
+    this.setState(this.attempt === 0 ? "connecting" : "reconnecting");
+    const WSImpl = this.opts.WebSocketImpl ?? (globalThis.WebSocket as typeof WebSocket);
+    if (!WSImpl) throw new Error("No WebSocket implementation available");
+
+    let url: string;
+    try {
+      url = await this.opts.urlBuilder();
+    } catch (err) {
+      this.opts.logger?.("error", "url_builder_failed", err);
+      this.scheduleReconnect();
+      return;
+    }
+
+    const ws = new WSImpl(url);
+    this.ws = ws;
+
+    ws.onopen = () => {
+      this.attempt = 0;
+      this.setState("open");
+      this.startPings();
+      // Drain anything that piled up while the socket was down. FIFO so
+      // chat_send temp_id ordering matches the user's typing order, which
+      // self-echo dedup in client.ts relies on.
+      if (this.outboundQueue.length > 0) {
+        const drained = this.outboundQueue;
+        this.outboundQueue = [];
+        this.opts.logger?.("info", "ws_outbound_drained", { count: drained.length });
+        for (const m of drained) {
+          try {
+            ws.send(JSON.stringify(m));
+          } catch (err) {
+            this.opts.logger?.("warn", "ws_outbound_drain_failed", err);
+          }
+        }
+      }
+      this.opts.onOpen?.();
+    };
+
+    ws.onmessage = (ev: MessageEvent) => {
+      try {
+        const data = typeof ev.data === "string" ? ev.data : ev.data.toString();
+        const parsed = JSON.parse(data) as WsInbound;
+        // Frame-level trace of every inbound frame BEFORE dispatch so the
+        // log line lands even if downstream handlers throw.
+        this.opts.logger?.("debug",
+          `ws_recv ${(parsed as { type?: string }).type ?? "?"}`,
+          parsed);
+        this.opts.onMessage(parsed);
+      } catch (err) {
+        this.opts.logger?.("warn", "ws_parse_failed", err);
+      }
+    };
+
+    ws.onerror = (ev) => {
+      this.opts.logger?.("warn", "ws_error", ev);
+    };
+
+    ws.onclose = (ev: CloseEvent) => {
+      this.stopPings();
+      this.ws = null;
+      if (this.explicitClose) {
+        this.setState("closed");
+        return;
+      }
+      if (NO_RECONNECT.has(ev.code)) {
+        this.opts.logger?.("warn", "ws_fatal_close", { code: ev.code, reason: ev.reason });
+        this.setState("closed");
+        return;
+      }
+      if (this.opts.autoReconnect) this.scheduleReconnect();
+      else this.setState("closed");
+    };
+  }
+
+  private scheduleReconnect(): void {
+    this.attempt += 1;
+    const base = 500;
+    const cap = this.opts.maxReconnectDelayMs;
+    const exp = Math.min(cap, base * 2 ** (this.attempt - 1));
+    const jitter = Math.floor(Math.random() * base);
+    const delay = exp + jitter;
+    this.opts.logger?.("info", "ws_reconnect_scheduled", { attempt: this.attempt, delay });
+    this.setState("reconnecting");
+    setTimeout(() => {
+      void this.openOnce();
+    }, delay);
+  }
+
+  private startPings(): void {
+    this.stopPings();
+    this.pingTimer = setInterval(() => {
+      this.send({ type: "ping", client_ts: Date.now() });
+    }, this.opts.pingIntervalMs);
+  }
+
+  private stopPings(): void {
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.pingTimer = null;
+  }
+
+  private setState(s: WsState): void {
+    if (s === this.state) return;
+    this.state = s;
+    this.opts.onStateChange?.(s);
+  }
+}