@peers-app/peers-sdk 0.21.1 → 0.21.2

package/dist/contracts/system-contracts.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSystemContract = registerSystemContract;
+exports.installSystemContracts = installSystemContracts;
+exports.listSystemContracts = listSystemContracts;
+exports._clearSystemContractsForTests = _clearSystemContractsForTests;
+const systemContracts = [];
+function systemContractKey(contractId, version) {
+    return `${contractId}@${version}`;
+}
+/**
+ * Self-register a built-in system contract.
+ *
+ * Call once from the contract module (side effect at import). Later
+ * {@link installSystemContracts} installs every registered entry into a
+ * concrete registry. New system contracts only need this one call.
+ */
+function registerSystemContract(registration) {
+    if (registration.resolve) {
+        if (!registration.contractId || registration.version == null) {
+            throw new Error("registerSystemContract: contractId and version are required when resolve is provided");
+        }
+        // Defer resolver registration so self-registration during SDK barrel / package-loader
+        // import cannot re-enter contract-resolvers mid-initialization.
+        const { contractId, version, resolve } = registration;
+        queueMicrotask(() => {
+            const { registerContractResolver } = require("./contract-resolvers");
+            registerContractResolver(contractId, version, resolve);
+        });
+    }
+    const key = registration.contractId && registration.version != null
+        ? systemContractKey(registration.contractId, registration.version)
+        : undefined;
+    if (key) {
+        const existingIdx = systemContracts.findIndex((entry) => entry.contractId &&
+            entry.version != null &&
+            systemContractKey(entry.contractId, entry.version) === key);
+        if (existingIdx >= 0) {
+            systemContracts[existingIdx] = registration;
+            return;
+        }
+    }
+    systemContracts.push(registration);
+}
+/**
+ * Register every known system contract into `registry` as a provider.
+ * Safe to call more than once for the same registry (provider updates in place).
+ */
+function installSystemContracts(registry) {
+    for (const entry of systemContracts) {
+        const definition = entry.getDefinition();
+        const result = registry.register(entry.providerPackageId, definition);
+        if (!result.valid) {
+            console.error(`[SystemContracts] Failed to register ${definition.name} (${definition.contractId}@${definition.version}):`, result.errors);
+        }
+    }
+}
+/** Snapshot of registered system contracts (for tests and diagnostics). */
+function listSystemContracts() {
+    return systemContracts;
+}
+/**
+ * Clear the system-contract catalog. Test-only — production code must not call this.
+ *
+ * @internal
+ */
+function _clearSystemContractsForTests() {
+    systemContracts.length = 0;
+}

package/dist/contracts/types.d.ts

@@ -4,6 +4,7 @@ import type { IToolInstance } from "../data/tools";
 import type { Event } from "../events";
 import type { Observable } from "../observable";
 import type { FieldType, IField } from "../types/field-type";
+import type { IContractConsumer, IContractConsumerBase } from "./contract-proxy";
 /**
  * A versioned interface definition declaring the shape of tables, tools,
  * observables, and events that a package provides. Pure data — no executable code.
@@ -58,6 +59,43 @@ export interface IContractEvent {
     /** Shape of the payload delivered to subscribers when the event fires. */
     payloadFields: IField[];
 }
