@openmarket/rooms-client 0.5.0 → 0.5.1

package/dist/agent/sidebar-model.d.ts

@@ -22,6 +22,9 @@ export interface SidebarRoom {
     headSeq: number | null;
     lastReadSeq: number | null;
     unread: number;
+    /** Unread mention count from the latest read-state snapshot: the server's
+     *  number verbatim, 0 when the snapshot carried none for this room. */
+    mentionUnread: number;
     joined: boolean;
     /** Topics dial from room meta. Absent reads as "allowed" since the
      *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
@@ -40,6 +43,13 @@ export interface SidebarSnapshot {
     dms: SidebarDm[];
     popular: SidebarRoom[];
     globalReplyUnread: number;
+    /** Per-room unread mention counts exactly as the server sent them in the
+     *  latest read-state snapshot: sparse (zero-count rooms absent) and
+     *  global (rooms outside the current listings may appear). Empty when the
+     *  snapshot carried none; a fresh snapshot replaces it wholesale. */
+    mentionCounts: Record<string, number>;
+    /** User-wide unread mention total from the same snapshot. */
+    mentionTotal: number;
     fetchedAt: number;
 }
 export declare const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot;
@@ -48,10 +58,22 @@ export declare function computeRoomUnread(input: {
     headSeq: number | null;
     lastReadSeq: number | null;
 }): number;
