@synnaxlabs/client 0.47.0 → 0.49.0

package/src/connection.spec.ts

@@ -0,0 +1,145 @@
+// 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 { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { checkConnection, newConnectionChecker } from "@/client";
+import { TEST_CLIENT_PARAMS } from "@/testutil/client";
+
+describe("checkConnection", () => {
+  it("should check connection to the server", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    expect(state.status).toEqual("connected");
+    expect(z.uuid().safeParse(state.clusterKey).success).toBe(true);
+  });
+
+  it("should include client version in the connection check", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    expect(state.clientVersion).toBeDefined();
+    expect(state.clientServerCompatible).toBe(true);
+  });
+
+  it("should support custom name parameter", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "test-client",
+    });
+    expect(state.status).toEqual("connected");
+  });
+
+  it("should handle connection failure to invalid host", async () => {
+    const state = await checkConnection({
+      host: "invalid-host-that-does-not-exist",
+      port: 9999,
+      secure: false,
+      retry: {
+        maxRetries: 0, // Disable retries for faster test
+      },
+    });
+    expect(state.status).toEqual("failed");
+  });
+
+  it("should handle connection failure to invalid port", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: 9999, // Wrong port
+      secure: false,
+      retry: {
+        maxRetries: 0, // Disable retries for faster test
+      },
+    });
+    expect(state.status).toEqual("failed");
+  });
+});
+
+describe("newConnectionChecker", () => {
+  it("should create a connection checker", () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    expect(checker).toBeDefined();
+  });
+
+  it("should create a checker that can check connection", async () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    const state = await checker.check();
+    expect(state.status).toEqual("connected");
+    expect(z.uuid().safeParse(state.clusterKey).success).toBe(true);
+  });
+
+  it("should support custom name parameter", async () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "custom-checker-name",
+    });
+    const state = await checker.check();
+    expect(state.status).toEqual("connected");
+  });
+
+  it("should support secure connection parameter", () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: true,
+    });
+    expect(checker).toBeDefined();
+  });
+
+  it("should create multiple independent checkers", async () => {
+    const checker1 = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "checker-1",
+    });
+    const checker2 = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "checker-2",
+    });
+
+    const state1 = await checker1.check();
+    const state2 = await checker2.check();
+
+    expect(state1.status).toEqual("connected");
+    expect(state2.status).toEqual("connected");
+    expect(checker1).not.toBe(checker2); // Different instances
+  });
+
+  it("should handle version compatibility checking", async () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    const state = await checker.check();
+    expect(state.clientVersion).toBeDefined();
+    expect(state.clientServerCompatible).toBe(true);
+  });
+});

package/src/device/access.spec.ts

