@pmate/chat-sdk 0.12.0-next.82 → 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/readSync.d.ts

@@ -20,5 +20,6 @@ export declare class ReadSyncClient {
     stop(): void;
     synchronize(): Promise<ReadIndexState>;
     private request;
+    private repairLegacyDiscussion;
     private run;
 }

package/lib/runtime/readSync.js

@@ -39,8 +39,12 @@ export class ReadSyncClient {
             const response = await (this.options.fetch ?? globalThis.fetch)(`${this.options.hubHttpUrl.replace(/\/$/, "")}${path}`, {
                 ...init, signal: timeout.signal, headers: { ...init.headers, authorization: `Bearer ${this.options.sessionToken}` },
             });
-            if (!response.ok)
-                throw Object.assign(new Error(`READ_SYNC_HTTP_${response.status}`), { status: response.status });
+            if (!response.ok) {
+                // Keep only a fixed domain code, never a provider response body.
+                const failure = await response.json().catch(() => undefined);
+                const code = failure?.message === "INVALID_READING_CURSOR" ? failure.message : undefined;
+                throw Object.assign(new Error(`READ_SYNC_HTTP_${response.status}`), { status: response.status, code });
+            }
             const envelope = await response.json();
             if (envelope.success !== true || envelope.data === undefined)
                 throw new Error("INVALID_READ_SYNC_RESPONSE");
@@ -51,7 +55,42 @@ export class ReadSyncClient {
             this.controller.signal.removeEventListener("abort", abort);
         }
     }
-    async run() {
+    async repairLegacyDiscussion(operation, versions) {
+        if (operation.threadRootId !== undefined || operation.readThroughSeq <= 0 || operation.explicitReadMessageIds.length)
+            return false;
+        const { appId, profileId, persistence } = this.options;
+        const query = new URLSearchParams({ appId, profileId, ...(this.options.metadataOnly ? { metadataOnly: "true" } : {}) });
+        const snapshot = await this.request(`/api/social/reading/snapshot?${query}`);
+        // Validate the complete response before changing any durable operation.
+        installReadSnapshot(createReadIndex(appId, profileId), snapshot);
+        const thread = snapshot.threads.find(thread => thread.id === operation.threadId);
+        const message = thread?.messages.find(message => message.id === operation.readThroughMessageId
+            && message.seq === operation.readThroughSeq && message.readPolicy === "visible" && message.threadRootId != null);
+        if (!thread || !message)
+            return false;
+        let repaired = false;
+        await persistence.update(appId, profileId, (state, currentVersions) => {
+            assertReadIndexVersions(versions, currentVersions);
+            if (this.controller.signal.aborted)
+                throw new Error("READ_SYNC_STOPPED");
+            const pending = state.pending.map(item => {
+                if (item.operationId !== operation.operationId || JSON.stringify(item) !== JSON.stringify(operation))
+                    return item;
+                repaired = true;
+                // New payload, new identity: an operation ID must never change meaning.
+                return { ...item, operationId: crypto.randomUUID(), threadRootId: message.threadRootId };
+            });
+            if (!repaired)
+                return state;
+            // Undo the rejected main-conversation optimistic position, then replay all
+            // remaining operations on the authoritative snapshot in their own scopes.
+            const threads = state.threads.map(item => item.id === thread.id && item.readThroughSeq === operation.readThroughSeq
+                ? { ...item, readThroughSeq: thread.readThroughSeq } : item);
+            return installReadSnapshot({ ...state, threads, pending }, snapshot);
+        });
+        return repaired;
+    }
+    async run(repairedLegacy = false) {
         const { appId, profileId, persistence } = this.options;
         const loaded = persistence.loadVersioned ? await persistence.loadVersioned(appId, profileId) : { state: await persistence.load(appId, profileId), versions: {} };
         const current = loaded.state ?? createReadIndex(appId, profileId);
@@ -72,9 +111,19 @@ export class ReadSyncClient {
         for (const operation of outgoing) {
             if (persistence.loadVersions)
                 assertReadIndexVersions(versions, await persistence.loadVersions(appId, profileId));
-            const receipt = await this.request("/api/social/reading", {
-                method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...operation, appId, profileId }),
-            });
+            let receipt;
+            try {
+                receipt = await this.request("/api/social/reading", {
+                    method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...operation, appId, profileId }),
+                });
+            }
+            catch (error) {
+                if (!repairedLegacy && error?.status === 400
+                    && error.code === "INVALID_READING_CURSOR"
+                    && await this.repairLegacyDiscussion(operation, versions))
+                    return this.run(true);
+                throw error;
+            }
             if (receipt.operationId !== operation.operationId || receipt.accepted !== true
                 || !Number.isSafeInteger(receipt.acceptedAt) || receipt.acceptedAt <= 0)
                 throw new Error("INVALID_READING_RECEIPT");

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.82",
+  "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",