@synnaxlabs/client 0.49.2 → 0.50.0

package/src/task/payload.spec.ts

@@ -0,0 +1,113 @@
+// 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 { newKey, rackKey } from "@/task/payload";
+
+describe("newKey", () => {
+  describe("basic key generation", () => {
+    // Verifies that newKey correctly combines rack and task keys via bit shifting.
+    // The rack key occupies the upper 32 bits, task key the lower 32.
+    const cases = [
+      { rackKey: 1, taskKey: 1, expected: ((1n << 32n) + 1n).toString() },
+      { rackKey: 1, taskKey: 0, expected: (1n << 32n).toString() },
+      { rackKey: 0, taskKey: 1, expected: "1" },
+      { rackKey: 0, taskKey: 0, expected: "0" },
+      { rackKey: 255, taskKey: 65535, expected: ((255n << 32n) + 65535n).toString() },
+    ];
+    cases.forEach(({ rackKey: r, taskKey: t, expected }) => {
+      it(`should combine rackKey=${r} and taskKey=${t}`, () => {
+        expect(newKey(r, t)).toBe(expected);
+      });
+    });
+  });
+
+  describe("default taskKey", () => {
+    // Verifies that omitting taskKey defaults to 0, producing rackKey << 32.
+    const rackKeys = [0, 1, 42, 1000];
+    rackKeys.forEach((r) => {
+      it(`should default taskKey to 0 for rackKey=${r}`, () => {
+        expect(newKey(r)).toBe(newKey(r, 0));
+      });
+    });
+  });
+
+  describe("roundtrip with rackKey", () => {
+    // Verifies that rackKey correctly extracts the rack portion from a combined key.
+    // This ensures newKey and rackKey are inverse operations for the rack component.
+    const cases = [
+      { rack: 1, task: 1 },
+      { rack: 1, task: 0 },
+      { rack: 0, task: 1 },
+      { rack: 100, task: 50000 },
+      { rack: 2147483647, task: 2147483647 }, // max 32-bit signed integers
+    ];
+    cases.forEach(({ rack, task }) => {
+      it(`should extract rack=${rack} from key generated with task=${task}`, () => {
+        const key = newKey(rack, task);
+        expect(rackKey(key)).toBe(rack);
+      });
+    });
+  });
+
+  describe("edge cases", () => {
+    // Verifies behavior at boundary values to ensure no overflow or precision issues.
+    it("should handle max 32-bit unsigned rack key", () => {
+      const maxUint32 = 0xffffffff;
+      const key = newKey(maxUint32, 0);
+      expect(rackKey(key)).toBe(maxUint32);
+    });
+
+    it("should handle max 32-bit unsigned task key", () => {
+      const maxUint32 = 0xffffffff;
+      const key = newKey(1, maxUint32);
+      expect(key).toBe(((1n << 32n) + BigInt(maxUint32)).toString());
+    });
+
+    it("should handle both max 32-bit values", () => {
+      const maxUint32 = 0xffffffff;
+      const key = newKey(maxUint32, maxUint32);
+      const expected = ((BigInt(maxUint32) << 32n) + BigInt(maxUint32)).toString();
+      expect(key).toBe(expected);
+      expect(rackKey(key)).toBe(maxUint32);
+    });
+  });
+});
+
+describe("rackKey", () => {
+  // Verifies rackKey extracts upper 32 bits from various key formats.
+  // Keys can be string, bigint, or number per keyZ schema.
+  describe("key format handling", () => {
+    const rack = 42;
+    const task = 100;
+    const expectedKey = newKey(rack, task);
+
+    it("should extract rack from string key", () => {
+      expect(rackKey(expectedKey)).toBe(rack);
+    });
+
+    it("should extract rack from numeric string", () => {
+      const numericKey = ((42n << 32n) + 100n).toString();
+      expect(rackKey(numericKey)).toBe(42);
+    });
+  });
+
+  describe("zero handling", () => {
+    // Verifies correct behavior when rack or task portions are zero.
+    it("should return 0 for key with zero rack", () => {
+      expect(rackKey("100")).toBe(0);
+    });
+
+    it("should return rack when task portion is zero", () => {
+      const key = newKey(5, 0);
+      expect(rackKey(key)).toBe(5);
+    });
+  });
+});

