@ai-matrx/messaging 0.12.4 → 0.13.0

package/dist/index.d.cts

@@ -1046,6 +1046,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[];
@@ -1087,6 +1105,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;
@@ -1106,6 +1126,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;
@@ -1349,4 +1371,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, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };

package/dist/index.d.ts

@@ -1046,6 +1046,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[];
@@ -1087,6 +1105,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;
@@ -1106,6 +1126,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;
@@ -1349,4 +1371,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, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };

package/dist/index.js

@@ -974,6 +974,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() {
@@ -986,7 +987,8 @@ function createMessagingStore() {
       activeConversationId,
       totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
       archiveFilter,
-      archivedCount
+      archivedCount,
+      conversationReadFailures
     };
     return cached;
   }
@@ -1070,6 +1072,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,
@@ -1375,11 +1385,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({