+/**
+ * Options for {@link PackageBuilder.consumes}.
+ *
+ * Provider selection (`providerPackageIds`, `fallbackToDefaultProvider`) is
+ * recorded here for the package-loader; wiring that resolves the deferred
+ * handle is a follow-up step.
+ */
+export interface IConsumedContractOptions {
+    /**
+     * When true, a missing provider settles the handle with `undefined` instead
+     * of rejecting. Defaults to false (required).
+     */
+    optional?: boolean;
+    /**
+     * Ordered preference of provider package IDs. The loader tries these in
+     * order before considering the active/default provider.
+     */
+    providerPackageIds?: string[];
+    /**
+     * When true and none of {@link providerPackageIds} is available, fall back
+     * to the active/default provider for the contract. Ignored when
+     * `providerPackageIds` is omitted (default provider is used directly).
+     */
+    fallbackToDefaultProvider?: boolean;
+}
+/**
+ * Deferred handle returned by {@link PackageBuilder.consumes}.
+ *
+ * The handle itself is not thenable — await {@link consumer} from runtime
+ * code after `definePackage` finishes, not inside the define callback.
+ * Settlement is owned by the SDK (package-loader); package code cannot
+ * resolve or reject the promise.
+ */
+export interface IConsumedContractHandle<T extends IContractConsumerBase | undefined = IContractConsumer> {
+    /** Resolves to the live consumer proxy, or `undefined` when optional and unmatched. */
+    readonly consumer: Promise<T>;
+}
 /**
  * A reference to a contract that a package wants to consume.
  * Recorded during `definePackage` and checked at install time.
@@ -66,6 +104,12 @@ export interface IConsumedContract {
     contractId: string;
     version: number;
     optional?: boolean;
+    /** Ordered preferred provider package IDs, if any. */
+    providerPackageIds?: string[];
+    /** Whether to fall back to the default provider when preferred ones are missing. */
+    fallbackToDefaultProvider?: boolean;
+    /** Deferred handle returned by `consumes()` for this dependency. */
+    handle?: IConsumedContractHandle<IContractConsumerBase | undefined>;
 }
 /**
  * Declares that the owning contract's implementation also satisfies another

package/dist/package-loader/contract-package-loader.test.d.ts

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

package/dist/package-loader/contract-package-loader.test.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+jest.mock("../data/tools", () => ({
+    Tools: () => ({
+        save: jest.fn().mockResolvedValue(undefined),
+    }),
+}));
+jest.mock("../tools", () => ({
+    registerTool: jest.fn(),
+}));
+jest.mock("../data/assistants", () => ({
+    Assistants: () => ({
+        save: jest.fn().mockResolvedValue(undefined),
+    }),
+}));
+const registry_1 = require("../contracts/registry");
+const utils_1 = require("../utils");
+const contract_package_loader_1 = require("./contract-package-loader");
+describe("installContractPackage registry wiring", () => {
+    const packageId = (0, utils_1.newid)();
+    const contractId = (0, utils_1.newid)();
+    function makeDefinition(overrides = {}) {
+        return {
+            packageId,
+            version: "1.0.0",
+            contracts: [
+                {
+                    contractId,
+                    version: 1,
+                    devTag: "dev",
+                    name: "Test Contract",
+                    description: "For registry install tests",
+                    tables: [],
+                    tools: [],
+                    observables: [],
+                    events: [],
+                },
+            ],
+            consumes: [],
+            alsoImplements: new Map(),
+            assistants: [],
+            appNavs: [],
+            toolInstances: [],
+            tableDefinitions: [],
+            ...overrides,
+        };
+    }
+    function mockDataContext() {
+        return {
+            dataContextId: "test-ctx",
+            tableContainer: {
+                registerTableDefinition: jest.fn(),
+            },
+        };
+    }
+    it("registers contract providers into the provided ContractRegistry", async () => {
+        const registry = new registry_1.ContractRegistry();
+        const dataContext = mockDataContext();
+        const definition = makeDefinition();
+        await (0, contract_package_loader_1.installContractPackage)(dataContext, definition, { registry });
+        expect(registry.resolve(contractId, 1)?.name).toBe("Test Contract");
+        expect(registry.getProviderPackageId(contractId, 1)).toBe(packageId);
+        expect(registry.getContractKeysForPackage(packageId)).toEqual([`${contractId}@1`]);
+    });
+    it("does not register providers when no registry is provided", async () => {
+        const dataContext = mockDataContext();
+        await expect((0, contract_package_loader_1.installContractPackage)(dataContext, makeDefinition())).resolves.toBeUndefined();
+    });
+});
+describe("extractPackageDefinition", () => {
+    it("returns a package definition when packageId and contracts are present", () => {
+        const packageId = (0, utils_1.newid)();
+        const def = {
+            packageId,
+            contracts: [],
+            consumes: [],
+            alsoImplements: new Map(),
+            assistants: [],
+            appNavs: [],
+            toolInstances: [],
+            tableDefinitions: [],
+        };
+        expect((0, contract_package_loader_1.extractPackageDefinition)({ packageDefinition: def })).toBe(def);
+    });
+    it("returns undefined when packageDefinition is missing", () => {
+        expect((0, contract_package_loader_1.extractPackageDefinition)({})).toBeUndefined();
+    });
+});

package/dist/package-loader/package-loader.d.ts

@@ -1,6 +1,8 @@
 import type { DataContext } from "../context/data-context";
+import { ContractRegistry } from "../contracts/registry";
 import { type IPackage } from "../data/packages";
 import type { IPeersPackage } from "../types/peers-package";
+import "../contracts/system";
 export declare class PackageLoader {
     readonly dataContext: DataContext;
     static PeersSDK: any;
@@ -8,6 +10,12 @@ export declare class PackageLoader {
     private packageInstances;
     /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
     private contractInstalledPackages;
+    /**
+     * In-memory contract providers for this data context. Seeded with system
+     * contracts at construction; package providers are added via
+     * {@link installContractPackage}.
+     */
+    readonly contractRegistry: ContractRegistry;
     require: (<T>(module: string) => T) | undefined;
     constructor(dataContext: DataContext);
     /** Returns true if a package was installed via the contract-based definePackage() path. */

