@peers-app/peers-sdk 0.21.1 → 0.21.3

package/dist/context/user-context.d.ts

@@ -23,10 +23,17 @@ export declare class UserContext {
     constructor(userId: string, dataSourceFactory: DataSourceFactory, ephemeral?: boolean | undefined);
     private init;
     /**
-     * We want to load all packages as part of user context initialization
-     * so any tables in packages have been registered are available at sync time
+     * Loads all packages for the user's personal data context and every group
+     * they are a part of.
+     *
+     * Callers that `await` this (e.g. device init) block until every package
+     * bundle has been evaluated. That is intentional when tools/contracts must
+     * be ready before the device is considered initialized, but it does add
+     * package-load latency to startup compared to fire-and-forget loading.
      */
-    private loadAllPackages;
+    loadAllPackages(opts?: {
+        force?: boolean;
+    }): Promise<void>;
     private loadGroupContexts;
     getDataContext(groupId: string): DataContext;
     /** Wait for any pending `currentlyActiveGroupId` pvar write to be flushed to the DB. */

package/dist/context/user-context.js

@@ -44,22 +44,22 @@ class UserContext {
             await this.loadUserContextObservablesFromDB();
         }
         await this.loadGroupContexts();
-        await this.loadAllPackages();
         return this;
     }
     /**
-     * We want to load all packages as part of user context initialization
-     * so any tables in packages have been registered are available at sync time
+     * Loads all packages for the user's personal data context and every group
+     * they are a part of.
+     *
+     * Callers that `await` this (e.g. device init) block until every package
+     * bundle has been evaluated. That is intentional when tools/contracts must
+     * be ready before the device is considered initialized, but it does add
+     * package-load latency to startup compared to fire-and-forget loading.
      */
