@snakechat/commskit-node 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prateek0128
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @snakechat/commskit-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js / TypeScript server for the commskit wire protocol. It is a sibling of the Python backend
+(`../backend-python`, package `commskit`) and speaks exactly the same protocol
+([`../../docs/archive/PROTOCOL.md`](https://github.com/prateek0128/chat-call-module/blob/main/docs/archive/PROTOCOL.md)), so the existing clients (`mobile/`, `web/`,
+`examples/backend/demo-server-python` page) work against it unchanged. A database created by either backend works with the other
+(same table and column names).
+
+**Status: feature-complete.** Core, chat, call signalling, moderation (block / report / admin review),
+devices + push (Expo, Apple VoIP), the Redis bridge and S3 storage are implemented. 172 tests pass (1 more is
+skipped: it needs a real `redis-server`). Redis, S3, Expo and APNs are tested with fakes, not real services.
+Guides: [`../../docs/backend/backend-node/`](https://github.com/prateek0128/chat-call-module/tree/main/docs/backend/backend-node).
+
+Stack: TypeScript (strict), Node >= 20, ESM, `ws`, `kysely` (better-sqlite3 for tests/demo, `pg` for production),
+`jose` (HS256 JWT, claim `uid`), tsup, vitest.
+
+## Install
+
+```bash
+npm install @snakechat/commskit-node kysely ws jose
+npm install better-sqlite3      # or: pg
+npm install fastify             # or: express   (optional peer dependencies)
+```
+
+## Fastify (chat only)
+
+```ts
+import Fastify from "fastify";
+import Database from "better-sqlite3";
+import { Kysely, SqliteDialect } from "kysely";
+import { ChatFeature, CommsHub, JwtAuth, ensureSchema } from "@snakechat/commskit-node";
+import { commskitPlugin } from "@snakechat/commskit-node/fastify";
+
+const db = new Kysely<any>({ dialect: new SqliteDialect({ database: new Database("comms.db") }) });
+await ensureSchema(db); // creates chats, messages, calls, comms_* tables (idempotent)
+
+const hub = new CommsHub({ auth: new JwtAuth(process.env.JWT_SECRET!), db });
+hub.install(new ChatFeature());               // allow-all policy, LocalDiskStorage("comms_media")
+
+const app = Fastify();
+await app.register(commskitPlugin, { hub });  // REST routes + /ws/:token upgrade
+await app.listen({ port: 8080 });
+```
+
+## Express (chat only)
+
+```ts
+import { createServer } from "node:http";
+import express from "express";
+import { commskitRouter, attach } from "@snakechat/commskit-node/express";
+
+const app = express();
+app.use(commskitRouter(hub));                 // /chats/...
+const server = createServer(app);
+attach(server, hub);                          // /ws/:token
+server.listen(8080);
+```
+
+No framework: `createServer((req, res) => restListener(hub)(req, res))` plus `hub.attach(server)`.
+
+## Python name mapping
+
+| Python (`commskit`) | Node (`@snakechat/commskit-node`) |
+|---|---|
+| `CommsHub(auth=, session_factory=, users=, push=, ...)` | `new CommsHub({ auth, db, users, push, connections, rateLimiter, roleResolver, onHandlerError, cameOnlineCooldown })` |
+| `ChatFeature(...).install(hub)` | `hub.install(new ChatFeature({ policy, storage, devices, config }))` |
+| `ChatConfig`, `ChatPolicy`, `AllowAllChatPolicy` | `ChatConfig` (partial object), `ChatPolicy`, `AllowAllChatPolicy` |
+| `JwtAuth`, `StaticUserDirectory`, `NullUserDirectory`, `NoopPush`, `LocalDiskStorage` | same names |
+| `ConnectionManager`, `PresenceBridge`, `RateLimiter`, `RateLimit` | same names |
+| `hub.on(type, handler)`, `hub.on_connect`, `hub.on_disconnect` | `hub.on`, `hub.onConnect(hook, allRoles?)`, `hub.onDisconnect` |
+| `hub.events.on("chat.message_sent", fn)` | same event names |
+| `chat.send_message_as`, `chat.send_system_message`, `chat.delete_user_data` | `chat.sendMessageAs`, `chat.sendSystemMessage`, `chat.deleteUserData` |
+| `hub.ws_router()` / `hub.rest_router()` | `hub.attach(server)` / `hub.handleUpgrade(...)` and `hub.restRoutes()` |
+| `CommsBase.metadata.create_all` | `ensureSchema(db)` |
+
+Handlers receive `(userId, message, db)`; `db` is the hub's Kysely instance (the per-frame "session"; use
+`db.transaction()` where you need atomicity).
+
+## Develop
+
+```bash
+npm install
+npm run typecheck && npm test && npm run build
+python test/golden/generate_golden.py   # re-record the golden frames from the Python backend (optional)
+```
+
+`test/golden.test.ts` replays a scripted exchange against this server and requires frames identical (after
+id/timestamp normalisation) to the fixtures recorded from the Python backend.

package/dist/adapters-8ztjEYtz.d.ts

@@ -0,0 +1,83 @@
+/** Token is missing, invalid or expired. */
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+interface AuthAdapter {
+    /** Return the user id for `token` or throw (any exception = invalid). */
+    userIdFromToken(token: string): string | Promise<string>;
+}
+/** HS256 (by default) JWT auth reading the user id from `claim`. */
+declare class JwtAuth implements AuthAdapter {
+    private key;
+    private algorithm;
+    private claim;
+    constructor(secret: string, options?: {
+        algorithm?: string;
+        claim?: string;
+    } | string);
+    userIdFromToken(token: string): Promise<string>;
+}
+/** Call the adapter, supporting both sync and async implementations. */
+declare function resolveUserId(auth: AuthAdapter, token: string): Promise<string>;
+interface UserProfile {
+    name?: string | null;
+    avatar?: string | null;
+}
+interface UserDirectory {
+    /** Display info for the ids it knows; unknown ids may be omitted. */
+    getProfiles(userIds: readonly string[]): Promise<Record<string, UserProfile>>;
+}
+/** Knows nobody: names fall back to user ids / "Someone". */
+declare class NullUserDirectory implements UserDirectory {
+    getProfiles(): Promise<Record<string, UserProfile>>;
+}
+/** In-memory directory (tests, demos). */
+declare class StaticUserDirectory implements UserDirectory {
+    profiles: Record<string, UserProfile>;
+    constructor(profiles?: Record<string, UserProfile>);
+    getProfiles(userIds: readonly string[]): Promise<Record<string, UserProfile>>;
+}
+interface PushSender {
+    /** Push to every device of `userId`. Must not throw for "no devices". */
+    send(userId: string, title: string, body: string, data: Record<string, unknown>, channel?: string, ttl?: number | null): Promise<void>;
+}
+declare class NoopPush implements PushSender {
+    send(): Promise<void>;
+}
+/** Optional: backs the `/chats/expo/push/token` routes (`SqlDeviceRegistry` is the SQL implementation). */
+interface DeviceRegistry {
+    register(userId: string, payload: Record<string, unknown>): Promise<unknown>;
+    remove(userId: string, payload: Record<string, unknown>): Promise<unknown>;
+}
+interface MediaInfo {
+    file_url: string;
+    file_name: string;
+    file_size: number;
+    file_type: string;
+    media_type: string;
+    thumbnail_url?: string | null;
+    duration?: number | null;
+}
+interface MediaStorage {
+    /** Store the file and return where it lives. Throw `UploadRejected` to reject it with a message. */
+    upload(chatId: number, fileName: string, data: Buffer, mediaType: string): Promise<MediaInfo>;
+    /** Optional: remove a stored file (unsend, user deletion). Must not throw for files already gone. */
+    delete?(fileUrl: string): Promise<void>;
+}
+/** Throw from `MediaStorage.upload` to refuse a file; the message goes to the client (Python: ValueError). */
+declare class UploadRejected extends Error {
+}
+/** Delete files through `storage.delete` when the storage has it. Never throws; returns how many succeeded. */
+declare function deleteMedia(storage: unknown, ...fileUrls: (string | null | undefined)[]): Promise<number>;
+/** Writes files under `root/chat/<chatId>/<mediaType>/`; `file_url` is `baseUrl` + relative path (serve `root` yourself). */
+declare class LocalDiskStorage implements MediaStorage {
+    root: string;
+    baseUrl: string;
+    constructor(root?: string, baseUrl?: string);
+    upload(chatId: number, fileName: string, data: Buffer, mediaType: string): Promise<MediaInfo>;
+    /** Local path of a URL this storage produced; null for anything else (incl. `..` tricks). */
+    pathFor(fileUrl: string): string | null;
+    delete(fileUrl: string): Promise<void>;
+}
+
+export { type AuthAdapter as A, type DeviceRegistry as D, JwtAuth as J, LocalDiskStorage as L, type MediaInfo as M, NoopPush as N, type PushSender as P, StaticUserDirectory as S, UploadRejected as U, AuthError as a, type MediaStorage as b, NullUserDirectory as c, type UserDirectory as d, type UserProfile as e, deleteMedia as f, resolveUserId as r };

package/dist/call.d.ts

@@ -0,0 +1,34 @@
+import { C as CallInfo } from './feature-DwKkuOBh.js';
+export { A as ACTIVE_CALL_STATUSES, a as AllowAllCallPolicy, b as CallChatBridge, c as CallConfig, d as CallDecision, e as CallFeature, f as CallFeatureOptions, g as CallHandlers, h as CallLifecycle, i as CallPolicy, j as CallService, k as allow, l as callLogText, m as defaultCallConfig, n as deny, o as endStatus } from './feature-DwKkuOBh.js';
+export { C as CallsTable, c as callDdl } from './models-DTXEX1Q8.js';
+import './hub-CPrWmIvB.js';
+import 'node:http';
+import 'node:stream';
+import 'ws';
+import './adapters-8ztjEYtz.js';
+import './connections-CGEPiZPF.js';
+import 'kysely';
+import './util-B32rIBVA.js';
+
+declare function callPayload(event: string, info: CallInfo, extra?: Record<string, unknown>): Record<string, any>;
+/** Legacy: caller-side call_initiated / call_ringing carry the *receiver* in caller_id / caller_name. */
+declare const callerView: (info: CallInfo) => Record<string, unknown>;
+/** Legacy: busy is a call_rejected with call_id null. */
+declare function busyPayload(callerId: string, receiverId: string, callType: string): Record<string, unknown>;
+/** Tagged so clients only tear down call UI for call errors. */
+declare const callError: (error: string, extra?: Record<string, unknown>) => Record<string, unknown>;
+
+interface TurnCredentials {
+    username: string;
+    password: string;
+    ttl: number;
+    uris: string[];
+}
+/** username = "<expiry>[:<userId>]", password = base64(HMAC-SHA1(secret, username)). */
+declare function turnCredentials(secret: string, uris: readonly string[], ttl?: number, userId?: string | null, now?: number | null): TurnCredentials;
+
+declare function uuidv5(name: string, namespace?: string): string;
+/** CallKit UUID for a call: UUIDv5(NAMESPACE_URL, "commskit:call:<callId>"). */
+declare const callkitUuid: (callId: string) => string;
+
+export { CallInfo, type TurnCredentials, busyPayload, callError, callPayload, callerView, callkitUuid, turnCredentials, uuidv5 };

package/dist/call.js

@@ -0,0 +1,51 @@
+import {
+  ACTIVE_CALL_STATUSES,
+  AllowAllCallPolicy,
+  CallFeature,
+  CallHandlers,
+  CallInfo,
+  CallLifecycle,
+  CallService,
+  allow,
+  busyPayload,
+  callError,
+  callLogText,
+  callPayload,
+  callerView,
+  callkitUuid,
+  defaultCallConfig,
+  deny,
+  endStatus,
+  turnCredentials,
+  uuidv5
+} from "./chunk-KL4WRZKZ.js";
+import {
+  callDdl
+} from "./chunk-XQFQN73U.js";
+import "./chunk-GR4PMGCS.js";
+import "./chunk-BBFVG7QU.js";
+import "./chunk-KLKRK6OG.js";
+import "./chunk-5BJ2SNM5.js";
+export {
+  ACTIVE_CALL_STATUSES,
+  AllowAllCallPolicy,
+  CallFeature,
+  CallHandlers,
+  CallInfo,
+  CallLifecycle,
+  CallService,
+  allow,
+  busyPayload,
+  callDdl,
+  callError,
+  callLogText,
+  callPayload,
+  callerView,
+  callkitUuid,
+  defaultCallConfig,
+  deny,
+  endStatus,
+  turnCredentials,
+  uuidv5
+};
+//# sourceMappingURL=call.js.map

package/dist/call.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chat.d.ts

@@ -0,0 +1,64 @@
+export { A as AllowAllChatPolicy, C as ChatActionError, a as ChatConfig, b as ChatFeature, c as ChatFeatureOptions, d as ChatPolicy, e as ChatRow, f as ChatService, D as DELETED_TYPE, M as MessageDto, g as MessageRow, R as RESERVED_TYPES, h as ReplyPreview, S as SYSTEM_TYPE, i as defaultChatConfig, m as messageDto } from './feature-DQUbnYE-.js';
+import { Generated } from 'kysely';
+import { a as Dialect } from './hub-CPrWmIvB.js';
+import './adapters-8ztjEYtz.js';
+import './connections-CGEPiZPF.js';
+import 'node:http';
+import 'node:stream';
+import 'ws';
+
+/**
+ * Chat tables: same table/column names as the Python `commskit.chat.models` (and matrimonial-backend-v2).
+ * No foreign key to a users table, so the kit does not depend on the host's user model.
+ */
+
+type Ts = string | Date;
+interface ChatsTable {
+    id: Generated<number>;
+    user1_id: string;
+    user2_id: string;
+    created_at: Ts | null;
+    updated_at: Ts | null;
+}
+interface MessagesTable {
+    id: Generated<number>;
+    chat_id: number;
+    sender_id: string;
+    content: string | null;
+    message_type: string | null;
+    file_url: string | null;
+    file_name: string | null;
+    file_size: number | string | null;
+    file_type: string | null;
+    thumbnail_url: string | null;
+    duration: number | null;
+    is_read: boolean | number | null;
+    is_delivered: boolean | number | null;
+    is_call: boolean | number | null;
+    call_id: string | null;
+    reply_to_id: number | null;
+    created_at: Ts | null;
+    updated_at: Ts | null;
+}
+interface MessageHiddenTable {
+    id: Generated<number>;
+    user_id: string;
+    message_id: number;
+    created_at: Ts | null;
+}
+interface ChatClearedTable {
+    id: Generated<number>;
+    user_id: string;
+    chat_id: number;
+    cleared_at: Ts;
+    up_to_message_id: number;
+}
+interface ChatTables {
+    chats: ChatsTable;
+    messages: MessagesTable;
+    comms_message_hidden: MessageHiddenTable;
+    comms_chat_cleared: ChatClearedTable;
+}
+declare function chatDdl(dialect: Dialect): string[];
+
+export { type ChatClearedTable, type ChatTables, type ChatsTable, type MessageHiddenTable, type MessagesTable, chatDdl };

package/dist/chat.js

@@ -0,0 +1,30 @@
+import {
+  AllowAllChatPolicy,
+  ChatActionError,
+  ChatFeature,
+  ChatService,
+  DELETED_TYPE,
+  RESERVED_TYPES,
+  SYSTEM_TYPE,
+  chatDdl,
+  defaultChatConfig,
+  messageDto
+} from "./chunk-U4Z5INIW.js";
+import "./chunk-XQ6FLRX7.js";
+import "./chunk-GR4PMGCS.js";
+import "./chunk-BBFVG7QU.js";
+import "./chunk-KLKRK6OG.js";
+import "./chunk-5BJ2SNM5.js";
+export {
+  AllowAllChatPolicy,
+  ChatActionError,
+  ChatFeature,
+  ChatService,
+  DELETED_TYPE,
+  RESERVED_TYPES,
+  SYSTEM_TYPE,
+  chatDdl,
+  defaultChatConfig,
+  messageDto
+};
+//# sourceMappingURL=chat.js.map

package/dist/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-5BJ2SNM5.js

@@ -0,0 +1,26 @@
+// src/core/logger.ts
+var consoleLogger = {
+  info: () => void 0,
+  warn: (m, ...a) => console.warn(`[commskit] ${m}`, ...a),
+  error: (m, ...a) => console.error(`[commskit] ${m}`, ...a)
+};
+var silentLogger = { info() {
+}, warn() {
+}, error() {
+} };
+var current = consoleLogger;
+function setLogger(logger2) {
+  current = logger2;
+}
+var logger = {
+  info: (m, ...a) => current.info(m, ...a),
+  warn: (m, ...a) => current.warn(m, ...a),
+  error: (m, ...a) => current.error(m, ...a)
+};
+
+export {
+  silentLogger,
+  setLogger,
+  logger
+};
+//# sourceMappingURL=chunk-5BJ2SNM5.js.map

package/dist/chunk-5BJ2SNM5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/logger.ts"],"sourcesContent":["export interface Logger {\n  info(msg: string, ...args: unknown[]): void;\n  warn(msg: string, ...args: unknown[]): void;\n  error(msg: string, ...args: unknown[]): void;\n}\n\nconst consoleLogger: Logger = {\n  info: () => undefined,\n  warn: (m, ...a) => console.warn(`[commskit] ${m}`, ...a),\n  error: (m, ...a) => console.error(`[commskit] ${m}`, ...a),\n};\n\nexport const silentLogger: Logger = { info() {}, warn() {}, error() {} };\n\nlet current: Logger = consoleLogger;\n\n/** Replace the kit-wide logger (default: warnings and errors to the console). */\nexport function setLogger(logger: Logger): void {\n  current = logger;\n}\n\nexport const logger: Logger = {\n  info: (m, ...a) => current.info(m, ...a),\n  warn: (m, ...a) => current.warn(m, ...a),\n  error: (m, ...a) => current.error(m, ...a),\n};\n"],"mappings":";AAMA,IAAM,gBAAwB;AAAA,EAC5B,MAAM,MAAM;AAAA,EACZ,MAAM,CAAC,MAAM,MAAM,QAAQ,KAAK,cAAc,CAAC,IAAI,GAAG,CAAC;AAAA,EACvD,OAAO,CAAC,MAAM,MAAM,QAAQ,MAAM,cAAc,CAAC,IAAI,GAAG,CAAC;AAC3D;AAEO,IAAM,eAAuB,EAAE,OAAO;AAAC,GAAG,OAAO;AAAC,GAAG,QAAQ;AAAC,EAAE;AAEvE,IAAI,UAAkB;AAGf,SAAS,UAAUA,SAAsB;AAC9C,YAAUA;AACZ;AAEO,IAAM,SAAiB;AAAA,EAC5B,MAAM,CAAC,MAAM,MAAM,QAAQ,KAAK,GAAG,GAAG,CAAC;AAAA,EACvC,MAAM,CAAC,MAAM,MAAM,QAAQ,KAAK,GAAG,GAAG,CAAC;AAAA,EACvC,OAAO,CAAC,MAAM,MAAM,QAAQ,MAAM,GAAG,GAAG,CAAC;AAC3C;","names":["logger"]}