@openmarket/rooms-client 0.6.0 → 0.7.0

package/dist/social-client.js

@@ -419,10 +419,29 @@ export async function addSpaceMember(config, spaceId, input) {
     const result = await socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/members`, { method: "POST", body: input });
     return result.member;
 }
-/** Create (or refresh) a pending invitation. Membership needs their accept. */
+/** Create (or refresh) a pending invitation. Membership needs their accept.
+ *  `expiresAt` (ISO date, future, at most 30 days out) puts a deadline on
+ *  it; re-inviting without one clears any previous deadline. Fail-closed on
+ *  servers older than 0.6.0: they persist the invite but drop the deadline,
+ *  so a deadline the echo omits revokes the invite and throws. */
 export async function createSpaceInvite(config, spaceId, input) {
     const result = await socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/invites`, { method: "POST", body: input });
-    return result.invite;
+    const invite = result.invite;
+    // Presence check, not equality: servers may normalize the ISO string.
+    // declineSpaceInvite doubles as the manager-side revoke (the store
+    // deletes the row for invitee OR manager), so the inviter can retract
+    // the invite it just created.
+    if (input.expiresAt !== undefined && invite && typeof invite.expiresAt !== "string") {
+        const details = { spaceId, inviteId: invite.inviteId, requestedExpiresAt: input.expiresAt };
+        try {
+            await declineSpaceInvite(config, invite.inviteId);
+        }
+        catch (revokeError) {
+            throw new RoomSocialError("Server does not support invite expiry, and revoking the invite failed: a standing (never-expiring) invite may be live", 502, { ...details, revokeError: revokeError.message });
+        }
+        throw new RoomSocialError("Server does not support invite expiry; the standing invite was revoked", 502, details);
+    }
+    return invite;
 }
 /** The caller's own pending invitations. */
 export async function listMySpaceInvites(config) {
@@ -443,11 +462,46 @@ export async function declineSpaceInvite(config, inviteId) {
         method: "POST",
     });
 }
-/** Mint (or rotate) the shareable join code; plaintext comes back once. */
-export async function setSpaceJoinCode(config, spaceId) {
-    return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/join-code`, {
+/** Mint (or rotate) the shareable join code; plaintext comes back once.
+ *  Optional caps: `expiresAt` (ISO date, future, at most 30 days out) and
+ *  `maxUses` (1..10000). Rotation is a fresh grant: the new code starts at
+ *  zero uses and takes exactly the caps given here (omitted caps clear the
+ *  previous ones). Servers older than 0.6.0 echo neither cap field; they
+ *  mint the code but drop the caps, so a requested cap the echo omits
+ *  fail-closes: the fresh code is revoked and the call throws rather than
+ *  hand back a live UNLIMITED code the caller believes capped. */
+export async function setSpaceJoinCode(config, spaceId, options = {}) {
+    const body = {};
+    if (options.expiresAt !== undefined)
+        body.expiresAt = options.expiresAt;
+    if (options.maxUses !== undefined)
+        body.maxUses = options.maxUses;
+    const result = await socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/join-code`, {
         method: "PUT",
+        // Capless mints keep the historical bodiless PUT on the wire.
+        ...(Object.keys(body).length > 0 ? { body } : {}),
     });
