@peers-app/peers-sdk 0.27.0 → 0.27.1

package/dist/data/create-group.js

@@ -51,7 +51,7 @@ async function createGroup(userContext, input) {
     });
     await (0, groups_1.Groups)(groupDataContext).signAndSave(group);
     await (0, group_members_1.GroupMembers)(groupDataContext).signAndSave({
-        groupMemberId: (0, utils_1.newid)(),
+        groupMemberId: (0, utils_1.deterministicGroupMemberId)(groupId, me.userId),
         groupId,
         userId: me.userId,
         role: group_member_roles_1.GroupMemberRole.Founder,

package/dist/data/group-members.d.ts

@@ -36,6 +36,20 @@ export declare class GroupMembersTable extends Table<IGroupMember> {
     save(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     signAndSave(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     delete(groupMemberId: string): Promise<void>;
+    /**
+     * Settle two membership rows for the same user in the same group: devices that approved the
+     * same join at once could each write one, under a different id.
+     *
+     * Merged only when both rows grant the same access (role and deleted state), so nothing about
+     * the member's access changes. The id {@link deterministicGroupMemberId} gives wins if either
+     * row has it, otherwise the lexicographically smaller id; the winner is kept as it is, signature
+     * included. Rows that disagree stay queued for a person. A pure function of the two rows, so
+     * every device keeps the same one.
+     */
+    resolveUniqueConflict(incoming: IGroupMember, existing: IGroupMember): {
+        winner: IGroupMember;
+        loserId: string;
+    } | undefined;
     /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enableGroupMemberSigning(fn: (groupMember: IGroupMember) => IGroupMember): void;
     /** @deprecated Forbidden on GroupsTable; use save() */

package/dist/data/group-members.js

@@ -40,6 +40,7 @@ const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const decorators_1 = require("../data/orm/decorators");
 const zod_types_1 = require("../types/zod-types");
+const utils_1 = require("../utils");
 const group_member_roles_1 = require("./group-member-roles");
 const group_permissions_1 = require("./group-permissions");
 const table_1 = require("./orm/table");
@@ -125,6 +126,41 @@ let GroupMembersTable = (() => {
                 await this.signAndSave(groupMember);
             }
         }
+        /**
+         * Settle two membership rows for the same user in the same group: devices that approved the
+         * same join at once could each write one, under a different id.
+         *
+         * Merged only when both rows grant the same access (role and deleted state), so nothing about
+         * the member's access changes. The id {@link deterministicGroupMemberId} gives wins if either
+         * row has it, otherwise the lexicographically smaller id; the winner is kept as it is, signature
+         * included. Rows that disagree stay queued for a person. A pure function of the two rows, so
+         * every device keeps the same one.
+         */
+        resolveUniqueConflict(incoming, existing) {
+            if (incoming.groupId !== existing.groupId || incoming.userId !== existing.userId) {
+                return undefined;
+            }
+            if (incoming.groupMemberId === existing.groupMemberId) {
+                return undefined;
+            }
+            if (incoming.role !== existing.role ||
+                Boolean(incoming.deleted) !== Boolean(existing.deleted)) {
+                return undefined;
+            }
+            const derivedId = (0, utils_1.deterministicGroupMemberId)(incoming.groupId, incoming.userId);
+            let winner;
+            if (incoming.groupMemberId === derivedId) {
+                winner = incoming;
+            }
+            else if (existing.groupMemberId === derivedId) {
+                winner = existing;
+            }
+            else {
+                winner = incoming.groupMemberId < existing.groupMemberId ? incoming : existing;
+            }
+            const loser = winner === incoming ? existing : incoming;
+            return { winner, loserId: loser.groupMemberId };
+        }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enableGroupMemberSigning(fn) {
             signingGlobals[signingKey] = fn;

package/dist/data/group-members.test.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const group_members_1 = require("./group-members");
 const group_permissions_1 = require("./group-permissions");
 // Test the group members signature logic directly without ORM dependencies
 describe("Group Members Signature Logic", () => {
@@ -285,3 +287,50 @@ describe("Group Members Signature Logic", () => {
         });
     });
 });
+describe("GroupMembersTable.resolveUniqueConflict", () => {
+    const groupId = (0, utils_1.newid)();
+    const userId = (0, utils_1.newid)();
+    const resolve = (incoming, existing) => group_members_1.GroupMembersTable.prototype.resolveUniqueConflict.call({}, incoming, existing);
+    const row = (groupMemberId, overrides = {}) => ({
+        groupMemberId,
+        groupId,
+        userId,
+        role: group_permissions_1.GroupMemberRole.Writer,
+        signature: `sig-${groupMemberId}`,
+        ...overrides,
+    });
+    it("keeps the smaller id, unchanged, whichever row arrives", () => {
+        const [low, high] = [(0, utils_1.newid)(), (0, utils_1.newid)()].sort();
+        const a = row(low);
+        const b = row(high);
+        expect(resolve(a, b)).toEqual({ winner: a, loserId: high });
+        expect(resolve(b, a)).toEqual({ winner: a, loserId: high });
+        expect(resolve(b, a)?.winner.signature).toBe(`sig-${low}`);
+    });
+    it("prefers the id derived from the group and user", () => {
+        const derived = row((0, utils_1.deterministicGroupMemberId)(groupId, userId));
+        const other = row("00000000000000000000000001");
+        expect(resolve(other, derived)).toEqual({ winner: derived, loserId: other.groupMemberId });
+        expect(resolve(derived, other)).toEqual({ winner: derived, loserId: other.groupMemberId });
+    });
+    it("leaves rows that grant different access for a person to settle", () => {
+        const a = row((0, utils_1.newid)());
+        expect(resolve(a, row((0, utils_1.newid)(), { role: group_permissions_1.GroupMemberRole.Admin }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { deleted: true }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { userId: (0, utils_1.newid)() }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { groupId: (0, utils_1.newid)() }))).toBeUndefined();
+        expect(resolve(a, { ...a })).toBeUndefined();
+    });
+    it("treats a missing deleted flag as not deleted", () => {
+        const a = row((0, utils_1.newid)());
+        const b = row((0, utils_1.newid)(), { deleted: false });
+        expect(resolve(a, b)).toBeDefined();
+    });
+    it("depends only on the two signed rows and never modifies either one", () => {
+        const a = Object.freeze(row((0, utils_1.newid)()));
+        const b = Object.freeze(row((0, utils_1.newid)()));
+        const before = [structuredClone(a), structuredClone(b)];
+        expect(resolve(a, b)).toEqual(resolve(b, a));
+        expect([a, b]).toEqual(before);
+    });
+});

package/dist/invites/group-approval.js

@@ -31,7 +31,7 @@ async function buildGroupApproval(userContext, input) {
         // Groups created before founders got an explicit membership row: the founder role is
         // implicit (see `getUserRole`). Write the row now so it seeds to joiners like any admin.
         approvingMember = await groupMembersTable.signAndSave({
-            groupMemberId: (0, utils_1.newid)(),
+            groupMemberId: (0, utils_1.deterministicGroupMemberId)(input.groupId, userContext.userId),
             groupId: input.groupId,
             userId: userContext.userId,
             role: data_1.GroupMemberRole.Founder,
@@ -65,8 +65,10 @@ async function buildGroupApproval(userContext, input) {
         membership = await groupMembersTable.signAndSave(existingMember);
     }
     else {
+        // The same id on each of the approver's devices: a join several of them approve at once
+        // is one row, not rows that collide on (groupId, userId).
         membership = await groupMembersTable.signAndSave({
-            groupMemberId: (0, utils_1.newid)(),
+            groupMemberId: (0, utils_1.deterministicGroupMemberId)(input.groupId, input.joiner.userId),
             groupId: input.groupId,
             userId: input.joiner.userId,
             role: input.role,

package/dist/invites/group-approval.test.js

@@ -149,6 +149,8 @@ describe("group approval payloads", () => {
             role: group_member_roles_1.GroupMemberRole.Writer,
         });
         expect(approval.membership.signature).toContain(":");
+        // Each of the approver's devices writes the same row for this join.
+        expect(approval.membership.groupMemberId).toBe((0, utils_1.deterministicGroupMemberId)(group.groupId, joiner.userId));
         expect(approval.seed.groupMembers.map((member) => member.userId)).toContain(admin.userId);
         expect(approval.seed.devices[0]).toMatchObject({
             deviceId: admin.deviceId,

package/dist/utils.d.ts

@@ -37,6 +37,23 @@ export declare function deterministicTableId(identity: string): string;
  * @param id Peer ID to inspect.
  */
 export declare function isDeterministicTableId(id: string): boolean;
+/**
+ * The ID of a user's membership row in a group, the same on every device.
+ *
+ * Several of an admin's devices can approve the same join at once; with this ID they write one
+ * row, which merges as an ordinary update, instead of rows that collide on the
+ * `(groupId, userId)` unique index.
+ *
+ * @param groupId The group.
+ * @param userId The member.
+ */
+export declare function deterministicGroupMemberId(groupId: string, userId: string): string;
+/**
+ * Return whether a peer ID was generated by {@link deterministicGroupMemberId}.
+ *
+ * @param id Peer ID to inspect.
+ */
+export declare function isDeterministicGroupMemberId(id: string): boolean;
 /** Resolves after `ms` milliseconds (0 yields a microtask-yield on most runtimes). */
 export declare function sleep(ms?: number): Promise<void>;
 /** Turns `fooBar` into `Foo Bar` for labels (also replaces `_` with space). */
@@ -93,6 +110,8 @@ export declare function getTimestamp(): number;
  * @param opts.timeout Clamped timeout; defaults to {@link PeerDeviceConsts} min/max
  * @param opts.retriesOnError Max error retries
  * @param opts.retriesOnTimeout Max “timed out” races before giving up
+ * @param opts.shouldRetry Return false for a terminal error that must be reported immediately.
+ * @param opts.logFailure Log exhausted error retries; defaults to `console.error`.
  * @throws Last error, timeout exhaustion, or if the connection is closed
  */
 export declare function retryOnErrorOrTimeout<T>({ fn, connection, opts, }: {
@@ -102,6 +121,8 @@ export declare function retryOnErrorOrTimeout<T>({ fn, connection, opts, }: {
         timeout?: number;
         retriesOnError?: number;
         retriesOnTimeout?: number;
+        shouldRetry?: (error: unknown) => boolean;
+        logFailure?: (message: string, error: unknown) => void;
     };
 }): Promise<T>;
 /**

package/dist/utils.js

@@ -7,6 +7,8 @@ exports.deterministicPvarId = deterministicPvarId;
 exports.isDeterministicPvarId = isDeterministicPvarId;
 exports.deterministicTableId = deterministicTableId;
 exports.isDeterministicTableId = isDeterministicTableId;
+exports.deterministicGroupMemberId = deterministicGroupMemberId;
+exports.isDeterministicGroupMemberId = isDeterministicGroupMemberId;
 exports.sleep = sleep;
 exports.camelCaseToSpaces = camelCaseToSpaces;
 exports.camelCaseToHyphens = camelCaseToHyphens;
@@ -48,6 +50,8 @@ function simpleObjectHash(obj) {
 const DETERMINISTIC_PVAR_PREFIX = "000pvar0";
 /** Well-known prefix for deterministic package-table IDs. */
 const DETERMINISTIC_TABLE_PREFIX = "000tbl00";
+/** Well-known prefix for deterministic group-membership IDs. */
+const DETERMINISTIC_GROUP_MEMBER_PREFIX = "000gmbr0";
 /**
  * Converts a byte array to a base-36 string of the requested length, using unbiased modular reduction.
  * Bytes >= 252 are skipped to avoid bias (same technique as {@link cryptoRandomString}).
@@ -105,6 +109,27 @@ function deterministicTableId(identity) {
 function isDeterministicTableId(id) {
     return id.startsWith(DETERMINISTIC_TABLE_PREFIX);
 }
+/**
+ * The ID of a user's membership row in a group, the same on every device.
+ *
+ * Several of an admin's devices can approve the same join at once; with this ID they write one
+ * row, which merges as an ordinary update, instead of rows that collide on the
+ * `(groupId, userId)` unique index.
+ *
+ * @param groupId The group.
+ * @param userId The member.
+ */
+function deterministicGroupMemberId(groupId, userId) {
+    return deterministicPeerId(DETERMINISTIC_GROUP_MEMBER_PREFIX, `${groupId}:${userId}`);
+}
+/**
+ * Return whether a peer ID was generated by {@link deterministicGroupMemberId}.
+ *
+ * @param id Peer ID to inspect.
+ */
+function isDeterministicGroupMemberId(id) {
+    return id.startsWith(DETERMINISTIC_GROUP_MEMBER_PREFIX);
+}
 /** Resolves after `ms` milliseconds (0 yields a microtask-yield on most runtimes). */
 function sleep(ms = 0) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -243,6 +268,8 @@ function getTimestamp() {
  * @param opts.timeout Clamped timeout; defaults to {@link PeerDeviceConsts} min/max
  * @param opts.retriesOnError Max error retries
  * @param opts.retriesOnTimeout Max “timed out” races before giving up
+ * @param opts.shouldRetry Return false for a terminal error that must be reported immediately.
+ * @param opts.logFailure Log exhausted error retries; defaults to `console.error`.
  * @throws Last error, timeout exhaustion, or if the connection is closed
  */
 async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
@@ -258,8 +285,8 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
     let resultSet = false;
     let finalError;
     while (errorCount <= retriesOnError && timeoutCount <= retriesOnTimeout) {
+        let sleepTimeout = null;
         try {
-            let sleepTimeout = null;
             const sleepPromise = new Promise((resolve) => {
                 sleepTimeout = setTimeout(() => {
                     resolve();
@@ -292,14 +319,20 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
             finalError = error;
             connection.errorRate = connection.errorRate * 0.9 + 0.1;
             errorCount++;
+            if (opts.shouldRetry?.(error) === false)
+                throw error;
             if (connection.closed) {
                 throw new Error(`connection has been closed`);
             }
         }
+        finally {
+            if (sleepTimeout !== null)
+                clearTimeout(sleepTimeout);
+        }
         console.warn(`Call failed, retrying: timeout is ${timeout}ms, errorCount: ${errorCount} of ${retriesOnError}, timeoutCount: ${timeoutCount} of ${retriesOnTimeout + 1}. Last error:`, finalError);
     }
     if (finalError) {
-        console.error(`Retry failed after ${errorCount} errors and ${timeoutCount} timeouts. Last error:`, finalError);
+        (opts.logFailure ?? console.error)(`Retry failed after ${errorCount} errors and ${timeoutCount} timeouts. Last error:`, finalError);
         throw finalError;
     }
     else {

package/dist/utils.test.js

@@ -2,6 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const lodash_1 = require("lodash");
 const utils_1 = require("./utils");
+describe("retryOnErrorOrTimeout", () => {
+    it("reports a terminal error after one call and clears its timeout", async () => {
+        jest.useFakeTimers();
+        const error = new Error("No handler registered for event: listChanges_group");
+        const fn = jest.fn().mockRejectedValue(error);
+        try {
+            await expect((0, utils_1.retryOnErrorOrTimeout)({
+                fn,
+                connection: { deviceId: (0, utils_1.newid)(), latencyMs: 1, errorRate: 0, timestampLastApplied: 0 },
+                opts: { shouldRetry: () => false },
+            })).rejects.toBe(error);
+            expect(fn).toHaveBeenCalledTimes(1);
+            expect(jest.getTimerCount()).toBe(0);
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+});
 describe("readResponseTextCapped", () => {
     it("returns a body within the cap and refuses one over it", async () => {
         await expect((0, utils_1.readResponseTextCapped)(new Response("hello"), 5)).resolves.toBe("hello");
@@ -132,6 +151,23 @@ describe("newid", () => {
         });
     });
 });
+describe("deterministicGroupMemberId", () => {
+    it("preserves the membership identity protocol across SDK versions", () => {
+        expect((0, utils_1.deterministicGroupMemberId)("00000000000000000000000001", "00000000000000000000000002")).toBe("000gmbr0jzkpw7vuc2ew84u8c");
+    });
+    it("is a stable peer id per group and user", () => {
+        const groupId = (0, utils_1.newid)();
+        const userId = (0, utils_1.newid)();
+        const id = (0, utils_1.deterministicGroupMemberId)(groupId, userId);
+        expect(id).toMatch(/^[a-z0-9]{25}$/);
+        expect((0, utils_1.isid)(id)).toBe(true);
+        expect((0, utils_1.isDeterministicGroupMemberId)(id)).toBe(true);
+        expect((0, utils_1.deterministicGroupMemberId)(groupId, userId)).toBe(id);
+        expect((0, utils_1.deterministicGroupMemberId)(groupId, (0, utils_1.newid)())).not.toBe(id);
+        expect((0, utils_1.deterministicGroupMemberId)(userId, groupId)).not.toBe(id);
+        expect((0, utils_1.isDeterministicGroupMemberId)((0, utils_1.newid)())).toBe(false);
+    });
+});
 describe("debounceByArgs", () => {
     beforeEach(() => {
         jest.useFakeTimers();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"