+/** A READ_STATE reply that carries the additive mention decorations beside
+ *  the cursor map (RoomReadStatePayload satisfies this shape). Old
+ *  fetchReadState implementations returning the bare cursor Record keep
+ *  working; mention fields then read as zero. */
+export interface SidebarReadState {
+    readState: Record<string, number>;
+    mentionCounts?: Record<string, number> | undefined;
+    mentionTotal?: number | undefined;
+}
 export declare function buildSidebarSnapshot(input: {
     rooms: RoomMeta[];
     spaces: RoomSpace[];
     readState: Record<string, number>;
+    /** Server numbers pass through verbatim; merge policy is the caller's. */
+    mentionCounts?: Record<string, number> | undefined;
+    mentionTotal?: number | undefined;
     dms: SidebarDm[];
     globalReplyUnread: number;
     joinedUnread: (roomName: string) => number | null;
@@ -60,7 +82,9 @@ export declare function buildSidebarSnapshot(input: {
 export interface SidebarModelDeps {
     fetchRooms: () => Promise<RoomMeta[]>;
     fetchSpaces: () => Promise<RoomSpace[]>;
-    fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+    /** Either the bare cursor Record (the 0.2.0 shape) or a SidebarReadState
+     *  whose mention decorations feed the snapshot's mention fields. */
+    fetchReadState: (roomNames: string[]) => Promise<Record<string, number> | SidebarReadState>;
     fetchDms: () => Promise<SidebarDm[]>;
     fetchGlobalReplyUnread: () => Promise<number>;
     joinedUnread: (roomName: string) => number | null;

package/dist/agent/sidebar-model.js

@@ -4,6 +4,8 @@ export const EMPTY_SIDEBAR_SNAPSHOT = {
     dms: [],
     popular: [],
     globalReplyUnread: 0,
+    mentionCounts: {},
+    mentionTotal: 0,
     fetchedAt: 0,
 };
 const POPULAR_MAX = 6;
@@ -34,6 +36,11 @@ export function buildSidebarSnapshot(input) {
             headSeq,
             lastReadSeq,
             unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+            // Own-key guard like the readState read above: rooms named after
+            // Object.prototype members must read 0 from a sparse map, not NaN.
+            mentionUnread: Math.max(0, input.mentionCounts && Object.hasOwn(input.mentionCounts, name)
+                ? (input.mentionCounts[name] ?? 0)
+                : 0),
             // Joined = an open context OR a server read cursor (you only get a
             // cursor by having been in the room). This is what decides whether a
             // room lives in your channel tree or in the POPULAR discovery shelf.
@@ -92,9 +99,30 @@ export function buildSidebarSnapshot(input) {
         dms: input.dms,
         popular,
         globalReplyUnread: Math.max(0, input.globalReplyUnread),
+        mentionCounts: input.mentionCounts ?? {},
+        mentionTotal: Math.max(0, input.mentionTotal ?? 0),
         fetchedAt: input.now,
     };
 }
+/** A bare cursor Record maps room name to seq (numbers only), so an object
+ *  under the "readState" key can only be the snapshot shape, even for a
+ *  room literally named "readState" (its cursor would be a number). */
+function normalizeSidebarReadState(reply) {
+    const nested = reply.readState;
+    if (typeof nested === "object" && nested !== null) {
+        const snapshot = reply;
+        return {
+            readState: snapshot.readState,
+            mentionCounts: snapshot.mentionCounts,
+            mentionTotal: snapshot.mentionTotal,
+        };
+    }
+    return {
+        readState: reply,
+        mentionCounts: undefined,
+        mentionTotal: undefined,
+    };
+}
 export class SidebarModel {
     deps;
     snapshotValue = EMPTY_SIDEBAR_SNAPSHOT;
@@ -174,13 +202,16 @@ export class SidebarModel {
             this.deps.fetchDms().catch(() => []),
             this.deps.fetchGlobalReplyUnread().catch(() => 0),
         ]);
-        const readState = await this.deps
+        const readStateReply = await this.deps
             .fetchReadState(rooms.map((room) => room.name))
             .catch(() => ({}));
+        const { readState, mentionCounts, mentionTotal } = normalizeSidebarReadState(readStateReply);
         return buildSidebarSnapshot({
             rooms,
             spaces,
             readState,
+            mentionCounts,
+            mentionTotal,
             dms,
             globalReplyUnread,
             joinedUnread: this.deps.joinedUnread,

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

@@ -330,6 +330,16 @@ 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;
+    /** 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
+     *  GLOBAL: every room with a nonzero count appears (requested or not),
+     *  zero-count rooms are absent. Missing on servers older than the
+     *  mentions-completion store. */
+    mentionCounts?: Record<string, number> | undefined;
+    /** User-wide unread mention total (drives the app badge). Rides beside
+     *  mentionCounts; missing on older servers. */
+    mentionTotal?: number | undefined;
     requestId?: string | undefined;
 }
 export interface RoomSearchResultsPayload {

package/dist/social-client.d.ts

@@ -1,5 +1,5 @@
-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";
+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";
 /** 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. */
@@ -368,6 +368,24 @@ export declare function markRoomRepliesRead(config: RoomSocialConfig, options?:
     room?: string;
     before?: string | Date;
 }): Promise<RoomRepliesReadResult>;
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export declare function listRoomNotifications(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;
+    unread?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<RoomNotificationInboxResult>;
 export declare function suggestRooms(config: RoomSocialConfig, request: RoomSuggestionRequest, options?: {
     signal?: AbortSignal;
 }): Promise<RoomSuggestion[]>;

package/dist/social-client.js

@@ -592,6 +592,35 @@ export async function markRoomRepliesRead(config, options = {}) {
     });
     return { markedRead: result.markedRead ?? 0 };
 }
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export async function listRoomNotifications(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);
+    if (options.unread !== undefined)
+        params.set("unread", String(options.unread));
+    const init = {};
+    if (options.signal)
+        init.signal = options.signal;
+    const result = await socialRequest(config, `/users/notifications${params.size ? `?${params.toString()}` : ""}`, init);
+    return {
+        notifications: result.notifications ?? [],
+        hasMore: result.hasMore ?? false,
+        lastCursor: result.lastCursor ?? null,
+        lastCursorId: result.lastCursorId ?? null,
+    };
+}
 export async function suggestRooms(config, request, options = {}) {
     const init = {
         method: "POST",

package/dist/social-types.d.ts

@@ -171,6 +171,44 @@ export interface RoomRepliesResult {
 export interface RoomRepliesReadResult {
     markedRead: number;
 }
+/** The room kinds the chat notification inbox returns (the store's
+ *  ROOM_INBOX_NOTIFICATION_TYPES). ROOM_FOLLOW rows stay out of the inbox:
+ *  follow is a push channel, not a badge source. */
+export type RoomNotificationKind = "ROOM_MENTION" | "ROOM_REPLY" | "ROOM_DM" | "ROOM_KEYWORD";
+/** Shared room payload on a notification row, wire names verbatim from the
+ *  store's notification schema (room_message_data). `preview` follows the
+ *  push body rules (140 chars, empty for sealed content); `hash` is the
+ *  client deep link. */
+export interface RoomNotificationMessageData {
+    kind: "dm" | "mention" | "reply" | "follow" | "keyword";
+    room_id?: string;
+    room_name?: string;
+    space_id?: string;
+    conversation_id?: string;
+    seq?: number;
+    from_handle: string;
+    preview: string;
+    hash: string;
+}
+/** One chat notification inbox row: the store's explicit field pick
+ *  (snake_case wire names, dates as ISO strings, room_message_data only
+ *  when the row carries one). */
+export interface RoomNotificationInboxItem {
+    id: string;
+    type: RoomNotificationKind;
+    created_at: string;
+    read_at: string | null;
+    room_message_data?: RoomNotificationMessageData;
+}
+/** A newest-first inbox page plus the composite cursor naming the last row
+ *  returned; feed lastCursor and lastCursorId back together to request the
+ *  next page. Both are null on an empty page. */
+export interface RoomNotificationInboxResult {
+    notifications: RoomNotificationInboxItem[];
+    hasMore: boolean;
+    lastCursor: string | null;
+    lastCursorId: string | null;
+}
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
     docId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmarket/rooms-client",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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/sidebar-model.ts

@@ -23,6 +23,9 @@ export interface SidebarRoom {
   headSeq: number | null;
   lastReadSeq: number | null;
   unread: number;
+  /** Unread mention count from the latest read-state snapshot: the server's
+   *  number verbatim, 0 when the snapshot carried none for this room. */
+  mentionUnread: number;
   joined: boolean;
   /** Topics dial from room meta. Absent reads as "allowed" since the
    *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
@@ -40,6 +43,13 @@ export interface SidebarSnapshot {
   dms: SidebarDm[];
   popular: SidebarRoom[];
   globalReplyUnread: number;
+  /** Per-room unread mention counts exactly as the server sent them in the
+   *  latest read-state snapshot: sparse (zero-count rooms absent) and
+   *  global (rooms outside the current listings may appear). Empty when the
+   *  snapshot carried none; a fresh snapshot replaces it wholesale. */
+  mentionCounts: Record<string, number>;
+  /** User-wide unread mention total from the same snapshot. */
+  mentionTotal: number;
   fetchedAt: number;
 }
 
@@ -49,6 +59,8 @@ export const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot = {
   dms: [],
   popular: [],
   globalReplyUnread: 0,
+  mentionCounts: {},
+  mentionTotal: 0,
   fetchedAt: 0,
 };
 
@@ -65,10 +77,23 @@ export function computeRoomUnread(input: {
   return Math.max(0, input.headSeq - input.lastReadSeq);
 }
 
+/** A READ_STATE reply that carries the additive mention decorations beside
+ *  the cursor map (RoomReadStatePayload satisfies this shape). Old
+ *  fetchReadState implementations returning the bare cursor Record keep
+ *  working; mention fields then read as zero. */
+export interface SidebarReadState {
+  readState: Record<string, number>;
+  mentionCounts?: Record<string, number> | undefined;
+  mentionTotal?: number | undefined;
+}
+
 export function buildSidebarSnapshot(input: {
   rooms: RoomMeta[];
   spaces: RoomSpace[];
   readState: Record<string, number>;
+  /** Server numbers pass through verbatim; merge policy is the caller's. */
+  mentionCounts?: Record<string, number> | undefined;
+  mentionTotal?: number | undefined;
   dms: SidebarDm[];
   globalReplyUnread: number;
   joinedUnread: (roomName: string) => number | null;
@@ -91,6 +116,14 @@ export function buildSidebarSnapshot(input: {
       headSeq,
       lastReadSeq,
       unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+      // Own-key guard like the readState read above: rooms named after
+      // Object.prototype members must read 0 from a sparse map, not NaN.
+      mentionUnread: Math.max(
+        0,
+        input.mentionCounts && Object.hasOwn(input.mentionCounts, name)
+          ? (input.mentionCounts[name] ?? 0)
+          : 0,
+      ),
       // Joined = an open context OR a server read cursor (you only get a
       // cursor by having been in the room). This is what decides whether a
       // room lives in your channel tree or in the POPULAR discovery shelf.
@@ -154,6 +187,8 @@ export function buildSidebarSnapshot(input: {
     dms: input.dms,
     popular,
     globalReplyUnread: Math.max(0, input.globalReplyUnread),
+    mentionCounts: input.mentionCounts ?? {},
+    mentionTotal: Math.max(0, input.mentionTotal ?? 0),
     fetchedAt: input.now,
   };
 }
@@ -161,13 +196,39 @@ export function buildSidebarSnapshot(input: {
 export interface SidebarModelDeps {
   fetchRooms: () => Promise<RoomMeta[]>;
   fetchSpaces: () => Promise<RoomSpace[]>;
-  fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+  /** Either the bare cursor Record (the 0.2.0 shape) or a SidebarReadState
+   *  whose mention decorations feed the snapshot's mention fields. */
+  fetchReadState: (roomNames: string[]) => Promise<Record<string, number> | SidebarReadState>;
   fetchDms: () => Promise<SidebarDm[]>;
   fetchGlobalReplyUnread: () => Promise<number>;
   joinedUnread: (roomName: string) => number | null;
   now?: () => number;
 }
 
+/** A bare cursor Record maps room name to seq (numbers only), so an object
+ *  under the "readState" key can only be the snapshot shape, even for a
+ *  room literally named "readState" (its cursor would be a number). */
+function normalizeSidebarReadState(reply: Record<string, number> | SidebarReadState): {
+  readState: Record<string, number>;
+  mentionCounts: Record<string, number> | undefined;
+  mentionTotal: number | undefined;
+} {
+  const nested = (reply as SidebarReadState).readState;
+  if (typeof nested === "object" && nested !== null) {
+    const snapshot = reply as SidebarReadState;
+    return {
+      readState: snapshot.readState,
+      mentionCounts: snapshot.mentionCounts,
+      mentionTotal: snapshot.mentionTotal,
+    };
+  }
+  return {
+    readState: reply as Record<string, number>,
+    mentionCounts: undefined,
+    mentionTotal: undefined,
+  };
+}
+
 export class SidebarModel {
   private snapshotValue: SidebarSnapshot = EMPTY_SIDEBAR_SNAPSHOT;
   private inflight: Promise<SidebarSnapshot> | null = null;
@@ -243,13 +304,16 @@ export class SidebarModel {
       this.deps.fetchDms().catch(() => [] as SidebarDm[]),
       this.deps.fetchGlobalReplyUnread().catch(() => 0),
     ]);
-    const readState = await this.deps
+    const readStateReply = await this.deps
       .fetchReadState(rooms.map((room) => room.name))
       .catch(() => ({}) as Record<string, number>);
+    const { readState, mentionCounts, mentionTotal } = normalizeSidebarReadState(readStateReply);
     return buildSidebarSnapshot({
       rooms,
       spaces,
       readState,
+      mentionCounts,
+      mentionTotal,
       dms,
       globalReplyUnread,
       joinedUnread: this.deps.joinedUnread,

package/src/shared/rooms-protocol.ts

@@ -370,6 +370,16 @@ 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;
+  /** 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
+   *  GLOBAL: every room with a nonzero count appears (requested or not),
+   *  zero-count rooms are absent. Missing on servers older than the
+   *  mentions-completion store. */
+  mentionCounts?: Record<string, number> | undefined;
+  /** User-wide unread mention total (drives the app badge). Rides beside
+   *  mentionCounts; missing on older servers. */
+  mentionTotal?: number | undefined;
   requestId?: string | undefined;
 }
 

package/src/social-client.ts

@@ -18,6 +18,7 @@ import type {
   RoomFollowResult,
   RoomFriend,
   RoomFriendRequests,
+  RoomNotificationInboxResult,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
@@ -46,6 +47,10 @@ export type {
   RoomFriend,
   RoomFriendRequest,
   RoomFriendRequests,
+  RoomNotificationInboxItem,
+  RoomNotificationInboxResult,
+  RoomNotificationKind,
+  RoomNotificationMessageData,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
@@ -1197,6 +1202,47 @@ export async function markRoomRepliesRead(
   return { markedRead: result.markedRead ?? 0 };
 }
 
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export async function listRoomNotifications(
+  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;
+    unread?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+  } = {},
+): Promise<RoomNotificationInboxResult> {
+  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);
+  if (options.unread !== undefined) params.set("unread", String(options.unread));
+  const init: { signal?: AbortSignal } = {};
+  if (options.signal) init.signal = options.signal;
+  const result = await socialRequest<Partial<RoomNotificationInboxResult>>(
+    config,
+    `/users/notifications${params.size ? `?${params.toString()}` : ""}`,
+    init,
+  );
+  return {
+    notifications: result.notifications ?? [],
+    hasMore: result.hasMore ?? false,
+    lastCursor: result.lastCursor ?? null,
+    lastCursorId: result.lastCursorId ?? null,
+  };
+}
+
 export async function suggestRooms(
   config: RoomSocialConfig,
   request: RoomSuggestionRequest,

package/src/social-types.ts

@@ -192,6 +192,48 @@ export interface RoomRepliesReadResult {
   markedRead: number;
 }
 
+/** The room kinds the chat notification inbox returns (the store's
+ *  ROOM_INBOX_NOTIFICATION_TYPES). ROOM_FOLLOW rows stay out of the inbox:
+ *  follow is a push channel, not a badge source. */
+export type RoomNotificationKind = "ROOM_MENTION" | "ROOM_REPLY" | "ROOM_DM" | "ROOM_KEYWORD";
+
+/** Shared room payload on a notification row, wire names verbatim from the
+ *  store's notification schema (room_message_data). `preview` follows the
+ *  push body rules (140 chars, empty for sealed content); `hash` is the
+ *  client deep link. */
+export interface RoomNotificationMessageData {
+  kind: "dm" | "mention" | "reply" | "follow" | "keyword";
+  room_id?: string;
+  room_name?: string;
+  space_id?: string;
+  conversation_id?: string;
+  seq?: number;
+  from_handle: string;
+  preview: string;
+  hash: string;
+}
+
+/** One chat notification inbox row: the store's explicit field pick
+ *  (snake_case wire names, dates as ISO strings, room_message_data only
+ *  when the row carries one). */
+export interface RoomNotificationInboxItem {
+  id: string;
+  type: RoomNotificationKind;
+  created_at: string;
+  read_at: string | null;
+  room_message_data?: RoomNotificationMessageData;
+}
+
+/** A newest-first inbox page plus the composite cursor naming the last row
+ *  returned; feed lastCursor and lastCursorId back together to request the
+ *  next page. Both are null on an empty page. */
+export interface RoomNotificationInboxResult {
+  notifications: RoomNotificationInboxItem[];
+  hasMore: boolean;
+  lastCursor: string | null;
+  lastCursorId: string | null;
+}
+
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
   docId: string;