@synnaxlabs/client 0.38.0 → 0.39.0

package/src/framer/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.
@@ -23,10 +23,9 @@ import {
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
-import { type KeyOrName, type KeysOrNames, type Params } from "@/channel/payload";
-import { type Retriever } from "@/channel/retriever";
-import { WriteFrameAdapter } from "@/framer/adapter";
-import { type CrudeFrame, frameZ } from "@/framer/frame";
+import { channel } from "@/channel";
+import { WriteAdapter } from "@/framer/adapter";
+import { type Crude, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
 
 enum Command {
@@ -64,7 +63,7 @@ export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
 const netConfigZ = z.object({
   start: TimeStamp.z.optional(),
   controlSubject: control.subjectZ.optional(),
-  keys: z.number().array().optional(),
+  keys: channel.keyZ.array().optional(),
   authorities: control.Authority.z.array().optional(),
   mode: z.nativeEnum(WriterMode).optional(),
   errOnUnauthorized: z.boolean().optional(),
@@ -72,7 +71,7 @@ const netConfigZ = z.object({
   autoIndexPersistInterval: TimeSpan.z.optional(),
 });
 
-type Config = z.infer<typeof netConfigZ>;
+interface Config extends z.infer<typeof netConfigZ> {}
 
 const reqZ = z.object({
   command: z.nativeEnum(Command),
@@ -80,7 +79,7 @@ const reqZ = z.object({
   frame: frameZ.optional(),
 });
 
-type Request = z.infer<typeof reqZ>;
+interface Request extends z.infer<typeof reqZ> {}
 
 const resZ = z.object({
   ack: z.boolean(),
@@ -88,11 +87,11 @@ const resZ = z.object({
   error: errorZ.optional().nullable(),
 });
 
-type Response = z.infer<typeof resZ>;
+interface Response extends z.infer<typeof resZ> {}
 
 export interface WriterConfig {
   // channels denote the channels to write to.
-  channels: Params;
+  channels: channel.Params;
   // start sets the starting timestamp for the first sample in the writer.
   start?: CrudeTimeStamp;
   // controlSubject sets the control subject of the writer.
@@ -158,23 +157,21 @@ export interface WriterConfig {
 export class Writer {
   private static readonly ENDPOINT = "/frame/write";
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
-  private readonly adapter: WriteFrameAdapter;
+  private readonly adapter: WriteAdapter;
+  private errAccumulated: boolean = false;
 
-  private constructor(
-    stream: Stream<typeof reqZ, typeof resZ>,
-    adapter: WriteFrameAdapter,
-  ) {
+  private constructor(stream: Stream<typeof reqZ, typeof resZ>, adapter: WriteAdapter) {
     this.stream = new StreamProxy("Writer", stream);
     this.adapter = adapter;
   }
 
   static async _open(
-    retriever: Retriever,
+    retriever: channel.Retriever,
     client: StreamClient,
     {
       channels,
       start = TimeStamp.now(),
-      authorities = control.Authority.Absolute,
+      authorities = control.Authority.ABSOLUTE,
       controlSubject: subject,
       mode = WriterMode.PersistStream,
       errOnUnauthorized = false,
@@ -182,7 +179,7 @@ export class Writer {
       autoIndexPersistInterval = TimeSpan.SECOND,
     }: WriterConfig,
   ): Promise<Writer> {
-    const adapter = await WriteFrameAdapter.open(retriever, channels);
+    const adapter = await WriteAdapter.open(retriever, channels);
     const stream = await client.stream(Writer.ENDPOINT, reqZ, resZ);
     const writer = new Writer(stream, adapter);
     await writer.execute({
@@ -201,14 +198,19 @@ export class Writer {
     return writer;
   }
 
-  async write(channel: KeyOrName, data: CrudeSeries): Promise<boolean>;
-
-  async write(channel: KeysOrNames, data: CrudeSeries[]): Promise<boolean>;
-
-  async write(frame: CrudeFrame | Record<KeyOrName, CrudeSeries>): Promise<boolean>;
+  private async checkForAccumulatedError(): Promise<boolean> {
+    if (!this.errAccumulated && this.stream.received()) {
+      this.errAccumulated = true;
+      while (this.stream.received()) await this.stream.receive();
+    }
+    return this.errAccumulated;
+  }
 
+  async write(channel: channel.KeyOrName, data: CrudeSeries): Promise<boolean>;
+  async write(channel: channel.KeysOrNames, data: CrudeSeries[]): Promise<boolean>;
+  async write(frame: Crude | Record<channel.KeyOrName, CrudeSeries>): Promise<boolean>;
   async write(
-    channelsOrData: Params | Record<KeyOrName, CrudeSeries> | CrudeFrame,
+    channelsOrData: channel.Params | Record<channel.KeyOrName, CrudeSeries> | Crude,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<boolean>;
 
@@ -227,9 +229,10 @@ export class Writer {
    * should acknowledge the error by calling the error method or closing the writer.
    */
   async write(
-    channelsOrData: Params | Record<KeyOrName, CrudeSeries> | CrudeFrame,
+    channelsOrData: channel.Params | Record<channel.KeyOrName, CrudeSeries> | Crude,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<boolean> {
+    if (await this.checkForAccumulatedError()) return false;
     const frame = await this.adapter.adapt(channelsOrData, series);
     this.stream.send({ command: Command.Write, frame: frame.toPayload() });
     return true;
@@ -237,21 +240,27 @@ export class Writer {
 
   async setAuthority(value: number): Promise<boolean>;
 
-  async setAuthority(key: KeyOrName, authority: control.Authority): Promise<boolean>;
+  async setAuthority(
+    key: channel.KeyOrName,
+    authority: control.Authority,
+  ): Promise<boolean>;
 
-  async setAuthority(value: Record<KeyOrName, control.Authority>): Promise<boolean>;
+  async setAuthority(
+    value: Record<channel.KeyOrName, control.Authority>,
+  ): Promise<boolean>;
 
   async setAuthority(
-    value: Record<KeyOrName, control.Authority> | KeyOrName | number,
+    value: Record<channel.KeyOrName, control.Authority> | channel.KeyOrName | number,
     authority?: control.Authority,
   ): Promise<boolean> {
+    if (await this.checkForAccumulatedError()) return false;
     let config: Config;
     if (typeof value === "number" && authority == null)
       config = { keys: [], authorities: [value] };
     else {
-      let oValue: Record<KeyOrName, control.Authority>;
+      let oValue: Record<channel.KeyOrName, control.Authority>;
       if (typeof value === "string" || typeof value === "number")
-        oValue = { [value]: authority } as Record<KeyOrName, control.Authority>;
+        oValue = { [value]: authority } as Record<channel.KeyOrName, control.Authority>;
       else oValue = value;
       oValue = await this.adapter.adaptObjectKeys(oValue);
       config = {
@@ -272,7 +281,7 @@ export class Writer {
    * After the caller acknowledges the error, they can attempt to commit again.
    */
   async commit(): Promise<boolean> {
-    if (this.errorAccumulated) return false;
+    if (await this.checkForAccumulatedError()) return false;
     const res = await this.execute({ command: Command.Commit });
     return res.ack;
   }
@@ -282,7 +291,6 @@ export class Writer {
    * state, allowing the writer to be used again.
    */
   async error(): Promise<Error | null> {
-    this.stream.send({ command: Command.Error });
     const res = await this.execute({ command: Command.Error });
     return res.error != null ? decodeError(res.error) : null;
   }

package/src/hardware/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.

package/src/hardware/device/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.
@@ -15,28 +15,30 @@ import { z } from "zod";
 import { type framer } from "@/framer";
 import {
   type Device,
-  type DeviceKey,
-  deviceKeyZ,
   deviceZ,
-  type NewDevice,
-  newDeviceZ,
+  type Key,
+  keyZ,
+  type New,
+  newZ,
+  ONTOLOGY_TYPE,
 } from "@/hardware/device/payload";
+import { ontology } from "@/ontology";
 import { signals } from "@/signals";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
 
-const DEVICE_SET_NAME = "sy_device_set";
-const DEVICE_DELETE_NAME = "sy_device_delete";
+const SET_CHANNEL_NAME = "sy_device_set";
+const DELETE_CHANNEL_NAME = "sy_device_delete";
 
 const RETRIEVE_ENDPOINT = "/hardware/device/retrieve";
 const CREATE_ENDPOINT = "/hardware/device/create";
 const DELETE_ENDPOINT = "/hardware/device/delete";
 
-const createReqZ = z.object({ devices: newDeviceZ.array() });
+const createReqZ = z.object({ devices: newZ.array() });
 
 const createResZ = z.object({ devices: deviceZ.array() });
 
-const deleteReqZ = z.object({ keys: deviceKeyZ.array() });
+const deleteReqZ = z.object({ keys: keyZ.array() });
 
 const deleteResZ = z.object({});
 
@@ -44,21 +46,22 @@ const retrieveReqZ = z.object({
   search: z.string().optional(),
   limit: z.number().optional(),
   offset: z.number().optional(),
-  keys: deviceKeyZ.array().optional(),
+  keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   makes: z.string().array().optional(),
 });
 
-type RetrieveRequest = z.input<typeof retrieveReqZ>;
+interface RetrieveRequest extends z.input<typeof retrieveReqZ> {}
 
-export type RetrieveOptions = Pick<RetrieveRequest, "limit" | "offset" | "makes">;
+export interface RetrieveOptions
+  extends Pick<RetrieveRequest, "limit" | "offset" | "makes"> {}
 
-type PageOptions = Pick<RetrieveOptions, "makes">;
+interface PageOptions extends Pick<RetrieveOptions, "makes"> {}
 
 const retrieveResZ = z.object({ devices: nullableArrayZ(deviceZ) });
 
-export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
-  readonly type = "device";
+export class Client implements AsyncTermSearcher<string, Key, Device> {
+  readonly type = ONTOLOGY_TYPE;
   private readonly client: UnaryClient;
   private readonly frameClient: framer.Client;
 
@@ -67,20 +70,29 @@ export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
     this.frameClient = frameClient;
   }
 
-  async retrieve<P extends UnknownRecord = UnknownRecord>(
-    key: string,
-    options?: RetrieveOptions,
-  ): Promise<Device<P>>;
-
-  async retrieve<P extends UnknownRecord = UnknownRecord>(
+  async retrieve<
+    Properties extends UnknownRecord = UnknownRecord,
+    Make extends string = string,
+    Model extends string = string,
+  >(key: string, options?: RetrieveOptions): Promise<Device<Properties, Make, Model>>;
+
+  async retrieve<
+    Properties extends UnknownRecord = UnknownRecord,
+    Make extends string = string,
+    Model extends string = string,
+  >(
     keys: string[],
     options?: RetrieveOptions,
-  ): Promise<Array<Device<P>>>;
+  ): Promise<Array<Device<Properties, Make, Model>>>;
 
-  async retrieve<P extends UnknownRecord = UnknownRecord>(
+  async retrieve<
+    Properties extends UnknownRecord = UnknownRecord,
+    Make extends string = string,
+    Model extends string = string,
+  >(
     keys: string | string[],
     options?: RetrieveOptions,
-  ): Promise<Device<P> | Array<Device<P>>> {
+  ): Promise<Device<Properties, Make, Model> | Array<Device<Properties, Make, Model>>> {
     const isSingle = !Array.isArray(keys);
     const res = await sendRequired(
       this.client,
@@ -90,7 +102,9 @@ export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
       retrieveResZ,
     );
     checkForMultipleOrNoResults("Device", keys, res.devices, isSingle);
-    return (isSingle ? res.devices[0] : res.devices) as Device<P> | Array<Device<P>>;
+    return isSingle
+      ? (res.devices[0] as Device<Properties, Make, Model>)
+      : (res.devices as Array<Device<Properties, Make, Model>>);
   }
 
   async search(term: string, options?: RetrieveOptions): Promise<Device[]> {
@@ -117,17 +131,23 @@ export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
     ).devices;
   }
 
-  async create<P extends UnknownRecord = UnknownRecord>(
-    device: NewDevice<P>,
-  ): Promise<Device<P>>;
-
-  async create<P extends UnknownRecord = UnknownRecord>(
-    devices: NewDevice<P>[],
-  ): Promise<Device<P>[]>;
-
-  async create<P extends UnknownRecord = UnknownRecord>(
-    devices: NewDevice<P> | NewDevice<P>[],
-  ): Promise<Device<P> | Device<P>[]> {
+  async create<
+    Properties extends UnknownRecord = UnknownRecord,
+    Make extends string = string,
+    Model extends string = string,
+  >(device: New<Properties, Make>): Promise<Device<Properties, Make, Model>>;
+  async create<
+    Properties extends UnknownRecord = UnknownRecord,
+    Make extends string = string,
+    Model extends string = string,
+  >(devices: New<Properties, Make>[]): Promise<Device<Properties, Make, Model>[]>;
+  async create<
+    Properties extends UnknownRecord = UnknownRecord,
+    Make extends string = string,
+    Model extends string = string,
+  >(
+    devices: New<Properties, Make> | New<Properties, Make>[],
+  ): Promise<Device<Properties, Make, Model> | Device<Properties, Make, Model>[]> {
     const isSingle = !Array.isArray(devices);
     const res = await sendRequired(
       this.client,
@@ -136,7 +156,9 @@ export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
       createReqZ,
       createResZ,
     );
-    return isSingle ? (res.devices[0] as Device<P>) : (res.devices as Device<P>[]);
+    return isSingle
+      ? (res.devices[0] as Device<Properties, Make, Model>)
+      : (res.devices as Device<Properties, Make, Model>[]);
   }
 
   async delete(keys: string | string[]): Promise<void> {
@@ -152,15 +174,15 @@ export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
   async openDeviceTracker(): Promise<signals.Observable<string, Device>> {
     return await signals.openObservable<string, Device>(
       this.frameClient,
-      DEVICE_SET_NAME,
-      DEVICE_DELETE_NAME,
+      SET_CHANNEL_NAME,
+      DELETE_CHANNEL_NAME,
       decodeDeviceChanges,
     );
   }
 
   newSearcherWithOptions(
     options: RetrieveOptions,
-  ): AsyncTermSearcher<string, DeviceKey, Device> {
+  ): AsyncTermSearcher<string, Key, Device> {
     return {
       type: this.type,
       search: async (term: string) => await this.search(term, options),
@@ -176,3 +198,6 @@ const decodeDeviceChanges: signals.Decoder<string, Device> = (variant, data) =>
     return data.toStrings().map((k) => ({ variant, key: k, value: undefined }));
   return data.parseJSON(deviceZ).map((d) => ({ variant, key: d.key, value: d }));
 };
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: ONTOLOGY_TYPE, key });

package/src/hardware/device/device.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.
@@ -13,42 +13,58 @@ import { newClient } from "@/setupspecs";
 
 const client = newClient();
 
-describe("Device", () => {
-  describe("Device", () => {
-    describe("create", () => {
-      it("should create a device on a rack", async () => {
-        const rack = await client.hardware.racks.create({ name: "test" });
-        const d = await client.hardware.devices.create({
-          rack: rack.key,
-          location: "Dev1",
-          key: "SN222",
-          name: "test",
-          make: "ni",
-          model: "dog",
-          properties: { cat: "dog" },
-        });
-        expect(d.key).toEqual("SN222");
-        expect(d.name).toBe("test");
-        expect(d.make).toBe("ni");
+describe("Device", async () => {
+  const testRack = await client.hardware.racks.create({ name: "test" });
+  describe("create", () => {
+    it("should create a device on a rack", async () => {
+      const d = await client.hardware.devices.create({
+        rack: testRack.key,
+        location: "Dev1",
+        key: "SN222",
+        name: "test",
+        make: "ni",
+        model: "dog",
+        properties: { cat: "dog" },
       });
+      expect(d.key).toEqual("SN222");
+      expect(d.name).toBe("test");
+      expect(d.make).toBe("ni");
     });
-    describe("retrieve", () => {
-      it("should retrieve a device by its key", async () => {
-        const rack = await client.hardware.racks.create({ name: "test" });
-        const d = await client.hardware.devices.create({
-          key: "SN222",
-          rack: rack.key,
-          location: "Dev1",
-          name: "test",
-          make: "ni",
-          model: "dog",
-          properties: { cat: "dog" },
-        });
-        const retrieved = await client.hardware.devices.retrieve(d.key);
-        expect(retrieved.key).toBe(d.key);
-        expect(retrieved.name).toBe("test");
-        expect(retrieved.make).toBe("ni");
+  });
+  it("should properly encode and decode properties", async () => {
+    const properties = {
+      rate: 10,
+      stateIndexChannel: 234,
+      inputChannels: { port1: 34214 },
+      outputChannels: [{ port2: 232 }],
+    };
+    const d = await client.hardware.devices.create({
+      key: "SN222",
+      rack: testRack.key,
+      location: "Dev1",
+      name: "test",
+      make: "ni",
+      model: "dog",
+      properties,
+    });
+    const retrieved = await client.hardware.devices.retrieve(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({
+        key: "SN222",
+        rack: testRack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "dog",
+        properties: { cat: "dog" },
       });
+      const retrieved = await client.hardware.devices.retrieve(d.key);
+      expect(retrieved.key).toBe(d.key);
+      expect(retrieved.name).toBe("test");
+      expect(retrieved.make).toBe("ni");
     });
   });
 });

package/src/hardware/device/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/hardware/device/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/hardware/device/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,44 +10,44 @@
 import { binary, type UnknownRecord } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { rackKeyZ } from "@/hardware/rack/payload";
-import { ontology } from "@/ontology";
+import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
+import { decodeJSONString } from "@/util/decodeJSONString";
 
-export const deviceKeyZ = z.string();
+export const keyZ = z.string();
+export type Key = z.infer<typeof keyZ>;
 
 export const deviceZ = z.object({
-  key: deviceKeyZ,
+  key: keyZ,
   rack: rackKeyZ,
   name: z.string(),
   make: z.string(),
   model: z.string(),
   location: z.string(),
   configured: z.boolean().optional(),
-  properties: z.record(z.unknown()).or(
-    z.string().transform((c) => {
-      if (c === "") return {};
-      return binary.JSON_CODEC.decodeString(c);
-    }),
-  ) as z.ZodType<UnknownRecord>,
+  properties: z.record(z.unknown()).or(z.string().transform(decodeJSONString)),
 });
-
-export type Device<P extends UnknownRecord = UnknownRecord> = Omit<
-  z.output<typeof deviceZ>,
-  "properties"
-> & { properties: P };
-
-export type DeviceKey = z.infer<typeof deviceKeyZ>;
-
-export const newDeviceZ = deviceZ.extend({
+export interface Device<
+  Properties extends UnknownRecord = UnknownRecord,
+  Make extends string = string,
+  Model extends string = string,
+> extends Omit<z.output<typeof deviceZ>, "properties"> {
+  properties: Properties;
+  make: Make;
+  model: Model;
+}
+
+export const newZ = deviceZ.extend({
   properties: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
 });
-
-export type NewDevice<P extends UnknownRecord = UnknownRecord> = Omit<
-  z.input<typeof newDeviceZ>,
-  "properties"
-> & { properties: P };
-
-export const ONTOLOGY_TYPE: ontology.ResourceType = "device";
-
-export const ontologyID = (key: DeviceKey): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key: key.toString() });
+export interface New<
+  Properties extends UnknownRecord = UnknownRecord,
+  Make extends string = string,
+  Model extends string = string,
+> extends Omit<z.input<typeof newZ>, "properties"> {
+  properties: Properties;
+  make: Make;
+  model: Model;
+}
+
+export const ONTOLOGY_TYPE = "device";
+export type OntologyType = typeof ONTOLOGY_TYPE;

package/src/hardware/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/hardware/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.