-    loadAllPackages() {
-        this.userDataContext.packageLoader
-            .loadAllPackages()
-            .catch((err) => console.error("[UserContext] loadAllPackages failed for userDataContext:", err));
-        for (const groupContext of this.groupDataContexts.values()) {
-            groupContext.packageLoader
-                .loadAllPackages()
-                .catch((err) => console.error("[UserContext] loadAllPackages failed for groupContext:", err));
-        }
+    async loadAllPackages(opts) {
+        await Promise.all([
+            this.userDataContext.packageLoader.loadAllPackages(opts),
+            ...[...this.groupDataContexts.values()].map((ctx) => ctx.packageLoader.loadAllPackages(opts)),
+        ]);
     }
     async loadGroupContexts() {
         const groupsTable = (0, data_1.Groups)(this.userDataContext);

package/dist/contracts/__tests__/builder.test.js

@@ -97,10 +97,12 @@ describe("definePackage", () => {
         expect(result.contracts[1].contractId).toBe(NOTES_ID);
     });
     it("records consumed contracts", () => {
+        let tasksHandle;
+        let authHandle;
         const result = (0, builder_1.definePackage)((pkg) => {
             pkg.packageId = TEST_PKG_ID;
-            pkg.consumes(TASKS_ID, 1);
-            pkg.consumes(AUTH_ID, 2);
+            tasksHandle = pkg.consumes(TASKS_ID, 1);
+            authHandle = pkg.consumes(AUTH_ID, 2);
             const projects = pkg.contract(PROJECTS_ID, 1, "Projects");
             projects.tables = [
                 {
@@ -114,8 +116,160 @@ describe("definePackage", () => {
             ];
         });
         expect(result.consumes).toHaveLength(2);
-        expect(result.consumes[0]).toEqual({ contractId: TASKS_ID, version: 1 });
-        expect(result.consumes[1]).toEqual({ contractId: AUTH_ID, version: 2 });
+        expect(result.consumes[0].contractId).toBe(TASKS_ID);
+        expect(result.consumes[0].version).toBe(1);
+        expect(result.consumes[0].handle).toBe(tasksHandle);
+        expect(result.consumes[1].contractId).toBe(AUTH_ID);
+        expect(result.consumes[1].version).toBe(2);
+        expect(result.consumes[1].handle).toBe(authHandle);
+    });
+    it("preserves consume options and returns a deferred handle", () => {
+        const preferredProviderId = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.consumes(TASKS_ID, 1, {
+                providerPackageIds: [preferredProviderId],
+                fallbackToDefaultProvider: true,
+            });
+            pkg.consumes(AUTH_ID, 2, {
+                optional: true,
+                providerPackageIds: [preferredProviderId],
+                fallbackToDefaultProvider: false,
+            });
+        });
+        const [required, optional] = result.consumes;
+        expect(required).toMatchObject({
+            contractId: TASKS_ID,
+            version: 1,
+            providerPackageIds: [preferredProviderId],
+            fallbackToDefaultProvider: true,
+        });
+        expect(required.optional).toBeUndefined();
+        expect(required.handle).toBeDefined();
+        expect(typeof required.handle?.consumer.then).toBe("function");
+        // Handle itself must not be thenable (naive await on the return value must not wait).
+        expect(required.handle.then).toBeUndefined();
+        expect(optional).toMatchObject({
+            contractId: AUTH_ID,
+            version: 2,
+            optional: true,
+            providerPackageIds: [preferredProviderId],
+            fallbackToDefaultProvider: false,
+        });
+        expect(optional.handle).toBeDefined();
+    });
+    it("accepts a type argument that narrows the resolved consumer", () => {
+        (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const required = pkg.consumes(TASKS_ID, 1);
+            const optional = pkg.consumes(AUTH_ID, 1, { optional: true });
+            // Compile-time checks: required → TypedConsumer; optional → TypedConsumer | undefined.
+            void (async () => {
+                const requiredConsumer = await required.consumer;
+                const optionalConsumer = await optional.consumer;
+                void requiredConsumer;
+                void optionalConsumer;
+                // Named table methods (not only dataChanged) must be present on ITableProxy.
+                const _list = requiredConsumer.tables.ConsoleLogs.list;
+                const _deleteOldLogs = requiredConsumer.tables.ConsoleLogs.deleteOldLogs;
+                void _list;
+                void _deleteOldLogs;
+                // Typed consumers may omit empty bags — these must not exist on TypedConsumer.
+                // @ts-expect-error no tools bag on slim typed consumer
+                void requiredConsumer.tools;
+                // @ts-expect-error no events bag on slim typed consumer
+                void requiredConsumer.events;
+                // @ts-expect-error no observables bag on slim typed consumer
+                void requiredConsumer.observables;
+                // @ts-expect-error optional consume must allow undefined
+                const tooNarrow = await optional.consumer;
+                void tooNarrow;
+            })();
+        });
+    });
+    it("ILogsConsumer exposes ConsoleLogs as ITableProxy without empty bags", () => {
+        (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const handle = pkg.consumes(TASKS_ID, 1, { optional: true });
+            void (async () => {
+                const logs = await handle.consumer;
+                if (!logs)
+                    return;
+                const _list = logs.tables.ConsoleLogs.list;
+                const _deleteOldLogs = logs.tables.ConsoleLogs.deleteOldLogs;
+                void _list;
+                void _deleteOldLogs;
+                // @ts-expect-error ILogsConsumer has no tools bag
+                void logs.tools;
+                // @ts-expect-error ILogsConsumer has no events bag
+                void logs.events;
+                // @ts-expect-error ILogsConsumer has no observables bag
+                void logs.observables;
+            })();
+        });
+    });
+    it("settles required handles with a consumer and optional handles with undefined", async () => {
+        const { settleConsumedContractHandle, rejectConsumedContractHandle } = await Promise.resolve().then(() => require("../builder"));
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.consumes(TASKS_ID, 1);
+            pkg.consumes(AUTH_ID, 1, { optional: true });
+        });
+        const requiredHandle = result.consumes[0].handle;
+        const optionalHandle = result.consumes[1].handle;
+        expect(requiredHandle).toBeDefined();
+        expect(optionalHandle).toBeDefined();
+        if (!requiredHandle || !optionalHandle) {
+            throw new Error("expected consumes handles");
+        }
+        const fakeConsumer = {
+            contractId: TASKS_ID,
+            version: 1,
+            tables: {},
+            tools: {},
+            observables: {},
+            events: {},
+            loadingPromise: Promise.resolve(),
+            dispose: () => { },
+        };
+        settleConsumedContractHandle(requiredHandle, fakeConsumer);
+        settleConsumedContractHandle(optionalHandle, undefined);
+        await expect(requiredHandle.consumer).resolves.toBe(fakeConsumer);
+        await expect(optionalHandle.consumer).resolves.toBeUndefined();
+        expect(() => settleConsumedContractHandle(requiredHandle, fakeConsumer)).toThrow("already been settled");
+        expect(() => rejectConsumedContractHandle(optionalHandle, new Error("late"))).toThrow("already been settled");
+    });
+    it("rejects a required consume handle once", async () => {
+        const { rejectConsumedContractHandle } = await Promise.resolve().then(() => require("../builder"));
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.consumes(TASKS_ID, 1);
+        });
+        const requiredHandle = result.consumes[0].handle;
+        expect(requiredHandle).toBeDefined();
+        if (!requiredHandle) {
+            throw new Error("expected consumes handle");
+        }
+        const err = new Error("No provider for Tasks");
+        rejectConsumedContractHandle(requiredHandle, err);
+        await expect(requiredHandle.consumer).rejects.toThrow("No provider for Tasks");
+        expect(() => rejectConsumedContractHandle(requiredHandle, err)).toThrow("already been settled");
+    });
+    it("throws when consumes providerPackageIds contains an invalid peer ID", () => {
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.consumes(TASKS_ID, 1, { providerPackageIds: ["not-valid"] });
+            });
+        }).toThrow("providerPackageIds");
+    });
+    it("throws when consumes version is not a positive integer", () => {
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.consumes(TASKS_ID, 0);
+            });
+        }).toThrow("positive integer");
     });
     it("records alsoImplements declarations", () => {
         const result = (0, builder_1.definePackage)((pkg) => {

package/dist/contracts/__tests__/contract-resolvers.test.js

@@ -146,3 +146,97 @@ describe("Self-trusted contract caller authorization", () => {
         router.dispose();
     });
 });
+describe("local user-context contract routing", () => {
+    function setupLocalRouter() {
+        const userId = (0, utils_1.newid)();
+        const groupId = (0, utils_1.newid)();
+        const personalContext = { dataContextId: userId };
+        const groupContext = { dataContextId: groupId };
+        const getDataContext = jest.fn((dataContextId) => {
+            if (dataContextId === userId)
+                return personalContext;
+            if (dataContextId === groupId)
+                return groupContext;
+            throw new Error("unexpected data context");
+        });
+        const userContext = {
+            userId,
+            userDataContext: personalContext,
+            groupDataContexts: new Map([[groupId, groupContext]]),
+            groupIds: jest.fn(() => [groupId]),
+            getDataContext,
+        };
+        const contractId = (0, utils_1.newid)();
+        (0, index_1.registerContractResolver)(contractId, 1, ({ dataContext }) => ({
+            contractId,
+            version: 1,
+            tools: {
+                inspect: {
+                    tool: {
+                        toolId: (0, utils_1.newid)(),
+                        name: "inspect",
+                        usageDescription: "Return the authorized route.",
+                        inputSchema: { type: "simple", fields: [] },
+                        outputSchema: { type: "simple", fields: [] },
+                        code: "",
+                        packageId: (0, utils_1.newid)(),
+                    },
+                    toolFn: () => dataContext.dataContextId,
+                },
+            },
+        }));
+        const [consumerTransport, providerTransport] = (0, index_1.inProcessTransportPair)();
+        return {
+            consumerTransport,
+            contractId,
+            getDataContext,
+            groupId,
+            providerTransport,
+            userContext,
+            userId,
+        };
+    }
+    const makeToolCall = (contractId, dataContextId) => ({
+        contractId,
+        version: 1,
+        member: "tool",
+        name: "inspect",
+        operation: "run",
+        args: [],
+        dataContextId,
+    });
+    it("registers synchronously and waits for a lazily loaded user context", async () => {
+        const setup = setupLocalRouter();
+        let resolveUserContext;
+        const userContextPromise = new Promise((resolve) => {
+            resolveUserContext = resolve;
+        });
+        const router = (0, index_1.createLocalUserContextContractProviderRouter)(setup.providerTransport, {
+            getUserContext: () => userContextPromise,
+        });
+        const result = setup.consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeToolCall(setup.contractId));
+        resolveUserContext(setup.userContext);
+        await expect(result).resolves.toBe(setup.userId);
+        router.dispose();
+    });
+    it("routes known groups and rejects unknown contexts without creating them", async () => {
+        const setup = setupLocalRouter();
+        const router = (0, index_1.createLocalUserContextContractProviderRouter)(setup.providerTransport, {
+            getUserContext: async () => setup.userContext,
+        });
+        await expect(setup.consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeToolCall(setup.contractId, setup.groupId))).resolves.toBe(setup.groupId);
+        const unknownId = (0, utils_1.newid)();
+        await expect(setup.consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeToolCall(setup.contractId, unknownId))).rejects.toThrow("not available locally");
+        expect(setup.getDataContext).not.toHaveBeenCalledWith(unknownId);
+        router.dispose();
+    });
+    it("enforces an optional contract allowlist before resolving a provider", async () => {
+        const setup = setupLocalRouter();
+        const router = (0, index_1.createLocalUserContextContractProviderRouter)(setup.providerTransport, {
+            getUserContext: async () => setup.userContext,
+            allowedContractIds: new Set([(0, utils_1.newid)()]),
+        });
+        await expect(setup.consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeToolCall(setup.contractId))).rejects.toThrow("contract");
+        router.dispose();
+    });
+});

package/dist/contracts/__tests__/host-contract-transport.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/contracts/__tests__/host-contract-transport.test.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+describe("host contract transport", () => {
+    const disposers = [];
+    afterEach(() => {
+        while (disposers.length > 0) {
+            disposers.pop()?.();
+        }
+    });
+    it("publishes registration lifecycle and clears the active transport", () => {
+        const [transport] = (0, index_1.inProcessTransportPair)();
+        const values = [];
+        const unsubscribe = (0, index_1.subscribeHostContractTransport)((value) => values.push(value));
+        const dispose = (0, index_1.registerHostContractTransport)(transport);
+        disposers.push(dispose);
+        expect((0, index_1.getHostContractTransport)()).toBe(transport);
+        dispose();
+        unsubscribe();
+        expect((0, index_1.getHostContractTransport)()).toBeUndefined();
+        expect(values).toEqual([undefined, transport, undefined]);
+    });
+    it("does not let a stale registration disposer clear its replacement", () => {
+        const [first] = (0, index_1.inProcessTransportPair)();
+        const [second] = (0, index_1.inProcessTransportPair)();
+        const disposeFirst = (0, index_1.registerHostContractTransport)(first);
+        const disposeSecond = (0, index_1.registerHostContractTransport)(second);
+        disposers.push(disposeFirst, disposeSecond);
+        disposeFirst();
+        expect((0, index_1.getHostContractTransport)()).toBe(second);
+    });
+    it("waits for a transport registered after startup", async () => {
+        const pending = (0, index_1.waitForHostContractTransport)();
+        const [transport] = (0, index_1.inProcessTransportPair)();
+        const dispose = (0, index_1.registerHostContractTransport)(transport);
+        disposers.push(dispose);
+        await expect(pending).resolves.toBe(transport);
+    });
+    it("rejects when no transport arrives before timeoutMs", async () => {
+        jest.useFakeTimers();
+        try {
+            const pending = (0, index_1.waitForHostContractTransport)({ timeoutMs: 25 });
+            const expectation = expect(pending).rejects.toThrow("Timed out waiting for host contract transport after 25ms");
+            await jest.advanceTimersByTimeAsync(25);
+            await expectation;
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+});