@palbase/web 1.0.1 → 1.1.0

package/dist/{analytics-facade-DV2uAiSg.d.cts → analytics-facade-CAKBIH_U.d.cts}

@@ -1,3 +1,4 @@
+import { Room, ExternalE2EEKeyProvider } from 'livekit-client';
 import { S as SessionStorageAdapter } from './storage-BPaeSG8K.cjs';
 import { F } from './pooled-flags-Bwq4usn0.js';
 
@@ -30,7 +31,7 @@ interface Session$1 {
 }
 type AuthStateEvent$1 = 'SESSION_SET' | 'SESSION_CLEARED';
 type AuthStateCallback$1 = (event: AuthStateEvent$1, session: Session$1 | null) => void;
-type Unsubscribe$2 = () => void;
+type Unsubscribe$3 = () => void;
 
 declare class TokenManager$1 {
     private session;
@@ -44,7 +45,7 @@ declare class TokenManager$1 {
     clearSession(): void;
     isExpired(): boolean;
     refreshSession(): Promise<void>;
-    onAuthStateChange(callback: AuthStateCallback$1): Unsubscribe$2;
+    onAuthStateChange(callback: AuthStateCallback$1): Unsubscribe$3;
     private executeRefresh;
     private notify;
 }
@@ -120,7 +121,7 @@ interface Session {
 }
 type AuthStateEvent = 'SESSION_SET' | 'SESSION_CLEARED';
 type AuthStateCallback = (event: AuthStateEvent, session: Session | null) => void;
-type Unsubscribe$1 = () => void;
+type Unsubscribe$2 = () => void;
 
 declare class TokenManager {
     private session;
@@ -134,7 +135,7 @@ declare class TokenManager {
     clearSession(): void;
     isExpired(): boolean;
     refreshSession(): Promise<void>;
-    onAuthStateChange(callback: AuthStateCallback): Unsubscribe$1;
+    onAuthStateChange(callback: AuthStateCallback): Unsubscribe$2;
     private executeRefresh;
     private notify;
 }
@@ -505,6 +506,107 @@ declare class AuthClient {
     private setSessionAndWireRefresh;
 }
 
+type CallState = 'connecting' | 'active' | 'ended';
+interface CallParticipant {
+    identity: string;
+    isSpeaking: boolean;
+    audioMuted: boolean;
+    videoEnabled: boolean;
+    /** The live <video> element for this participant, or null before track arrives. */
+    videoElement: HTMLVideoElement | null;
+    /** The live <audio> element for this participant, or null before track arrives. */
+    audioElement: HTMLAudioElement | null;
+}
+type CallChangeCallback = (call: Call) => void;
+/**
+ * A live call session. Obtain via `pb.calls.start()` or `pb.calls.accept()`.
+ *
+ * Lifecycle:
+ *   connecting → active (room joined, tracks flowing)
+ *   active → ended   (leave() / remote disconnect)
+ *
+ * Subscribe to changes via `call.subscribe(cb)` which fires on state or
+ * participant changes (mirrors flags `onChange` / realtime `on` pattern).
+ */
+declare class Call {
+    readonly id: string;
+    private _state;
+    private readonly _participants;
+    private readonly _listeners;
+    private readonly _room;
+    private readonly _keyProvider;
+    /** @internal — obtain via PalbeCalls.start() / .accept() */
+    constructor(callId: string, room: Room, keyProvider: ExternalE2EEKeyProvider);
+    get state(): CallState;
+    /** Snapshot of current remote participants (does NOT include the local participant). */
+    get participants(): readonly CallParticipant[];
+    get localParticipant(): Room['localParticipant'];
+    /**
+     * Subscribe to call changes (state + participant updates).
+     * Returns an `Unsubscribe` function — matches the SDK's flags/auth pattern.
+     */
+    subscribe(callback: CallChangeCallback): Unsubscribe;
+    /** Mute / unmute the local microphone. */
+    mute(on: boolean): Promise<void>;
+    /** Enable / disable the local camera. */
+    setCamera(on: boolean): Promise<void>;
+    /**
+     * Set a raw frame encryption key (ArrayBuffer) for this call.
+     * Design seam for SP-1.x web-MLS: call this with the MLS exporter secret
+     * to enable frame-level E2EE via ExternalE2EEKeyProvider.
+     *
+     * NOTE: The room must have been opened with `e2ee` options for this to take
+     * effect. Currently calls connect WITHOUT e2ee — see module docstring.
+     *
+     * TODO(SP-1-web): wire this to MLS-derived key on session join.
+     */
+    setMediaKey(key: ArrayBuffer): Promise<void>;
+    /** Leave the call and disconnect from the LiveKit room. */
+    leave(): Promise<void>;
+    private _setState;
+    private _emit;
+    private _upsertParticipant;
+    private _attachTrack;
+    private _wireRoomEvents;
+}
+declare class PalbeCalls {
+    private readonly rt;
+    constructor(rt: PalbeRuntime);
+    /**
+     * Start a new call in a messaging group.
+     *
+     * @param groupId  - Messaging group display-id (`grp_<uuidv7>`)
+     * @param media    - Which media tracks to publish (default: audio + video)
+     * @returns        A `Call` in `connecting` state; transitions to `active` once LiveKit connects.
+     *
+     * @throws BackendError('network', { code: 'call_service_unavailable' })  if LiveKit SFU is down (503)
+     * @throws BackendError('forbidden', { code: 'not_group_member' })       if the caller is not a member (403)
+     * @throws BackendError('conflict', { code: 'call_room_full' })          if the room is full (409)
+     */
+    start(groupId: string, { media }?: {
+        media?: Array<'audio' | 'video'>;
+    }): Promise<Call>;
+    /**
+     * Accept an incoming call in a messaging group.
+     *
+     * @param groupId  - Messaging group display-id
+     * @param callId   - Call identifier (from the push notification payload)
+     * @param media    - Which media tracks to publish (default: audio + video)
+     */
+    accept(groupId: string, callId: string, { media }?: {
+        media?: Array<'audio' | 'video'>;
+    }): Promise<Call>;
+    /**
+     * Decline an incoming call.
+     *
+     * @param groupId  - Messaging group display-id
+     * @param callId   - Call identifier
+     * @param reason   - Optional decline reason string
+     */
+    decline(groupId: string, callId: string, reason?: string): Promise<void>;
+    private _connect;
+}
+
 interface PalbeOAuthConfig {
     google?: {
         enabled?: boolean;
@@ -598,6 +700,248 @@ declare class PalbeFlags {
     destroy(): void;
 }
 
+/** 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. */
+type ChatState = 'draft' | 'active';
+/** Server-side ACL role (group only; a direct chat has no roles). */
+type ChatRole = 'owner' | 'admin' | 'member';
+/** Whether a message was received (`incoming`) or sent by this device (`outgoing`). */
+type MessageDirection = 'incoming' | 'outgoing';
+/** A renderable message kind. `system` = a membership commit / control frame. */
+type ChatMessageKind = 'text' | 'media' | 'system';
+/** A participating USER (not a device). For a direct chat: `[me, peer]`. */
+interface ChatMember {
+    /** == userId (stable identity). */
+    readonly id: string;
+    readonly userId: string;
+    readonly displayName: string | null;
+    readonly role: ChatRole;
+    readonly isSelf: boolean;
+}
+/**
+ * A resolved reply context — produced by `resolveReply` on the decode path.
+ * `state:'resolved'` means the parent was found in local history and `quoteText`
+ * is the REAL parent text (spoof-proof). `state:'unavailable'` means the parent
+ * was not in local history; `quoteText` is the embedded preview body (may be null).
+ */
+interface ResolvedReply {
+    readonly parentClientMsgId: string;
+    readonly state: 'resolved' | 'unavailable';
+    readonly quoteSenderUserId: string;
+    readonly quoteText: string | null;
+    readonly quoteKind: string;
+}
+/** One message in a chat transcript. */
+interface ChatMessage {
+    /** Routing-key-free id: `<chat.id>#<serverSeq>`. */
+    readonly id: string;
+    readonly kind: ChatMessageKind;
+    readonly direction: MessageDirection;
+    /** The sending USER id, when resolved (nil for system frames or unknown sender). */
+    readonly senderUserId: string | null;
+    readonly text: string | null;
+    /** The server-minted per-group monotonic sequence (sort key + read cursor). */
+    readonly serverSeq: number;
+    /** When this device decoded (incoming) or sent (outgoing) the message. */
+    readonly sentAt: Date;
+    /** The client-minted idempotency id for this message (empty string for legacy/system). */
+    readonly clientMsgId: string;
+    /** Resolved reply context, or null if this is not a reply. */
+    readonly replyTo: ResolvedReply | null;
+}
+/** The receipt from a send — the server's monotonic sequence + accepted epoch. */
+interface SentReceipt {
+    readonly serverSeq: number;
+    readonly epoch: number;
+}
+/** Per-user comms privacy prefs (defaults both-true). */
+interface CommsPrefs {
+    readonly sharePresence: boolean;
+    readonly shareReceipts: boolean;
+}
+/** A presence snapshot for a user in a chat (60s TTL, device-union). */
+interface PresenceState {
+    readonly userId: string;
+    readonly isOnline: boolean;
+    readonly lastSeenAt: Date | null;
+}
+/** An unsubscribe handle (matches the flags/realtime/auth pattern). */
+type Unsubscribe$1 = () => void;
+
+/** A resolved group as the SDK tracks it. `name` is always null on web (no exporter). */
+interface MessagingGroup {
+    displayId: string;
+    rfcGroupId: string;
+    currentEpoch: number;
+    ownerUserId: string | null;
+    directKey: string | null;
+    name: string | null;
+}
+interface QuotePreview {
+    kind: string;
+    author_user_id: string;
+    body?: string;
+    body_truncated: boolean;
+}
+interface ReplyRef {
+    v: number;
+    client_msg_id: string;
+    preview?: QuotePreview;
+}
+
+/** A decoded incoming message handed to chat listeners. */
+interface IncomingMessage {
+    kind: 'application' | 'commit' | 'proposal' | 'welcome';
+    group: MessagingGroup;
+    text: string | null;
+    senderDeviceId: string | null;
+    epoch: number;
+    serverSeq: number;
+    receivedAt: Date;
+    /** The client-minted idempotency id from the decoded envelope (empty string for legacy/system). */
+    clientMsgId: string;
+    /** The decoded reply reference, if present in the envelope. */
+    replyRef: ReplyRef | null;
+}
+
+/** The intended participants of a draft chat (held until the first send). */
+interface ChatDraft {
+    mode: {
+        kind: 'direct';
+        peerUserId: string;
+    } | {
+        kind: 'group';
+        members: string[];
+    };
+    /** The reserved local id a draft shows before it materializes. */
+    reservedId: string;
+}
+/** The seam the Chat talks to for the work needing the resolved machinery. */
+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<{
+        receipt: SentReceipt;
+        clientMsgId: string;
+    }>;
+    history(group: MessagingGroup, limit: number, before?: number): Promise<ChatMessage[]>;
+    members(group: MessagingGroup): Promise<ChatMember[]>;
+    addMember(group: MessagingGroup, userId: string): Promise<void>;
+    removeMember(group: MessagingGroup, userId: string): Promise<void>;
+    leave(group: MessagingGroup): Promise<void>;
+    registerActive(group: MessagingGroup): void;
+    setTyping(group: MessagingGroup, isTyping: boolean): void;
+    markRead(group: MessagingGroup, upToServerSeq: number): Promise<void>;
+    /** Subscribe live message + conv (presence/typing/read) for an active group. */
+    subscribeLive(group: MessagingGroup, chat: Chat): Unsubscribe$1;
+    /** Resolve a sender device id → its owning user id (for senderUserId). */
+    userIdForDevice(group: MessagingGroup, deviceId: string): Promise<string | null>;
+}
+declare class Chat {
+    /** Stable, URL/log-safe id (the grp_ display id once active; a reserved local id while draft). */
+    id: string;
+    readonly kind: ChatKind;
+    private _state;
+    private _group;
+    private _draft;
+    private readonly backend;
+    private messageList;
+    private memberCache;
+    private typingList;
+    private presenceStates;
+    private readWatermark;
+    private titleOverride;
+    private readonly seenKeys;
+    /** Index: clientMsgId → { text, senderUserId } for resolveReply lookups. */
+    private readonly byClientMsgId;
+    private loadedEarliestSeq;
+    private historyLoaded;
+    private wired;
+    private liveUnsub;
+    private readonly listeners;
+    /** @internal — obtain via pb.messaging.directChat / groupChat / chat(id). */
+    constructor(args: {
+        group: MessagingGroup;
+        kind: ChatKind;
+        backend: ChatBackend;
+    } | {
+        draft: ChatDraft;
+        kind: ChatKind;
+        backend: ChatBackend;
+    });
+    /** Subscribe to any change in this chat (messages/members/typing/state). */
+    onChange(cb: () => void): Unsubscribe$1;
+    private emit;
+    get state(): ChatState;
+    get isDirect(): boolean;
+    get messages(): readonly ChatMessage[];
+    get members(): readonly ChatMember[];
+    get typing(): readonly ChatMember[];
+    get lastMessage(): ChatMessage | null;
+    get unreadCount(): number;
+    get title(): string;
+    presence(userId: string): PresenceState | null;
+    private ensureWired;
+    private hydrateHistory;
+    private mergeHistory;
+    /** @internal — called by the backend's live subscription. */
+    ingestLive(incoming: IncomingMessage): Promise<void>;
+    /** @internal — called by the backend's conv subscription. */
+    applyConv(event: string, payload: Record<string, unknown>): void;
+    private kindOf;
+    private internalKey;
+    private publicId;
+    /** Page older messages in. Returns how many were prepended. */
+    loadEarlier(limit?: number): Promise<number>;
+    private refreshMembers;
+    private seedMembersFromGroup;
+    private seedDraftMembers;
+    send(text: string, opts?: {
+        replyTo?: ChatMessage;
+    }): Promise<SentReceipt>;
+    private appendOwnSend;
+    private materializeIfNeeded;
+    addMemberUser(userId: string): Promise<void>;
+    removeMemberUser(userId: string): Promise<void>;
+    leave(): Promise<void>;
+    setTyping(isTyping: boolean): void;
+    markRead(message: ChatMessage): Promise<void>;
+}
+
+declare class PalbeMessaging {
+    private readonly coordinator;
+    constructor(rt: PalbeRuntime);
+    /**
+     * Warm messaging at sign-in (optional). Enrolls this device + starts the live
+     * delivery source so incoming DMs/Welcomes drain before the chat list opens.
+     * Never REQUIRED — any chat op self-enrolls. Idempotent.
+     */
+    start(): Promise<void>;
+    /**
+     * Open the ONE direct chat with `userId`. INSTANT + LOCAL — no network, nothing
+     * created yet. Returns a draft `Chat` to show immediately; the server group +
+     * MLS material materialize LAZILY on the first `chat.send`. Idempotent + stable:
+     * the same two users always resolve to the SAME Chat.
+     */
+    directChat(userId: string): Chat;
+    /**
+     * Open a multi-party group chat. LOCAL + LAZY like `directChat`: pick the
+     * members, get a draft Chat, the group is created on the FIRST `chat.send`.
+     */
+    groupChat(opts?: {
+        members?: string[];
+    }): Chat;
+    /** Look up a chat by id (e.g. from a push payload / deep link). null if unknown. */
+    chat(id: string): Chat | null;
+    /** The observable chat list (DMs + groups, active only). Read it after an
+     * `onChatsChange` subscription to render the inbox. */
+    get chats(): readonly Chat[];
+    /** Subscribe to chat-list changes (a chat added/removed/hydrated). */
+    onChatsChange(cb: () => void): Unsubscribe$1;
+}
+
 /**
  * The connection state of the shared realtime WebSocket (iOS enum parity), plus
  * `'error'` — surfaced when a channel could not be recovered after a
@@ -702,6 +1046,8 @@ interface PalbeRuntime {
     flags: PalbeFlags;
     realtime: PalbeRealtime;
     analytics: PalbeAnalytics;
+    calls: PalbeCalls;
+    messaging: PalbeMessaging;
     storage: SessionStorageAdapter;
     /**
      * Destroy the realtime facade if it was already constructed (no-op otherwise).
@@ -953,4 +1299,4 @@ declare class PalbeAnalytics {
     private post;
 }
 
-export { type AnalyticsProperties as A, type FlagsView as F, type MagicLinkResult as M, type OAuthExchangeResult as O, PalbeAnalytics as P, RealtimeChannel as R, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, PalbeAuth as e, type PalbeConfig as f, PalbeFlags as g, type PalbeOAuthConfig as h, PalbeRealtime as i, type RealtimeConnectionState as j, type RealtimeHandler as k, type RealtimePayload as l, type RealtimeStatus as m, type RealtimeStatusSnapshot as n, type RealtimeSubscription as o, type PalbeRuntime as p, buildRuntime as q };
+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 PalbeRuntime as J, buildRuntime as K, 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 };