@openmarket/rooms-client 0.5.1 → 0.7.0

package/dist/agent/armed-mode.d.ts

@@ -100,14 +100,6 @@ export declare function rearmedRoomState(roomId: string, retired: ArmedRoomState
 /** Seqs of the user's own posts in a window of entries; the reply-trigger
  *  check tests `inReplyTo` against this set. Pure. */
 export declare function ownSeqsOf(entries: ReadonlyArray<RoomLedgerEntry>, ownUserId: string): Set<number>;
-/**
- * Whether a single incoming entry is a qualifying TRIGGER: a NEW human POST in
- * the room that @mentions the user's own handle, OR (when `ownSeqs` is given)
- * directly replies to one of the user's own messages. Reply semantics match a
- * mention (replying pings the author), so armed mode treats both as addressed
- * to the user. Agent posts, system entries, the user's own posts, and
- * non-mentions never trigger. Pure.
- */
 export declare function isTriggeringEntry(entry: RoomLedgerEntry, ownHandle: string, ownUserId: string, ownSeqs?: ReadonlySet<number>): boolean;
 /**
  * The newest qualifying trigger among entries strictly newer than

package/dist/agent/armed-mode.js

@@ -117,12 +117,24 @@ export function ownSeqsOf(entries, ownUserId) {
  * to the user. Agent posts, system entries, the user's own posts, and
  * non-mentions never trigger. Pure.
  */
+/** Webhook-ingested entries are machine posts even though isAgent is
+ *  false (the flag marks agent USERS). They must never count as the human
+ *  in any autonomy gate: a webhook @mention cannot start an unreviewed
+ *  autonomous turn, and webhook chatter cannot satisfy the
+ *  human-activity brake. */
+function isWebhookEntry(entry) {
+    return Boolean(entry.metadata?.webhook);
+}
 export function isTriggeringEntry(entry, ownHandle, ownUserId, ownSeqs) {
     if (entry.type !== RoomLedgerEntryType.POST)
         return false;
     if (entry.isAgent)
         return false;
-    if (!entry.text?.trim())
+    if (isWebhookEntry(entry))
+        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();
@@ -139,7 +151,9 @@ export function isTriggeringEntry(entry, ownHandle, ownUserId, ownSeqs) {
     // 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);
 }
 /**
  * The newest qualifying trigger among entries strictly newer than
@@ -312,13 +326,15 @@ export function isHumanResetEntry(entry, ownHandle, ownUserId) {
         return false;
     if (entry.isAgent)
         return false;
+    if (isWebhookEntry(entry))
+        return false;
     if (entry.userId === ownUserId)
         return false;
     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
  *  should auto-disarm (>= maxConsecutiveErrors in a row). Mutates `state`. */

package/dist/agent/clients/common.d.ts

@@ -1,5 +1,12 @@
 import { type KnownProvider } from "@earendil-works/pi-ai";
-export type SurfaceId = "cli" | "telegram" | "discord" | "slack" | "webui";
+/** Every chat surface, as a runtime list. The `SurfaceId` union derives from
+ *  this literal so per-surface policy checklists (packages/cli/test/
+ *  harness-budgets.test.ts) can iterate the surfaces at runtime while a new
+ *  entry still breaks type-exhaustive tables at compile time. Adding a
+ *  surface here requires classifying it in EVERY policy set (see AGENTS.md,
+ *  "Harness invariants"). */
+export declare const SURFACE_IDS: readonly ["cli", "telegram", "discord", "slack", "webui"];
+export type SurfaceId = (typeof SURFACE_IDS)[number];
 export interface AgentToolCall {
     id: string;
     name: string;
@@ -21,6 +28,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 {
     name: string;

package/dist/agent/clients/common.js

@@ -1,4 +1,11 @@
 import { getProviders } from "@earendil-works/pi-ai";
+/** Every chat surface, as a runtime list. The `SurfaceId` union derives from
+ *  this literal so per-surface policy checklists (packages/cli/test/
+ *  harness-budgets.test.ts) can iterate the surfaces at runtime while a new
+ *  entry still breaks type-exhaustive tables at compile time. Adding a
+ *  surface here requires classifying it in EVERY policy set (see AGENTS.md,
+ *  "Harness invariants"). */
+export const SURFACE_IDS = ["cli", "telegram", "discord", "slack", "webui"];
 /** OM-level provider for any OpenAI-compatible /v1/chat/completions endpoint
  *  (Ollama, vLLM, LM Studio, llama.cpp, custom proxies). Not a pi-ai
  *  KnownProvider: the model object is constructed at turn time from the
@@ -32,7 +39,10 @@ export function stringifyToolContent(value) {
         return "";
     if (typeof value === "string")
         return value;
-    return JSON.stringify(value, null, 2);
+    // Compact on purpose: this string is LLM input, and 2-space pretty-printing
+    // inflated every structured tool result by roughly a fifth in tokens for
+    // zero model benefit.
+    return JSON.stringify(value);
 }
 export function parseToolArguments(raw) {
     if (raw === undefined || raw === null)

package/dist/agent/topic-inbox.d.ts

@@ -18,6 +18,12 @@
 import type { RoomTopic, RoomTopicAttention, RoomTopicBucketState, RoomTopicsResultPayload } from "../shared/rooms-protocol.js";
 /** The reserved bucket key for untopicked (linear) messages. */
 export declare const UNTOPICKED_BUCKET = "";
+/** Effective attention for a bucket: an elapsed timed mute reads as the
+ *  base attention ('default'). The store expires timed mutes lazily (no
+ *  deadline-triggered frame), so a hydrated inbox would otherwise stay
+ *  muted past the deadline until the next hydration. A null or absent
+ *  deadline keeps the stored attention (permanent mute). */
+export declare function resolveTopicAttention(state: Pick<RoomTopicBucketState, "attention" | "muteUntil">, nowMs?: number): RoomTopicAttention;
 export interface TopicInboxItem {
     /** Bucket key: a topicId, or UNTOPICKED_BUCKET for the linear lane. */
     key: string;

package/dist/agent/topic-inbox.js

@@ -17,6 +17,17 @@
  */
 /** The reserved bucket key for untopicked (linear) messages. */
 export const UNTOPICKED_BUCKET = "";
+/** Effective attention for a bucket: an elapsed timed mute reads as the
+ *  base attention ('default'). The store expires timed mutes lazily (no
+ *  deadline-triggered frame), so a hydrated inbox would otherwise stay
+ *  muted past the deadline until the next hydration. A null or absent
+ *  deadline keeps the stored attention (permanent mute). */
+export function resolveTopicAttention(state, nowMs = Date.now()) {
+    if (state.attention !== "mute" || state.muteUntil == null)
+        return state.attention;
+    const deadline = Date.parse(state.muteUntil);
+    return Number.isFinite(deadline) && deadline <= nowMs ? "default" : "mute";
+}
 function emptyBucket() {
     return { lastSeq: 0, unreadCount: 0, cursor: 0, attention: "default" };
 }
@@ -111,7 +122,7 @@ export class RoomTopicInbox {
         return rows;
     }
     attentionFor(topicId) {
-        return this.bucketFor(topicId).attention;
+        return resolveTopicAttention(this.bucketFor(topicId));
     }
     /** A registry mutation arrived (TOPIC_UPDATED, or a verb result echo). */
     applyTopicUpdated(topic) {
@@ -160,6 +171,10 @@ export class RoomTopicInbox {
             this.buckets.set(topicId, bucket);
         }
         bucket.attention = attention;
+        // The mirror knows only the new attention: a stale deadline from a
+        // previous timed mute must not expire it. The next hydration restores
+        // any server-side deadline.
+        delete bucket.muteUntil;
     }
     /**
      * The viewer saw a bucket up to seq (the view batcher owns the durable
@@ -188,7 +203,7 @@ export class RoomTopicInbox {
     channelUnread() {
         let total = 0;
         for (const bucket of this.buckets.values()) {
-            if (bucket.attention === "mute")
+            if (resolveTopicAttention(bucket) === "mute")
                 continue;
             total += bucket.unreadCount;
         }
@@ -205,7 +220,7 @@ export class RoomTopicInbox {
     inboxItems() {
         const items = [];
         const untopicked = this.bucketFor(UNTOPICKED_BUCKET);
-        if (untopicked.unreadCount > 0 && untopicked.attention !== "mute") {
+        if (untopicked.unreadCount > 0 && resolveTopicAttention(untopicked) !== "mute") {
             items.push({
                 key: UNTOPICKED_BUCKET,
                 topic: undefined,
@@ -218,12 +233,12 @@ export class RoomTopicInbox {
             if (topic.mergedInto)
                 continue;
             const state = this.bucketFor(topic.topicId);
-            if (state.attention === "mute")
+            if (resolveTopicAttention(state) === "mute")
                 continue;
             let aliasUnread = 0;
             for (const alias of this.aliasesOf(topic.topicId)) {
                 const aliasState = this.bucketFor(alias);
-                if (aliasState.attention === "mute")
+                if (resolveTopicAttention(aliasState) === "mute")
                     continue;
                 aliasUnread += aliasState.unreadCount;
             }

package/dist/shared/rooms-protocol.d.ts

@@ -222,6 +222,19 @@ export interface RoomLedgerEntry {
         count: number;
     }> | undefined;
     editedAt?: string | number | Date | undefined;
+    /** Database-serialized edit counter: positive integer, strictly
+     *  increasing per event row, incremented on every successful text or
+     *  caption edit; absent means never edited. Orders caption edits where
+     *  wall-clock editedAt stamps can tie or skew across store replicas.
+     *  Missing on stores older than edit revisions. */
+    editRevision?: number | undefined;
+    /** Database-serialized card-mutation counter: positive integer,
+     *  strictly increasing per event row, bumped on every unfurl card
+     *  mutation (attach, edit-drop, purge); absent means cards were never
+     *  mutated. Consumers apply card patches only at or above their known
+     *  revision, making stale post-removal unfurl frames inert. Missing on
+     *  stores older than unfurl revisions. */
+    unfurlsRevision?: number | undefined;
     deletedAt?: string | number | Date | undefined;
     deletedBy?: string | undefined;
     replyCount?: number | undefined;
@@ -230,8 +243,14 @@ export interface RoomLedgerEntry {
     pinnedBy?: string | null | undefined;
     pinnedAt?: string | number | Date | null | undefined;
     attachments?: RoomAttachment[] | undefined;
+    /** Counts-only poll summary when this message carries a poll. Additive:
+     *  non-poll entries omit it, and live updates ride ENTRY_UPDATED. */
+    poll?: RoomPollSummary | null | undefined;
+    /** Server-rendered link unfurl cards. Additive: entries without links
+     *  (and servers older than the unfurl worker) omit it. */
+    unfurls?: RoomUnfurl[] | undefined;
     roomRole?: RoomRole | null | undefined;
-    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata>) | undefined;
+    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata> & Partial<RoomWebhookMetadata>) | undefined;
 }
 export type RoomForwardedFrom = {
     kind: "room";
@@ -245,6 +264,18 @@ export type RoomForwardedFrom = {
 export interface RoomForwardMetadata {
     forwardedFrom: RoomForwardedFrom;
 }
+/** Sender identity for messages posted through a channel webhook (the
+ *  Discord-compatible ingest). Entries carrying it render the webhook's
+ *  name and avatar with an APP-style badge; the entry's handle mirrors
+ *  the display name and its userId is the synthetic `webhook:<id>`, so a
+ *  webhook can never impersonate a member. */
+export interface RoomWebhookMetadata {
+    webhook: {
+        id: string;
+        name: string;
+        avatarUrl?: string | undefined;
+    };
+}
 export interface RoomAttachment {
     /**
      * Object key under room-attachments/; clients sign it at render time.
@@ -267,6 +298,46 @@ export interface RoomAttachment {
 export type RoomAttachmentInput = RoomAttachment & {
     key: string;
 };
+export interface RoomPollOption {
+    id: string;
+    text: string;
+    /** Vote count for this option. Counts only, never voter identities
+     *  (voters are fetched on demand, exactly like reactors). */
+    count: number;
+}
+/**
+ * Counts-only poll summary denormalized onto the carrying message (a poll
+ * IS a message). Vote/close/edit updates ride the existing ENTRY_UPDATED
+ * frame with the refreshed summary; the server's side collections stay the
+ * authoritative copy.
+ */
+export interface RoomPollSummary {
+    question: string;
+    options: RoomPollOption[];
+    multi: boolean;
+    /** ISO date when the poll auto-closes; null or absent means open-ended. */
+    closesAt?: string | null | undefined;
+    closed: boolean;
+    /** Store-serialized poll ordering revision, strictly increasing per
+     *  poll: consumers reject frames below their known revision so
+     *  bus-reordered vote/close updates cannot regress tallies. Present
+     *  where the relay forwards it; missing on older relays. */
+    revision?: number | undefined;
+}
+/**
+ * Server-rendered link unfurl card on an entry. `url` is the canonical
+ * URL; `thumbnailKey` is the re-hosted copy in the attachments bucket,
+ * signed through the member-scoped attachment path. The origin's image URL
+ * never crosses the wire. Cards appear via ENTRY_UPDATED when the unfurl
+ * worker lands.
+ */
+export interface RoomUnfurl {
+    url: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    siteName?: string | undefined;
+    thumbnailKey?: string | undefined;
+}
 /**
  * A registry-backed topic inside a channel. The id is permanent: rename
  * changes `name` only, and links (`om://topic/<topicId>`) keep resolving.
@@ -330,6 +401,21 @@ export interface RoomReadStatePayload {
      *  Present when the store surfaces it and on ROOM_SET_ATTENTION acks
      *  (which reply READ_STATE scoped to the one room, readState empty). */
     attention?: Record<string, RoomTopicAttention> | undefined;
+    /** Per-room timed-mute expiry (ISO date), keyed like attention. Rides
+     *  beside a 'mute' attention entry when the mute carries an expiry; null
+     *  marks an explicitly cleared or permanent mute. A lapsed expiry never
+     *  appears: the server resolves it at read time and the attention value
+     *  reads as its base ('default'). Missing on servers older than
+     *  mute-with-duration. */
+    muteUntil?: Record<string, string | null> | undefined;
+    /** Per-room attention commit revision, keyed like attention: a
+     *  database-serialized, strictly increasing counter per (user, room),
+     *  present only for rooms whose attention has ever been committed.
+     *  ORDERING CONTRACT: a consumer that has synced revision R for a room
+     *  must ignore snapshot attention entries whose revision is <= R (a
+     *  snapshot read before a newer commit can arrive after that commit's
+     *  sync frame). Missing on stores older than attention revisions. */
+    attentionRevision?: Record<string, number> | undefined;
     /** Unread mention counts by room, server-computed from the notify
      *  worker's ROOM_MENTION rows so badges survive reload and clear through
      *  the ack path. Unlike readState/attention the map is SPARSE AND
@@ -501,7 +587,7 @@ export interface RoomDmMessage {
     createdAt?: string | number | undefined;
     /** Sealed DM: content is '' and the opaque envelope rides here. */
     secret?: RoomLedgerSecretPayload | null | undefined;
-    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata>) | undefined;
+    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata> & Partial<RoomWebhookMetadata>) | undefined;
     /** Legacy public chat-image URL (renders as-is, no signing). */
     imageUrl?: string | null | undefined;
     /** Private, signed, scanned DM attachments (dm-attachments/ keyspace).
@@ -852,6 +938,14 @@ export interface RoomTopicBucketState {
     unreadCount: number;
     cursor: number;
     attention: RoomTopicAttention;
+    /** Standing timed-mute deadline (ISO date; null = permanent mute).
+     *  Present only on the room-wide '' bucket and only while its attention
+     *  is an active 'mute'; never on topic buckets. Same semantics as the
+     *  read-state muteUntil: the store expires timed mutes lazily, so
+     *  consumers resolve an elapsed deadline back to the base attention
+     *  ('default') at read time (see resolveTopicAttention). Missing on
+     *  servers older than mute-with-duration. */
+    muteUntil?: string | null | undefined;
 }
 export interface RoomTopicResultPayload {
     room: string;

package/dist/social-client.d.ts

@@ -1,5 +1,6 @@
-import type { RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, RoomNotificationInboxResult, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomSocialConfig, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSuggestion, RoomSuggestionRequest } from "./social-types.js";
-export type { RoomAttachment, RoomDmConversation, RoomDmHistory, RoomDmMessage, RoomDmParticipant, RoomDmSendResult, RoomDmUnreadConversation, RoomDocAttribution, RoomDocEditingLease, RoomDocMergeRegion, RoomDocRevisionSource, RoomDocRunRevertResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequest, RoomFriendRequests, RoomNotificationInboxItem, RoomNotificationInboxResult, RoomNotificationKind, RoomNotificationMessageData, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomSocialConfig, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, } from "./social-types.js";
+import type { RoomTopicAttention } from "./shared/rooms-protocol.js";
+import type { RoomBookmarkSaved, RoomBookmarksResult, RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, RoomNotificationInboxResult, RoomPollVotersResult, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomRestEvent, RoomSocialConfig, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSuggestion, RoomSuggestionRequest, RoomUserBlock, RoomUserBlocksResult } from "./social-types.js";
+export type { RoomAttachment, RoomBookmark, RoomBookmarkSaved, RoomBookmarksResult, RoomDmConversation, RoomDmHistory, RoomDmMessage, RoomDmParticipant, RoomDmSendResult, RoomDmUnreadConversation, RoomDocAttribution, RoomDocEditingLease, RoomDocMergeRegion, RoomDocRevisionSource, RoomDocRunRevertResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequest, RoomFriendRequests, RoomNotificationInboxItem, RoomNotificationInboxResult, RoomNotificationKind, RoomNotificationMessageData, RoomNotifyQuietHours, RoomPollOptionVoters, RoomPollVotersResult, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomRestEvent, RoomSocialConfig, RoomSpaceNotificationOverride, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, RoomsNotificationSettings, RoomUserBlock, RoomUserBlocksResult, } from "./social-types.js";
 /** Largest per-file size any tier accepts (plus tier). The server enforces
  *  the per-tier caps (free 10MB/file, plus 25MB/file) and daily quotas; this
  *  constant only pre-flights uploads no tier could ever accept. */
@@ -210,6 +211,31 @@ export declare function updateSpaceRole(config: RoomSocialConfig, spaceId: strin
     position?: number;
 }): Promise<RoomSpaceRole>;
 export declare function deleteSpaceRole(config: RoomSocialConfig, spaceId: string, roleId: string): Promise<void>;
+/** A channel webhook: the Discord-compatible ingest capability. The
+ *  posting URL is `<chat-api>/webhooks/<webhookId>/<token>`; the token is
+ *  the whole credential, so treat listed webhooks like secrets. */
+export interface RoomWebhook {
+    webhookId: string;
+    room: string;
+    name: string;
+    avatarUrl: string | null;
+    token: string;
+    createdBy: string;
+    /** Creator's handle at create time (display; createdBy is the id). */
+    createdByHandle?: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    deliveryCount: number;
+    disabled: boolean;
+}
+export declare function listRoomWebhooks(config: RoomSocialConfig, room: string): Promise<RoomWebhook[]>;
+export declare function createRoomWebhook(config: RoomSocialConfig, room: string, input: {
+    name: string;
+    avatarUrl?: string | null;
+}): Promise<RoomWebhook>;
+export declare function deleteRoomWebhook(config: RoomSocialConfig, room: string, webhookId: string): Promise<void>;
+/** Rotate the capability: the old URL dies immediately. */
+export declare function regenerateRoomWebhookToken(config: RoomSocialConfig, room: string, webhookId: string): Promise<RoomWebhook>;
 export declare function setSpaceMemberRoles(config: RoomSocialConfig, spaceId: string, targetUserId: string, roleIds: string[]): Promise<{
     spaceId: string;
     userId: string;
@@ -229,12 +255,20 @@ export interface RoomSpaceInvite {
     invitedBy?: string;
     role: "admin" | "member";
     createdAt?: string;
+    /** Expiry deadline (ISO date); null or absent means the invite stands
+     *  until accepted or declined. Additive (0.6.0 servers). */
+    expiresAt?: string | null;
 }
-/** 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 declare function createSpaceInvite(config: RoomSocialConfig, spaceId: string, input: {
     targetUserId?: string;
     targetUsername?: string;
     role?: "admin" | "member";
+    expiresAt?: string;
 }): Promise<RoomSpaceInvite>;
 /** The caller's own pending invitations. */
 export declare function listMySpaceInvites(config: RoomSocialConfig): Promise<RoomSpaceInvite[]>;
@@ -249,10 +283,22 @@ export declare function acceptSpaceInvite(config: RoomSocialConfig, inviteId: st
 export declare function declineSpaceInvite(config: RoomSocialConfig, inviteId: string): Promise<{
     declined?: boolean;
 }>;
-/** Mint (or rotate) the shareable join code; plaintext comes back once. */
-export declare function setSpaceJoinCode(config: RoomSocialConfig, spaceId: string): Promise<{
+/** 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 declare function setSpaceJoinCode(config: RoomSocialConfig, spaceId: string, options?: {
+    expiresAt?: string | undefined;
+    maxUses?: number | undefined;
+}): Promise<{
     spaceId: string;
     code: string;
+    expiresAt?: string | null;
+    maxUses?: number | null;
 }>;
 export declare function clearSpaceJoinCode(config: RoomSocialConfig, spaceId: string): Promise<{
     cleared?: boolean;
@@ -386,6 +432,154 @@ export declare function listRoomNotifications(config: RoomSocialConfig, options?
     unread?: boolean | undefined;
     signal?: AbortSignal | undefined;
 }): Promise<RoomNotificationInboxResult>;
+/**
+ * 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 declare function markRoomUnread(config: RoomSocialConfig, room: string, seq: number): Promise<{
+    success: boolean;
+}>;
+/**
+ * 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 declare function setRoomAttentionRest(config: RoomSocialConfig, room: string, attention: RoomTopicAttention, options?: {
+    untilMs?: number | undefined;
+}): Promise<{
+    attention: RoomTopicAttention;
+    muteUntil: string | null;
+}>;
+/**
+ * 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 declare function addRoomBookmark(config: RoomSocialConfig, room: string, seq: number): Promise<RoomBookmarkSaved>;
+export declare function removeRoomBookmark(config: RoomSocialConfig, room: string, seq: number): Promise<{
+    removed: boolean;
+}>;
+/**
+ * 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 declare function listUserBookmarks(config: RoomSocialConfig, options?: {
+    limit?: number | undefined;
+    /** Feed a page's lastCursor back here (explicit undefined reads as
+     *  "first page", so `page.lastCursor ?? undefined` composes under
+     *  exactOptionalPropertyTypes). */
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<RoomBookmarksResult>;
+/**
+ * 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 declare function getUserBlocks(config: RoomSocialConfig, options?: {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<RoomUserBlocksResult>;
+/** 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 declare function blockUser(config: RoomSocialConfig, userId: string): Promise<RoomUserBlock>;
+/** Unblock a user (idempotent: unblocking a non-blocked user is a no-op). */
+export declare function unblockUser(config: RoomSocialConfig, userId: string): Promise<{
+    success: boolean;
+}>;
+/**
+ * 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 declare function createRoomPoll(config: RoomSocialConfig, room: string, input: {
+    question: string;
+    options: string[];
+    multi?: boolean | undefined;
+    closesAt?: string | undefined;
+    text?: string | undefined;
+    /** Exact-case workspace id: lets a COLD relay replica materialize a
+     *  virtual workspace room without guessing the id's casing from the
+     *  lowercased room name (owners resolve server-side; non-owner first
+     *  writers need this). */
+    workspaceId?: string | undefined;
+    /** Route into a topic lane like any other append. */
+    topicId?: string | undefined;
+    /** Post the poll as a threaded reply. */
+    replyToSeq?: number | undefined;
+    /** Server-side idempotency: retries after an ambiguous failure reuse
+     *  the key instead of minting a duplicate poll. */
+    clientMsgId?: string | undefined;
+}): Promise<RoomRestEvent>;
+/**
+ * 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 declare function voteRoomPoll(config: RoomSocialConfig, room: string, seq: number, optionIds: string[]): Promise<RoomRestEvent>;
+/** Clear the caller's vote. Echoes the refreshed store event row. */
+export declare function unvoteRoomPoll(config: RoomSocialConfig, room: string, seq: number): Promise<RoomRestEvent>;
+/** Close a poll (idempotent on an already-closed poll). Echoes the store
+ *  event row with `poll.closed` set. */
+export declare function closeRoomPoll(config: RoomSocialConfig, room: string, seq: number): Promise<RoomRestEvent>;
+/** 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 declare function unsetRoomEventUnfurls(config: RoomSocialConfig, room: string, seq: number): Promise<void>;
+/** 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 declare function editRoomEventRest(config: RoomSocialConfig, room: string, seq: number, text: string): Promise<void>;
+export declare function editRoomPoll(config: RoomSocialConfig, room: string, seq: number, patch: {
+    question?: string | undefined;
+    options?: string[] | undefined;
+}): Promise<RoomRestEvent>;
+/**
+ * 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 declare function listRoomPollVoters(config: RoomSocialConfig, room: string, seq: number, options?: {
+    optionId?: string | undefined;
+    limit?: number | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<RoomPollVotersResult>;
 export declare function suggestRooms(config: RoomSocialConfig, request: RoomSuggestionRequest, options?: {
     signal?: AbortSignal;
 }): Promise<RoomSuggestion[]>;
@@ -395,6 +589,9 @@ export declare function socialRequest<T>(config: RoomSocialConfig, path: string,
     signal?: AbortSignal;
     formData?: FormData;
     headers?: Record<string, string>;
+    /** Fetch cache mode; token-bearing reads pass "no-store" so posting
+     *  credentials never persist in a browser HTTP cache. */
+    cache?: RequestCache;
 }): Promise<T>;
 export declare function cleanUsername(username: string): string;
 export declare function cleanRoomId(room: string): string;