@ai-matrx/messaging 0.12.4 → 0.13.0

package/dist/react.d.cts

@@ -943,6 +943,24 @@ declare function createMessagingRepository(options: RepositoryOptions): Messagin
  *    place here.
  */
 
+/**
+ * Why a conversation could not be read — held PER conversation so a screen can
+ * tell "still loading" from "this will never load".
+ *
+ * Without it a refused read left the thread absent forever (an endless
+ * spinner), and a zero-row read of a conversation the caller cannot see
+ * rendered "No messages yet" — a confident lie about a conversation they may
+ * not even be allowed to know exists.
+ */
+interface ConversationReadFailure {
+    readonly error: MessagingError;
+    /**
+     * True when the conversation does not exist or this user may not read it
+     * (`not-found` / `forbidden`) — an ACCESS question the host answers with its
+     * access surface, never a retryable fault.
+     */
+    readonly unavailable: boolean;
+}
 interface ConversationThread {
     readonly conversationId: ConversationId;
     readonly messages: readonly Message[];
@@ -984,6 +1002,8 @@ interface MessagingSnapshot {
         readonly count: number;
         readonly exact: boolean;
     } | null;
+    /** Conversations whose last open failed, keyed by id. Cleared on the next open. */
+    readonly conversationReadFailures: ReadonlyMap<ConversationId, ConversationReadFailure>;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
@@ -1003,6 +1023,8 @@ interface MessagingStore {
     upsertConversation(item: ConversationSummary): void;
     removeConversation(id: ConversationId): void;
     setActiveConversation(id: ConversationId | null): void;
+    /** Record (or clear, with `null`) why a conversation could not be read. */
+    setConversationReadFailure(id: ConversationId, failure: ConversationReadFailure | null): void;
     setThread(id: ConversationId, messages: readonly Message[], args?: {
         hasMoreOlder?: boolean;
     }): void;
@@ -1362,7 +1384,18 @@ interface UseConversationResult {
     thread: ConversationThread | null;
     messages: readonly Message[];
     participants: readonly UserSummary[];
+    /** True only while the first read is in flight — false once it failed. */
     isLoading: boolean;
+    /**
+     * Why the conversation could not be read, or `null`. `error.cause` is the
+     * raw database error, for hosts that classify access failures themselves.
+     */
+    error: MessagingError | null;
+    /**
+     * True when the conversation does not exist or this user may not read it.
+     * Render the host's access surface — never "No messages yet".
+     */
+    unavailable: boolean;
     hasMoreOlder: boolean;
     loadOlder: () => void;
     pending: readonly OutboxEntry[];
@@ -1805,4 +1838,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.d.ts

@@ -943,6 +943,24 @@ declare function createMessagingRepository(options: RepositoryOptions): Messagin
  *    place here.
  */
 
+/**
+ * Why a conversation could not be read — held PER conversation so a screen can
+ * tell "still loading" from "this will never load".
+ *
+ * Without it a refused read left the thread absent forever (an endless
+ * spinner), and a zero-row read of a conversation the caller cannot see
+ * rendered "No messages yet" — a confident lie about a conversation they may
+ * not even be allowed to know exists.
+ */
+interface ConversationReadFailure {
+    readonly error: MessagingError;
+    /**
+     * True when the conversation does not exist or this user may not read it
+     * (`not-found` / `forbidden`) — an ACCESS question the host answers with its
+     * access surface, never a retryable fault.
+     */
+    readonly unavailable: boolean;
+}
 interface ConversationThread {
     readonly conversationId: ConversationId;
     readonly messages: readonly Message[];
@@ -984,6 +1002,8 @@ interface MessagingSnapshot {
         readonly count: number;
         readonly exact: boolean;
     } | null;
+    /** Conversations whose last open failed, keyed by id. Cleared on the next open. */
+    readonly conversationReadFailures: ReadonlyMap<ConversationId, ConversationReadFailure>;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
@@ -1003,6 +1023,8 @@ interface MessagingStore {
     upsertConversation(item: ConversationSummary): void;
     removeConversation(id: ConversationId): void;
     setActiveConversation(id: ConversationId | null): void;
+    /** Record (or clear, with `null`) why a conversation could not be read. */
+    setConversationReadFailure(id: ConversationId, failure: ConversationReadFailure | null): void;
     setThread(id: ConversationId, messages: readonly Message[], args?: {
         hasMoreOlder?: boolean;
     }): void;
@@ -1362,7 +1384,18 @@ interface UseConversationResult {
     thread: ConversationThread | null;
     messages: readonly Message[];
     participants: readonly UserSummary[];
+    /** True only while the first read is in flight — false once it failed. */
     isLoading: boolean;
+    /**
+     * Why the conversation could not be read, or `null`. `error.cause` is the
+     * raw database error, for hosts that classify access failures themselves.
+     */
+    error: MessagingError | null;
+    /**
+     * True when the conversation does not exist or this user may not read it.
+     * Render the host's access surface — never "No messages yet".
+     */
+    unavailable: boolean;
     hasMoreOlder: boolean;
     loadOlder: () => void;
     pending: readonly OutboxEntry[];
@@ -1805,4 +1838,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.js

@@ -875,6 +875,7 @@ function createMessagingStore() {
   let archivedCount = null;
   let threads = /* @__PURE__ */ new Map();
   let activeConversationId = null;
+  let conversationReadFailures = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   let cached = null;
   function snapshot() {
@@ -887,7 +888,8 @@ function createMessagingStore() {
       activeConversationId,
       totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
       archiveFilter,
-      archivedCount
+      archivedCount,
+      conversationReadFailures
     };
     return cached;
   }
@@ -971,6 +973,14 @@ function createMessagingStore() {
       conversations = normalizeConversations(conversations);
       emit();
     },
+    setConversationReadFailure(id, failure) {
+      if (failure === null && !conversationReadFailures.has(id)) return;
+      const next = new Map(conversationReadFailures);
+      if (failure === null) next.delete(id);
+      else next.set(id, failure);
+      conversationReadFailures = next;
+      emit();
+    },
     setThread(id, messages, args = {}) {
       writeThread({
         conversationId: id,
@@ -1276,11 +1286,26 @@ function createMessagingEngine(options) {
     },
     async openConversation(id) {
       store.setActiveConversation(id);
+      store.setConversationReadFailure(id, null);
       try {
         const page = await repository.listMessages(id, { limit: messagePageSize });
+        if (page.items.length === 0) {
+          await repository.getConversation(id);
+        }
         store.setThread(id, page.items, { hasMoreOlder: page.hasMore });
       } catch (error) {
-        reportError(error, "openConversation");
+        const normalized = normalizeMessagingError(error, "openConversation");
+        const unavailable = normalized.code === "not-found" || normalized.code === "forbidden";
+        store.setConversationReadFailure(id, { error: normalized, unavailable });
+        if (unavailable) {
+          report({
+            level: "warn",
+            message: normalized.message,
+            remedy: normalized.remedy
+          });
+          return;
+        }
+        reportError(normalized, "openConversation");
       }
       if (openChannels.has(id) || disposed) return;
       const handle = manager.open({
@@ -2393,6 +2418,7 @@ function useConversation(id) {
   }, []);
   const thread = id === null ? null : snapshot?.threads.get(id) ?? null;
   const summary = id === null ? null : snapshot?.conversations.find((item) => item.conversation.id === id) ?? null;
+  const failure = id === null ? null : snapshot?.conversationReadFailures.get(id) ?? null;
   const pending = useMemo2(() => {
     void outboxTick;
     return id === null ? [] : host?.engine.outbox.pendingFor(id) ?? [];
@@ -2402,7 +2428,9 @@ function useConversation(id) {
     thread,
     messages: thread?.messages ?? [],
     participants: summary?.participants ?? [],
-    isLoading: id !== null && thread === null,
+    isLoading: id !== null && thread === null && failure === null,
+    error: failure?.error ?? null,
+    unavailable: failure?.unavailable ?? false,
     hasMoreOlder: thread?.hasMoreOlder ?? false,
     loadOlder: () => {
       if (id !== null) void host?.engine.loadOlderMessages(id);
@@ -3189,7 +3217,19 @@ function ConversationView(props) {
         }
       )
     ] }) : null,
-    /* @__PURE__ */ jsx4("div", { className: "mx-msg__scroll", ref: scrollRef, children: conversation.isLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, { rows: 4 }) : messages.length === 0 ? /* @__PURE__ */ jsx4(EmptyState, { title: "No messages yet", body: "Say something to get started." }) : /* @__PURE__ */ jsxs2("div", { className: "mx-msg__messages", children: [
+    /* @__PURE__ */ jsx4("div", { className: "mx-msg__scroll", ref: scrollRef, children: conversation.isLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, { rows: 4 }) : conversation.unavailable ? /* @__PURE__ */ jsx4(
+      EmptyState,
+      {
+        title: "Conversation unavailable",
+        body: "It doesn't exist, or you aren't a member of it."
+      }
+    ) : conversation.error !== null && messages.length === 0 ? /* @__PURE__ */ jsx4(
+      EmptyState,
+      {
+        title: "Couldn't load this conversation",
+        body: "Check your connection, then open it again."
+      }
+    ) : messages.length === 0 ? /* @__PURE__ */ jsx4(EmptyState, { title: "No messages yet", body: "Say something to get started." }) : /* @__PURE__ */ jsxs2("div", { className: "mx-msg__messages", children: [
       conversation.hasMoreOlder ? /* @__PURE__ */ jsx4(
         "button",
         {