@synnaxlabs/client 0.44.4 → 0.45.1

package/src/workspace/schematic/symbol/client.spec.ts

@@ -0,0 +1,133 @@
+// 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 { beforeAll, describe, expect, it } from "vitest";
+
+import { ontology } from "@/ontology";
+import { type group } from "@/ontology/group";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("Symbol Client", () => {
+  let group: group.Group;
+  beforeAll(async () => {
+    group = await client.ontology.groups.create(ontology.ROOT_ID, "Test Symbols");
+  });
+  describe("create", () => {
+    it("should create a single symbol", async () => {
+      const symbol = await client.workspaces.schematic.symbols.create({
+        name: "Test Symbol",
+        data: {
+          svg: "<svg></svg>",
+          states: [],
+          handles: [],
+          variant: "sensor",
+        },
+        parent: group.ontologyID,
+      });
+      expect(symbol.name).toBe("Test Symbol");
+      expect(symbol.key).toBeDefined();
+    });
+
+    it("should create multiple symbols", async () => {
+      const symbols = await client.workspaces.schematic.symbols.create({
+        symbols: [
+          {
+            name: "Symbol 1",
+            data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+          },
+          {
+            name: "Symbol 2",
+            data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+          },
+        ],
+        parent: group.ontologyID,
+      });
+      expect(symbols).toHaveLength(2);
+      expect(symbols[0].name).toBe("Symbol 1");
+      expect(symbols[1].name).toBe("Symbol 2");
+    });
+  });
+
+  describe("retrieve", () => {
+    it("should retrieve a single symbol by key", async () => {
+      const created = await client.workspaces.schematic.symbols.create({
+        name: "Retrieve Test",
+        data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+        parent: group.ontologyID,
+      });
+
+      const retrieved = await client.workspaces.schematic.symbols.retrieve({
+        key: created.key,
+      });
+      expect(retrieved.key).toBe(created.key);
+      expect(retrieved.name).toBe("Retrieve Test");
+    });
+
+    it("should retrieve multiple symbols by keys", async () => {
+      const created1 = await client.workspaces.schematic.symbols.create({
+        name: "Multi Test 1",
+        data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+        parent: group.ontologyID,
+      });
+      const created2 = await client.workspaces.schematic.symbols.create({
+        name: "Multi Test 2",
+        data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+        parent: group.ontologyID,
+      });
+
+      const retrieved = await client.workspaces.schematic.symbols.retrieve({
+        keys: [created1.key, created2.key],
+      });
+      expect(retrieved).toHaveLength(2);
+    });
+  });
+
+  describe("rename", () => {
+    it("should rename a symbol", async () => {
+      const symbol = await client.workspaces.schematic.symbols.create({
+        name: "Original Name",
+        data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+        parent: group.ontologyID,
+      });
+
+      await client.workspaces.schematic.symbols.rename(symbol.key, "New Name");
+
+      const retrieved = await client.workspaces.schematic.symbols.retrieve({
+        key: symbol.key,
+      });
+      expect(retrieved.name).toBe("New Name");
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete a single symbol", async () => {
+      const symbol = await client.workspaces.schematic.symbols.create({
+        name: "Delete Test",
+        data: { svg: "<svg></svg>", states: [], handles: [], variant: "sensor" },
+        parent: group.ontologyID,
+      });
+
+      await client.workspaces.schematic.symbols.delete(symbol.key);
+
+      await expect(
+        client.workspaces.schematic.symbols.retrieve({ key: symbol.key }),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("retrieveGroup", () => {
+    it("should retrieve the symbol group", async () => {
+      const group = await client.workspaces.schematic.symbols.retrieveGroup();
+      expect(group.key).toBeDefined();
+      expect(group.name).toBe("Schematic Symbols");
+    });
+  });
+});

package/src/workspace/schematic/symbol/client.ts

@@ -0,0 +1,146 @@
+// 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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { array } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { ontology } from "@/ontology";
+import { group } from "@/ontology/group";
+import { checkForMultipleOrNoResults } from "@/util/retrieve";
+import { nullableArrayZ } from "@/util/zod";
+import {
+  type Key,
+  keyZ,
+  type New,
+  newZ,
+  type Symbol,
+  symbolZ,
+} from "@/workspace/schematic/symbol/payload";
+
+const RETRIEVE_ENDPOINT = "/workspace/schematic/symbol/retrieve";
+const CREATE_ENDPOINT = "/workspace/schematic/symbol/create";
+const RENAME_ENDPOINT = "/workspace/schematic/symbol/rename";
+const DELETE_ENDPOINT = "/workspace/schematic/symbol/delete";
+const RETRIEVE_GROUP_ENDPOINT = "/workspace/schematic/symbol/retrieve_group";
+
+const createReqZ = z.object({ symbols: newZ.array(), parent: ontology.idZ });
+const renameReqZ = z.object({ key: keyZ, name: z.string() });
+const deleteReqZ = z.object({ keys: keyZ.array() });
+
+const retrieveRequestZ = z.object({
+  keys: keyZ.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 type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+export type SingleRetrieveArgs = z.input<typeof singleRetrieveArgsZ>;
+export type MultiRetrieveArgs = z.input<typeof retrieveRequestZ>;
+
+const retrieveResZ = z.object({ symbols: nullableArrayZ(symbolZ) });
+const createResZ = z.object({ symbols: symbolZ.array() });
+const emptyResZ = z.object({});
+const retrieveGroupReqZ = z.object({});
+const retrieveGroupResZ = z.object({ group: group.groupZ });
+
+export const SET_CHANNEL_NAME = "sy_schematic_symbol_set";
+export const DELETE_CHANNEL_NAME = "sy_schematic_symbol_delete";
+
+export interface CreateArgs extends New {
+  parent: ontology.ID;
+}
+
+export interface CreateMultipleArgs {
+  symbols: New[];
+  parent: ontology.ID;
+}
+
+export class Client {
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async create(options: CreateArgs): Promise<Symbol>;
+  async create(options: CreateMultipleArgs): Promise<Symbol[]>;
+  async create(options: CreateArgs | CreateMultipleArgs): Promise<Symbol | Symbol[]> {
+    const isMany = "symbols" in options;
+    const symbols = isMany ? options.symbols : [options];
+    const res = await sendRequired(
+      this.client,
+      CREATE_ENDPOINT,
+      { symbols, parent: options.parent },
+      createReqZ,
+      createResZ,
+    );
+    return isMany ? res.symbols : res.symbols[0];
+  }
+
+  async rename(key: Key, name: string): Promise<void> {
+    await sendRequired(
+      this.client,
+      RENAME_ENDPOINT,
+      { key, name },
+      renameReqZ,
+      emptyResZ,
+    );
+  }
+
+  async retrieve(args: SingleRetrieveArgs): Promise<Symbol>;
+  async retrieve(args: MultiRetrieveArgs): Promise<Symbol[]>;
+  async retrieve(args: RetrieveArgs): Promise<Symbol | Symbol[]> {
+    const isSingle = "key" in args;
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      args,
+      retrieveArgsZ,
+      retrieveResZ,
+    );
+    checkForMultipleOrNoResults("Schematic Symbol", args, res.symbols, isSingle);
+    return isSingle ? res.symbols[0] : res.symbols;
+  }
+
+  async delete(key: Key): Promise<void>;
+  async delete(keys: Key[]): Promise<void>;
+  async delete(keys: Key | Key[]): Promise<void> {
+    await sendRequired(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: array.toArray(keys) },
+      deleteReqZ,
+      emptyResZ,
+    );
+  }
+
+  async retrieveGroup(): Promise<group.Payload> {
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_GROUP_ENDPOINT,
+      {},
+      retrieveGroupReqZ,
+      retrieveGroupResZ,
+    );
+    return res.group;
+  }
+}
+
+export const ontologyID = (key: Key): ontology.ID => ({
+  type: "schematic_symbol",
+  key,
+});

package/src/workspace/schematic/symbol/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 "@/workspace/schematic/symbol/client";
+export * from "@/workspace/schematic/symbol/payload";

package/src/workspace/schematic/symbol/index.ts

@@ -0,0 +1,10 @@
+// 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 * as symbol from "@/workspace/schematic/symbol/external";

package/src/workspace/schematic/symbol/payload.ts

@@ -0,0 +1,70 @@
+// 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 { location, xy } from "@synnaxlabs/x";
+import { z } from "zod";
+
+export const keyZ = z.uuid();
+export type Key = z.infer<typeof keyZ>;
+export type Params = Key | Key[];
+
+export const regionZ = z.object({
+  key: z.string(),
+  name: z.string(),
+  selectors: z.string().array().default([]),
+  strokeColor: z.string().optional(),
+  fillColor: z.string().optional(),
+});
+
+export interface Region extends z.infer<typeof regionZ> {}
+
+export const stateZ = z.object({
+  key: z.string(),
+  name: z.string(),
+  regions: regionZ.array(),
+});
+
+export interface State extends z.infer<typeof stateZ> {}
+
+export const handleZ = z.object({
+  key: z.string(),
+  position: xy.xy,
+  orientation: location.outer,
+});
+
+export interface Handle extends z.infer<typeof handleZ> {}
+
+const viewportZ = z.object({
+  zoom: z.number().positive().default(1),
+  position: xy.xy,
+});
+
+export const specZ = z.object({
+  svg: z.string().min(1, "SVG is required"),
+  states: stateZ.array(),
+  variant: z.string().min(1, "Variant is required"),
+  handles: handleZ.array(),
+  scale: z.number().positive().default(1),
+  scaleStroke: z.boolean().default(false),
+  previewViewport: viewportZ.default({ zoom: 1, position: { x: 0, y: 0 } }),
+});
+
+export interface Spec extends z.infer<typeof specZ> {}
+
+export const symbolZ = z.object({
+  key: keyZ,
+  version: z.literal(1).optional().default(1),
+  name: z.string().min(1, "Name is required"),
+  data: specZ,
+});
+
+export const newZ = symbolZ.partial({ key: true });
+export interface New extends z.input<typeof newZ> {}
+
+export interface Symbol extends z.infer<typeof symbolZ> {}