@synnaxlabs/client 0.50.0 → 0.53.0

package/src/channel/client.ts

@@ -24,7 +24,6 @@ import {
   type Key,
   type KeyOrName,
   keyZ,
-  type Name,
   type New,
   ontologyID,
   type Operation,
@@ -45,8 +44,8 @@ import {
 import { type Writer } from "@/channel/writer";
 import { ValidationError } from "@/errors";
 import { type framer } from "@/framer";
+import { group } from "@/group";
 import { type ontology } from "@/ontology";
-import { group } from "@/ontology/group";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
 interface CreateOptions {
@@ -73,10 +72,9 @@ export class Channel {
    */
   readonly key: Key;
   /**
-   * A human-readable name for the channel. This name is not guaranteed to be
-   * unique.
+   * A human-readable name for the channel. This name is not guaranteed to be unique.
    */
-  readonly name: Name;
+  readonly name: string;
   /**
    * The data type of the channel.
    */

package/src/channel/payload.spec.ts

@@ -43,48 +43,6 @@ describe("nameZ", () => {
       expect(result.success).toBe(false);
       expect(result.error?.issues[0].message).toContain("Name must not be empty");
     });
-
-    it("should reject name starting with digit", () => {
-      const result = nameZ.safeParse("1sensor");
-      expect(result.success).toBe(false);
-      // Regex validation covers both "cannot start with digit" and "invalid characters"
-      expect(result.error?.issues[0].message).toContain(
-        "can only contain letters, digits, and underscores",
-      );
-    });
-
-    it("should reject name with spaces", () => {
-      const result = nameZ.safeParse("my channel");
-      expect(result.success).toBe(false);
-      expect(result.error?.issues[0].message).toContain(
-        "can only contain letters, digits, and underscores",
-      );
-    });
-
-    it("should reject name with special characters", () => {
-      const result = nameZ.safeParse("sensor!");
-      expect(result.success).toBe(false);
-    });
-
-    it("should reject name with hyphens", () => {
-      const result = nameZ.safeParse("sensor-temp");
-      expect(result.success).toBe(false);
-    });
-
-    it("should reject name with dots", () => {
-      const result = nameZ.safeParse("sensor.temp");
-      expect(result.success).toBe(false);
-    });
-
-    it("should reject name with parentheses", () => {
-      const result = nameZ.safeParse("sensor(1)");
-      expect(result.success).toBe(false);
-    });
-
-    it("should reject name with brackets", () => {
-      const result = nameZ.safeParse("sensor[0]");
-      expect(result.success).toBe(false);
-    });
   });
 });
 
@@ -106,21 +64,6 @@ describe("newZ", () => {
       expect(result.success).toBe(false);
     });
 
