@marktiderman/genesis-chat 0.1.1 → 0.2.1

package/src/core/thread.ts

@@ -0,0 +1,171 @@
+/**
+ * @feat:chat
+ * Pure thread logic, the same on every platform: merging the server's messages
+ * with ones still on their way, grouping a run of messages from one sender,
+ * day dividers, the unread line, reactions by emoji, and the typing line.
+ */
+import type { ChatActivity, ChatMessage, PendingMessage } from "./types";
+
+export type ThreadItem =
+  | { type: "message"; message: ChatMessage; pending?: undefined }
+  | { type: "pending"; pending: PendingMessage; message?: undefined };
+
+/**
+ * The server's messages (by seq), then what is still sending, oldest first. A
+ * pending message the server already has (same clientId) is dropped, so a send
+ * that landed never shows twice.
+ */
+export function mergeThread(server: ChatMessage[], pending: PendingMessage[]): ThreadItem[] {
+  const byId = new Map<string, ChatMessage>();
+  for (const m of server) byId.set(m.id, m);
+  const sorted = [...byId.values()].sort((a, b) => a.seq - b.seq);
+  const landed = new Set(sorted.map((m) => m.clientId));
+  const waiting = pending
+    .filter((p) => !landed.has(p.clientId))
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  return [
+    ...sorted.map((message) => ({ type: "message" as const, message })),
+    ...waiting.map((p) => ({ type: "pending" as const, pending: p })),
+  ];
+}
+
+/** Adds or replaces messages in a page, keeping it sorted and free of duplicates. */
+export function upsertMessages(existing: ChatMessage[], incoming: ChatMessage[]): ChatMessage[] {
+  const byId = new Map(existing.map((m) => [m.id, m]));
+  for (const m of incoming) byId.set(m.id, m);
+  return [...byId.values()].sort((a, b) => a.seq - b.seq);
+}
+
+export function itemSender(item: ThreadItem): string | null {
+  return item.type === "message" ? item.message.senderId : item.pending.senderId;
+}
+
+export function itemTime(item: ThreadItem): string {
+  return item.type === "message" ? item.message.createdAt : item.pending.createdAt;
+}
+
+/** Runs of one sender within five minutes share a header (name, avatar). */
+export function startsGroup(items: ThreadItem[], index: number, gapMs = 5 * 60_000): boolean {
+  if (index === 0) return true;
+  const prev = items[index - 1]!;
+  const cur = items[index]!;
+  if (cur.type === "message" && cur.message.kind === "system") return true;
+  if (prev.type === "message" && prev.message.kind === "system") return true;
+  if (itemSender(prev) !== itemSender(cur)) return true;
+  return Date.parse(itemTime(cur)) - Date.parse(itemTime(prev)) > gapMs || !sameDay(itemTime(prev), itemTime(cur));
+}
+
+export function sameDay(a: string, b: string): boolean {
+  const x = new Date(a);
+  const y = new Date(b);
+  return x.getFullYear() === y.getFullYear() && x.getMonth() === y.getMonth() && x.getDate() === y.getDate();
+}
+
+/** A day divider goes before this item. */
+export function startsDay(items: ThreadItem[], index: number): boolean {
+  return index === 0 || !sameDay(itemTime(items[index - 1]!), itemTime(items[index]!));
+}
+
+/** "Today", "Yesterday", "Monday", or "12 Mar 2026". */
+export function dayLabel(iso: string, now = new Date(), locale?: string): string {
+  const d = new Date(iso);
+  const startOf = (x: Date) => new Date(x.getFullYear(), x.getMonth(), x.getDate()).getTime();
+  const days = Math.round((startOf(now) - startOf(d)) / 86_400_000);
+  if (days === 0) return "Today";
+  if (days === 1) return "Yesterday";
+  if (days > 1 && days < 7) return d.toLocaleDateString(locale, { weekday: "long" });
+  return d.toLocaleDateString(locale, { day: "numeric", month: "short", year: d.getFullYear() === now.getFullYear() ? undefined : "numeric" });
+}
+
+/** The first message after what you had read, from someone else: where "New" goes. */
+export function firstUnreadId(messages: ChatMessage[], lastReadSeq: number, me: string): string | null {
+  return messages.find((m) => m.seq > lastReadSeq && m.senderId !== me && !m.deletedAt)?.id ?? null;
+}
+
+export interface ReactionSummary {
+  emoji: string;
+  count: number;
+  mine: boolean;
+  userIds: string[];
+}
+
+/** Reactions by emoji, most first, then in first-used order. */
+export function summarizeReactions(message: ChatMessage, me: string): ReactionSummary[] {
+  const order: string[] = [];
+  const by = new Map<string, string[]>();
+  for (const r of message.reactions) {
+    if (!by.has(r.emoji)) {
+      by.set(r.emoji, []);
+      order.push(r.emoji);
+    }
+    by.get(r.emoji)!.push(r.userId);
+  }
+  return order
+    .map((emoji) => ({ emoji, count: by.get(emoji)!.length, mine: by.get(emoji)!.includes(me), userIds: by.get(emoji)! }))
+    .sort((a, b) => b.count - a.count || order.indexOf(a.emoji) - order.indexOf(b.emoji));
+}
+
+/** Who is doing what now: activity older than six seconds has stopped. */
+export function currentActivity(activity: ChatActivity[], now = Date.now(), staleMs = 6000): ChatActivity[] {
+  const latest = new Map<string, ChatActivity>();
+  for (const a of activity) {
+    if (now - a.at > staleMs) continue;
+    const prev = latest.get(a.userId);
+    if (!prev || prev.at < a.at) latest.set(a.userId, a);
+  }
+  return [...latest.values()];
+}
+
+/** "Sam is typing…", "Sam and Lee are typing…", "Sam is recording a voice message…". */
+export function activityLine(activity: ChatActivity[], nameOf: (userId: string) => string): string | null {
+  if (activity.length === 0) return null;
+  const recording = activity.find((a) => a.activity !== "typing");
+  if (recording) {
+    return `${nameOf(recording.userId)} is recording ${recording.activity === "recording-video" ? "a video" : "a voice message"}…`;
+  }
+  const names = activity.map((a) => nameOf(a.userId));
+  if (names.length === 1) return `${names[0]} is typing…`;
+  if (names.length === 2) return `${names[0]} and ${names[1]} are typing…`;
+  return "Several people are typing…";
+}
+
+/** Sends activity at most once every `everyMs`. */
+export function throttle(fn: () => void, everyMs = 3000): () => void {
+  let last = 0;
+  return () => {
+    const now = Date.now();
+    if (now - last >= everyMs) {
+      last = now;
+      fn();
+    }
+  };
+}
+
+/** The ids @mentioned in markdown written as `@[Name](user:<uuid>)`. */
+export function parseMentions(body: string): string[] {
+  const ids = new Set<string>();
+  for (const m of body.matchAll(/@\[[^\]]{1,80}\]\(user:([0-9a-f-]{36})\)/gi)) ids.add(m[1]!.toLowerCase());
+  return [...ids];
+}
+
+/** A one-line preview: text, or what was attached. */
+export function previewText(body: string, attachment: string | null | undefined, deleted = false): string {
+  if (deleted) return "Message deleted";
+  const text = body.replace(/@\[([^\]]+)\]\(user:[0-9a-f-]{36}\)/gi, "@$1").replace(/[*_`#>~]/g, "").trim();
+  if (text) return text.length > 140 ? `${text.slice(0, 139)}…` : text;
+  switch (attachment) {
+    case "image":
+      return "Photo";
+    case "voice":
+      return "Voice message";
+    case "video":
+      return "Video";
+    case "file":
+      return "File";
+    case null:
+    case undefined:
+      return "";
+    default:
+      return "Attachment";
+  }
+}

package/src/core/transfer.ts

@@ -0,0 +1,71 @@
+/**
+ * @feat:chat
+ * Sending bytes with progress, the same on every platform. fetch can't report how much of a
+ * request body has gone, so where XMLHttpRequest exists (browsers, React Native) the body goes
+ * through it and `onProgress(sent, total)` follows `upload.onprogress`; elsewhere it goes
+ * through fetch and reports once, at the end.
+ */
+import { ChatError } from "./client";
+
+export type UploadProgress = (sent: number, total: number) => void;
+
+export interface SendBytesOptions {
+  method?: "PUT" | "POST";
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  onProgress?: UploadProgress;
+  /** For tests and runtimes without XMLHttpRequest. */
+  fetch?: typeof fetch;
+}
+
+const sizeOf = (body: Blob | ArrayBuffer) => (typeof Blob !== "undefined" && body instanceof Blob ? body.size : (body as ArrayBuffer).byteLength);
+
+/** A failed answer's code: a 5xx, 408 or no answer is worth retrying, 429 waits, any other 4xx is a refusal. */
+const refusal = (status: number) => (status >= 500 || status === 0 || status === 408 ? undefined : status === 429 ? "GS429" : "22023");
+
+const aborted = () => new ChatError("The upload was cancelled", "GSABORT", "upload");
+
+/** Sends `body` to `url`; resolves with the response text, throws a ChatError on a non-2xx answer. */
+export function sendBytes(url: string, body: Blob | ArrayBuffer, opts: SendBytesOptions = {}): Promise<string> {
+  const method = opts.method ?? "PUT";
+  const total = sizeOf(body);
+  if (opts.signal?.aborted) return Promise.reject(aborted());
+  if (typeof XMLHttpRequest === "undefined" || opts.fetch) {
+    const f = opts.fetch ?? fetch;
+    return f(url, { method, body, headers: opts.headers, signal: opts.signal }).then(async (res) => {
+      if (!res.ok) throw new ChatError(`The upload failed (${res.status})`, refusal(res.status), "upload");
+      opts.onProgress?.(total, total);
+      return res.text().catch(() => "");
+    });
+  }
+  return new Promise<string>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const onAbort = () => xhr.abort();
+    const done = () => opts.signal?.removeEventListener("abort", onAbort);
+    xhr.open(method, url);
+    for (const [k, v] of Object.entries(opts.headers ?? {})) xhr.setRequestHeader(k, v);
+    if (opts.onProgress && xhr.upload) {
+      xhr.upload.onprogress = (e: ProgressEvent) => opts.onProgress?.(e.loaded, e.lengthComputable ? e.total : total);
+    }
+    xhr.onload = () => {
+      done();
+      if (xhr.status >= 200 && xhr.status < 300) {
+        opts.onProgress?.(total, total);
+        resolve(typeof xhr.responseText === "string" ? xhr.responseText : "");
+      } else {
+        reject(new ChatError(`The upload failed (${xhr.status})`, refusal(xhr.status), "upload"));
+      }
+    };
+    // No answer at all: the connection, worth retrying.
+    xhr.onerror = () => {
+      done();
+      reject(new ChatError("The upload didn't reach the server", undefined, "upload"));
+    };
+    xhr.onabort = () => {
+      done();
+      reject(aborted());
+    };
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    xhr.send(body);
+  });
+}

package/src/core/types.ts

@@ -0,0 +1,328 @@
+/**
+ * @feat:chat
+ * The chat contract: what the genesis_chat schema (migrations 0001 and 0002) stores, in
+ * the app's words. Everything here is plain data, shared by web, native and
+ * the server.
+ */
+
+/** owner, admin or member of a conversation; observer when the kind's observer check lets you read it. */
+export type ChatRole = "owner" | "admin" | "member" | "observer";
+
+/** Built in: image, file, voice, video, link. Apps add their own (form, lesson, worksheet…). */
+export type AttachmentKind = "image" | "file" | "voice" | "video" | "link" | (string & {});
+
+export type AttachmentProvider = "storage" | "mux" | "cloudflare" | "external" | "none";
+
+export interface ChatAttachment {
+  id: string;
+  messageId: string;
+  position: number;
+  kind: AttachmentKind;
+  /** The app's reference for its own kinds, e.g. `{ formId, versionHash }`. */
+  ref: Record<string, unknown>;
+  provider: AttachmentProvider;
+  /** The object in the genesis-chat bucket (`<conversation>/<uploader>/<name>.<ext>`). */
+  path: string | null;
+  providerId: string | null;
+  playbackId: string | null;
+  url: string | null;
+  status: "pending" | "ready" | "failed";
+  name: string | null;
+  mime: string | null;
+  bytes: number | null;
+  width: number | null;
+  height: number | null;
+  durationMs: number | null;
+  /** Peaks 0–100, at most 128, drawn before the audio loads. */
+  waveform: number[] | null;
+  posterPath: string | null;
+  thumbhash: string | null;
+  transcript: string | null;
+  transcriptStatus: "pending" | "ready" | "failed" | "off" | null;
+}
+
+export interface ChatReaction {
+  emoji: string;
+  userId: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  conversationId: string;
+  seq: number;
+  clientId: string;
+  senderId: string | null;
+  senderRole: ChatRole | "system";
+  kind: "text" | "system";
+  /** Markdown. Empty for a deleted message. */
+  body: string;
+  mentions: string[];
+  replyToId: string | null;
+  threadRootId: string | null;
+  threadCount: number;
+  threadLastAt: string | null;
+  topic: string | null;
+  visibility: "everyone" | "observers";
+  silent: boolean;
+  meta: Record<string, unknown>;
+  createdAt: string;
+  editedAt: string | null;
+  deletedAt: string | null;
+  /**
+   * What moderation said (migration 0002): `hidden` messages reach only their sender and the
+   * conversation's observers; `flagged` ones are visible to everyone and reported to observers.
+   */
+  moderation?: "flagged" | "hidden" | null;
+  attachments: ChatAttachment[];
+  reactions: ChatReaction[];
+}
+
+export interface ChatConversation {
+  id: string;
+  kind: string;
+  title: string | null;
+  subjectType: string | null;
+  subjectId: string | null;
+  settings: { who_posts?: "members" | "admins" } & Record<string, unknown>;
+  status: "open" | "pending" | "solved" | "closed" | null;
+  assigneeId: string | null;
+  lastSeq: number;
+  lastMessageAt: string | null;
+  createdAt: string;
+  archivedAt: string | null;
+}
+
+export interface ChatMember {
+  conversationId: string;
+  userId: string;
+  role: ChatRole;
+  lastReadSeq: number;
+  joinedAt: string;
+}
+
+/** A kind's rules, as genesis_chat.kinds holds them. */
+export interface ChatKindRules {
+  kind: string;
+  label: string;
+  /** 2 for a direct conversation. */
+  maxMembers: number | null;
+  whoPosts: "members" | "admins";
+  membership: "app" | "admins";
+  threads: boolean;
+  observersPost: boolean;
+}
+
+/** The latest message, as the inbox previews it. */
+export interface ChatPreview {
+  id: string;
+  seq: number;
+  senderId: string | null;
+  kind: "text" | "system";
+  body: string;
+  deleted: boolean;
+  createdAt: string;
+  attachment: AttachmentKind | null;
+}
+
+export interface ChatInboxItem {
+  conversationId: string;
+  kind: string;
+  title: string | null;
+  subjectType: string | null;
+  subjectId: string | null;
+  status: ChatConversation["status"];
+  role: ChatRole;
+  /** The other person, in a two-person kind. */
+  otherUserId: string | null;
+  memberCount: number;
+  lastSeq: number;
+  lastReadSeq: number;
+  /** Counted to 99. */
+  unread: number;
+  mentioned: boolean;
+  muted: boolean;
+  pinned: boolean;
+  archived: boolean;
+  lastMessageAt: string | null;
+  lastMessage: ChatPreview | null;
+}
+
+/** What a sender attaches; files are uploaded first (ChatClient.upload). */
+export interface AttachmentInput {
+  kind: AttachmentKind;
+  path?: string;
+  provider?: AttachmentProvider;
+  providerId?: string;
+  url?: string;
+  ref?: Record<string, unknown>;
+  status?: "pending" | "ready";
+  name?: string;
+  mime?: string;
+  bytes?: number;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  waveform?: number[];
+  posterPath?: string;
+  thumbhash?: string;
+}
+
+export interface SendInput {
+  conversationId: string;
+  /** Made once per message on the device, so a retry never posts twice. */
+  clientId: string;
+  body?: string;
+  attachments?: AttachmentInput[];
+  replyToId?: string | null;
+  threadRootId?: string | null;
+  topic?: string | null;
+  mentions?: string[];
+  visibility?: "everyone" | "observers";
+  silent?: boolean;
+}
+
+/** A message on its way: shown at once, swapped for the server's when it lands. */
+export interface PendingMessage {
+  clientId: string;
+  input: SendInput;
+  senderId: string;
+  createdAt: string;
+  status: "sending" | "failed";
+  error?: string;
+  /** The server refused it (not allowed, bad data): only a manual retry sends it again. */
+  permanent?: boolean;
+  /** Local previews for files still uploading (object URLs or file URIs). */
+  previews?: Record<number, string>;
+  /** What each file is, in order, so a pending bubble can draw it (a voice note's duration and waveform, a file's name). */
+  files?: PendingFile[];
+}
+
+export interface PendingFile {
+  name: string;
+  contentType: string;
+  kind: AttachmentKind;
+  meta?: Partial<AttachmentInput>;
+  /** Not kept between launches (bytes with nowhere to save them): attach it again. */
+  lost?: boolean;
+  /** How much of it has uploaded, 0 to 1, once the upload reports progress. */
+  progress?: number;
+  /** Going to the hosted video provider (Mux, Cloudflare) rather than storage. */
+  hosted?: boolean;
+}
+
+/**
+ * A hosted video upload that has started: the provider's upload id, sent with the message as
+ * `{ provider, providerId, status: "pending" }` while the bytes still go up. The provider's
+ * webhook marks the attachment ready.
+ */
+export interface HostedAttachment {
+  provider: "mux" | "cloudflare";
+  providerId: string;
+  status: "pending";
+}
+
+/** A live hint from Realtime: something changed; fetch to see what. */
+export type ChatSignal =
+  | { type: "message"; conversationId: string; id: string; seq?: number; op: "insert" | "update" }
+  | { type: "reaction"; conversationId: string; messageId: string }
+  | { type: "members"; conversationId: string }
+  | { type: "conversation"; conversationId: string }
+  | { type: "inbox"; conversationId: string; seq?: number };
+
+/** Ephemeral, never stored: someone typing or recording. */
+export interface ChatActivity {
+  userId: string;
+  activity: "typing" | "recording-voice" | "recording-video";
+  at: number;
+}
+
+// ── Migration 0002: topics, scheduled send, availability, search, link previews ──
+
+/** A named sub-thread of a conversation (a cohort's lesson threads). Messages join one through `topic`. */
+export interface ChatTopic {
+  conversationId: string;
+  /** The key messages carry in `topic`. */
+  topic: string;
+  title: string;
+  position: number;
+  /** Set when closed: only owners, admins and observers post in it then. */
+  closedAt: string | null;
+  createdBy: string | null;
+  createdAt: string;
+}
+
+/** What `setTopic` changes; anything left out keeps its value (a new topic's title is its key). */
+export interface TopicInput {
+  title?: string;
+  position?: number;
+  closed?: boolean;
+}
+
+/** A message to send later, as its sender. Only its sender reads it. */
+export interface ScheduledMessage {
+  id: string;
+  conversationId: string;
+  clientId: string;
+  body: string;
+  attachments: AttachmentInput[];
+  replyToId: string | null;
+  topic: string | null;
+  mentions: string[];
+  silent: boolean;
+  sendAt: string;
+  sentMessageId: string | null;
+  cancelledAt: string | null;
+  /** Why it couldn't be sent when due (the sender left the conversation, say). */
+  error: string | null;
+  createdAt: string;
+  status: "scheduled" | "sent" | "cancelled" | "failed";
+}
+
+/** Between a minute and a year ahead. Files in `attachments` are uploaded first, as for `send`. */
+export interface ScheduleInput extends Omit<SendInput, "threadRootId" | "visibility"> {
+  sendAt: string | Date;
+}
+
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+
+/** Working hours per weekday as `[["09:00","17:00"]]`, 24-hour local times; a missing day is not working. An end at or before its start runs past midnight. */
+export type WorkingHours = Partial<Record<Weekday, [string, string][]>>;
+
+/** A person's away message and working hours. */
+export interface ChatAvailability {
+  userId: string;
+  awayMessage: string | null;
+  /** Away until then; with an away message and no date, away until they clear it. */
+  awayUntil: string | null;
+  /** An IANA zone (`America/New_York`); hours are read in it. */
+  timeZone: string | null;
+  hours: WorkingHours | null;
+}
+
+export type AvailabilityInput = Partial<Omit<ChatAvailability, "userId">>;
+
+/** One search result. `snippet` marks the matched words with « and » (the text's own « and » arrive as ‹ and ›, so marks are always real). */
+export interface ChatSearchHit {
+  messageId: string;
+  conversationId: string;
+  seq: number;
+  senderId: string | null;
+  createdAt: string;
+  snippet: string;
+  /** Found in a voice note's or video's transcript, not the text. */
+  inTranscript: boolean;
+  /** The thread the message is a reply in (open that thread to show it); null on the main timeline. */
+  threadRootId: string | null;
+}
+
+/** Open Graph data for a link (fetched by the server's runner). Plain text: never render it as HTML. */
+export interface ChatLinkPreview {
+  url: string;
+  status: "ok" | "failed" | "blocked";
+  title: string | null;
+  description: string | null;
+  /** Always https when present. */
+  imageUrl: string | null;
+  siteName: string | null;
+  fetchedAt: string;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @feat:chat
+ * @marktiderman/genesis-chat: conversations, messages, media and live updates
+ * in the app's own Supabase. The core has no React; `/react` adds hooks,
+ * `/web` and `/native` render on Genesis UI, `/server` works the outbox.
+ */
+export * from "./core/types";
+export * from "./core/client";
+export * from "./core/media";
+export * from "./core/thread";
+export * from "./core/outbox";
+export * from "./core/transfer";
+export * from "./core/availability";
+export * from "./core/extras";