@peers-app/peers-sdk 0.16.5 → 0.17.0

package/dist/contracts/__tests__/builder.test.d.ts

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

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

@@ -0,0 +1,426 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const types_1 = require("../../data/orm/types");
+const field_type_1 = require("../../types/field-type");
+const utils_1 = require("../../utils");
+const builder_1 = require("../builder");
+const extract_1 = require("../extract");
+const types_2 = require("../types");
+beforeAll(() => {
+    (0, extract_1.setSchemaToFieldsFn)(types_1.schemaToFields);
+});
+const TEST_PKG_ID = (0, utils_1.newid)();
+const TASKS_ID = (0, utils_1.newid)();
+const NOTES_ID = (0, utils_1.newid)();
+const AUTH_ID = (0, utils_1.newid)();
+const PROJECTS_ID = (0, utils_1.newid)();
+const FANCY_TASKS_ID = (0, utils_1.newid)();
+const GENERIC_ID = (0, utils_1.newid)();
+describe("definePackage", () => {
+    it("produces a contract definition from a single contract with tables and tools", () => {
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const tasks = pkg.contract(TASKS_ID, 1, "Tasks");
+            tasks.tables = [
+                {
+                    metaData: {
+                        name: "Tasks",
+                        description: "Task tracking",
+                        primaryKeyName: "taskId",
+                        fields: [],
+                    },
+                    schema: zod_1.z.object({
+                        taskId: zod_1.z.string().describe("PK"),
+                        title: zod_1.z.string().describe("Title"),
+                    }),
+                },
+            ];
+            tasks.tools = [
+                {
+                    tool: {
+                        name: "create-task",
+                        usageDescription: "Creates a task",
+                        inputSchema: {
+                            fields: [{ name: "title", type: field_type_1.FieldType.string, description: "Title" }],
+                        },
+                        outputSchema: {
+                            fields: [{ name: "taskId", type: field_type_1.FieldType.id, description: "ID" }],
+                        },
+                    },
+                },
+            ];
+        });
+        expect(result.contracts).toHaveLength(1);
+        const contract = result.contracts[0];
+        expect(contract.contractId).toBe(TASKS_ID);
+        expect(contract.version).toBe(1);
+        expect(contract.name).toBe("Tasks");
+        expect(contract.description).toBe("");
+        expect(contract.devTag).toBeUndefined();
+        expect(contract.tables).toHaveLength(1);
+        expect(contract.tables[0].name).toBe("Tasks");
+        expect(contract.tables[0].fields).toHaveLength(2);
+        expect(contract.tools).toHaveLength(1);
+        expect(contract.tools[0].name).toBe("create-task");
+        expect(contract.tools[0].inputFields).toHaveLength(1);
+        expect(contract.tools[0].outputFields).toHaveLength(1);
+    });
+    it("supports multiple contracts from one package", () => {
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const tasks = pkg.contract(TASKS_ID, 1, "Tasks");
+            tasks.tables = [
+                {
+                    metaData: {
+                        name: "Tasks",
+                        description: "d",
+                        primaryKeyName: "taskId",
+                        fields: [{ name: "taskId", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+            const notes = pkg.contract(NOTES_ID, 1, "Notes");
+            notes.tables = [
+                {
+                    metaData: {
+                        name: "Notes",
+                        description: "d",
+                        primaryKeyName: "noteId",
+                        fields: [{ name: "noteId", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        expect(result.contracts).toHaveLength(2);
+        expect(result.contracts[0].contractId).toBe(TASKS_ID);
+        expect(result.contracts[1].contractId).toBe(NOTES_ID);
+    });
+    it("records consumed contracts", () => {
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.consumes(TASKS_ID, 1);
+            pkg.consumes(AUTH_ID, 2);
+            const projects = pkg.contract(PROJECTS_ID, 1, "Projects");
+            projects.tables = [
+                {
+                    metaData: {
+                        name: "Projects",
+                        description: "d",
+                        primaryKeyName: "projectId",
+                        fields: [{ name: "projectId", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        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 });
+    });
+    it("records alsoImplements declarations", () => {
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const fancy = pkg.contract(FANCY_TASKS_ID, 1, "Fancy Tasks");
+            fancy.alsoImplements(TASKS_ID, 1);
+            fancy.alsoImplements(TASKS_ID, { from: 1, to: 3 });
+            fancy.tables = [
+                {
+                    metaData: {
+                        name: "Tasks",
+                        description: "d",
+                        primaryKeyName: "taskId",
+                        fields: [{ name: "taskId", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        const key = (0, types_2.contractKey)(FANCY_TASKS_ID, 1);
+        expect(result.alsoImplements.has(key)).toBe(true);
+        const decls = result.alsoImplements.get(key) ?? [];
+        expect(decls).toHaveLength(2);
+        expect(decls[0]).toEqual({ contractId: TASKS_ID, version: 1 });
+        expect(decls[1]).toEqual({ contractId: TASKS_ID, version: { from: 1, to: 3 } });
+    });
+    it("includes package-level assistants and appNavs", () => {
+        const assistant = { id: "asst1", name: "Task Bot" };
+        const nav = { name: "Tasks", iconClassName: "bi bi-list-task", navigationPath: "app" };
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.assistants = [assistant];
+            pkg.appNavs = [nav];
+            const c = pkg.contract(GENERIC_ID, 1, "Generic");
+            c.tables = [
+                {
+                    metaData: {
+                        name: "T",
+                        description: "d",
+                        primaryKeyName: "id",
+                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        expect(result.assistants).toEqual([assistant]);
+        expect(result.appNavs).toEqual([nav]);
+    });
+    it("supports devTag on contracts", () => {
+        const devContractId = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const c = pkg.contract(devContractId, 1, "Dev Contract", "dev");
+            c.tables = [
+                {
+                    metaData: {
+                        name: "T",
+                        description: "d",
+                        primaryKeyName: "id",
+                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        expect(result.contracts[0].devTag).toBe("dev");
+    });
+    it("supports observables on contracts", () => {
+        const obsContractId = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const c = pkg.contract(obsContractId, 1, "Observable Contract");
+            c.tables = [
+                {
+                    metaData: {
+                        name: "T",
+                        description: "d",
+                        primaryKeyName: "id",
+                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+            c.observables = [
+                {
+                    name: "taskCount",
+                    description: "Count of tasks",
+                    valueType: field_type_1.FieldType.number,
+                    writable: false,
+                },
+            ];
+        });
+        expect(result.contracts[0].observables).toHaveLength(1);
+        expect(result.contracts[0].observables[0].name).toBe("taskCount");
+    });
+    it("uses provided name and description on the contract definition", () => {
+        const cid = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const c = pkg.contract(cid, 1, "Human-Readable Name");
+            c.tables = [
+                {
+                    metaData: {
+                        name: "T",
+                        description: "d",
+                        primaryKeyName: "id",
+                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        expect(result.contracts[0].name).toBe("Human-Readable Name");
+        expect(result.contracts[0].description).toBe("");
+    });
+    it("includes packageId, version, and versionTag in the result", () => {
+        const cid = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.version = "1.2.3";
+            pkg.versionTag = "dev";
+            const c = pkg.contract(cid, 1, "C");
+            c.tables = [
+                {
+                    metaData: {
+                        name: "T",
+                        description: "d",
+                        primaryKeyName: "id",
+                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        expect(result.packageId).toBe(TEST_PKG_ID);
+        expect(result.version).toBe("1.2.3");
+        expect(result.versionTag).toBe("dev");
+    });
+    it("leaves version and versionTag undefined when not set", () => {
+        const cid = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const c = pkg.contract(cid, 1, "C");
+            c.tables = [
+                {
+                    metaData: {
+                        name: "T",
+                        description: "d",
+                        primaryKeyName: "id",
+                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                    },
+                },
+            ];
+        });
+        expect(result.packageId).toBe(TEST_PKG_ID);
+        expect(result.version).toBeUndefined();
+        expect(result.versionTag).toBeUndefined();
+    });
+});
+describe("definePackage — error cases", () => {
+    it("throws when packageId is not set", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.contract(cid, 1, "C");
+            });
+        }).toThrow("must set packageId");
+    });
+    it("throws when packageId is not a valid peer ID", () => {
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = "not-valid";
+            });
+        }).toThrow("valid peer ID");
+    });
+    it("allows package with no contracts (UI-only)", () => {
+        const nav = { name: "Game", iconClassName: "bi-controller", navigationPath: "play" };
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.appNavs = [nav];
+        });
+        expect(result.contracts).toHaveLength(0);
+        expect(result.consumes).toHaveLength(0);
+        expect(result.toolInstances).toHaveLength(0);
+        expect(result.tableDefinitions).toHaveLength(0);
+        expect(result.appNavs).toEqual([nav]);
+    });
+    it("allows consumes-only package with no defined contracts", () => {
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.consumes(TASKS_ID, 1);
+        });
+        expect(result.contracts).toHaveLength(0);
+        expect(result.consumes).toHaveLength(1);
+        expect(result.toolInstances).toHaveLength(0);
+        expect(result.tableDefinitions).toHaveLength(0);
+    });
+    it("throws on duplicate contract ID + version", () => {
+        const dupId = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.contract(dupId, 1, "First");
+                pkg.contract(dupId, 1, "Second");
+            });
+        }).toThrow("Duplicate contract");
+    });
+    it("allows same contractId with different versions", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                const v1 = pkg.contract(cid, 1, "V1");
+                v1.tables = [
+                    {
+                        metaData: {
+                            name: "T",
+                            description: "d",
+                            primaryKeyName: "id",
+                            fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                        },
+                    },
+                ];
+                const v2 = pkg.contract(cid, 2, "V2");
+                v2.tables = [
+                    {
+                        metaData: {
+                            name: "T",
+                            description: "d",
+                            primaryKeyName: "id",
+                            fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                        },
+                    },
+                ];
+            });
+        }).not.toThrow();
+    });
+    it("throws on non-integer version", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.contract(cid, 1.5, "Bad Version");
+            });
+        }).toThrow("positive integer");
+    });
+    it("throws on zero version", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.contract(cid, 0, "Zero");
+            });
+        }).toThrow("positive integer");
+    });
+    it("throws on negative version", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.contract(cid, -1, "Negative");
+            });
+        }).toThrow("positive integer");
+    });
+    it("throws when contractId is not a valid peer ID", () => {
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.contract("tasks001", 1, "Bad ID");
+            });
+        }).toThrow("valid peer ID");
+    });
+    it("throws when consumes contractId is not a valid peer ID", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                pkg.consumes("not-a-peer-id", 1);
+                const c = pkg.contract(cid, 1, "C");
+                c.tables = [
+                    {
+                        metaData: {
+                            name: "T",
+                            description: "d",
+                            primaryKeyName: "id",
+                            fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                        },
+                    },
+                ];
+            });
+        }).toThrow("valid peer ID");
+    });
+    it("throws when alsoImplements targetContractId is not a valid peer ID", () => {
+        const cid = (0, utils_1.newid)();
+        expect(() => {
+            (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = TEST_PKG_ID;
+                const c = pkg.contract(cid, 1, "C");
+                c.alsoImplements("invalid-id", 1);
+                c.tables = [
+                    {
+                        metaData: {
+                            name: "T",
+                            description: "d",
+                            primaryKeyName: "id",
+                            fields: [{ name: "id", type: field_type_1.FieldType.id }],
+                        },
+                    },
+                ];
+            });
+        }).toThrow("valid peer ID");
+    });
+});

