@marktiderman/genesis-chat 0.0.0-stage → 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,137 @@
+import * as _tanstack_query_core from '@tanstack/query-core';
+import { C as ChatClient, a as ChatConversation, b as ChatMember, c as ChatRole, d as ChatKindRules, e as ChatMessage, f as ChatActivity, S as SendInput, g as ChatSignal, h as ChatInboxItem } from './client-BtdALFCx.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { OutboxStore, LocalFile, ThreadItem, Outbox, QueuedMessage } from './index.js';
+import '@supabase/supabase-js';
+
+declare const chatKeys: {
+    all: readonly ["genesis-chat"];
+    inbox: (opts?: object) => readonly ["genesis-chat", "inbox", object];
+    unread: () => readonly ["genesis-chat", "unread"];
+    conversation: (id: string) => readonly ["genesis-chat", "conversation", string];
+    members: (id: string) => readonly ["genesis-chat", "members", string];
+    role: (id: string) => readonly ["genesis-chat", "role", string];
+    pins: (id: string) => readonly ["genesis-chat", "pins", string];
+    files: (paths: string[]) => readonly ["genesis-chat", "files", string[]];
+};
+/** Does a messages list (`[genesis-chat, conversation, id, messages, threadRootId, topic]`) hold this message? */
+declare function belongsTo(key: readonly unknown[], m: ChatMessage): boolean;
+interface ChatContextValue {
+    client: ChatClient;
+    userId: string;
+    outbox: Outbox;
+    queue: QueuedMessage[];
+    loadPeople?: (userIds: string[]) => Promise<Record<string, ChatPerson>>;
+    /** Subscribe to inbox hints (one channel for the app, fanned out here). */
+    onInbox(listener: (s: ChatSignal) => void): () => void;
+}
+interface ChatProviderProps {
+    client: ChatClient;
+    /** The signed-in user's id (auth.users). */
+    userId: string;
+    /** Where unsent messages wait between launches (localStorage, MMKV…). Memory by default. */
+    outboxStore?: OutboxStore;
+    /** Reads a native file URI for upload. */
+    readFile?: (uri: string) => Promise<Blob | ArrayBuffer>;
+    /** Replaces the plain upload (resumable uploads on native). */
+    upload?: (conversationId: string, file: LocalFile) => Promise<string>;
+    /** Makes client ids (default: a random UUID that works without crypto.randomUUID). */
+    newId?: () => string;
+    /** Keeps a byte file (a pasted image, a recording) across launches: write it, return a URI. */
+    persistFile?: (file: LocalFile) => Promise<string>;
+    /** Names and avatars for user ids, fetched in batches (usePeople, usePerson). */
+    loadPeople?: (userIds: string[]) => Promise<Record<string, ChatPerson>>;
+    children: ReactNode;
+}
+/** How the app shows a person. */
+interface ChatPerson {
+    name: string;
+    avatarUrl?: string | null;
+}
+/** Puts chat in reach of every hook below it. Needs a TanStack QueryClientProvider above it. */
+declare function ChatProvider({ client, userId, outboxStore, readFile, upload, newId, persistFile, loadPeople, children }: ChatProviderProps): react.JSX.Element;
+declare function useChat(): ChatContextValue;
+/** Your conversations, live. `kind` narrows to one kind; `archived` shows the archived ones. */
+declare function useInbox(opts?: {
+    kind?: string;
+    archived?: boolean;
+    limit?: number;
+}): {
+    items: NoInfer<ChatInboxItem[]>;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<NoInfer<ChatInboxItem[]>, Error>>;
+};
+/** How many messages wait for you everywhere (for a badge), live. */
+declare function useUnreadTotal(): number;
+interface UseConversationOptions {
+    /** Mark messages read as they arrive while this is true (the thread is on screen). Default true. */
+    markRead?: boolean;
+    /** One thread's replies instead of the main timeline. */
+    threadRootId?: string;
+    /** One topic's messages. */
+    topic?: string;
+    pageSize?: number;
+}
+/** One conversation: its messages (with what you are still sending), members, your role, and who is typing. */
+declare function useConversation(conversationId: string | null | undefined, opts?: UseConversationOptions): {
+    conversation: NonNullable<NoInfer<ChatConversation | null>> | null;
+    members: NoInfer<ChatMember[]>;
+    role: ChatRole | null;
+    canPost: boolean;
+    /** Your role and posting rights are still loading: show the composer as waiting, not refused. */
+    accessLoading: boolean;
+    /** The kind's rules (max members, threads, who posts). */
+    kind: NonNullable<NoInfer<ChatKindRules | null>> | null;
+    /** May you pin here: owners and admins, or anyone in a two-person conversation. */
+    canPin: boolean;
+    /** Gives a message whose files were lost on a relaunch its files again. */
+    reattach: (clientId: string, files: LocalFile[]) => Promise<void>;
+    items: ThreadItem[];
+    messages: ChatMessage[];
+    isLoading: boolean;
+    error: Error | null;
+    hasEarlier: boolean;
+    loadingEarlier: boolean;
+    loadEarlier: () => Promise<void>;
+    /** Where to draw the "New" line, from what you had read when it opened. */
+    firstUnreadId: string | null;
+    activity: ChatActivity[];
+    signalTyping: () => void;
+    signalRecording: () => void;
+    markRead: () => Promise<void>;
+    send: (input: Omit<SendInput, "conversationId" | "clientId">, files?: LocalFile[]) => Promise<string>;
+    retry: (clientId: string) => Promise<void>;
+    discard: (clientId: string) => Promise<void>;
+    refetch: () => Promise<void>;
+};
+type ConversationState = ReturnType<typeof useConversation>;
+/** Edit, delete, react, pin, save and report, refreshing what they change. */
+declare function useMessageActions(): {
+    edit: (m: ChatMessage, body: string, mentions?: string[]) => Promise<void>;
+    remove: (m: ChatMessage) => Promise<void>;
+    react: (m: ChatMessage, emoji: string, on: boolean) => Promise<void>;
+    pin: (m: ChatMessage, on: boolean) => Promise<void>;
+    save: (m: ChatMessage, on: boolean, note?: string) => Promise<void>;
+    report: (m: ChatMessage, reason: "spam" | "harassment" | "safety" | "other", note?: string) => Promise<string>;
+};
+/**
+ * Names and avatars for these people, from the provider's `loadPeople`, fetched as one
+ * batch per set of ids and cached. Unknown ids are left out.
+ */
+declare function usePeople(userIds: (string | null | undefined)[]): Record<string, ChatPerson>;
+/** One person's name and avatar (see usePeople). */
+declare function usePerson(userId: string | null | undefined): ChatPerson | null;
+/** The pinned message ids of a conversation. */
+declare function usePins(conversationId: string | null | undefined): string[];
+/** Signed links for files (cached by the client until shortly before they expire). */
+declare function useFileUrls(paths: (string | null | undefined)[]): Record<string, string>;
+/** Starts (or finds again) a conversation, then refreshes the inbox. */
+declare function useStartConversation(): (kind: string, memberIds: string[], opts?: {
+    title?: string;
+    subjectType?: string;
+    subjectId?: string;
+}) => Promise<string>;
+
+export { type ChatPerson, ChatProvider, type ChatProviderProps, type ConversationState, LocalFile, QueuedMessage, ThreadItem, type UseConversationOptions, belongsTo, chatKeys, useChat, useConversation, useFileUrls, useInbox, useMessageActions, usePeople, usePerson, usePins, useStartConversation, useUnreadTotal };