+    // Presence check for expiresAt (servers may normalize the ISO string),
+    // numeric equality for maxUses.
+    const droppedExpiry = body.expiresAt !== undefined && typeof result.expiresAt !== "string";
+    const droppedMaxUses = body.maxUses !== undefined && result.maxUses !== body.maxUses;
+    if (droppedExpiry || droppedMaxUses) {
+        // Details deliberately omit the plaintext code: RoomSocialError.details
+        // ends up in logs.
+        const details = {
+            spaceId,
+            requested: body,
+            echoed: { expiresAt: result.expiresAt ?? null, maxUses: result.maxUses ?? null },
+        };
+        try {
+            await clearSpaceJoinCode(config, spaceId);
+        }
+        catch (revokeError) {
+            throw new RoomSocialError("Server does not support join-code caps, and revoking the code failed: an uncapped join code may be live", 502, { ...details, revokeError: revokeError.message });
+        }
+        throw new RoomSocialError("Server does not support join-code caps; the uncapped code was revoked", 502, details);
+    }
+    return result;
 }
 export async function clearSpaceJoinCode(config, spaceId) {
     return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/join-code`, {
@@ -651,6 +705,288 @@ export async function listRoomNotifications(config, options = {}) {
         lastCursorId: result.lastCursorId ?? null,
     };
 }
+/**
+ * Mark a room unread from `seq` (Discord-style): the room-wide read cursor
+ * drops to seq - 1 (server-clamped at 0) so the unread divider and pill
+ * return. The one sanctioned cursor-regression path; mention rows an
+ * earlier ack swept stay swept, and nothing is re-notified.
+ */
+export async function markRoomUnread(config, room, seq) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/read/unread`, { method: "POST", body: { seq } });
+    return { success: result.success === true };
+}
+/**
+ * Set the caller's room-level attention over REST, the path that carries
+ * mute-with-duration: `untilMs` (epoch ms, valid only with 'mute') stamps
+ * the expiry that read state later surfaces as `muteUntil`; the mute lapses
+ * server-side and reads as 'default' afterwards. Every write settles the
+ * expiry, so follow/default (and a plain permanent mute) clear a previous
+ * one. The pinned ROOM_SET_ATTENTION frame (setRoomAttentionOnClient)
+ * predates `untilMs` and stays the live-session path for permanent
+ * postures; servers older than mute-with-duration strip the field and land
+ * the mute permanent, so a requested `untilMs` the echo omits fail-closes:
+ * the attention is reset and the call throws rather than leave an
+ * unbounded mute the caller believes timed. Echoes the persisted
+ * attention; `muteUntil` is the ISO expiry, null when none stands.
+ */
+export async function setRoomAttentionRest(config, room, attention, options = {}) {
+    const body = { attention };
+    if (options.untilMs !== undefined)
+        body.untilMs = options.untilMs;
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/attention`, {
+        method: "POST",
+        body,
+    });
+    const muteUntil = typeof result.muteUntil === "string" ? result.muteUntil : null;
+    if (options.untilMs !== undefined && muteUntil === null) {
+        // The undo cannot know the caller's prior attention, so it deliberately
+        // lands 'default' (the same neutral a lapsed timed mute reads as, see
+        // resolveTopicAttention) rather than leave the unbounded mute standing.
+        try {
+            await setRoomAttentionRest(config, room, "default");
+        }
+        catch (undoError) {
+            throw new RoomSocialError("Server does not support timed mutes, and undoing the mute failed: a permanent mute may be standing", 502, { room, undoError: undoError.message });
+        }
+        throw new RoomSocialError("Server does not support timed mutes; the permanent mute was undone (attention is now 'default')", 502, { room });
+    }
+    return { attention: result.attention ?? attention, muteUntil };
+}
+/**
+ * Save a message for later (personal, per-user; nothing broadcasts).
+ * Idempotent: re-saving an already bookmarked event echoes the standing
+ * row with its original createdAt.
+ */
+export async function addRoomBookmark(config, room, seq) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/bookmarks`, { method: "POST", body: { seq } });
+    if (!result.bookmark) {
+        throw new RoomSocialError("Bookmark save returned no row", 502, result);
+    }
+    return result.bookmark;
+}
+/** Remove a bookmark. Idempotent, and deliberately NOT gated on room
+ *  readability: cleanup keeps working after lost membership or a deleted
+ *  target (`removed` is false when no row stood). */
+/** Sequence numbers ride URL paths; a JavaScript caller can pass any value
+ *  despite the type annotation, and fetch normalizes dot segments, so a seq
+ *  of ".." would rewrite a bookmark DELETE onto the ROOM route (archive).
+ *  Runtime-require a nonnegative safe integer before interpolating. */
+function requireSeq(seq) {
+    if (!Number.isSafeInteger(seq) || seq < 0) {
+        throw new RoomSocialError("Invalid sequence number", 400, { seq: String(seq) });
+    }
+    return seq;
+}
+export async function removeRoomBookmark(config, room, seq) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/bookmarks/${requireSeq(seq)}`, { method: "DELETE" });
+    return { removed: result.removed === true };
+}
+/**
+ * The caller's bookmarks across every room (GET /users/bookmarks), newest
+ * first with the notification inbox's composite cursor: pass a page's
+ * lastCursor and lastCursorId back TOGETHER for the next page. Rows in
+ * rooms the caller can no longer read are subtracted server-side.
+ */
+export async function listUserBookmarks(config, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.cursor !== undefined)
+        params.set("cursor", options.cursor);
+    if (options.cursorId !== undefined)
+        params.set("cursorId", options.cursorId);
+    const init = {};
+    if (options.signal)
+        init.signal = options.signal;
+    const result = await socialRequest(config, `/users/bookmarks${params.size ? `?${params.toString()}` : ""}`, init);
+    return {
+        bookmarks: result.bookmarks ?? [],
+        hasMore: result.hasMore ?? false,
+        lastCursor: result.lastCursor ?? null,
+        lastCursorId: result.lastCursorId ?? null,
+        total: result.total ?? 0,
+    };
+}
+/**
+ * The caller's user-block list (GET /users/blocks), newest first with the
+ * same composite-cursor paging as the notification inbox. Blocks are
+ * directional and the blocker is always the verified caller.
+ */
+export async function getUserBlocks(config, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.cursor !== undefined)
+        params.set("cursor", options.cursor);
+    if (options.cursorId !== undefined)
+        params.set("cursorId", options.cursorId);
+    const init = {};
+    if (options.signal)
+        init.signal = options.signal;
+    const result = await socialRequest(config, `/users/blocks${params.size ? `?${params.toString()}` : ""}`, init);
+    return {
+        blocks: result.blocks ?? [],
+        hasMore: result.hasMore ?? false,
+        lastCursor: result.lastCursor ?? null,
+        lastCursorId: result.lastCursorId ?? null,
+    };
+}
+/** Path-safety guard for block-target ids, NOT a format guard: the server
+ *  accepts any trimmed non-empty id up to 128 chars (legacy and agent
+ *  identities are not ObjectIds), so only the traversal class is refused
+ *  here: empty ids and pure dot segments, which encodeURIComponent leaves
+ *  alone and fetch would normalize onto /users/ itself. Everything else
+ *  rides percent-encoded. */
+function requireBlockUserId(userId) {
+    const trimmed = String(userId).trim();
+    if (trimmed === "" || trimmed === "." || trimmed === ".." || trimmed.length > 128) {
+        throw new RoomSocialError("Invalid user id", 400, { userId: String(userId) });
+    }
+    return trimmed;
+}
+/** Block a user by userId (PUT, idempotent: re-blocking echoes the standing
+ *  row with its original createdAt). Server-enforced effects: DM doors shut
+ *  both directions, friend requests refuse, and the blocked sender produces
+ *  no notifications for the caller. Room visibility is unchanged. */
+export async function blockUser(config, userId) {
+    const result = await socialRequest(config, `/users/blocks/${encodeURIComponent(requireBlockUserId(userId))}`, { method: "PUT" });
+    if (!result.block) {
+        throw new RoomSocialError("Block returned no row", 502, result);
+    }
+    return result.block;
+}
+/** Unblock a user (idempotent: unblocking a non-blocked user is a no-op). */
+export async function unblockUser(config, userId) {
+    const result = await socialRequest(config, `/users/blocks/${encodeURIComponent(requireBlockUserId(userId))}`, { method: "DELETE" });
+    return { success: result.success === true };
+}
+/**
+ * Post a poll message. There is no separate create route and no WS input
+ * path (the relay's post frame carries text only): a poll rides the normal
+ * REST append as the strict body's `poll` block. `options` are option TEXT
+ * (2..10 entries; ids are minted server-side) and `closesAt` is an ISO
+ * deadline that must sit in the future. `text` is the optional caption;
+ * absent is fine, the poll IS the content. Echoes the created store event
+ * row with its counts-only summary; the room hears the same message
+ * through the ordinary live echo. Additive (0.6.0 servers): older stores
+ * reject the unknown block.
+ */
+export async function createRoomPoll(config, room, input) {
+    const poll = {
+        question: input.question,
+        options: input.options,
+    };
+    if (input.multi !== undefined)
+        poll.multi = input.multi;
+    if (input.closesAt !== undefined)
+        poll.closesAt = input.closesAt;
+    const body = {
+        roomId: cleanRoomId(room),
+        poll,
+    };
+    if (input.text !== undefined)
+        body.text = input.text;
+    if (input.workspaceId !== undefined)
+        body.workspaceId = input.workspaceId;
+    if (input.topicId !== undefined)
+        body.topicId = input.topicId;
+    if (input.replyToSeq !== undefined)
+        body.replyToSeq = input.replyToSeq;
+    if (input.clientMsgId !== undefined)
+        body.clientMsgId = input.clientMsgId;
+    const result = await socialRequest(config, "/rooms/events", { method: "POST", body });
+    if (!result.event) {
+        throw new RoomSocialError("Poll create returned no event", 502, result);
+    }
+    return result.event;
+}
+/**
+ * Vote on a poll (the poll is keyed by its carrying message's seq). Echoes
+ * the store's public event row (RoomRestEvent, not the relay's mapped
+ * ledger entry) with the refreshed counts-only summary; the room hears the
+ * same update over ENTRY_UPDATED. Single-choice polls replace the caller's
+ * previous ballot; multi-choice polls union into it.
+ */
+export async function voteRoomPoll(config, room, seq, optionIds) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/vote`, { method: "POST", body: { optionIds } });
+    if (!result.event) {
+        throw new RoomSocialError("Poll vote returned no event", 502, result);
+    }
+    return result.event;
+}
+/** Clear the caller's vote. Echoes the refreshed store event row. */
+export async function unvoteRoomPoll(config, room, seq) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/vote`, { method: "DELETE" });
+    if (!result.event) {
+        throw new RoomSocialError("Poll unvote returned no event", 502, result);
+    }
+    return result.event;
+}
+/** Close a poll (idempotent on an already-closed poll). Echoes the store
+ *  event row with `poll.closed` set. */
+export async function closeRoomPoll(config, room, seq) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/close`, { method: "POST" });
+    if (!result.event) {
+        throw new RoomSocialError("Poll close returned no event", 502, result);
+    }
+    return result.event;
+}
+/** Edit a poll's question/options (author-only, and locked once any vote
+ *  exists or the poll closes; at least one field required). Options are
+ *  full replacement TEXT, like creation. */
+/** Purge an event's frozen unfurl cards without editing or deleting the
+ *  message. Author or a delete-any moderation power; the store unsets the
+ *  cards, schedules thumbnail cleanup, and returns the mutated event for
+ *  ENTRY_UPDATED fan-out. An edit that removes a card's URL from the text
+ *  drops that card automatically; this route is the explicit purge for
+ *  everything else (a capability URL that must go without rewording the
+ *  message, a moderator acting on someone else's post). */
+export async function unsetRoomEventUnfurls(config, room, seq) {
+    await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/events/${requireSeq(seq)}/unfurls`, { method: "DELETE" });
+}
+/** Edit an event's text over REST: the cold-replica-safe mirror of the WS
+ *  EDIT frame, and the ONE shape the WS path cannot express: an empty text
+ *  on a poll-bearing message legally clears the optional caption (the poll
+ *  stays the content; the store rejects empty edits on plain messages).
+ *  Viewers reconcile through the store's ENTRY_UPDATED fan-out exactly
+ *  like the REST poll verbs. */
+export async function editRoomEventRest(config, room, seq, text) {
+    await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/events/${requireSeq(seq)}`, { method: "PATCH", body: { text } });
+}
+export async function editRoomPoll(config, room, seq, patch) {
+    const body = {};
+    if (patch.question !== undefined)
+        body.question = patch.question;
+    if (patch.options !== undefined)
+        body.options = patch.options;
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}`, { method: "PATCH", body });
+    if (!result.event) {
+        throw new RoomSocialError("Poll edit returned no event", 502, result);
+    }
+    return result.event;
+}
+/**
+ * Voter identities, on demand (the entry's summary carries counts only).
+ * Grouped per option; `optionId` narrows to one option and `limit` caps the
+ * identities per option (counts stay exact).
+ */
+export async function listRoomPollVoters(config, room, seq, options = {}) {
+    const params = new URLSearchParams();
+    if (options.optionId !== undefined)
+        params.set("optionId", options.optionId);
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    const init = {};
+    if (options.signal)
+        init.signal = options.signal;
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/voters${params.size ? `?${params.toString()}` : ""}`, init);
+    return {
+        room: result.room ?? cleanRoomId(room),
+        seq: result.seq ?? seq,
+        voters: result.voters ?? [],
+        viewerOptionIds: result.viewerOptionIds ?? [],
+    };
+}
 export async function suggestRooms(config, request, options = {}) {
     const init = {
         method: "POST",

package/dist/social-types.d.ts

@@ -1,4 +1,4 @@
-import type { RoomLedgerSecretPayload } from "./shared/rooms-protocol.js";
+import type { RoomLedgerSecretPayload, RoomPollSummary, RoomTopicAttention, RoomUnfurl } from "./shared/rooms-protocol.js";
 export interface RoomSocialConfig {
     apiUrl: string;
     apiKey: string;
@@ -209,6 +209,169 @@ export interface RoomNotificationInboxResult {
     lastCursor: string | null;
     lastCursorId: string | null;
 }
+/** One of the caller's user blocks, wire names verbatim from the store's
+ *  block rows: the row id, the BLOCKED user's id, and when the block was
+ *  created (ISO string). Blocks are directional; the blocker is always the
+ *  verified caller and never appears on the row. */
+export interface RoomUserBlock {
+    id: string;
+    blockedId: string;
+    createdAt: string;
+}
+/** A newest-first page of the caller's blocks plus the composite cursor
+ *  (same paging contract as the notification inbox: feed lastCursor and
+ *  lastCursorId back together; both null on an empty page). */
+export interface RoomUserBlocksResult {
+    blocks: RoomUserBlock[];
+    hasMore: boolean;
+    lastCursor: string | null;
+    lastCursorId: string | null;
+}
+/** The row echoed by a bookmark save. `createdAt` is null only when a
+ *  concurrent remove raced the save (the save still happened). */
+export interface RoomBookmarkSaved {
+    roomId: string;
+    seq: number;
+    createdAt: string | null;
+}
+/** The store's REST poll summary: the ledger-entry wire shape plus the
+ *  store's monotonic ordering revision (create = 0, bumped per mutation).
+ *  The relay strips revision before entries reach the WS surface, so only
+ *  REST consumers see it; use it to refuse applying a stale mutation echo
+ *  over newer state. Optional because rows written before the field read
+ *  without it. */
+export type RoomRestPollSummary = RoomPollSummary & {
+    revision?: number | undefined;
+};
+/**
+ * A persisted room event as the store's REST surfaces return it: the stored
+ * row with its wire names verbatim (roomId/senderId/sender/createdAt, store
+ * event kinds like 'message'), minus the server-internal fields the store's
+ * publicRoomEvent projection strips. This is NOT the relay's mapped
+ * RoomLedgerEntry (room/handle/ts, type 'post'); the two shapes never mix.
+ * Only the identity core is guaranteed: non-visible bookmark targets arrive
+ * as content-free tombstones, and older rows predate newer columns.
+ */
+export interface RoomRestEvent {
+    roomId: string;
+    seq: number;
+    /** The store's event kinds, not the relay's mapped entry types. */
+    type: "message" | "system_market" | "moderation" | "secret";
+    senderId: string;
+    /** Write-time sender snapshot (denormalized; never re-resolved). */
+    sender: {
+        userId: string;
+        username: string;
+        handle: string;
+        isAgent: boolean;
+        role?: string | null | undefined;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** Absent on content-free tombstones. */
+    text?: string | undefined;
+    /** The store's body blob. Room attachments live at body.attachments
+     *  (sanitized for the viewer), never top-level like the ledger entry's. */
+    body?: Record<string, unknown> | undefined;
+    secret?: RoomLedgerSecretPayload | null | undefined;
+    cashtags?: string[] | undefined;
+    entities?: string[] | undefined;
+    reactions?: Array<{
+        emoji: string;
+        count: number;
+    }> | undefined;
+    /** Counts-only poll summary (additive; the same wire shape the ledger
+     *  entry carries plus the store's ordering revision). */
+    poll?: RoomRestPollSummary | null | undefined;
+    /** Server-rendered link unfurl cards (additive). */
+    unfurls?: RoomUnfurl[] | undefined;
+    replyToSeq?: number | null | undefined;
+    topicId?: string | null | undefined;
+    replyCount?: number | undefined;
+    lastReplyAt?: string | null | undefined;
+    pinned?: boolean | undefined;
+    visibility?: "visible" | "soft_deleted" | "hidden" | "held" | undefined;
+    /** Present only when the viewer holds view-audit on the room. */
+    moderationState?: "clean" | "flagged" | "reported" | "actioned" | undefined;
+    clientMsgId?: string | null | undefined;
+    editedAt?: string | null | undefined;
+    deletedAt?: string | null | undefined;
+    deletedBy?: string | null | undefined;
+}
+/** One saved message on the cross-room bookmark list, with the bookmarked
+ *  event hydrated server-side in the store's public row shape (non-visible
+ *  targets arrive as content-free tombstones, exactly like the room's own
+ *  read surfaces). */
+export interface RoomBookmark {
+    roomId: string;
+    seq: number;
+    createdAt: string;
+    event: RoomRestEvent;
+}
+/** A newest-first bookmark page plus the composite cursor. `total` is the
+ *  raw row count capped server-side: a bounded hint, not an exact readable
+ *  total (rows in rooms the caller can no longer read are subtracted from
+ *  pages but still count). */
+export interface RoomBookmarksResult {
+    bookmarks: RoomBookmark[];
+    hasMore: boolean;
+    lastCursor: string | null;
+    lastCursorId: string | null;
+    total: number;
+}
+/** Voter identities for one poll option, fetched on demand (the entry's
+ *  poll summary carries counts only). */
+export interface RoomPollOptionVoters {
+    optionId: string;
+    users: Array<{
+        userId: string;
+        handle: string;
+    }>;
+    count: number;
+}
+export interface RoomPollVotersResult {
+    room: string;
+    seq: number;
+    voters: RoomPollOptionVoters[];
+    /** The authenticated caller's own current ballot, from an exact point
+     *  read: independent of the bounded voter-identity window and of any
+     *  optionId filter. Empty when the caller holds no ballot. This is the
+     *  reload/recovery source of truth for rendering one's own vote. */
+    viewerOptionIds: string[];
+}
+/** Recipient-local daily push-suppression window (notify settings). */
+export interface RoomNotifyQuietHours {
+    enabled: boolean;
+    /** Minutes after local midnight, 0..1439. */
+    startMinutes: number;
+    /** Minutes after local midnight, 0..1439. May wrap past midnight. */
+    endMinutes: number;
+    /** IANA time zone name, 1..64 chars (server-probed against Intl). */
+    tz: string;
+}
+/** Per-space override entry on the rooms notification settings. */
+export interface RoomSpaceNotificationOverride {
+    suppressMassMentions?: boolean | undefined;
+    attention?: RoomTopicAttention | undefined;
+    /** Timed-mute expiry (ISO date). Meaningful only beside attention 'mute';
+     *  normalization drops it otherwise. The settings surface echoes the
+     *  CONFIGURED expiry, lapsed or not (a configuration read, not an
+     *  effective-state read). */
+    muteUntil?: string | undefined;
+}
+/** The store-owned `user_settings.notificationSettings.rooms` shape behind
+ *  GET/PUT /users/notification-settings. PUT is always the FULL object;
+ *  absent fields take their contract defaults. */
+export interface RoomsNotificationSettings {
+    dm: boolean;
+    mention: boolean;
+    reply: boolean;
+    /** Case-insensitive word-boundary keywords, capped at 50. */
+    keywords: string[];
+    spaceOverrides: Record<string, RoomSpaceNotificationOverride>;
+    /** Absent means no quiet-hours window is configured. */
+    quietHours?: RoomNotifyQuietHours | undefined;
+}
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
     docId: string;

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-export type { RoomAccessMode, RoomAttachment, RoomAttachmentInput, RoomAuditEntry, RoomAuditLogPayload, RoomAuditLogRequestPayload, RoomAuthSuccessPayload, RoomBackfillPayload, RoomClientMessage, RoomClientPlatform, RoomCreatedPayload, RoomCreatePayload, RoomDmHistoryPayload, RoomDmHistoryResultPayload, RoomDmInboxUpdatedPayload, RoomDmMessage, RoomDmMessageDeletedPayload, RoomDmMessageEditedPayload, RoomDmMessagePayload, RoomDmOpenedPayload, RoomDmOpenPayload, RoomDmParticipant, RoomDmPinsResultPayload, RoomDmPinUpdatedPayload, RoomDmReactionUpdatedPayload, RoomDmReadPayload, RoomDmReplyPayload, RoomDmSendPayload, RoomEntryUpdatedPayload, RoomErrorPayload, RoomForwardedFrom, RoomForwardMetadata, RoomFriendPresence, RoomInvitedPayload, RoomInvitePayload, RoomLedgerEntry, RoomMember, RoomMemberRemovedPayload, RoomMemberRoleChangedPayload, RoomMemberTier, RoomMessagePayload, RoomMeta, RoomModerateMemberPayload, RoomMutedPayload, RoomPinsPayload, RoomPresenceDeltaPayload, RoomPresencePayload, RoomReactorsPayload, RoomReadStatePayload, RoomRemoveMemberPayload, RoomReportedPayload, RoomReportPayload, RoomResyncPayload, RoomRole, RoomRoleChangePayload, RoomSearchPayload, RoomSearchResultsPayload, RoomSearchScope, RoomServerMessage, RoomServerMessageOf, RoomSetAttentionPayload, RoomSetReadOnlyPayload, RoomSpace, RoomSpaceJoinedPayload, RoomSpacesPayload, RoomThreadPayload, RoomTopic, RoomTopicAttention, RoomTopicBucketState, RoomTopicCreatePayload, RoomTopicListPayload, RoomTopicMergePayload, RoomTopicMovePayload, RoomTopicRenamePayload, RoomTopicResolvePayload, RoomTopicResultPayload, RoomTopicSetAttentionPayload, RoomTopicsPolicy, RoomTopicsResultPayload, RoomTopicUpdatedPayload, RoomTypingPayload, RoomUserStatus, RoomWhoPayload, } from "./shared/rooms-protocol.js";
+export type { RoomAccessMode, RoomAttachment, RoomAttachmentInput, RoomAuditEntry, RoomAuditLogPayload, RoomAuditLogRequestPayload, RoomAuthSuccessPayload, RoomBackfillPayload, RoomClientMessage, RoomClientPlatform, RoomCreatedPayload, RoomCreatePayload, RoomDmHistoryPayload, RoomDmHistoryResultPayload, RoomDmInboxUpdatedPayload, RoomDmMessage, RoomDmMessageDeletedPayload, RoomDmMessageEditedPayload, RoomDmMessagePayload, RoomDmOpenedPayload, RoomDmOpenPayload, RoomDmParticipant, RoomDmPinsResultPayload, RoomDmPinUpdatedPayload, RoomDmReactionUpdatedPayload, RoomDmReadPayload, RoomDmReplyPayload, RoomDmSendPayload, RoomEntryUpdatedPayload, RoomErrorPayload, RoomForwardedFrom, RoomForwardMetadata, RoomFriendPresence, RoomInvitedPayload, RoomInvitePayload, RoomLedgerEntry, RoomMember, RoomMemberRemovedPayload, RoomMemberRoleChangedPayload, RoomMemberTier, RoomMessagePayload, RoomMeta, RoomModerateMemberPayload, RoomMutedPayload, RoomPinsPayload, RoomPollOption, RoomPollSummary, RoomPresenceDeltaPayload, RoomPresencePayload, RoomReactorsPayload, RoomReadStatePayload, RoomRemoveMemberPayload, RoomReportedPayload, RoomReportPayload, RoomResyncPayload, RoomRole, RoomRoleChangePayload, RoomSearchPayload, RoomSearchResultsPayload, RoomSearchScope, RoomServerMessage, RoomServerMessageOf, RoomSetAttentionPayload, RoomSetReadOnlyPayload, RoomSpace, RoomSpaceJoinedPayload, RoomSpacesPayload, RoomThreadPayload, RoomTopic, RoomTopicAttention, RoomTopicBucketState, RoomTopicCreatePayload, RoomTopicListPayload, RoomTopicMergePayload, RoomTopicMovePayload, RoomTopicRenamePayload, RoomTopicResolvePayload, RoomTopicResultPayload, RoomTopicSetAttentionPayload, RoomTopicsPolicy, RoomTopicsResultPayload, RoomTopicUpdatedPayload, RoomTypingPayload, RoomUnfurl, RoomUserStatus, RoomWhoPayload, } from "./shared/rooms-protocol.js";
 export { applyRoomPresenceDelta, isSystemRoomLedgerEntryType, ROOM_PRESENCE_SAMPLE_LIMIT, RoomClientMessageType, RoomLedgerEntryType, RoomServerMessageType, SUPPORTED_ROOM_PROTOCOL_VERSION, } from "./shared/rooms-protocol.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmarket/rooms-client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "OM Rooms protocol client: wire types, WebSocket + REST clients, and chat view-models. Browser-safe (no node:/bun: imports).",
   "type": "module",
   "license": "Apache-2.0",

package/src/agent/armed-mode.ts

@@ -184,7 +184,9 @@ export function isTriggeringEntry(
   if (entry.type !== RoomLedgerEntryType.POST) return false;
   if (entry.isAgent) return false;
   if (isWebhookEntry(entry)) return false;
-  if (!entry.text?.trim()) return false;
+  // A poll is substantive content even with no caption, and a captionless
+  // poll REPLY is addressed at us like any other reply.
+  if (!entry.text?.trim() && entry.poll == null) return false;
   // Never trigger on our own message (we post as this handle/userId).
   const fromHandle = normalizeHandle(entry.handle).toLowerCase();
   const me = normalizeHandle(ownHandle).toLowerCase();
@@ -197,7 +199,9 @@ export function isTriggeringEntry(
   // old mentionsAgent) fired on ordinary words for short handles like "may" /
   // "btc"; armed posting has no human review, so it triggers ONLY on an `@handle`
   // token. Empty handle never matches (mentionsAgentExplicit guards it).
-  return mentionsAgentExplicit(entry.text, ownHandle);
+  // Mentions can live in the poll question too (member-authored content).
+  const mentionSource = [entry.text ?? "", entry.poll?.question ?? ""].filter(Boolean).join(" ");
+  return mentionsAgentExplicit(mentionSource, ownHandle);
 }
 
 /**
@@ -396,7 +400,7 @@ export function isHumanResetEntry(
   const fromHandle = normalizeHandle(entry.handle).toLowerCase();
   const me = normalizeHandle(ownHandle).toLowerCase();
   if (me.length > 0 && fromHandle === me) return false;
-  return Boolean(entry.text?.trim());
+  return Boolean(entry.text?.trim()) || entry.poll != null;
 }
 
 /** Note a turn/post error against the kill switch; returns true once the room

package/src/agent/clients/common.ts

@@ -24,6 +24,11 @@ export type AgentMessage =
 export interface ToolDispatchResult {
   isError?: true;
   content: string;
+  /** Full-fidelity render payload for in-process SURFACES (e.g. the TUI's
+   *  backtest card). Present only on the streamed copy channels consume —
+   *  the agent runtime strips it before the result reaches the model's
+   *  messages or the conversation store, so it never costs context. */
+  artifact?: unknown;
 }
 
 export interface LlmTool {