package/dist/contracts/__tests__/extract.test.d.ts

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

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

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const types_1 = require("../../data/orm/types");
+const field_type_1 = require("../../types/field-type");
+const extract_1 = require("../extract");
+// Wire in the real schemaToFields before tests run so we don't trigger the
+// lazy require (which would pull in the full DI chain in some environments).
+beforeAll(() => {
+    (0, extract_1.setSchemaToFieldsFn)(types_1.schemaToFields);
+});
+describe("extractTableShape", () => {
+    it("extracts shape from a Zod schema via schemaToFields", () => {
+        const schema = zod_1.z.object({
+            taskId: zod_1.z.string().describe("Primary key"),
+            title: zod_1.z.string().describe("Task title"),
+            done: zod_1.z.boolean().optional().describe("Completion flag"),
+        });
+        const def = {
+            metaData: {
+                name: "Tasks",
+                description: "Task tracking table",
+                primaryKeyName: "taskId",
+                fields: [],
+            },
+            schema,
+        };
+        const shape = (0, extract_1.extractTableShape)(def);
+        expect(shape.name).toBe("Tasks");
+        expect(shape.description).toBe("Task tracking table");
+        expect(shape.primaryKeyName).toBe("taskId");
+        expect(shape.fields).toHaveLength(3);
+        const taskIdField = shape.fields.find((f) => f.name === "taskId");
+        expect(taskIdField?.type).toBe(field_type_1.FieldType.string);
+        const titleField = shape.fields.find((f) => f.name === "title");
+        expect(titleField?.type).toBe(field_type_1.FieldType.string);
+        const doneField = shape.fields.find((f) => f.name === "done");
+        expect(doneField?.type).toBe(field_type_1.FieldType.boolean);
+        expect(doneField?.optional).toBe(true);
+    });
+    it("falls back to metaData.fields when no schema is provided", () => {
+        const def = {
+            metaData: {
+                name: "Legacy",
+                description: "A legacy table",
+                primaryKeyName: "legacyId",
+                fields: [
+                    { name: "legacyId", type: field_type_1.FieldType.id, description: "Primary key" },
+                    { name: "label", type: field_type_1.FieldType.string, description: "Label" },
+                ],
+            },
+        };
+        const shape = (0, extract_1.extractTableShape)(def);
+        expect(shape.name).toBe("Legacy");
+        expect(shape.fields).toHaveLength(2);
+        expect(shape.fields[0].name).toBe("legacyId");
+        expect(shape.fields[1].name).toBe("label");
+    });
+    it("does not mutate the original metaData.fields array", () => {
+        const originalFields = [{ name: "id", type: field_type_1.FieldType.id, description: "PK" }];
+        const def = {
+            metaData: {
+                name: "Test",
+                description: "Test",
+                primaryKeyName: "id",
+                fields: originalFields,
+            },
+        };
+        const shape = (0, extract_1.extractTableShape)(def);
+        shape.fields.push({ name: "extra", type: field_type_1.FieldType.string });
+        expect(originalFields).toHaveLength(1);
+    });
+    it("handles arrays and complex Zod types", () => {
+        const schema = zod_1.z.object({
+            recordId: zod_1.z.string().describe("PK"),
+            tags: zod_1.z.string().array().describe("Tag list"),
+            metadata: zod_1.z.object({}).optional().describe("Arbitrary metadata"),
+        });
+        const def = {
+            metaData: {
+                name: "Records",
+                description: "Records with arrays",
+                primaryKeyName: "recordId",
+                fields: [],
+            },
+            schema,
+        };
+        const shape = (0, extract_1.extractTableShape)(def);
+        const tagsField = shape.fields.find((f) => f.name === "tags");
+        expect(tagsField?.type).toBe(field_type_1.FieldType.string);
+        expect(tagsField?.isArray).toBe(true);
+        const metadataField = shape.fields.find((f) => f.name === "metadata");
+        expect(metadataField?.type).toBe(field_type_1.FieldType.object);
+        expect(metadataField?.optional).toBe(true);
+    });
+});
+describe("extractToolShape", () => {
+    it("extracts name and usageDescription from the tool", () => {
+        const inst = {
+            tool: {
+                name: "create-task",
+                usageDescription: "Creates a new task",
+                inputSchema: { fields: [] },
+                outputSchema: { fields: [] },
+            },
+        };
+        const shape = (0, extract_1.extractToolShape)(inst);
+        expect(shape.name).toBe("create-task");
+        expect(shape.usageDescription).toBe("Creates a new task");
+    });
+    it("extracts input and output fields from IOSchema", () => {
+        const inst = {
+            tool: {
+                name: "create-task",
+                usageDescription: "Creates a task",
+                inputSchema: {
+                    fields: [
+                        { name: "title", type: field_type_1.FieldType.string, description: "Task title" },
+                        { name: "priority", type: field_type_1.FieldType.number, description: "Priority level" },
+                    ],
+                },
+                outputSchema: {
+                    fields: [{ name: "taskId", type: field_type_1.FieldType.id, description: "Created task ID" }],
+                },
+            },
+        };
+        const shape = (0, extract_1.extractToolShape)(inst);
+        expect(shape.inputFields).toHaveLength(2);
+        expect(shape.inputFields[0].name).toBe("title");
+        expect(shape.inputFields[1].name).toBe("priority");
+        expect(shape.outputFields).toHaveLength(1);
+        expect(shape.outputFields[0].name).toBe("taskId");
+    });
+    it("returns empty field arrays when schemas are missing", () => {
+        const inst = {
+            tool: {
+                name: "no-io-tool",
+                usageDescription: "A tool with no I/O",
+            },
+        };
+        const shape = (0, extract_1.extractToolShape)(inst);
+        expect(shape.inputFields).toEqual([]);
+        expect(shape.outputFields).toEqual([]);
+    });
+});

package/dist/contracts/__tests__/integration.test.d.ts

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