@synnaxlabs/client 0.38.0 → 0.39.0

package/src/hardware/task/payload.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -10,108 +10,89 @@
 import { binary, type observe, type UnknownRecord } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { ontology } from "@/ontology";
+import { type Key as RackKey } from "@/hardware/rack/payload";
+import { decodeJSONString } from "@/util/decodeJSONString";
+import { parseWithoutKeyConversion } from "@/util/parseWithoutKeyConversion";
 
-export const taskKeyZ = z.union([
+export const keyZ = z.union([
   z.string(),
   z.bigint().transform((k) => k.toString()),
   z.number().transform((k) => k.toString()),
 ]);
+export type Key = z.infer<typeof keyZ>;
 
-export type TaskKey = z.infer<typeof taskKeyZ>;
+export const statusZ = z.enum(["info", "success", "error", "warning"]);
+export type Status = z.infer<typeof statusZ>;
 
 export const stateZ = z.object({
-  task: taskKeyZ,
-  variant: z.string(),
+  task: keyZ,
+  variant: statusZ,
   key: z.string().optional(),
   details: z
     .record(z.unknown())
-    .or(
-      z.string().transform((c) => {
-        if (c === "") return {};
-        return JSON.parse(c);
-      }),
-    )
+    .or(z.string().transform(parseWithoutKeyConversion))
     .or(z.array(z.unknown()))
-    .or(z.null()),
+    .or(z.null()) as z.ZodType<UnknownRecord | undefined>,
 });
-
-export type State<D extends {} = UnknownRecord> = Omit<
-  z.infer<typeof stateZ>,
-  "details"
-> & {
-  details?: D;
-};
+export interface State<Details extends {} = UnknownRecord>
+  extends Omit<z.infer<typeof stateZ>, "details"> {
+  details?: Details;
+}
 
 export const taskZ = z.object({
-  key: taskKeyZ,
+  key: keyZ,
   name: z.string(),
   type: z.string(),
   internal: z.boolean().optional(),
-  config: z.record(z.unknown()).or(
-    z.string().transform((c) => {
-      if (c === "") return {};
-      return binary.JSON_CODEC.decodeString(c);
-    }),
-  ) as z.ZodType<UnknownRecord>,
+  config: z.record(z.unknown()).or(z.string().transform(decodeJSONString)),
   state: stateZ.optional().nullable(),
   snapshot: z.boolean().optional(),
 });
-
-export const newTaskZ = taskZ.omit({ key: true }).extend({
-  key: taskKeyZ.transform((k) => k.toString()).optional(),
+export interface Payload<
+  Config extends UnknownRecord = UnknownRecord,
+  Details extends {} = UnknownRecord,
+  Type extends string = string,
+> extends Omit<z.output<typeof taskZ>, "config" | "type" | "state"> {
+  type: Type;
+  config: Config;
+  state?: State<Details> | null;
+}
+
+export const newZ = taskZ.omit({ key: true }).extend({
+  key: keyZ.transform((k) => k.toString()).optional(),
   config: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
 });
-
-export type NewTask<
-  C extends UnknownRecord = UnknownRecord,
-  T extends string = string,
-> = Omit<z.input<typeof newTaskZ>, "config" | "state"> & {
-  type: T;
-  config: C;
-};
-
-export type Payload<
-  C extends UnknownRecord = UnknownRecord,
-  D extends {} = UnknownRecord,
-  T extends string = string,
-> = Omit<z.output<typeof taskZ>, "config" | "type" | "state"> & {
-  type: T;
-  config: C;
-  state?: State<D> | null;
-};
+export interface New<
+  Config extends UnknownRecord = UnknownRecord,
+  Type extends string = string,
+> extends Omit<z.input<typeof newZ>, "config" | "state"> {
+  type: Type;
+  config: Config;
+}
 
 export const commandZ = z.object({
-  task: taskKeyZ,
+  task: keyZ,
   type: z.string(),
   key: z.string(),
   args: z
     .record(z.unknown())
-    .or(
-      z.string().transform((c) => {
-        if (c === "") return {};
-        return JSON.parse(c);
-      }),
-    )
+    .or(z.string().transform(parseWithoutKeyConversion))
     .or(z.array(z.unknown()))
     .or(z.null())
     .optional() as z.ZodOptional<z.ZodType<UnknownRecord>>,
 });
+export interface Command<Args extends {} = UnknownRecord>
+  extends Omit<z.infer<typeof commandZ>, "args"> {
+  args?: Args;
+}
 
-export type Command<A extends {} = UnknownRecord> = Omit<
-  z.infer<typeof commandZ>,
-  "args"
-> & {
-  args?: A;
-};
-
-export type StateObservable<D extends UnknownRecord = UnknownRecord> =
-  observe.ObservableAsyncCloseable<State<D>>;
+export interface StateObservable<Details extends {} = UnknownRecord>
+  extends observe.ObservableAsyncCloseable<State<Details>> {}
 
-export type CommandObservable<A extends UnknownRecord = UnknownRecord> =
-  observe.ObservableAsyncCloseable<Command<A>>;
+export interface CommandObservable<Args extends {} = UnknownRecord>
+  extends observe.ObservableAsyncCloseable<Command<Args>> {}
 
-export const ONTOLOGY_TYPE: ontology.ResourceType = "task";
+export const ONTOLOGY_TYPE = "task";
+export type OntologyType = typeof ONTOLOGY_TYPE;
 
-export const ontologyID = (key: TaskKey): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key: key.toString() });
+export const getRackKey = (key: Key): RackKey => Number(BigInt(key) >> 32n);

package/src/hardware/task/task.spec.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -15,101 +15,118 @@ import { newClient } from "@/setupspecs";
 
 const client = newClient();
 
-describe("Hardware", () => {
-  describe("Task", () => {
-    describe("create", () => {
-      it("should create a task on a rack", async () => {
-        const r = await client.hardware.racks.create({ name: "test" });
-        const m = await r.createTask({
-          name: "test",
-          config: { a: "dog" },
-          type: "ni",
-        });
-        expect(m.key).not.toHaveLength(0);
-        const rackKey = BigInt(m.key) >> 32n;
-        expect(Number(rackKey)).toBe(r.key);
+describe("Task", async () => {
+  const testRack = await client.hardware.racks.create({ name: "test" });
+  describe("create", () => {
+    it("should create a task on a rack", async () => {
+      const m = await testRack.createTask({
+        name: "test",
+        config: { a: "dog" },
+        type: "ni",
       });
+      expect(m.key).not.toHaveLength(0);
+      const rackKey = BigInt(m.key) >> 32n;
+      expect(Number(rackKey)).toBe(testRack.key);
     });
-    describe("retrieve", () => {
-      it("should retrieve a task by its key", async () => {
-        const r = await client.hardware.racks.create({ name: "test" });
-        const m = await r.createTask({
-          name: "test",
-          config: { a: "dog" },
-          type: "ni",
-        });
-        const retrieved = await client.hardware.tasks.retrieve(m.key);
-        expect(retrieved.key).toBe(m.key);
-        expect(retrieved.name).toBe("test");
-        expect(retrieved.config).toStrictEqual({ a: "dog" });
-        expect(retrieved.type).toBe("ni");
+    it("should create a task with a config", async () => {
+      const config = {
+        stateRate: 100,
+        inputChannels: [
+          { port: "AIN0", enabled: true },
+          { port: "DAC2", enabled: false },
+        ],
+        dataSaving: false,
+      };
+      const m = await testRack.createTask({
+        name: "test",
+        config,
+        type: "ni",
       });
-      describe("retrieveByName", () => {
-        it("should retrieve a task by its name", async () => {
-          const name = `test-${Date.now()}-${Math.random()}`;
-          const r = await client.hardware.racks.create({ name });
-          const m = await r.createTask({
-            name,
-            config: { a: "dog" },
-            type: "ni",
-          });
-          const retrieved = await client.hardware.tasks.retrieveByName(name);
-          expect(retrieved.key).toBe(m.key);
-        });
+      expect(m.config).toStrictEqual(config);
+    });
+  });
+  describe("update", () => {
+    it("should update a task if the key is provided", async () => {
+      const m = await testRack.createTask({
+        name: "test",
+        config: { a: "dog" },
+        type: "ni",
       });
-      describe("retrieve with state", () => {
-        it("should also send the tasks state", async () => {
-          const r = await client.hardware.racks.create({ name: "test" });
-          const t = await r.createTask({
-            name: "test",
-            config: { a: "dog" },
-            type: "ni",
-          });
-          const w = await client.openWriter(["sy_task_state"]);
-          interface StateDetails {
-            dog: string;
-          }
-          const state: task.State<StateDetails> = {
-            key: id.id(),
-            task: t.key,
-            variant: "success",
-          };
-          expect(await w.write("sy_task_state", [state])).toBeTruthy();
-          await w.close();
-          const retrieved = await client.hardware.tasks.retrieve(t.key, {
-            includeState: true,
-          });
-          expect(retrieved.state).not.toBeNull();
-          expect(retrieved.state?.variant).toBe(state.variant);
-        });
+      const updated = await client.hardware.tasks.create({
+        ...m,
+        name: "updated",
       });
+      expect(updated.name).toBe("updated");
+      const retrieved = await client.hardware.tasks.retrieve(m.key);
+      expect(retrieved.name).toBe("updated");
     });
-
-    describe("copy", () => {
-      it("should correctly copy the task", async () => {
-        const r = await client.hardware.racks.create({ name: "test" });
-        const m = await r.createTask({
+  });
+  describe("retrieve", () => {
+    it("should retrieve a task by its key", async () => {
+      const m = await testRack.createTask({
+        name: "test",
+        config: { a: "dog" },
+        type: "ni",
+      });
+      const retrieved = await client.hardware.tasks.retrieve(m.key);
+      expect(retrieved.key).toBe(m.key);
+      expect(retrieved.name).toBe("test");
+      expect(retrieved.config).toStrictEqual({ a: "dog" });
+      expect(retrieved.type).toBe("ni");
+    });
+    describe("retrieveByName", () => {
+      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.retrieveByName(name);
+        expect(retrieved.key).toBe(m.key);
+      });
+    });
+    describe("retrieve with state", () => {
+      it("should also send the tasks state", async () => {
+        const t = await testRack.createTask({
           name: "test",
           config: { a: "dog" },
           type: "ni",
         });
-        const copy = await client.hardware.tasks.copy(m.key, "New Name", false);
-        expect(copy.name).toBe("New Name");
-        expect(copy.config).toStrictEqual({ a: "dog" });
+        const w = await client.openWriter(["sy_task_state"]);
+        interface StateDetails {
+          dog: string;
+        }
+        const state: task.State<StateDetails> = {
+          key: id.create(),
+          task: t.key,
+          variant: "success",
+        };
+        expect(await w.write("sy_task_state", [state])).toBeTruthy();
+        await w.close();
+        const retrieved = await client.hardware.tasks.retrieve(t.key, {
+          includeState: true,
+        });
+        expect(retrieved.state).not.toBeNull();
+        expect(retrieved.state?.variant).toBe(state.variant);
       });
     });
+  });
 
-    describe("list", () => {
-      it("should list all tasks", async () => {
-        const t = await client.hardware.racks.create({ name: "test" });
-        await t.createTask({
-          name: "test",
-          config: { a: "dog" },
-          type: "ni",
-        });
-        const tasks = await client.hardware.tasks.list();
-        expect(tasks.length).toBeGreaterThan(0);
+  describe("copy", () => {
+    it("should correctly copy the task", async () => {
+      const m = await testRack.createTask({
+        name: "test",
+        config: { a: "dog" },
+        type: "ni",
       });
+      const copy = await client.hardware.tasks.copy(m.key, "New Name", false);
+      expect(copy.name).toBe("New Name");
+      expect(copy.config).toStrictEqual({ a: "dog" });
+    });
+  });
+
+  describe("list", () => {
+    it("should list all tasks", async () => {
+      await testRack.createTask({ name: "test", config: { a: "dog" }, type: "ni" });
+      const tasks = await client.hardware.tasks.list();
+      expect(tasks.length).toBeGreaterThan(0);
     });
   });
 });

package/src/index.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/label/client.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -12,14 +12,14 @@ import { observe } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 
 import { type framer } from "@/framer";
-import { type Key, type Label, labelZ, ontologyID } from "@/label/payload";
+import { type Key, type Label, labelZ, ONTOLOGY_TYPE } from "@/label/payload";
 import { Retriever } from "@/label/retriever";
-import { type NewLabelPayload, type SetOptions, Writer } from "@/label/writer";
+import { type New, type SetOptions, Writer } from "@/label/writer";
 import { ontology } from "@/ontology";
 import { signals } from "@/signals";
 
-const LABEL_SET_NAME = "sy_label_set";
-const LABEL_DELETE_NAME = "sy_label_delete";
+const SET_CHANNEL_NAME = "sy_label_set";
+const DELETE_CHANNEL_NAME = "sy_label_delete";
 
 export class Client implements AsyncTermSearcher<string, Key, Label> {
   readonly type: string = "label";
@@ -44,9 +44,7 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
   }
 
   async retrieve(key: Key): Promise<Label>;
-
   async retrieve(keys: Key[]): Promise<Label[]>;
-
   async retrieve(keys: Key | Key[]): Promise<Label | Label[]> {
     const isMany = Array.isArray(keys);
     const res = await this.retriever.retrieve(keys);
@@ -73,20 +71,16 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
     return await this.retriever.page(offset, limit);
   }
 
-  async create(label: NewLabelPayload): Promise<Label>;
-
-  async create(labels: NewLabelPayload[]): Promise<Label[]>;
-
-  async create(labels: NewLabelPayload | NewLabelPayload[]): Promise<Label | Label[]> {
+  async create(label: New): Promise<Label>;
+  async create(labels: New[]): Promise<Label[]>;
+  async create(labels: New | New[]): Promise<Label | Label[]> {
     const isMany = Array.isArray(labels);
     const res = await this.writer.create(labels);
     return isMany ? res : res[0];
   }
 
   async delete(key: Key): Promise<void>;
-
   async delete(keys: Key[]): Promise<void>;
-
   async delete(keys: Key | Key[]): Promise<void> {
     await this.writer.delete(keys);
   }
@@ -94,8 +88,8 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
   async openChangeTracker(): Promise<signals.Observable<string, Label>> {
     return await signals.openObservable<string, Label>(
       this.frameClient,
-      LABEL_SET_NAME,
-      LABEL_DELETE_NAME,
+      SET_CHANNEL_NAME,
+      DELETE_CHANNEL_NAME,
       decodeChanges,
     );
   }
@@ -132,3 +126,6 @@ const decodeChanges: signals.Decoder<string, Label> = (variant, data) => {
   if (variant === "delete") return data.toUUIDs().map((v) => ({ variant, key: v }));
   return data.parseJSON(labelZ).map((l) => ({ variant, key: l.key, value: l }));
 };
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: ONTOLOGY_TYPE, key });

package/src/label/external.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/label/index.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/label/label.spec.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/label/payload.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -9,10 +9,7 @@
 
 import { z } from "zod";
 
-import { ontology } from "@/ontology";
-
 export const keyZ = z.string().uuid();
-
 export type Key = z.infer<typeof keyZ>;
 
 export type Params = Key | Key[];
@@ -22,10 +19,7 @@ export const labelZ = z.object({
   name: z.string().min(1),
   color: z.string(),
 });
+export interface Label extends z.infer<typeof labelZ> {}
 
-export type Label = z.infer<typeof labelZ>;
-
-export const ONTOLOGY_TYPE: ontology.ResourceType = "label";
-
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key });
+export const ONTOLOGY_TYPE = "label";
+export type OntologyType = typeof ONTOLOGY_TYPE;

package/src/label/retriever.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -22,12 +22,9 @@ const reqZ = z.object({
   offset: z.number().optional(),
   limit: z.number().optional(),
 });
+interface Request extends z.infer<typeof reqZ> {}
 
-type Request = z.infer<typeof reqZ>;
-
-const resZ = z.object({
-  labels: nullableArrayZ(labelZ),
-});
+const resZ = z.object({ labels: nullableArrayZ(labelZ) });
 
 export class Retriever {
   private static readonly ENDPOINT = "/label/retrieve";
@@ -38,8 +35,7 @@ export class Retriever {
   }
 
   async retrieve(labels: Params): Promise<Label[]> {
-    const normalized = toArray(labels);
-    return await this.execute({ keys: normalized });
+    return await this.execute({ keys: toArray(labels) });
   }
 
   async retrieveFor(id: ontology.ID): Promise<Label[]> {

package/src/label/writer.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -14,21 +14,14 @@ import { z } from "zod";
 import { type Key, keyZ, type Label, labelZ } from "@/label/payload";
 import { ontology } from "@/ontology";
 
-export const newLabelPayloadZ = labelZ.extend({ key: keyZ.optional() });
+export const newZ = labelZ.extend({ key: keyZ.optional() });
+export interface New extends z.infer<typeof newZ> {}
 
-export type NewLabelPayload = z.infer<typeof newLabelPayloadZ>;
+const createReqZ = z.object({ labels: newZ.array() });
 
-const createReqZ = z.object({
-  labels: newLabelPayloadZ.array(),
-});
-
-const createResZ = z.object({
-  labels: labelZ.array(),
-});
+const createResZ = z.object({ labels: labelZ.array() });
 
-const deleteReqZ = z.object({
-  keys: keyZ.array(),
-});
+const deleteReqZ = z.object({ keys: keyZ.array() });
 
 const setReqZ = z.object({
   id: ontology.idZ,
@@ -36,8 +29,8 @@ const setReqZ = z.object({
   replace: z.boolean().optional(),
 });
 
-type SetReq = z.infer<typeof setReqZ>;
-export type SetOptions = Pick<SetReq, "replace">;
+interface SetReq extends z.infer<typeof setReqZ> {}
+export interface SetOptions extends Pick<SetReq, "replace"> {}
 
 const removeReqZ = setReqZ.omit({ replace: true });
 
@@ -55,7 +48,7 @@ export class Writer {
     this.client = client;
   }
 
-  async create(labels: NewLabelPayload | NewLabelPayload[]): Promise<Label[]> {
+  async create(labels: New | New[]): Promise<Label[]> {
     const res = await sendRequired<typeof createReqZ, typeof createResZ>(
       this.client,
       CREATE_ENDPOINT,