@headless-lms/core 0.3.0 → 0.5.0

package/dist/discussion/ports.d.ts

@@ -1,13 +1,13 @@
 import { JsonValue, Page } from "../types/shared.js";
-import { Activity, SpaceDetail } from "../types/schemas/content.js";
-import { Role } from "../types/schemas/organizations.js";
-import { Chat, ChatLastMessage, ChatUser, CommentListItem, CommentView, CommentsConfig, FlaggedComment, ListCommentsQuery, Message, MessageFlag, MessageFlagResolution, MessageView, Post, PostFlag, PostFlagResolution, PostStatus, PostView, ReactionCounts, ReactionEmoji } from "../types/schemas/discussion.js";
-import { Comment, CommentReport } from "../types/discussion.js";
+import { Activity, DmSettings, SpaceDetail } from "../types/schemas/content.js";
+import { Chat, ChatLastMessage, ChatLiveEvent, ChatUnreadSummary, ChatUser, CommentListItem, CommentView, CommentsConfig, DigestRun, FlaggedComment, FlaggedCommentView, ListCommentsQuery, LiveMessage, MentionItemType, Message, MessageFlag, MessageFlagResolution, MessageView, Post, PostFlag, PostFlagResolution, PostStatus, PostView, ReactionCounts, ReactionEmoji, Subscription, SubscriptionItemType, SubscriptionView } from "../types/schemas/discussion.js";
+import { Comment, CommentAuthor, CommentReport } from "../types/discussion.js";
+import { SubjectRef } from "../types/notifications.js";
 import "../types/index.js";
+import { Actor, EffectivePermissions } from "../shared/actor.js";
 import { OutboxAppender, UnitOfWork } from "../shared/ports.js";
-import { Actor } from "../shared/actor.js";
+import { CommunityDigest } from "../content/ports.js";
 import "../content/index.js";
-import "../organizations/index.js";
 import "./model.js";
 import "./types.js";
 //#region src/discussion/ports.d.ts
