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

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/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/socialReadClient.js

@@ -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.84",
   "description": "Local-first chat SDK, message subscriptions, reading state, and shared chat UI primitives",
   "type": "module",
   "main": "./lib/index.js",