@openmarket/rooms-client 0.1.0

package/src/social-types.ts

@@ -0,0 +1,376 @@
+import type { RoomLedgerSecretPayload } from "./shared/rooms-protocol.js";
+
+export interface RoomSocialConfig {
+  apiUrl: string;
+  apiKey: string;
+}
+
+export type RoomSuggestionSource = "init" | "alert_create" | "market_lookup" | "status" | "digest";
+
+export interface RoomSuggestionIntent {
+  symbols?: string[];
+  entities?: string[];
+  categories?: string[];
+  roomHints?: string[];
+  reason?: string;
+}
+
+export interface RoomSuggestionRequest {
+  source: RoomSuggestionSource;
+  intent?: RoomSuggestionIntent;
+  limit?: number;
+}
+
+export interface RoomSuggestion {
+  room: string;
+  title: string;
+  proof: {
+    online: number;
+    heat: "surging" | "active_now";
+    latestActivity?: string;
+    followingOnline?: number;
+    followingHandles?: string[];
+    friendsOnline?: number;
+    friendHandles?: string[];
+  };
+  copy: string;
+  suggestionId: string;
+}
+
+export interface RoomFollow {
+  userId: string;
+  profileUrl?: string | undefined;
+}
+
+export interface RoomFollowTarget {
+  userId: string;
+  username: string;
+}
+
+export interface RoomFollowResult {
+  target: RoomFollowTarget;
+  isNewFollow?: boolean;
+}
+
+export interface RoomAttachment {
+  /** Object key under room-attachments/; clients sign it at render time. */
+  key: string;
+  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. */
+  attachment: RoomAttachment & { url: string; expiresAt: string | null };
+}
+
+export interface RoomPublicProfile {
+  userId: string;
+  displayName?: string | undefined;
+  username?: string | undefined;
+  handle?: string | undefined;
+  profileDescription?: string | undefined;
+  profileUrl?: string | undefined;
+  followerCount?: number | undefined;
+  memberSince?: string | number | null | undefined;
+}
+
+export interface RoomFriend {
+  friendshipId: string;
+  userId: string;
+  username: string;
+  acceptedAt: string | number;
+  lastMessageAt?: string | number;
+}
+
+export interface RoomFriendRequest {
+  friendshipId: string;
+  userId: string;
+  username: string;
+  createdAt: string | number;
+}
+
+export interface RoomFriendRequests {
+  sent: RoomFriendRequest[];
+  received: RoomFriendRequest[];
+}
+
+export interface RoomDmParticipant {
+  userId: string;
+  username: string;
+}
+
+export interface RoomDmConversation {
+  conversationId: string;
+  participant: RoomDmParticipant;
+  unreadCount: number;
+  lastMessage?: RoomDmMessage;
+  updatedAt?: string | number;
+}
+
+export interface RoomDmMessage {
+  id?: string;
+  _id?: string;
+  messageId?: string;
+  conversationId?: string;
+  senderId?: string;
+  userId?: string;
+  senderUsername?: string;
+  username?: string;
+  content: string;
+  type?: string;
+  timestamp?: string | number;
+  createdAt?: string | number;
+  /** Sealed DM: content is '' and the opaque envelope rides here. */
+  secret?: RoomLedgerSecretPayload | null;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RoomDmHistory {
+  conversationId: string;
+  participant: RoomDmParticipant;
+  messages: RoomDmMessage[];
+  hasMore: boolean;
+  cursor?: number;
+}
+
+export interface RoomDmUnreadConversation extends RoomDmHistory {
+  unreadCount: number;
+}
+
+export interface RoomDmSendResult {
+  conversationId: string;
+  participant: RoomDmParticipant;
+  message: RoomDmMessage;
+}
+
+export interface RoomReplyInboxItem {
+  id?: string;
+  roomId: string;
+  replySeq: number;
+  parentSeq: number;
+  senderId?: string;
+  senderHandle: string;
+  parentPreview: string;
+  replyPreview: string;
+  readAt?: string | number | null;
+  createdAt?: string | number;
+  updatedAt?: string | number;
+}
+
+export interface RoomRepliesResult {
+  replies: RoomReplyInboxItem[];
+  unreadCount: number;
+}
+
+export interface RoomRepliesReadResult {
+  markedRead: number;
+}
+
+/** A living markdown doc scoped to a space (head state; content on demand). */
+export interface RoomDoc {
+  docId: string;
+  spaceId: string;
+  path: string;
+  title: string;
+  headRev: number;
+  headSha: string;
+  headNote: string;
+  headAuthorId: string;
+  headAuthorHandle: string;
+  headIsAgent: boolean;
+  headAt: string;
+  status: "active" | "archived";
+  aclMode: "space" | "owner";
+  restrictedToRoomId: string | null;
+  discussionRoomId: string | null;
+  createdByUserId: string;
+  createdByHandle: string;
+  sizeBytes: number;
+  spaceDocSeq: number;
+  createdAt?: string;
+  updatedAt?: string;
+  content?: string;
+}
+
+export interface RoomDocProvenance {
+  roomId?: string | undefined;
+  seqFrom?: number | undefined;
+  seqTo?: number | undefined;
+}
+
+/**
+ * Which surface issued a doc write: the rooms GUI editor, an agent doc verb,
+ * the local disk mirror (library sync), or the TUI/CLI flows. Self-declared
+ * attribution for the history view (same trust model as `asAgent`), never
+ * enforcement.
+ */
+export type RoomDocRevisionSource = "gui" | "agent" | "mirror" | "cli";
+
+/** Optional attribution rider accepted by every doc write. */
+export interface RoomDocAttribution {
+  /** Phase 1 agent credential id (`agcr_*`) when an agent authored the write. */
+  credentialId?: string | undefined;
+  /** Groups every revision one agent run produced. */
+  runId?: string | undefined;
+  /** Surface that issued the write. */
+  source?: RoomDocRevisionSource | undefined;
+}
+
+export interface RoomDocRevision {
+  docId: string;
+  rev: number;
+  op: string;
+  authorUserId: string;
+  authorHandle: string;
+  isAgent: boolean;
+  baseRev: number;
+  sha: string;
+  sizeBytes: number;
+  note: string;
+  noteSource: "human" | "agent" | "auto";
+  /** Attribution rider (null on pre-attribution revisions and older servers). */
+  credentialId?: string | null;
+  runId?: string | null;
+  source?: RoomDocRevisionSource | null;
+  provenance: RoomDocProvenance | null;
+  pathAfter: string | null;
+  revertOf: number | null;
+  recoveryPlanId?: string | null;
+  restorePoint?: string | null;
+  statusAfter?: "active" | "archived" | null;
+  at: string;
+  content?: string;
+  diff?: string;
+  diffOmitted?: boolean;
+}
+
+export type RoomSpaceRestoreActionKind =
+  | "content"
+  | "archive"
+  | "restore"
+  | "content_and_status"
+  | "archive_created_after";
+
+export interface RoomSpaceRestoreAction {
+  docId: string;
+  path: string;
+  kind: RoomSpaceRestoreActionKind;
+  currentRev: number;
+  targetRev: number | null;
+  currentStatus: "active" | "archived";
+  targetStatus: "active" | "archived";
+  currentAuthorUserId: string;
+  currentAuthorHandle: string;
+  currentAt: string;
+  targetAt: string | null;
+}
+
+export interface RoomSpaceRestoreSummary {
+  totalDocs: number;
+  totalActions: number;
+  contentRestores: number;
+  archives: number;
+  restores: number;
+  pathConflicts: number;
+  unchanged: number;
+}
+
+export interface RoomSpaceRestorePlan {
+  planId: string;
+  spaceId: string;
+  restoreAt: string;
+  baseCursor: number;
+  reason: string;
+  requestedByHandle: string;
+  status: "ready" | "applying" | "applied" | "failed" | "stale";
+  scope: "content_and_lifecycle";
+  scopeNote: string;
+  actions: RoomSpaceRestoreAction[];
+  summary: RoomSpaceRestoreSummary;
+  appliedCount: number;
+  expiresAt: string;
+  appliedAt: string | null;
+  resultingCursor: number | null;
+  error: string | null;
+}
+
+export interface RoomSpaceRestoreReceipt {
+  planId: string;
+  spaceId: string;
+  restoreAt: string;
+  reason: string;
+  status: "applied";
+  appliedActions: number;
+  resultingCursor: number;
+  appliedAt: string;
+  summary: RoomSpaceRestoreSummary;
+}
+
+/** Resumable per-space change feed page. `latestSeq` is the space's current
+ *  head cursor: `cursor === latestSeq` means the caller is fully in sync. */
+export interface RoomDocChanges {
+  changes: RoomDoc[];
+  cursor: number;
+  latestSeq: number;
+}
+
+export interface RoomDocConflictHead {
+  rev: number;
+  sha: string;
+  content: string;
+  note: string;
+  authorHandle: string;
+  isAgent: boolean;
+  at: string;
+}
+
+export interface RoomDocWriteResult {
+  doc: RoomDoc;
+  rev: number;
+  unchanged: boolean;
+}
+
+/** One diverging chunk from a three-way merge (line arrays, no separators). */
+export interface RoomDocMergeRegion {
+  base: string[];
+  mine: string[];
+  theirs: string[];
+}
+
+/**
+ * Outcome of a selective run revert. A merge conflict is OUTCOME data, not
+ * an error: nothing was written, and the payload carries the three full
+ * contents (base = the run's final content, mine = the current head,
+ * theirs = the pre-run content) plus the diverging regions so the reconcile
+ * surface can mediate. `headRev` is the fence a mediated resolution
+ * publishes against.
+ */
+export type RoomDocRunRevertResult =
+  | { status: "reverted"; doc: RoomDoc; rev: number; unchanged: boolean }
+  | {
+      status: "conflict";
+      headRev: number;
+      runId: string;
+      base: string;
+      mine: string;
+      theirs: string;
+      regions: RoomDocMergeRegion[];
+    };
+
+/**
+ * An editing-presence lease: the HINT that a user currently holds a dirty
+ * working copy of a doc on some device. Renewed by heartbeat, dropped on
+ * publish/discard, TTL-expired otherwise. Never a lock, never content;
+ * `isAgent` lets UIs class agent editors per the phase 3 presence rules.
+ */
+export interface RoomDocEditingLease {
+  docId: string;
+  spaceId: string;
+  userId: string;
+  handle: string;
+  isAgent: boolean;
+  expiresAt: string;
+}

package/src/suggestion-attribution.ts

@@ -0,0 +1,83 @@
+import type { RoomSuggestion } from "./social-types.js";
+
+export interface RoomSuggestionAttribution {
+  suggestionId: string;
+  hook: string;
+}
+
+export const ROOM_SUGGESTION_ATTRIBUTION_TTL_MS = 15 * 60 * 1000;
+
+const MAX_ROOM_SUGGESTION_ATTRIBUTIONS = 100;
+const roomSuggestionAttributions = new Map<
+  string,
+  RoomSuggestionAttribution & { expiresAt: number }
+>();
+
+export function rememberRoomSuggestionAttribution(
+  suggestion: Pick<RoomSuggestion, "room" | "suggestionId">,
+  hook: string,
+  now = Date.now(),
+): void {
+  const room = normalizeRoomKey(suggestion.room);
+  const suggestionId = suggestion.suggestionId.trim();
+  const normalizedHook = hook.trim();
+  if (!room || !suggestionId || !normalizedHook) return;
+
+  pruneExpiredRoomSuggestionAttributions(now);
+  while (
+    roomSuggestionAttributions.size >= MAX_ROOM_SUGGESTION_ATTRIBUTIONS &&
+    !roomSuggestionAttributions.has(room)
+  ) {
+    const oldest = roomSuggestionAttributions.keys().next().value;
+    if (!oldest) break;
+    roomSuggestionAttributions.delete(oldest);
+  }
+
+  roomSuggestionAttributions.set(room, {
+    suggestionId,
+    hook: normalizedHook,
+    expiresAt: now + ROOM_SUGGESTION_ATTRIBUTION_TTL_MS,
+  });
+}
+
+export function rememberRoomSuggestionAttributions(
+  suggestions: readonly Pick<RoomSuggestion, "room" | "suggestionId">[],
+  hook: string,
+  now = Date.now(),
+): void {
+  for (const suggestion of suggestions) {
+    rememberRoomSuggestionAttribution(suggestion, hook, now);
+  }
+}
+
+export function consumeRoomSuggestionAttribution(
+  room: string,
+  now = Date.now(),
+): RoomSuggestionAttribution | undefined {
+  const roomKey = normalizeRoomKey(room);
+  if (!roomKey) return undefined;
+  const attribution = roomSuggestionAttributions.get(roomKey);
+  if (!attribution) return undefined;
+  roomSuggestionAttributions.delete(roomKey);
+  if (attribution.expiresAt <= now) return undefined;
+  return {
+    suggestionId: attribution.suggestionId,
+    hook: attribution.hook,
+  };
+}
+
+export function resetRoomSuggestionAttributionForTest(): void {
+  roomSuggestionAttributions.clear();
+}
+
+function pruneExpiredRoomSuggestionAttributions(now: number): void {
+  for (const [room, attribution] of roomSuggestionAttributions) {
+    if (attribution.expiresAt <= now) {
+      roomSuggestionAttributions.delete(room);
+    }
+  }
+}
+
+function normalizeRoomKey(room: string): string {
+  return room.trim().replace(/^#/, "").toLowerCase();
+}

package/src/topic-uri.ts

@@ -0,0 +1,64 @@
+import pc from "picocolors";
+
+/**
+ * om://topic URIs: permanent links into a channel's topics.
+ *
+ * The id is registry-backed and never changes, so a captured link
+ * (`om://topic/<topicId>`) keeps resolving after the topic is renamed or
+ * merged into another topic. Clients that understand the scheme render it as
+ * a pill and can annotate it with the topic's live name from a local cache;
+ * clients that don't still show a usable, resolvable reference.
+ */
+
+export interface TopicUriRef {
+  topicId: string;
+}
+
+const TOPIC_URI_RE = /om:\/\/topic\/([A-Za-z0-9_-]{6,64})/g;
+
+export function makeTopicUri(topicId: string): string {
+  return `om://topic/${topicId}`;
+}
+
+export function parseTopicUris(text: string): TopicUriRef[] {
+  const refs: TopicUriRef[] = [];
+  for (const match of text.matchAll(TOPIC_URI_RE)) {
+    const topicId = match[1];
+    if (!topicId) continue;
+    refs.push({ topicId });
+  }
+  return refs;
+}
+
+export interface TopicUriRenderContext {
+  /** Resolve a topicId to its live name, when known. */
+  lookup?: ((topicId: string) => string | undefined) | undefined;
+}
+
+/**
+ * Process-wide lookup used by the tape renderers, mirroring
+ * `setDocUriLookup` in ./doc-uri. Renderers work unregistered too: pills
+ * just lose the name annotation and fall back to a truncated id.
+ */
+let activeLookup: TopicUriRenderContext["lookup"];
+
+export function setTopicUriLookup(lookup: TopicUriRenderContext["lookup"]): void {
+  activeLookup = lookup;
+}
+
+export function decorateTopicUrisLive(text: string): string {
+  if (!text.includes("om://topic/")) return text;
+  return decorateTopicUris(text, { lookup: activeLookup });
+}
+
+/**
+ * Replace om://topic URIs with a rendered pill: the topic's live name when a
+ * cache lookup resolves it, otherwise a compact id reference that is still
+ * visibly a topic link.
+ */
+export function decorateTopicUris(text: string, context: TopicUriRenderContext = {}): string {
+  return text.replace(TOPIC_URI_RE, (_raw, topicId: string) => {
+    const name = context.lookup?.(topicId);
+    return name ? pc.cyan(`⌗ ${name}`) : pc.cyan(`⌗ topic:${topicId.slice(0, 8)}`);
+  });
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+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 {
+  applyRoomPresenceDelta,
+  isSystemRoomLedgerEntryType,
+  ROOM_PRESENCE_SAMPLE_LIMIT,
+  RoomClientMessageType,
+  RoomLedgerEntryType,
+  RoomServerMessageType,
+  SUPPORTED_ROOM_PROTOCOL_VERSION,
+} from "./shared/rooms-protocol.js";

package/src/version.ts

@@ -0,0 +1,2 @@
+export const VERSION = "0.5.0";
+export const RUNNER_VERSION = "0.5.0";