@marktiderman/genesis-chat 0.1.1 → 0.2.1

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { i as ChatSupabase } from './client-BtdALFCx.js';
+import { w as ChatSupabase } from './client-DUIG1hum.js';
 import '@supabase/supabase-js';
 
 /**
@@ -30,18 +30,35 @@ interface ChatNotification {
     /** 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;
+    /**
+     * `chat:<conversation id>`, only when the runner's `collapse` is on: a newer push
+     * replaces an older one. Off by default, because on iOS it becomes the
+     * notification's identifier, so replies from two notifications of one
+     * conversation would collide.
+     */
+    collapseKey?: string | undefined;
     /** 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;
+    /**
+     * The push's data, built by `chatPushPayload` (genesis-chat/push): flat strings the iOS
+     * Notification Service Extension reads (sender name and https photo, group name) plus `seq`.
+     */
     data: {
         url: string;
         conversationId: string;
         messageId: string;
         seq: number | null;
+        senderId?: string;
+        senderName?: string;
+        senderAvatar?: string;
+        groupName?: string;
     };
+    /** Let the iOS extension rewrite it into a Communication Notification (sender photo). */
+    mutableContent?: boolean;
+    /** The notification category the native push block registers for chat (`messages`). */
+    categoryId?: string;
 }
 /**
  * Sends a message's push. Throw to have the effect retried (with backoff, up
@@ -87,8 +104,40 @@ interface VideoProvider {
         supabase: ChatSupabase;
     }): Promise<Response>;
 }
+/** What moderation decided: `hidden` takes a message from members' view, `flagged` files a report only. */
+type ModerationResult = "clean" | "flagged" | "hidden";
+/** A message to moderate: its text and signed URLs (10 minutes) for its photos. */
+interface ModerateInput {
+    text: string;
+    imageUrls: string[];
+}
+interface ModerationVerdict {
+    result: ModerationResult;
+    /** A short, safe reason for the report observers see ("harassment 0.93"). Never the message itself. */
+    reason?: string | undefined;
+}
+/** A moderation provider. Throw on failure: the effect is retried. */
+interface Moderator {
+    readonly name: string;
+    moderate(input: ModerateInput): Promise<ModerationVerdict>;
+}
+/** One link's Open Graph data, as `save_link_preview` stores it. */
+interface LinkPreview {
+    url: string;
+    /** `blocked`: the URL is not one the server may fetch (private address, not https). */
+    status: "ok" | "failed" | "blocked";
+    title?: string | null | undefined;
+    description?: string | null | undefined;
+    /** https only. */
+    imageUrl?: string | null | undefined;
+    siteName?: string | null | undefined;
+}
+/** Fetches a link's preview. Resolve `failed` or `blocked` rather than throw; a throw is retried. */
+interface LinkUnfurler {
+    unfurl(url: string): Promise<LinkPreview>;
+}
 /** The outbox kinds the runner works. */