@@ -0,0 +1,159 @@
+// 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 { device } from "@/device";
+import { AuthError, NotFoundError } from "@/errors";
+import { createTestClientWithPolicy } from "@/testutil/access";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("device", () => {
+  describe("access control", () => {
+    it("should deny access when no retrieve policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      await expect(
+        userClient.devices.retrieve({ key: randomDevice.key }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to retrieve devices with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: ["retrieve"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      const retrieved = await userClient.devices.retrieve({
+        key: randomDevice.key,
+      });
+      expect(retrieved.key).toBe(randomDevice.key);
+      expect(retrieved.name).toBe(randomDevice.name);
+    });
+
+    it("should allow the caller to create devices with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: ["create"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      await userClient.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+    });
+
+    it("should deny access when no create policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      await expect(
+        userClient.devices.create({
+          key: id.create(),
+          rack: rack.key,
+          location: "Dev1",
+          name: "test",
+          make: "ni",
+          model: "test",
+          properties: {},
+        }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to delete devices with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: ["delete", "retrieve"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      await userClient.devices.delete(randomDevice.key);
+      await expect(
+        userClient.devices.retrieve({ key: randomDevice.key }),
+      ).rejects.toThrow(NotFoundError);
+    });
+
+    it("should deny access when no delete policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      await expect(userClient.devices.delete(randomDevice.key)).rejects.toThrow(
+        AuthError,
+      );
+    });
+  });
+});

package/src/{hardware/device → device}/client.ts

@@ -11,25 +11,13 @@ import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { array, type record } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import {
-  type Device,
-  deviceZ,
-  type Key,
-  keyZ,
-  type New,
-  newZ,
-} from "@/hardware/device/payload";
-import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
-import { type ontology } from "@/ontology";
+import { type Device, deviceZ, type Key, keyZ, type New, newZ } from "@/device/payload";
+import { ontology } from "@/ontology";
+import { keyZ as rackKeyZ } from "@/rack/payload";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
 export const SET_CHANNEL_NAME = "sy_device_set";
 export const DELETE_CHANNEL_NAME = "sy_device_delete";
-export const STATUS_CHANNEL_NAME = "sy_device_status";
-
-const RETRIEVE_ENDPOINT = "/hardware/device/retrieve";
-const CREATE_ENDPOINT = "/hardware/device/create";
-const DELETE_ENDPOINT = "/hardware/device/delete";
 
 const createReqZ = z.object({ devices: newZ.array() });
 const createResZ = z.object({ devices: deviceZ.array() });
@@ -45,8 +33,8 @@ const retrieveRequestZ = z.object({
   locations: z.string().array().optional(),
   racks: rackKeyZ.array().optional(),
   searchTerm: z.string().optional(),
-  limit: z.number().optional(),
-  offset: z.number().optional(),
+  limit: z.int().optional(),
+  offset: z.int().optional(),
   includeStatus: z.boolean().optional(),
 });
 const retrieveResZ = z.object({ devices: array.nullableZ(deviceZ) });
@@ -97,7 +85,7 @@ export class Client {
     const isSingle = typeof args === "object" && "key" in args;
     const res = await sendRequired(
       this.client,
-      RETRIEVE_ENDPOINT,
+      "/device/retrieve",
       args,
       retrieveArgsZ,
       retrieveResZ,
@@ -127,7 +115,7 @@ export class Client {
     const isSingle = !Array.isArray(devices);
     const res = await sendRequired(
       this.client,
-      CREATE_ENDPOINT,
+      "/device/create",
       { devices: array.toArray(devices) },
       createReqZ,
       createResZ,
@@ -139,7 +127,7 @@ export class Client {
   async delete(keys: Key | Key[]): Promise<void> {
     await sendRequired(
       this.client,
-      DELETE_ENDPOINT,
+      "/device/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,
       deleteResZ,
@@ -147,4 +135,7 @@ export class Client {
   }
 }
 
-export const ontologyID = (key: Key): ontology.ID => ({ type: "device", key });
+export const ontologyID = ontology.createIDFactory<Key>("device");
+export const TYPE_ONTOLOGY_ID = ontologyID("");
+
+export const statusKey = (key: Key): string => ontology.idToString(ontologyID(key));

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

@@ -7,19 +7,20 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { id, unique } from "@synnaxlabs/x";
+import { id, TimeStamp, unique } from "@synnaxlabs/x";
 import { beforeAll, describe, expect, it } from "vitest";
 
+import { type device } from "@/device";
 import { createTestClient } from "@/testutil/client";
 
 const client = createTestClient();
 
 describe("Device", async () => {
-  const testRack = await client.hardware.racks.create({ name: "test" });
+  const testRack = await client.racks.create({ name: "test" });
   describe("create", () => {
     it("should create a device on a rack", async () => {
       const key = id.create();
-      const d = await client.hardware.devices.create({
+      const d = await client.devices.create({
         rack: testRack.key,
         location: "Dev1",
         key,
@@ -32,7 +33,40 @@ describe("Device", async () => {
       expect(d.name).toBe("test");
       expect(d.make).toBe("ni");
     });
+    it("should create a device with a custom status", async () => {
+      const key = id.create();
+      const customStatus: device.Status = {
+        key: "",
+        name: "",
+        variant: "success",
+        message: "Custom device status",
+        description: "Device is connected",
+        time: TimeStamp.now(),
+        details: { rack: 0, device: "" },
+      };
+      const d = await client.devices.create({
+        rack: testRack.key,
+        location: "Dev1",
+        key,
+        name: "device-with-status",
+        make: "ni",
+        model: "dog",
+        properties: { cat: "dog" },
+        status: customStatus,
+      });
+      expect(d.key).toEqual(key);
+      const retrieved = await client.devices.retrieve({
+        key: d.key,
+        includeStatus: true,
+      });
+      expect(retrieved.status).toBeDefined();
+      expect(retrieved.status?.variant).toBe("success");
+      expect(retrieved.status?.message).toBe("Custom device status");
+      expect(retrieved.status?.description).toBe("Device is connected");
+      expect(retrieved.status?.details?.device).toBe(d.key);
+    });
   });
+
   it("should properly encode and decode properties", async () => {
     const properties = {
       rate: 10,
@@ -40,7 +74,7 @@ describe("Device", async () => {
       inputChannels: { port1: 34214 },
       outputChannels: [{ port2: 232 }],
     };
-    const d = await client.hardware.devices.create({
+    const d = await client.devices.create({
       key: id.create(),
       rack: testRack.key,
       location: "Dev1",
@@ -49,13 +83,14 @@ describe("Device", async () => {
       model: "dog",
       properties,
     });
-    const retrieved = await client.hardware.devices.retrieve({ key: d.key });
+    const retrieved = await client.devices.retrieve({ key: d.key });
     expect(retrieved.key).toEqual(d.key);
     expect(retrieved.properties).toEqual(properties);
   });
+
   describe("retrieve", () => {
     it("should retrieve a device by its key", async () => {
-      const d = await client.hardware.devices.create({
+      const d = await client.devices.create({
         key: id.create(),
         rack: testRack.key,
         location: "Dev1",
@@ -64,13 +99,14 @@ describe("Device", async () => {
         model: "dog",
         properties: { cat: "dog" },
       });
-      const retrieved = await client.hardware.devices.retrieve({ key: d.key });
+      const retrieved = await client.devices.retrieve({ key: d.key });
       expect(retrieved.key).toBe(d.key);
       expect(retrieved.name).toBe("test");
       expect(retrieved.make).toBe("ni");
     });
+
     it("should retrieve multiple devices by their keys", async () => {
-      const d1 = await client.hardware.devices.create({
+      const d1 = await client.devices.create({
         key: id.create(),
         rack: testRack.key,
         location: "Dev1",
@@ -79,7 +115,7 @@ describe("Device", async () => {
         model: "dog",
         properties: { cat: "dog" },
       });
-      const d2 = await client.hardware.devices.create({
+      const d2 = await client.devices.create({
         key: id.create(),
         rack: testRack.key,
         location: "Dev2",
@@ -88,7 +124,7 @@ describe("Device", async () => {
         model: "dog",
         properties: { cat: "dog" },
       });
-      const retrieved = await client.hardware.devices.retrieve({
+      const retrieved = await client.devices.retrieve({
         keys: [d1.key, d2.key],
       });
       expect(retrieved.length).toBe(2);
@@ -96,9 +132,9 @@ describe("Device", async () => {
       expect(retrieved[1].key).toBe(d2.key);
     });
 
-    describe("state", () => {
-      it("should not include state by default", async () => {
-        const d = await client.hardware.devices.create({
+    describe("status", () => {
+      it("should not include status by default", async () => {
+        const d = await client.devices.create({
           key: id.create(),
           rack: testRack.key,
           location: "Dev1",
@@ -108,12 +144,12 @@ describe("Device", async () => {
           properties: { cat: "dog" },
         });
 
-        const retrieved = await client.hardware.devices.retrieve({ key: d.key });
+        const retrieved = await client.devices.retrieve({ key: d.key });
         expect(retrieved.status).toBeUndefined();
       });
 
       it("should include status when includeStatus is true", async () => {
-        const d = await client.hardware.devices.create({
+        const d = await client.devices.create({
           key: id.create(),
           rack: testRack.key,
           location: "Dev1",
@@ -125,7 +161,7 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const { status } = await client.hardware.devices.retrieve({
+            const { status } = await client.devices.retrieve({
               key: d.key,
               includeStatus: true,
             });
@@ -134,8 +170,8 @@ describe("Device", async () => {
           .toBe(true);
       });
 
-      it("should include state for multiple devices", async () => {
-        const d1 = await client.hardware.devices.create({
+      it("should include status for multiple devices", async () => {
+        const d1 = await client.devices.create({
           key: id.create(),
           rack: testRack.key,
           location: "Dev1",
@@ -145,7 +181,7 @@ describe("Device", async () => {
           properties: { cat: "dog" },
         });
 
-        const d2 = await client.hardware.devices.create({
+        const d2 = await client.devices.create({
           key: id.create(),
           rack: testRack.key,
           location: "Dev2",
@@ -157,7 +193,7 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const retrievedDevices = await client.hardware.devices.retrieve({
+            const retrievedDevices = await client.devices.retrieve({
               keys: [d1.key, d2.key],
               includeStatus: true,
             });
@@ -169,7 +205,7 @@ describe("Device", async () => {
 
       it("should handle state with type-safe details", async () => {
         const key = id.create();
-        await client.hardware.devices.create({
+        await client.devices.create({
           key,
           rack: testRack.key,
           location: "Dev1",
@@ -181,13 +217,13 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const retrieved = await client.hardware.devices.retrieve({
+            const retrieved = await client.devices.retrieve({
               key,
               includeStatus: true,
             });
             return (
               retrieved.status !== undefined &&
-              retrieved.status.variant === "info" &&
+              retrieved.status.variant === "warning" &&
               retrieved.status.details.device === key
             );
           })
@@ -215,7 +251,7 @@ describe("Device", async () => {
 
         for (const config of deviceConfigs) {
           const key = id.create();
-          await client.hardware.devices.create({
+          await client.devices.create({
             key,
             rack: testRack.key,
             location: config.location,
@@ -229,7 +265,7 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by names", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           names: ["sensor1", "actuator1"],
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -240,7 +276,7 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by makes", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           makes: ["ni"],
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -248,7 +284,7 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by models", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           models: ["pxi-6281", "t7"],
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -259,7 +295,7 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by locations", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           locations: ["Lab1"],
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -267,7 +303,7 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by racks", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           racks: [testRack.key],
         });
         expect(result.length).toBeGreaterThanOrEqual(5);
@@ -275,7 +311,7 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by search term", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           searchTerm: "sensor1",
         });
         expect(result.length).toBeGreaterThanOrEqual(2);
@@ -283,14 +319,14 @@ describe("Device", async () => {
       });
 
       it("should support pagination with limit and offset", async () => {
-        const firstPage = await client.hardware.devices.retrieve({
+        const firstPage = await client.devices.retrieve({
           racks: [testRack.key],
           limit: 2,
           offset: 0,
         });
         expect(firstPage).toHaveLength(2);
 
-        const secondPage = await client.hardware.devices.retrieve({
+        const secondPage = await client.devices.retrieve({
           racks: [testRack.key],
           limit: 2,
           offset: 2,
@@ -303,7 +339,7 @@ describe("Device", async () => {
       });
 
       it("should support combined filters", async () => {
-        const result = await client.hardware.devices.retrieve({
+        const result = await client.devices.retrieve({
           makes: ["ni"],
           locations: ["Lab1", "Lab2"],
           includeStatus: true,
@@ -315,7 +351,7 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const devices = await client.hardware.devices.retrieve({
+            const devices = await client.devices.retrieve({
               makes: ["ni"],
               locations: ["Lab1", "Lab2"],
               includeStatus: true,

package/src/device/external.ts

@@ -0,0 +1,11 @@
+// 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.
+
+export * from "@/device/client";
+export * from "@/device/payload";