-    it("should reject name starting with digit", () => {
-      const result = newZ.safeParse({ ...validNewChannel, name: "1sensor" });
-      expect(result.success).toBe(false);
-    });
-
-    it("should reject name with spaces", () => {
-      const result = newZ.safeParse({ ...validNewChannel, name: "my channel" });
-      expect(result.success).toBe(false);
-    });
-
-    it("should reject name with special characters", () => {
-      const result = newZ.safeParse({ ...validNewChannel, name: "sensor-temp" });
-      expect(result.success).toBe(false);
-    });
-
     it("should accept name with underscores", () => {
       const result = newZ.safeParse({
         ...validNewChannel,

package/src/channel/payload.ts

@@ -30,19 +30,10 @@ export const keyZ = z.uint32().or(
 );
 export type Key = z.infer<typeof keyZ>;
 export type Keys = Key[];
-const VALID_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-export const nameZ = z
-  .string()
-  .min(1, "Name must not be empty")
-  .regex(
-    VALID_NAME_PATTERN,
-    "Name can only contain letters, digits, and underscores, and cannot start with a digit",
-  );
-export type Name = z.infer<typeof nameZ>;
-export type Names = Name[];
-export type KeyOrName = Key | Name;
-export type KeysOrNames = Keys | Names;
-export type PrimitiveParams = Key | Name | Keys | Names;
+export const nameZ = z.string().min(1, "Name must not be empty");
+export type KeyOrName = Key | string;
+export type KeysOrNames = Keys | string[];
+export type PrimitiveParams = KeyOrName | KeysOrNames;
 
 export const OPERATION_TYPES = ["min", "max", "avg", "none"] as const;
 export const operationType = z.enum(OPERATION_TYPES);
@@ -105,13 +96,15 @@ export const paramsZ = z.union([
   zod.toArray(nameZ),
   zod.toArray(payloadZ).transform((p) => p.map((c) => c.key)),
 ]);
-export type Params = Key | Name | Keys | Names | Payload | Payload[];
+export type Params = PrimitiveParams | Payload | Payload[];
 
 export const ontologyID = ontology.createIDFactory<Key>("channel");
 export const TYPE_ONTOLOGY_ID = ontologyID(0);
 
 const CHAR_REGEX = /[a-zA-Z0-9_]/;
 
+const VALID_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
 export const escapeInvalidName = (name: string, changeEmptyToUnderscore = false) => {
   if (name === "") return changeEmptyToUnderscore ? "_" : "";
   if (name.match(VALID_NAME_PATTERN)) return name;

package/src/channel/retriever.ts

@@ -18,11 +18,10 @@ import {
   type Keys,
   type KeysOrNames,
   keyZ,
-  type Name,
-  type Names,
   type Params,
   type Payload,
   payloadZ,
+  type PrimitiveParams,
 } from "@/channel/payload";
 import { QueryError } from "@/errors";
 import { keyZ as rangeKeyZ } from "@/ranger/payload";
@@ -62,7 +61,7 @@ export const analyzeParams = (
   if (Array.isArray(channels) && channels.length > 0 && typeof channels[0] === "object")
     channels = (channels as Payload[]).map((c) => c.key);
   else if (typeof channels === "object" && "key" in channels) channels = [channels.key];
-  return analyzeParameters(channels as Key | Name | Keys | Names, {
+  return analyzeParameters(channels as PrimitiveParams, {
     number: "keys",
     string: "names",
   });

package/src/client.ts

@@ -19,11 +19,16 @@ import { control } from "@/control";
 import { device } from "@/device";
 import { errorsMiddleware } from "@/errors";
 import { framer } from "@/framer";
+import { group } from "@/group";
 import { label } from "@/label";
+import { lineplot } from "@/lineplot";
+import { log } from "@/log";
 import { ontology } from "@/ontology";
 import { rack } from "@/rack";
 import { ranger } from "@/ranger";
+import { schematic } from "@/schematic";
 import { status } from "@/status";
+import { table } from "@/table";
 import { task } from "@/task";
 import { Transport } from "@/transport";
 import { user } from "@/user";
@@ -73,6 +78,11 @@ export default class Synnax extends framer.Client {
   readonly control: control.Client;
   readonly arcs: arc.Client;
   readonly views: view.Client;
+  readonly schematics: schematic.Client;
+  readonly lineplots: lineplot.Client;
+  readonly logs: log.Client;
+  readonly tables: table.Client;
+  readonly groups: group.Client;
   static readonly connectivity = connection.Checker;
   private readonly transport: Transport;
 
@@ -131,7 +141,7 @@ export default class Synnax extends framer.Client {
       parsedParams.name,
     );
     this.control = new control.Client(this);
-    this.ontology = new ontology.Client(transport.unary, this);
+    this.ontology = new ontology.Client(this.transport.unary);
     const rangeWriter = new ranger.Writer(this.transport.unary);
     this.labels = new label.Client(this.transport.unary);
     this.statuses = new status.Client(this.transport.unary);
@@ -156,6 +166,11 @@ export default class Synnax extends framer.Client {
     this.devices = new device.Client(this.transport.unary);
     this.arcs = new arc.Client(this.transport.unary, this.transport.stream);
     this.views = new view.Client(this.transport.unary);
+    this.schematics = new schematic.Client(this.transport.unary);
+    this.lineplots = new lineplot.Client(this.transport.unary);
+    this.logs = new log.Client(this.transport.unary);
+    this.tables = new table.Client(this.transport.unary);
+    this.groups = new group.Client(this.transport.unary);
   }
 
   get key(): string {

package/src/device/client.ts

@@ -8,10 +8,18 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { array, type record } from "@synnaxlabs/x";
+import { array, type record, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { type Device, deviceZ, type Key, keyZ, type New, newZ } from "@/device/payload";
+import {
+  type Device,
+  type DeviceSchemas,
+  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";
@@ -19,8 +27,21 @@ import { checkForMultipleOrNoResults } from "@/util/retrieve";
 export const SET_CHANNEL_NAME = "sy_device_set";
 export const DELETE_CHANNEL_NAME = "sy_device_delete";
 
-const createReqZ = z.object({ devices: newZ.array() });
-const createResZ = z.object({ devices: deviceZ.array() });
+const createReqZ = <
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+>(
+  schemas?: DeviceSchemas<Properties, Make, Model>,
+) => z.object({ devices: zod.toArray(newZ(schemas)) });
+
+const createResZ = <
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+>(
+  schemas?: DeviceSchemas<Properties, Make, Model>,
+) => z.object({ devices: deviceZ(schemas).array() });
 
 const deleteReqZ = z.object({ keys: keyZ.array() });
 const deleteResZ = z.object({});
@@ -37,7 +58,14 @@ const retrieveRequestZ = z.object({
   offset: z.int().optional(),
   includeStatus: z.boolean().optional(),
 });
-const retrieveResZ = z.object({ devices: array.nullableZ(deviceZ) });
+
+const retrieveResZ = <
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+>(
+  schemas?: DeviceSchemas<Properties, Make, Model>,
+) => z.object({ devices: array.nullableZ(deviceZ(schemas)) });
 
 const singleRetrieveArgsZ = z
   .object({
@@ -56,6 +84,12 @@ const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveRequestZ]);
 
 export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
 
+type RetrieveSchemas<
+  Properties extends z.ZodType<record.Unknown>,
+  Make extends z.ZodType<string>,
+  Model extends z.ZodType<string>,
+> = { schemas: DeviceSchemas<Properties, Make, Model> };
+
 export class Client {
   private readonly client: UnaryClient;
 
@@ -64,64 +98,76 @@ export class Client {
   }
 
   async retrieve<
-    Properties extends record.Unknown = record.Unknown,
-    Make extends string = string,
-    Model extends string = string,
-  >(args: RetrieveSingleParams): Promise<Device<Properties, Make, Model>>;
+    Properties extends z.ZodType<record.Unknown>,
+    Make extends z.ZodType<string>,
+    Model extends z.ZodType<string>,
+  >(
+    args: RetrieveSingleParams & RetrieveSchemas<Properties, Make, Model>,
+  ): Promise<Device<Properties, Make, Model>>;
 
-  async retrieve<
-    Properties extends record.Unknown = record.Unknown,
-    Make extends string = string,
-    Model extends string = string,
-  >(args: RetrieveMultipleParams): Promise<Array<Device<Properties, Make, Model>>>;
+  async retrieve(args: RetrieveSingleParams): Promise<Device>;
 
   async retrieve<
-    Properties extends record.Unknown = record.Unknown,
-    Make extends string = string,
-    Model extends string = string,
+    Properties extends z.ZodType<record.Unknown>,
+    Make extends z.ZodType<string>,
+    Model extends z.ZodType<string>,
   >(
-    args: RetrieveArgs,
-  ): Promise<Device<Properties, Make, Model> | Array<Device<Properties, Make, Model>>> {
-    const isSingle = typeof args === "object" && "key" in args;
+    args: RetrieveMultipleParams & RetrieveSchemas<Properties, Make, Model>,
+  ): Promise<Array<Device<Properties, Make, Model>>>;
+
+  async retrieve(args: RetrieveMultipleParams): Promise<Array<Device>>;
+
+  async retrieve(
+    args: RetrieveArgs & { schemas?: DeviceSchemas },
+  ): Promise<Device | Array<Device>> {
+    const { schemas, ...rest } = args as RetrieveArgs & { schemas?: DeviceSchemas };
+    const isSingle = typeof rest === "object" && "key" in rest;
     const res = await sendRequired(
       this.client,
       "/device/retrieve",
-      args,
+      rest,
       retrieveArgsZ,
-      retrieveResZ,
+      retrieveResZ(schemas),
     );
-    checkForMultipleOrNoResults("Device", args, res.devices, isSingle);
-    const devices = res.devices as Device<Properties, Make, Model>[];
-    return isSingle ? devices[0] : devices;
+    checkForMultipleOrNoResults("Device", rest, res.devices, isSingle);
+    return isSingle ? res.devices[0] : res.devices;
   }
 
   async create<
-    Properties extends record.Unknown = record.Unknown,
-    Make extends string = string,
-    Model extends string = string,
-  >(device: New<Properties, Make>): Promise<Device<Properties, Make, Model>>;
-  async create<
-    Properties extends record.Unknown = record.Unknown,
-    Make extends string = string,
-    Model extends string = string,
-  >(devices: New<Properties, Make>[]): Promise<Device<Properties, Make, Model>[]>;
+    Properties extends z.ZodType<record.Unknown>,
+    Make extends z.ZodType<string>,
+    Model extends z.ZodType<string>,
+  >(
+    device: New<Properties, Make, Model>,
+    schemas: DeviceSchemas<Properties, Make, Model>,
+  ): Promise<Device<Properties, Make, Model>>;
+
+  async create(device: New): Promise<Device>;
+
   async create<
-    Properties extends record.Unknown = record.Unknown,
-    Make extends string = string,
-    Model extends string = string,
+    Properties extends z.ZodType<record.Unknown>,
+    Make extends z.ZodType<string>,
+    Model extends z.ZodType<string>,
   >(
-    devices: New<Properties, Make> | New<Properties, Make>[],
-  ): Promise<Device<Properties, Make, Model> | Device<Properties, Make, Model>[]> {
+    devices: New<Properties, Make, Model>[],
+    schemas: DeviceSchemas<Properties, Make, Model>,
+  ): Promise<Device<Properties, Make, Model>[]>;
+
+  async create(devices: New[]): Promise<Device[]>;
+
+  async create(
+    devices: New | New[],
+    schemas?: DeviceSchemas,
+  ): Promise<Device | Device[]> {
     const isSingle = !Array.isArray(devices);
     const res = await sendRequired(
       this.client,
       "/device/create",
       { devices: array.toArray(devices) },
-      createReqZ,
-      createResZ,
+      createReqZ(schemas),
+      createResZ(schemas),
     );
-    const created = res.devices as Device<Properties, Make, Model>[];
-    return isSingle ? created[0] : created;
+    return isSingle ? res.devices[0] : res.devices;
   }
 
   async delete(keys: Key | Key[]): Promise<void> {

package/src/device/payload.spec.ts

@@ -0,0 +1,118 @@
+// Copyright 2026 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 { deviceZ, newZ } from "@/device/payload";
+
+const VALID_DEVICE = {
+  key: "dev-1",
+  rack: 1,
+  name: "Test Device",
+  make: "ni",
+  model: "pxi-6281",
+  location: "Lab1",
+  properties: { rate: 10 },
+  status: null,
+};
+
+describe("deviceZ", () => {
+  describe("default schemas", () => {
+    it("should accept a valid device", () => {
+      const result = deviceZ().safeParse(VALID_DEVICE);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject a device with an empty name", () => {
+      const result = deviceZ().safeParse({ ...VALID_DEVICE, name: "" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject a device with an empty make", () => {
+      const result = deviceZ().safeParse({ ...VALID_DEVICE, make: "" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject a device with an empty model", () => {
+      const result = deviceZ().safeParse({ ...VALID_DEVICE, model: "" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should accept properties as an object", () => {
+      const result = deviceZ().parse(VALID_DEVICE);
+      expect(result.properties).toEqual({ rate: 10 });
+    });
+  });
+
+  describe("custom make schema", () => {
+    const makeZ = z.enum(["ni", "labjack"]);
+
+    it("should accept a valid make value", () => {
+      const result = deviceZ({ make: makeZ }).safeParse(VALID_DEVICE);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject an invalid make value", () => {
+      const result = deviceZ({ make: makeZ }).safeParse({
+        ...VALID_DEVICE,
+        make: "unknown",
+      });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe("custom model schema", () => {
+    const modelZ = z.literal("pxi-6281");
+
+    it("should accept a matching model", () => {
+      const result = deviceZ({ model: modelZ }).safeParse(VALID_DEVICE);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject a non-matching model", () => {
+      const result = deviceZ({ model: modelZ }).safeParse({
+        ...VALID_DEVICE,
+        model: "t7",
+      });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe("custom properties schema", () => {
+    const propertiesZ = z.object({ rate: z.number(), channel: z.string() });
+
+    it("should validate properties against the custom schema", () => {
+      const result = deviceZ({ properties: propertiesZ }).safeParse({
+        ...VALID_DEVICE,
+        properties: { rate: 10, channel: "ai0" },
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject properties that don't match the custom schema", () => {
+      expect(() => deviceZ({ properties: propertiesZ }).parse(VALID_DEVICE)).toThrow();
+    });
+  });
+});
+
+describe("newZ", () => {
+  it("should encode properties to a JSON string", () => {
+    const result = newZ().parse(VALID_DEVICE);
+    expect(result.properties).toEqual(VALID_DEVICE.properties);
+  });
+
+  it("should still validate make and model with custom schemas", () => {
+    const makeZ = z.literal("ni");
+    const result = newZ({ make: makeZ }).safeParse(VALID_DEVICE);
+    expect(result.success).toBe(true);
+    const bad = newZ({ make: makeZ }).safeParse({ ...VALID_DEVICE, make: "opc" });
+    expect(bad.success).toBe(false);
+  });
+});

package/src/device/payload.ts

@@ -7,11 +7,10 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { binary, record, status, zod } from "@synnaxlabs/x";
+import { record, status, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { keyZ as rackKeyZ } from "@/rack/payload";
-import { decodeJSONString } from "@/util/decodeJSONString";
 
 export const keyZ = z.string();
 export type Key = z.infer<typeof keyZ>;
@@ -21,38 +20,64 @@ export const statusZ = status.statusZ(statusDetailsZ);
 
 export interface Status extends z.infer<typeof statusZ> {}
 
-export const deviceZ = z.object({
-  key: keyZ,
-  rack: rackKeyZ.min(1, "Must select a location to connect from"),
-  name: z.string().min(1, "Name is required"),
-  make: z.string().min(1, "Make is required"),
-  model: z.string().min(1, "Model is required"),
-  location: z.string().min(1, "Location is required"),
-  configured: z.boolean().optional(),
-  properties: record.unknownZ.or(z.string().transform(decodeJSONString)),
-  status: zod.nullToUndefined(statusZ),
-});
+export interface DeviceSchemas<
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+> {
+  properties?: Properties;
+  make?: Make;
+  model?: Model;
+}
+
+export const deviceZ = <
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+>({ properties, make, model }: DeviceSchemas<Properties, Make, Model> = {}) =>
+  z.object({
+    key: keyZ,
+    rack: rackKeyZ.min(1, "Must select a location to connect from"),
+    name: z.string().min(1, "Name is required"),
+    make: make ?? z.string().min(1, "Make is required"),
+    model: model ?? z.string().min(1, "Model is required"),
+    location: z.string().min(1, "Location is required"),
+    configured: z.boolean().optional(),
+    properties: properties ?? record.nullishToEmpty(),
+    status: zod.nullToUndefined(statusZ),
+  });
 
 export interface Device<
-  Properties extends record.Unknown = record.Unknown,
-  Make extends string = string,
-  Model extends string = string,
-> extends Omit<z.infer<typeof deviceZ>, "properties" | "status"> {
-  properties: Properties;
-  make: Make;
-  model: Model;
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+> extends Omit<
+  z.infer<ReturnType<typeof deviceZ>>,
+  "properties" | "make" | "model" | "status"
+> {
+  properties: z.infer<Properties>;
+  make: z.infer<Make>;
+  model: z.infer<Model>;
   status?: Status;
 }
 
-export const newZ = deviceZ.extend({
-  properties: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
-});
+export const newZ = <
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+>(
+  schemas: DeviceSchemas<Properties, Make, Model> = {},
+) =>
+  deviceZ(schemas).extend({
+    properties: schemas?.properties ?? record.nullishToEmpty(),
+  });
+
 export interface New<
-  Properties extends record.Unknown = record.Unknown,
-  Make extends string = string,
-  Model extends string = string,
-> extends Omit<z.input<typeof newZ>, "properties"> {
-  properties: Properties;
-  make: Make;
-  model: Model;
+  Properties extends z.ZodType<record.Unknown> = typeof record.unknownZ,
+  Make extends z.ZodType<string> = z.ZodString,
+  Model extends z.ZodType<string> = z.ZodString,
+> extends Omit<z.input<ReturnType<typeof newZ>>, "properties"> {
+  properties: z.infer<Properties>;
+  make: z.infer<Make>;
+  model: z.infer<Model>;
 }

package/src/errors.spec.ts

@@ -64,7 +64,7 @@ test("client", async () => {
     expect(NotFoundError.matches(e)).toBe(true);
   }
   try {
-    await client.workspaces.schematics.retrieve({ key: uuid.create() });
+    await client.schematics.retrieve({ key: uuid.create() });
   } catch (e) {
     expect(NotFoundError.matches(e)).toBe(true);
   }