@openmarket/rooms-client 0.2.1 → 0.4.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-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 RoomAccessMode, type RoomAttachmentInput, type RoomAuditLogPayload, type RoomAuthSuccessPayload, type RoomBackfillPayload, type RoomClientPlatform, 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;
@@ -39,7 +39,7 @@ export interface RoomJoinOptions {
 }
 export interface RoomSayOptions extends RoomJoinOptions {
     text?: string;
-    attachments?: RoomAttachment[];
+    attachments?: RoomAttachmentInput[];
     inReplyTo?: number;
     /** Post directly into a topic; the room's linear stream is unaffected. */
     topicId?: string;
@@ -283,9 +283,18 @@ export declare function joinRoom(config: RoomClientConfig, options: RoomJoinOpti
 /** 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;
+/**
+ * Post into a joined room and return the frame's clientMsgId (what MESSAGE
+ * echoes carry back for optimistic-send reconciliation). `clientMsgId` is
+ * caller-suppliable so an offline send queue can retry one logical message
+ * under one stable id (same contract as sayRoom / sendRoomDmOnClient);
+ * omitted, it mints a UUID exactly as before. The relay validates the id
+ * (1..128 chars after trim); dedupe on (userId, clientMsgId) is server-side
+ * work and NOT implied here.
+ */
+export declare function postRoomMessage(client: RoomWsClient, room: string, text: string, inReplyTo?: number, attachments?: RoomAttachmentInput[], topicId?: string, clientMsgId?: 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;
+export declare function sendRoomStatus(client: RoomWsClient, status: RoomUserStatus, statusText?: string | null, platform?: RoomClientPlatform): 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
@@ -310,7 +319,18 @@ export declare function requestRoomReactors(client: RoomWsClient, request: {
  *  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>;
+export declare function setRoomStatusOnce(config: RoomClientConfig, status: RoomUserStatus, statusText?: string | null, platform?: RoomClientPlatform): Promise<void>;
+/**
+ * Set the caller's room-level attention (notification posture) on a live
+ * client. The relay validates room participation, persists through the
+ * store, and acks with a READ_STATE frame scoped to this room whose
+ * attention map carries the persisted value (readState stays empty: cursors
+ * are untouched). Private per-user state; nothing broadcasts.
+ */
+export declare function setRoomAttentionOnClient(client: RoomWsClient, request: {
+    room: string;
+    attention: RoomTopicAttention;
+}): Promise<RoomReadStatePayload>;
 /** Add/remove one reaction (one-shot). Returns the updated entry. */
 export declare function reactRoom(config: RoomClientConfig, options: {
     room: string;

package/dist/client.js

@@ -618,21 +618,30 @@ export function attachRejoinOnReconnect(client, options, latestSeq, onRejoined,
             .catch((err) => onError?.(err));
     });
 }
-export function postRoomMessage(client, room, text, inReplyTo, attachments, topicId) {
-    const clientMsgId = randomUUID();
+/**
+ * Post into a joined room and return the frame's clientMsgId (what MESSAGE
+ * echoes carry back for optimistic-send reconciliation). `clientMsgId` is
+ * caller-suppliable so an offline send queue can retry one logical message
+ * under one stable id (same contract as sayRoom / sendRoomDmOnClient);
+ * omitted, it mints a UUID exactly as before. The relay validates the id
+ * (1..128 chars after trim); dedupe on (userId, clientMsgId) is server-side
+ * work and NOT implied here.
+ */
+export function postRoomMessage(client, room, text, inReplyTo, attachments, topicId, clientMsgId) {
+    const msgId = clientMsgId ?? randomUUID();
     client.send({
         type: RoomClientMessageType.POST,
         payload: {
             room,
             ...(text ? { text } : {}),
             ...(attachments?.length ? { attachments: toRoomAttachmentPayloads(attachments) } : {}),
-            clientMsgId,
+            clientMsgId: msgId,
             ...(inReplyTo !== undefined ? { inReplyTo } : {}),
             ...(topicId ? { topicId } : {}),
         },
         timestamp: Date.now(),
     });
-    return clientMsgId;
+    return msgId;
 }
 export function sendRoomTyping(client, room, state) {
     if (client.isGuest())
@@ -643,10 +652,16 @@ export function sendRoomTyping(client, room, state) {
         timestamp: Date.now(),
     });
 }
-export function sendRoomStatus(client, status, statusText) {
+export function sendRoomStatus(client, status, statusText, platform) {
     client.send({
         type: RoomClientMessageType.STATUS,
-        payload: { status, ...(statusText !== undefined ? { statusText } : {}) },
+        payload: {
+            status,
+            ...(statusText !== undefined ? { statusText } : {}),
+            // Session identity, declared once per connection (or on change): the
+            // relay carries it onto presence member entries.
+            ...(platform ? { platform } : {}),
+        },
         timestamp: Date.now(),
     });
 }
@@ -769,11 +784,11 @@ export async function requestRoomReactors(client, request) {
  *  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 async function setRoomStatusOnce(config, status, statusText) {
+export async function setRoomStatusOnce(config, status, statusText, platform) {
     const client = new RoomWsClient(config);
     try {
         await client.connect();
-        sendRoomStatus(client, status, statusText);
+        sendRoomStatus(client, status, statusText, platform);
         // STATUS has no ack frame: give the socket a beat to flush before close.
         await new Promise((resolve) => setTimeout(resolve, 200));
     }
@@ -781,6 +796,24 @@ export async function setRoomStatusOnce(config, status, statusText) {
         client.close();
     }
 }
+/**
+ * Set the caller's room-level attention (notification posture) on a live
+ * client. The relay validates room participation, persists through the
+ * store, and acks with a READ_STATE frame scoped to this room whose
+ * attention map carries the persisted value (readState stays empty: cursors
+ * are untouched). Private per-user state; nothing broadcasts.
+ */
+export async function setRoomAttentionOnClient(client, request) {
+    const requestId = randomUUID();
+    const room = normalizeRoomName(request.room);
+    client.send({
+        type: RoomClientMessageType.ROOM_SET_ATTENTION,
+        payload: { requestId, room, attention: request.attention },
+        timestamp: Date.now(),
+    });
+    const result = await client.waitFor(RoomServerMessageType.READ_STATE, (msg) => msg.payload.requestId === requestId, undefined, requestId);
+    return result.payload;
+}
 /** One-shot session helper for the config-based mutation verbs below (the
  *  agent tools' transport: connect, join, act, wait for the echo, close). */
 async function withRoomEcho(config, room, seq, send) {

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

@@ -48,6 +48,7 @@ export declare const RoomClientMessageType: {
     readonly TOPIC_RESOLVE: "TOPIC_RESOLVE";
     readonly TOPIC_SET_ATTENTION: "TOPIC_SET_ATTENTION";
     readonly TOPIC_LIST: "TOPIC_LIST";
+    readonly ROOM_SET_ATTENTION: "ROOM_SET_ATTENTION";
 };
 export type RoomClientMessageType = (typeof RoomClientMessageType)[keyof typeof RoomClientMessageType];
 export declare const RoomServerMessageType: {
@@ -127,6 +128,9 @@ export type RoomRole = "owner" | "admin" | "mod" | "member";
  *  semantics of an absent value). */
 export type RoomTopicsPolicy = "off" | "allowed" | "required";
 export type RoomTopicAttention = "follow" | "default" | "mute";
+/** Self-declared client class on STATUS frames; presence member entries
+ *  carry it through so rosters can render where someone is connected from. */
+export type RoomClientPlatform = "web" | "desktop" | "mobile" | "tui";
 export interface RoomMember {
     userId: string;
     username: string;
@@ -140,6 +144,8 @@ export interface RoomMember {
     joinedAt: number;
     avatarUrl?: string | null;
     statusText?: string | null;
+    /** Present when the member's session declared one via STATUS. */
+    platform?: RoomClientPlatform | undefined;
 }
 export interface RoomMeta {
     name: string;
@@ -164,6 +170,10 @@ export interface RoomMeta {
      *  2026-07-12 dial-default flip (post-flip relays always advertise the
      *  stored value, "off" included); explicit "off" means topics are inert. */
     topicsPolicy?: RoomTopicsPolicy | undefined;
+    /** The viewer's room attention (notification posture), a per-viewer field
+     *  like viewerRole: surfaced on rooms listings for the caller. Absent
+     *  reads as "default". */
+    attention?: RoomTopicAttention | undefined;
     tags?: string[] | undefined;
     entities?: string[] | undefined;
     sourceRefs?: Array<Record<string, unknown>> | undefined;
@@ -217,13 +227,27 @@ export interface RoomLedgerEntry {
     roomRole?: RoomRole | null | undefined;
 }
 export interface RoomAttachment {
-    /** Object key under room-attachments/; clients sign it at render time. */
-    key: string;
+    /**
+     * Object key under room-attachments/; clients sign it at render time.
+     * Absent while scanStatus is "pending" on entries served to members: the
+     * store withholds the signable key until the scan clears, so render the
+     * metadata as a placeholder and do not attempt signing without a key.
+     */
+    key?: string | undefined;
     name: string;
     size: number;
     mime: string;
     scanStatus?: "pending" | "clean" | "held" | undefined;
 }
+/**
+ * A postable attachment reference. Outbound frames must always carry the
+ * stored key (senders reference their own uploads, which include it); only
+ * read views of pending entries may be keyless, and those must never be
+ * forwarded back into a post.
+ */
+export type RoomAttachmentInput = RoomAttachment & {
+    key: string;
+};
 /**
  * A registry-backed topic inside a channel. The id is permanent: rename
  * changes `name` only, and links (`om://topic/<topicId>`) keep resolving.
@@ -281,7 +305,12 @@ export interface RoomPinsPayload {
     requestId?: string | undefined;
 }
 export interface RoomReadStatePayload {
+    /** Partial map: rooms absent from a reply are unchanged. */
     readState: Record<string, number>;
+    /** Per-room attention for the requesting user, keyed like readState.
+     *  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;
     requestId?: string | undefined;
 }
 export interface RoomSearchResultsPayload {
@@ -729,6 +758,15 @@ export interface RoomTopicSetAttentionPayload {
     topicId: string;
     attention: RoomTopicAttention;
 }
+/** Room-level attention (notification posture). Private per-user state on
+ *  the caller's read row; topic attention wins for topic-scoped messages
+ *  and room attention wins over space attention. The relay acks with a
+ *  READ_STATE frame scoped to the room (see RoomReadStatePayload). */
+export interface RoomSetAttentionPayload {
+    requestId?: string;
+    room: string;
+    attention: RoomTopicAttention;
+}
 export interface RoomTopicListPayload {
     requestId?: string;
     room: string;
@@ -843,7 +881,7 @@ export type RoomClientMessage = {
     payload: {
         room: string;
         text?: string;
-        attachments?: RoomAttachment[];
+        attachments?: RoomAttachmentInput[];
         inReplyTo?: number;
         /** Post directly into a topic; the room's linear stream is unaffected. */
         topicId?: string;
@@ -1003,6 +1041,7 @@ export type RoomClientMessage = {
     payload: {
         status: RoomUserStatus;
         statusText?: string | null;
+        platform?: RoomClientPlatform;
     };
     timestamp?: number;
 } | {
@@ -1078,6 +1117,10 @@ export type RoomClientMessage = {
     type: typeof RoomClientMessageType.TOPIC_LIST;
     payload: RoomTopicListPayload;
     timestamp?: number;
+} | {
+    type: typeof RoomClientMessageType.ROOM_SET_ATTENTION;
+    payload: RoomSetAttentionPayload;
+    timestamp?: number;
 };
 export type RoomServerMessage = {
     type: typeof RoomServerMessageType.AUTH_SUCCESS;

package/dist/shared/rooms-protocol.js

@@ -48,6 +48,7 @@ export const RoomClientMessageType = {
     TOPIC_RESOLVE: "TOPIC_RESOLVE",
     TOPIC_SET_ATTENTION: "TOPIC_SET_ATTENTION",
     TOPIC_LIST: "TOPIC_LIST",
+    ROOM_SET_ATTENTION: "ROOM_SET_ATTENTION",
 };
 export const RoomServerMessageType = {
     AUTH_SUCCESS: "AUTH_SUCCESS",

package/dist/social-client.d.ts

@@ -1,5 +1,8 @@
 import type { RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, 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, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomSocialConfig, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, } 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. */
 export declare const ROOM_ATTACHMENT_MAX_BYTES: number;
 export declare class RoomSocialError extends Error {
     readonly name = "RoomSocialError";
@@ -337,7 +340,10 @@ export declare function restoreRoomDoc(config: RoomSocialConfig, docId: string,
     note?: string;
     asAgent?: boolean;
 }): Promise<RoomDoc>;
-export declare function getRoomAttachmentUrl(config: RoomSocialConfig, room: string, key: string): Promise<{
+export declare function getRoomAttachmentUrl(config: RoomSocialConfig, room: string, key: string, opts?: {
+    name?: string;
+    download?: boolean;
+}): Promise<{
     url: string;
     expiresAt: string | null;
 }>;
@@ -363,6 +369,7 @@ export declare function socialRequest<T>(config: RoomSocialConfig, path: string,
     body?: unknown;
     signal?: AbortSignal;
     formData?: FormData;
+    headers?: Record<string, string>;
 }): Promise<T>;
 export declare function cleanUsername(username: string): string;
 export declare function cleanRoomId(room: string): string;

package/dist/social-client.js

@@ -1,6 +1,9 @@
 import { resolveRoomsWsUrl } from "./client.js";
 import { envString, ROOM_CHAT_API_URL } from "./endpoints.js";
-export const ROOM_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** 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. */
+export const ROOM_ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
 export class RoomSocialError extends Error {
     name = "RoomSocialError";
     status;
@@ -517,9 +520,22 @@ export async function restoreRoomDoc(config, docId, input = {}) {
     const result = await socialRequest(config, `/docs/${encodeURIComponent(docId)}/restore`, { method: "POST", body: input });
     return result.doc;
 }
-export async function getRoomAttachmentUrl(config, room, key) {
+export async function getRoomAttachmentUrl(config, room, key, opts = {}) {
+    // The object key identifies the object and stays in the query. The
+    // download filename and force-download flag ride REQUEST HEADERS, never
+    // the URL: a private-room filename in the query string leaked into the
+    // relay's access logs and error telemetry (Morgan, Sentry).
     const params = new URLSearchParams({ key });
-    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/attachment-url?${params.toString()}`, { method: "GET" });
+    const headers = {};
+    // Percent-encode the name: Fetch/HTTP header values are byte strings, so a
+    // raw Unicode filename (报告.py, an emoji) throws a TypeError before the
+    // request is sent. The store decodes with decodeURIComponent.
+    if (opts.name)
+        headers["X-Om-Download-Name"] = encodeURIComponent(opts.name);
+    // Forces a Content-Disposition attachment even for inline mimes.
+    if (opts.download)
+        headers["X-Om-Download"] = "1";
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/attachment-url?${params.toString()}`, { method: "GET", headers });
     if (!result.url) {
         throw new RoomSocialError("Attachment sign failed", 502, result);
     }
@@ -587,6 +603,7 @@ export async function socialRequest(config, path, init = {}) {
             Authorization: `Bearer ${config.apiKey}`,
             Accept: "application/json",
             ...(hasJsonBody ? { "Content-Type": "application/json" } : {}),
+            ...(init.headers ?? {}),
         },
         ...(hasJsonBody
             ? { body: JSON.stringify(init.body) }
@@ -658,6 +675,63 @@ function requestPath(url) {
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
+/** Source/config/text extensions declared as text/plain so the server's
+ *  UTF-8 code-file lane accepts them. Markup extensions the server
+ *  blocklists (html, svg, xml, ...) are deliberately absent: they fall
+ *  through to application/octet-stream and the server rejects them. */
+const CODE_TEXT_EXTENSIONS = new Set([
+    "js",
+    "jsx",
+    "ts",
+    "tsx",
+    "py",
+    "rb",
+    "go",
+    "rs",
+    "java",
+    "c",
+    "h",
+    "cc",
+    "cpp",
+    "hpp",
+    "cs",
+    "php",
+    "sh",
+    "bash",
+    "zsh",
+    "fish",
+    "ps1",
+    "sql",
+    "yaml",
+    "yml",
+    "toml",
+    "ini",
+    "cfg",
+    "conf",
+    "log",
+    "diff",
+    "patch",
+    "tex",
+    "r",
+    "jl",
+    "kt",
+    "kts",
+    "swift",
+    "scala",
+    "clj",
+    "cljs",
+    "ex",
+    "exs",
+    "erl",
+    "lua",
+    "pl",
+    "pm",
+    "dart",
+    "gradle",
+    "properties",
+    "bat",
+    "cmd",
+]);
 export function mimeFromFilename(filename) {
     const lower = filename.toLowerCase();
     if (lower.endsWith(".png"))
@@ -668,6 +742,10 @@ export function mimeFromFilename(filename) {
         return "image/webp";
     if (lower.endsWith(".gif"))
         return "image/gif";
+    if (lower.endsWith(".mp4"))
+        return "video/mp4";
+    if (lower.endsWith(".webm"))
+        return "video/webm";
     if (lower.endsWith(".pdf"))
         return "application/pdf";
     if (lower.endsWith(".txt"))
@@ -687,5 +765,8 @@ export function mimeFromFilename(filename) {
     if (lower.endsWith(".pptx")) {
         return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
     }
+    const dot = lower.lastIndexOf(".");
+    if (dot !== -1 && CODE_TEXT_EXTENSIONS.has(lower.slice(dot + 1)))
+        return "text/plain";
     return "application/octet-stream";
 }

package/dist/social-types.d.ts

@@ -44,16 +44,26 @@ export interface RoomFollowResult {
     isNewFollow?: boolean;
 }
 export interface RoomAttachment {
-    /** Object key under room-attachments/; clients sign it at render time. */
-    key: string;
+    /**
+     * Object key under room-attachments/; clients sign it at render time.
+     * Absent while scanStatus is "pending" on entries served to members: the
+     * store withholds the signable key until the scan clears, so render the
+     * metadata as a placeholder and do not attempt signing without a key.
+     */
+    key?: string | undefined;
     name: string;
     size: number;
     mime: string;
     scanStatus?: "pending" | "clean" | "held" | undefined;
 }
 export interface RoomAttachmentUpload {
-    /** The stored attachment plus its first signed URL, for immediate render. */
+    /**
+     * The stored attachment plus its first signed URL, for immediate render.
+     * The uploader always receives the key; only member views of PENDING
+     * entries withhold it.
+     */
     attachment: RoomAttachment & {
+        key: string;
         url: string;
         expiresAt: string | null;
     };
@@ -120,6 +130,9 @@ export interface RoomDmMessage {
         emoji: string;
         users: string[];
     }>;
+    /** Client-minted idempotency tag echoed back on DM sends, so a sender's
+     *  durable queue can settle its optimistic row. Additive (0.4.0). */
+    clientMsgId?: string;
 }
 export interface RoomDmHistory {
     conversationId: string;

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-export type { RoomAccessMode, RoomAttachment, RoomAuditEntry, RoomAuditLogPayload, RoomAuditLogRequestPayload, RoomAuthSuccessPayload, RoomBackfillPayload, RoomClientMessage, RoomCreatedPayload, RoomCreatePayload, RoomDmHistoryPayload, RoomDmHistoryResultPayload, RoomDmInboxUpdatedPayload, RoomDmMessage, RoomDmMessagePayload, RoomDmOpenedPayload, RoomDmOpenPayload, RoomDmParticipant, RoomDmReadPayload, RoomDmSendPayload, RoomEntryUpdatedPayload, RoomErrorPayload, 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, 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, RoomDmMessagePayload, RoomDmOpenedPayload, RoomDmOpenPayload, RoomDmParticipant, RoomDmReadPayload, RoomDmSendPayload, RoomEntryUpdatedPayload, RoomErrorPayload, 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 { 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.2.1",
+  "version": "0.4.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/client.ts

@@ -7,12 +7,13 @@ import { authFromApiKey } from "./jwt.js";
 import { consumeRoomSuggestionAttribution } from "./suggestion-attribution.js";
 import {
   type RoomAccessMode,
-  type RoomAttachment,
+  type RoomAttachmentInput,
   type RoomAuditLogPayload,
   type RoomAuthSuccessPayload,
   type RoomBackfillPayload,
   type RoomClientMessage,
   RoomClientMessageType,
+  type RoomClientPlatform,
   type RoomDmHistoryResultPayload,
   type RoomDmMessagePayload,
   type RoomDmOpenedPayload,
@@ -82,7 +83,7 @@ export interface RoomJoinOptions {
 
 export interface RoomSayOptions extends RoomJoinOptions {
   text?: string;
-  attachments?: RoomAttachment[];
+  attachments?: RoomAttachmentInput[];
   inReplyTo?: number;
   /** Post directly into a topic; the room's linear stream is unaffected. */
   topicId?: string;
@@ -261,7 +262,9 @@ export interface RoomJoinedSession {
   client: RoomWsClient;
 }
 
-function toRoomAttachmentPayloads(attachments: readonly RoomAttachment[]): RoomAttachment[] {
+function toRoomAttachmentPayloads(
+  attachments: readonly RoomAttachmentInput[],
+): RoomAttachmentInput[] {
   return attachments.map(({ key, name, size, mime }) => ({ key, name, size, mime }));
 }
 
@@ -1145,28 +1148,38 @@ export function attachRejoinOnReconnect(
   });
 }
 
+/**
+ * Post into a joined room and return the frame's clientMsgId (what MESSAGE
+ * echoes carry back for optimistic-send reconciliation). `clientMsgId` is
+ * caller-suppliable so an offline send queue can retry one logical message
+ * under one stable id (same contract as sayRoom / sendRoomDmOnClient);
+ * omitted, it mints a UUID exactly as before. The relay validates the id
+ * (1..128 chars after trim); dedupe on (userId, clientMsgId) is server-side
+ * work and NOT implied here.
+ */
 export function postRoomMessage(
   client: RoomWsClient,
   room: string,
   text: string,
   inReplyTo?: number,
-  attachments?: RoomAttachment[],
+  attachments?: RoomAttachmentInput[],
   topicId?: string,
+  clientMsgId?: string,
 ): string {
-  const clientMsgId = randomUUID();
+  const msgId = clientMsgId ?? randomUUID();
   client.send({
     type: RoomClientMessageType.POST,
     payload: {
       room,
       ...(text ? { text } : {}),
       ...(attachments?.length ? { attachments: toRoomAttachmentPayloads(attachments) } : {}),
-      clientMsgId,
+      clientMsgId: msgId,
       ...(inReplyTo !== undefined ? { inReplyTo } : {}),
       ...(topicId ? { topicId } : {}),
     },
     timestamp: Date.now(),
   });
-  return clientMsgId;
+  return msgId;
 }
 
 export function sendRoomTyping(client: RoomWsClient, room: string, state: "start" | "stop"): void {
@@ -1182,10 +1195,17 @@ export function sendRoomStatus(
   client: RoomWsClient,
   status: RoomUserStatus,
   statusText?: string | null,
+  platform?: RoomClientPlatform,
 ): void {
   client.send({
     type: RoomClientMessageType.STATUS,
-    payload: { status, ...(statusText !== undefined ? { statusText } : {}) },
+    payload: {
+      status,
+      ...(statusText !== undefined ? { statusText } : {}),
+      // Session identity, declared once per connection (or on change): the
+      // relay carries it onto presence member entries.
+      ...(platform ? { platform } : {}),
+    },
     timestamp: Date.now(),
   });
 }
@@ -1391,11 +1411,12 @@ export async function setRoomStatusOnce(
   config: RoomClientConfig,
   status: RoomUserStatus,
   statusText?: string | null,
+  platform?: RoomClientPlatform,
 ): Promise<void> {
   const client = new RoomWsClient(config);
   try {
     await client.connect();
-    sendRoomStatus(client, status, statusText);
+    sendRoomStatus(client, status, statusText, platform);
     // STATUS has no ack frame: give the socket a beat to flush before close.
     await new Promise((resolve) => setTimeout(resolve, 200));
   } finally {
@@ -1403,6 +1424,33 @@ export async function setRoomStatusOnce(
   }
 }
 
+/**
+ * Set the caller's room-level attention (notification posture) on a live
+ * client. The relay validates room participation, persists through the
+ * store, and acks with a READ_STATE frame scoped to this room whose
+ * attention map carries the persisted value (readState stays empty: cursors
+ * are untouched). Private per-user state; nothing broadcasts.
+ */
+export async function setRoomAttentionOnClient(
+  client: RoomWsClient,
+  request: { room: string; attention: RoomTopicAttention },
+): Promise<RoomReadStatePayload> {
+  const requestId = randomUUID();
+  const room = normalizeRoomName(request.room);
+  client.send({
+    type: RoomClientMessageType.ROOM_SET_ATTENTION,
+    payload: { requestId, room, attention: request.attention },
+    timestamp: Date.now(),
+  });
+  const result = await client.waitFor(
+    RoomServerMessageType.READ_STATE,
+    (msg) => msg.payload.requestId === requestId,
+    undefined,
+    requestId,
+  );
+  return result.payload;
+}
+
 /** One-shot session helper for the config-based mutation verbs below (the
  *  agent tools' transport: connect, join, act, wait for the echo, close). */
 async function withRoomEcho(

package/src/shared/rooms-protocol.ts

@@ -48,6 +48,7 @@ export const RoomClientMessageType = {
   TOPIC_RESOLVE: "TOPIC_RESOLVE",
   TOPIC_SET_ATTENTION: "TOPIC_SET_ATTENTION",
   TOPIC_LIST: "TOPIC_LIST",
+  ROOM_SET_ATTENTION: "ROOM_SET_ATTENTION",
 } as const;
 
 export type RoomClientMessageType =
@@ -152,6 +153,9 @@ export type RoomRole = "owner" | "admin" | "mod" | "member";
  *  semantics of an absent value). */
 export type RoomTopicsPolicy = "off" | "allowed" | "required";
 export type RoomTopicAttention = "follow" | "default" | "mute";
+/** Self-declared client class on STATUS frames; presence member entries
+ *  carry it through so rosters can render where someone is connected from. */
+export type RoomClientPlatform = "web" | "desktop" | "mobile" | "tui";
 
 export interface RoomMember {
   userId: string;
@@ -166,6 +170,8 @@ export interface RoomMember {
   joinedAt: number;
   avatarUrl?: string | null;
   statusText?: string | null;
+  /** Present when the member's session declared one via STATUS. */
+  platform?: RoomClientPlatform | undefined;
 }
 
 export interface RoomMeta {
@@ -191,6 +197,10 @@ export interface RoomMeta {
    *  2026-07-12 dial-default flip (post-flip relays always advertise the
    *  stored value, "off" included); explicit "off" means topics are inert. */
   topicsPolicy?: RoomTopicsPolicy | undefined;
+  /** The viewer's room attention (notification posture), a per-viewer field
+   *  like viewerRole: surfaced on rooms listings for the caller. Absent
+   *  reads as "default". */
+  attention?: RoomTopicAttention | undefined;
   tags?: string[] | undefined;
   entities?: string[] | undefined;
   sourceRefs?: Array<Record<string, unknown>> | undefined;
@@ -246,14 +256,27 @@ export interface RoomLedgerEntry {
 }
 
 export interface RoomAttachment {
-  /** Object key under room-attachments/; clients sign it at render time. */
-  key: string;
+  /**
+   * Object key under room-attachments/; clients sign it at render time.
+   * Absent while scanStatus is "pending" on entries served to members: the
+   * store withholds the signable key until the scan clears, so render the
+   * metadata as a placeholder and do not attempt signing without a key.
+   */
+  key?: string | undefined;
   name: string;
   size: number;
   mime: string;
   scanStatus?: "pending" | "clean" | "held" | undefined;
 }
 
+/**
+ * A postable attachment reference. Outbound frames must always carry the
+ * stored key (senders reference their own uploads, which include it); only
+ * read views of pending entries may be keyless, and those must never be
+ * forwarded back into a post.
+ */
+export type RoomAttachmentInput = RoomAttachment & { key: string };
+
 /**
  * A registry-backed topic inside a channel. The id is permanent: rename
  * changes `name` only, and links (`om://topic/<topicId>`) keep resolving.
@@ -318,7 +341,12 @@ export interface RoomPinsPayload {
 }
 
 export interface RoomReadStatePayload {
+  /** Partial map: rooms absent from a reply are unchanged. */
   readState: Record<string, number>;
+  /** Per-room attention for the requesting user, keyed like readState.
+   *  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;
   requestId?: string | undefined;
 }
 
@@ -849,6 +877,16 @@ export interface RoomTopicSetAttentionPayload {
   attention: RoomTopicAttention;
 }
 
+/** Room-level attention (notification posture). Private per-user state on
+ *  the caller's read row; topic attention wins for topic-scoped messages
+ *  and room attention wins over space attention. The relay acks with a
+ *  READ_STATE frame scoped to the room (see RoomReadStatePayload). */
+export interface RoomSetAttentionPayload {
+  requestId?: string;
+  room: string;
+  attention: RoomTopicAttention;
+}
+
 export interface RoomTopicListPayload {
   requestId?: string;
   room: string;
@@ -968,7 +1006,7 @@ export type RoomClientMessage =
       payload: {
         room: string;
         text?: string;
-        attachments?: RoomAttachment[];
+        attachments?: RoomAttachmentInput[];
         inReplyTo?: number;
         /** Post directly into a topic; the room's linear stream is unaffected. */
         topicId?: string;
@@ -1116,7 +1154,11 @@ export type RoomClientMessage =
     }
   | {
       type: typeof RoomClientMessageType.STATUS;
-      payload: { status: RoomUserStatus; statusText?: string | null };
+      payload: {
+        status: RoomUserStatus;
+        statusText?: string | null;
+        platform?: RoomClientPlatform;
+      };
       timestamp?: number;
     }
   | {
@@ -1200,6 +1242,11 @@ export type RoomClientMessage =
       type: typeof RoomClientMessageType.TOPIC_LIST;
       payload: RoomTopicListPayload;
       timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.ROOM_SET_ATTENTION;
+      payload: RoomSetAttentionPayload;
+      timestamp?: number;
     };
 
 export type RoomServerMessage =

package/src/social-client.ts

@@ -62,7 +62,10 @@ export type {
   RoomSuggestionSource,
 } from "./social-types.js";
 
-export const ROOM_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** 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. */
+export const ROOM_ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
 
 export class RoomSocialError extends Error {
   override readonly name = "RoomSocialError";
@@ -1097,12 +1100,24 @@ export async function getRoomAttachmentUrl(
   config: RoomSocialConfig,
   room: string,
   key: string,
+  opts: { name?: string; download?: boolean } = {},
 ): Promise<{ url: string; expiresAt: string | null }> {
+  // The object key identifies the object and stays in the query. The
+  // download filename and force-download flag ride REQUEST HEADERS, never
+  // the URL: a private-room filename in the query string leaked into the
+  // relay's access logs and error telemetry (Morgan, Sentry).
   const params = new URLSearchParams({ key });
+  const headers: Record<string, string> = {};
+  // Percent-encode the name: Fetch/HTTP header values are byte strings, so a
+  // raw Unicode filename (报告.py, an emoji) throws a TypeError before the
+  // request is sent. The store decodes with decodeURIComponent.
+  if (opts.name) headers["X-Om-Download-Name"] = encodeURIComponent(opts.name);
+  // Forces a Content-Disposition attachment even for inline mimes.
+  if (opts.download) headers["X-Om-Download"] = "1";
   const result = await socialRequest<{ url?: string; expiresAt?: string | null }>(
     config,
     `/rooms/${encodeURIComponent(cleanRoomId(room))}/attachment-url?${params.toString()}`,
-    { method: "GET" },
+    { method: "GET", headers },
   );
   if (!result.url) {
     throw new RoomSocialError("Attachment sign failed", 502, result);
@@ -1195,6 +1210,7 @@ export async function socialRequest<T>(
     body?: unknown;
     signal?: AbortSignal;
     formData?: FormData;
+    headers?: Record<string, string>;
   } = {},
 ): Promise<T> {
   const url = `${trimTrailingSlash(config.apiUrl)}${path}`;
@@ -1205,6 +1221,7 @@ export async function socialRequest<T>(
       Authorization: `Bearer ${config.apiKey}`,
       Accept: "application/json",
       ...(hasJsonBody ? { "Content-Type": "application/json" } : {}),
+      ...(init.headers ?? {}),
     },
     ...(hasJsonBody
       ? { body: JSON.stringify(init.body) }
@@ -1284,12 +1301,72 @@ function trimTrailingSlash(value: string): string {
   return value.replace(/\/+$/, "");
 }
 
+/** Source/config/text extensions declared as text/plain so the server's
+ *  UTF-8 code-file lane accepts them. Markup extensions the server
+ *  blocklists (html, svg, xml, ...) are deliberately absent: they fall
+ *  through to application/octet-stream and the server rejects them. */
+const CODE_TEXT_EXTENSIONS = new Set([
+  "js",
+  "jsx",
+  "ts",
+  "tsx",
+  "py",
+  "rb",
+  "go",
+  "rs",
+  "java",
+  "c",
+  "h",
+  "cc",
+  "cpp",
+  "hpp",
+  "cs",
+  "php",
+  "sh",
+  "bash",
+  "zsh",
+  "fish",
+  "ps1",
+  "sql",
+  "yaml",
+  "yml",
+  "toml",
+  "ini",
+  "cfg",
+  "conf",
+  "log",
+  "diff",
+  "patch",
+  "tex",
+  "r",
+  "jl",
+  "kt",
+  "kts",
+  "swift",
+  "scala",
+  "clj",
+  "cljs",
+  "ex",
+  "exs",
+  "erl",
+  "lua",
+  "pl",
+  "pm",
+  "dart",
+  "gradle",
+  "properties",
+  "bat",
+  "cmd",
+]);
+
 export function mimeFromFilename(filename: string): string {
   const lower = filename.toLowerCase();
   if (lower.endsWith(".png")) return "image/png";
   if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
   if (lower.endsWith(".webp")) return "image/webp";
   if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".mp4")) return "video/mp4";
+  if (lower.endsWith(".webm")) return "video/webm";
   if (lower.endsWith(".pdf")) return "application/pdf";
   if (lower.endsWith(".txt")) return "text/plain";
   if (lower.endsWith(".md") || lower.endsWith(".markdown")) return "text/markdown";
@@ -1304,5 +1381,7 @@ export function mimeFromFilename(filename: string): string {
   if (lower.endsWith(".pptx")) {
     return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
   }
+  const dot = lower.lastIndexOf(".");
+  if (dot !== -1 && CODE_TEXT_EXTENSIONS.has(lower.slice(dot + 1))) return "text/plain";
   return "application/octet-stream";
 }

package/src/social-types.ts

@@ -53,8 +53,13 @@ export interface RoomFollowResult {
 }
 
 export interface RoomAttachment {
-  /** Object key under room-attachments/; clients sign it at render time. */
-  key: string;
+  /**
+   * Object key under room-attachments/; clients sign it at render time.
+   * Absent while scanStatus is "pending" on entries served to members: the
+   * store withholds the signable key until the scan clears, so render the
+   * metadata as a placeholder and do not attempt signing without a key.
+   */
+  key?: string | undefined;
   name: string;
   size: number;
   mime: string;
@@ -62,8 +67,16 @@ export interface RoomAttachment {
 }
 
 export interface RoomAttachmentUpload {
-  /** The stored attachment plus its first signed URL, for immediate render. */
-  attachment: RoomAttachment & { url: string; expiresAt: string | null };
+  /**
+   * The stored attachment plus its first signed URL, for immediate render.
+   * The uploader always receives the key; only member views of PENDING
+   * entries withhold it.
+   */
+  attachment: RoomAttachment & {
+    key: string;
+    url: string;
+    expiresAt: string | null;
+  };
 }
 
 export interface RoomPublicProfile {
@@ -131,6 +144,9 @@ export interface RoomDmMessage {
   imageUrl?: string | null;
   /** Aggregated reactions (per-emoji userId lists). Additive. */
   reactions?: Array<{ emoji: string; users: string[] }>;
+  /** Client-minted idempotency tag echoed back on DM sends, so a sender's
+   *  durable queue can settle its optimistic row. Additive (0.4.0). */
+  clientMsgId?: string;
 }
 
 export interface RoomDmHistory {

package/src/types.ts

@@ -1,12 +1,14 @@
 export type {
   RoomAccessMode,
   RoomAttachment,
+  RoomAttachmentInput,
   RoomAuditEntry,
   RoomAuditLogPayload,
   RoomAuditLogRequestPayload,
   RoomAuthSuccessPayload,
   RoomBackfillPayload,
   RoomClientMessage,
+  RoomClientPlatform,
   RoomCreatedPayload,
   RoomCreatePayload,
   RoomDmHistoryPayload,
@@ -49,6 +51,7 @@ export type {
   RoomSearchScope,
   RoomServerMessage,
   RoomServerMessageOf,
+  RoomSetAttentionPayload,
   RoomSetReadOnlyPayload,
   RoomSpace,
   RoomSpaceJoinedPayload,