@ai-matrx/messaging 0.13.1 → 0.14.0

package/dist/react.d.cts

@@ -208,7 +208,11 @@ interface Page<TItem, TCursor> {
 /** What the host injects. Identity ONLY — every hard part is in the package. */
 interface MessagingIdentity {
     readonly userId: UserId;
-    readonly organizationId: OrganizationId;
+    /**
+     * The active organization, or `null` when none is selected. Reads never
+     * depend on it; it is only where a NEW conversation lands.
+     */
+    readonly organizationId: OrganizationId | null;
 }
 interface DraftMessage {
     readonly conversationId: ConversationId;
@@ -525,7 +529,9 @@ declare function createOutbox(options: OutboxOptions): Outbox;
  * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
  * warns and retries; it is never a red error.
  */
-type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
+type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured"
+/** A NEW conversation needs an organization to land in and none is selected. */
+ | "organization-required" | "unknown";
 declare class MessagingError extends Error {
     readonly code: MessagingErrorCode;
     /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
@@ -817,15 +823,21 @@ interface RepositoryOptions {
      */
     client: MessagingSupabaseClient;
     /**
-     * The active organization. Every conversation and message write carries it
-     * explicitly (R5).
+     * The active organization, or `null`/omitted when none is selected.
+     *
+     * 🚨 READS NEVER NEED IT (access belongs to the person, 2026-09-23). Every
+     * read here is answered by RLS as the session's user; the organization is
+     * only the DESTINATION of a NEW conversation. Without one, starting a
+     * conversation is refused with `organization-required` (the host asks the
+     * person to choose), and a message or member added to an EXISTING
+     * conversation is stamped with that conversation's own organization.
      *
      * 🚨 THERE IS NO `userId` HERE, AND THERE WILL NOT BE ONE (DD-241). Who is
      * acting is read from `client`'s own session — see `session-identity.ts` for
      * the class that closed and why a handed-in id could not be made safe by
      * convention. A caller that still passes `identity` is IGNORED and told so.
      */
-    organizationId: string;
+    organizationId?: string | null | undefined;
     /**
      * INTERNAL. The React provider already runs one session reader for its own
      * render loop and hands it here so the two cannot answer differently and so
@@ -846,8 +858,11 @@ interface RepositoryOptions {
     now?: (() => number) | undefined;
 }
 interface MessagingRepository {
-    /** The organization every write here is stamped with. */
-    readonly organizationId: OrganizationId;
+    /**
+     * The active organization new conversations land in, or `null` when none is
+     * selected — reads work either way.
+     */
+    readonly organizationId: OrganizationId | null;
     /**
      * Who the session says is acting — awaited, because the first `getSession()`
      * is a real read. Rejects with `session-unavailable` when nobody is signed
@@ -1269,7 +1284,12 @@ interface MessagingProviderProps {
      * (DD-241). There is no `userId` prop, on purpose.
      */
     client: MessagingSupabaseClient | null | undefined;
-    /** The active organization. Every write carries it (R5). */
+    /**
+     * The active organization, or `null` when none is selected. Messaging runs
+     * without one: every read is the person's own. It is the destination of a
+     * NEW conversation (refused as `organization-required` without it) and of
+     * AI runs (the AI actions do not render without it).
+     */
     organizationId: string | null | undefined;
     /**
      * The Matrx API transport for AI features. Omit to run messaging without AI;
@@ -1778,9 +1798,13 @@ declare function formatLastSeen(lastSeenMs: number | null, now?: number): string
 
 declare function projectUserSummary(row: Record<string, unknown>): UserSummary;
 declare function projectMessageAction(value: unknown): MessageAction | null;
-declare function projectMessage(row: Record<string, unknown>, fallbackOrganizationId: OrganizationId): Message;
+declare function projectMessage(row: Record<string, unknown>, 
+/** The active organization, or `null` when none is selected (reads never need one). */
+fallbackOrganizationId: OrganizationId | null): Message;
 declare function projectParticipantRole(value: unknown): ParticipantRole;
-declare function projectConversationSummary(row: Record<string, unknown>, viewerId: UserId, fallbackOrganizationId: OrganizationId): ConversationSummary;
+declare function projectConversationSummary(row: Record<string, unknown>, viewerId: UserId, 
+/** The active organization, or `null` when none is selected (reads never need one). */
+fallbackOrganizationId: OrganizationId | null): ConversationSummary;
 
 /**
  * MATRX REFERENCES — a message can name a platform entity, and everything it

package/dist/react.d.ts

@@ -208,7 +208,11 @@ interface Page<TItem, TCursor> {
 /** What the host injects. Identity ONLY — every hard part is in the package. */
 interface MessagingIdentity {
     readonly userId: UserId;
-    readonly organizationId: OrganizationId;
+    /**
+     * The active organization, or `null` when none is selected. Reads never
+     * depend on it; it is only where a NEW conversation lands.
+     */
+    readonly organizationId: OrganizationId | null;
 }
 interface DraftMessage {
     readonly conversationId: ConversationId;
@@ -525,7 +529,9 @@ declare function createOutbox(options: OutboxOptions): Outbox;
  * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
  * warns and retries; it is never a red error.
  */
-type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
+type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured"
+/** A NEW conversation needs an organization to land in and none is selected. */
+ | "organization-required" | "unknown";
 declare class MessagingError extends Error {
     readonly code: MessagingErrorCode;
     /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
@@ -817,15 +823,21 @@ interface RepositoryOptions {
      */
     client: MessagingSupabaseClient;
     /**
-     * The active organization. Every conversation and message write carries it
-     * explicitly (R5).
+     * The active organization, or `null`/omitted when none is selected.
+     *
+     * 🚨 READS NEVER NEED IT (access belongs to the person, 2026-09-23). Every
+     * read here is answered by RLS as the session's user; the organization is
+     * only the DESTINATION of a NEW conversation. Without one, starting a
+     * conversation is refused with `organization-required` (the host asks the
+     * person to choose), and a message or member added to an EXISTING
+     * conversation is stamped with that conversation's own organization.
      *
      * 🚨 THERE IS NO `userId` HERE, AND THERE WILL NOT BE ONE (DD-241). Who is
      * acting is read from `client`'s own session — see `session-identity.ts` for
      * the class that closed and why a handed-in id could not be made safe by
      * convention. A caller that still passes `identity` is IGNORED and told so.
      */
-    organizationId: string;
+    organizationId?: string | null | undefined;
     /**
      * INTERNAL. The React provider already runs one session reader for its own
      * render loop and hands it here so the two cannot answer differently and so
@@ -846,8 +858,11 @@ interface RepositoryOptions {
     now?: (() => number) | undefined;
 }
 interface MessagingRepository {
-    /** The organization every write here is stamped with. */
-    readonly organizationId: OrganizationId;
+    /**
+     * The active organization new conversations land in, or `null` when none is
+     * selected — reads work either way.
+     */
+    readonly organizationId: OrganizationId | null;
     /**
      * Who the session says is acting — awaited, because the first `getSession()`
      * is a real read. Rejects with `session-unavailable` when nobody is signed
@@ -1269,7 +1284,12 @@ interface MessagingProviderProps {
      * (DD-241). There is no `userId` prop, on purpose.
      */
     client: MessagingSupabaseClient | null | undefined;
-    /** The active organization. Every write carries it (R5). */
+    /**
+     * The active organization, or `null` when none is selected. Messaging runs
+     * without one: every read is the person's own. It is the destination of a
+     * NEW conversation (refused as `organization-required` without it) and of
+     * AI runs (the AI actions do not render without it).
+     */
     organizationId: string | null | undefined;
     /**
      * The Matrx API transport for AI features. Omit to run messaging without AI;
@@ -1778,9 +1798,13 @@ declare function formatLastSeen(lastSeenMs: number | null, now?: number): string
 
 declare function projectUserSummary(row: Record<string, unknown>): UserSummary;
 declare function projectMessageAction(value: unknown): MessageAction | null;
-declare function projectMessage(row: Record<string, unknown>, fallbackOrganizationId: OrganizationId): Message;
+declare function projectMessage(row: Record<string, unknown>, 
+/** The active organization, or `null` when none is selected (reads never need one). */
+fallbackOrganizationId: OrganizationId | null): Message;
 declare function projectParticipantRole(value: unknown): ParticipantRole;
-declare function projectConversationSummary(row: Record<string, unknown>, viewerId: UserId, fallbackOrganizationId: OrganizationId): ConversationSummary;
+declare function projectConversationSummary(row: Record<string, unknown>, viewerId: UserId, 
+/** The active organization, or `null` when none is selected (reads never need one). */
+fallbackOrganizationId: OrganizationId | null): ConversationSummary;
 
 /**
  * MATRX REFERENCES — a message can name a platform entity, and everything it

package/dist/react.js

@@ -762,7 +762,7 @@ function projectMessage(row, fallbackOrganizationId) {
     id: requiredStr(row, "id", operation),
     conversationId: requiredStr(row, "conversation_id", operation),
     senderId: requiredStr(row, "sender_id", operation),
-    organizationId: str(row, "organization_id") ?? fallbackOrganizationId,
+    organizationId: str(row, "organization_id") ?? fallbackOrganizationId ?? "",
     content: typeof row["content"] === "string" ? row["content"] : "",
     kind: MESSAGE_KINDS.has(kindRaw) ? kindRaw : "text",
     // A row read from the DB is at least `sent`. `sending`/`failed` are outbox
@@ -810,7 +810,7 @@ function projectConversationSummary(row, viewerId, fallbackOrganizationId) {
       groupName,
       groupImageUrl,
       createdBy: createdBy === null ? null : createdBy,
-      organizationId: str(row, "organization_id") ?? fallbackOrganizationId,
+      organizationId: str(row, "organization_id") ?? fallbackOrganizationId ?? "",
       createdAt,
       updatedAt,
       metadata: jsonObject(row["metadata"])
@@ -1143,7 +1143,11 @@ function createMessagingEngine(options) {
           optimisticMessage({
             conversationId: entry.draft.conversationId,
             senderId: identity.userId,
-            organizationId: identity.organizationId,
+            // Client-only until the confirmed row replaces it: the active
+            // organization, else the conversation's own.
+            organizationId: identity.organizationId ?? store.snapshot().conversations.find(
+              (item) => item.conversation.id === entry.draft.conversationId
+            )?.conversation.organizationId ?? "",
             content: entry.draft.content,
             clientMessageId: entry.clientMessageId,
             ...entry.draft.kind !== void 0 ? { kind: entry.draft.kind } : {},
@@ -1632,12 +1636,15 @@ var RPCS = {
 };
 var MESSAGE_COLUMNS = "id,conversation_id,sender_id,organization_id,content,message_type,status,reply_to_id,client_message_id,action_data,media_url,media_thumbnail_url,media_metadata,created_at,edited_at,deleted_at,deleted_for_everyone,metadata";
 var CONVERSATION_COLUMNS = "id,type,group_name,group_image_url,created_by,organization_id,created_at,updated_at,metadata";
+function optionalOrg(organizationId) {
+  return typeof organizationId === "string" && organizationId.length > 0 ? organizationId : null;
+}
 function requireOrg(organizationId, operation) {
-  if (typeof organizationId !== "string" || organizationId.length === 0) {
+  if (organizationId === null) {
     throw new MessagingError(
-      "misconfigured",
-      `${operation}: no organization_id`,
-      "Every conversation and message write carries an explicit organization_id (R5). Pass a real org on <MessagingProvider>; the package refuses the write rather than letting an unscoped row reach the database."
+      "organization-required",
+      `${operation}: no organization selected`,
+      "A new conversation is filed under one organization. Ask the person to choose one, then pass it as organizationId on <MessagingProvider>. Reading and replying to existing conversations never needs it."
     );
   }
   return organizationId;
@@ -1649,7 +1656,7 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, jittered));
 }
 function createMessagingRepository(options) {
-  const org = requireOrg(options.organizationId, "createMessagingRepository");
+  const org = optionalOrg(options.organizationId);
   const handedIn = options.identity;
   if (handedIn !== void 0 && handedIn !== null && handedIn.userId !== void 0) {
     options.onDiagnostic?.(
@@ -1719,6 +1726,11 @@ function createMessagingRepository(options) {
     });
     return found;
   }
+  async function organizationOfExisting(conversationId) {
+    if (org !== null) return org;
+    const conversation = await repository.getConversation(conversationId);
+    return conversation.organizationId;
+  }
   const repository = {
     organizationId: org,
     actingUserId,
@@ -1851,6 +1863,7 @@ function createMessagingRepository(options) {
     },
     async getOrCreateDirectConversation(otherUserId) {
       const operation = "getOrCreateDirectConversation";
+      const destination = requireOrg(org, operation);
       const me = await actingUser(operation);
       const id = await withSessionRetry(
         operation,
@@ -1862,7 +1875,7 @@ function createMessagingRepository(options) {
             // not a preference.
             p_user1_id: me,
             p_user2_id: otherUserId,
-            p_organization_id: org
+            p_organization_id: destination
           },
           operation
         )
@@ -1874,13 +1887,14 @@ function createMessagingRepository(options) {
     },
     async createGroupConversation({ name, memberIds }) {
       const operation = "createGroupConversation";
+      const destination = requireOrg(org, operation);
       const me = await actingUser(operation);
       const { data, error } = await withSessionRetry(
         operation,
         async () => db().from(TABLES.conversations).insert({
           type: "group",
           group_name: name,
-          organization_id: org,
+          organization_id: destination,
           created_by: me
         }).select("id").single()
       );
@@ -1895,7 +1909,7 @@ function createMessagingRepository(options) {
           conversation_id: conversationId,
           user_id: userId,
           role: userId === me ? "owner" : "member",
-          organization_id: org,
+          organization_id: destination,
           created_by: me
         }))
       );
@@ -1905,10 +1919,11 @@ function createMessagingRepository(options) {
     async insertMessage(draft, clientMessageId) {
       const operation = "insertMessage";
       const me = await actingUser(operation);
+      const destination = await organizationOfExisting(draft.conversationId);
       const { data, error } = await db().from(TABLES.messages).insert({
         conversation_id: draft.conversationId,
         sender_id: me,
-        organization_id: org,
+        organization_id: destination,
         created_by: me,
         content: draft.content,
         message_type: draft.kind ?? "text",
@@ -1969,12 +1984,13 @@ function createMessagingRepository(options) {
     async addMembers(conversationId, memberIds) {
       const operation = "addMembers";
       const me = await actingUser(operation);
+      const destination = await organizationOfExisting(conversationId);
       const { error } = await db().from(TABLES.participants).insert(
         memberIds.map((userId) => ({
           conversation_id: conversationId,
           user_id: userId,
           role: "member",
-          organization_id: org,
+          organization_id: destination,
           created_by: me
         }))
       );
@@ -2085,7 +2101,7 @@ function MessagingProvider(props) {
   }, [strayUserId]);
   const session = useSessionUserId(client, props.onDiagnostic);
   const userId = session.snapshot.userId;
-  const ready = client != null && userId !== null && typeof organizationId === "string" && organizationId.length > 0;
+  const ready = client != null && userId !== null;
   const hostProvidesRealtime = useIsRealtimeProviderMounted();
   const runtime = /* @__PURE__ */ jsx(
     MessagingRuntime,
@@ -2121,12 +2137,13 @@ function MessagingRuntime(props) {
       actionRegistry.register(handler);
     });
   }, [actionRegistry, handlers]);
-  const ready = client != null && manager !== null && sessionIdentity !== null && userId !== null && typeof organizationId === "string" && organizationId.length > 0;
+  const ready = client != null && manager !== null && sessionIdentity !== null && userId !== null;
+  const activeOrganizationId = typeof organizationId === "string" && organizationId.length > 0 ? organizationId : null;
   const engine = useMemo(() => {
     if (!ready || manager === null || sessionIdentity === null || userId === null) return null;
     const identity = {
       userId,
-      organizationId
+      organizationId: activeOrganizationId
     };
     const report = (event) => {
       (diagnosticRef.current ?? defaultDiagnostics)(event);
@@ -2137,7 +2154,7 @@ function MessagingRuntime(props) {
       // supabase-shape.ts); everything below this line works against the rich
       // contract, which `supabase-shape.test.ts` proves a real client honors.
       client,
-      organizationId,
+      organizationId: activeOrganizationId,
       // THE SAME READER the render loop above uses. Two readers would be two
       // answers during the tick an account switch takes.
       sessionIdentity,
@@ -2170,14 +2187,14 @@ function MessagingRuntime(props) {
       }
     });
     return built;
-  }, [ready, manager, sessionIdentity, userId, organizationId]);
+  }, [ready, manager, sessionIdentity, userId, activeOrganizationId]);
   useEffect(() => {
     if (engine === null) return void 0;
     void engine.start().catch((error) => {
       (diagnosticRef.current ?? defaultDiagnostics)({
         level: "error",
         message: `Messaging failed to start: ${String(error?.message ?? error)}`,
-        remedy: "Check the signed-in session and organization, then reload the surface."
+        remedy: "Check the signed-in session, then reload the surface."
       });
     });
     return () => {
@@ -2191,9 +2208,10 @@ function MessagingRuntime(props) {
   const sourceFeature = props.sourceFeature;
   const ai = useMemo(() => {
     if (transport === void 0 || agents === void 0 || !ready) return null;
+    if (activeOrganizationId === null) return null;
     return createMessagingAi({
       transport,
-      organizationId,
+      organizationId: activeOrganizationId,
       agents,
       ...maxTranscriptMessages !== void 0 ? { maxTranscriptMessages } : {},
       ...sourceApp !== void 0 ? { sourceApp } : {},
@@ -2203,7 +2221,7 @@ function MessagingRuntime(props) {
     transport,
     agents,
     ready,
-    organizationId,
+    activeOrganizationId,
     maxTranscriptMessages,
     sourceApp,
     sourceFeature
@@ -2254,7 +2272,7 @@ function useRequiredMessagingHost() {
   const host = useMessagingHost();
   if (host === null) {
     throw new Error(
-      "[@ai-matrx/messaging] No messaging host. Wrap this tree in <MessagingProvider client={supabase} userId={userId} organizationId={orgId}> and render it only once auth has resolved."
+      "[@ai-matrx/messaging] No messaging host. Wrap this tree in <MessagingProvider client={supabase} organizationId={orgId}> and render it only once auth has resolved."
     );
   }
   return host;
@@ -2644,7 +2662,8 @@ function useMessageAction(message) {
       const context = {
         messageId: message.id,
         actorId: host.identity.userId,
-        organizationId: host.identity.organizationId,
+        // The active organization, else the organization the message lives in.
+        organizationId: host.identity.organizationId ?? message.organizationId,
         choice
       };
       host.actions.execute(action, context).then(setReceipt).catch((cause) => {