package/dist/react.js

@@ -0,0 +1,5 @@
+export { ChatProvider, belongsTo, chatKeys, useChat, useConversation, useFileUrls, useInbox, useMessageActions, usePeople, usePerson, usePins, useStartConversation, useUnreadTotal } from './chunk-27UTR5FW.js';
+import './chunk-SAY24E6V.js';
+import './chunk-JQXZUEEL.js';
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"react.js"}

package/dist/server.d.ts

@@ -0,0 +1,311 @@
+import { i as ChatSupabase } from './client-BtdALFCx.js';
+import '@supabase/supabase-js';
+
+/**
+ * The server's contracts: what the runner hands an app's push sender, and the
+ * adapters it takes for transcripts and hosted video. No React, no Node APIs:
+ * fetch and Web Crypto only, so it runs in Node, edge functions and Deno.
+ */
+
+/** One person a chat push goes to. */
+interface ChatRecipient {
+    userId: string;
+    /** Their unread total across conversations (capped at 99 each), for the app badge. */
+    badge: number;
+    /** The message mentions them. */
+    mentioned: boolean;
+}
+/**
+ * One message's push, for every recipient at once. Its shape matches what
+ * `notify()` from genesis-notifications takes (type/category, recipients, data,
+ * idempotencyKey, threadKey, collapseKey), so an app can hand it on unchanged.
+ */
+interface ChatNotification {
+    category: "messages";
+    messageId: string;
+    conversationId: string;
+    recipients: ChatRecipient[];
+    /** The conversation's title, or the sender's name in a direct conversation. */
+    title: string;
+    /** The preview; in a group, prefixed with the sender's name ("Ana: see you"). */
+    body: string;
+    senderId: string | null;
+    /** `chat:<conversation id>`: a newer push replaces an older one where the platform can. */
+    collapseKey: string;
+    /** The conversation id: groups a conversation's pushes on the lock screen. */
+    threadKey: string;
+    /** `push:<message id>`: the same message is never pushed twice by a sender that dedupes. */
+    idempotencyKey: string;
+    data: {
+        url: string;
+        conversationId: string;
+        messageId: string;
+        seq: number | null;
+    };
+}
+/**
+ * Sends a message's push. Throw to have the effect retried (with backoff, up
+ * to 8 attempts); resolve once it is handed over. What it resolves with is
+ * passed back to nobody: keep what you need (tickets) yourself.
+ */
+type ChatDeliver = (notification: ChatNotification) => Promise<unknown>;
+/** A voice note or video to transcribe. */
+interface TranscribeInput {
+    /** A signed URL, valid for 10 minutes. */
+    url: string;
+    mime: string | null;
+    durationMs: number | null;
+    /** A BCP-47 code; without one the provider detects the language. */
+    language?: string | undefined;
+}
+interface TranscribeResult {
+    text: string;
+    /** The language heard, when the provider says. */
+    language?: string | undefined;
+}
+/** A speech-to-text provider. Throw on failure: the effect is retried. */
+interface Transcriber {
+    readonly name: string;
+    transcribe(input: TranscribeInput): Promise<TranscribeResult>;
+}
+/** A hosted video service (Mux): direct uploads, removal and its webhook. */
+interface VideoProvider {
+    /** The attachments' `provider` value it owns (`mux`). */
+    readonly name: "mux" | "cloudflare";
+    /** A one-time URL the client uploads the file to. */
+    createUpload(options: {
+        corsOrigin: string;
+        passthrough?: string | undefined;
+    }): Promise<{
+        uploadId: string;
+        url: string;
+    }>;
+    /** Removes a hosted asset. Already gone counts as removed. */
+    remove(assetId: string): Promise<void>;
+    /** Verifies and applies one of the service's webhooks. */
+    handleWebhook(request: Request, context: {
+        supabase: ChatSupabase;
+    }): Promise<Response>;
+}
+/** The outbox kinds the runner works. */
+type ChatEffectKind = "push" | "transcribe" | "storage.remove" | "video.remove";
+/** A claimed row of `genesis_chat.effects`. */
+interface ChatEffect {
+    id: number;
+    kind: string;
+    key: string;
+    payload: Record<string, unknown>;
+    /** This attempt's number, from 1 (claim_effects counts it). */
+    attempts: number;
+}
+interface ChatRunReport {
+    claimed: number;
+    done: number;
+    /** Failed this time; retried later with backoff until the 8th attempt. */
+    failed: number;
+}
+
+/**
+ * The outbox runner: claims due effects from `genesis_chat.effects`, does
+ * each one, and settles it. Settling with an error has `complete_effect` back
+ * it off (30 s × 2^attempts); `claim_effects` gives up after the 8th attempt.
+ *
+ *   push            push_targets(message) → deliver(notification), once per message
+ *   transcribe      signed URL (10 min) → transcriber → update_attachment
+ *   storage.remove  storage.from(bucket).remove([path]); not found is done
+ *   video.remove    video.remove(provider id), when a video provider is given
+ *
+ * Kinds it doesn't handle are never claimed, so an app's own runner can work
+ * them. Effects run concurrently per kind, up to a cap; one failure never
+ * stops the others. Errors are stored as short messages, never payloads.
+ */
+
+/** `claim_effects` stops claiming an effect after this many attempts. */
+declare const CHAT_MAX_ATTEMPTS = 8;
+interface ChatRunnerOptions {
+    /** A service-role supabase-js client (the runner reads past row level security). */
+    supabase: ChatSupabase;
+    /** Sends a message's push: `createExpoDeliver(...)`, or a function that calls genesis-notifications' `notify`. */
+    deliver: ChatDeliver;
+    /** Speech to text for voice notes and stored videos. Without one, their transcripts are set `off`. */
+    transcriber?: Transcriber | undefined;
+    /** The language to transcribe in (BCP-47). Default: detected. */
+    transcriptLanguage?: string | undefined;
+    /** Hosted video (Mux), to remove an asset when its attachment goes. */
+    video?: Pick<VideoProvider, "name" | "remove"> | undefined;
+    /** The kinds this runner works (default all four), so separate schedules can split them. */
+    kinds?: readonly ChatEffectKind[] | undefined;
+    batch?: {
+        /** Effects claimed per run (default 50, at most 500). */
+        limit?: number | undefined;
+        /** Effects of one kind in flight at once (default 4). */
+        concurrency?: number | undefined;
+    };
+    /** A person's display name, for push titles and group previews. */
+    resolveName?: ((userId: string) => Promise<string | null | undefined> | string | null | undefined) | undefined;
+    /** Kinds that are one-to-one (default `["direct"]`): their push title is the sender's name. */
+    directKinds?: readonly string[] | undefined;
+    /** Where a tapped notification opens (default `/messages/<conversationId>`). */
+    linkFor?: ((conversationId: string, messageId: string) => string) | undefined;
+    /** Safe log lines (effect ids, kinds, short errors). Default: nothing is logged. */
+    log?: ((line: string) => void) | undefined;
+}
+interface ChatRunner {
+    /** One claim, its work and its settling. Rejects only when claiming fails. */
+    run(): Promise<ChatRunReport>;
+    /** Works one effect (exported for tests and for apps that claim themselves). Throws to retry. */
+    handle(effect: ChatEffect): Promise<void>;
+}
+declare function createChatRunner(options: ChatRunnerOptions): ChatRunner;
+
+/**
+ * Speech-to-text providers behind `Transcriber`. A failed call throws with
+ * the HTTP status only (an error body can echo the request), so the runner
+ * retries it.
+ */
+
+interface DeepgramOptions {
+    apiKey: string;
+    /** Default `nova-3`. */
+    model?: string | undefined;
+    fetch?: typeof fetch | undefined;
+}
+/**
+ * Deepgram pre-recorded transcription by URL
+ * (https://developers.deepgram.com/reference/speech-to-text/listen-pre-recorded):
+ * `POST /v1/listen?model=…&smart_format=true&detect_language=true` with
+ * `{ url }` and `Authorization: Token <key>`; Deepgram fetches the file itself.
+ */
+declare function deepgramTranscriber(options: DeepgramOptions): Transcriber;
+interface OpenAiTranscriberOptions {
+    apiKey: string;
+    /** Default `gpt-4o-mini-transcribe`. */
+    model?: string | undefined;
+    fetch?: typeof fetch | undefined;
+}
+/**
+ * OpenAI `POST /v1/audio/transcriptions` (multipart: file, model, language):
+ * the file is downloaded from the signed URL first, as OpenAI takes no URL.
+ * Files over 25 MB are refused by OpenAI, so they fail here without the upload.
+ */
+declare function openAiTranscriber(options: OpenAiTranscriberOptions): Transcriber;
+
+interface MuxSigningKey {
+    /** The signing key's id (`kid`). */
+    signingKeyId: string;
+    /** The private key as Mux gives it: base64 of a PEM. A PEM works too. */
+    privateKey: string;
+}
+interface MuxVideoOptions {
+    tokenId: string;
+    tokenSecret: string;
+    /** The webhook endpoint's signing secret (Settings → Webhooks). */
+    webhookSecret: string;
+    /** `public` (default) or `signed`; signed playback needs `signing` to build URLs. */
+    playbackPolicy?: "public" | "signed" | undefined;
+    /** Mux's auto-generated captions, kept as the transcript (default English; false turns them off). */
+    captions?: {
+        languageCode?: string;
+        name?: string;
+    } | false | undefined;
+    /** For signed playback: fetching generated captions as the transcript. */
+    signing?: MuxSigningKey | undefined;
+    /** Mux `video_quality` (default `basic`). */
+    videoQuality?: "basic" | "plus" | "premium" | undefined;
+    fetch?: typeof fetch | undefined;
+    now?: (() => number) | undefined;
+}
+/** Verifies a `mux-signature` header (`t=<unix>,v1=<hex>`) over the raw body. */
+declare function verifyMuxSignature(header: string | null, body: string, secret: string, options?: {
+    now?: number;
+    toleranceSeconds?: number;
+}): Promise<boolean>;
+/**
+ * A signed playback URL (RS256 JWT with `sub` = playback id, `aud` = v, `kid`
+ * in the header), valid for `expiresInSeconds` (default 6 hours).
+ */
+declare function muxPlaybackUrl(playbackId: string, key: MuxSigningKey, options?: {
+    expiresInSeconds?: number;
+    now?: number;
+    path?: string;
+}): Promise<string>;
+declare function muxPlaybackToken(playbackId: string, key: MuxSigningKey, options?: {
+    expiresInSeconds?: number;
+    now?: number;
+    audience?: "v" | "t" | "g" | "s";
+}): Promise<string>;
+declare function muxVideo(options: MuxVideoOptions): VideoProvider & {
+    playbackUrl(playbackId: string, opts?: {
+        expiresInSeconds?: number;
+    }): Promise<string>;
+};
+
+/**
+ * A plain `deliver` for apps without genesis-notifications yet: one Expo push
+ * per device token, in requests of 100 (https://docs.expo.dev/push-notifications/sending-notifications/).
+ * It returns every ticket, so the app can forget tokens Expo calls
+ * `DeviceNotRegistered`. It throws only when nothing at all was sent, so a
+ * retry never pushes twice to the devices that already got it.
+ */
+
+declare const EXPO_SEND_URL = "https://exp.host/--/api/v2/push/send";
+declare const EXPO_BATCH = 100;
+interface ExpoPushMessage {
+    to: string;
+    title: string;
+    body: string;
+    data: Record<string, unknown>;
+    sound: "default" | null;
+    badge: number;
+    threadId: string;
+    collapseId?: string;
+    channelId: string;
+    categoryId: string;
+}
+type ExpoPushTicket = {
+    status: "ok";
+    id: string;
+} | {
+    status: "error";
+    message?: string;
+    details?: {
+        error?: string;
+    };
+};
+interface ExpoDeliveryTicket {
+    userId: string;
+    token: string;
+    ticket: ExpoPushTicket;
+}
+interface ExpoDeliverOptions {
+    /** The Expo push tokens of these people (any number per person). */
+    tokensFor: (userIds: string[]) => Promise<{
+        userId: string;
+        token: string;
+    }[]>;
+    fetch?: typeof fetch | undefined;
+    /** Required when the Expo project has enhanced push security on. */
+    accessToken?: string | undefined;
+    /** Default `default`; null for silent. */
+    sound?: "default" | null | undefined;
+    /** Android channel (default `messages`) and notification category (default `messages`, the category genesis-native's push block registers for chat). */
+    channelId?: string | undefined;
+    categoryId?: string | undefined;
+    /**
+     * Replace a conversation's earlier notification with the newest (one per conversation).
+     * Off by default: like iMessage and WhatsApp, each message shows, grouped by thread.
+     */
+    collapse?: boolean | undefined;
+}
+declare function createExpoDeliver(options: ExpoDeliverOptions): (n: ChatNotification) => Promise<ExpoDeliveryTicket[]>;
+/** The tokens Expo says are gone (`DeviceNotRegistered`): forget them. */
+declare function deadTokens(tickets: readonly ExpoDeliveryTicket[]): string[];
+
+interface ChatRunnerHandlerOptions {
+    runner: Pick<ChatRunner, "run">;
+    /** At least 32 characters. */
+    secret: string;
+}
+declare function chatRunnerHandler(options: ChatRunnerHandlerOptions): (request: Request) => Promise<Response>;
+
+export { CHAT_MAX_ATTEMPTS, type ChatDeliver, type ChatEffect, type ChatEffectKind, type ChatNotification, type ChatRecipient, type ChatRunReport, type ChatRunner, type ChatRunnerHandlerOptions, type ChatRunnerOptions, type DeepgramOptions, EXPO_BATCH, EXPO_SEND_URL, type ExpoDeliverOptions, type ExpoDeliveryTicket, type ExpoPushMessage, type ExpoPushTicket, type MuxSigningKey, type MuxVideoOptions, type OpenAiTranscriberOptions, type TranscribeInput, type TranscribeResult, type Transcriber, type VideoProvider, chatRunnerHandler, createChatRunner, createExpoDeliver, deadTokens, deepgramTranscriber, muxPlaybackToken, muxPlaybackUrl, muxVideo, openAiTranscriber, verifyMuxSignature };