@marktiderman/genesis-chat 0.1.1 → 0.2.1

package/dist/outbox-B9NAWQ58.d.ts

@@ -0,0 +1,219 @@
+import { b as AttachmentKind, A as AttachmentInput, U as UploadProgress, H as HostedAttachment, i as ChatClient, B as PendingMessage, P as PendingFile, q as ChatMessage, F as SendInput } from './client-DUIG1hum.js';
+
+/**
+ * @feat:chat
+ * Media rules shared by every platform: which files may be sent (the same list
+ * migration 0001 checks), what kind an upload becomes, the default limits, and
+ * the waveform a voice note carries so its bubble draws before the audio loads.
+ */
+
+/**
+ * A random UUID (v4): `crypto.randomUUID` where the platform has it (some React Native
+ * runtimes don't), else `crypto.getRandomValues`, else Math.random as a last resort. Ids
+ * only need to be unique per sender: the server checks (sender, client_id).
+ */
+declare function randomId(): string;
+/** Mirrors genesis_chat.allowed_extension. Never SVG or HTML, which a browser runs as a page. */
+declare const ALLOWED_EXTENSIONS: readonly ["png", "jpg", "jpeg", "webp", "gif", "heic", "heif", "m4a", "aac", "mp3", "ogg", "oga", "opus", "weba", "webm", "mp4", "mov", "pdf", "txt", "csv", "docx", "xlsx", "pptx"];
+/** The extension a file is stored under: from its content type, else its name. */
+declare function fileExtension(name: string, contentType?: string): string;
+declare function isAllowedExtension(ext: string): boolean;
+/** What an upload becomes in a message. */
+declare function attachmentKindFor(contentType: string, opts?: {
+    recordedVoice?: boolean;
+}): AttachmentKind;
+/** Default limits (decision 5): an app may lower them, not raise them past the bucket's 100 MB. */
+declare const CHAT_LIMITS: {
+    /** Voice notes and videos, for members. */
+    readonly recordingMs: number;
+    /** For owners, admins and observers (coaches, staff). */
+    readonly staffRecordingMs: number;
+    readonly fileBytes: number;
+    readonly videoBytes: number;
+    readonly attachmentsPerMessage: 20;
+    readonly bodyChars: 10000;
+};
+/** The longest recording this role may make. */
+declare function recordingLimitMs(role: string | null | undefined): number;
+/**
+ * Peaks for a waveform: `count` values 0–100 from raw samples (-1…1), the loudest
+ * in each bucket, scaled so the loudest bucket is 100. Quiet recordings still show
+ * a shape; silence shows a flat line.
+ */
+declare function waveformPeaks(samples: ArrayLike<number>, count?: number): number[];
+/**
+ * Peaks from a level meter read while recording (expo-audio's `metering`, in dB,
+ * about -160…0): resampled to `count` values 0–100.
+ */
+declare function waveformFromMetering(levelsDb: number[], count?: number): number[];
+/** 0:42, 1:05:09. */
+declare function formatDuration(ms: number | null | undefined): string;
+/** Playback speeds offered for voice and video (free for everyone, decision 5). */
+declare const PLAYBACK_RATES: readonly [1, 1.5, 2];
+declare function nextPlaybackRate(rate: number): number;
+
+/**
+ * @feat:chat
+ * The send queue: a message shows at once as pending, its files upload, then it
+ * is sent with the clientId made when it was written, so a retry (after a lost
+ * connection, a closed app) never posts twice. Messages to one conversation go
+ * in the order they were written: the first that can't go (a lost file, a refusal)
+ * holds back the ones after it. A refusal (not allowed, bad data) is `permanent`
+ * and only sent again by hand. `clear()` (sign-out) stops sends in flight: none
+ * posts, or saves anything, afterwards. Storage is the platform's (memory by default;
+ * localStorage on web, MMKV or SQLite on native), behind OutboxStore.
+ *
+ * A hosted video (`LocalFile.hosted`, with `hostedUpload`) doesn't wait for its bytes: the
+ * upload is started (the provider's upload id minted), the message is sent in its place in the
+ * order with the attachment `pending`, and the bytes carry on going up; the provider's webhook
+ * marks it ready. The message stays here (hidden from the thread once the server has it) until
+ * its bytes are up, so a relaunch carries the upload on (`resume`) and sends the message again
+ * with the same clientId, which posts nothing twice.
+ */
+
+/** A file still on the device, uploaded when its message is sent. */
+interface LocalFile {
+    /** The bytes, or (native) a file URI the platform reads in `readFile`. */
+    data: Blob | ArrayBuffer | string;
+    name: string;
+    contentType: string;
+    /** A preview to show while it uploads (an object URL, a file URI). The outbox owns it from here: see `releasePreview`. */
+    previewUrl?: string;
+    /** Known up front: a voice note's duration and waveform, a photo's size. */
+    meta?: Partial<Omit<AttachmentInput, "path" | "kind">> & {
+        kind?: AttachmentInput["kind"];
+    };
+    /**
+     * Send it to the hosted video provider (the outbox's `hostedUpload`) instead of storage: the
+     * message goes at once, in order, with the attachment pending, while the bytes go up. Without
+     * a `hostedUpload` it goes to storage like any file.
+     */
+    hosted?: boolean;
+}
+/** A hosted upload as the outbox keeps it (saved with the message), so it can be carried on. */
+interface HostedUploadRecord {
+    provider: HostedAttachment["provider"];
+    providerId: string;
+    /** Where the bytes go, when the hook returned it: what a resume needs. */
+    url?: string;
+    /** Every byte is there. */
+    uploaded?: boolean;
+}
+/** What `hostedUpload` resolves with as soon as the upload exists (before the bytes are up). */
+interface HostedUploadStart extends HostedAttachment {
+    /** Where the bytes go; kept with the message, handed back as `resume.url`. */
+    url?: string;
+    /** Settles when every byte is there (rejects when the transfer fails). Absent: already there. */
+    done?: Promise<void>;
+}
+interface HostedUploadOptions {
+    /** Aborts when the message is discarded or the outbox cleared. */
+    signal?: AbortSignal;
+    onProgress?: UploadProgress;
+    /**
+     * The upload started before (a relaunch, a retry after the transfer failed): carry it on and
+     * resolve with the same `providerId`. A message may already be posted with it, so mint a new
+     * one only when the old upload is gone; that message's video then stays pending.
+     */
+    resume?: HostedUploadRecord;
+}
+/** Starts (or carries on) a hosted upload; resolves once the provider's upload id exists. */
+type HostedUpload = (conversationId: string, file: LocalFile, opts: HostedUploadOptions) => Promise<HostedUploadStart>;
+/** Uploads a file to storage and resolves with its path. */
+type StorageUpload = (conversationId: string, file: LocalFile, opts?: {
+    signal?: AbortSignal;
+    onProgress?: UploadProgress;
+}) => Promise<string>;
+interface QueuedMessage extends Omit<PendingMessage, "files"> {
+    files: LocalFile[];
+    /** What each file is, kept with the saved copy (PendingMessage.files). */
+    pendingFiles?: PendingFile[];
+    /** Files lost on a relaunch (bytes that weren't persisted). */
+    lostFiles?: number;
+    attempts: number;
+    /** Hosted uploads started, by file slot. */
+    hosted?: Record<number, HostedUploadRecord>;
+    /** Posted (this message's id): it waits here only for its hosted bytes to finish. */
+    sentMessageId?: string;
+}
+interface OutboxStore {
+    load(): Promise<QueuedMessage[]>;
+    save(queue: QueuedMessage[]): Promise<void>;
+}
+declare const memoryOutboxStore: () => OutboxStore;
+interface OutboxOptions {
+    client: ChatClient;
+    userId: string;
+    store?: OutboxStore;
+    /** Reads a native file URI into bytes for upload. */
+    readFile?: (uri: string) => Promise<Blob | ArrayBuffer>;
+    /**
+     * Upload hook, e.g. resumable uploads on native. Defaults to client.upload. `signal` aborts
+     * when the message is discarded or the outbox cleared; call `onProgress(sent, total)` as bytes
+     * go, and the pending bubble shows it (`PendingMessage.files[i].progress`).
+     */
+    upload?: StorageUpload;
+    /**
+     * Starts a hosted video upload for a file marked `hosted` and resolves once the provider's
+     * upload id exists, with `done` for the bytes. See HostedUpload; without it, hosted files go
+     * to storage.
+     */
+    hostedUpload?: HostedUpload;
+    /** Called with every change, for the UI. */
+    onChange?: (queue: QueuedMessage[]) => void;
+    /** Called when a message lands. */
+    onSent?: (message: ChatMessage, clientId: string) => void;
+    /** Makes client ids. Default: a random UUID (works where crypto.randomUUID is missing). */
+    newId?: () => string;
+    /**
+     * Keeps a file held as bytes (a pasted image, a recording) between launches: write it
+     * somewhere and return a URI `readFile` can read (native: the app's cache directory).
+     * Without it, such a file isn't saved, and after a relaunch its message asks for it again.
+     */
+    persistFile?: (file: LocalFile) => Promise<string>;
+    /**
+     * Lets go of a file's `previewUrl` once its message has landed, been discarded or cleared.
+     * Default: revokes `blob:` object URLs (the web's), and leaves everything else alone.
+     */
+    releasePreview?: (url: string) => void;
+}
+/** Revokes a `blob:` object URL; anything else (a native file URI) is left alone. */
+declare function releaseObjectUrl(url: string): void;
+declare function createOutbox(opts: OutboxOptions): {
+    /** Queues a message; it shows at once and sends in order. Returns its clientId. */
+    send(input: Omit<SendInput, "clientId"> & {
+        clientId?: string;
+    }, files?: LocalFile[]): Promise<string>;
+    retry(clientId: string): Promise<void>;
+    /**
+     * Gives a message the files it lost on a relaunch and sends it. `files` fill the lost
+     * slots in order (`PendingMessage.files[i].lost`); the files that were kept stay. Pass
+     * one per lost slot; with fewer, the message keeps waiting for the rest.
+     */
+    reattach(clientId: string, files: LocalFile[]): Promise<void>;
+    /**
+     * Retries failed messages (after the connection comes back), in order per conversation,
+     * stopping at the first that can't go on its own: one waiting for a lost file, or one the
+     * server refused (`permanent`, retried only by hand). The ones after it keep waiting.
+     */
+    retryAll(): Promise<void>;
+    /** Forgets every queued message, here and in the store (call it on sign-out). */
+    clear(): Promise<void>;
+    discard(clientId: string): Promise<void>;
+    /**
+     * Uploads one file to storage the way the outbox does (the `upload` hook, or `readFile` then
+     * the client's upload) and resolves with its path: for files sent outside the queue, such as
+     * a scheduled message's.
+     */
+    uploadFile(conversationId: string, file: LocalFile, o?: {
+        signal?: AbortSignal;
+        onProgress?: UploadProgress;
+    }): Promise<string>;
+    pending(conversationId?: string): PendingMessage[];
+    /** A new client id, made the way this outbox makes them. */
+    newId: typeof randomId;
+    load: () => Promise<void>;
+};
+type Outbox = ReturnType<typeof createOutbox>;
+
+export { ALLOWED_EXTENSIONS as A, CHAT_LIMITS as C, type HostedUpload as H, type LocalFile as L, type Outbox as O, PLAYBACK_RATES as P, type QueuedMessage as Q, type StorageUpload as S, type HostedUploadOptions as a, type HostedUploadRecord as b, type HostedUploadStart as c, type OutboxOptions as d, type OutboxStore as e, attachmentKindFor as f, createOutbox as g, fileExtension as h, formatDuration as i, isAllowedExtension as j, recordingLimitMs as k, releaseObjectUrl as l, memoryOutboxStore as m, nextPlaybackRate as n, waveformPeaks as o, randomId as r, waveformFromMetering as w };