package/src/task/payload.ts

@@ -1,4 +1,4 @@
-// Copyright 2025 Synnax Labs, Inc.
+// Copyright 2026 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -46,8 +46,9 @@ const newStatusDetailsZ = <DataSchema extends z.ZodType>(data: DataSchema) =>
 export const newStatusZ = <DataSchema extends z.ZodType>(data: DataSchema) =>
   status.statusZ(newStatusDetailsZ(data)).partial({ key: true, name: true });
 
-export interface NewStatus<DataSchema extends z.ZodType = z.ZodUnknown>
-  extends z.infer<ReturnType<typeof newStatusZ<DataSchema>>> {}
+export interface NewStatus<DataSchema extends z.ZodType = z.ZodUnknown> extends z.infer<
+  ReturnType<typeof newStatusZ<DataSchema>>
+> {}
 
 export const taskZ = <
   Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
@@ -138,9 +139,13 @@ export interface Command extends Omit<z.infer<typeof commandZ>, "args"> {
   args?: record.Unknown;
 }
 
-export interface StateObservable<StatusData extends z.ZodType>
-  extends observe.ObservableAsyncCloseable<Status<StatusData>> {}
+export interface StateObservable<
+  StatusData extends z.ZodType,
+> extends observe.ObservableAsyncCloseable<Status<StatusData>> {}
 
 export interface CommandObservable extends observe.ObservableAsyncCloseable<Command> {}
 
 export const rackKey = (key: Key): RackKey => Number(BigInt(key) >> 32n);
+
+export const newKey = (rackKey: RackKey, taskKey: number = 0): Key =>
+  ((BigInt(rackKey) << 32n) + BigInt(taskKey)).toString();

package/src/task/task.spec.ts

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

package/src/testutil/access.ts

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

package/src/testutil/channels.ts

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

package/src/testutil/client.ts

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

package/src/testutil/telem.ts

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

package/src/transport.ts

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

package/src/user/access.spec.ts

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

package/src/user/client.ts

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

package/src/user/external.ts

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

package/src/user/index.ts

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

package/src/user/payload.ts

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

package/src/user/user.spec.ts

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

package/src/util/decodeJSONString.ts

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

package/src/util/parseWithoutKeyConversion.ts

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

package/src/util/retrieve.spec.ts

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

package/src/util/retrieve.ts

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

package/src/util/telem.ts

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

package/src/view/client.ts