package/dist/package-loader/package-loader.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageLoader = void 0;
 exports.setDefaultRequire = setDefaultRequire;
+const registry_1 = require("../contracts/registry");
+const system_contracts_1 = require("../contracts/system-contracts");
 const files_1 = require("../data/files");
 const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
@@ -9,6 +11,9 @@ const packages_1 = require("../data/packages");
 const tools_1 = require("../data/tools");
 const tools_2 = require("../tools");
 const contract_package_loader_1 = require("./contract-package-loader");
+const resolve_consumed_contracts_1 = require("./resolve-consumed-contracts");
+// Ensure built-in system contracts are cataloged before any PackageLoader installs them.
+require("../contracts/system");
 class PackageLoader {
     dataContext;
     static PeersSDK;
@@ -16,9 +21,17 @@ class PackageLoader {
     packageInstances = {};
     /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
     contractInstalledPackages = new Set();
+    /**
+     * In-memory contract providers for this data context. Seeded with system
+     * contracts at construction; package providers are added via
+     * {@link installContractPackage}.
+     */
+    contractRegistry;
     require = undefined;
     constructor(dataContext) {
         this.dataContext = dataContext;
+        this.contractRegistry = new registry_1.ContractRegistry();
+        (0, system_contracts_1.installSystemContracts)(this.contractRegistry);
     }
     /** Returns true if a package was installed via the contract-based definePackage() path. */
     isContractInstalled(packageId) {
@@ -208,7 +221,10 @@ class PackageLoader {
                 if (packageDefinition.packageId !== pkg.packageId) {
                     console.warn(`[PackageLoader] packageId mismatch: definition has "${packageDefinition.packageId}" but DB record has "${pkg.packageId}"`);
                 }
-                await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition);
+                await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition, {
+                    registry: this.contractRegistry,
+                });
+                await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(this.dataContext, this.contractRegistry, packageDefinition);
                 this.contractInstalledPackages.add(packageDefinition.packageId);
                 this.correctPackageVersion(pkg, packageDefinition);
                 // Build a proper IPeersPackage from the contract definition so callers

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

@@ -10,6 +10,8 @@ jest.mock("../data/package-versions", () => ({
     }),
     computePackageVersionHash: (version, versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash) => mockComputePackageVersionHash(version, versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash),
 }));
+const registry_1 = require("../contracts/registry");
+const system_ids_1 = require("../system-ids");
 const package_loader_1 = require("./package-loader");
 describe("PackageLoader.correctPackageVersion", () => {
     const activePvId = "pv-active";
@@ -79,3 +81,18 @@ describe("PackageLoader.correctPackageVersion", () => {
         expect(mockSignAndSave).not.toHaveBeenCalled();
     });
 });
