@noverachat/sdk-web 0.0.3

package/src/types.ts

@@ -0,0 +1,375 @@
+/**
+ * Shared wire types. Must stay in lock-step with:
+ *   noverachat-backend/src/noverachat/ws/protocol.py
+ *   noverachat-backend/src/noverachat/modules/message/schemas.py
+ *
+ * NOTE on `message_id` / `reply_to_id` / `last_*_message_id`: server-side
+ * these are 63-bit Snowflake integers. On the wire they are JSON STRINGS
+ * because JS `Number` can only represent integers up to 2^53 exactly.
+ * Stringifying preserves precision; the SDK never converts them back to
+ * Number. Compare with `BigInt(a) > BigInt(b)`.
+ */
+
+/** 63-bit Snowflake serialized as a JSON string. Treat as opaque. */
+export type MessageIdStr = string;
+
+/**
+ * Wire frame types + shared string enums are GENERATED from
+ * packages/protocol/schema (single source of truth). Do not hand-edit them
+ * here — edit the schema and run `pnpm --filter @noverachat/protocol gen`.
+ * Re-exported so the rest of the SDK keeps importing them from "./types.js".
+ */
+import type {
+  MessageType, DeleteScope, FileKind, FileThumbnailStatus,
+  WsInbound, WsOutbound, WsChatSend, WsReadWatermark, WsTypingSend, WsPing,
+  WsConnected, WsAck, WsChatReceive, WsMessageUpdated, WsMessageDeleted,
+  WsMessagesCleared, WsReactionAdded, WsReactionRemoved, WsSyncTick,
+  WsTypingBroadcast, WsRoomEvent, WsAnnouncementEvent, WsPresence, WsPong,
+  WsError, WsCloseNotice,
+} from "./generated/wire.js";
+
+export type {
+  MessageType, DeleteScope, FileKind, FileThumbnailStatus,
+  WsInbound, WsOutbound, WsChatSend, WsReadWatermark, WsTypingSend, WsPing,
+  WsConnected, WsAck, WsChatReceive, WsMessageUpdated, WsMessageDeleted,
+  WsMessagesCleared, WsReactionAdded, WsReactionRemoved, WsSyncTick,
+  WsTypingBroadcast, WsRoomEvent, WsAnnouncementEvent, WsPresence, WsPong,
+  WsError, WsCloseNotice,
+};
+
+export interface SenderMini {
+  userId: string;
+  nickname?: string | null;
+  profileImageUrl?: string | null;
+}
+
+export interface ReactionEntry {
+  key: string;
+  userIds: string[];
+  updatedAt: number; // unix ms
+}
+
+export interface MessageOut {
+  appId: string;
+  roomId: string;
+  messageId: MessageIdStr;
+  sender?: SenderMini | null;
+  senderId?: string | null;
+  messageType: MessageType;
+  customType?: string | null;
+  content?: string | null;
+  data?: Record<string, unknown> | null;
+  meta?: Record<string, unknown> | null;
+  /** Custom metadata attached by the sender (extracted from `data._customMeta`).
+   *  Null when the sender didn't attach anything. */
+  customMeta?: Record<string, unknown> | null;
+  /** Snowflake bigint (string) of the attached file, when this is a file
+   *  message. Use ``chat.getFileUrl(fileId)`` to obtain a short-lived
+   *  signed download URL, or ``chat.getFileMeta(fileId)`` for metadata
+   *  without the download. Null for text-only messages. */
+  fileId?: MessageIdStr | null;
+  /** Inline file metadata embedded by the server on chat_receive — lets
+   *  the UI render a placeholder (filename, size, dimensions, thumbnail
+   *  status) without an extra round-trip. May be null even when `fileId`
+   *  is set (e.g. for messages loaded via REST history before the inline
+   *  metadata feature shipped); call ``getFileMeta()`` in that case. */
+  file?: FileInline | null;
+  /** Multi-file bundle — set when the message references multiple files
+   *  via ``data.file_ids`` (kind = "file_group"). Each entry has the
+   *  same shape as ``file``. Null for single-file / text-only messages.
+   *  UIs should check ``files?.length > 0`` first and only fall through
+   *  to the ``file`` singleton when the bundle field is absent. */
+  files?: FileInline[] | null;
+  replyToId?: MessageIdStr | null;
+  reactions: ReactionEntry[];
+  createdAt: string;      // ISO
+  createdAtMs: number;    // unix ms
+  updatedAt?: string | null;
+  updatedAtMs?: number | null;
+  deletedAt?: string | null;
+  deletedByUserId?: string | null;
+  deleteScope?: DeleteScope | null;
+  editedCount: number;
+}
+
+export interface RoomUnread {
+  roomId: string;
+  unreadCount: number;
+  lastReadMessageId: MessageIdStr | null;
+  lastMessageId: MessageIdStr | null;
+}
+
+export interface Announcement {
+  id: number;
+  roomId: string;
+  content: string;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** One-way user block — KakaoTalk-style.
+ *
+ *  A row in the caller's block list. The blocked user is NOT told they're
+ *  blocked; they keep sending messages that just don't reach the blocker.
+ *  See ``chat.blockUser`` / ``chat.unblockUser`` / ``chat.listBlocks``.
+ */
+export interface Block {
+  blockedUserId: string;
+  reason: string | null;
+  /** ISO-8601 UTC. */
+  createdAt: string;
+}
+
+/** 방 초대 링크 (카톡 오픈채팅 URL 스타일). Minted by an OPERATOR via
+ *  ``room.createInvite()``; consumed by any user via ``chat.acceptInvite()``. */
+export interface InviteToken {
+  /** URL-safe short id (~22 chars). Embed in the shareable URL as-is. */
+  token: string;
+  roomId: string;
+  createdBy: string;
+  /** ISO-8601 UTC. */
+  createdAt: string;
+  /** ISO-8601 UTC. `null` = never expires. */
+  expiresAt: string | null;
+  /** `null` = unlimited uses. */
+  maxUses: number | null;
+  /** Successful `accept` calls so far. */
+  usedCount: number;
+  /** ISO-8601 UTC. `null` = still active (assuming not expired / exhausted). */
+  revokedAt: string | null;
+}
+
+/** Result of `chat.acceptInvite(token)`. */
+export interface AcceptInviteResult {
+  roomId: string;
+  roomName: string | null;
+  /** True when the caller was already an active member — the call is a
+   *  no-op and does NOT bump the invite's `used_count`. Useful for
+   *  deep-link flows that may be triggered on re-open. */
+  wasAlreadyMember: boolean;
+}
+
+/** One member shown in a channel-list avatar mosaic. */
+export interface MemberPreview {
+  userId: string;
+  nickname: string | null;
+  profileImageUrl: string | null;
+  /** Cluster-wide presence dot. `null` = not resolved (endpoint didn't
+   *  include it). Consumers rendering a green/gray dot should treat
+   *  `null` and `false` differently only if they care about the
+   *  "unknown" state. */
+  isOnline: boolean | null;
+}
+
+export interface UnreadRoomItem {
+  roomId: string;
+  name: string | null;
+  /** "ONE" | "GROUP" | "SUPER_GROUP" — lets the UI pick a 1-up vs mosaic avatar. */
+  roomType: string | null;
+  unreadCount: number;
+  lastMessageId: MessageIdStr | null;
+  /** One-line preview shown under the room name in the channel list.
+   *  TEXT/SYSTEM → first 200 chars, EMOTICON → "[이모티콘]", images/videos/
+   *  files → "[사진]" / "[동영상]" / "[파일] name". Null when the room has
+   *  no messages yet (or was just cleared). */
+  lastMessagePreview: string | null;
+  lastReadMessageId: MessageIdStr | null;
+  /** Total active (non-KICKED) members incl. the caller — the count badge. */
+  memberCount: number;
+  /** Up to 4 OTHER members (caller excluded) for the avatar mosaic. */
+  members: MemberPreview[];
+}
+
+export interface UnreadSummary {
+  total: number;
+  rooms: UnreadRoomItem[];
+}
+
+export interface AppPolicy {
+  appId: string;
+  /** When true, any non-KICKED room member can call
+   *  `room.deleteAllMessages()`. When false, only operators (or super-admin)
+   *  can. UIs should gate the destructive button on this. */
+  allowMemberBulkDelete: boolean;
+  /** When false, server does NOT broadcast `sync_tick` frames — hide
+   *  read-receipt badges client-side. Per-user unread counts via REST
+   *  still work (DB tracking is independent of the broadcast). */
+  readReceiptsEnabled: boolean;
+  /** When false, the server silently drops inbound `typing` frames and
+   *  no peer ever sees "alice is typing…". SDK callers should also
+   *  short-circuit `room.setTyping()` based on this flag so a disabled
+   *  app doesn't pay the WS frame cost per keystroke. */
+  typingIndicatorsEnabled: boolean;
+  /** When true, any non-KICKED room member can hard-delete another
+   *  member's message (scope=ALL). Default false — sender-or-operator
+   *  only. UIs should gate the "Delete for everyone" button on other
+   *  users' messages by this flag. */
+  deleteAnyMessageEnabled: boolean;
+}
+
+/** Push providers we can deliver to. Matches the backend `TokenType`. */
+export type DeviceTokenType = "FCM" | "APNS" | "HUAWEI";
+
+/** Coarse device platform — used only for display / analytics on the
+ *  server. Matches the backend `DeviceOS`. */
+export type DeviceOS = "iOS" | "Android" | "Web";
+
+export interface RegisterDeviceParams {
+  /** Client-stable installation id. NOT the push token — tokens rotate,
+   *  this should not. Re-registering with the same deviceId just
+   *  refreshes the stored token. */
+  deviceId: string;
+  /** The FCM / APNS / HMS push token. */
+  token: string;
+  tokenType: DeviceTokenType;
+  os?: DeviceOS;
+  appVersion?: string;
+}
+
+export interface DeviceInfo {
+  deviceId: string;
+  tokenType: DeviceTokenType;
+  /** Server returns only a short prefix of the token — it's a credential
+   *  and the caller already holds the full value. */
+  tokenPreview: string;
+  os: DeviceOS | null;
+  appVersion: string | null;
+  pushEnabled: boolean;
+  lastActiveAt: string | null;
+  createdAt: string;
+}
+
+export interface SendParams {
+  content?: string;
+  messageType?: "TEXT" | "FILE" | "EMOTICON";
+  customType?: string;
+  data?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  /** Attach an already-committed file (returned by ``room.sendFile()``'s
+   *  internal upload flow, or by a prior ``presignFileUpload()`` +
+   *  ``commitFileUpload()`` if you're orchestrating the upload manually).
+   *  The message_type will be auto-set to ``FILE`` when this is supplied. */
+  fileId?: MessageIdStr;
+  /** Multi-file bundle — attach N already-committed files as ONE
+   *  message. The SDK sets ``message_type = "FILE"``, ``file_id = null``,
+   *  and writes the ids into ``data.file_ids`` (with
+   *  ``data.kind = "file_group"``). Use ``room.uploadFileOnly()`` per
+   *  file to collect the ids first. Mutually exclusive with ``fileId`` —
+   *  when both are set, ``fileIds`` wins. */
+  fileIds?: MessageIdStr[];
+  /** Apply the "no-forward" flag to the whole bundle (mirrors the
+   *  per-file flag set at upload time). Written to
+   *  ``data.forward_blocked`` for the receiving client to gate its
+   *  forward-toolbar button on. */
+  forwardBlocked?: boolean;
+  replyToId?: MessageIdStr;
+  /** Set when this send is forwarding an existing message. The server
+   *  uses it to enforce the source file's ``forwardBlocked`` flag (Phase
+   *  C #7): if the source's file is no-forward AND the destination room
+   *  differs from the source room, the send is rejected with
+   *  ``NC-FILE-014``. Pass the ORIGINAL message's ``messageId``. */
+  forwardOfMessageId?: MessageIdStr;
+  /** Arbitrary custom metadata attached to the message. Stored under
+   *  `data._customMeta`. Surfaces on receiving clients as
+   *  `MessageOut.customMeta`. */
+  customMeta?: Record<string, unknown>;
+}
+
+
+
+/** Compact metadata embedded in chat_receive frames. The full ``FileMeta``
+ *  shape is returned by ``chat.getFileMeta(fileId)`` and matches the
+ *  ``GET /files/{id}/meta`` response — currently identical to this
+ *  inline form. */
+export interface FileInline {
+  id: MessageIdStr;
+  kind: FileKind;
+  mime: string;
+  /** Bytes. */
+  size: number;
+  /** Original filename as the uploader sent it — may be null when not
+   *  known (some clients omit it). */
+  name?: string | null;
+  /** Pixel dimensions — populated for image / video after the thumbnail
+   *  worker probes the file. May be null until the worker finishes. */
+  width?: number | null;
+  height?: number | null;
+  /** Seconds — video only. */
+  durationSec?: number | null;
+  thumbnailStatus: FileThumbnailStatus;
+  /** Uploader-set "no forward" flag. When true, another user cannot
+   *  forward a message carrying this file to a different room — the
+   *  server rejects such sends with NC-FILE-014. UIs should surface a
+   *  🚫 badge and hide the forward action for these files. Downloads
+   *  and same-room views stay allowed. */
+  forwardBlocked: boolean;
+}
+
+/** Same shape as ``FileInline`` for now — kept distinct so future
+ *  meta-only fields (e.g. uploader info, dedupe hash) can land here
+ *  without forcing them onto every WS frame. */
+export type FileMeta = FileInline;
+
+/** Per-call options for ``room.sendFile()``. */
+export interface SendFileOptions {
+  /** Optional progress callback fired during the S3 PUT. ``loaded`` and
+   *  ``total`` are bytes; ``ratio`` is in [0, 1]. Called from an XHR
+   *  ``upload.onprogress`` listener — at minimum the final ``ratio=1``
+   *  fires when the PUT completes. */
+  onProgress?: (p: { loaded: number; total: number; ratio: number }) => void;
+  /** Override the declared kind. Default: derived from the File's MIME
+   *  type (``image/*`` → image, ``video/*`` → video, else file). Useful
+   *  if you need to force a particular UI rendering. */
+  kind?: FileKind;
+  /** Override the declared filename. Default: ``file.name``. */
+  name?: string;
+  /** 파일 전달 제한 — when true, the uploader (this call) marks the
+   *  file as "no-forward". Other users won't be able to forward the
+   *  resulting message to a different room; the server rejects such
+   *  sends with ``NC-FILE-014``. Downloads and same-room views stay
+   *  allowed. Default false. */
+  forwardBlocked?: boolean;
+  /** Arbitrary custom metadata attached to the resulting file message.
+   *  Stored under `data._customMeta`. Surfaces on receiving clients as
+   *  `MessageOut.customMeta`. */
+  customMeta?: Record<string, unknown>;
+}
+
+/** Backend response from ``POST /api/v1/files`` (presign step). */
+export interface FilePresignResponse {
+  fileId: MessageIdStr;
+  uploadUrl: string;
+  /** Headers the client MUST send on its S3 PUT. At minimum carries
+   *  ``Content-Type`` — the presigned URL is bound to it, so a mismatch
+   *  causes the PUT to fail with 403. */
+  headers: Record<string, string>;
+  expiresAtMs: number;
+}
+
+// ------------------ WS envelopes (outbound to server) ------------------
+
+// (wire frame types are generated — see re-export block near the top)
+
+export interface ClientOptions {
+  appId: string;
+  endpoint: string;                // e.g. "https://chat.example.com"
+  wsEndpoint?: string;             // defaults to endpoint with ws(s)://
+  tokenProvider: () => Promise<string>;
+  autoReconnect?: boolean;         // default true
+  pingIntervalMs?: number;         // default 20_000
+  readWatermarkDebounceMs?: number;// default 1500
+  maxReconnectDelayMs?: number;    // default 30_000
+  /**
+   * Seed the per-room "highest-seen message_id" map at construction time.
+   * Use this to feed back values your app persisted to local storage in a
+   * previous session, so a cold page load can still drive `?since=...` on
+   * the WS handshake and surface unread messages via `chat.backfill()`.
+   *
+   * Shape: { [roomId]: lastSeenMessageId }
+   */
+  initialLastMessageIds?: Record<string, MessageIdStr>;
+  fetch?: typeof fetch;
+  WebSocketImpl?: typeof WebSocket;
+  logger?: (lvl: "debug" | "info" | "warn" | "error", msg: string, ctx?: unknown) => void;
+}

package/src/utils/debounce.ts

@@ -0,0 +1,14 @@
+/** Debounce a single-arg function: calls are coalesced within `waitMs`. */
+
+export function debounce<T>(waitMs: number, fn: (arg: T) => void): (arg: T) => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let lastArg: T | undefined;
+  return (arg: T) => {
+    lastArg = arg;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      if (lastArg !== undefined) fn(lastArg);
+      timer = null;
+    }, waitMs);
+  };
+}