@openmarket/rooms-client 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,421 @@
+import { type RoomAccessMode, type RoomAttachment, type RoomAuditLogPayload, type RoomAuthSuccessPayload, type RoomBackfillPayload, type RoomDmHistoryResultPayload, type RoomDmMessagePayload, type RoomDmOpenedPayload, type RoomFriendPresence, type RoomInvitedPayload, type RoomLedgerEntry, type RoomMemberRemovedPayload, type RoomMemberRoleChangedPayload, type RoomMeta, type RoomPinsPayload, type RoomPresencePayload, type RoomReactorsPayload, type RoomReadStatePayload, type RoomReportedPayload, type RoomRole, type RoomSearchResultsPayload, type RoomSearchScope, type RoomSpace, type RoomThreadPayload, type RoomTopic, type RoomTopicAttention, type RoomTopicResultPayload, type RoomTopicsResultPayload, type RoomUserStatus, type RoomWhoPayload } from "./types.js";
+import { type RoomWebSocketCtor, RoomWsClient } from "./ws-client.js";
+export interface RoomClientConfig {
+    url: string;
+    apiKey: string;
+    /** Explicit chat REST base (e.g. a same-origin proxy path). When absent,
+     *  the base is derived from `url` / env, which assumes the relay's own
+     *  host layout. */
+    apiUrl?: string;
+    refreshAuthToken?: () => Promise<string>;
+    webSocketCtor?: RoomWebSocketCtor;
+    timeoutMs?: number;
+    /** Sidekick sessions authenticate with this agent identity assertion;
+     *  ghost and plain user sessions leave it unset. See RoomWsClientOptions. */
+    agentIdentity?: {
+        name: string;
+    };
+    /** Reconnect herd jitter override; tests pin 0 for deterministic timing. */
+    reconnectHerdJitterMs?: number;
+}
+export interface RoomJoinOptions {
+    room: string;
+    workspaceId?: string;
+    code?: string;
+    sinceSeq?: number;
+    limit?: number;
+    ackOnJoin?: boolean;
+    /** Optional one-line reason broadcast as a system join note (server-side).
+     *  Omitted ⇒ no field sent ⇒ no announce. Additive; older servers ignore it. */
+    reason?: string;
+    /** Optional telemetry metadata for the surface that caused the join. */
+    source?: string;
+    hook?: string;
+    suggestionId?: string;
+    /** Internal: set by rejoinRoomOnClient so a reconnect re-JOIN never
+     *  consumes a rendered-suggestion attribution — a rejoin of an empty room
+     *  carries no sinceSeq and would otherwise look like an initial join. */
+    isRejoin?: boolean;
+}
+export interface RoomSayOptions extends RoomJoinOptions {
+    text?: string;
+    attachments?: RoomAttachment[];
+    inReplyTo?: number;
+    /** Post directly into a topic; the room's linear stream is unaffected. */
+    topicId?: string;
+    clientMsgId?: string;
+}
+export interface RoomPeekOptions {
+    room: string;
+    beforeSeq?: number;
+    sinceSeq?: number;
+    atMs?: number;
+    limit?: number;
+}
+export interface RoomListResult {
+    auth: RoomAuthSuccessPayload;
+    rooms: RoomMeta[];
+}
+export interface RoomListRequest {
+    query?: string | undefined;
+    scope?: RoomSearchScope | undefined;
+    category?: string[] | undefined;
+    tag?: string[] | undefined;
+    kind?: string[] | undefined;
+    entity?: string[] | undefined;
+    symbol?: string[] | undefined;
+    spaceId?: string[] | undefined;
+    hot?: boolean | undefined;
+    includeHeat?: boolean | undefined;
+    createdByMe?: boolean | undefined;
+    includeArchived?: boolean | undefined;
+    limit?: number | undefined;
+}
+export interface RoomCreateRequest {
+    name: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    access?: RoomAccessMode | undefined;
+    maxMembers?: number | undefined;
+    category?: string | undefined;
+    sortOrder?: number | undefined;
+    spaceId?: string | undefined;
+    postingRoles?: RoomRole[] | undefined;
+    tags?: string[] | undefined;
+}
+export interface RoomCreateResult {
+    auth: RoomAuthSuccessPayload;
+    room: RoomMeta;
+    joinCode?: string | undefined;
+}
+export interface RoomInviteRequest {
+    room: string;
+    username?: string | undefined;
+    userId?: string | undefined;
+}
+export interface RoomInviteResult {
+    auth: RoomAuthSuccessPayload;
+    invite: RoomInvitedPayload;
+}
+export interface RoomRemoveMemberRequest {
+    room: string;
+    username?: string | undefined;
+    userId?: string | undefined;
+    reason?: string | undefined;
+}
+export interface RoomRemoveMemberResult {
+    auth: RoomAuthSuccessPayload;
+    removal: RoomMemberRemovedPayload;
+}
+export interface RoomReportRequest {
+    room: string;
+    seq?: number | undefined;
+    targetUserId?: string | undefined;
+    reason: string;
+}
+export interface RoomReportResult {
+    auth: RoomAuthSuccessPayload;
+    report: RoomReportedPayload;
+}
+export interface RoomModerationMemberRequest {
+    room: string;
+    username?: string | undefined;
+    userId?: string | undefined;
+    reason?: string | undefined;
+}
+export interface RoomMuteRequest extends RoomModerationMemberRequest {
+    until: string | number | Date;
+}
+export interface RoomMuteResult {
+    auth: RoomAuthSuccessPayload;
+    mute: {
+        requestId?: string;
+        room: string;
+        mutedUserId: string;
+        mutedHandle: string;
+        until: string | number | Date;
+    };
+}
+export interface RoomBanResult {
+    auth: RoomAuthSuccessPayload;
+    ban: {
+        requestId?: string;
+        room: string;
+        bannedUserId: string;
+        bannedHandle: string;
+    };
+}
+export interface RoomRoleChangeRequest extends RoomModerationMemberRequest {
+    role: RoomRole;
+}
+export interface RoomRoleChangeResult {
+    auth: RoomAuthSuccessPayload;
+    roleChange: RoomMemberRoleChangedPayload;
+}
+export interface RoomSetReadOnlyRequest {
+    room: string;
+    postingRoles: RoomRole[];
+    reason?: string | undefined;
+}
+export interface RoomSetReadOnlyResult {
+    auth: RoomAuthSuccessPayload;
+    room: string;
+    postingRoles: RoomRole[];
+}
+export interface RoomAuditLogRequest {
+    room: string;
+    limit?: number | undefined;
+}
+export interface RoomAuditLogResult {
+    auth: RoomAuthSuccessPayload;
+    audit: RoomAuditLogPayload;
+}
+export interface RoomSpacesResult {
+    auth: RoomAuthSuccessPayload;
+    spaces: RoomSpace[];
+}
+export interface RoomJoinSpaceRequest {
+    spaceId: string;
+}
+export interface RoomJoinSpaceResult {
+    auth: RoomAuthSuccessPayload;
+    space: RoomSpace;
+}
+export interface RoomSayResult {
+    auth: RoomAuthSuccessPayload;
+    entry: RoomLedgerEntry;
+    clientMsgId: string;
+}
+export interface RoomJoinedSession {
+    auth: RoomAuthSuccessPayload;
+    backfill: RoomBackfillPayload;
+    client: RoomWsClient;
+}
+export interface RoomDmOpenRequest {
+    username: string;
+    limit?: number;
+    markRead?: boolean;
+}
+export interface RoomDmHistoryRequest {
+    username?: string;
+    conversationId?: string;
+    before?: number;
+    limit?: number;
+    markRead?: boolean;
+}
+export interface RoomDmSendRequest {
+    username?: string;
+    conversationId?: string;
+    content: string;
+    clientMsgId?: string;
+}
+export interface RoomThreadRequest {
+    room: string;
+    rootSeq: number;
+    beforeSeq?: number;
+    sinceSeq?: number;
+    limit?: number;
+}
+export interface RoomSearchEntriesRequest {
+    room: string;
+    query: string;
+    beforeSeq?: number;
+    sinceSeq?: number;
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+}
+export declare function resolveRoomsWsUrl(): string;
+export { workspaceRoomName } from "./names.js";
+export declare function listRooms(config: RoomClientConfig, request?: RoomListRequest): Promise<RoomListResult>;
+export declare function createRoom(config: RoomClientConfig, request: RoomCreateRequest): Promise<RoomCreateResult>;
+export declare function inviteRoom(config: RoomClientConfig, request: RoomInviteRequest): Promise<RoomInviteResult>;
+export declare function removeRoomMember(config: RoomClientConfig, request: RoomRemoveMemberRequest): Promise<RoomRemoveMemberResult>;
+export declare function reportRoomTarget(config: RoomClientConfig, request: RoomReportRequest): Promise<RoomReportResult>;
+export declare function muteRoomMember(config: RoomClientConfig, request: RoomMuteRequest): Promise<RoomMuteResult>;
+export declare function kickRoomMember(config: RoomClientConfig, request: RoomModerationMemberRequest): Promise<RoomRemoveMemberResult>;
+export declare function banRoomMember(config: RoomClientConfig, request: RoomModerationMemberRequest): Promise<RoomBanResult>;
+export declare function changeRoomMemberRole(config: RoomClientConfig, request: RoomRoleChangeRequest): Promise<RoomRoleChangeResult>;
+export declare function setRoomReadOnly(config: RoomClientConfig, request: RoomSetReadOnlyRequest): Promise<RoomSetReadOnlyResult>;
+export declare function requestRoomAuditLog(config: RoomClientConfig, request: RoomAuditLogRequest): Promise<RoomAuditLogResult>;
+export declare function listRoomSpaces(config: RoomClientConfig): Promise<RoomSpacesResult>;
+export declare function joinRoomSpace(config: RoomClientConfig, request: RoomJoinSpaceRequest): Promise<RoomJoinSpaceResult>;
+/** Paged WHO on an already-connected room client (member panel). */
+export declare function requestRoomWho(client: RoomWsClient, room: string, offset?: number, limit?: number): Promise<RoomWhoPayload>;
+export declare function whoRoom(config: RoomClientConfig, room: string): Promise<RoomPresencePayload>;
+/** The signed-in user's own room identity (userId / handle / username), learned
+ *  by opening and immediately closing a room connection. Used to attribute "my"
+ *  past messages when inferring a writing persona. */
+export declare function whoamiRoom(config: RoomClientConfig): Promise<RoomAuthSuccessPayload>;
+export declare function requestRoomFriends(client: RoomWsClient): Promise<RoomFriendPresence[]>;
+export declare function openRoomDmOnClient(client: RoomWsClient, request: RoomDmOpenRequest, timeoutMs?: number): Promise<RoomDmOpenedPayload>;
+export declare function requestRoomDmHistoryOnClient(client: RoomWsClient, request: RoomDmHistoryRequest, timeoutMs?: number): Promise<RoomDmHistoryResultPayload>;
+export declare function sendRoomDmOnClient(client: RoomWsClient, request: RoomDmSendRequest, timeoutMs?: number): Promise<RoomDmMessagePayload>;
+export declare function peekRoom(config: RoomClientConfig, options: RoomPeekOptions): Promise<RoomBackfillPayload>;
+export declare function sayRoom(config: RoomClientConfig, options: RoomSayOptions): Promise<RoomSayResult>;
+export declare function joinRoom(config: RoomClientConfig, options: RoomJoinOptions): Promise<RoomJoinedSession>;
+/** Re-join a room on an already-connected client (used after a reconnect). */
+export declare function rejoinRoomOnClient(client: RoomWsClient, options: RoomJoinOptions): Promise<RoomBackfillPayload>;
+export declare function attachRejoinOnReconnect(client: RoomWsClient, options: RoomJoinOptions, latestSeq: () => number | undefined, onRejoined?: (backfill: RoomBackfillPayload) => void, onError?: (err: unknown) => void): () => void;
+export declare function postRoomMessage(client: RoomWsClient, room: string, text: string, inReplyTo?: number, attachments?: RoomAttachment[], topicId?: string): string;
+export declare function sendRoomTyping(client: RoomWsClient, room: string, state: "start" | "stop"): void;
+export declare function sendRoomStatus(client: RoomWsClient, status: RoomUserStatus, statusText?: string | null): void;
+/**
+ * Fetch a joined room's meta (title, access, postingRoles, viewerRole) over
+ * the live socket via a scoped SEARCH. Returns null on timeout/no match so
+ * callers can degrade to role hints from presence.
+ */
+export declare function requestRoomMeta(client: RoomWsClient, room: string, timeoutMs?: number): Promise<RoomMeta | null>;
+export declare function reactRoomEntry(client: RoomWsClient, room: string, seq: number, emoji: string, op: "add" | "remove"): void;
+export declare function editRoomEntry(client: RoomWsClient, room: string, seq: number, text: string): void;
+export declare function deleteRoomEntry(client: RoomWsClient, room: string, seq: number): Promise<RoomLedgerEntry>;
+export declare function requestRoomThread(client: RoomWsClient, request: RoomThreadRequest): Promise<RoomThreadPayload>;
+export declare function requestRoomPins(client: RoomWsClient, room: string, limit?: number): Promise<RoomPinsPayload>;
+export declare function pinRoomEntry(client: RoomWsClient, room: string, seq: number): Promise<RoomLedgerEntry>;
+export declare function unpinRoomEntry(client: RoomWsClient, room: string, seq: number): Promise<RoomLedgerEntry>;
+/** Who reacted (live socket): lazy read for reaction-chip tooltips. */
+export declare function requestRoomReactors(client: RoomWsClient, request: {
+    room: string;
+    seq: number;
+    emoji?: string;
+    limit?: number;
+}): Promise<RoomReactorsPayload>;
+/** Set my presence status (one-shot, agent-verb transport). The relay
+ *  persists it durably; a one-shot socket has no joined rooms, so live
+ *  rosters pick the change up from the store (the TUI/GUI send STATUS on
+ *  their live connection instead, which also broadcasts PRESENCE_DELTA). */
+export declare function setRoomStatusOnce(config: RoomClientConfig, status: RoomUserStatus, statusText?: string | null): Promise<void>;
+/** Add/remove one reaction (one-shot). Returns the updated entry. */
+export declare function reactRoom(config: RoomClientConfig, options: {
+    room: string;
+    seq: number;
+    emoji: string;
+    op: "add" | "remove";
+}): Promise<RoomLedgerEntry>;
+/** Edit own message (one-shot). Returns the updated entry. */
+export declare function editRoomMessage(config: RoomClientConfig, options: {
+    room: string;
+    seq: number;
+    text: string;
+}): Promise<RoomLedgerEntry>;
+/** Delete a message (own, or moderator delete-any; one-shot). */
+export declare function deleteRoomMessage(config: RoomClientConfig, options: {
+    room: string;
+    seq: number;
+}): Promise<RoomLedgerEntry>;
+/** Pin or unpin a message (one-shot). Returns the updated entry. */
+export declare function pinRoomMessage(config: RoomClientConfig, options: {
+    room: string;
+    seq: number;
+    op: "pin" | "unpin";
+}): Promise<RoomLedgerEntry>;
+/** List pinned messages (one-shot). */
+export declare function listRoomPinsOnce(config: RoomClientConfig, options: {
+    room: string;
+    limit?: number;
+}): Promise<RoomPinsPayload>;
+/** Fetch one reply thread (one-shot). */
+export declare function getRoomThreadOnce(config: RoomClientConfig, options: {
+    room: string;
+    rootSeq: number;
+    limit?: number;
+}): Promise<RoomThreadPayload>;
+/** Who reacted (one-shot). */
+export declare function getRoomReactorsOnce(config: RoomClientConfig, options: {
+    room: string;
+    seq: number;
+    emoji?: string;
+    limit?: number;
+}): Promise<RoomReactorsPayload>;
+/** Fetch one entry by seq (one-shot; HISTORY page of one). */
+export declare function getRoomMessageOnce(config: RoomClientConfig, options: {
+    room: string;
+    seq: number;
+}): Promise<RoomLedgerEntry | null>;
+export declare function requestRoomReadState(client: RoomWsClient, rooms: string[], timeoutMs?: number): Promise<RoomReadStatePayload>;
+export declare function searchRoomEntries(client: RoomWsClient, request: RoomSearchEntriesRequest): Promise<RoomSearchResultsPayload>;
+/** One-shot variant for headless surfaces (actions): connect, join, search,
+ *  close. The relay gates SEARCH_ENTRIES on per-socket room participation
+ *  (isInRoom checks this very WebSocket), so a minimal JOIN is required
+ *  first; the brief presence blip matches getRoomMessageOnce. */
+export declare function searchRoomEntriesOnce(config: RoomClientConfig, request: RoomSearchEntriesRequest): Promise<RoomSearchResultsPayload>;
+export interface RoomHistoryRequest {
+    beforeSeq?: number;
+    sinceSeq?: number;
+    atMs?: number;
+    limit: number;
+}
+export declare function requestRoomHistory(client: RoomWsClient, room: string, beforeSeq: number, limit: number): Promise<RoomBackfillPayload>;
+export declare function requestRoomHistoryPage(client: RoomWsClient, room: string, request: RoomHistoryRequest): Promise<RoomBackfillPayload>;
+/** `topicId` acks a per-topic cursor; the room-wide cursor is separate. */
+export declare function ackRoom(client: RoomWsClient, room: string, seq: number, topicId?: string): void;
+export declare class RoomAckDebouncer {
+    private readonly client;
+    private readonly delayMs;
+    private readonly pending;
+    private timer;
+    constructor(client: RoomWsClient, delayMs?: number);
+    /** `topicId` batches a per-topic view-time cursor; omit for the room-wide one. */
+    schedule(room: string, seq: number, topicId?: string): void;
+    flush(): void;
+    close(): void;
+}
+export interface RoomTopicCreateRequest {
+    room: string;
+    name: string;
+}
+export interface RoomTopicListRequest {
+    room: string;
+    includeResolved?: boolean | undefined;
+}
+export interface RoomTopicRenameRequest {
+    topicId: string;
+    name: string;
+}
+export interface RoomTopicMoveRequest {
+    topicId: string;
+    seqs: number[];
+    toTopicId: string;
+}
+export interface RoomTopicMergeRequest {
+    topicId: string;
+    intoTopicId: string;
+}
+export interface RoomTopicResolveRequest {
+    topicId: string;
+    /** Defaults to true (mark resolved) when omitted; false reopens it. */
+    resolved?: boolean | undefined;
+}
+export interface RoomTopicSetAttentionRequest {
+    topicId: string;
+    attention: RoomTopicAttention;
+}
+export interface RoomTopicResult {
+    auth: RoomAuthSuccessPayload;
+    topic: RoomTopic;
+}
+export interface RoomTopicsResult {
+    auth: RoomAuthSuccessPayload;
+    topics: RoomTopic[];
+}
+export declare function createRoomTopic(config: RoomClientConfig, request: RoomTopicCreateRequest): Promise<RoomTopicResult>;
+export declare function listRoomTopics(config: RoomClientConfig, request: RoomTopicListRequest): Promise<RoomTopicsResult>;
+export declare function renameRoomTopic(config: RoomClientConfig, request: RoomTopicRenameRequest): Promise<RoomTopicResult>;
+export declare function moveRoomTopicMessages(config: RoomClientConfig, request: RoomTopicMoveRequest): Promise<RoomTopicResult>;
+export declare function mergeRoomTopics(config: RoomClientConfig, request: RoomTopicMergeRequest): Promise<RoomTopicResult>;
+export declare function resolveRoomTopic(config: RoomClientConfig, request: RoomTopicResolveRequest): Promise<RoomTopicResult>;
+export declare function setRoomTopicAttention(config: RoomClientConfig, request: RoomTopicSetAttentionRequest): Promise<RoomTopicResult>;
+export interface RoomTopicListStateRequest extends RoomTopicListRequest {
+    withState?: boolean | undefined;
+}
+export declare function requestRoomTopicsOnClient(client: RoomWsClient, request: RoomTopicListStateRequest): Promise<RoomTopicsResultPayload>;
+export declare function createRoomTopicOnClient(client: RoomWsClient, request: RoomTopicCreateRequest): Promise<RoomTopicResultPayload>;
+export declare function renameRoomTopicOnClient(client: RoomWsClient, request: RoomTopicRenameRequest): Promise<RoomTopicResultPayload>;
+export declare function setRoomTopicAttentionOnClient(client: RoomWsClient, request: RoomTopicSetAttentionRequest): Promise<RoomTopicResultPayload>;
+export declare function resolveRoomTopicOnClient(client: RoomWsClient, request: RoomTopicResolveRequest): Promise<RoomTopicResultPayload>;
+export declare function resolveRoomChatApiUrl(config?: {
+    url?: string;
+    apiUrl?: string;
+}): string;
+export declare function normalizePresence(payload: RoomPresencePayload): RoomPresencePayload;
+export declare function presenceFromWho(payload: RoomWhoPayload): RoomPresencePayload;