@kispi/chat 0.1.0

package/dist/server/index.cjs

@@ -0,0 +1,311 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  DefaultTokenTtlSeconds: () => DefaultTokenTtlSeconds,
+  MaxTokenTtlSeconds: () => MaxTokenTtlSeconds,
+  SignatureToleranceMs: () => SignatureToleranceMs,
+  createChatServer: () => createChatServer
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/errors.ts
+var ChatError = class extends Error {
+  code;
+  /** Present on rate limits, in milliseconds. */
+  retryAfterMs;
+  /** The consumer's own code, when a before_publish hook denied this. */
+  appCode;
+  constructor(code, message, extra) {
+    super(message);
+    this.name = "ChatError";
+    this.code = code;
+    if (extra?.retryAfterMs !== void 0) this.retryAfterMs = extra.retryAfterMs;
+    if (extra?.appCode !== void 0) this.appCode = extra.appCode;
+  }
+};
+function errorFrom(data, fallback = "the server refused the request") {
+  if (typeof data === "object" && data !== null) {
+    const d = data;
+    const inner = d["error"] ?? d;
+    const code = typeof inner["code"] === "string" ? inner["code"] : "internal";
+    const message = typeof inner["message"] === "string" ? inner["message"] : fallback;
+    const extra = {};
+    if (typeof inner["retryAfterMs"] === "number") extra.retryAfterMs = inner["retryAfterMs"];
+    if (typeof inner["appCode"] === "string") extra.appCode = inner["appCode"];
+    return new ChatError(code, message, extra);
+  }
+  return new ChatError("internal", fallback);
+}
+
+// src/server/api.ts
+var ServerRest = class {
+  constructor(url, secretKey, doFetch) {
+    this.url = url;
+    this.secretKey = secretKey;
+    this.doFetch = doFetch;
+  }
+  url;
+  secretKey;
+  doFetch;
+  async call(method, path, body) {
+    const headers = { Authorization: `Bearer ${this.secretKey}` };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await this.doFetch(`${this.url}${path}`, {
+      method,
+      headers,
+      ...body === void 0 ? {} : { body: JSON.stringify(body) }
+    });
+    if (res.status === 204) return void 0;
+    const text = await res.text();
+    const parsed = text === "" ? void 0 : JSON.parse(text);
+    if (!res.ok) throw errorFrom(parsed, `${method} ${path} failed with ${res.status}`);
+    return parsed;
+  }
+  query(params) {
+    const search = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0) search.set(k, String(v));
+    }
+    const s = search.toString();
+    return s === "" ? "" : `?${s}`;
+  }
+};
+
+// src/server/jwt.ts
+var import_node_crypto = require("crypto");
+function signHS256(header, claims, secret) {
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
+  const mac = (0, import_node_crypto.createHmac)("sha256", secret).update(signingInput).digest();
+  return `${signingInput}.${mac.toString("base64url")}`;
+}
+function macMatches(expected, given) {
+  return expected.length === given.length && (0, import_node_crypto.timingSafeEqual)(expected, given);
+}
+function b64url(s) {
+  return Buffer.from(s, "utf8").toString("base64url");
+}
+
+// src/server/token.ts
+var MaxTokenTtlSeconds = 24 * 60 * 60;
+var DefaultTokenTtlSeconds = 60 * 60;
+var MaxUserIdBytes = 128;
+function tokenClaims(input, now) {
+  const ttl = input.ttlSeconds ?? DefaultTokenTtlSeconds;
+  if (!Number.isInteger(ttl) || ttl <= 0) {
+    throw new TypeError(`ttlSeconds must be a positive whole number of seconds, got ${input.ttlSeconds}`);
+  }
+  if (ttl > MaxTokenTtlSeconds) {
+    throw new RangeError(`ttlSeconds must be at most ${MaxTokenTtlSeconds} (24 hours), got ${ttl}`);
+  }
+  if (input.userId === "") {
+    throw new TypeError("userId is required");
+  }
+  if (Buffer.byteLength(input.userId, "utf8") > MaxUserIdBytes) {
+    throw new RangeError(`userId must be at most ${MaxUserIdBytes} bytes`);
+  }
+  const iat = Math.floor(now.getTime() / 1e3);
+  const claims = {
+    sub: input.userId,
+    name: input.name,
+    iat,
+    exp: iat + ttl
+  };
+  if (input.avatar !== void 0) claims["avatar"] = input.avatar;
+  if (input.meta !== void 0) claims["meta"] = input.meta;
+  return claims;
+}
+
+// src/server/webhooks.ts
+var import_node_crypto2 = require("crypto");
+var SignatureToleranceMs = 5 * 60 * 1e3;
+var EventBeforePublish = "before_publish";
+function verifyWebhook(secret, headers, rawBody, options = {}) {
+  const signature = headerOf(headers, "x-chat-signature");
+  if (signature === void 0) {
+    throw new Error("webhook: no X-Chat-Signature header");
+  }
+  const event = headerOf(headers, "x-chat-event");
+  if (event === void 0) {
+    throw new Error("webhook: X-Chat-Event is required");
+  }
+  const rawDelivery = headerOf(headers, "x-chat-delivery");
+  if (rawDelivery === void 0 && event !== EventBeforePublish) {
+    throw new Error("webhook: X-Chat-Delivery is required");
+  }
+  const delivery = rawDelivery ?? "";
+  const parts = signature.split(",");
+  let timestamp;
+  const candidates = [];
+  for (const part of parts) {
+    const [k, v] = part.trim().split("=", 2);
+    if (k === "t") timestamp = v;
+    else if (k === "v1" && v !== void 0) candidates.push(v);
+  }
+  if (timestamp === void 0 || candidates.length === 0) {
+    throw new Error(`webhook: signature header is missing t or v1: ${signature}`);
+  }
+  const seconds = Number.parseInt(timestamp, 10);
+  if (!Number.isFinite(seconds)) {
+    throw new Error(`webhook: signature t is not a unix timestamp: ${timestamp}`);
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const age = Math.abs(now.getTime() - seconds * 1e3);
+  const tolerance = options.tolerance ?? SignatureToleranceMs;
+  if (age > tolerance) {
+    throw new Error(`webhook: signature is ${Math.round(age / 1e3)}s old, tolerance is ${tolerance / 1e3}s`);
+  }
+  const expected = (0, import_node_crypto2.createHmac)("sha256", secret).update(`${timestamp}
+${event}
+${delivery}
+${rawBody}`).digest();
+  const matched = candidates.some((candidate) => {
+    const given = Buffer.from(candidate, "hex");
+    return given.length > 0 && macMatches(expected, given);
+  });
+  if (!matched) {
+    throw new Error("webhook: signature does not match");
+  }
+  return { event, delivery, data: rawBody === "" ? void 0 : JSON.parse(rawBody) };
+}
+function headerOf(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const record = headers;
+  const value = record[name] ?? record[name.toUpperCase()] ?? record[titleCase(name)];
+  return Array.isArray(value) ? value[0] : value;
+}
+function titleCase(name) {
+  return name.split("-").map((p) => p === "" ? p : p[0].toUpperCase() + p.slice(1)).join("-");
+}
+
+// src/server/index.ts
+function createChatServer(options) {
+  if (!options.secretKey.startsWith("sk_")) {
+    throw new TypeError("secretKey must be an sk_ key; a pk_ cannot sign tokens or reach server routes");
+  }
+  if (options.keyId === "") {
+    throw new TypeError("keyId is required: it becomes the token's kid, which tells the server which key signed it");
+  }
+  const rest = new ServerRest(options.url, options.secretKey, options.fetch ?? globalThis.fetch.bind(globalThis));
+  return {
+    token(input) {
+      return signHS256(
+        { alg: "HS256", typ: "JWT", kid: options.keyId },
+        tokenClaims(input, /* @__PURE__ */ new Date()),
+        options.secretKey
+      );
+    },
+    rooms: {
+      ensure: (input) => rest.call("PUT", "/v1/rooms", input),
+      ensureDM: (members) => rest.call("PUT", "/v1/rooms", { type: "dm", members }),
+      get: (roomId) => rest.call("GET", `/v1/rooms/${roomId}`),
+      update: (roomId, patch) => rest.call("PATCH", `/v1/rooms/${roomId}`, patch),
+      delete: async (roomId) => {
+        await rest.call("DELETE", `/v1/rooms/${roomId}`);
+      },
+      custom: async (roomId, payload) => {
+        await rest.call("POST", `/v1/rooms/${roomId}/custom`, { payload });
+      },
+      members: {
+        list: (roomId, o) => rest.call("GET", `/v1/rooms/${roomId}/members${rest.query({ cursor: o?.cursor, limit: o?.limit })}`),
+        add: async (roomId, userId, role) => {
+          await rest.call("PUT", `/v1/rooms/${roomId}/members/${userId}`, role === void 0 ? {} : { role });
+        },
+        remove: async (roomId, userId) => {
+          await rest.call("DELETE", `/v1/rooms/${roomId}/members/${userId}`);
+        }
+      }
+    },
+    messages: {
+      send: (roomId, input) => {
+        const body = {
+          clientMessageId: input.clientMessageId ?? `srv-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+          sender: input.sender,
+          body: {
+            ...input.text === void 0 ? {} : { text: input.text },
+            ...input.attachments === void 0 ? {} : { attachments: input.attachments }
+          }
+        };
+        if (input.kind !== void 0) body["kind"] = input.kind;
+        if (input.appMeta !== void 0) body["appMeta"] = input.appMeta;
+        if (input.replyTo !== void 0) body["replyTo"] = input.replyTo;
+        if (input.threadId !== void 0) body["threadId"] = input.threadId;
+        return rest.call("POST", `/v1/rooms/${roomId}/messages`, body);
+      },
+      list: (roomId, o) => rest.call(
+        "GET",
+        `/v1/rooms/${roomId}/messages${rest.query({ before: o?.before, after: o?.after, limit: o?.limit })}`
+      ),
+      delete: async (roomId, messageId) => {
+        await rest.call("DELETE", `/v1/rooms/${roomId}/messages/${messageId}`);
+      }
+    },
+    users: {
+      list: (o) => rest.call("GET", `/v1/users${rest.query({ cursor: o?.cursor, limit: o?.limit })}`),
+      update: (userId, patch) => rest.call("PUT", `/v1/users/${userId}`, patch),
+      // `purge_messages`, not `purgeMessages`: the option is named in
+      // this SDK's style and the query parameter in the wire's, and
+      // those are two different names for the same thing rather than
+      // one name used twice. This sent the SDK spelling and the server
+      // read no parameter at all -- so a purge request was answered
+      // with 200 and `purgedMessages: 0`, the identity anonymized and
+      // the messages left standing. Nothing failed; the caller was told
+      // it had worked.
+      delete: (userId, o) => rest.call("DELETE", `/v1/users/${userId}${rest.query({ purge_messages: o?.purgeMessages ? "true" : void 0 })}`),
+      revokeTokens: async (userId) => {
+        await rest.call("POST", `/v1/users/${userId}/revoke-tokens`);
+      },
+      ban: async (userId, input) => {
+        await rest.call("PUT", `/v1/users/${userId}/ban`, input);
+      },
+      unban: async (userId) => {
+        await rest.call("DELETE", `/v1/users/${userId}/ban`);
+      },
+      disconnect: (userId, o) => rest.call("POST", `/v1/users/${userId}/disconnect`, o ?? {})
+    },
+    events: {
+      // The cursor is a position, and a row committed late can appear
+      // behind a page already walked. The server documents the recovery
+      // -- read the last page again, or step `after` back a little --
+      // and the SDK does **not** do it silently: a consumer dedups on
+      // `delivery` anyway, and a hidden re-read would double the work
+      // for consumers who already got that right.
+      list: (o) => rest.call("GET", `/v1/events${rest.query({ after: o?.after, limit: o?.limit })}`)
+    },
+    webhooks: {
+      verify: (headers, rawBody, verifyOptions) => {
+        if (options.webhookSecret === void 0) {
+          throw new TypeError("webhookSecret was not given to createChatServer, so a delivery cannot be verified");
+        }
+        return verifyWebhook(options.webhookSecret, headers, rawBody, verifyOptions ?? {});
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DefaultTokenTtlSeconds,
+  MaxTokenTtlSeconds,
+  SignatureToleranceMs,
+  createChatServer
+});

package/dist/server/index.d.cts

@@ -0,0 +1,208 @@
+/**
+ * The claims of a token-mode user token (spec: "유저 토큰 (token 모드)").
+ *
+ * `userId` is the consumer's own id for the person and becomes `sub`. The
+ * chat server upserts `(app_id, sub)` on connect and takes `name` and
+ * `avatar` from here, which is why a rename is a re-issued token rather
+ * than a call.
+ */
+type TokenInput = {
+    userId: string;
+    name: string;
+    avatar?: string;
+    /** Merged into `users.meta.provider`. The consumer's trusted channel. */
+    meta?: Record<string, unknown>;
+    /** Default 3600. The server refuses anything over a day. */
+    ttlSeconds?: number;
+};
+/** The spec's ceiling: `exp - iat ≤ 24h`. */
+declare const MaxTokenTtlSeconds: number;
+declare const DefaultTokenTtlSeconds: number;
+
+/** How old a signature may be. The server signs with the same window. */
+declare const SignatureToleranceMs: number;
+type VerifiedDelivery = {
+    /** `X-Chat-Event`, e.g. `message.created`. */
+    event: string;
+    /**
+     * `X-Chat-Delivery`. **The dedup key** for a queued delivery --
+     * delivery is at-least-once. Empty for `before_publish`, which is a
+     * synchronous question with nothing to dedup on.
+     */
+    delivery: string;
+    /** The parsed body. */
+    data: unknown;
+};
+type VerifyOptions = {
+    /** Now, for tests. Defaults to the real clock. */
+    now?: Date;
+    tolerance?: number;
+};
+
+type ChatServerOptions = {
+    /** The chat server's base URL, e.g. `https://chat.example.com`. */
+    url: string;
+    /** An `sk_` key. Never ship this to a browser. */
+    secretKey: string;
+    /**
+     * The id of the row that `secretKey` came from, printed by
+     * `chat-server app create --json`.
+     *
+     * It goes in the token's `kid`, which tells the server which key to
+     * verify with. Without it the server tries every unrevoked `sk_` the
+     * app has -- which works, and is the compatibility path for tokens
+     * minted before this SDK existed, not a mode to choose.
+     */
+    keyId: string;
+    /** Needed only by `webhooks.verify`. */
+    webhookSecret?: string;
+    /** Defaults to the global. */
+    fetch?: typeof globalThis.fetch;
+};
+type EnsureRoomInput = {
+    key?: string;
+    type: 'public' | 'private' | 'channel' | 'dm';
+    name?: string;
+    meta?: Record<string, unknown>;
+    members?: string[];
+};
+type ServerSendInput = {
+    clientMessageId?: string;
+    kind?: 'text' | 'system';
+    text?: string;
+    attachments?: unknown[];
+    /** The app's own annotation. A user token cannot set this. */
+    appMeta?: Record<string, unknown>;
+    /** Required: an sk_ has no user identity to attribute the message to. */
+    sender: {
+        id: string;
+        name: string;
+        avatar?: string;
+    };
+    replyTo?: string;
+    threadId?: string;
+};
+type ChatServer = {
+    /** Signs a user token locally. No network call. */
+    token: (input: TokenInput) => string;
+    rooms: {
+        /** get-or-create. The same call whether the room exists or not. */
+        ensure: (input: EnsureRoomInput) => Promise<{
+            id: string;
+            key?: string;
+            type: string;
+        }>;
+        /** get-or-create for the two-person room these two share. */
+        ensureDM: (members: [string, string]) => Promise<{
+            id: string;
+            type: string;
+        }>;
+        get: (roomId: string) => Promise<unknown>;
+        update: (roomId: string, patch: {
+            key?: string;
+            name?: string;
+            meta?: Record<string, unknown>;
+        }) => Promise<unknown>;
+        delete: (roomId: string) => Promise<void>;
+        /**
+         * Broadcasts an app-authored `custom` event into the room.
+         *
+         * The payload reaches `room.on('custom', ...)` unchanged and the
+         * server neither stores nor interprets it. This is the control
+         * channel -- "refresh now", "an alert fired" -- not a message: it
+         * leaves no history, no unread count and no webhook, so a client
+         * that was offline when it went out never learns of it. A signal
+         * that must survive a reconnect is a `kind: 'system'` message.
+         *
+         * A JSON object, bounded by the server (a control signal has to fit
+         * in one frame). `sk_` only, like every other route on this object.
+         */
+        custom: (roomId: string, payload: Record<string, unknown>) => Promise<void>;
+        members: {
+            list: (roomId: string, options?: {
+                cursor?: string;
+                limit?: number;
+            }) => Promise<unknown>;
+            add: (roomId: string, userId: string, role?: string) => Promise<void>;
+            remove: (roomId: string, userId: string) => Promise<void>;
+        };
+    };
+    messages: {
+        send: (roomId: string, input: ServerSendInput) => Promise<{
+            messageId: string;
+            seq: number;
+        }>;
+        list: (roomId: string, options?: {
+            before?: number;
+            after?: number;
+            limit?: number;
+        }) => Promise<unknown>;
+        delete: (roomId: string, messageId: string) => Promise<void>;
+    };
+    users: {
+        /**
+         * The console's user list, newest first.
+         *
+         * `cursor` is opaque -- do not parse it -- and an empty one means
+         * this was the last page. `limit` defaults to 50 and caps at 100.
+         *
+         * **Withdrawn identities are on this list**, carrying `deletedAt`.
+         * That is the opposite of the room-scoped listings, which hide a
+         * withdrawn user's id: those are readable by other *users*, and
+         * this one needs an `sk_`, so the only caller is the backend that
+         * issued the id. A consumer syncing live users filters on
+         * `deletedAt`.
+         */
+        list: (options?: {
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            users: unknown[];
+            cursor: string;
+        }>;
+        update: (userId: string, patch: {
+            name?: string;
+            avatar?: string;
+            meta?: Record<string, unknown>;
+        }) => Promise<unknown>;
+        /** Withdrawal: anonymises rather than deleting rows. */
+        delete: (userId: string, options?: {
+            purgeMessages?: boolean;
+        }) => Promise<unknown>;
+        revokeTokens: (userId: string) => Promise<void>;
+        /**
+         * Bans until a moment, given as **unix milliseconds**.
+         *
+         * `until` is required and the server refuses the call without it: an
+         * indefinite ban is a far-future date the caller chose, which shows
+         * up in an audit as a decision, where a missing field would show up
+         * as an accident.
+         */
+        ban: (userId: string, input: {
+            until: number;
+            reason?: string;
+        }) => Promise<void>;
+        unban: (userId: string) => Promise<void>;
+        disconnect: (userId: string, options?: {
+            connectionId?: string;
+            reason?: string;
+        }) => Promise<unknown>;
+    };
+    events: {
+        /** The outbox, for catching up on webhooks that were missed. */
+        list: (options?: {
+            after?: string;
+            limit?: number;
+        }) => Promise<{
+            events: unknown[];
+            cursor: string;
+        }>;
+    };
+    webhooks: {
+        /** Verifies a delivery's signature. Needs the raw body, not a parsed one. */
+        verify: (headers: Headers | Record<string, string | string[] | undefined>, rawBody: string, options?: VerifyOptions) => VerifiedDelivery;
+    };
+};
+declare function createChatServer(options: ChatServerOptions): ChatServer;
+
+export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, MaxTokenTtlSeconds, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };