@synnaxlabs/client 0.40.0 → 0.42.0

package/src/hardware/rack/client.ts

@@ -13,6 +13,7 @@ import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
+import { framer } from "@/framer";
 import {
   type Key,
   keyZ,
@@ -21,6 +22,8 @@ import {
   ONTOLOGY_TYPE,
   type Payload,
   rackZ,
+  type State,
+  stateZ,
 } from "@/hardware/rack/payload";
 import { type task } from "@/hardware/task";
 import { ontology } from "@/ontology";
@@ -31,12 +34,17 @@ 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";
+
 const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   search: z.string().optional(),
-  offset: z.number().optional(),
+  embedded: z.boolean().optional(),
+  hostIsNode: z.boolean().optional(),
   limit: z.number().optional(),
+  offset: z.number().optional(),
+  includeState: z.boolean().optional(),
 });
 
 const retrieveResZ = z.object({ racks: nullableArrayZ(rackZ) });
@@ -49,14 +57,24 @@ 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;
   private readonly client: UnaryClient;
   private readonly tasks: task.Client;
+  private readonly frameClient: framer.Client;
 
-  constructor(client: UnaryClient, taskClient: task.Client) {
+  constructor(
+    client: UnaryClient,
+    taskClient: task.Client,
+    frameClient: framer.Client,
+  ) {
     this.client = client;
     this.tasks = taskClient;
+    this.frameClient = frameClient;
   }
 
   async delete(keys: Key | Key[]): Promise<void> {
@@ -107,9 +125,12 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     return this.sugar(res.racks);
   }
 
-  async retrieve(key: string | Key): Promise<Rack>;
-  async retrieve(keys: Key[]): Promise<Rack[]>;
-  async retrieve(racks: string | Key | Key[]): Promise<Rack | Rack[]> {
+  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",
@@ -117,7 +138,10 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     const res = await sendRequired<typeof retrieveReqZ, typeof retrieveResZ>(
       this.client,
       RETRIEVE_ENDPOINT,
-      { [variant]: normalized },
+      {
+        [variant]: normalized,
+        includeState: options?.includeState,
+      },
       retrieveReqZ,
       retrieveResZ,
     );
@@ -126,20 +150,36 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     return single ? 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 }) => new Rack(key, name, this.tasks));
+    return payloads.map(
+      ({ key, name, state }) => new Rack(key, name, this.tasks, state),
+    );
   }
 }
 
 export class Rack {
   key: Key;
   name: string;
+  state?: State;
   private readonly tasks: task.Client;
 
-  constructor(key: Key, name: string, taskClient: task.Client) {
+  constructor(key: Key, name: string, taskClient: task.Client, state?: State) {
     this.key = key;
     this.name = name;
     this.tasks = taskClient;
+    this.state = state;
   }
 
   async listTasks(): Promise<task.Task[]> {

package/src/hardware/rack/payload.ts

@@ -8,12 +8,27 @@
 // included in the file licenses/APL.txt.
 
 import { zod } from "@synnaxlabs/x";
+import { TimeStamp } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 export const keyZ = zod.uint32;
 export type Key = z.infer<typeof keyZ>;
 
-export const rackZ = z.object({ key: keyZ, name: z.string() });
+export const stateZ = z.object({
+  key: keyZ,
+  variant: z.string(),
+  message: z.string(),
+  lastReceived: TimeStamp.z.optional(),
+});
+
+export interface State extends z.infer<typeof stateZ> {}
+
+export const rackZ = z.object({
+  key: keyZ,
+  name: z.string(),
+  state: stateZ.optional(),
+});
+
 export interface Payload extends z.infer<typeof rackZ> {}
 
 export const newZ = rackZ.partial({ key: true });

package/src/hardware/rack/rack.spec.ts

@@ -7,6 +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 { TimeStamp } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 import { ZodError } from "zod";
 
@@ -66,4 +67,39 @@ describe("Rack", () => {
       ).rejects.toThrow(NotFoundError);
     });
   });
+  describe("state", () => {
+    it("should include state when includeState is true", async () => {
+      const r = await client.hardware.racks.create({ name: "test" });
+      await expect
+        .poll(async () => {
+          const retrieved = await client.hardware.racks.retrieve(r.key, {
+            includeState: true,
+          });
+          return (
+            retrieved.state !== undefined &&
+            retrieved.state.lastReceived instanceof TimeStamp &&
+            retrieved.state.key === r.key
+          );
+        })
+        .toBeTruthy();
+    });
+    it("should include state for multiple racks", async () => {
+      const r1 = await client.hardware.racks.create({ name: "test1" });
+      const r2 = await client.hardware.racks.create({ name: "test2" });
+
+      await expect
+        .poll(async () => {
+          const retrieved = await client.hardware.racks.retrieve([r1.key, r2.key], {
+            includeState: true,
+          });
+          return retrieved.every(
+            (rack) =>
+              rack.state !== undefined &&
+              rack.state.lastReceived instanceof TimeStamp &&
+              rack.state.key === rack.key,
+          );
+        })
+        .toBeTruthy();
+    });
+  });
 });

package/src/hardware/task/payload.ts

@@ -7,7 +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 { binary, type observe, type UnknownRecord } from "@synnaxlabs/x";
+import {
+  binary,
+  type observe,
+  type UnknownRecord,
+  unknownRecordZ,
+} from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { type Key as RackKey } from "@/hardware/rack/payload";
@@ -28,8 +33,7 @@ export const stateZ = z.object({
   task: keyZ,
   variant: statusZ,
   key: z.string().optional(),
-  details: z
-    .record(z.unknown())
+  details: unknownRecordZ
     .or(z.string().transform(parseWithoutKeyConversion))
     .or(z.array(z.unknown()))
     .or(z.null()) as z.ZodType<UnknownRecord | undefined>,
@@ -44,7 +48,7 @@ export const taskZ = z.object({
   name: z.string(),
   type: z.string(),
   internal: z.boolean().optional(),
-  config: z.record(z.unknown()).or(z.string().transform(decodeJSONString)),
+  config: unknownRecordZ.or(z.string().transform(decodeJSONString)),
   state: stateZ.optional().nullable(),
   snapshot: z.boolean().optional(),
 });
@@ -74,8 +78,7 @@ export const commandZ = z.object({
   task: keyZ,
   type: z.string(),
   key: z.string(),
-  args: z
-    .record(z.unknown())
+  args: unknownRecordZ
     .or(z.string().transform(parseWithoutKeyConversion))
     .or(z.array(z.unknown()))
     .or(z.null())

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

@@ -98,13 +98,16 @@ describe("Task", async () => {
           task: t.key,
           variant: "success",
         };
-        expect(await w.write("sy_task_state", [state])).toBeTruthy();
+        await w.write("sy_task_state", [state]);
         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);
+        await expect
+          .poll(async () => {
+            const retrieved = await client.hardware.tasks.retrieve(t.key, {
+              includeState: true,
+            });
+            return retrieved.state?.variant === state.variant;
+          })
+          .toBeTruthy();
       });
     });
   });

package/src/index.ts

@@ -61,5 +61,3 @@ export {
   type TypedArray,
   type TZInfo,
 } from "@synnaxlabs/x/telem";
-import { control } from "@synnaxlabs/x";
-export const Authority = control.Authority;

package/src/ontology/group/group.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import { QueryError } from "@/errors";
+import { NotFoundError } from "@/errors";
 import { ontology } from "@/ontology";
 import { newClient } from "@/setupspecs";
 
@@ -40,7 +40,7 @@ describe("Group", () => {
       await client.ontology.groups.delete(g.key);
       await expect(
         async () => await client.ontology.retrieve(g.ontologyID),
-      ).rejects.toThrow(QueryError);
+      ).rejects.toThrowError(NotFoundError);
     });
   });
 });

package/src/ontology/payload.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 { type change, type UnknownRecord } from "@synnaxlabs/x";
+import { type change, type UnknownRecord, unknownRecordZ } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import {
@@ -124,7 +124,7 @@ export interface SchemaField extends z.infer<typeof schemaFieldZ> {}
 
 export const schemaZ = z.object({
   type: resourceTypeZ,
-  fields: z.record(schemaFieldZ),
+  fields: z.record(z.string(), schemaFieldZ),
 });
 export interface Schema extends z.infer<typeof schemaZ> {}
 
@@ -133,7 +133,7 @@ export const resourceZ = z
     id: ID.z,
     name: z.string(),
     schema: schemaZ.optional().nullable(),
-    data: z.record(z.unknown()).optional().nullable(),
+    data: unknownRecordZ.optional().nullable(),
   })
   .transform((resource) => ({ key: resource.id.toString(), ...resource }));
 export interface Resource<T extends UnknownRecord = UnknownRecord>

package/src/ranger/client.ts

@@ -17,7 +17,7 @@ import { z } from "zod";
 import { type channel } from "@/channel";
 import { MultipleFoundError, NotFoundError, QueryError } from "@/errors";
 import { type framer } from "@/framer";
-import { type label } from "@/label";
+import { label } from "@/label";
 import { ontology } from "@/ontology";
 import { type Alias, Aliaser } from "@/ranger/alias";
 import { KV } from "@/ranger/kv";
@@ -195,6 +195,7 @@ const retrieveReqZ = z.object({
   overlapsWith: TimeRange.z.optional(),
   limit: z.number().int().optional(),
   offset: z.number().int().optional(),
+  hasLabels: label.keyZ.array().optional(),
 });
 
 export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
@@ -321,7 +322,7 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
       "sy_range_delete",
       (variant, data) => {
         if (variant === "delete")
-          return data.toStrings().map((k) => ({ variant, key: k, value: undefined }));
+          return data.toUUIDs().map((k) => ({ variant, key: k, value: undefined }));
         const sugared = this.sugarMany(data.parseJSON(payloadZ));
         return sugared.map((r) => ({ variant, key: r.key, value: r }));
       },

package/src/ranger/ranger.spec.ts

@@ -8,10 +8,10 @@
 // included in the file licenses/APL.txt.
 
 import { type change } from "@synnaxlabs/x";
-import { DataType, Rate, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
+import { DataType, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, expect, it } from "vitest";
 
-import { QueryError } from "@/errors";
+import { NotFoundError } from "@/errors";
 import { type ranger } from "@/ranger";
 import { newClient } from "@/setupspecs";
 
@@ -74,7 +74,7 @@ describe("Ranger", () => {
       });
       await client.ranges.delete(range.key);
       await expect(async () => await client.ranges.retrieve(range.key)).rejects.toThrow(
-        QueryError,
+        NotFoundError,
       );
     });
   });
@@ -172,7 +172,9 @@ describe("Ranger", () => {
       const val = await rng.kv.get("foo");
       expect(val).toEqual("bar");
       await rng.kv.delete("foo");
-      await expect(async () => await rng.kv.get("foo")).rejects.toThrow(QueryError);
+      await expect(async () => await rng.kv.get("foo")).rejects.toThrowError(
+        NotFoundError,
+      );
     });
 
     it("should set and get multiple keys", async () => {
@@ -240,7 +242,7 @@ describe("Ranger", () => {
         const ch = await client.channels.create({
           name: "My New Channel",
           dataType: DataType.FLOAT32,
-          rate: Rate.hz(1),
+          virtual: true,
         });
         const rng = await client.ranges.create({
           name: "My New One Second Range",
@@ -256,7 +258,7 @@ describe("Ranger", () => {
         const ch = await client.channels.create({
           name: "My New Channel",
           dataType: DataType.FLOAT32,
-          rate: Rate.hz(1),
+          virtual: true,
         });
         const rng = await client.ranges.create({
           name: "My New One Second Range",
@@ -272,7 +274,7 @@ describe("Ranger", () => {
         const ch = await client.channels.create({
           name: "My New Channel",
           dataType: DataType.FLOAT32,
-          rate: Rate.hz(1),
+          virtual: true,
         });
         const rng = await client.ranges.create({
           name: "My New One Second Range",

package/src/testutil/indexedPair.ts

@@ -0,0 +1,40 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { DataType, id } from "@synnaxlabs/x";
+
+import { type channel } from "@/channel";
+import type Synnax from "@/client";
+
+export const newIndexedPair = async (
+  client: Synnax,
+): Promise<[channel.Channel, channel.Channel]> => {
+  const index = await client.channels.create({
+    leaseholder: 1,
+    name: `test-${id.create()}`,
+    dataType: DataType.TIMESTAMP,
+    isIndex: true,
+  });
+  const data = await client.channels.create({
+    leaseholder: 1,
+    name: `test-${id.create()}`,
+    dataType: DataType.FLOAT64,
+    index: index.key,
+  });
+  return [index, data];
+};
+
+export const newVirtualChannel = async (client: Synnax): Promise<channel.Channel> => {
+  const ch = await client.channels.create({
+    name: `test-${id.create()}`,
+    dataType: DataType.FLOAT64,
+    virtual: true,
+  });
+  return ch;
+};

package/src/testutil/telem.ts

@@ -0,0 +1,13 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { TimeStamp } from "@synnaxlabs/x";
+
+export const secondsLinspace = (start: number, n: number): TimeStamp[] =>
+  Array.from({ length: n }, (_, i) => start + i).map((n) => TimeStamp.seconds(n));

package/src/transport.ts

@@ -10,7 +10,6 @@
 import {
   HTTPClient,
   type Middleware,
-  type StreamClient,
   type UnaryClient,
   unaryWithBreaker,
   WebSocketClient,
@@ -24,7 +23,7 @@ const baseAPIEndpoint = "/api/v1/";
 export class Transport {
   readonly url: URL;
   readonly unary: UnaryClient;
-  readonly stream: StreamClient;
+  readonly stream: WebSocketClient;
   readonly secure: boolean;
 
   constructor(url: URL, breakerCfg: breaker.Config = {}, secure: boolean = false) {

package/src/util/decodeJSONString.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 { binary, type UnknownRecord } from "@synnaxlabs/x";
+import { binary, type UnknownRecord, unknownRecordZ } from "@synnaxlabs/x";
 
 export const decodeJSONString = (s: string): UnknownRecord =>
-  s ? binary.JSON_CODEC.decodeString(s) : {};
+  s ? binary.JSON_CODEC.decodeString(s, unknownRecordZ) : {};

package/src/util/retrieve.spec.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 { type Primitive } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
-import { type Primitive } from "zod";
 
 import {
   analyzeParams,