@@ -0,0 +1,96 @@
+// 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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { array } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type ontology } from "@/ontology";
+import { checkForMultipleOrNoResults } from "@/util/retrieve";
+import { type Key, keyZ, type New, newZ, type View, viewZ } from "@/view/payload";
+
+export const SET_CHANNEL_NAME = "sy_view_set";
+export const DELETE_CHANNEL_NAME = "sy_view_delete";
+
+const createReqZ = z.object({ views: newZ.array() });
+const createResZ = z.object({ views: viewZ.array() });
+const deleteReqZ = z.object({ keys: keyZ.array() });
+const emptyResZ = z.object({});
+
+const retrieveRequestZ = z.object({
+  keys: keyZ.array().optional(),
+  types: z.string().array().optional(),
+  searchTerm: z.string().optional(),
+  offset: z.number().optional(),
+  limit: z.number().optional(),
+});
+
+const singleRetrieveArgsZ = z
+  .object({ key: keyZ })
+  .transform(({ key }) => ({ keys: [key] }));
+
+const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveRequestZ]);
+
+export interface RetrieveSingleParams extends z.input<typeof singleRetrieveArgsZ> {}
+export interface RetrieveMultipleParams extends z.input<typeof retrieveRequestZ> {}
+
+const retrieveResponseZ = z.object({ views: array.nullableZ(viewZ) });
+
+export class Client {
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async retrieve(args: RetrieveSingleParams): Promise<View>;
+  async retrieve(args: RetrieveMultipleParams): Promise<View[]>;
+  async retrieve(
+    args: RetrieveSingleParams | RetrieveMultipleParams,
+  ): Promise<View | View[]> {
+    const isSingle = "key" in args;
+    const res = await sendRequired(
+      this.client,
+      "/view/retrieve",
+      args,
+      retrieveArgsZ,
+      retrieveResponseZ,
+    );
+    checkForMultipleOrNoResults("View", args, res.views, isSingle);
+    return isSingle ? res.views[0] : res.views;
+  }
+
+  async create(view: New): Promise<View>;
+  async create(views: New[]): Promise<View[]>;
+  async create(views: New | New[]): Promise<View | View[]> {
+    const isMany = Array.isArray(views);
+    const res = await sendRequired<typeof createReqZ, typeof createResZ>(
+      this.client,
+      "/view/create",
+      { views: array.toArray(views) },
+      createReqZ,
+      createResZ,
+    );
+    return isMany ? res.views : res.views[0];
+  }
+
+  async delete(keys: Key | Key[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof emptyResZ>(
+      this.client,
+      "/view/delete",
+      { keys: array.toArray(keys) },
+      deleteReqZ,
+      emptyResZ,
+    );
+  }
+}
+
+export const ontologyID = (key: Key): ontology.ID => ({ type: "view", key });
+
+export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/view/external.ts

@@ -0,0 +1,11 @@
+// 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.
+
+export * from "@/view/client";
+export * from "@/view/payload";

package/src/view/index.ts

@@ -0,0 +1,10 @@
+// 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.
+
+export * as view from "@/view/external";

package/src/view/payload.ts

@@ -0,0 +1,25 @@
+// 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 { record } from "@synnaxlabs/x";
+import z from "zod";
+
+export const keyZ = z.uuid();
+export type Key = z.infer<typeof keyZ>;
+
+export const viewZ = z.object({
+  key: keyZ,
+  name: z.string(),
+  type: z.string(),
+  query: record.unknownZ,
+});
+export interface View extends z.infer<typeof viewZ> {}
+
+export const newZ = viewZ.extend({ key: keyZ.optional() });
+export interface New extends z.infer<typeof newZ> {}

package/src/view/view.spec.ts

@@ -0,0 +1,161 @@
+// 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 { id } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { NotFoundError } from "@/errors";
+import { createTestClient } from "@/testutil/client";
+
+describe("View", () => {
+  describe("create", () => {
+    it("should create a single view", async () => {
+      const client = createTestClient();
+      const v = await client.views.create({
+        name: "Test View",
+        type: "lineplot",
+        query: { channels: ["test-1", "test-2"] },
+      });
+      expect(v.name).toEqual("Test View");
+      expect(v.type).toEqual("lineplot");
+      expect(v.key).toBeDefined();
+    });
+
+    it("should create multiple views", async () => {
+      const client = createTestClient();
+      const views = await client.views.create([
+        {
+          name: "View 1",
+          type: "table",
+          query: { channels: ["ch-1"] },
+        },
+        {
+          name: "View 2",
+          type: "lineplot",
+          query: { channels: ["ch-2"] },
+        },
+      ]);
+      expect(views).toHaveLength(2);
+      expect(views[0].name).toEqual("View 1");
+      expect(views[0].query).toEqual({ channels: ["ch-1"] });
+      expect(views[1].name).toEqual("View 2");
+      expect(views[1].query).toEqual({ channels: ["ch-2"] });
+    });
+  });
+
+  describe("retrieve", () => {
+    it("should retrieve a view by key", async () => {
+      const client = createTestClient();
+      const created = await client.views.create({
+        name: "Retrieve Test",
+        type: "table",
+        query: { channels: ["test"] },
+      });
+      const retrieved = await client.views.retrieve({ key: created.key });
+      expect(retrieved.key).toEqual(created.key);
+      expect(retrieved.name).toEqual("Retrieve Test");
+      expect(retrieved.query).toEqual({ channels: ["test"] });
+    });
+
+    it("should retrieve multiple views", async () => {
+      const client = createTestClient();
+      const created = await client.views.create([
+        {
+          name: "Multi 1",
+          type: "table",
+          query: { channels: ["ch-1"] },
+        },
+        {
+          name: "Multi 2",
+          type: "lineplot",
+          query: { channels: ["ch-2"] },
+        },
+      ]);
+      const keys = created.map((v) => v.key);
+      const retrieved = await client.views.retrieve({ keys });
+      expect(retrieved).toHaveLength(2);
+      expect(retrieved[0].name).toEqual("Multi 1");
+      expect(retrieved[0].query).toEqual({ channels: ["ch-1"] });
+      expect(retrieved[1].name).toEqual("Multi 2");
+      expect(retrieved[1].query).toEqual({ channels: ["ch-2"] });
+    });
+
+    it("should retrieve views by type", async () => {
+      const client = createTestClient();
+      const type = id.create();
+      await client.views.create([
+        {
+          name: "Type 1",
+          type,
+          query: { channels: ["ch-1"] },
+        },
+        {
+          name: "Type 2",
+          type,
+          query: { channels: ["ch-2"] },
+        },
+      ]);
+      const retrieved = await client.views.retrieve({ types: [type] });
+      expect(retrieved).toHaveLength(2);
+      retrieved.forEach((v) => expect(v.type).toEqual(type));
+      retrieved.sort((a, b) => a.name.localeCompare(b.name));
+      expect(retrieved[0].name).toEqual("Type 1");
+      expect(retrieved[0].query).toEqual({ channels: ["ch-1"] });
+      expect(retrieved[1].name).toEqual("Type 2");
+      expect(retrieved[1].query).toEqual({ channels: ["ch-2"] });
+    });
+
+    it("should search for views by name", async () => {
+      const client = createTestClient();
+      await client.views.create({
+        name: "Searchable View",
+        type: "lineplot",
+        query: { channels: ["search"] },
+      });
+      const results = await client.views.retrieve({ searchTerm: "Searchable" });
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].name).toContain("Searchable");
+      expect(results[0].query).toEqual({ channels: ["search"] });
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete a single view", async () => {
+      const client = createTestClient();
+      const v = await client.views.create({
+        name: "To Delete",
+        type: "table",
+        query: { channels: ["delete"] },
+      });
+      await client.views.delete(v.key);
+      await expect(client.views.retrieve({ key: v.key })).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+
+    it("should delete multiple views", async () => {
+      const client = createTestClient();
+      const views = await client.views.create([
+        {
+          name: "Delete 1",
+          type: "table",
+          query: { channels: ["d1"] },
+        },
+        {
+          name: "Delete 2",
+          type: "lineplot",
+          query: { channels: ["d2"] },
+        },
+      ]);
+      const keys = views.map((v) => v.key);
+      await client.views.delete(keys);
+      await expect(client.views.retrieve({ keys })).rejects.toThrow(NotFoundError);
+    });
+  });
+});

package/src/vite-env.d.ts

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

package/src/workspace/access.spec.ts

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

package/src/workspace/client.ts

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

package/src/workspace/external.ts

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

package/src/workspace/index.ts

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

package/src/workspace/lineplot/access.spec.ts

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

package/src/workspace/lineplot/client.ts

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

package/src/workspace/lineplot/external.ts

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

package/src/workspace/lineplot/index.ts

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

package/src/workspace/lineplot/lineplot.spec.ts

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

package/src/workspace/lineplot/payload.ts

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