@marktiderman/genesis-chat 0.1.1 → 0.2.0

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/types.ts

@@ -0,0 +1,311 @@
+/**
+ * @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;
+}
+
+/** 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;
+}
+
+/** 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,13 @@
+/**
+ * @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/availability";
+export * from "./core/extras";

package/src/native/__tests__/auto-retry.test.tsx

@@ -0,0 +1,128 @@
+// @vitest-environment happy-dom
+// @feat:chat
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ChatClient } from "../../core/client";
+import type { OutboxStore, QueuedMessage } from "../../core/outbox";
+import { ChatProvider } from "../../react/index";
+import { ChatAutoRetry, isOnline, type AppStateLike } from "../auto-retry";
+import { ChatNativeProvider } from "../context";
+import type { NetInfoLike } from "../modules";
+
+afterEach(cleanup);
+
+function fakes() {
+  let appListener: ((s: string) => void) | null = null;
+  let netListener: ((s: { isConnected: boolean | null; isInternetReachable?: boolean | null }) => void) | null = null;
+  const appState: AppStateLike = {
+    currentState: "active",
+    addEventListener: (_t, l) => {
+      appListener = l;
+      return { remove: () => (appListener = null) };
+    },
+  };
+  const netInfo: NetInfoLike = {
+    addEventListener: (l) => {
+      netListener = l;
+      // NetInfo reports the current state as soon as you subscribe.
+      l({ isConnected: true, isInternetReachable: true });
+      return () => (netListener = null);
+    },
+  };
+  return {
+    appState,
+    netInfo,
+    app: (s: string) => appListener?.(s),
+    net: (online: boolean) => netListener?.({ isConnected: online, isInternetReachable: online }),
+    unsubscribed: () => appListener === null && netListener === null,
+  };
+}
+
+/** One message that failed to send, waiting in the saved outbox; the server keeps refusing it. */
+function failing(extra: Partial<QueuedMessage> = {}) {
+  const queued: QueuedMessage = {
+    clientId: "q1",
+    input: { conversationId: "c1", clientId: "q1", body: "hello", replyToId: null, mentions: [] } as QueuedMessage["input"],
+    senderId: "u1",
+    createdAt: "2026-10-25T10:00:00Z",
+    status: "failed",
+    files: [],
+    attempts: 1,
+    ...extra,
+  };
+  let saved = [queued];
+  const store: OutboxStore = { load: async () => saved, save: async (q) => void (saved = q) };
+  const send = vi.fn(async () => {
+    throw new Error("offline");
+  });
+  const client = { send, subscribeInbox: () => ({ unsubscribe: () => undefined }) } as unknown as ChatClient;
+  return { store, client, send };
+}
+
+function mount(f: ReturnType<typeof fakes>, o: ReturnType<typeof failing>) {
+  return render(
+    <QueryClientProvider client={new QueryClient()}>
+      <ChatProvider client={o.client} userId="u1" outboxStore={o.store}>
+        <ChatNativeProvider modules={{ netInfo: f.netInfo }}>
+          <ChatAutoRetry appState={f.appState} />
+        </ChatNativeProvider>
+      </ChatProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("ChatAutoRetry", () => {
+  it("retries unsent messages when the app comes back to the front", async () => {
+    const f = fakes();
+    const o = failing();
+    mount(f, o);
+    // The provider's own retry of what the last launch left.
+    await waitFor(() => expect(o.send).toHaveBeenCalledTimes(1));
+    await act(async () => f.app("active"));
+    expect(o.send).toHaveBeenCalledTimes(1);
+    await act(async () => f.app("background"));
+    await act(async () => f.app("active"));
+    await waitFor(() => expect(o.send).toHaveBeenCalledTimes(2));
+  });
+
+  it("retries when the connection comes back, not on NetInfo's first report", async () => {
+    const f = fakes();
+    const o = failing();
+    mount(f, o);
+    await waitFor(() => expect(o.send).toHaveBeenCalledTimes(1));
+    await act(async () => f.net(true));
+    expect(o.send).toHaveBeenCalledTimes(1);
+    await act(async () => f.net(false));
+    await act(async () => f.net(true));
+    await waitFor(() => expect(o.send).toHaveBeenCalledTimes(2));
+  });
+
+  it("leaves alone a message the server refused for good", async () => {
+    const f = fakes();
+    const o = failing({ permanent: true, error: "You can't post here" });
+    mount(f, o);
+    await act(async () => f.app("background"));
+    await act(async () => f.app("active"));
+    await act(async () => f.net(false));
+    await act(async () => f.net(true));
+    expect(o.send).not.toHaveBeenCalled();
+  });
+
+  it("stops listening when unmounted", async () => {
+    const f = fakes();
+    const o = failing();
+    const view = mount(f, o);
+    view.unmount();
+    expect(f.unsubscribed()).toBe(true);
+  });
+});
+
+describe("isOnline", () => {
+  it("counts unknown as online, so only a real offline waits", () => {
+    expect(isOnline({ isConnected: true, isInternetReachable: true })).toBe(true);
+    expect(isOnline({ isConnected: null, isInternetReachable: null })).toBe(true);
+    expect(isOnline({ isConnected: false })).toBe(false);
+    expect(isOnline({ isConnected: true, isInternetReachable: false })).toBe(false);
+  });
+});