-type ChatEffectKind = "push" | "transcribe" | "storage.remove" | "video.remove";
+type ChatEffectKind = "push" | "transcribe" | "storage.remove" | "video.remove" | "moderate" | "unfurl";
 /** A claimed row of `genesis_chat.effects`. */
 interface ChatEffect {
     id: number;
@@ -103,23 +152,23 @@ interface ChatRunReport {
     done: number;
     /** Failed this time; retried later with backoff until the 8th attempt. */
     failed: number;
+    /**
+     * Scheduled messages that were due. `skipped`: not posted this run (refused, with the reason
+     * on the row; a passing error, tried again next run; or taken by another runner).
+     * `failed`: the call itself failed. Absent with `scheduled: false`.
+     */
+    scheduled?: {
+        due: number;
+        posted: number;
+        skipped: number;
+        failed: number;
+    } | undefined;
+    /** Messages removed past their kind's retention. Present only with `retention: true`. */
+    purged?: number | undefined;
+    /** Steps besides the outbox that failed this run (scheduled posting, retention), as short messages. */
+    errors?: string[] | undefined;
 }
 
-/**
- * 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 {
@@ -133,7 +182,17 @@ interface ChatRunnerOptions {
     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. */
+    /** Moderation for kinds that ask for it (`set_kind_options(kind, p_moderate => true)`): `openAiModerator(...)`. */
+    moderator?: Moderator | undefined;
+    /** Link previews: `createLinkUnfurler()`. Without one, `unfurl` effects are left unclaimed. */
+    unfurler?: LinkUnfurler | undefined;
+    /** Post due scheduled messages on each run (default true). */
+    scheduled?: boolean | undefined;
+    /** Remove messages past their kind's retention on each run (default false: run it once a day). */
+    retention?: boolean | undefined;
+    /** Messages removed per purge_expired call (default 1000); up to 10 calls a run. */
+    retentionBatch?: number | undefined;
+    /** The kinds this runner works (default the four base kinds, plus `moderate` and `unfurl` when their adapters are given). */
     kinds?: readonly ChatEffectKind[] | undefined;
     batch?: {
         /** Effects claimed per run (default 50, at most 500). */
@@ -143,8 +202,18 @@ interface ChatRunnerOptions {
     };
     /** A person's display name, for push titles and group previews. */
     resolveName?: ((userId: string) => Promise<string | null | undefined> | string | null | undefined) | undefined;
+    /** A person's photo (an https URL), shown on iOS as the sender of a chat push. */
+    resolveAvatar?: ((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;
+    /**
+     * Set `collapseKey` (`chat:<conversation id>`) so a conversation's newer push
+     * replaces the older one. Default false: on iOS the collapse id becomes the
+     * notification's identifier, and replies from one conversation's notifications collide.
+     */
+    collapse?: boolean | undefined;
+    /** Kinds left out of the push badge, matching the app's own badge (`useUnreadTotal({ excludeKinds })`). */
+    badgeExcludeKinds?: 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. */
@@ -240,6 +309,47 @@ declare function muxVideo(options: MuxVideoOptions): VideoProvider & {
     }): Promise<string>;
 };
 
+/**
+ * A pretend hosted video service for local development, behind `VideoProvider`, so the hosted
+ * path (pending attachment, upload, ready) runs without a Mux account.
+ *
+ *   createUpload  a local upload URL (`uploadUrl?id=<upload id>`) and its id, `fake_<uuid>`
+ *   handler       the fetch handler to mount at `uploadUrl`: takes the PUT body, stores it in
+ *                 the genesis-chat bucket, then marks the attachment ready
+ *   markReady     what Mux's `video.asset.ready` webhook does: `update_attachment` with status
+ *                 ready, a playback id (`fake-<upload id>`) and a fake HLS URL
+ *   playbackUrl   a signed link to the stored file (the fake HLS URL when nothing was stored)
+ *
+ * It refuses to be made when NODE_ENV is `production`, unless `force` is set.
+ */
+
+interface FakeVideoProviderOptions {
+    /** A service-role client: it writes the bucket and calls `update_attachment`. */
+    supabase: ChatSupabase;
+    /** Where `handler` is mounted, e.g. `http://localhost:3000/api/chat/fake-video`. */
+    uploadUrl: string;
+    /** The `provider` value it stands in for. Default `mux`. */
+    name?: "mux" | "cloudflare";
+    /** Run even when NODE_ENV is `production`. */
+    force?: boolean;
+    /** NODE_ENV, read from `process.env` by default. */
+    env?: string | undefined;
+    /** How long `handler` waits for the message carrying the upload to arrive before answering 202 (default 10 s). */
+    readyWaitMs?: number;
+    newId?: () => string;
+    sleep?: (ms: number) => Promise<void>;
+}
+interface FakeReadyOptions {
+    durationMs?: number;
+    /** A poster image already in the genesis-chat bucket. */
+    posterPath?: string;
+}
+declare function fakeVideoProvider(options: FakeVideoProviderOptions): VideoProvider & {
+    markReady(providerId: string, ready?: FakeReadyOptions): Promise<void>;
+    handler(request: Request): Promise<Response>;
+    playbackUrl(playbackId: string): 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/).
@@ -261,6 +371,7 @@ interface ExpoPushMessage {
     collapseId?: string;
     channelId: string;
     categoryId: string;
+    mutableContent?: boolean;
 }
 type ExpoPushTicket = {
     status: "ok";
@@ -308,4 +419,423 @@ interface ChatRunnerHandlerOptions {
 }
 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 };
+/**
+ * OpenAI's moderation endpoint behind `Moderator`
+ * (https://developers.openai.com/api/docs/guides/moderation):
+ *
+ *   POST https://api.openai.com/v1/moderations
+ *   { model: "omni-moderation-latest", input: [{ type: "text", text }, { type: "image_url", image_url: { url } }] }
+ *
+ * Each result has `flagged`, `categories`, `category_scores` (0 to 1) and
+ * `category_applied_input_types`. A message's text goes with its first photo;
+ * further photos go one request each (the guide doesn't say how many images one
+ * request takes), and the highest score per category wins.
+ *
+ * Mapping: any category at or over its `hide` threshold → `hidden`; else any at
+ * or over `flag` (or OpenAI's own `flagged`, unless `trustFlagged: false`) →
+ * `flagged`; else `clean`. The reason names the categories and scores, never
+ * the text.
+ */
+
+declare const OPENAI_MODERATIONS_URL = "https://api.openai.com/v1/moderations";
+/** The categories omni-moderation scores (text and images, or text only where noted in OpenAI's guide). */
+declare const OPENAI_MODERATION_CATEGORIES: readonly ["sexual", "sexual/minors", "harassment", "harassment/threatening", "hate", "hate/threatening", "illicit", "illicit/violent", "self-harm", "self-harm/intent", "self-harm/instructions", "violence", "violence/graphic"];
+interface ModerationThresholds {
+    /** At or over: a report for observers (default 0.5). */
+    flag?: number | undefined;
+    /** At or over: the message is hidden from members and reported (default 0.9). */
+    hide?: number | undefined;
+}
+interface OpenAiModeratorOptions {
+    apiKey: string;
+    /** Default `omni-moderation-latest`. */
+    model?: string | undefined;
+    /** Defaults for every category. */
+    thresholds?: ModerationThresholds | undefined;
+    /**
+     * Per category, over the defaults. Default: `sexual/minors` hides at 0.5 and
+     * flags at 0.2; `self-harm/intent` and `self-harm/instructions` flag at 0.3
+     * (a coach should see them) and hide at 0.95.
+     */
+    categories?: Record<string, ModerationThresholds> | undefined;
+    /** Count OpenAI's own `flagged` as at least `flagged` (default true). */
+    trustFlagged?: boolean | undefined;
+    /** Text sent per request (default 10 000 characters, a message's maximum). */
+    maxTextChars?: number | undefined;
+    fetch?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+}
+/** Maps category scores to a verdict with the given thresholds (exported for tests and other providers). */
+declare function moderationVerdict(scores: Record<string, number>, options?: {
+    thresholds?: ModerationThresholds | undefined;
+    categories?: Record<string, ModerationThresholds> | undefined;
+    flagged?: boolean;
+}): ModerationVerdict;
+declare function openAiModerator(options: OpenAiModeratorOptions): Moderator;
+
+/**
+ * Link previews without letting a message aim the server at its own network.
+ *
+ *   - https only, port 443, no user:password@; at most 3 redirects, each hop
+ *     checked again (redirects are followed by hand, never by fetch);
+ *   - the host must not be, or resolve to, a private, loopback, link-local,
+ *     carrier-grade NAT, multicast, documentation or metadata address
+ *     (169.254.169.254, fd00:ec2::254), nor an IPv6 form that carries one
+ *     (::ffff:0:0/96 mapped and translated, NAT64, 6to4 2002::/16, Teredo),
+ *     nor `localhost`, `*.localhost`, `*.local`, `*.internal` or a single-label
+ *     name;
+ *   - no URL whose query carries what looks like a credential (`token=`,
+ *     `sig=`, `code=`, `X-Amz-Signature=` ...): fetching it could use up a
+ *     one-time link;
+ *   - HTML only (`text/html`, `application/xhtml+xml`), read up to `maxBytes`
+ *     and no further; nothing is executed;
+ *   - og:title, og:description, og:image (https only, resolved against the
+ *     page, and its host held to the same address rules, else dropped),
+ *     og:site_name, with twitter:* and <title> / meta description as
+ *     fallbacks; entities decoded, whitespace collapsed, lengths capped to the
+ *     columns of `link_previews`.
+ *
+ * DNS: the host is resolved first (Node's `node:dns`, Deno's `Deno.resolveDns`,
+ * or a `resolve` you pass), within the timeout, and refused if any address is
+ * private. Where nothing can resolve (some edge runtimes), every host that is
+ * not an IP literal is refused (`blocked`, logged once) unless you pass
+ * `allowUnresolved: true`, accepting that a public name pointing at a private
+ * address gets through.
+ *
+ * Rebinding: fetch resolves the name again, so a host that changes its answer
+ * between the check and the connection is not caught by the check alone. On
+ * Node, close that gap by connecting through the checked lookup: pass
+ * `dispatcher: new Agent({ connect: { lookup: guardedLookup } })` (`Agent` from
+ * `undici`), which refuses a private address at connect time. Elsewhere, run
+ * the runner where outbound traffic to private ranges is firewalled.
+ */
+
+interface LinkUnfurlerOptions {
+    fetch?: typeof fetch | undefined;
+    /** For the whole fetch, redirects included (default 5000). */
+    timeoutMs?: number | undefined;
+    /** Bytes of HTML read at most (default 512 KiB). */
+    maxBytes?: number | undefined;
+    /** At most this many redirects (default 3). */
+    maxRedirects?: number | undefined;
+    /**
+     * The host's addresses. Default: `node:dns` or `Deno.resolveDns` where
+     * present; `null` means "can't resolve here" and only literal and local
+     * hosts are refused. Throwing means the name doesn't resolve: `failed`.
+     */
+    resolve?: ((hostname: string) => Promise<string[] | null>) | undefined;
+    /**
+     * Fetch a name even when nothing here can resolve it (default false: such a
+     * name is `blocked`). Only for a runner behind an egress firewall.
+     */
+    allowUnresolved?: boolean | undefined;
+    /**
+     * Passed to fetch as `dispatcher` (Node, undici): `new Agent({ connect: {
+     * lookup: guardedLookup } })` pins each connection to an address checked at
+     * connect time, which closes DNS rebinding.
+     */
+    dispatcher?: unknown;
+    /** Where a misconfiguration is reported (no resolver). Default `console.warn`. */
+    log?: ((line: string) => void) | undefined;
+    userAgent?: string | undefined;
+}
+/** True when `ip` (v4 or v6, brackets allowed) is not a public unicast address. Unparseable counts as private. */
+declare function isPrivateAddress(ip: string): boolean;
+/** True when the URL's query or fragment carries what looks like a credential (exported for tests). */
+declare function carriesCredential(url: string): boolean;
+type LookupAddress = {
+    address: string;
+    family: number;
+};
+type LookupCallback = (error: Error | null, address?: string | LookupAddress[], family?: number) => void;
+/**
+ * A `dns.lookup` for Node's socket `connect.lookup` (undici `Agent({ connect: { lookup } })`):
+ * resolves the name and refuses it when any address is private, so the connection
+ * goes only to an address that was checked. That closes DNS rebinding.
+ */
+declare function guardedLookup(hostname: string, options: {
+    all?: boolean;
+    family?: number;
+} | number | undefined, callback: LookupCallback): void;
+/** Decodes HTML entities (named, decimal, hex). */
+declare function decodeEntities(text: string): string;
+/**
+ * Open Graph data from a page's HTML (exported for tests). `base` resolves a relative og:image.
+ * The page is hostile input and this runs synchronously, so every scan is linear in its length.
+ */
+declare function parseOpenGraph(html: string, base: string): Omit<LinkPreview, "url" | "status">;
+declare function createLinkUnfurler(options?: LinkUnfurlerOptions): LinkUnfurler;
+
+/**
+ * Chat pushes through genesis-notifications: `notificationsDeliver` hands a
+ * message's `ChatNotification` to `notify()` (one call, every recipient with
+ * their own badge), and `CHAT_NOTIFICATION_TYPES` / `CHAT_NOTIFICATION_CATEGORIES`
+ * go into the app's `defineNotifications` registry. Typed structurally, so
+ * genesis-chat doesn't depend on genesis-notifications; its tests check the
+ * shapes against the real package.
+ *
+ * ```ts
+ * import { notify } from "@marktiderman/genesis-notifications/server";
+ * const deliver = notificationsDeliver({ notify, client: supabase, registry: notifications });
+ * ```
+ *
+ * The preferences, quiet hours, channels and devices are genesis-notifications'.
+ */
+
+/** The notification type id chat pushes go out as. */
+declare const CHAT_NOTIFICATION_TYPE_ID = "chat.message";
+/** What `notify()` receives for a chat message (a `NotifyInput<"chat.message">`). */
+interface ChatNotifyInput {
+    type: string;
+    recipients: {
+        userId: string;
+        badge?: number;
+    }[];
+    data: {
+        url: string;
+        conversationId: string;
+        messageId: string;
+        seq: number | null;
+        title: string;
+        body: string;
+        senderId: string | null;
+        senderName?: string;
+        senderAvatar?: string;
+        groupName?: string;
+    };
+    idempotencyKey: string;
+    threadKey: string;
+    collapseKey?: string;
+    tenantId?: string;
+}
+interface NotificationsDeliverOptions<Client, Registry> {
+    /** genesis-notifications' `notify` from `@marktiderman/genesis-notifications/server`. */
+    notify: (client: Client, input: ChatNotifyInput, options?: {
+        registry?: Registry;
+    }) => Promise<unknown>;
+    /** The service-role client `notify` calls `genesis_notify` through. */
+    client: Client;
+    /** Passed to `notify` as `{ registry }`, so an unknown type fails before the database. */
+    registry?: Registry | undefined;
+    /** Default `chat.message`. `collapseKey` is passed on only when the runner set it (its `collapse` option). */
+    type?: string | undefined;
+    /** The practice or workspace the conversation belongs to, when the app has one. */
+    tenantFor?: ((notification: ChatNotification) => string | null | undefined | Promise<string | null | undefined>) | undefined;
+}
+/** Maps a chat push onto genesis-notifications' `notify()` (exported for tests and apps that call notify themselves). */
+declare function chatNotifyInput(notification: ChatNotification, options?: {
+    type?: string | undefined;
+}): ChatNotifyInput;
+declare function notificationsDeliver<Client, Registry>(options: NotificationsDeliverOptions<Client, Registry>): ChatDeliver;
+/** The `messages` category, for `defineNotifications({ categories })`. */
+declare const CHAT_NOTIFICATION_CATEGORIES: {
+    readonly messages: {
+        readonly label: "Messages";
+        readonly description: "New messages in your conversations.";
+        readonly android: {
+            readonly importance: "high";
+        };
+    };
+};
+/**
+ * The `chat.message` type, for `defineNotifications({ types })`: in the feed and
+ * pushed, no email unless the app adds it. Spread it and override what you need
+ * (`actions: "message"` with genesis-notifications' `MESSAGE_ACTIONS` for reply
+ * and mark-as-read buttons).
+ */
+declare const CHAT_NOTIFICATION_TYPES: {
+    readonly "chat.message": {
+        readonly category: "messages";
+        readonly channels: {
+            readonly in_app: true;
+            readonly push: true;
+        };
+        readonly render: (data: Record<string, unknown>) => {
+            push: {
+                ids: Record<string, string | number>;
+                display: Record<string, string | number>;
+                mutableContent: boolean;
+            };
+            url?: string | undefined;
+            body?: string | undefined;
+            title: string;
+        };
+    };
+};
+
+/**
+ * AI help for a conversation, through the Claude API: a short recap of what
+ * came in since someone last looked, and a reply draft in a coach's voice.
+ * Nothing is ever sent: the caller shows the text, labelled as written by AI,
+ * and a person decides. Internal notes (visibility `observers`) and messages
+ * moderation hid are left out unless the caller says the reader is an
+ * observer: take `observer` from `genesis_chat.i_observe(conversation)` asked
+ * as the reader, never from the request.
+ *
+ * Pass `anthropic` (an `@anthropic-ai/sdk` client) or nothing: without one it
+ * calls `POST /v1/messages` with fetch and `apiKey`. Messages go to the API as
+ * a transcript inside one user turn, marked as data to summarise, not
+ * instructions to follow; `<` and `>` in bodies, names and the coach's voice
+ * are replaced, so nothing in a message can close or open a tag.
+ *
+ * `fallbacks` is a Claude API feature: Bedrock, Vertex AI and Foundry clients
+ * reject it, so pass `fallbacks: false` with those.
+ */
+declare const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+/** The Messages API version the fetch path sends. */
+declare const ANTHROPIC_VERSION = "2026-10-21";
+/** The default model: the current Sonnet. */
+declare const CHAT_ASSISTANT_MODEL = "claude-sonnet-5-5";
+/** One message as the assistant reads it: genesis-chat's `ChatMessage` fits. */
+interface AssistantMessage {
+    senderId: string | null;
+    body: string;
+    createdAt: string;
+    kind?: "text" | "system" | undefined;
+    visibility?: "everyone" | "observers" | undefined;
+    deletedAt?: string | null | undefined;
+    /** `hidden` by moderation: left out unless the reader is an observer. */
+    moderation?: "flagged" | "hidden" | null | undefined;
+}
+interface AssistantResult {
+    text: string;
+    /** The model that wrote it (a fallback model when the first declined). */
+    model: string;
+    /** Always true: show it as written by AI. */
+    labelled: true;
+}
+type NameResolver = (userId: string) => Promise<string | null | undefined> | string | null | undefined;
+interface RecapInput {
+    messages: readonly AssistantMessage[];
+    /** When the reader last looked (ISO time). Messages after it are what the recap covers; up to 20 before it are context. */
+    since?: string | Date | null | undefined;
+    resolveName?: NameResolver | undefined;
+    /** The reader, so their own messages read "You". */
+    me?: string | undefined;
+    /**
+     * The reader observes the conversation (staff), so internal notes and hidden
+     * messages are included. Default false. Take it from `genesis_chat.i_observe`
+     * asked as the reader, never from the request.
+     */
+    observer?: boolean | undefined;
+}
+interface DraftReplyInput {
+    messages: readonly AssistantMessage[];
+    /** How the coach writes ("warm, brief, first names, no emoji"). */
+    voice?: string | undefined;
+    /** The coach the draft is for: their messages read "You". */
+    me?: string | undefined;
+    resolveName?: NameResolver | undefined;
+    observer?: boolean | undefined;
+}
+/** The part of an `@anthropic-ai/sdk` client this uses. */
+interface AnthropicLike {
+    beta: {
+        messages: {
+            create(body: Record<string, unknown>): Promise<{
+                content: {
+                    type: string;
+                    text?: string;
+                }[];
+                model: string;
+                stop_reason?: string | null;
+            }>;
+        };
+    };
+}
+interface ChatAssistantOptions {
+    /** An `@anthropic-ai/sdk` client (`new Anthropic()`); else fetch with `apiKey`. */
+    anthropic?: AnthropicLike | undefined;
+    fetch?: typeof fetch | undefined;
+    /** `ANTHROPIC_API_KEY`, for the fetch path. */
+    apiKey?: string | undefined;
+    /** Default `claude-sonnet-5-5`. */
+    model?: string | undefined;
+    /** Output cap per answer, thinking included (default 4000). */
+    maxTokens?: number | undefined;
+    /** Re-run a declined request on Anthropic's recommended fallback model (default true). */
+    fallbacks?: boolean | undefined;
+    timeoutMs?: number | undefined;
+}
+interface ChatAssistant {
+    recap(input: RecapInput): Promise<AssistantResult>;
+    draftReply(input: DraftReplyInput): Promise<AssistantResult>;
+}
+/** The transcript lines (exported for tests): notes and hidden messages stripped unless `observer`, deleted messages left out, angle brackets neutralised, oldest first. */
+declare function transcriptLines(messages: readonly AssistantMessage[], options: {
+    resolveName?: NameResolver | undefined;
+    me?: string | undefined;
+    observer?: boolean | undefined;
+}): Promise<{
+    at: number;
+    line: string;
+}[]>;
+/** The recap's user turn (exported for tests). */
+declare function recapPrompt(input: RecapInput): Promise<string>;
+/** The draft's user turn (exported for tests). */
+declare function draftPrompt(input: DraftReplyInput): Promise<string>;
+declare function createChatAssistant(options: ChatAssistantOptions): ChatAssistant;
+
+/**
+ * A fetch handler that gives a composer a direct-upload URL for a video, after
+ * the app confirms the person may post in that conversation.
+ *
+ *   POST { conversationId }  →  { url, providerId, provider: "mux" }
+ *   OPTIONS                  →  204 with CORS headers, for an allowed origin
+ *
+ * The client PUTs the file to `url` and sends its message with an attachment
+ * `{ kind: "video", provider: "mux", provider_id: providerId, status: "pending" }`.
+ *
+ * The caller chooses nothing the webhook trusts. The server sets the upload's
+ * passthrough to the conversation (and the uploader, when `authorize` names
+ * them); the webhook finds the attachment only by the upload id the client sent
+ * with its message, and applies an event only when the passthrough names that
+ * attachment's conversation (and its sender). So nobody can aim their upload at
+ * another conversation's video.
+ */
+
+/** Who an upload is for: written by the server into the upload's passthrough, never by the client. */
+interface ChatUploadBinding {
+    conversationId: string;
+    /** The uploader, when the app's `authorize` named them. */
+    userId?: string | undefined;
+}
+/** `gc1:<conversation id>:<user id or empty>`: the passthrough the upload handler sets. */
+declare function chatUploadPassthrough(binding: ChatUploadBinding): string;
+/** Reads a passthrough the upload handler set, or null for anything else. */
+declare function parseChatUploadPassthrough(value: string | null | undefined): ChatUploadBinding | null;
+interface VideoUploadHandlerOptions {
+    /** `muxVideo(...)`. */
+    video: Pick<VideoProvider, "name" | "createUpload">;
+    /**
+     * Must confirm the request's user may post in `conversationId` (verify their
+     * session, then ask the database as them, e.g. a select on
+     * `genesis_chat.members` under row level security). Resolve false to refuse.
+     * Resolve `{ userId }` to also bind the upload to its uploader: the webhook
+     * then applies it only to a message they sent.
+     */
+    authorize: (request: Request, context: {
+        conversationId: string;
+    }) => Promise<boolean | {
+        userId: string;
+    }> | boolean | {
+        userId: string;
+    };
+    /**
+     * Required. The web origin(s) allowed to upload: one origin, or a list that
+     * the request's `origin` header must be in. Native apps send no origin; they
+     * get the first. `"*"` allows any origin (only for an app with no web client).
+     */
+    corsOrigin: string | readonly string[];
+    /**
+     * A per-user cap on minting uploads (each one can cost money). Resolve false
+     * to answer 429. Called after `authorize`, with the user it named.
+     */
+    rateLimit?: ((request: Request, context: {
+        conversationId: string;
+        userId: string | undefined;
+    }) => Promise<boolean> | boolean) | undefined;
+}
+declare function createVideoUploadHandler(options: VideoUploadHandlerOptions): (request: Request) => Promise<Response>;
+
+export { ANTHROPIC_MESSAGES_URL, ANTHROPIC_VERSION, type AnthropicLike, type AssistantMessage, type AssistantResult, CHAT_ASSISTANT_MODEL, CHAT_MAX_ATTEMPTS, CHAT_NOTIFICATION_CATEGORIES, CHAT_NOTIFICATION_TYPES, CHAT_NOTIFICATION_TYPE_ID, type ChatAssistant, type ChatAssistantOptions, type ChatDeliver, type ChatEffect, type ChatEffectKind, type ChatNotification, type ChatNotifyInput, type ChatRecipient, type ChatRunReport, type ChatRunner, type ChatRunnerHandlerOptions, type ChatRunnerOptions, type ChatUploadBinding, type DeepgramOptions, type DraftReplyInput, EXPO_BATCH, EXPO_SEND_URL, type ExpoDeliverOptions, type ExpoDeliveryTicket, type ExpoPushMessage, type ExpoPushTicket, type FakeReadyOptions, type FakeVideoProviderOptions, type LinkPreview, type LinkUnfurler, type LinkUnfurlerOptions, type ModerateInput, type ModerationResult, type ModerationThresholds, type ModerationVerdict, type Moderator, type MuxSigningKey, type MuxVideoOptions, type NotificationsDeliverOptions, OPENAI_MODERATIONS_URL, OPENAI_MODERATION_CATEGORIES, type OpenAiModeratorOptions, type OpenAiTranscriberOptions, type RecapInput, type TranscribeInput, type TranscribeResult, type Transcriber, type VideoProvider, type VideoUploadHandlerOptions, carriesCredential, chatNotifyInput, chatRunnerHandler, chatUploadPassthrough, createChatAssistant, createChatRunner, createExpoDeliver, createLinkUnfurler, createVideoUploadHandler, deadTokens, decodeEntities, deepgramTranscriber, draftPrompt, fakeVideoProvider, guardedLookup, isPrivateAddress, moderationVerdict, muxPlaybackToken, muxPlaybackUrl, muxVideo, notificationsDeliver, openAiModerator, openAiTranscriber, parseChatUploadPassthrough, parseOpenGraph, recapPrompt, transcriptLines, verifyMuxSignature };