@palbase/web 1.4.0 → 1.6.0

package/dist/{analytics-facade-CbXprYrS.d.ts → analytics-facade-DYNLUW0L.d.ts}

@@ -700,6 +700,24 @@ declare class PalbeFlags {
     destroy(): void;
 }
 
+/**
+ * Pure deadline math — the web mirror of iOS DeadlineCalculator (Codex-finalized
+ * restart conversion rule). Identical algorithm; web uses ms internally and
+ * compares against ttlSeconds (converted). Clock readings are passed in so it is
+ * fully table-testable and byte-identical with iOS.
+ *
+ * NOTE on the send-vs-arrival clamp: like iOS T3, this Calculator stays PURE — it
+ * consumes an already-resolved anchor + the current clock readings. The
+ * `min(sender_send_ts + ttl, first_arrival_monotonic + ttl)` effective-deadline
+ * basis is applied at ARM time by the caller (Chat, T10), which picks the anchor's
+ * monotonic baseline; the Calculator only converts that anchor into remaining/purge.
+ */
+interface AnchorTriple {
+    mAnchorMs: number;
+    wAnchorEpochMs: number;
+    bAnchorToken: string;
+}
+
 /** A direct (1:1) chat or a multi-party group. */
 type ChatKind = 'direct' | 'group';
 /** A draft (local-only, not yet on the server) or an active (materialized) chat. */
@@ -710,6 +728,20 @@ type ChatRole = 'owner' | 'admin' | 'member';
 type MessageDirection = 'incoming' | 'outgoing';
 /** A renderable message kind. `system` = a membership commit / control frame. */
 type ChatMessageKind = 'text' | 'media' | 'system';
