@synnaxlabs/client 0.43.1 → 0.44.2

package/src/hardware/device/device.spec.ts

@@ -7,13 +7,12 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { id, type UnknownRecord } from "@synnaxlabs/x";
-import { describe, expect, it } from "vitest";
+import { id, unique } from "@synnaxlabs/x";
+import { beforeAll, describe, expect, it } from "vitest";
 
-import { NotFoundError } from "@/errors";
-import { newClient } from "@/setupspecs";
+import { createTestClient } from "@/testutil/client";
 
-const client = newClient();
+const client = createTestClient();
 
 describe("Device", async () => {
   const testRack = await client.hardware.racks.create({ name: "test" });
@@ -50,7 +49,8 @@ describe("Device", async () => {
       model: "dog",
       properties,
     });
-    const retrieved = await client.hardware.devices.retrieve(d.key);
+    const retrieved = await client.hardware.devices.retrieve({ key: d.key });
+    expect(retrieved.key).toEqual(d.key);
     expect(retrieved.properties).toEqual(properties);
   });
   describe("retrieve", () => {
@@ -64,7 +64,7 @@ describe("Device", async () => {
         model: "dog",
         properties: { cat: "dog" },
       });
-      const retrieved = await client.hardware.devices.retrieve(d.key);
+      const retrieved = await client.hardware.devices.retrieve({ key: d.key });
       expect(retrieved.key).toBe(d.key);
       expect(retrieved.name).toBe("test");
       expect(retrieved.make).toBe("ni");
@@ -88,27 +88,13 @@ describe("Device", async () => {
         model: "dog",
         properties: { cat: "dog" },
       });
-      const retrieved = await client.hardware.devices.retrieve([d1.key, d2.key]);
+      const retrieved = await client.hardware.devices.retrieve({
+        keys: [d1.key, d2.key],
+      });
       expect(retrieved.length).toBe(2);
       expect(retrieved[0].key).toBe(d1.key);
       expect(retrieved[1].key).toBe(d2.key);
     });
