@pmate/chat-sdk 0.12.0-next.83 → 0.12.0-next.85

package/README.md

@@ -338,3 +338,18 @@ A discussion cannot open another discussion. Thread-internal quoted replies keep
 the same root. Close each discussion when its view closes; closing the parent
 also closes its discussions. Agents working on a platform supporting Message
 Threads should put their replies in the incoming Message Thread.
+
+## App-wide group identity
+
+### Background
+
+A group is addressed by `(appId, groupId)`. Team membership governs access but is
+not part of the public destination identity. Callers can read group metadata
+without supplying a Team; the Hub resolves the canonical Team and checks access.
+
+Both group creation APIs generate a UUID when no ID is supplied. A definitive
+`GROUP_ID_CONFLICT` selects another UUID, with at most eight attempts. Timeouts,
+permission errors and unknown delivery outcomes retain the original identity;
+they must never create a second group. Durable creation retries reuse the same
+creation command. Server-side conditional appends enforce uniqueness across Hub
+instances. Deploy that server contract before enabling Team-free group lookup.

package/lib/internal/chatEngine.js

@@ -1,3 +1,4 @@
+import { createUniqueGroup } from "../runtime/groupIdentity.js";
 import { createMessagePresenter } from "../messageView.js";
 import { createChat as createSession } from "../runtime/createChat.js";
 import { asChatError } from "../runtime/chatError.js";