+describe("PackageLoader.contractRegistry", () => {
+    it("owns an in-memory ContractRegistry per loader instance", () => {
+        const loaderA = new package_loader_1.PackageLoader({ dataContextId: "ctx-a" });
+        const loaderB = new package_loader_1.PackageLoader({ dataContextId: "ctx-b" });
+        expect(loaderA.contractRegistry).toBeInstanceOf(registry_1.ContractRegistry);
+        expect(loaderB.contractRegistry).toBeInstanceOf(registry_1.ContractRegistry);
+        expect(loaderA.contractRegistry).not.toBe(loaderB.contractRegistry);
+    });
+    it("installs system contracts into each new registry", () => {
+        const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-system" });
+        expect(loader.contractRegistry.getProviderPackageId(system_ids_1.logsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+        expect(loader.contractRegistry.resolve(system_ids_1.logsContractId, 1)?.name).toBe("System Logs");
+        expect(loader.contractRegistry.getProviderPackageId(system_ids_1.deviceOperationsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+    });
+});

package/dist/package-loader/resolve-consumed-contracts.d.ts

@@ -0,0 +1,13 @@
+import type { DataContext } from "../context/data-context";
+import type { ContractRegistry } from "../contracts/registry";
+import type { IPackageDefinitionResult } from "../contracts/types";
+/**
+ * Settle each deferred `consumes` handle on a package definition after its
+ * providers have been registered.
+ *
+ * A consume succeeds only when {@link ContractRegistry.selectProvider} finds a
+ * matching provider **and** a live {@link getContractResolver|ContractResolver}
+ * exists for that contract version. Missing optional deps settle to `undefined`;
+ * missing required deps reject the handle.
+ */
+export declare function resolveConsumedContracts(dataContext: DataContext, registry: ContractRegistry, packageDefinition: IPackageDefinitionResult): Promise<void>;

package/dist/package-loader/resolve-consumed-contracts.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConsumedContracts = resolveConsumedContracts;
+const builder_1 = require("../contracts/builder");
+const contract_resolvers_1 = require("../contracts/contract-resolvers");
+const create_local_consumer_1 = require("../contracts/create-local-consumer");
+/**
+ * Settle each deferred `consumes` handle on a package definition after its
+ * providers have been registered.
+ *
+ * A consume succeeds only when {@link ContractRegistry.selectProvider} finds a
+ * matching provider **and** a live {@link getContractResolver|ContractResolver}
+ * exists for that contract version. Missing optional deps settle to `undefined`;
+ * missing required deps reject the handle.
+ */
+async function resolveConsumedContracts(dataContext, registry, packageDefinition) {
+    for (const dep of packageDefinition.consumes) {
+        const handle = dep.handle;
+        if (!handle) {
+            continue;
+        }
+        try {
+            const selected = registry.selectProvider(dep);
+            if (!selected) {
+                settleMissing(dep.optional === true, handle, dep.contractId, dep.version, "no matching provider");
+                continue;
+            }
+            const resolver = (0, contract_resolvers_1.getContractResolver)(dep.contractId, dep.version);
+            if (!resolver) {
+                settleMissing(dep.optional === true, handle, dep.contractId, dep.version, `provider ${selected.providerPackageId} has no live resolver`);
+                continue;
+            }
+            const resolution = await resolver({ dataContext });
+            const consumer = (0, create_local_consumer_1.createLocalContractConsumer)(selected.definition, resolution, {
+                dataContextId: dataContext.dataContextId,
+            });
+            (0, builder_1.settleConsumedContractHandle)(handle, consumer);
+        }
+        catch (err) {
+            if (dep.optional === true) {
+                (0, builder_1.settleConsumedContractHandle)(handle, undefined);
+            }
+            else {
+                (0, builder_1.rejectConsumedContractHandle)(handle, err);
+            }
+        }
+    }
+}
+function settleMissing(optional, handle, contractId, version, reason) {
+    if (optional) {
+        (0, builder_1.settleConsumedContractHandle)(handle, undefined);
+        return;
+    }
+    (0, builder_1.rejectConsumedContractHandle)(handle, new Error(`Required contract ${contractId}@${version} could not be resolved: ${reason}`));
+}

package/dist/package-loader/resolve-consumed-contracts.test.d.ts

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

package/dist/package-loader/resolve-consumed-contracts.test.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const builder_1 = require("../contracts/builder");
+const contract_resolvers_1 = require("../contracts/contract-resolvers");
+const registry_1 = require("../contracts/registry");
+const utils_1 = require("../utils");
+const resolve_consumed_contracts_1 = require("./resolve-consumed-contracts");
+describe("resolveConsumedContracts", () => {
+    const contractId = (0, utils_1.newid)();
+    const providerPackageId = (0, utils_1.newid)();
+    function mockDataContext() {
+        return { dataContextId: "test-ctx" };
+    }
+    function makeProvidingRegistry() {
+        const registry = new registry_1.ContractRegistry();
+        registry.register(providerPackageId, {
+            contractId,
+            version: 1,
+            devTag: "dev",
+            name: "Fake Contract",
+            description: "test",
+            tables: [
+                {
+                    name: "Items",
+                    description: "Items table",
+                    primaryKeyName: "itemId",
+                    fields: [],
+                },
+            ],
+            tools: [],
+            observables: [],
+            events: [],
+        });
+        return registry;
+    }
+    beforeEach(() => {
+        const resolution = {
+            contractId,
+            version: 1,
+            tables: {
+                Items: {
+                    list: jest.fn().mockResolvedValue([{ itemId: "1" }]),
+                    count: jest.fn().mockResolvedValue(1),
+                },
+            },
+        };
+        (0, contract_resolvers_1.registerContractResolver)(contractId, 1, () => resolution);
+    });
+    it("settles a required consume with a live local consumer proxy", async () => {
+        const registry = makeProvidingRegistry();
+        let consumeHandle;
+        const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = (0, utils_1.newid)();
+            pkg.version = "1.0.0";
+            consumeHandle = pkg.consumes(contractId, 1);
+        });
+        await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(mockDataContext(), registry, packageDefinition);
+        if (!consumeHandle) {
+            throw new Error("expected consume handle");
+        }
+        const consumer = (await consumeHandle.consumer);
+        expect(consumer).toBeDefined();
+        expect(consumer?.contractId).toBe(contractId);
+        expect(consumer?.version).toBe(1);
+        await expect(consumer?.tables.Items.list()).resolves.toEqual([{ itemId: "1" }]);
+        await expect(consumer?.tables.Items.count()).resolves.toBe(1);
+    });
+    it("settles optional missing consumes to undefined", async () => {
+        const registry = new registry_1.ContractRegistry();
+        let consumeHandle;
+        const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = (0, utils_1.newid)();
+            pkg.version = "1.0.0";
+            consumeHandle = pkg.consumes(contractId, 1, { optional: true });
+        });
+        await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(mockDataContext(), registry, packageDefinition);
+        if (!consumeHandle) {
+            throw new Error("expected consume handle");
+        }
+        await expect(consumeHandle.consumer).resolves.toBeUndefined();
+    });
+    it("rejects required consumes when no provider is available", async () => {
+        const registry = new registry_1.ContractRegistry();
+        let consumeHandle;
+        const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = (0, utils_1.newid)();
+            pkg.version = "1.0.0";
+            consumeHandle = pkg.consumes(contractId, 1);
+        });
+        await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(mockDataContext(), registry, packageDefinition);
+        if (!consumeHandle) {
+            throw new Error("expected consume handle");
+        }
+        await expect(consumeHandle.consumer).rejects.toThrow(/could not be resolved/);
+    });
+    it("treats a registered provider without a live resolver as missing", async () => {
+        const noResolverContractId = (0, utils_1.newid)();
+        const registry = new registry_1.ContractRegistry();
+        registry.register(providerPackageId, {
+            contractId: noResolverContractId,
+            version: 1,
+            devTag: "dev",
+            name: "No Resolver",
+            description: "test",
+            tables: [],
+            tools: [],
+            observables: [],
+            events: [],
+        });
+        expect((0, contract_resolvers_1.getContractResolver)(noResolverContractId, 1)).toBeUndefined();
+        let consumeHandle;
+        const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = (0, utils_1.newid)();
+            pkg.version = "1.0.0";
+            consumeHandle = pkg.consumes(noResolverContractId, 1, { optional: true });
+        });
+        await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(mockDataContext(), registry, packageDefinition);
+        if (!consumeHandle) {
+            throw new Error("expected consume handle");
+        }
+        await expect(consumeHandle.consumer).resolves.toBeUndefined();
+    });
+});

package/package.json

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