@@ -27,7 +27,6 @@ interface CommentWithContext {
   activityTitle: string;
 }
 type PostCommentInput = {
-  actor: Actor;
   parentId: string | null;
   body: string;
 } & ({
@@ -38,74 +37,109 @@ type PostCommentInput = {
   activityId?: undefined;
 });
 /** A profile row as the repository loads it, keyed by `org_users.id`. `email`
- *  is stripped before comments are served and kept only for the staff list. */
+ *  is stripped before comments are served and kept only for the moderation list. */
 interface AuthorRecord {
   id: string;
   firstName: string | null;
   lastName: string | null;
   email: string;
   image: string | null;
-  role: Role;
   displayName: string | null;
   headline: string | null;
   imageAssetOrgId: string | null;
   imageAssetId: string | null;
 }
+interface ItemTitle {
+  title: string;
+  excerpt?: string;
+}
+interface ItemTitles {
+  titlesFor(refs: SubjectRef[], actor: Actor): Promise<Record<string, ItemTitle>>;
+}
 interface AuthorProfileReader {
   authorsOf(orgId: string, orgUserIds: string[]): Promise<Record<string, AuthorRecord>>;
 }
+/** Where a comment must be for a moderation call: in one community, on a
+ *  lesson, or anywhere the actor can reach. */
+type CommentWithin = {
+  communityId: string;
+} | 'lesson' | 'any';
 interface DiscussionService {
   /** Post a root comment or a reply. Lands pending where review is required and
-   *  the poster is not staff. */
-  postComment(orgId: string, input: PostCommentInput): Promise<CommentView>;
-  /** Author-only. Throws ForbiddenError for anyone else, staff included. */
-  edit(orgId: string, commentId: string, actor: Actor, body: string): Promise<CommentView>;
-  /** The author, or anyone whose role is staff. */
-  remove(orgId: string, commentId: string, actor: Actor, communityId?: string): Promise<CommentView>;
-  /** Staff only. Returns the comment to published. */
-  restore(orgId: string, commentId: string, actor: Actor, communityId?: string): Promise<CommentView>;
-  /** Staff only. Publishes a pending comment. */
-  approve(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
-  /** Make a comment published, whichever state it is in. Staff only. */
-  publish(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+   *  the poster does not skip review. */
+  postComment(input: PostCommentInput, actor: Actor): Promise<CommentView>;
+  /** Reply to a lesson comment as a moderator of its course; a reply to a reply
+   *  attaches to its root. */
+  replyToComment(commentId: string, body: string, actor: Actor): Promise<CommentView>;
+  /** Author-only. Throws ForbiddenError for anyone else, moderators included. */
+  edit(commentId: string, body: string, actor: Actor): Promise<CommentView>;
+  /** The author, or a moderator of where the comment is. */
+  remove(commentId: string, within: CommentWithin, actor: Actor): Promise<CommentView>;
+  /** A moderator of where the comment is. Returns the comment to published. */
+  restore(commentId: string, within: CommentWithin, actor: Actor): Promise<CommentView>;
+  /** A moderator of where the comment is. Publishes a pending comment. */
+  approve(commentId: string, actor: Actor): Promise<Comment>;
+  /** Make a comment published, whichever state it is in. A moderator of where
+   *  the comment is. */
+  publish(commentId: string, within: CommentWithin, actor: Actor): Promise<Comment>;
   /** The activity's comments as this reader may see them. */
-  activityComments(orgId: string, activityId: string, actor: Actor): Promise<ActivityComments>;
+  activityComments(activityId: string, actor: Actor): Promise<ActivityComments>;
   /** One page of top-level comments, oldest first, each with its replies. */
-  postComments(orgId: string, postId: string, actor: Actor, query: PageQuery): Promise<Page<CommentView>>;
-  /**
-   * The org's comments, filtered. Staff-scoped: rows carry the author's email
-   * and a removed comment's body, neither of which a learner may see, so the
-   * edge admits only staff.
-   *
-   * No rule is applied beyond the filters — this is what exists, not what
-   * someone is allowed to read.
-   */
-  listComments(orgId: string, query: ListCommentsQuery): Promise<Page<CommentListItem>>;
-  setReaction(orgId: string, commentId: string, actor: Actor, emoji: ReactionEmoji | null): Promise<CommentReactions>;
-  resolveReports(orgId: string, commentId: string, actor: Actor, communityId?: string): Promise<void>;
+  postComments(postId: string, query: PageQuery, actor: Actor): Promise<Page<CommentView>>;
+  /** The lesson comments of the courses the actor moderates, filtered. Rows
+   *  carry the author's email and a removed comment's body. */
+  listComments(query: ListCommentsQuery, actor: Actor): Promise<Page<CommentListItem>>;
+  setReaction(commentId: string, emoji: ReactionEmoji | null, actor: Actor): Promise<CommentReactions>;
+  resolveReports(commentId: string, within: CommentWithin, actor: Actor): Promise<void>;
   /** Accepted even on locked comments — a locked activity can still hold
    *  something a moderator needs to see. */
-  reportComment(orgId: string, commentId: string, actor: Actor, reason: string): Promise<CommentReport>;
+  reportComment(commentId: string, reason: string, actor: Actor): Promise<CommentReport>;
   /** Plain read of one comment — no rules applied. */
   getComment(orgId: string, commentId: string): Promise<Comment | null>;
-  sendDigest(orgId: string, now: Date): Promise<void>;
+  commenterIds(orgId: string, target: {
+    postId: string;
+  } | {
+    activityId: string;
+  }): Promise<string[]>;
 }
 interface ContentAccessReader {
   hasAccess(orgId: string, orgUserId: string, contentId: string): Promise<boolean>;
 }
 interface ActivityGetter {
-  getActivity(orgId: string, activityId: string): Promise<Activity | null>;
+  getActivity(activityId: string, actor: Actor): Promise<Activity | null>;
+}
+interface SpaceReader {
+  getSpace(spaceId: string, actor: Actor): Promise<SpaceDetail | null>;
+  getDmSettings(communityId: string, actor: Actor): Promise<DmSettings | null>;
+}
+interface OpenableSpace {
+  id: string;
+  communityId: string;
+  accessRule: SpaceDetail['accessRule'];
+}
+interface CommunityAccess {
+  isCommunityMember(communityId: string, actor: Actor): Promise<boolean>;
+  canOpenSpace(spaceId: string, actor: Actor): Promise<boolean>;
+  canOpen(space: OpenableSpace, actor: Actor): Promise<boolean>;
+  openSpaceIds(communityId: string, actor: Actor): Promise<string[]>;
+  communityMembersAmong(orgId: string, communityId: string, orgUserIds: string[]): Promise<string[]>;
+  spaceOpenersAmong(orgId: string, spaceId: string, orgUserIds: string[]): Promise<string[]>;
 }
 interface DiscussionRepository extends PostCommentReader, AuthorProfileReader {
   insertComment(orgId: string, comment: Comment): Promise<Comment>;
   findComment(orgId: string, id: string): Promise<Comment | null>;
+  commenterIds(orgId: string, target: {
+    postId: string;
+  } | {
+    activityId: string;
+  }): Promise<string[]>;
   updateComment(orgId: string, id: string, patch: Partial<Pick<Comment, 'body' | 'status' | 'removedBy' | 'updatedAt'>>): Promise<Comment | null>;
   /** Every comment on the activity, oldest first, including removed ones. */
   listByActivity(orgId: string, activityId: string): Promise<Comment[]>;
   /** A page of the post's top-level threads the viewer can see, oldest first, with their replies. `total` counts threads. */
   listThreadsByPost(orgId: string, postId: string, query: PostThreadsQuery): Promise<Page<Comment>>;
   reactionsOf(orgId: string, commentIds: string[], viewerId: string): Promise<Record<string, CommentReactions>>;
-  setReaction(orgId: string, commentId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<void>;
+  setReaction(orgId: string, commentId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<boolean>;
   /** Returns null when this person has already reported this comment. */
   insertReport(orgId: string, report: CommentReport): Promise<CommentReport | null>;
   /** Every unresolved report against the given comments. */
@@ -115,18 +149,21 @@ interface DiscussionRepository extends PostCommentReader, AuthorProfileReader {
     resolvedBy: string;
     resolution: 'dismissed' | 'removed';
   }): Promise<void>;
-  listComments(orgId: string, query: ListCommentsQuery): Promise<Page<CommentWithContext>>;
+  /** `courseIds` limits the rows to those courses; undefined means every course. */
+  listComments(orgId: string, query: ListCommentsQuery, courseIds?: string[]): Promise<Page<CommentWithContext>>;
 }
 /** Writes that emit events run through this scope so the row and the outbox
  *  entry commit in one transaction. */
 interface DiscussionWriteScope {
   discussion: DiscussionRepository;
+  mentions: MentionsRepository;
   outbox: OutboxAppender;
 }
 type DiscussionUnitOfWork = UnitOfWork<DiscussionWriteScope>;
-interface AuthorRoleReader {
-  roleOf(orgId: string, orgUserId: string): Promise<Role | null>;
-  rolesOf(orgId: string, orgUserIds: string[]): Promise<Record<string, Role>>;
+interface AuthorPermissionReader {
+  permissionsOfMany(orgId: string, orgUserIds: string[]): Promise<Map<string, EffectivePermissions>>;
+  actorFor(orgId: string, orgUserId: string): Promise<Actor | null>;
+  systemActor(orgId: string): Actor;
 }
 type PostMode = 'draft' | 'submit' | 'schedule';
 interface CreatePostInput {
@@ -169,68 +206,74 @@ declare const MODERATION_QUEUE_LIMIT = 100;
 interface SpaceModerationQueue {
   pending: PostView[];
   flags: PostFlag[];
-  commentFlags: FlaggedComment[];
+  commentFlags: FlaggedCommentView[];
 }
 interface PostCommentReader {
   listOpenFlagsForSpace(orgId: string, spaceId: string, limit: number): Promise<FlaggedComment[]>;
   publishedCommentCounts(orgId: string, postIds: string[]): Promise<Record<string, number>>;
 }
+interface PublishedPost {
+  postId: string;
+  spaceId: string;
+  title: string;
+  orgUserId: string;
+  commentCount: number;
+}
 interface PostService {
-  visibleTitles(orgId: string, actor: Actor, postIds: string[]): Promise<Record<string, string>>;
-  create(orgId: string, actor: Actor, input: CreatePostInput): Promise<PostView>;
-  update(orgId: string, postId: string, actor: Actor, patch: UpdatePostInput): Promise<PostView>;
-  submit(orgId: string, postId: string, actor: Actor): Promise<PostView>;
-  schedule(orgId: string, postId: string, actor: Actor, scheduledAt: Date): Promise<PostView>;
-  approve(orgId: string, postId: string, actor: Actor, communityId?: string): Promise<PostView>;
-  remove(orgId: string, postId: string, actor: Actor, communityId?: string): Promise<PostView>;
-  restore(orgId: string, postId: string, actor: Actor, communityId?: string): Promise<PostView>;
-  pin(orgId: string, postId: string, actor: Actor): Promise<PostView>;
-  unpin(orgId: string, postId: string, actor: Actor): Promise<PostView>;
-  closeComments(orgId: string, postId: string, actor: Actor): Promise<PostView>;
-  openComments(orgId: string, postId: string, actor: Actor): Promise<PostView>;
-  setReactions(orgId: string, postId: string, actor: Actor, enabled: boolean): Promise<PostView>;
-  setReaction(orgId: string, postId: string, actor: Actor, emoji: ReactionEmoji | null): Promise<PostReactions>;
-  follow(orgId: string, postId: string, actor: Actor): Promise<void>;
-  unfollow(orgId: string, postId: string, actor: Actor): Promise<void>;
-  bookmark(orgId: string, postId: string, actor: Actor): Promise<void>;
-  unbookmark(orgId: string, postId: string, actor: Actor): Promise<void>;
-  flag(orgId: string, postId: string, actor: Actor, reason: string): Promise<PostFlag>;
-  resolveFlags(orgId: string, postId: string, actor: Actor, resolution: Extract<PostFlagResolution, 'dismissed'>, communityId?: string): Promise<void>;
-  spaceFeed(orgId: string, actor: Actor, communityId: string, spaceId: string, query: FeedQuery): Promise<Page<PostView>>;
-  memberFeed(orgId: string, actor: Actor, communityId: string, query: Pick<FeedQuery, 'page' | 'pageSize'>): Promise<Page<PostView>>;
-  listOwn(orgId: string, actor: Actor, communityId: string, query: PageQuery): Promise<Page<PostView>>;
-  listBookmarked(orgId: string, actor: Actor, communityId: string, query: PageQuery): Promise<Page<PostView>>;
+  visibleTitles(postIds: string[], actor: Actor): Promise<Record<string, string>>;
+  publishedBetween(orgId: string, communityId: string, from: Date, to: Date): Promise<PublishedPost[]>;
+  create(input: CreatePostInput, actor: Actor): Promise<PostView>;
+  update(postId: string, patch: UpdatePostInput, actor: Actor): Promise<PostView>;
+  submit(postId: string, actor: Actor): Promise<PostView>;
+  schedule(postId: string, scheduledAt: Date, actor: Actor): Promise<PostView>;
+  unschedule(postId: string, actor: Actor): Promise<PostView>;
+  publishScheduled(orgId: string, postId: string, now: Date): Promise<void>;
+  approve(postId: string, communityId: string | null, actor: Actor): Promise<PostView>;
+  remove(postId: string, communityId: string | null, actor: Actor): Promise<PostView>;
+  restore(postId: string, communityId: string | null, actor: Actor): Promise<PostView>;
+  pin(postId: string, actor: Actor): Promise<PostView>;
+  unpin(postId: string, actor: Actor): Promise<PostView>;
+  closeComments(postId: string, actor: Actor): Promise<PostView>;
+  openComments(postId: string, actor: Actor): Promise<PostView>;
+  setReactions(postId: string, enabled: boolean, actor: Actor): Promise<PostView>;
+  setReaction(postId: string, emoji: ReactionEmoji | null, actor: Actor): Promise<PostReactions>;
+  bookmark(postId: string, actor: Actor): Promise<void>;
+  unbookmark(postId: string, actor: Actor): Promise<void>;
+  flag(postId: string, reason: string, actor: Actor): Promise<PostFlag>;
+  resolveFlags(postId: string, resolution: Extract<PostFlagResolution, 'dismissed'>, communityId: string | null, actor: Actor): Promise<void>;
+  spaceFeed(communityId: string, spaceId: string, query: FeedQuery, actor: Actor): Promise<Page<PostView>>;
+  memberFeed(communityId: string, query: Pick<FeedQuery, 'page' | 'pageSize'>, actor: Actor): Promise<Page<PostView>>;
+  listOwn(communityId: string, query: PageQuery, actor: Actor): Promise<Page<PostView>>;
+  listBookmarked(communityId: string, query: PageQuery, actor: Actor): Promise<Page<PostView>>;
   /** Signed URL of the post's cover, for whoever can read the post. */
-  coverFile(orgId: string, actor: Actor, postId: string): Promise<string | null>;
-  getPost(orgId: string, actor: Actor, postId: string): Promise<PostView>;
-  visible(orgId: string, actor: Actor, postId: string): Promise<{
+  coverFile(postId: string, actor: Actor): Promise<string>;
+  assetFile(postId: string, assetId: string, actor: Actor): Promise<string>;
+  getPost(postId: string, actor: Actor): Promise<PostView>;
+  visible(postId: string, actor: Actor): Promise<{
     post: Post;
     space: SpaceDetail;
   }>;
   find(orgId: string, postId: string): Promise<Post | null>;
-  followerIds(orgId: string, postId: string): Promise<string[]>;
-  moderationQueue(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceModerationQueue>;
-  publishDue(orgId: string, now: Date): Promise<void>;
-  hasDue(orgId: string, now: Date): Promise<boolean>;
+  moderationQueue(communityId: string, spaceId: string, actor: Actor): Promise<SpaceModerationQueue>;
+}
+interface PostGuard {
+  status: PostStatus;
+  scheduledAt?: Date;
+  dueBy?: Date;
 }
 interface PostRepository {
   insert(orgId: string, post: Post): Promise<Post>;
   update(orgId: string, id: string, patch: PostPatch): Promise<Post | null>;
+  updateIf(orgId: string, id: string, guard: PostGuard, patch: PostPatch): Promise<Post | null>;
   find(orgId: string, id: string): Promise<Post | null>;
   findMany(orgId: string, ids: string[]): Promise<Post[]>;
+  publishedBetween(orgId: string, communityId: string, from: Date, to: Date): Promise<PublishedPost[]>;
   listPublished(orgId: string, spaceIds: string[], query: FeedQuery): Promise<Page<Post>>;
   listByAuthor(orgId: string, orgUserId: string, spaceIds: string[], query: PageQuery): Promise<Page<Post>>;
   listBookmarked(orgId: string, orgUserId: string, spaceIds: string[], query: BookmarkQuery): Promise<Page<Post>>;
   listPending(orgId: string, spaceId: string, limit: number): Promise<Post[]>;
-  /** Due scheduled posts in id order, after `afterId` when given. */
-  listDue(orgId: string, now: Date, limit: number, afterId?: string): Promise<Post[]>;
-  hasDue(orgId: string, now: Date): Promise<boolean>;
   reactionsOf(orgId: string, postIds: string[], viewerId: string): Promise<Record<string, PostReactions>>;
-  setReaction(orgId: string, postId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<void>;
-  follow(orgId: string, postId: string, orgUserId: string): Promise<void>;
-  unfollow(orgId: string, postId: string, orgUserId: string): Promise<void>;
-  followerIds(orgId: string, postId: string): Promise<string[]>;
-  followedAmong(orgId: string, postIds: string[], orgUserId: string): Promise<string[]>;
+  setReaction(orgId: string, postId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<boolean>;
   bookmark(orgId: string, postId: string, orgUserId: string): Promise<void>;
   unbookmark(orgId: string, postId: string, orgUserId: string): Promise<void>;
   bookmarkedAmong(orgId: string, postIds: string[], orgUserId: string): Promise<string[]>;
@@ -245,9 +288,25 @@ interface PostRepository {
 }
 interface PostWriteScope {
   posts: PostRepository;
+  mentions: MentionsRepository;
   outbox: OutboxAppender;
 }
 type PostUnitOfWork = UnitOfWork<PostWriteScope>;
+interface DigestScheduleReader {
+  communitiesWithDigest(): Promise<CommunityDigest[]>;
+}
+interface DigestRunRepository {
+  listRuns(): Promise<DigestRun[]>;
+  advance(orgId: string, communityId: string, dueAt: Date): Promise<boolean>;
+}
+interface DigestWriteScope {
+  digests: DigestRunRepository;
+  outbox: OutboxAppender;
+}
+type DigestUnitOfWork = UnitOfWork<DigestWriteScope>;
+interface DigestService {
+  openDue(now: Date): Promise<void>;
+}
 interface StartDirectInput {
   communityId: string;
   orgUserId: string;
@@ -262,16 +321,62 @@ interface SendMessageInput {
   body: string;
   replyToId: string | null;
   assetIds: string[];
+  clientId?: string;
 }
 interface ChatListItem {
   chat: Chat;
   participantIds: string[];
+  participants: CommentAuthor[];
   lastReadMessageId: string | null;
-  muted: boolean;
-  mutedUntil: Date | null;
+  subscription: SubscriptionView | null;
   unread: number;
   lastMessage: ChatLastMessage | null;
 }
+type ChatInboxRow = Omit<ChatListItem, 'subscription' | 'participants'>;
+/** `requests`: true for only the pending requests to the member, false for
+ *  everything else, omitted for every chat. */
+interface ChatListQuery extends PageQuery {
+  requests?: boolean;
+}
+interface ReactionChange {
+  inserted: boolean;
+  changed: boolean;
+}
+interface ChatMemberState {
+  chatId: string;
+  unread: number;
+  lastReadMessageId: string | null;
+  subscription: SubscriptionView | null;
+}
+/** A member's state in each chat they are in in one community, with their
+ *  unread total there. */
+interface ChatMemberStates {
+  orgUserId: string;
+  unread: ChatUnreadSummary;
+  chats: ChatMemberState[];
+}
+interface LiveChat {
+  chat: Chat;
+  participantIds: string[];
+  participants: CommentAuthor[];
+}
+/** What the chat hub reads for each change, as current state. */
+interface ChatLiveReads {
+  activeParticipants(orgId: string, chatId: string): Promise<string[]>;
+  messageViews(orgId: string, messageIds: string[]): Promise<LiveMessage[]>;
+  messageReactions(orgId: string, messageId: string): Promise<ReactionCounts>;
+  /** The chat with its active participants and their profiles. */
+  liveChat(orgId: string, chatId: string): Promise<LiveChat | null>;
+  memberStates(orgId: string, communityId: string, orgUserIds: string[]): Promise<ChatMemberStates[]>;
+}
+interface ChatUnread {
+  count: number;
+  latest: {
+    messageId: string;
+    senderOrgUserId: string;
+    body: string;
+  } | null;
+}
 interface MessageReactions {
   reactions: ReactionCounts;
   viewerReaction?: ReactionEmoji;
@@ -289,38 +394,48 @@ interface MessageQueueEntry {
 interface MessageQueue {
   entries: MessageQueueEntry[];
 }
-interface ChatService {
-  startDirect(orgId: string, actor: Actor, input: StartDirectInput): Promise<Chat>;
-  startGroup(orgId: string, actor: Actor, input: StartGroupInput): Promise<Chat>;
-  addParticipant(orgId: string, actor: Actor, chatId: string, orgUserId: string): Promise<Chat>;
-  leave(orgId: string, actor: Actor, chatId: string): Promise<Chat>;
-  accept(orgId: string, actor: Actor, chatId: string): Promise<Chat>;
-  send(orgId: string, actor: Actor, chatId: string, input: SendMessageInput): Promise<MessageView>;
-  editMessage(orgId: string, actor: Actor, messageId: string, body: string): Promise<MessageView>;
-  deleteMessage(orgId: string, actor: Actor, messageId: string): Promise<MessageView>;
-  setReaction(orgId: string, actor: Actor, messageId: string, emoji: ReactionEmoji | null): Promise<MessageReactions>;
-  markRead(orgId: string, actor: Actor, chatId: string, messageId: string): Promise<void>;
-  mute(orgId: string, actor: Actor, chatId: string, until?: Date): Promise<void>;
-  unmute(orgId: string, actor: Actor, chatId: string): Promise<void>;
-  block(orgId: string, actor: Actor, communityId: string, orgUserId: string): Promise<void>;
-  unblock(orgId: string, actor: Actor, communityId: string, orgUserId: string): Promise<void>;
-  flagMessage(orgId: string, actor: Actor, messageId: string, reason: string): Promise<MessageFlag>;
-  resolveMessageFlags(orgId: string, actor: Actor, messageId: string, resolution: Extract<MessageFlagResolution, 'dismissed'>, communityId?: string): Promise<void>;
-  lock(orgId: string, actor: Actor, chatId: string, communityId?: string): Promise<Chat>;
-  unlock(orgId: string, actor: Actor, chatId: string, communityId?: string): Promise<Chat>;
-  listChats(orgId: string, actor: Actor, communityId: string, query: PageQuery): Promise<Page<ChatListItem>>;
+interface ChatService extends ChatLiveReads {
+  startDirect(input: StartDirectInput, actor: Actor): Promise<Chat>;
+  startGroup(input: StartGroupInput, actor: Actor): Promise<Chat>;
+  addParticipant(chatId: string, orgUserId: string, actor: Actor): Promise<Chat>;
+  leave(chatId: string, actor: Actor): Promise<Chat>;
+  accept(chatId: string, actor: Actor): Promise<Chat>;
+  send(chatId: string, input: SendMessageInput, actor: Actor): Promise<MessageView>;
+  editMessage(messageId: string, body: string, actor: Actor): Promise<MessageView>;
+  deleteMessage(messageId: string, actor: Actor): Promise<MessageView>;
+  setReaction(messageId: string, emoji: ReactionEmoji | null, actor: Actor): Promise<MessageReactions>;
+  markRead(chatId: string, messageId: string, actor: Actor): Promise<void>;
+  block(communityId: string, orgUserId: string, actor: Actor): Promise<void>;
+  unblock(communityId: string, orgUserId: string, actor: Actor): Promise<void>;
+  flagMessage(messageId: string, reason: string, actor: Actor): Promise<MessageFlag>;
+  resolveMessageFlags(messageId: string, resolution: Extract<MessageFlagResolution, 'dismissed'>, communityId: string | null, actor: Actor): Promise<void>;
+  lock(chatId: string, communityId: string | null, actor: Actor): Promise<Chat>;
+  unlock(chatId: string, communityId: string | null, actor: Actor): Promise<Chat>;
+  listChats(communityId: string, query: ChatListQuery, actor: Actor): Promise<Page<ChatListItem>>;
+  /** One live stream of the member's chat events in the community. */
+  watch(communityId: string, actor: Actor): Promise<AsyncIterable<ChatLiveEvent>>;
+  chat(chatId: string, actor: Actor): Promise<ChatListItem>;
+  directChat(communityId: string, orgUserId: string, actor: Actor): Promise<ChatListItem>;
+  unreadSummary(communityId: string, actor: Actor): Promise<ChatUnreadSummary>;
+  typing(chatId: string, actor: Actor): Promise<void>;
+  /** The messages as every participant sees them: a deleted message without
+   *  its body, attachments or mentions, and no viewer reaction. */
+  messageViews(orgId: string, messageIds: string[]): Promise<LiveMessage[]>;
   chatSummary(orgId: string, chatId: string): Promise<{
     chat: Chat;
     participants: ChatUser[];
   } | null>;
   latestMessageBody(orgId: string, chatId: string): Promise<string | null>;
+  unreadInChat(orgId: string, chatId: string, orgUserId: string): Promise<ChatUnread>;
+  findMessage(orgId: string, messageId: string): Promise<Message | null>;
   isBlocked(orgId: string, communityId: string, a: string, b: string): Promise<boolean>;
-  titlesFor(orgId: string, actor: Actor, chatIds: string[]): Promise<Record<string, string>>;
-  messages(orgId: string, actor: Actor, chatId: string, query: Pick<FeedQuery, 'page' | 'pageSize'>): Promise<Page<MessageView>>;
+  titlesFor(chatIds: string[], actor: Actor): Promise<Record<string, string>>;
+  messages(chatId: string, query: Pick<FeedQuery, 'page' | 'pageSize'>, actor: Actor): Promise<Page<MessageView>>;
   /** Signed URL of a message attachment: for the chat's participants while the
-   *  message stands (staff also after deletion), and for staff while it is flagged. */
-  attachmentFile(orgId: string, actor: Actor, chatId: string, messageId: string, assetId: string): Promise<string | null>;
-  messageQueue(orgId: string, actor: Actor, communityId: string): Promise<MessageQueue>;
+   *  message stands (moderators also after deletion), and for moderators while
+   *  it is flagged. */
+  attachmentFile(chatId: string, messageId: string, assetId: string, actor: Actor): Promise<string>;
+  messageQueue(communityId: string, actor: Actor): Promise<MessageQueue>;
 }
 interface ChatRepository {
   lockDirectPair(orgId: string, communityId: string, orgUserId: string, otherOrgUserId: string): Promise<void>;
@@ -328,12 +443,22 @@ interface ChatRepository {
   insertChat(orgId: string, chat: Chat): Promise<Chat>;
   updateChat(orgId: string, id: string, patch: Partial<Pick<Chat, 'status' | 'lockedAt' | 'lockedBy'>>): Promise<Chat | null>;
   findChat(orgId: string, id: string): Promise<Chat | null>;
-  listForUser(orgId: string, communityId: string, orgUserId: string, query: PageQuery): Promise<Page<ChatListItem>>;
+  listForUser(orgId: string, communityId: string, orgUserId: string, query: ChatListQuery): Promise<Page<ChatInboxRow>>;
+  /** The member's inbox row for one chat they are in, or null. */
+  inboxRow(orgId: string, chatId: string, orgUserId: string): Promise<ChatInboxRow | null>;
   participants(orgId: string, chatId: string): Promise<ChatUser[]>;
+  activeParticipants(orgId: string, chatId: string): Promise<string[]>;
   join(orgId: string, user: ChatUser): Promise<void>;
   markLeft(orgId: string, chatId: string, orgUserId: string, leftAt: Date): Promise<void>;
-  setRead(orgId: string, chatId: string, orgUserId: string, messageId: string): Promise<void>;
-  setMuted(orgId: string, chatId: string, orgUserId: string, muted: boolean, mutedUntil: Date | null): Promise<void>;
+  /** Moves the read mark to the message only when it is newer (by created
+   *  time, then id) than the current one. True when it moved. */
+  setRead(orgId: string, chatId: string, orgUserId: string, messageId: string): Promise<boolean>;
+  unreadFor(orgId: string, chatId: string, orgUserId: string): Promise<ChatUnread>;
+  /** Unread messages across the member's chats in the community that are
+   *  neither muted at `at` nor pending requests to them, plus those requests. */
+  unreadSummary(orgId: string, communityId: string, orgUserId: string, at: Date): Promise<ChatUnreadSummary>;
+  memberStates(orgId: string, communityId: string, orgUserIds: string[], at: Date): Promise<ChatMemberStates[]>;
+  findByClientId(orgId: string, chatId: string, orgUserId: string, clientId: string): Promise<Message | null>;
   insertMessage(orgId: string, message: Message): Promise<Message>;
   updateMessage(orgId: string, id: string, patch: Partial<Pick<Message, 'body' | 'editedAt' | 'deletedAt'>>): Promise<Message | null>;
   findMessage(orgId: string, id: string): Promise<Message | null>;
@@ -341,7 +466,7 @@ interface ChatRepository {
   attach(orgId: string, communityId: string, messageId: string, assetIds: string[]): Promise<void>;
   attachmentsOf(orgId: string, messageIds: string[]): Promise<Record<string, string[]>>;
   blockedWith(orgId: string, communityId: string, orgUserId: string, otherIds: string[]): Promise<string[]>;
-  setReaction(orgId: string, communityId: string, messageId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<void>;
+  setReaction(orgId: string, communityId: string, messageId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<ReactionChange>;
   reactionsOf(orgId: string, messageIds: string[], viewerId: string): Promise<Record<string, MessageReactions>>;
   block(orgId: string, communityId: string, blockerOrgUserId: string, blockedOrgUserId: string): Promise<void>;
   unblock(orgId: string, communityId: string, blockerOrgUserId: string, blockedOrgUserId: string): Promise<void>;
@@ -365,9 +490,49 @@ interface ChatRepository {
 }
 interface ChatWriteScope {
   chats: ChatRepository;
+  mentions: MentionsRepository;
   outbox: OutboxAppender;
 }
 type ChatUnitOfWork = UnitOfWork<ChatWriteScope>;
+type SubscriptionInput = {
+  state: 'following';
+} | {
+  state: 'muted';
+  mutedUntil?: Date | null;
+} | {
+  state: 'none';
+};
+type MuteInput = Exclude<SubscriptionInput, {
+  state: 'following';
+}>;
+interface SubscriptionWriteScope {
+  subscriptions: SubscriptionsRepository;
+  outbox: OutboxAppender;
+}
+type SubscriptionUnitOfWork = UnitOfWork<SubscriptionWriteScope>;
+interface SubscriptionService {
+  setPost(postId: string, input: SubscriptionInput, actor: Actor): Promise<void>;
+  setSpace(spaceId: string, input: MuteInput, actor: Actor): Promise<void>;
+  setChat(chatId: string, input: MuteInput, actor: Actor): Promise<void>;
+  viewerSubscriptions(orgId: string, orgUserId: string, itemType: SubscriptionItemType, itemIds: string[], at: Date): Promise<Record<string, SubscriptionView>>;
+  followerIds(orgId: string, postId: string): Promise<string[]>;
+  mutedAmong(orgId: string, item: SubjectRef, orgUserIds: string[], at: Date): Promise<string[]>;
+  itemSubscriptions(orgId: string, item: SubjectRef): Promise<Subscription[]>;
+}
+interface SubscriptionsRepository {
+  upsert(orgId: string, subscription: Subscription): Promise<void>;
+  remove(orgId: string, orgUserId: string, itemType: SubscriptionItemType, itemId: string): Promise<void>;
+  forViewer(orgId: string, orgUserId: string, itemType: SubscriptionItemType, itemIds: string[]): Promise<Subscription[]>;
+  ofItem(orgId: string, itemType: SubscriptionItemType, itemId: string): Promise<Subscription[]>;
+  followerIds(orgId: string, postId: string): Promise<string[]>;
+  mutedAmong(orgId: string, itemType: SubscriptionItemType, itemId: string, orgUserIds: string[], at: Date): Promise<string[]>;
+}
+interface MentionsRepository {
+  ofItem(orgId: string, itemType: MentionItemType, itemId: string): Promise<string[]>;
+  forItems(orgId: string, itemType: MentionItemType, itemIds: string[]): Promise<Record<string, string[]>>;
+  sync(orgId: string, itemType: MentionItemType, itemId: string, orgUserIds: string[], at: Date): Promise<string[]>;
+  removeItem(orgId: string, itemType: MentionItemType, itemId: string): Promise<void>;
+}
 //#endregion
-export { ActivityComments, ActivityGetter, type Actor, AuthorProfileReader, AuthorRecord, AuthorRoleReader, BookmarkQuery, ChatListItem, ChatRepository, ChatService, ChatSummary, ChatUnitOfWork, ChatWriteScope, CommentReactions, CommentWithContext, ContentAccessReader, CreatePostInput, DiscussionRepository, DiscussionService, DiscussionUnitOfWork, DiscussionWriteScope, FeedQuery, MODERATION_QUEUE_LIMIT, MessageQueue, MessageQueueEntry, MessageReactions, PageQuery, PostCommentInput, PostCommentReader, PostMode, PostPatch, PostReactions, PostRepository, PostService, PostThreadsQuery, PostUnitOfWork, PostWriteScope, SendMessageInput, SpaceModerationQueue, StartDirectInput, StartGroupInput, UpdatePostInput };
+export { ActivityComments, ActivityGetter, type Actor, AuthorPermissionReader, AuthorProfileReader, AuthorRecord, BookmarkQuery, ChatInboxRow, ChatListItem, ChatListQuery, ChatLiveReads, ChatMemberState, ChatMemberStates, ChatRepository, ChatService, ChatSummary, ChatUnitOfWork, ChatUnread, ChatWriteScope, CommentReactions, CommentWithContext, CommentWithin, CommunityAccess, ContentAccessReader, CreatePostInput, DigestRunRepository, DigestScheduleReader, DigestService, DigestUnitOfWork, DigestWriteScope, DiscussionRepository, DiscussionService, DiscussionUnitOfWork, DiscussionWriteScope, FeedQuery, ItemTitle, ItemTitles, LiveChat, MODERATION_QUEUE_LIMIT, MentionsRepository, MessageQueue, MessageQueueEntry, MessageReactions, MuteInput, OpenableSpace, PageQuery, PostCommentInput, PostCommentReader, PostGuard, PostMode, PostPatch, PostReactions, PostRepository, PostService, PostThreadsQuery, PostUnitOfWork, PostWriteScope, PublishedPost, ReactionChange, SendMessageInput, SpaceModerationQueue, SpaceReader, StartDirectInput, StartGroupInput, SubscriptionInput, SubscriptionService, SubscriptionUnitOfWork, SubscriptionWriteScope, SubscriptionsRepository, UpdatePostInput };
 //# sourceMappingURL=ports.d.ts.map