@@ -272,9 +273,11 @@ export class ChatEngine {
     getGroup(threadId, options = {}) { return this.threadOperation(threadId, async () => this.group(await this.advanced.getGroup(threadId, options))); }
     createGroup(input) {
         return this.operation(async () => {
-            const groupId = input.groupId ?? crypto.randomUUID(), threadId = await this.getConversation({ groupId });
-            const group = await this.advanced.createGroup({ id: threadId, kind: "group", targetId: groupId, teamId: this.options.teamId }, { title: input.title, members: input.members });
-            return { ...this.group(group), threadId };
+            return createUniqueGroup(input.groupId, async (groupId) => {
+                const threadId = await this.getConversation({ groupId });
+                const group = await this.advanced.createGroup({ id: threadId, kind: "group", targetId: groupId, teamId: this.options.teamId }, { title: input.title, members: input.members });
+                return { ...this.group(group), threadId };
+            });
         });
     }
     updateGroup(threadId, changes) { return this.threadOperation(threadId, async () => this.group(await this.advanced.updateGroup(threadId, changes))); }

package/lib/runtime/chatClient.d.ts

@@ -109,7 +109,7 @@ export declare class ChatClient {
         teamId?: string;
     }): Promise<ChatRuntimeMessage>;
     createGroup(input: {
-        groupId: string;
+        groupId?: string;
         teamId?: string;
         members: string[];
         title?: string;

package/lib/runtime/chatClient.js

@@ -1,3 +1,4 @@
+import { createUniqueGroup } from "./groupIdentity.js";
 import { withChatTeam } from "./teamScope.js";
 import { OnlineReachReceiver } from "./reach.js";
 import { OnlineNotificationReceiver } from "./notification.js";
@@ -232,18 +233,18 @@ export class ChatClient {
         });
     }
     async createGroup(input) {
-        return this.sendChat(input.groupId, {
+        return createUniqueGroup(input.groupId, groupId => this.sendChat(groupId, {
             kind: "group",
             threadKind: "group",
             action: "groupCreate",
             payload: {
                 appId: this.options.appId,
-                groupId: input.groupId,
+                groupId,
                 ...(input.teamId !== undefined ? { teamId: input.teamId } : {}),
                 members: input.members,
                 title: input.title,
             },
-        }, input.members);
+        }, input.members));
     }
     async updateGroup(input) {
         return this.sendChat(input.groupId, {

package/lib/runtime/conversationRead.js

@@ -13,7 +13,7 @@ export function recordConversationRead(state, conversationId, messages = [], ope
             indexedIds.add(message.id);
             return (message.threadRootId ?? undefined) === threadRootId && !message.recalled && message.from !== state.profileId && message.recipients.includes(state.profileId);
         });
-        const latest = incoming.filter(message => message.readPolicy === "visible" && message.seq > readingCursor(source, threadRootId))
+        const latest = incoming.filter(message => message.readPolicy === "visible" && !source.preservedReadMessageIds?.includes(message.id) && message.seq > readingCursor(source, threadRootId))
             .reduce((last, message) => !last || message.seq > last.seq ? message : last, undefined);
         if (latest)
             next = recordReadIntent(next, { operationId: operationId(), threadId: source.id, messageId: latest.id, readPolicy: "visible" });

package/lib/runtime/conversationReading.js

@@ -13,7 +13,7 @@ export function projectConversationReading(state, conversation, candidates = [])
     for (const source of sources)
         for (const message of source.messages) {
             indexed.add(message.id);
-            messageReading[message.id] = { seq: message.seq, readPolicy: message.readPolicy, read: message.recalled || hidden.get(message.id)?.has(message.from) === true || message.from === state.profileId || !message.recipients.includes(state.profileId) || (message.readPolicy === "explicit" ? source.explicitReadMessageIds.includes(message.id) : message.seq <= readingCursor(source, message.threadRootId)) };
+            messageReading[message.id] = { seq: message.seq, readPolicy: message.readPolicy, read: source.preservedReadMessageIds?.includes(message.id) === true || message.recalled || hidden.get(message.id)?.has(message.from) === true || message.from === state.profileId || !message.recipients.includes(state.profileId) || (message.readPolicy === "explicit" ? source.explicitReadMessageIds.includes(message.id) : message.seq <= readingCursor(source, message.threadRootId)) };
         }
     const observed = new Map();
     for (const intent of state?.observedReadIntents ?? [])

package/lib/runtime/durableSender.js

@@ -1,3 +1,4 @@
+import { groupIdCollision } from "./groupIdentity.js";
 import { Dexie } from "dexie";
 import { validMessageIdentifier } from "./outgoingContent.js";
 import { outboxDatabase, prepareOutboxSchema } from "./outboxSchema.js";
@@ -500,7 +501,7 @@ export class DurableChatSender {
         catch (error) {
             // A failed delivery can already be durable remotely, including the first
             // lost ACK. Proof recovery never sends a second wire in this attempt.
-            if (statefulGroup(record.message) && this.options.reconcile && transmitting && !this.closed && !this.closing && !this.withdrawn) {
+            if (!groupIdCollision(error) && statefulGroup(record.message) && this.options.reconcile && transmitting && !this.closed && !this.closing && !this.withdrawn) {
                 try {
                     if (await this.reconcile(record)) {
                         await this.confirm([hash]);

package/lib/runtime/groupIdentity.d.ts

@@ -0,0 +1,4 @@
+/** Only a definitive create rejection may choose a new UUID. Unknown delivery
+ * outcomes retain the original message/idempotency identity. */
+export declare function groupIdCollision(error: unknown): boolean;
+export declare function createUniqueGroup<T>(initialId: string | undefined, create: (groupId: string) => Promise<T>, uuid?: () => string): Promise<T>;

package/lib/runtime/groupIdentity.js

@@ -0,0 +1,26 @@
+/** Only a definitive create rejection may choose a new UUID. Unknown delivery
+ * outcomes retain the original message/idempotency identity. */
+export function groupIdCollision(error) {
+    let current = error;
+    const seen = new Set();
+    while (current instanceof Error && !seen.has(current)) {
+        seen.add(current);
+        if (current.message === "GROUP_ID_CONFLICT")
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+export async function createUniqueGroup(initialId, create, uuid = () => crypto.randomUUID()) {
+    let id = initialId ?? uuid();
+    for (let attempt = 0; attempt < 8; attempt++)
+        try {
+            return await create(id);
+        }
+        catch (error) {
+            if (!groupIdCollision(error) || attempt === 7)
+                throw error;
+            id = uuid();
+        }
+    throw new Error("GROUP_ID_GENERATION_EXHAUSTED");
+}

package/lib/runtime/readIndex.d.ts

@@ -27,6 +27,8 @@ export type ReadingOperation = {
     explicitReadMessageIds: string[];
 };
 export type IndexedReadThread = {
+    /** Read facts retained when server-side thread organization moves a message. */
+    preservedReadMessageIds?: string[];
     /** Durable source ID: reading positions must remain attached to this ID. */
     id: string;
     teamId?: string;

package/lib/runtime/readIndex.js

@@ -50,6 +50,8 @@ function validateThread(thread) {
         throw new Error("INVALID_READ_TEAM");
     if (thread.conversationId !== undefined && (!thread.conversationId || !thread.teamId))
         throw new Error("INVALID_READ_CONVERSATION");
+    if (thread.preservedReadMessageIds !== undefined && (!Array.isArray(thread.preservedReadMessageIds) || thread.preservedReadMessageIds.some(id => typeof id !== "string" || !id)))
+        throw new Error("INVALID_PRESERVED_READ_MESSAGES");
     if (Object.entries(thread.messageThreadReadThrough ?? {}).some(([root, seq]) => !validMessageThreadRoot(root) || !Number.isSafeInteger(seq) || seq < 0))
         throw new Error("INVALID_MESSAGE_THREAD_READING");
     const ids = new Set(), positions = new Set();
@@ -94,7 +96,7 @@ export function installReadSnapshot(current, snapshot) {
     for (const previous of current.threads) {
         const thread = byId.get(previous.id);
         if (thread)
-            byId.set(thread.id, { ...thread, ...mergeDiscussionCursors(thread, previous), readThroughSeq: Math.max(thread.readThroughSeq, previous.readThroughSeq),
+            byId.set(thread.id, { ...thread, ...mergeDiscussionCursors(thread, previous), preservedReadMessageIds: [...new Set([...(thread.preservedReadMessageIds ?? []), ...(previous.preservedReadMessageIds ?? [])])], readThroughSeq: Math.max(thread.readThroughSeq, previous.readThroughSeq),
                 explicitReadMessageIds: [...new Set([...thread.explicitReadMessageIds, ...previous.explicitReadMessageIds])] });
     }
     return resolveObservedReads({ ...snapshot, threads: [...byId.values()], pending, observedReadIntents: current.observedReadIntents ?? [] });
@@ -110,7 +112,7 @@ export function applyReadChange(current, change) {
     const incoming = cloneThread(change.thread);
     const pending = current.pending.filter(operation => operation.threadId !== incoming.id || !covered(incoming, operation));
     const previous = current.threads.find(thread => thread.id === incoming.id);
-    const merged = previous ? { ...incoming, ...mergeDiscussionCursors(incoming, previous), readThroughSeq: Math.max(incoming.readThroughSeq, previous.readThroughSeq),
+    const merged = previous ? { ...incoming, ...mergeDiscussionCursors(incoming, previous), preservedReadMessageIds: [...new Set([...(incoming.preservedReadMessageIds ?? []), ...(previous.preservedReadMessageIds ?? [])])], readThroughSeq: Math.max(incoming.readThroughSeq, previous.readThroughSeq),
         explicitReadMessageIds: [...new Set([...incoming.explicitReadMessageIds, ...previous.explicitReadMessageIds])] } : incoming;
     const projected = pending.filter(operation => operation.threadId === incoming.id).reduce(applyOperation, merged);
     return resolveObservedReads({ ...current, syncCursor: change.syncCursor, pending, threads: [...current.threads.filter(t => t.id !== incoming.id), projected] });
@@ -154,7 +156,7 @@ export function recordVisibleRead(current, threadId, messageId, operationId) {
     const message = thread?.messages.find(m => m.id === messageId);
     if (!thread || !message || message.readPolicy !== "visible")
         throw new Error("INVALID_VISIBLE_READ");
-    if (message.seq <= readingCursor(thread, message.threadRootId))
+    if (thread.preservedReadMessageIds?.includes(message.id) || message.seq <= readingCursor(thread, message.threadRootId))
         return current;
     return enqueue(current, { operationId, threadId: thread.id, ...(message.threadRootId == null ? {} : { threadRootId: message.threadRootId }), readThroughSeq: message.seq, readThroughMessageId: message.id, explicitReadMessageIds: [] });
 }
@@ -198,7 +200,7 @@ export function unreadInThread(state, threadId, hidden, threadRootId) {
         throw new Error("UNKNOWN_READ_THREAD");
     const explicit = new Set(thread.explicitReadMessageIds);
     const messages = thread.messages.filter(message => (threadRootId === undefined || message.threadRootId === threadRootId) && !message.recalled && !hidden?.get(message.id)?.has(message.from) && !(message.readingControl || isReadingControl(message.payload, state.appId)) && message.from !== state.profileId && message.recipients.includes(state.profileId)
-        && (message.readPolicy === "explicit" ? !explicit.has(message.id) : message.seq > readingCursor(thread, message.threadRootId)));
+        && !thread.preservedReadMessageIds?.includes(message.id) && (message.readPolicy === "explicit" ? !explicit.has(message.id) : message.seq > readingCursor(thread, message.threadRootId)));
     const unreadMessageCount = messages.length;
     const unreadMentionCount = messages.filter(message => message.mentions.includes(state.profileId)).length;
     return { unreadMessageCount, unreadMentionCount, badgeCount: thread.kind === "group" ? unreadMentionCount : unreadMessageCount };

package/lib/runtime/socialReadClient.d.ts

@@ -14,6 +14,7 @@ export type SocialMessagePage = {
     resetRequired: boolean;
 };
 export type MessageThreadSummary = {
+    ownerAgentId?: string;
     rootMessageId: string;
     replyCount: number;
     unreadCount: number;

package/lib/runtime/socialReadClient.js

@@ -59,7 +59,7 @@ export class SocialReadClient {
         const value = await this.request("message-threads", { threadId: input.threadId, ...this.teamQuery(input.teamId), rootMessageIds: JSON.stringify(input.rootMessageIds) }, signal);
         const roots = new Set(input.rootMessageIds), seen = new Set();
         if (!value || value.appId !== this.options.appId || value.threadId !== input.threadId || !Number.isSafeInteger(value.revision) || value.revision < 0 || !Array.isArray(value.items) || value.items.length !== roots.size || value.items.some(item => {
-            const invalid = !roots.has(item.rootMessageId) || seen.has(item.rootMessageId) || !Number.isSafeInteger(item.replyCount) || item.replyCount < 0 || !Number.isSafeInteger(item.unreadCount) || item.unreadCount < 0 || item.unreadCount > item.replyCount || !Array.isArray(item.participantProfileIds);
+            const invalid = item.ownerAgentId !== undefined && (typeof item.ownerAgentId !== "string" || !/^0x[a-f0-9]{64}$/.test(item.ownerAgentId)) || !roots.has(item.rootMessageId) || seen.has(item.rootMessageId) || !Number.isSafeInteger(item.replyCount) || item.replyCount < 0 || !Number.isSafeInteger(item.unreadCount) || item.unreadCount < 0 || item.unreadCount > item.replyCount || !Array.isArray(item.participantProfileIds);
             seen.add(item.rootMessageId);
             return invalid;
         }))
@@ -67,7 +67,6 @@ export class SocialReadClient {
         return value;
     }
     group(input, signal) {
-        this.requireTeam(input.teamId);
         return this.request("group", { groupId: input.groupId, ...this.teamQuery(input.teamId) }, signal);
     }
     relationship(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.83",
+  "version": "0.12.0-next.85",
   "description": "Local-first chat SDK, message subscriptions, reading state, and shared chat UI primitives",
   "type": "module",
   "main": "./lib/index.js",