@synnaxlabs/client 0.48.0 → 0.49.0

package/src/{hardware/task → task}/task.spec.ts

@@ -7,16 +7,17 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { id, TimeStamp } from "@synnaxlabs/x";
+import { TimeStamp } from "@synnaxlabs/x";
 import { beforeAll, describe, expect, it } from "vitest";
 
-import { task } from "@/hardware/task";
+import { ontology } from "@/ontology";
+import { task } from "@/task";
 import { createTestClient } from "@/testutil/client";
 
 const client = createTestClient();
 
 describe("Task", async () => {
-  const testRack = await client.hardware.racks.create({ name: "test" });
+  const testRack = await client.racks.create({ name: "test" });
   describe("create", () => {
     it("should create a task on a rack", async () => {
       const m = await testRack.createTask({
@@ -44,6 +45,31 @@ describe("Task", async () => {
       });
       expect(m.config).toStrictEqual(config);
     });
+    it("should create a task with a custom status", async () => {
+      const m = await testRack.createTask({
+        name: "task-with-status",
+        config: { test: true },
+        type: "ni",
+        status: {
+          variant: "success",
+          message: "Custom task status",
+          description: "Task is running",
+          time: TimeStamp.now(),
+          details: { running: true, data: { customData: true } },
+        },
+      });
+      expect(m.key).not.toHaveLength(0);
+      const retrieved = await client.tasks.retrieve({
+        key: m.key,
+        includeStatus: true,
+      });
+      expect(retrieved.status).toBeDefined();
+      expect(retrieved.status?.variant).toBe("success");
+      expect(retrieved.status?.message).toBe("Custom task status");
+      expect(retrieved.status?.description).toBe("Task is running");
+      expect(retrieved.status?.details?.task).toBe(m.key);
+      expect(retrieved.status?.details?.running).toBe(true);
+    });
   });
   describe("update", () => {
     it("should update a task if the key is provided", async () => {
@@ -52,12 +78,12 @@ describe("Task", async () => {
         config: { a: "dog" },
         type: "ni",
       });
-      const updated = await client.hardware.tasks.create({
+      const updated = await client.tasks.create({
         ...m,
         name: "updated",
       });
       expect(updated.name).toBe("updated");
-      const retrieved = await client.hardware.tasks.retrieve({ key: m.key });
+      const retrieved = await client.tasks.retrieve({ key: m.key });
       expect(retrieved.name).toBe("updated");
     });
   });
@@ -68,7 +94,7 @@ describe("Task", async () => {
         config: { a: "dog" },
         type: "ni",
       });
-      const retrieved = await client.hardware.tasks.retrieve({ key: m.key });
+      const retrieved = await client.tasks.retrieve({ key: m.key });
       expect(retrieved.key).toBe(m.key);
       expect(retrieved.name).toBe("test");
       expect(retrieved.config).toStrictEqual({ a: "dog" });
@@ -78,31 +104,29 @@ describe("Task", async () => {
     it("should retrieve a task by its name", async () => {
       const name = `test-${Date.now()}-${Math.random()}`;
       const m = await testRack.createTask({ name, config: { a: "dog" }, type: "ni" });
-      const retrieved = await client.hardware.tasks.retrieve({ name });
+      const retrieved = await client.tasks.retrieve({ name });
       expect(retrieved.key).toBe(m.key);
     });
 
-    describe("state", () => {
+    describe("status", () => {
       it("should include task status when requested", async () => {
         const t = await testRack.createTask({
           name: "test",
           config: { a: "dog" },
           type: "ni",
         });
-        const w = await client.openWriter([task.STATUS_CHANNEL_NAME]);
         const communicatedStatus: task.Status = {
-          key: id.create(),
+          key: ontology.idToString(task.ontologyID(t.key)),
           name: "test",
           variant: "success",
           details: { task: t.key, running: false, data: {} },
           message: "test",
           time: TimeStamp.now(),
         };
-        await w.write(task.STATUS_CHANNEL_NAME, [communicatedStatus]);
-        await w.close();
+        await client.statuses.set(communicatedStatus);
         await expect
           .poll(async () => {
-            const retrieved = await client.hardware.tasks.retrieve({
+            const retrieved = await client.tasks.retrieve({
               key: t.key,
               includeStatus: true,
             });
@@ -117,7 +141,7 @@ describe("Task", async () => {
       let secondRack: any;
 
       beforeAll(async () => {
-        secondRack = await client.hardware.racks.create({ name: "test-rack-2" });
+        secondRack = await client.racks.create({ name: "test-rack-2" });
 
         const taskConfigs = [
           { name: "sensor_task1", type: "ni", rack: testRack },
@@ -138,7 +162,7 @@ describe("Task", async () => {
       });
 
       it("should retrieve tasks by rack", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           rack: testRack.key,
         });
         expect(result.length).toBeGreaterThanOrEqual(3);
@@ -147,7 +171,7 @@ describe("Task", async () => {
 
       it("should retrieve tasks by multiple keys", async () => {
         const keysToQuery = testTasks.slice(0, 2).map((t) => t.key);
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           keys: keysToQuery,
         });
         expect(result).toHaveLength(2);
@@ -156,7 +180,7 @@ describe("Task", async () => {
 
       it("should retrieve tasks by multiple names", async () => {
         const namesToQuery = ["sensor_task1", "actuator_task1"];
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           names: namesToQuery,
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -164,7 +188,7 @@ describe("Task", async () => {
       });
 
       it("should retrieve tasks by types", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           types: ["ni"],
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -173,7 +197,7 @@ describe("Task", async () => {
 
       it("should retrieve tasks by multiple types", async () => {
         const typesToQuery = ["ni", "labjack"];
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           types: typesToQuery,
         });
         expect(result.length).toBeGreaterThanOrEqual(4);
@@ -181,7 +205,7 @@ describe("Task", async () => {
       });
 
       it("should support pagination with limit and offset", async () => {
-        const firstPage = await client.hardware.tasks.retrieve({
+        const firstPage = await client.tasks.retrieve({
           rack: testRack.key,
           limit: 2,
           offset: 0,
@@ -189,7 +213,7 @@ describe("Task", async () => {
         expect(firstPage.length).toBeLessThanOrEqual(2);
 
         if (firstPage.length === 2) {
-          const secondPage = await client.hardware.tasks.retrieve({
+          const secondPage = await client.tasks.retrieve({
             rack: testRack.key,
             limit: 2,
             offset: 2,
@@ -204,7 +228,7 @@ describe("Task", async () => {
       });
 
       it("should support combined filters", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           rack: testRack.key,
           types: ["ni"],
           includeStatus: true,
@@ -214,7 +238,7 @@ describe("Task", async () => {
 
         await expect
           .poll(async () => {
-            const tasks = await client.hardware.tasks.retrieve({
+            const tasks = await client.tasks.retrieve({
               rack: testRack.key,
               types: ["ni"],
               includeStatus: true,
@@ -225,14 +249,14 @@ describe("Task", async () => {
       });
 
       it("should handle empty results gracefully", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           types: ["nonexistent_type"],
         });
         expect(result).toEqual([]);
       });
 
       it("should combine rack and type filters", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           rack: secondRack.key,
           types: ["labjack"],
         });
@@ -241,14 +265,14 @@ describe("Task", async () => {
       });
 
       it("should handle limit without offset", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           limit: 1,
         });
         expect(result).toHaveLength(1);
       });
 
       it("should retrieve tasks with includeStatus in request object", async () => {
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           rack: testRack.key,
           includeStatus: true,
         });
@@ -256,7 +280,7 @@ describe("Task", async () => {
 
         await expect
           .poll(async () => {
-            const tasks = await client.hardware.tasks.retrieve({
+            const tasks = await client.tasks.retrieve({
               rack: testRack.key,
               includeStatus: true,
             });
@@ -272,19 +296,19 @@ describe("Task", async () => {
           config: { test: true },
         });
 
-        const snapshotTask = await client.hardware.tasks.copy(
+        const snapshotTask = await client.tasks.copy(
           regularTask.key,
           "snapshot_test_task",
           true,
         );
 
-        const snapshotOnlyResult = await client.hardware.tasks.retrieve({
+        const snapshotOnlyResult = await client.tasks.retrieve({
           snapshot: true,
         });
         expect(snapshotOnlyResult.some((t) => t.key === snapshotTask.key)).toBe(true);
         expect(snapshotOnlyResult.every((t) => t.snapshot === true)).toBe(true);
 
-        const regularOnlyResult = await client.hardware.tasks.retrieve({
+        const regularOnlyResult = await client.tasks.retrieve({
           snapshot: false,
         });
         expect(regularOnlyResult.some((t) => t.key === regularTask.key)).toBe(true);
@@ -298,7 +322,7 @@ describe("Task", async () => {
           config: { test: true },
         });
 
-        const result = await client.hardware.tasks.retrieve({
+        const result = await client.tasks.retrieve({
           rack: testRack.key,
           types: ["ni"],
           snapshot: false,
@@ -311,6 +335,35 @@ describe("Task", async () => {
     });
   });
 
+  describe("list", () => {
+    it("should list all tasks excluding internal tasks", async () => {
+      const tasks = await client.tasks.list();
+      expect(Array.isArray(tasks)).toBe(true);
+      expect(tasks.every((t) => t.internal === false)).toBe(true);
+    });
+
+    it("should list tasks on a specific rack", async () => {
+      const task1 = await testRack.createTask({
+        name: `list-test-${Date.now()}`,
+        config: { test: true },
+        type: "ni",
+      });
+      const tasks = await client.tasks.list(testRack.key);
+      expect(tasks.some((t) => t.key === task1.key)).toBe(true);
+      expect(tasks.every((t) => task.rackKey(t.key) === testRack.key)).toBe(true);
+    });
+
+    it("should exclude internal tasks by default", async () => {
+      const allTasks = await client.tasks.list();
+      const internalTasks = await client.tasks.retrieve({
+        internal: true,
+      });
+      const allTaskKeys = allTasks.map((t) => t.key);
+      const internalTaskKeys = internalTasks.map((t) => t.key);
+      expect(internalTaskKeys.every((key) => !allTaskKeys.includes(key))).toBe(true);
+    });
+  });
+
   describe("copy", () => {
     it("should correctly copy the task", async () => {
       const m = await testRack.createTask({
@@ -318,12 +371,122 @@ describe("Task", async () => {
         config: { a: "dog" },
         type: "ni",
       });
-      const copy = await client.hardware.tasks.copy(m.key, "New Name", false);
+      const copy = await client.tasks.copy(m.key, "New Name", false);
       expect(copy.name).toBe("New Name");
       expect(copy.config).toStrictEqual({ a: "dog" });
     });
   });
 
+  describe("lifecycle methods", () => {
+    it("should start a task", async () => {
+      const t = await testRack.createTask({
+        name: "lifecycle-start-test",
+        config: {},
+        type: "ni",
+      });
+      const streamer = await client.openStreamer(task.COMMAND_CHANNEL_NAME);
+      await t.start();
+      await expect
+        .poll<Promise<task.Command>>(async () => {
+          const fr = await streamer.read();
+          const sample = fr.at(-1)[task.COMMAND_CHANNEL_NAME];
+          return task.commandZ.parse(sample);
+        })
+        .toMatchObject({ task: t.key, type: "start" });
+      streamer.close();
+    });
+
+    it("should stop a task", async () => {
+      const t = await testRack.createTask({
+        name: "lifecycle-stop-test",
+        config: {},
+        type: "ni",
+      });
+      const streamer = await client.openStreamer(task.COMMAND_CHANNEL_NAME);
+      await t.stop();
+      await expect
+        .poll<Promise<task.Command>>(async () => {
+          const fr = await streamer.read();
+          const sample = fr.at(-1)[task.COMMAND_CHANNEL_NAME];
+          return task.commandZ.parse(sample);
+        })
+        .toMatchObject({ task: t.key, type: "stop" });
+      streamer.close();
+    });
+
+    it("should run a task with automatic start and stop", async () => {
+      const t = await testRack.createTask({
+        name: "lifecycle-run-test",
+        config: {},
+        type: "ni",
+      });
+      const streamer = await client.openStreamer(task.COMMAND_CHANNEL_NAME);
+      let executedCallback = false;
+
+      await t.run(async () => {
+        executedCallback = true;
+      });
+
+      expect(executedCallback).toBe(true);
+
+      // Should have received both start and stop commands
+      const commands: task.Command[] = [];
+      await expect
+        .poll(async () => {
+          try {
+            const fr = await streamer.read();
+            const samples = fr.get(task.COMMAND_CHANNEL_NAME);
+            for (const sample of samples) commands.push(task.commandZ.parse(sample));
+
+            return (
+              commands.some((c) => c.task === t.key && c.type === "start") &&
+              commands.some((c) => c.task === t.key && c.type === "stop")
+            );
+          } catch {
+            return false;
+          }
+        })
+        .toBe(true);
+
+      streamer.close();
+    });
+
+    it("should stop task even if callback throws error", async () => {
+      const t = await testRack.createTask({
+        name: "lifecycle-run-error-test",
+        config: {},
+        type: "ni",
+      });
+      const streamer = await client.openStreamer(task.COMMAND_CHANNEL_NAME);
+
+      await expect(
+        t.run(async () => {
+          throw new Error("Test error");
+        }),
+      ).rejects.toThrow("Test error");
+
+      // Should still have received stop command
+      const stopCommands: task.Command[] = [];
+      await expect
+        .poll(async () => {
+          try {
+            const fr = await streamer.read();
+            const samples = fr.get(task.COMMAND_CHANNEL_NAME);
+            for (const sample of samples) {
+              const cmd = task.commandZ.parse(sample);
+              if (cmd.task === t.key && cmd.type === "stop") stopCommands.push(cmd);
+            }
+            return stopCommands.length > 0;
+          } catch {
+            return false;
+          }
+        })
+        .toBe(true);
+
+      streamer.close();
+    });
+  });
+
   describe("executeCommand", () => {
     it("should execute a command on a task", async () => {
       const type = "testCmd";
@@ -334,7 +497,7 @@ describe("Task", async () => {
         type: "ni",
       });
       const streamer = await client.openStreamer(task.COMMAND_CHANNEL_NAME);
-      const key = await client.hardware.tasks.executeCommand({
+      const key = await client.tasks.executeCommand({
         task: t.key,
         type,
         args,

package/src/testutil/access.ts

@@ -0,0 +1,34 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { id } from "@synnaxlabs/x";
+
+import { policy } from "@/access/policy";
+import { role } from "@/access/role";
+import type Synnax from "@/client";
+import { createTestClient } from "@/testutil/client";
+
+export const createTestClientWithPolicy = async (client: Synnax, pol: policy.New) => {
+  const username = id.create();
+  const u = await client.users.create({
+    username,
+    password: "test",
+    firstName: "test",
+    lastName: "test",
+  });
+  const p = await client.access.policies.create(pol);
+  const r = await client.access.roles.create({
+    name: "test",
+    description: "test",
+  });
+  await client.ontology.addChildren(role.ontologyID(r.key), policy.ontologyID(p.key));
+  await client.access.roles.assign({ user: u.key, role: r.key });
+  const userClient = createTestClient({ username, password: "test" });
+  return userClient;
+};

package/src/testutil/channels.ts

@@ -17,13 +17,13 @@ export const newIndexedPair = async (
 ): Promise<[channel.Channel, channel.Channel]> => {
   const index = await client.channels.create({
     leaseholder: 1,
-    name: `test-${id.create()}`,
+    name: id.create(),
     dataType: DataType.TIMESTAMP,
     isIndex: true,
   });
   const data = await client.channels.create({
     leaseholder: 1,
-    name: `test-${id.create()}`,
+    name: id.create(),
     dataType: DataType.FLOAT64,
     index: index.key,
   });
@@ -32,7 +32,7 @@ export const newIndexedPair = async (
 
 export const newVirtualChannel = async (client: Synnax): Promise<channel.Channel> => {
   const ch = await client.channels.create({
-    name: `test-${id.create()}`,
+    name: id.create(),
     dataType: DataType.FLOAT64,
     virtual: true,
   });

package/src/transport.ts

@@ -16,8 +16,6 @@ import {
 } from "@synnaxlabs/freighter";
 import { binary, type breaker, type URL } from "@synnaxlabs/x";
 
-const baseAPIEndpoint = "/api/v1/";
-
 export class Transport {
   readonly url: URL;
   readonly unary: UnaryClient;
@@ -26,7 +24,7 @@ export class Transport {
 
   constructor(url: URL, breakerCfg: breaker.Config = {}, secure: boolean = false) {
     this.secure = secure;
-    this.url = url.child(baseAPIEndpoint);
+    this.url = url.child("/api/v1/");
     const codec = new binary.JSONCodec();
     this.unary = unaryWithBreaker(
       new HTTPClient(this.url, codec, this.secure),

package/src/user/access.spec.ts

@@ -0,0 +1,107 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { id } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { AuthError, NotFoundError } from "@/errors";
+import { createTestClientWithPolicy } from "@/testutil/access";
+import { createTestClient } from "@/testutil/client";
+import { user } from "@/user";
+
+const client = createTestClient();
+
+describe("user", () => {
+  describe("access control", () => {
+    it("should deny access when no retrieve policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [],
+        actions: [],
+      });
+      const randomUser = await client.users.create({
+        username: id.create(),
+        password: "test",
+      });
+      await expect(userClient.users.retrieve({ key: randomUser.key })).rejects.toThrow(
+        AuthError,
+      );
+    });
+
+    it("should allow the caller to retrieve users with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [user.ontologyID("")],
+        actions: ["retrieve"],
+      });
+      const randomUser = await client.users.create({
+        username: id.create(),
+        password: "test",
+      });
+      const retrieved = await userClient.users.retrieve({ key: randomUser.key });
+      expect(retrieved.key).toBe(randomUser.key);
+      expect(retrieved.username).toBe(randomUser.username);
+    });
+
+    it("should allow the caller to create users with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [user.ontologyID("")],
+        actions: ["create"],
+      });
+      await userClient.users.create({
+        username: id.create(),
+        password: "test",
+      });
+    });
+
+    it("should deny access when no create policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [user.ontologyID("")],
+        actions: [],
+      });
+      await expect(
+        userClient.users.create({
+          username: id.create(),
+          password: "test",
+        }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to delete users with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [user.ontologyID("")],
+        actions: ["delete"],
+      });
+      const randomUser = await client.users.create({
+        username: id.create(),
+        password: "test",
+      });
+      await userClient.users.delete(randomUser.key);
+      await expect(userClient.users.retrieve({ key: randomUser.key })).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+
+    it("should deny access when no delete policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [user.ontologyID("")],
+        actions: [],
+      });
+      const randomUser = await client.users.create({
+        username: id.create(),
+        password: "test",
+      });
+      await expect(userClient.users.delete(randomUser.key)).rejects.toThrow(AuthError);
+    });
+  });
+});