+/**
+ * A resolved mention span inside a message body. Produced at decode/merge time by
+ * NORMALIZING the wire `body_ranges` (the pinned `normalizeMentionRangesUtf16`
+ * contract) against the message text, then resolving the `mentionedUserId` to a
+ * roster display name. Offsets are UTF-16 code units, half-open `[start, start+length)`.
+ * `displayName` is `null` when the mentioned user is not in the local roster (the
+ * renderer falls back to the underlying `text` slice). Mirrors iOS `ResolvedMention`.
+ */
+interface ResolvedMention {
+    readonly start: number;
+    readonly length: number;
+    readonly mentionedUserId: string;
+    readonly displayName: string | null;
+}
 /** A participating USER (not a device). For a direct chat: `[me, peer]`. */
 interface ChatMember {
     /** == userId (stable identity). */
@@ -774,6 +806,25 @@ interface ChatMessage {
      * local-only suppression that omits the message from this view entirely.)
      */
     readonly isDeleted: boolean;
+    /**
+     * The resolved mention spans on this message (defaults to `[]`). A mention is a
+     * NORMAL bubble — these spans only annotate the existing `text` for highlighting,
+     * they never make a message non-bubble. Recomputed by the Chat as the roster
+     * resolves (display names are live, not snapshotted). When this message is
+     * tombstoned (deleted-for-everyone) the spans are scrubbed to `[]` (delete
+     * DOMINATES); when it is edited they reflect the EDIT's replacement `body_ranges`.
+     */
+    readonly mentions: ResolvedMention[];
+    /**
+     * The LOCAL purge deadline for this message (monotonic-derived, never a wire field).
+     * `null` when this message has no TTL. The UI may show a countdown; the durable truth
+     * is the persisted anchor + a re-check on every load (disappearing T10). A message's
+     * effective TTL is its OWN per-message `expiry` if present, else the chat default
+     * `timer_set` active AS OF this message's order (forward-only — a message ordered
+     * BEFORE the governing `timer_set` inherits nothing; own-expiry WINS over the default).
+     * Mirrors iOS `ChatMessage.effectiveExpiry` (which it derives from).
+     */
+    readonly expiresAt: Date | null;
 }
 /** The receipt from a send — the server's monotonic sequence + accepted epoch. */
 interface SentReceipt {
@@ -814,6 +865,15 @@ interface ReplyRef {
     client_msg_id: string;
     preview?: QuotePreview;
 }
+/** A single mention range inside a message body.
+ * Offsets are UTF-16 code units, half-open [start, start+length).
+ * Wire: snake_case (mentioned_user_id, body_ranges) — web does RAW JSON, no case-convert.
+ */
+interface MentionRange {
+    start: number;
+    length: number;
+    mentionedUserId: string;
+}
 interface ReactionPayload {
     targetClientMsgId: string;
     emoji: string;
@@ -827,6 +887,13 @@ interface DeletePayload {
     targetClientMsgId: string;
     scope: string;
 }
+/** Per-message TTL spec (decoded). senderSendTs present iff start === 'send'. */
+interface ExpirySpec {
+    v: number;
+    ttlSeconds: number;
+    start: 'send' | 'read';
+    senderSendTs: number | null;
+}
 
 /** A decoded incoming message handed to chat listeners. */
 interface IncomingMessage {
@@ -857,6 +924,20 @@ interface IncomingMessage {
      * the Chat route a delete-for-everyone tombstone into its DeleteFold instead of
      * appending a visible bubble. */
     delete?: DeletePayload | null;
+    /** The decoded mention ranges (raw, un-normalized). Present on a `'text'` bubble
+     * with `body_ranges` OR on an `'edit'` (the edit's replacement ranges). The Chat
+     * normalizes + resolves roster names → `ChatMessage.mentions` (mentions T6). */
+    bodyRanges?: MentionRange[] | null;
+    /** The decoded `timer_set` payload, present only when `envelopeType === 'timer_set'`
+     * (disappearing T10). Lets the Chat route a chat-default timer into its TimerFold
+     * instead of appending a visible bubble. */
+    timer?: {
+        ttlSeconds: number | null;
+        start: 'send' | 'read';
+    } | null;
+    /** The decoded per-message TTL spec, present only on a `'text'` bubble that carried an
+     * `expiry` (disappearing T10). Lets the Chat arm the message's purge on first display. */
+    expiry?: ExpirySpec | null;
 }
 
 /** The intended participants of a draft chat (held until the first send). */
@@ -876,7 +957,7 @@ interface ChatBackend {
     selfUserId: string;
     /** Materialize a draft → the active group (DM get-or-create / group create+add). */
     materialize(draft: ChatDraft): Promise<MessagingGroup>;
-    sendText(group: MessagingGroup, text: string, replyTo?: ReplyRef | null): Promise<{
+    sendText(group: MessagingGroup, text: string, replyTo?: ReplyRef | null, bodyRanges?: MentionRange[] | null, expiry?: ExpirySpec | null): Promise<{
         receipt: SentReceipt;
         clientMsgId: string;
     }>;
@@ -897,6 +978,7 @@ interface ChatBackend {
         clientMsgId: string;
         targetClientMsgId: string;
         newText: string;
+        bodyRanges?: MentionRange[] | null;
     }): Promise<{
         receipt: SentReceipt;
         clientMsgId: string;
@@ -927,6 +1009,36 @@ interface ChatBackend {
     loadSuppressed(group: MessagingGroup): Promise<string[]>;
     /** Persist this chat's delete-for-me suppression keys (durable, no wire). */
     saveSuppressed(group: MessagingGroup, keys: string[]): Promise<void>;
+    /** Load this chat's persisted self-elevation dedup keys (durable, no wire) so a
+     * re-delivered mention does not re-fire `onMentionElevation` after a cold launch. */
+    loadElevated(group: MessagingGroup): Promise<string[]>;
+    /** Persist this chat's self-elevation dedup keys (durable, no wire). */
+    saveElevated(group: MessagingGroup, keys: string[]): Promise<void>;
+    /** Send a per-chat default disappearing-timer control envelope (`timer_set`). Goes
+     * through the SAME MLS application path as `sendText` — server-blind, never a bubble.
+     * `ttlSeconds === null` disables the default. Returns the receipt + the wire clientMsgId. */
+    sendTimerSet(group: MessagingGroup, args: {
+        clientMsgId: string;
+        ttlSeconds: number | null;
+        start: 'send' | 'read';
+    }): Promise<{
+        receipt: SentReceipt;
+        clientMsgId: string;
+    }>;
+    /** The persisted INTEGER `server_seq` tombstone set for a chat — drives transcript
+     * exclusion (cold-launch) + redelivery drop (live arrival). Durable, no wire. */
+    tombstonedSeqs(group: MessagingGroup): Promise<Set<number>>;
+    /** The persisted STRING `client_msg_id` purge set — drives the orphan-fold resolver
+     * (`authorOfTarget → 'purged'`) so a late edit DROPs / a late delete no-ops. */
+    purgedClientMsgIds(group: MessagingGroup): Promise<Set<string>>;
+    /** The persisted write-once anchor triple for a `clientMsgId`, or null if none. */
+    anchor(group: MessagingGroup, clientMsgId: string): Promise<AnchorTriple | null>;
+    /** Write-once: capture the first-arrival/first-read anchor triple for a `clientMsgId`
+     * (a second call for the same id is a no-op, so the deadline never resets). */
+    writeAnchorOnce(group: MessagingGroup, clientMsgId: string, a: AnchorTriple): Promise<void>;
+    /** Tombstone-first purge commit point: persist the int `server_seq` + string
+     * `client_msg_id` purge id in ONE durable record (idempotent). */
+    tombstone(group: MessagingGroup, serverSeq: number, clientMsgId: string): Promise<void>;
 }
 declare class Chat {
     /** Stable, URL/log-safe id (the grp_ display id once active; a reserved local id while draft). */
@@ -952,12 +1064,35 @@ declare class Chat {
     /** The single authoritative delete-for-everyone fold (live + own-send + history).
      * A tombstone scrubs its target in place (delete DOMINATES edit at render). */
     private readonly deleteFold;
+    /** The per-chat default disappearing-timer fold — the latest valid `timer_set` (LWW
+     * on (epoch, serverSeq), author = the resolved MLS sender). A `timer_set` is NEVER a
+     * bubble; it routes here. The active default governs a subsequent bubble that carries
+     * no per-message expiry (disappearing T10). */
+    private readonly timerFold;
+    /** Advisory in-memory purge timers, keyed by serverSeq. The DURABLE truth is the
+     * persisted anchor + a re-check on every load; this just drives live eviction while
+     * the tab is open. Cancelled when the message purges (disappearing T10). */
+    private readonly purgeTimers;
+    /** In-memory mirror of the durable `purgedClientMsgIds` set (the STRING namespace),
+     * hydrated from `backend.purgedClientMsgIds` and grown by each live purge. Consulted
+     * by `authorOfTarget` so a late edit/delete targeting a TTL-purged message resolves to
+     * `'purged'` (DROP / no-op — never resurrects). Namespace-separate from the int seq
+     * tombstone (disappearing T10). */
+    private readonly purgedCids;
+    private purgedLoaded;
     /** delete-for-me suppression keys (clientMsgId, or `seq:<serverSeq>` for legacy)
      * — the message is OMITTED from this view. Local + persisted per chat, NO wire. */
     private readonly suppressed;
     /** True once the persisted suppression set has been loaded (so the omit applies
      * even on the cold-launch hydrate path before a fresh deleteForMe). */
     private suppressedLoaded;
+    /** Self-elevation dedup keys (`<selfUserId>|<clientMsgId or seq:n>`). Once a
+     * mention of me from another sender fires `onMentionElevation`, its key lands here
+     * + is persisted, so a re-delivery / cold-launch re-hydrate never re-fires. */
+    private readonly elevated;
+    /** True once the persisted elevation set has been loaded (so a re-delivered mention
+     * on the cold-launch hydrate path dedups against the persisted decision). */
+    private elevatedLoaded;
     /** Per-target BASE (original) text, so the rendered text is `edit ?? original`.
      * Seeded once per target (write-once base) so a 2nd own edit can't corrupt it. */
     private readonly originalTextByClientMsgId;
@@ -969,6 +1104,14 @@ declare class Chat {
     private wired;
     private liveUnsub;
     private readonly listeners;
+    /**
+     * Fires ONCE per `(selfUserId, clientMsgId)` when an INCOMING message mentions THIS
+     * user from ANOTHER sender (not an edit). The dedup survives re-delivery + reload
+     * via the persisted elevation set, so this never double-fires for one mention. The
+     * app wires it to a buzz/badge (e.g. an in-app banner). Best-effort cooperative —
+     * the SDK guarantees the DECISION, not the buzz. Mirrors iOS `Chat.onMentionElevation`.
+     */
+    onMentionElevation?: (message: ChatMessage) => void;
     /** @internal — obtain via pb.messaging.directChat / groupChat / chat(id). */
     constructor(args: {
         group: MessagingGroup;
@@ -1006,17 +1149,85 @@ declare class Chat {
     get title(): string;
     presence(userId: string): PresenceState | null;
     private ensureWired;
+    /** Hydrate the durable `purgedClientMsgIds` set (once) into the in-memory mirror so the
+     * live Edit/Delete fold author-gate sees TTL-purged targets as 'purged' on cold launch
+     * (disappearing T10). No re-emit: it only gates the orphan-fold resolution. */
+    private loadPurged;
     /** Hydrate the persisted delete-for-me suppression keys (once), then re-emit so
      * any already-surfaced suppressed message is omitted (cold-launch parity). */
     private loadSuppressed;
+    /** Hydrate the persisted self-elevation dedup keys (once). No re-emit: the set only
+     * gates the elevation DECISION, it does not change what renders. */
+    private loadElevated;
     private hydrateHistory;
     private mergeHistory;
     /** @internal — called by the backend's live subscription. */
     ingestLive(incoming: IncomingMessage): Promise<void>;
-    /** The EditFold author-gate input: the target message's resolved author userId
-     * (null = target unknown/dangling → the fold HOLDs). Captured as a bound arrow
-     * so it can be passed to the pure EditFold. */
+    /** Normalize a decoded `IncomingMessage.expiry` / `StoredMessage.expiry` into the
+     * `ExpirySpec` the arm path consumes (or null when absent). */
+    private toExpirySpec;
+    /** The chat-default expiry derived from the active `timer_set` fold, as an `ExpirySpec`
+     * so a bubble with no per-message expiry inherits it. null when no default is active or
+     * the default was explicitly DISABLED (`ttlSeconds === null`). `senderSendTs` is null —
+     * the default has no per-message sender clock; the arrival anchor drives the deadline
+     * (mirrors iOS `defaultExpiry()`). */
+    private defaultExpiry;
+    /** The surfaced display deadline for an effective expiry (a local, monotonic-derived
+     * value — the wall-clock projection of the TTL from now). null for a non-disappearing
+     * message. The durable purge is driven by `armPurge`'s write-once anchor; this is the
+     * UI countdown baseline. */
+    private deadlineFor;
+    /** Arm a message's TTL purge on first decrypt-and-display. Captures the WRITE-ONCE
+     * monotonic/wall/boot anchor (so the deadline survives a reload — a re-arm after relaunch
+     * reads back the ORIGINAL capture, never a fresh one → the deadline never resets),
+     * computes the remaining time via `remainingSeconds`, applies the send-anchor clamp
+     * `min(sender_send_ts+ttl, first_arrival+ttl)` (read-anchor uses the write-once first-read
+     * capture), then either purges immediately or schedules an advisory `setTimeout`. A null
+     * expiry / empty clientMsgId is a no-op. Mirrors iOS `armPurge`. */
+    private armPurge;
+    /** Re-arm a purge from a derived deadline (cold-launch hydrate path). The deadline is
+     * the projection's monotonic-derived `expiresAt`; schedule an advisory timer for the
+     * remaining time (purge immediately if the deadline has already passed). The durable
+     * tombstone is written by `purge` when it fires (the crash-safe commit point). */
+    private armFromDeadline;
+    /** Purge message M (TTL eviction). TOMBSTONE-FIRST (the crash-safe commit point):
+     * persist the `server_seq` tombstone + the `client_msg_id` purge id in ONE durable
+     * record, THEN drop M's body from `messageList` + `emit()`, then re-evaluate any HELD
+     * edit / PARKED delete targeting the now-purged cid so an orphan annotation DROPs/no-ops
+     * (the resolver now returns `'purged'`). Idempotent. Mirrors iOS `purge`. */
+    private purge;
+    /** The Edit/Delete fold author-gate input via {@link AuthorResolution} (disappearing
+     * T10 — the orphan-aware resolver): `'purged'` when the target's clientMsgId is in the
+     * durable purge set (a late edit DROPs / a late delete no-ops — never resurrects a
+     * disappeared message); `'author'` when its author is locally known → run the
+     * author-gate; `'unknown'` otherwise → HOLD. The live twin of `projectHistory`'s
+     * resolver. Captured as a bound arrow so it can be passed to the pure folds. */
     private readonly authorOfTarget;
+    /** Resolve a message's decode-time mention spans: NORMALIZE the raw `body_ranges`
+     * against `text` (the pinned `normalizeMentionRangesUtf16` cross-SDK contract) then
+     * resolve each surviving range's `mentionedUserId` to a roster display name. An id
+     * not in the roster resolves to `null` (the renderer falls back to the `text` slice).
+     * Pure over (text, bodyRanges, memberCache); never throws. Mirrors iOS T3. */
+    private resolveMentions;
+    /** Re-resolve the roster display name on already-NORMALIZED spans (the history
+     * projection produces them with null names — resolution is LIVE, not snapshotted).
+     * A member rename then reflects on old messages. Returns the message unchanged when
+     * it has no mentions (the common case) or no name changed. Mirrors iOS T3. */
+    private resolveMentionNames;
+    /** The WINNING edit's resolved mentions for a target (normalize its replacement
+     * ranges against the new text + roster names), or `[]` if no winning edit / no
+     * ranges. The edited message's mentions reflect the EDIT's ranges (mirrors iOS T3). */
+    private editMentions;
+    /** Resolve a userId → its roster display name (null if not a known member). */
+    private displayNameOf;
+    /** Compute the SELF-ELEVATION decision for a freshly-ingested INCOMING bubble and,
+     * when it fires, record the dedup key (persisted) + invoke `onMentionElevation`.
+     * Gate (mirrors iOS T3): a surviving mention targets THIS user AND the sender is not
+     * me AND it's NOT an edit AND the `(selfUserId, clientMsgId|seq)` key isn't already
+     * elevated. Dedup-once: the in-memory set gates the session, the persisted set
+     * survives reload. An EDIT never reaches here (it folds, not a bubble) — the
+     * `envelopeType !== 'edit'` guard is belt-and-braces. */
+    private elevateIfMentioned;
     /** Seed the per-target base text + author for the edit fold. Base is write-once
      * (a later own/peer edit must not overwrite the original we render against). The
      * author is (re)recorded whenever a non-empty resolution is available. */
@@ -1057,11 +1268,29 @@ declare class Chat {
     /** Page older messages in. Returns how many were prepended. */
     loadEarlier(limit?: number): Promise<number>;
     private refreshMembers;
+    /** Re-resolve roster display names across the whole transcript (called on a roster
+     * change). Re-emits only if any name actually changed. */
+    private reresolveAllMentionNames;
     private seedMembersFromGroup;
     private seedDraftMembers;
     send(text: string, opts?: {
         replyTo?: ChatMessage;
+        mentions?: MentionRange[];
+        expiresIn?: {
+            ttlSeconds: number;
+            start?: 'send' | 'read';
+        };
     }): Promise<SentReceipt>;
+    /** Set (or DISABLE) this chat's DEFAULT disappearing timer. Emits a `timer_set` control
+     * envelope (server-blind — an opaque application message, NEVER a bubble) and folds the
+     * own-set locally so the default applies immediately to subsequent sends that carry no
+     * per-message expiry. `ttlSeconds === null` DISABLES the default. FIRE-AND-FORGET
+     * ADVISORY: returns on the LOCAL emit only; it exposes NO "active for all peers" signal.
+     * Mirrors iOS `setDisappearing(ttlSeconds:start:)`. */
+    setDisappearing(opts: {
+        ttlSeconds: number | null;
+        start?: 'send' | 'read';
+    }): Promise<void>;
     private appendOwnSend;
     private materializeIfNeeded;
     addMemberUser(userId: string): Promise<void>;
@@ -1084,8 +1313,11 @@ declare class Chat {
      * instantly; the durable echo on the next pump is a fold no-op (dedup on the
      * SAME wire clientMsgId). Never appends a bubble; PRESERVES the target's
      * reactions + reply context. Only the original author's edits count — for an own
-     * message self IS the author, so the author-gate passes. */
-    edit(message: ChatMessage, newText: string): Promise<void>;
+     * message self IS the author, so the author-gate passes. `opts.mentions` carries the
+     * edit's REPLACEMENT mention ranges → the edited message's mentions reflect them. */
+    edit(message: ChatMessage, newText: string, opts?: {
+        mentions?: MentionRange[];
+    }): Promise<void>;
     /** Delete a message for EVERYONE (a cooperative encrypted tombstone). Only the
      * ORIGINAL SENDER can do this — for an own message self IS the author, so the
      * author-gate passes. Legacy messages (empty clientMsgId) are DISABLED (a
@@ -1491,4 +1723,4 @@ declare class PalbeAnalytics {
     private post;
 }
 
-export { type AnalyticsProperties as A, type RealtimeConnectionState as B, Call as C, type RealtimeHandler as D, type RealtimePayload as E, type FlagsView as F, type RealtimeStatus as G, type RealtimeStatusSnapshot as H, type RealtimeSubscription as I, type ResolvedReply as J, type PalbeRuntime as K, buildRuntime as L, type MagicLinkResult as M, type OAuthExchangeResult as O, PalbeAnalytics as P, RealtimeChannel as R, type SentReceipt as S, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MessageDirection as r, PalbeAuth as s, PalbeCalls as t, type PalbeConfig as u, PalbeFlags as v, PalbeMessaging as w, type PalbeOAuthConfig as x, PalbeRealtime as y, type PresenceState as z };
+export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type PalbeRuntime as N, type OAuthExchangeResult as O, PalbeAnalytics as P, buildRuntime as Q, RealtimeChannel as R, type SentReceipt as S, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };