@peers-app/peers-sdk 0.23.4 → 0.23.6

package/dist/package-loader/isolated-artifact.test.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const access_level_1 = require("../data/access-level");
+const field_type_1 = require("../types/field-type");
+const utils_1 = require("../utils");
+const isolated_artifact_1 = require("./isolated-artifact");
+function makeArtifact(overrides = {}) {
+    const packageId = (0, utils_1.newid)();
+    const contractId = (0, utils_1.newid)();
+    return {
+        packageId,
+        contractId,
+        artifact: {
+            manifest: {
+                packageId,
+                version: "1.0.0",
+                provides: [
+                    {
+                        contractId,
+                        version: 1,
+                        name: "Greeter",
+                        description: "Hello",
+                        tools: [
+                            {
+                                name: "greet",
+                                usageDescription: "Say hello",
+                                inputFields: [{ name: "name", type: field_type_1.FieldType.string, optional: true }],
+                                outputFields: [{ name: "greeting", type: field_type_1.FieldType.string }],
+                                suggestedAccessLevel: access_level_1.AccessLevel.Writer,
+                            },
+                        ],
+                    },
+                ],
+                consumes: [],
+                tables: [],
+            },
+            providerSource: "registerContractTool('x', 1, 'greet', function () {})",
+            ...overrides,
+        },
+    };
+}
+describe("isolated package artifact", () => {
+    test("serializes and parses a valid envelope", () => {
+        const { artifact, contractId } = makeArtifact();
+        const bundle = (0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact);
+        expect(bundle.startsWith(`${isolated_artifact_1.ISOLATED_PACKAGE_MAGIC}\n`)).toBe(true);
+        expect((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(bundle)).toBe(true);
+        expect((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)("module.exports = {}")).toBe(false);
+        const parsed = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundle);
+        expect(parsed.manifest.packageId).toBe(artifact.manifest.packageId);
+        expect(parsed.manifest.provides[0].tools[0].inputFields).toEqual([
+            { name: "name", type: field_type_1.FieldType.string, optional: true },
+        ]);
+        const definition = (0, isolated_artifact_1.isolatedContractToDefinition)(parsed.manifest.provides[0], parsed.manifest.tables ?? []);
+        expect(definition.contractId).toBe(contractId);
+        expect(definition.tools[0].name).toBe("greet");
+        expect(definition.tables).toEqual([]);
+    });
+    test("defaults omitted tables to an empty array", () => {
+        const { artifact } = makeArtifact();
+        delete artifact.manifest.tables;
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect(manifest.tables).toEqual([]);
+    });
+    test("accepts a package-private table without adding it to the contract definition", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                description: "Owned state",
+                primaryKeyName: "stateId",
+                fields: [
+                    { name: "stateId", type: field_type_1.FieldType.id },
+                    { name: "count", type: field_type_1.FieldType.number },
+                ],
+            },
+        ];
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect(manifest.tables?.[0].versionNumber).toBe(1);
+        const definition = (0, isolated_artifact_1.isolatedContractToDefinition)(manifest.provides[0], manifest.tables ?? []);
+        expect(definition.tables).toEqual([]);
+    });
+    test("maps table references and pvar-backed observables to public contract shapes", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.tables = [
+            {
+                name: "SharedState",
+                description: "Consumer-facing state",
+                primaryKeyName: "stateId",
+                fields: [
+                    { name: "stateId", type: field_type_1.FieldType.id },
+                    { name: "count", type: field_type_1.FieldType.number },
+                ],
+            },
+        ];
+        artifact.manifest.provides[0].tables = [{ name: "SharedState" }];
+        artifact.manifest.provides[0].observables = [
+            {
+                name: "sharedCount",
+                description: "Consumer-facing count",
+                valueType: field_type_1.FieldType.number,
+                writable: true,
+                persistentVar: {
+                    scope: "device",
+                    name: "sharedCount",
+                    defaultValue: 0,
+                },
+            },
+        ];
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        const definition = (0, isolated_artifact_1.isolatedContractToDefinition)(manifest.provides[0], manifest.tables ?? []);
+        expect(definition.tables).toEqual([
+            {
+                name: "SharedState",
+                description: "Consumer-facing state",
+                primaryKeyName: "stateId",
+                fields: [
+                    { name: "stateId", type: field_type_1.FieldType.id },
+                    { name: "count", type: field_type_1.FieldType.number },
+                ],
+            },
+        ]);
+        expect(definition.observables).toEqual([
+            {
+                name: "sharedCount",
+                description: "Consumer-facing count",
+                valueType: field_type_1.FieldType.number,
+                writable: true,
+            },
+        ]);
+    });
+    test("rejects malformed isolated tables", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                primaryKeyName: "stateId",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.id }],
+                tableId: (0, utils_1.newid)(),
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/must not declare tableId/);
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                primaryKeyName: "stateId",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.id }],
+                physicalName: "SystemTable",
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/physicalName/);
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                primaryKeyName: "missing",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.id }],
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/primaryKeyName/);
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                primaryKeyName: "stateId",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.string }],
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/type id/);
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                primaryKeyName: "stateId",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.id }],
+            },
+        ];
+        artifact.manifest.provides[0].tables = [
+            {
+                name: "State",
+                primaryKeyName: "stateId",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.id }],
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/only a package table name/);
+    });
+    test("requires table names to be unique inside the package", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.tables = [
+            {
+                name: "State",
+                primaryKeyName: "stateId",
+                fields: [{ name: "stateId", type: field_type_1.FieldType.id }],
+            },
+            {
+                name: "State",
+                primaryKeyName: "otherStateId",
+                fields: [{ name: "otherStateId", type: field_type_1.FieldType.id }],
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/duplicate table "State"/);
+    });
+    test("rejects a recognized but malformed envelope", () => {
+        expect(() => (0, isolated_artifact_1.parseIsolatedPackageArtifact)(`${isolated_artifact_1.ISOLATED_PACKAGE_MAGIC}\n{not-json`)).toThrow(/JSON is invalid/);
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({
+            manifest: {
+                packageId: "not-an-id",
+                version: "1.0.0",
+                provides: [],
+                consumes: [],
+            },
+            providerSource: "x",
+        })).toThrow(/peer id|provide at least one/i);
+    });
+    test("defaults missing tool field arrays", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].tools[0] = {
+            name: "greet",
+            usageDescription: "Say hello",
+        };
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect(manifest.provides[0].tools[0].inputFields).toEqual([]);
+        expect(manifest.provides[0].tools[0].outputFields).toEqual([]);
+        expect(manifest.provides[0].tables).toEqual([]);
+        expect(manifest.provides[0].observables).toEqual([]);
+        expect(manifest.provides[0].alsoImplements).toEqual([]);
+    });
+    test("validates and preserves alsoImplements declarations", () => {
+        const { artifact } = makeArtifact();
+        const targetContractId = (0, utils_1.newid)();
+        artifact.manifest.provides[0].alsoImplements = [
+            { contractId: targetContractId, version: 1 },
+            { contractId: targetContractId, version: { from: 2, to: 4 } },
+        ];
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect(manifest.provides[0].alsoImplements).toEqual([
+            { contractId: targetContractId, version: 1 },
+            { contractId: targetContractId, version: { from: 2, to: 4 } },
+        ]);
+    });
+    test("rejects unsupported contract features instead of dropping them", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].events = [
+            { name: "changed", payloadFields: [] },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/events is not supported/);
+    });
+    test("rejects missing public table references and malformed observable bindings", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].tables = [{ name: "Missing" }];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/undeclared package table/);
+        artifact.manifest.provides[0].tables = [];
+        artifact.manifest.provides[0].observables = [
+            {
+                name: "sharedCount",
+                description: "Shared count",
+                valueType: field_type_1.FieldType.number,
+                writable: true,
+                persistentVar: {
+                    scope: "device",
+                    name: "sharedCount",
+                    defaultValue: "zero",
+                },
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/must match.*number/);
+        artifact.manifest.provides[0].observables[0].valueType = field_type_1.FieldType.object;
+        artifact.manifest.provides[0].observables[0].persistentVar.defaultValue = {
+            callback: () => undefined,
+        };
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/JSON-compatible/);
+    });
+});

package/dist/package-loader/isolated-persistent-var-gateway.d.ts

@@ -0,0 +1,20 @@
+import type { DataContext } from "../context/data-context";
+import type { IIsolatedPackagePersistentVarGateway } from "./isolated-runtime";
+/**
+ * In-memory package-prefixed pvar gateway for isolated runtime tests.
+ *
+ * Values survive repeated access through the same gateway and are copied on
+ * both read and write.
+ */
+export declare function createMemoryIsolatedPackagePersistentVarGateway(): IIsolatedPackagePersistentVarGateway;
+/**
+ * Create a host-owned pvar gateway for one trusted data-context route.
+ *
+ * This is a thin async adapter over the canonical Peers pvar constructors.
+ * Every logical name is prefixed with trusted package identity before the
+ * canonical constructor derives its deterministic storage identity.
+ *
+ * @param dataContext - Authorized personal or group context for this runtime.
+ * @returns A package-scoped gateway whose reads and writes await pvar persistence.
+ */
+export declare function createIsolatedPackagePersistentVarGateway(dataContext: DataContext): IIsolatedPackagePersistentVarGateway;

package/dist/package-loader/isolated-persistent-var-gateway.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMemoryIsolatedPackagePersistentVarGateway = createMemoryIsolatedPackagePersistentVarGateway;
+exports.createIsolatedPackagePersistentVarGateway = createIsolatedPackagePersistentVarGateway;
+const persistent_var_identity_1 = require("../data/persistent-var-identity");
+const isolated_value_1 = require("./isolated-value");
+function memoryKey(ref) {
+    return `${ref.packageId}:${ref.scope}:${ref.name}`;
+}
+async function resolvePersistentVar(dataContext, ref) {
+    const { deviceVar, groupDeviceVar, groupUserVar, groupVar, userVar } = await Promise.resolve().then(() => require("../data/persistent-vars"));
+    const name = (0, persistent_var_identity_1.packageScopedPersistentVarName)(ref.packageId, ref.name);
+    const userContext = dataContext.userContext;
+    switch (ref.scope) {
+        case "device":
+            return deviceVar(name, { userContext });
+        case "user":
+            return userVar(name, { userContext });
+        case "group":
+            return groupVar(name, { dataContext, userContext });
+        case "groupDevice":
+            return groupDeviceVar(name, { dataContext, userContext });
+        case "groupUser":
+            return groupUserVar(name, { dataContext, userContext });
+    }
+}
+/**
+ * In-memory package-prefixed pvar gateway for isolated runtime tests.
+ *
+ * Values survive repeated access through the same gateway and are copied on
+ * both read and write.
+ */
+function createMemoryIsolatedPackagePersistentVarGateway() {
+    const values = new Map();
+    const subscribers = new Map();
+    return {
+        async get(ref) {
+            const value = values.get(memoryKey(ref));
+            return value === undefined ? undefined : (0, isolated_value_1.copyIsolatedValue)(value);
+        },
+        async set(ref, value) {
+            if (value === undefined) {
+                throw new Error("Persistent variable value must be copyable");
+            }
+            const copy = (0, isolated_value_1.copyIsolatedValue)(value);
+            const key = memoryKey(ref);
+            values.set(key, copy);
+            for (const handler of subscribers.get(key) ?? []) {
+                handler((0, isolated_value_1.copyIsolatedValue)(copy));
+            }
+            return (0, isolated_value_1.copyIsolatedValue)(copy);
+        },
+        async subscribe(ref, handler) {
+            const key = memoryKey(ref);
+            const handlers = subscribers.get(key) ?? new Set();
+            handlers.add(handler);
+            subscribers.set(key, handlers);
+            return () => {
+                handlers.delete(handler);
+                if (handlers.size === 0) {
+                    subscribers.delete(key);
+                }
+            };
+        },
+    };
+}
+/**
+ * Create a host-owned pvar gateway for one trusted data-context route.
+ *
+ * This is a thin async adapter over the canonical Peers pvar constructors.
+ * Every logical name is prefixed with trusted package identity before the
+ * canonical constructor derives its deterministic storage identity.
+ *
+ * @param dataContext - Authorized personal or group context for this runtime.
+ * @returns A package-scoped gateway whose reads and writes await pvar persistence.
+ */
+function createIsolatedPackagePersistentVarGateway(dataContext) {
+    return {
+        async get(ref) {
+            const persistentVar = await resolvePersistentVar(dataContext, ref);
+            await persistentVar.loadingPromise;
+            const value = persistentVar();
+            return value === undefined ? undefined : (0, isolated_value_1.copyIsolatedValue)(value);
+        },
+        async set(ref, value) {
+            if (value === undefined) {
+                throw new Error("Persistent variable value must be copyable");
+            }
+            const persistentVar = await resolvePersistentVar(dataContext, ref);
+            const copy = (0, isolated_value_1.copyIsolatedValue)(value);
+            await persistentVar.loadingPromise;
+            persistentVar(copy);
+            await persistentVar.loadingPromise;
+            const saved = persistentVar();
+            return saved === undefined ? undefined : (0, isolated_value_1.copyIsolatedValue)(saved);
+        },
+        async subscribe(ref, handler) {
+            const persistentVar = await resolvePersistentVar(dataContext, ref);
+            await persistentVar.loadingPromise;
+            const subscription = persistentVar.subscribe((value) => {
+                handler((0, isolated_value_1.copyIsolatedValue)(value));
+            });
+            return () => subscription.dispose();
+        },
+    };
+}

