@synnaxlabs/client 0.48.0 → 0.49.2

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";

package/src/{hardware/rack → device}/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as rack from "@/hardware/rack/external";
+export * as device from "@/device/external";

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

@@ -10,14 +10,14 @@
 import { binary, record, status, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
+import { keyZ as rackKeyZ } from "@/rack/payload";
 import { decodeJSONString } from "@/util/decodeJSONString";
 
 export const keyZ = z.string();
 export type Key = z.infer<typeof keyZ>;
 
-export const statusDetailsSchema = z.object({ rack: rackKeyZ, device: keyZ });
-export const statusZ = status.statusZ(statusDetailsSchema);
+export const statusDetailsZ = z.object({ rack: rackKeyZ, device: keyZ });
+export const statusZ = status.statusZ(statusDetailsZ);
 
 export interface Status extends z.infer<typeof statusZ> {}
 

package/src/errors.ts

@@ -51,6 +51,8 @@ export class InvalidTokenError extends AuthError.sub("invalid_token") {}
 
 export class ExpiredTokenError extends AuthError.sub("expired_token") {}
 
+export class AccessDeniedError extends AuthError.sub("access_denied") {}
+
 /**
  * UnexpectedError is raised when an unexpected error occurs.
  */

package/src/framer/adapter.spec.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { DataType, Series, TimeStamp } from "@synnaxlabs/x";
+import { DataType, id, Series, TimeStamp } from "@synnaxlabs/x";
 import { beforeAll, describe, expect, it } from "vitest";
 
 import { type channel } from "@/channel";
@@ -24,12 +24,12 @@ describe("WriteFrameAdapter", () => {
 
   beforeAll(async () => {
     timeCh = await client.channels.create({
-      name: `time-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.TIMESTAMP,
       isIndex: true,
     });
     dataCh = await client.channels.create({
-      name: `data-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.FLOAT32,
       index: timeCh.key,
     });
@@ -118,7 +118,7 @@ describe("WriteFrameAdapter", () => {
 
   it("should correctly adapt a name and JSON value", async () => {
     const jsonChannel = await client.channels.create({
-      name: `json-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.JSON,
       virtual: true,
     });
@@ -134,7 +134,7 @@ describe("WriteFrameAdapter", () => {
 
   it("should correctly adapt a name and a json typed series", async () => {
     const jsonChannel = await client.channels.create({
-      name: `json-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.JSON,
       virtual: true,
     });
@@ -150,7 +150,7 @@ describe("WriteFrameAdapter", () => {
 
   it("should correctly adapt a numeric value to a BigInt keyed by key", async () => {
     const bigIntCh = await client.channels.create({
-      name: `bigint-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.INT64,
       virtual: true,
     });
@@ -176,7 +176,7 @@ describe("WriteFrameAdapter", () => {
 
     it("should return true when adding a new channel", async () => {
       const newCh = await client.channels.create({
-        name: `new-${Math.random()}-${TimeStamp.now().toString()}`,
+        name: id.create(),
         dataType: DataType.FLOAT32,
         index: timeCh.key,
       });
@@ -191,7 +191,7 @@ describe("WriteFrameAdapter", () => {
 
     it("should return true when replacing channels", async () => {
       const newCh = await client.channels.create({
-        name: `replacement-${Math.random()}-${TimeStamp.now().toString()}`,
+        name: id.create(),
         dataType: DataType.FLOAT32,
         index: timeCh.key,
       });
@@ -221,17 +221,17 @@ describe("ReadFrameAdapter", () => {
 
   beforeAll(async () => {
     timeCh = await client.channels.create({
-      name: `read-time-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.TIMESTAMP,
       isIndex: true,
     });
     dataCh = await client.channels.create({
-      name: `read-data-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.FLOAT32,
       index: timeCh.key,
     });
     extraCh = await client.channels.create({
-      name: `read-extra-${Math.random()}-${TimeStamp.now().toString()}`,
+      name: id.create(),
       dataType: DataType.FLOAT64,
       index: timeCh.key,
     });
@@ -471,7 +471,7 @@ describe("ReadFrameAdapter", () => {
     describe("data integrity", () => {
       it("should preserve series values across multiple data types", async () => {
         const int64Ch = await client.channels.create({
-          name: `read-int64-${Math.random()}-${TimeStamp.now().toString()}`,
+          name: id.create(),
           dataType: DataType.INT64,
           index: timeCh.key,
         });
@@ -582,7 +582,7 @@ describe("ReadFrameAdapter", () => {
 
     it("should return true when adding a new channel", async () => {
       const newCh = await client.channels.create({
-        name: `read-new-${Math.random()}-${TimeStamp.now().toString()}`,
+        name: id.create(),
         dataType: DataType.FLOAT32,
         index: timeCh.key,
       });
@@ -597,7 +597,7 @@ describe("ReadFrameAdapter", () => {
 
     it("should return true when replacing channels", async () => {
       const newCh = await client.channels.create({
-        name: `read-replacement-${Math.random()}-${TimeStamp.now().toString()}`,
+        name: id.create(),
         dataType: DataType.FLOAT32,
         index: timeCh.key,
       });

package/src/framer/client.spec.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { TimeSpan, TimeStamp } from "@synnaxlabs/x";
+import { id, TimeSpan, TimeStamp } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 
 import { createTestClient } from "@/testutil/client";
@@ -17,14 +17,13 @@ const client = createTestClient();
 describe("Client", () => {
   describe("read + write", () => {
     it("should correctly write and read a frame of data", async () => {
-      const rand = `${TimeStamp.now().toString()}${Math.random()}`;
       const time = await client.channels.create({
-        name: `time-${rand}`,
+        name: id.create(),
         dataType: "timestamp",
         isIndex: true,
       });
       const data = await client.channels.create({
-        name: `data-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });
@@ -38,14 +37,13 @@ describe("Client", () => {
       expect(Array.from(frame.get(data.key))).toEqual([1]);
     });
     it("should correctly write a single series of data", async () => {
-      const rand = `${TimeStamp.now().toString()}${Math.random()}`;
       const time = await client.channels.create({
-        name: `time-${rand}`,
+        name: id.create(),
         dataType: "timestamp",
         isIndex: true,
       });
       const data = await client.channels.create({
-        name: `data-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });
@@ -62,14 +60,13 @@ describe("Client", () => {
   });
   describe("readLatestN", () => {
     it("should correctly read the latest N samples from a single channel", async () => {
-      const rand = `${TimeStamp.now().toString()}${Math.random()}`;
       const time = await client.channels.create({
-        name: `time-${rand}`,
+        name: id.create(),
         dataType: "timestamp",
         isIndex: true,
       });
       const data = await client.channels.create({
-        name: `data-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });
@@ -94,19 +91,18 @@ describe("Client", () => {
     });
 
     it("should correctly read the latest N samples from multiple channels", async () => {
-      const rand = `${TimeStamp.now().toString()}${Math.random()}`;
       const time = await client.channels.create({
-        name: `time-${rand}`,
+        name: id.create(),
         dataType: "timestamp",
         isIndex: true,
       });
       const data1 = await client.channels.create({
-        name: `data1-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });
       const data2 = await client.channels.create({
-        name: `data2-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });
@@ -142,14 +138,13 @@ describe("Client", () => {
     });
 
     it("should return empty series when no data exists", async () => {
-      const rand = `${TimeStamp.now().toString()}${Math.random()}`;
       const time = await client.channels.create({
-        name: `time-${rand}`,
+        name: id.create(),
         dataType: "timestamp",
         isIndex: true,
       });
       const data = await client.channels.create({
-        name: `data-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });
@@ -159,14 +154,13 @@ describe("Client", () => {
     });
 
     it("should correctly handle N larger than available data", async () => {
-      const rand = `${TimeStamp.now().toString()}${Math.random()}`;
       const time = await client.channels.create({
-        name: `time-${rand}`,
+        name: id.create(),
         dataType: "timestamp",
         isIndex: true,
       });
       const data = await client.channels.create({
-        name: `data-${rand}`,
+        name: id.create(),
         dataType: "float32",
         index: time.key,
       });

package/src/framer/client.ts

@@ -21,19 +21,19 @@ import { channel } from "@/channel";
 import { Deleter } from "@/framer/deleter";
 import { Frame } from "@/framer/frame";
 import { AUTO_SPAN, Iterator, type IteratorConfig } from "@/framer/iterator";
+import { Reader, type ReadRequest } from "@/framer/reader";
 import { openStreamer, type Streamer, type StreamerConfig } from "@/framer/streamer";
 import { Writer, type WriterConfig, WriterMode } from "@/framer/writer";
-import { type ontology } from "@/ontology";
+import { ontology } from "@/ontology";
 
-export const ontologyID = (key: channel.Key): ontology.ID => ({
-  type: "framer",
-  key: key.toString(),
-});
+export const ontologyID = ontology.createIDFactory<string>("framer");
+export const TYPE_ONTOLOGY_ID = ontologyID("");
 
 export class Client {
   private readonly streamClient: WebSocketClient;
   private readonly retriever: channel.Retriever;
   private readonly deleter: Deleter;
+  private readonly reader: Reader;
 
   constructor(
     stream: WebSocketClient,
@@ -43,6 +43,7 @@ export class Client {
     this.streamClient = stream;
     this.retriever = retriever;
     this.deleter = new Deleter(unary);
+    this.reader = new Reader(retriever, stream);
   }
 
   /**
@@ -142,15 +143,15 @@ export class Client {
   }
 
   async read(tr: CrudeTimeRange, channel: channel.KeyOrName): Promise<MultiSeries>;
-
   async read(tr: CrudeTimeRange, channels: channel.Params): Promise<Frame>;
-
+  async read(request: ReadRequest): Promise<ReadableStream<Uint8Array>>;
   async read(
-    tr: CrudeTimeRange,
-    channels: channel.Params,
-  ): Promise<MultiSeries | Frame> {
-    const { single } = channel.analyzeParams(channels);
-    const fr = await this.readFrame(tr, channels);
+    tr: CrudeTimeRange | ReadRequest,
+    channels?: channel.Params,
+  ): Promise<MultiSeries | Frame | ReadableStream<Uint8Array>> {
+    if (!("start" in tr)) return this.reader.read(tr);
+    const { single } = channel.analyzeParams(channels!);
+    const fr = await this.readFrame(tr, channels!);
     if (single) return fr.get(channels as channel.KeyOrName);
     return fr;
   }
@@ -201,13 +202,7 @@ export class Client {
     const { normalized, variant } = channel.analyzeParams(channels);
     const bounds = new TimeRange(timeRange);
     if (variant === "keys")
-      return await this.deleter.delete({
-        keys: normalized as channel.Key[],
-        bounds,
-      });
-    return await this.deleter.delete({
-      names: normalized as string[],
-      bounds,
-    });
+      return await this.deleter.delete({ keys: normalized as channel.Key[], bounds });
+    return await this.deleter.delete({ names: normalized as string[], bounds });
   }
 }

package/src/framer/deleter.spec.ts

@@ -58,7 +58,7 @@ describe("Deleter", () => {
     });
 
     await expect(
-      client.delete(["billy bob", dataCh.name], TimeRange.MAX),
+      client.delete(["nonexistent_channel_name", dataCh.name], TimeRange.MAX),
     ).rejects.toThrow(NotFoundError);
 
     const res = await client.read(TimeRange.MAX, dataCh.key);