package/dist/push.d.ts

@@ -0,0 +1,206 @@
+import { i as ChatClient } from './client-DUIG1hum.js';
+import { O as Outbox, e as OutboxStore, Q as QueuedMessage } from './outbox-B9NAWQ58.js';
+import '@supabase/supabase-js';
+
+/**
+ * @feat:chat
+ * Push glue for genesis-native's push block, data only: the `messages`
+ * category (a switch in Notification settings and an Android channel), its
+ * notification actions (Reply with a text field, Mark read), what a tap opens
+ * (`data.url` = `/messages/<conversationId>`), the reply and mark-read
+ * handlers for the block's `onResponse`, and the match that keeps a thread's
+ * own pushes out of the foreground while it is open (the block's `suppress`).
+ *
+ *   const push = createPush({ …, categories: [...yours, chatPushCategory()],
+ *     onResponse: (r) => void handleChatPushResponse(r, { client: chatClient, notifications: Notifications }) });
+ *   void registerChatNotificationActions(Notifications);       // once, at start
+ *   useSuppressNotifications(chatThreadMatch(conversationId)); // in the thread screen
+ *
+ * The sender sets `categoryId: "messages"` (iOS) / the `messages` channel
+ * (Android) and `data: { url: "/messages/<id>", conversationId, seq, messageId }`;
+ * `chatPushPayload` builds those and the fields iOS rich push reads (the
+ * sender's name and photo, the group, a photo), and it is server safe: import
+ * it from `@marktiderman/genesis-chat/push`.
+ *
+ * A reply goes through the outbox, so a phone that is offline keeps it: pass
+ * the live one (`useChat().outbox`) when the chat screens are mounted, and the
+ * persisted store and user id (`ChatProvider outboxStore`) for when they
+ * aren't. A reply that can't be sent then waits there, failed, with Retry in
+ * its thread.
+ */
+
+declare const CHAT_PUSH_CATEGORY = "messages";
+declare const CHAT_REPLY_ACTION = "reply";
+declare const CHAT_MARK_READ_ACTION = "mark-read";
+interface ChatPushCopy {
+    title: string;
+    description: string;
+    reply: string;
+    replySubmit: string;
+    replyPlaceholder: string;
+    markRead: string;
+}
+declare const chatPushCopy: ChatPushCopy;
+/** The path a message's push opens. */
+declare function chatPath(conversationId: string): string;
+/** The category for createPush's `categories` (genesis-native's NotificationCategory). */
+declare function chatPushCategory(copy?: Partial<ChatPushCopy>): {
+    id: string;
+    title: string;
+    description: string;
+    importance: "high";
+};
+/** expo-notifications' `setNotificationCategoryAsync`, the one call this needs. */
+interface NotificationCategoriesLike {
+    setNotificationCategoryAsync(identifier: string, actions: {
+        identifier: string;
+        buttonTitle: string;
+        textInput?: {
+            submitButtonTitle: string;
+            placeholder: string;
+        };
+        options?: {
+            opensAppToForeground?: boolean;
+            isDestructive?: boolean;
+            isAuthenticationRequired?: boolean;
+        };
+    }[], options?: Record<string, unknown>): Promise<unknown>;
+    dismissNotificationAsync?(identifier: string): Promise<void>;
+}
+/** The actions on a message's notification: Reply (a text field) and Mark read, neither opening the app. */
+declare function chatNotificationActions(copy?: Partial<ChatPushCopy>): ({
+    identifier: string;
+    buttonTitle: string;
+    textInput: {
+        submitButtonTitle: string;
+        placeholder: string;
+    };
+    options: {
+        opensAppToForeground: boolean;
+    };
+} | {
+    identifier: string;
+    buttonTitle: string;
+    options: {
+        opensAppToForeground: boolean;
+    };
+    textInput?: undefined;
+})[];
+/** Registers the actions with the OS (once, at start; it is idempotent). */
+declare function registerChatNotificationActions(notifications: NotificationCategoriesLike, copy?: Partial<ChatPushCopy>, onError?: (error: unknown) => void): Promise<unknown>;
+/** The conversation a push is about: `data.conversationId`, else the id in `data.url`. */
+declare function conversationIdFromData(data: Record<string, unknown> | null | undefined): string | null;
+/**
+ * The client id a reply from this notification sends with: the notification's
+ * own id, as a uuid (it already is one on iOS; anything else is hashed into
+ * one), so the same reply delivered twice posts once.
+ */
+declare function replyClientId(notificationId: string): string;
+/**
+ * The client id for one reply: from the notification's id, the message it is
+ * about (`data.messageId`) and the reply's text. The same reply delivered
+ * twice posts once; two replies to one conversation never share an id, even
+ * when iOS reuses the notification's id for a collapsed push.
+ */
+declare function replyClientIdFor(notificationId: string, data: Record<string, unknown> | null | undefined, body: string): string;
+/** The part of a notification response this reads (expo-notifications' `NotificationResponse`). */
+interface ChatPushResponseLike {
+    actionIdentifier: string;
+    /** The text typed into Reply. */
+    userText?: string;
+    notification: {
+        request: {
+            identifier: string;
+            content: {
+                data?: Record<string, unknown> | null;
+            };
+        };
+    };
+}
+/** "queued": the reply couldn't go now and waits in the outbox, failed, for Retry. */
+type ChatPushOutcome = "replied" | "queued" | "marked-read" | "ignored" | "failed";
+type LiveOutbox = Pick<Outbox, "send" | "pending"> & Partial<Pick<Outbox, "load">>;
+/** How long a reply queued in the live outbox is waited for before it counts as queued, not sent. */
+declare const PUSH_REPLY_WAIT_MS = 15000;
+/** Where a reply waits when it can't go now. */
+interface ChatPushOutboxDeps {
+    /** The live outbox (`useChat().outbox`), or a getter for it (read again after a slow failure): the reply is queued there and sent in order. */
+    outbox?: LiveOutbox | null | (() => LiveOutbox | null | undefined);
+    /** Without a live outbox: the persisted store (`ChatProvider outboxStore`) a reply that failed is added to. */
+    store?: OutboxStore | null;
+    /** Whose store it is (the signed-in user's id). */
+    userId?: string | null;
+}
+/** A reply that couldn't be sent, as the outbox keeps it: shown failed in its thread, with Retry. */
+declare function failedReply(input: {
+    conversationId: string;
+    clientId: string;
+    body: string;
+}, userId: string, error?: string): QueuedMessage;
+/**
+ * Handles Reply and Mark read from a message's notification (pass it as the
+ * push block's `onResponse`). Taps on the notification itself are the block's
+ * routing, not this. Never throws: a failure is the outcome "failed" (and
+ * `onError`).
+ */
+declare function handleChatPushResponse(response: ChatPushResponseLike, deps: {
+    client: Pick<ChatClient, "send" | "markRead">;
+    notifications?: Pick<NotificationCategoriesLike, "dismissNotificationAsync">;
+    onError?: (error: unknown) => void;
+    /** How long to wait for a reply queued in the live outbox to go. Default PUSH_REPLY_WAIT_MS. */
+    waitMs?: number;
+} & ChatPushOutboxDeps): Promise<ChatPushOutcome>;
+/** For the push block's `suppress` / `useSuppressNotifications`: this conversation's pushes, while its thread is open. */
+declare function chatThreadMatch(conversationId: string | null | undefined): ((data: Record<string, unknown>) => boolean) | null;
+/** What a message's push says about itself, for `chatPushPayload`. */
+interface ChatPushPayloadInput {
+    conversationId: string;
+    messageId: string;
+    seq?: number | null | undefined;
+    /** Who sent it: an opaque id (never an email or phone), the name to show and an https photo. */
+    sender?: {
+        id: string;
+        name: string;
+        avatarUrl?: string | null | undefined;
+    } | null | undefined;
+    /** The conversation's name when it is a group; leave it out for a direct conversation. */
+    groupName?: string | null | undefined;
+    /** An https photo in the message, attached to the notification. */
+    imageUrl?: string | null | undefined;
+    /**
+     * The recipient hides previews: the push carries the link and ids only (no
+     * sender, group or photo) and the service extension doesn't run. Send neutral
+     * title and body text with it.
+     */
+    hidePreviews?: boolean | undefined;
+}
+/** The `data` of a message's push. Flat strings and numbers, as genesis-notifications' `PushMessage.data` takes. */
+interface ChatPushData {
+    [key: string]: string | number;
+    url: string;
+    conversationId: string;
+    messageId: string;
+}
+/** The fields to spread into an Expo push message (with `to`, `title`, `body`, `badge`, `channelId`). */
+interface ChatPushPayload {
+    categoryId: typeof CHAT_PUSH_CATEGORY;
+    /** Groups the conversation's notifications, and is the conversation iOS files a Communication Notification under. */
+    threadId: string;
+    /** iOS runs genesis-native's Notification Service Extension only when this is true (`mutable-content: 1`). */
+    mutableContent: boolean;
+    data: ChatPushData;
+}
+/**
+ * The category, thread, `mutableContent` and `data` of a message's push, for
+ * the server that sends it:
+ *
+ *   const message = { to, title, body, badge, channelId: "messages", ...chatPushPayload({ conversationId, messageId, seq, sender, groupName, imageUrl, hidePreviews }) };
+ *
+ * On iOS, with the rich push plugin, a push with a sender is a Communication
+ * Notification (the sender's photo; Focus treats it as a message) and `imageUrl`
+ * is attached. Fields that aren't usable (a URL that isn't https, an empty
+ * name) are left out rather than sent.
+ */
+declare function chatPushPayload(input: ChatPushPayloadInput): ChatPushPayload;
+
+export { CHAT_MARK_READ_ACTION, CHAT_PUSH_CATEGORY, CHAT_REPLY_ACTION, type ChatPushCopy, type ChatPushData, type ChatPushOutboxDeps, type ChatPushOutcome, type ChatPushPayload, type ChatPushPayloadInput, type ChatPushResponseLike, type NotificationCategoriesLike, PUSH_REPLY_WAIT_MS, chatNotificationActions, chatPath, chatPushCategory, chatPushCopy, chatPushPayload, chatThreadMatch, conversationIdFromData, failedReply, handleChatPushResponse, registerChatNotificationActions, replyClientId, replyClientIdFor };

package/dist/push.js

@@ -0,0 +1,3 @@
+export { CHAT_MARK_READ_ACTION, CHAT_PUSH_CATEGORY, CHAT_REPLY_ACTION, PUSH_REPLY_WAIT_MS, chatNotificationActions, chatPath, chatPushCategory, chatPushCopy, chatPushPayload, chatThreadMatch, conversationIdFromData, failedReply, handleChatPushResponse, registerChatNotificationActions, replyClientId, replyClientIdFor } from './chunk-VEPZROQB.js';
+//# sourceMappingURL=push.js.map
+//# sourceMappingURL=push.js.map

package/dist/push.js.map

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