package/dist/package-loader/isolated-persistent-var-gateway.test.d.ts

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

package/dist/package-loader/isolated-persistent-var-gateway.test.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+const isolated_persistent_var_gateway_1 = require("./isolated-persistent-var-gateway");
+describe("isolated package persistent variable gateway", () => {
+    test("separates the same logical name by trusted package and scope", async () => {
+        const gateway = (0, isolated_persistent_var_gateway_1.createMemoryIsolatedPackagePersistentVarGateway)();
+        const packageA = { packageId: (0, utils_1.newid)(), scope: "device", name: "settings" };
+        const packageB = { packageId: (0, utils_1.newid)(), scope: "device", name: "settings" };
+        const packageAUser = { ...packageA, scope: "user" };
+        await gateway.set(packageA, { count: 1 });
+        await gateway.set(packageB, { count: 2 });
+        await gateway.set(packageAUser, { count: 3 });
+        await expect(gateway.get(packageA)).resolves.toEqual({ count: 1 });
+        await expect(gateway.get(packageB)).resolves.toEqual({ count: 2 });
+        await expect(gateway.get(packageAUser)).resolves.toEqual({ count: 3 });
+    });
+    test("copies supported values and rejects unsafe writes", async () => {
+        const gateway = (0, isolated_persistent_var_gateway_1.createMemoryIsolatedPackagePersistentVarGateway)();
+        const ref = { packageId: (0, utils_1.newid)(), scope: "group", name: "state" };
+        const input = {
+            nested: { count: 1 },
+            savedAt: new Date("2026-08-24T12:00:00.000Z"),
+            bytes: new Uint8Array([1, 2, 3]),
+        };
+        await gateway.set(ref, input);
+        input.nested.count = 9;
+        const stored = (await gateway.get(ref));
+        expect(stored).toEqual({
+            nested: { count: 1 },
+            savedAt: new Date("2026-08-24T12:00:00.000Z"),
+            bytes: new Uint8Array([1, 2, 3]),
+        });
+        stored.nested.count = 7;
+        await expect(gateway.get(ref)).resolves.toEqual({
+            nested: { count: 1 },
+            savedAt: new Date("2026-08-24T12:00:00.000Z"),
+            bytes: new Uint8Array([1, 2, 3]),
+        });
+        await expect(gateway.set(ref, undefined)).rejects.toThrow(/copyable/);
+        await expect(gateway.set(ref, { callback: () => undefined })).rejects.toThrow(/unsupported/);
+        await expect(gateway.set(ref, Number.POSITIVE_INFINITY)).rejects.toThrow(/finite/);
+    });
+    test("streams detached values until the host subscription is removed", async () => {
+        const gateway = (0, isolated_persistent_var_gateway_1.createMemoryIsolatedPackagePersistentVarGateway)();
+        const ref = { packageId: (0, utils_1.newid)(), scope: "group", name: "shared" };
+        const received = [];
+        const unsubscribe = await gateway.subscribe(ref, (value) => received.push(value));
+        const value = { count: 1 };
+        await gateway.set(ref, value);
+        value.count = 2;
+        unsubscribe();
+        await gateway.set(ref, { count: 3 });
+        expect(received).toEqual([{ count: 1 }]);
+    });
+});