-    it("should handle ignoreNotFound option", async () => {
-      // Test multiple device retrieval
-      const results = await client.hardware.devices.retrieve(
-        ["nonexistent_key1", "nonexistent_key2"],
-        { ignoreNotFound: true },
-      );
-      expect(results).toEqual([]);
-    });
-
-    it("should throw an error when device not found and ignoreNotFound is false", async () => {
-      await expect(
-        client.hardware.devices.retrieve(["nonexistent_key"], {
-          ignoreNotFound: false,
-        }),
-      ).rejects.toThrow(NotFoundError);
-    });
 
     describe("state", () => {
       it("should not include state by default", async () => {
@@ -122,11 +108,11 @@ describe("Device", async () => {
           properties: { cat: "dog" },
         });
 
-        const retrieved = await client.hardware.devices.retrieve(d.key);
-        expect(retrieved.state).toBeUndefined();
+        const retrieved = await client.hardware.devices.retrieve({ key: d.key });
+        expect(retrieved.status).toBeUndefined();
       });
 
-      it("should include state when includeState is true", async () => {
+      it("should include status when includeStatus is true", async () => {
         const d = await client.hardware.devices.create({
           key: id.create(),
           rack: testRack.key,
@@ -139,12 +125,13 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const { state } = await client.hardware.devices.retrieve(d.key, {
-              includeState: true,
+            const { status } = await client.hardware.devices.retrieve({
+              key: d.key,
+              includeStatus: true,
             });
-            return state !== undefined;
+            return status != null;
           })
-          .toBeTruthy();
+          .toBe(true);
       });
 
       it("should include state for multiple devices", async () => {
@@ -170,22 +157,17 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const retrievedDevices = await client.hardware.devices.retrieve(
-              [d1.key, d2.key],
-              { includeState: true },
-            );
+            const retrievedDevices = await client.hardware.devices.retrieve({
+              keys: [d1.key, d2.key],
+              includeStatus: true,
+            });
             if (retrievedDevices.length !== 2) return false;
-            return retrievedDevices.every(({ state }) => state !== undefined);
+            return retrievedDevices.every(({ status }) => status !== undefined);
           })
-          .toBeTruthy();
+          .toBe(true);
       });
 
       it("should handle state with type-safe details", async () => {
-        interface DeviceStateDetails {
-          status: string;
-          temperature: number;
-        }
-
         const key = id.create();
         await client.hardware.devices.create({
           key,
@@ -199,19 +181,148 @@ describe("Device", async () => {
 
         await expect
           .poll(async () => {
-            const retrieved = await client.hardware.devices.retrieve<
-              UnknownRecord,
-              string,
-              string,
-              DeviceStateDetails
-            >(key, { includeState: true });
+            const retrieved = await client.hardware.devices.retrieve({
+              key,
+              includeStatus: true,
+            });
             return (
-              retrieved.state !== undefined &&
-              retrieved.state.variant === "info" &&
-              retrieved.state.key === key
+              retrieved.status !== undefined &&
+              retrieved.status.variant === "info" &&
+              retrieved.status.details.device === key
             );
           })
-          .toBeTruthy();
+          .toBe(true);
+      });
+    });
+
+    describe("request object format", () => {
+      const testDevices: Array<{
+        key: string;
+        name: string;
+        make: string;
+        model: string;
+        location: string;
+      }> = [];
+
+      beforeAll(async () => {
+        const deviceConfigs = [
+          { name: "sensor1", make: "ni", model: "pxi-6281", location: "Lab1" },
+          { name: "sensor2", make: "ni", model: "pxi-6284", location: "Lab2" },
+          { name: "actuator1", make: "labjack", model: "t7", location: "Lab1" },
+          { name: "actuator2", make: "labjack", model: "t4", location: "Lab3" },
+          { name: "controller", make: "opc", model: "server", location: "Lab2" },
+        ];
+
+        for (const config of deviceConfigs) {
+          const key = id.create();
+          await client.hardware.devices.create({
+            key,
+            rack: testRack.key,
+            location: config.location,
+            name: config.name,
+            make: config.make,
+            model: config.model,
+            properties: { test: true },
+          });
+          testDevices.push({ key, ...config });
+        }
+      });
+
+      it("should retrieve devices by names", async () => {
+        const result = await client.hardware.devices.retrieve({
+          names: ["sensor1", "actuator1"],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(unique.unique(result.map((d) => d.name).sort())).toEqual([
+          "actuator1",
+          "sensor1",
+        ]);
+      });
+
+      it("should retrieve devices by makes", async () => {
+        const result = await client.hardware.devices.retrieve({
+          makes: ["ni"],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(result.every((d) => d.make === "ni")).toBe(true);
+      });
+
+      it("should retrieve devices by models", async () => {
+        const result = await client.hardware.devices.retrieve({
+          models: ["pxi-6281", "t7"],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(unique.unique(result.map((d) => d.model).sort())).toEqual([
+          "pxi-6281",
+          "t7",
+        ]);
+      });
+
+      it("should retrieve devices by locations", async () => {
+        const result = await client.hardware.devices.retrieve({
+          locations: ["Lab1"],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(result.every((d) => d.location === "Lab1")).toBe(true);
+      });
+
+      it("should retrieve devices by racks", async () => {
+        const result = await client.hardware.devices.retrieve({
+          racks: [testRack.key],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(5);
+        expect(result.every((d) => d.rack === testRack.key)).toBe(true);
+      });
+
+      it("should retrieve devices by search term", async () => {
+        const result = await client.hardware.devices.retrieve({
+          searchTerm: "sensor1",
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(result.every((d) => d.name.includes("sensor"))).toBe(true);
+      });
+
+      it("should support pagination with limit and offset", async () => {
+        const firstPage = await client.hardware.devices.retrieve({
+          racks: [testRack.key],
+          limit: 2,
+          offset: 0,
+        });
+        expect(firstPage).toHaveLength(2);
+
+        const secondPage = await client.hardware.devices.retrieve({
+          racks: [testRack.key],
+          limit: 2,
+          offset: 2,
+        });
+        expect(secondPage).toHaveLength(2);
+
+        const firstPageKeys = firstPage.map((d) => d.key);
+        const secondPageKeys = secondPage.map((d) => d.key);
+        expect(firstPageKeys.every((key) => !secondPageKeys.includes(key))).toBe(true);
+      });
+
+      it("should support combined filters", async () => {
+        const result = await client.hardware.devices.retrieve({
+          makes: ["ni"],
+          locations: ["Lab1", "Lab2"],
+          includeStatus: true,
+        });
+        expect(result.length).toBeGreaterThanOrEqual(1);
+        expect(
+          result.every((d) => d.make === "ni" && ["Lab1", "Lab2"].includes(d.location)),
+        ).toBe(true);
+
+        await expect
+          .poll(async () => {
+            const devices = await client.hardware.devices.retrieve({
+              makes: ["ni"],
+              locations: ["Lab1", "Lab2"],
+              includeStatus: true,
+            });
+            return devices.every((d) => d.status !== undefined);
+          })
+          .toBe(true);
       });
     });
   });

package/src/hardware/device/payload.ts

@@ -7,8 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { binary, status, type UnknownRecord, unknownRecordZ, zod } from "@synnaxlabs/x";
-import { z } from "zod/v4";
+import { binary, record, status, zod } from "@synnaxlabs/x";
+import { z } from "zod";
 
 import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
 import { decodeJSONString } from "@/util/decodeJSONString";
@@ -16,16 +16,9 @@ import { decodeJSONString } from "@/util/decodeJSONString";
 export const keyZ = z.string();
 export type Key = z.infer<typeof keyZ>;
 
-export const stateZ = z.object({
-  key: keyZ,
-  variant: status.variantZ.or(z.literal("").transform<status.Variant>(() => "info")),
-  details: unknownRecordZ.or(z.string().transform(decodeJSONString)),
-});
+export const statusZ = status.statusZ(z.object({ rack: rackKeyZ, device: keyZ }));
 
-export interface State<Details extends {} = UnknownRecord>
-  extends Omit<z.infer<typeof stateZ>, "details"> {
-  details: Details;
-}
+export interface Status extends z.infer<typeof statusZ> {}
 
 export const deviceZ = z.object({
   key: keyZ,
@@ -35,27 +28,26 @@ export const deviceZ = z.object({
   model: z.string(),
   location: z.string(),
   configured: z.boolean().optional(),
-  properties: unknownRecordZ.or(z.string().transform(decodeJSONString)),
-  state: zod.nullToUndefined(stateZ),
+  properties: record.unknownZ.or(z.string().transform(decodeJSONString)),
+  status: zod.nullToUndefined(statusZ),
 });
 
 export interface Device<
-  Properties extends UnknownRecord = UnknownRecord,
+  Properties extends record.Unknown = record.Unknown,
   Make extends string = string,
   Model extends string = string,
-  StateDetails extends {} = UnknownRecord,
-> extends Omit<z.infer<typeof deviceZ>, "properties" | "state"> {
+> extends Omit<z.infer<typeof deviceZ>, "properties" | "status"> {
   properties: Properties;
   make: Make;
   model: Model;
-  state?: State<StateDetails>;
+  status?: Status;
 }
 
 export const newZ = deviceZ.extend({
   properties: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
 });
 export interface New<
-  Properties extends UnknownRecord = UnknownRecord,
+  Properties extends record.Unknown = record.Unknown,
   Make extends string = string,
   Model extends string = string,
 > extends Omit<z.input<typeof newZ>, "properties"> {
@@ -63,6 +55,3 @@ export interface New<
   make: Make;
   model: Model;
 }
-
-export const ONTOLOGY_TYPE = "device";
-export type OntologyType = typeof ONTOLOGY_TYPE;

package/src/hardware/rack/client.ts

@@ -8,73 +8,81 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { type UnknownRecord } from "@synnaxlabs/x";
 import { array } from "@synnaxlabs/x/array";
-import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
-import { z } from "zod/v4";
+import { z } from "zod";
 
-import { framer } from "@/framer";
 import {
   type Key,
   keyZ,
   type New,
   newZ,
-  ONTOLOGY_TYPE,
   type Payload,
   rackZ,
-  type State,
-  stateZ,
+  type Status,
 } from "@/hardware/rack/payload";
 import { type task } from "@/hardware/task";
-import { ontology } from "@/ontology";
-import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
+import { type ontology } from "@/ontology";
+import { checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
 
 const RETRIEVE_ENDPOINT = "/hardware/rack/retrieve";
 const CREATE_ENDPOINT = "/hardware/rack/create";
 const DELETE_ENDPOINT = "/hardware/rack/delete";
 
-const STATE_CHANNEL_NAME = "sy_rack_state";
+export const STATUS_CHANNEL_NAME = "sy_rack_status";
+export const SET_CHANNEL_NAME = "sy_rack_set";
+export const DELETE_CHANNEL_NAME = "sy_rack_delete";
 
 const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
-  search: z.string().optional(),
+  searchTerm: z.string().optional(),
   embedded: z.boolean().optional(),
   hostIsNode: z.boolean().optional(),
   limit: z.number().optional(),
   offset: z.number().optional(),
-  includeState: z.boolean().optional(),
+  includeStatus: z.boolean().optional(),
 });
-
 const retrieveResZ = z.object({ racks: nullableArrayZ(rackZ) });
 
-const createReqZ = z.object({ racks: newZ.array() });
+const singleRetrieveArgsZ = z.union([
+  z
+    .object({
+      key: keyZ,
+      includeStatus: z.boolean().optional(),
+    })
+    .transform(({ key, includeStatus }) => ({ keys: [key], includeStatus })),
+  z
+    .object({
+      name: z.string(),
+      includeStatus: z.boolean().optional(),
+    })
+    .transform(({ name, includeStatus }) => ({ names: [name], includeStatus })),
+]);
+export type SingleRetrieveArgs = z.input<typeof singleRetrieveArgsZ>;
+
+const multiRetrieveArgsZ = retrieveReqZ;
+
+export type MultiRetrieveArgs = z.input<typeof multiRetrieveArgsZ>;
+
+const retrieveArgsZ = z.union([singleRetrieveArgsZ, multiRetrieveArgsZ]);
 
+export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+
+const createReqZ = z.object({ racks: newZ.array() });
 const createResZ = z.object({ racks: rackZ.array() });
 
 const deleteReqZ = z.object({ keys: keyZ.array() });
-
 const deleteResZ = z.object({});
 
-export interface RetrieveOptions {
-  includeState?: boolean;
-}
-
-export class Client implements AsyncTermSearcher<string, Key, Payload> {
-  readonly type = ONTOLOGY_TYPE;
+export class Client {
+  readonly type = "rack";
   private readonly client: UnaryClient;
   private readonly tasks: task.Client;
-  private readonly frameClient: framer.Client;
 
-  constructor(
-    client: UnaryClient,
-    taskClient: task.Client,
-    frameClient: framer.Client,
-  ) {
+  constructor(client: UnaryClient, taskClient: task.Client) {
     this.client = client;
     this.tasks = taskClient;
-    this.frameClient = frameClient;
   }
 
   async delete(keys: Key | Key[]): Promise<void> {
@@ -99,117 +107,91 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
       createResZ,
     );
     const sugared = this.sugar(res.racks);
-    if (isSingle) return sugared[0];
-    return sugared;
-  }
-
-  async search(term: string): Promise<Rack[]> {
-    const res = await sendRequired<typeof retrieveReqZ, typeof retrieveResZ>(
-      this.client,
-      RETRIEVE_ENDPOINT,
-      { search: term },
-      retrieveReqZ,
-      retrieveResZ,
-    );
-    return this.sugar(res.racks);
-  }
-
-  async page(offset: number, limit: number): Promise<Rack[]> {
-    const res = await sendRequired<typeof retrieveReqZ, typeof retrieveResZ>(
-      this.client,
-      RETRIEVE_ENDPOINT,
-      { offset, limit },
-      retrieveReqZ,
-      retrieveResZ,
-    );
-    return this.sugar(res.racks);
+    return isSingle ? sugared[0] : sugared;
   }
 
-  async retrieve(key: string | Key, options?: RetrieveOptions): Promise<Rack>;
-  async retrieve(keys: Key[], options?: RetrieveOptions): Promise<Rack[]>;
-  async retrieve(
-    racks: string | Key | Key[],
-    options?: RetrieveOptions,
-  ): Promise<Rack | Rack[]> {
-    const { variant, normalized, single } = analyzeParams(racks, {
-      string: "names",
-      number: "keys",
-    });
-    const res = await sendRequired<typeof retrieveReqZ, typeof retrieveResZ>(
+  async retrieve(args: SingleRetrieveArgs): Promise<Rack>;
+  async retrieve(args: MultiRetrieveArgs): Promise<Rack[]>;
+  async retrieve(args: RetrieveArgs): Promise<Rack | Rack[]> {
+    const isSingle = "key" in args || "name" in args;
+    const res = await sendRequired(
       this.client,
       RETRIEVE_ENDPOINT,
-      {
-        [variant]: normalized,
-        includeState: options?.includeState,
-      },
-      retrieveReqZ,
+      args,
+      retrieveArgsZ,
       retrieveResZ,
     );
     const sugared = this.sugar(res.racks);
-    checkForMultipleOrNoResults("Rack", racks, sugared, single);
-    return single ? sugared[0] : sugared;
+    checkForMultipleOrNoResults("Rack", args, sugared, isSingle);
+    return isSingle ? sugared[0] : sugared;
   }
 
-  async openStateObserver(): Promise<framer.ObservableStreamer<State[]>> {
-    return new framer.ObservableStreamer<State[]>(
-      await this.frameClient.openStreamer(STATE_CHANNEL_NAME),
-      (fr) => {
-        const data = fr.get(STATE_CHANNEL_NAME);
-        if (data.length === 0) return [[], false];
-        const states = data.parseJSON(stateZ);
-        return [states, true];
-      },
-    );
-  }
-
-  private sugar(payloads: Payload[]): Rack[] {
-    return payloads.map(
-      ({ key, name, state }) => new Rack(key, name, this.tasks, state),
-    );
+  sugar(payload: Payload): Rack;
+  sugar(payloads: Payload[]): Rack[];
+  sugar(payloads: Payload | Payload[]): Rack | Rack[] {
+    const isSingle = !Array.isArray(payloads);
+    const sugared = array
+      .toArray(payloads)
+      .map(({ key, name, status }) => new Rack(key, name, this.tasks, status));
+    return isSingle ? sugared[0] : sugared;
   }
 }
 
 export class Rack {
   key: Key;
   name: string;
-  state?: State;
+  status?: Status;
   private readonly tasks: task.Client;
 
-  constructor(key: Key, name: string, taskClient: task.Client, state?: State) {
+  constructor(key: Key, name: string, taskClient: task.Client, status?: Status) {
     this.key = key;
     this.name = name;
     this.tasks = taskClient;
-    this.state = state;
+    this.status = status;
   }
 
   async listTasks(): Promise<task.Task[]> {
-    return await this.tasks.retrieve(this.key);
+    return await this.tasks.retrieve({ rack: this.key });
   }
 
-  async retrieveTaskByName(name: string): Promise<task.Task> {
-    return await this.tasks.retrieveByName(name, this.key);
-  }
-
-  async retrieveTaskByType(type: string): Promise<task.Task[]> {
-    return await this.tasks.retrieveByType(type, this.key);
-  }
+  async createTask(task: task.New): Promise<task.Task>;
+  async createTask<
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    task: task.New<Type, Config>,
+    schemas: task.Schemas<Type, Config, StatusData>,
+  ): Promise<task.Task<Type, Config, StatusData>>;
 
   async createTask<
-    Config extends UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(task: task.New<Config, Type>): Promise<task.Task<Config, Details, Type>> {
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    task: task.New<Type, Config>,
+    schemas?: task.Schemas<Type, Config, StatusData>,
+  ): Promise<task.Task<Type, Config, StatusData>> {
     task.key = (
       (BigInt(this.key) << 32n) +
       (BigInt(task.key ?? 0) & 0xffffffffn)
     ).toString();
-    return await this.tasks.create<Config, Details, Type>(task);
+    return await this.tasks.create(
+      task,
+      schemas as Required<task.Schemas<Type, Config, StatusData>>,
+    );
   }
 
-  async deleteTask(task: bigint): Promise<void> {
+  async deleteTask(task: task.Key): Promise<void> {
     await this.tasks.delete([task]);
   }
+
+  get payload(): Payload {
+    return { key: this.key, name: this.name, status: this.status };
+  }
 }
 
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key: key.toString() });
+export const ontologyID = (key: Key): ontology.ID => ({
+  type: "rack",
+  key: key.toString(),
+});

package/src/hardware/rack/payload.ts

@@ -8,31 +8,22 @@
 // included in the file licenses/APL.txt.
 
 import { status, zod } from "@synnaxlabs/x";
-import { TimeStamp } from "@synnaxlabs/x/telem";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 export const keyZ = z.uint32();
 export type Key = z.infer<typeof keyZ>;
 
-export const stateZ = z.object({
-  key: keyZ,
-  variant: status.variantZ.or(z.literal("").transform<status.Variant>(() => "info")),
-  message: z.string(),
-  lastReceived: TimeStamp.z,
-});
+export const statusZ = status.statusZ(z.object({ rack: keyZ }));
 
-export interface State extends z.infer<typeof stateZ> {}
+export interface Status extends z.infer<typeof statusZ> {}
 
 export const rackZ = z.object({
   key: keyZ,
   name: z.string(),
-  state: zod.nullToUndefined(stateZ),
+  status: zod.nullToUndefined(statusZ),
 });
 
 export interface Payload extends z.infer<typeof rackZ> {}
 
 export const newZ = rackZ.partial({ key: true });
 export interface New extends z.input<typeof newZ> {}
-
-export const ONTOLOGY_TYPE = "rack";
-export type OntologyType = typeof ONTOLOGY_TYPE;