@synnaxlabs/client 0.47.0 → 0.49.0

package/src/access/policy/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 { array } from "@synnaxlabs/x";
+import { array, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { actionZ } from "@/access/payload";
@@ -18,16 +18,20 @@ export type Key = z.infer<typeof keyZ>;
 
 export const policyZ = z.object({
   key: keyZ,
-  subjects: array.nullableZ(ontology.idZ),
+  name: z.string(),
   objects: array.nullableZ(ontology.idZ),
   actions: array.nullableZ(actionZ),
+  internal: z.boolean(),
 });
 export interface Policy extends z.infer<typeof policyZ> {}
 
 export const newZ = z.object({
   key: keyZ.optional(),
-  subjects: ontology.idZ.array().or(ontology.idZ),
-  objects: ontology.idZ.array().or(ontology.idZ),
-  actions: actionZ.array().or(actionZ),
+  name: z.string(),
+  objects: zod.toArray(ontology.idZ),
+  actions: zod.toArray(actionZ),
 });
 export interface New extends z.input<typeof newZ> {}
+
+export const ontologyID = ontology.createIDFactory<Key>("policy");
+export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/access/role/client.ts

@@ -0,0 +1,135 @@
+// 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 { keyZ, type New, newZ, type Role, roleZ } from "@/access/role/payload";
+import { user } from "@/user";
+
+const retrieveRequestZ = z.object({
+  keys: keyZ.array().optional(),
+  limit: z.number().optional(),
+  offset: z.number().optional(),
+  internal: z.boolean().optional(),
+});
+
+const keyRetrieveRequestZ = z
+  .object({ key: keyZ })
+  .transform(({ key }) => ({ keys: [key] }));
+
+const singleCreateArgsZ = newZ.transform((r) => ({ roles: [r] }));
+export type SingleCreateArgs = z.input<typeof singleCreateArgsZ>;
+
+export const multipleCreateArgsZ = newZ.array().transform((roles) => ({ roles }));
+
+export const createArgsZ = z.union([singleCreateArgsZ, multipleCreateArgsZ]);
+export type CreateArgs = z.input<typeof createArgsZ>;
+
+const createResZ = z.object({ roles: roleZ.array() });
+const retrieveResZ = z.object({ roles: array.nullableZ(roleZ) });
+
+export type RetrieveSingleParams = z.input<typeof keyRetrieveRequestZ>;
+export type RetrieveMultipleParams = z.input<typeof retrieveRequestZ>;
+
+export const retrieveArgsZ = z.union([keyRetrieveRequestZ, retrieveRequestZ]);
+export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+
+const deleteResZ = z.object({});
+
+const deleteArgsZ = keyZ
+  .transform((key) => ({ keys: [key] }))
+  .or(keyZ.array().transform((keys) => ({ keys })));
+export type DeleteArgs = z.input<typeof deleteArgsZ>;
+
+const assignReqZ = z.object({
+  user: user.keyZ,
+  role: keyZ,
+});
+export type AssignArgs = z.input<typeof assignReqZ>;
+
+const assignResZ = z.object({});
+
+const unassignReqZ = z.object({
+  user: user.keyZ,
+  role: keyZ,
+});
+export type UnassignArgs = z.input<typeof unassignReqZ>;
+
+const unassignResZ = z.object({});
+
+export const SET_CHANNEL_NAME = "sy_role_set";
+export const DELETE_CHANNEL_NAME = "sy_role_delete";
+
+export class Client {
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async create(role: New): Promise<Role>;
+  async create(roles: New[]): Promise<Role[]>;
+  async create(roles: New | New[]): Promise<Role | Role[]> {
+    const isMany = Array.isArray(roles);
+    const res = await sendRequired<typeof createArgsZ, typeof createResZ>(
+      this.client,
+      "/access/role/create",
+      roles,
+      createArgsZ,
+      createResZ,
+    );
+    return isMany ? res.roles : res.roles[0];
+  }
+
+  async retrieve(args: RetrieveSingleParams): Promise<Role>;
+  async retrieve(args: RetrieveMultipleParams): Promise<Role[]>;
+  async retrieve(args: RetrieveArgs): Promise<Role | Role[]> {
+    const isSingle = "key" in args;
+    const res = await sendRequired<typeof retrieveArgsZ, typeof retrieveResZ>(
+      this.client,
+      "/access/role/retrieve",
+      args,
+      retrieveArgsZ,
+      retrieveResZ,
+    );
+    return isSingle ? res.roles[0] : res.roles;
+  }
+
+  async delete(args: DeleteArgs): Promise<void> {
+    await sendRequired<typeof deleteArgsZ, typeof deleteResZ>(
+      this.client,
+      "/access/role/delete",
+      args,
+      deleteArgsZ,
+      deleteResZ,
+    );
+  }
+
+  async assign(args: AssignArgs): Promise<void> {
+    await sendRequired<typeof assignReqZ, typeof assignResZ>(
+      this.client,
+      "/access/role/assign",
+      args,
+      assignReqZ,
+      assignResZ,
+    );
+  }
+
+  async unassign(args: UnassignArgs): Promise<void> {
+    await sendRequired<typeof unassignReqZ, typeof unassignResZ>(
+      this.client,
+      "/access/role/unassign",
+      args,
+      unassignReqZ,
+      unassignResZ,
+    );
+  }
+}

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

package/src/{hardware → access/role}/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 hardware from "@/hardware/external";
+export * as role from "@/access/role/external";

package/src/access/role/payload.ts

@@ -0,0 +1,32 @@
+// 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 { z } from "zod";
+
+import { ontology } from "@/ontology";
+
+export const keyZ = z.uuid();
+
+export type Key = z.infer<typeof keyZ>;
+
+export const roleZ = z.object({
+  key: keyZ,
+  name: z.string(),
+  description: z.string().optional(),
+  internal: z.boolean().optional(),
+});
+
+export type Role = z.infer<typeof roleZ>;
+
+export const newZ = roleZ.partial({ key: true });
+
+export type New = z.infer<typeof newZ>;
+
+export const ontologyID = ontology.createIDFactory<Key>("role");
+export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/access/role/role.spec.ts

@@ -0,0 +1,95 @@
+// 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 { id } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { NotFoundError } from "@/errors";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("role", () => {
+  describe("create", () => {
+    it("should allow the caller to create a role", async () => {
+      const role = await client.access.roles.create({
+        name: "test",
+        description: "test",
+      });
+      expect(role.key).toBeDefined();
+      expect(role.name).toBe("test");
+      expect(role.description).toBe("test");
+    });
+  });
+
+  describe("retrieve", () => {
+    it("should allow the caller to retrieve a role", async () => {
+      const created = await client.access.roles.create({
+        name: "test",
+        description: "test",
+      });
+      const retrieved = await client.access.roles.retrieve({ key: created.key });
+      expect(retrieved.key).toBe(created.key);
+      expect(retrieved.name).toBe(created.name);
+      expect(retrieved.description).toBe(created.description);
+    });
+
+    it("should filter by internal flag when retrieving roles", async () => {
+      // Create a non-internal role
+      const created = await client.access.roles.create({
+        name: "test-non-internal",
+        description: "test",
+      });
+
+      // Retrieve only internal roles (built-in system roles)
+      const internalRoles = await client.access.roles.retrieve({ internal: true });
+      expect(internalRoles.length).toBeGreaterThan(0);
+      expect(internalRoles.every((r) => r.internal === true)).toBe(true);
+      expect(internalRoles.find((r) => r.key === created.key)).toBeUndefined();
+
+      // Retrieve only non-internal roles
+      const nonInternalRoles = await client.access.roles.retrieve({ internal: false });
+      expect(nonInternalRoles.every((r) => r.internal !== true)).toBe(true);
+      expect(nonInternalRoles.find((r) => r.key === created.key)).toBeDefined();
+    });
+  });
+
+  describe("delete", () => {
+    it("should allow the caller to delete a role", async () => {
+      const created = await client.access.roles.create({
+        name: "test",
+        description: "test",
+      });
+      await client.access.roles.delete(created.key);
+      await expect(client.access.roles.retrieve({ key: created.key })).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+  });
+
+  describe("assign", () => {
+    it("should allow the caller to assign a role to a user", async () => {
+      const role = await client.access.roles.create({
+        name: "test",
+        description: "test",
+      });
+      const username = id.create();
+      const u = await client.users.create({
+        username,
+        password: "test",
+        firstName: "test",
+        lastName: "test",
+      });
+      await client.access.roles.assign({
+        user: u.key,
+        role: role.key,
+      });
+    });
+  });
+});

package/src/arc/access.spec.ts

@@ -0,0 +1,143 @@
+// 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 { describe, expect, it } from "vitest";
+
+import { arc } from "@/arc";
+import { AuthError, NotFoundError } from "@/errors";
+import { createTestClientWithPolicy } from "@/testutil/access";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("arc", () => {
+  describe("access control", () => {
+    it("should deny access when no retrieve policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [],
+        actions: [],
+      });
+      const a: arc.New = {
+        name: "test",
+        graph: {
+          nodes: [],
+          edges: [],
+        },
+        text: { raw: "" },
+        deploy: false,
+        version: "1.0.0",
+      };
+      const randomArc = await client.arcs.create(a);
+      await expect(userClient.arcs.retrieve({ key: randomArc.key })).rejects.toThrow(
+        AuthError,
+      );
+    });
+
+    it("should allow the caller to retrieve arcs with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [arc.ontologyID("")],
+        actions: ["retrieve"],
+      });
+      const randomArc = await client.arcs.create({
+        name: "test",
+        graph: {
+          nodes: [],
+          edges: [],
+        },
+        text: { raw: "" },
+        deploy: false,
+        version: "1.0.0",
+      });
+      const retrieved = await userClient.arcs.retrieve({ key: randomArc.key });
+      expect(retrieved.key).toBe(randomArc.key);
+      expect(retrieved.name).toBe(randomArc.name);
+    });
+
+    it("should allow the caller to create arcs with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [arc.ontologyID("")],
+        actions: ["create"],
+      });
+      await userClient.arcs.create({
+        name: "test",
+        graph: {
+          nodes: [],
+          edges: [],
+        },
+        text: { raw: "" },
+        deploy: false,
+        version: "1.0.0",
+      });
+    });
+
+    it("should deny access when no create policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [arc.ontologyID("")],
+        actions: [],
+      });
+      await expect(
+        userClient.arcs.create({
+          name: "test",
+          graph: {
+            nodes: [],
+            edges: [],
+          },
+          text: { raw: "" },
+          deploy: false,
+          version: "1.0.0",
+        }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to delete arcs with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [arc.ontologyID("")],
+        actions: ["delete", "retrieve"],
+      });
+      const randomArc = await client.arcs.create({
+        name: "test",
+        graph: {
+          nodes: [],
+          edges: [],
+        },
+        text: { raw: "" },
+        deploy: false,
+        version: "1.0.0",
+      });
+      await userClient.arcs.delete(randomArc.key);
+      await expect(userClient.arcs.retrieve({ key: randomArc.key })).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+
+    it("should deny access when no delete policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [arc.ontologyID("")],
+        actions: [],
+      });
+      const randomArc = await client.arcs.create({
+        name: "test",
+        graph: {
+          nodes: [],
+          edges: [],
+        },
+        text: { raw: "" },
+        deploy: false,
+        version: "1.0.0",
+      });
+      await expect(userClient.arcs.delete(randomArc.key)).rejects.toThrow(AuthError);
+    });
+  });
+});

package/src/arc/client.ts

@@ -16,33 +16,18 @@ import {
 import { array } from "@synnaxlabs/x";
 import { z } from "zod/v4";
 
-import {
-  type Arc,
-  arcZ,
-  type Key,
-  keyZ,
-  type New,
-  newZ,
-  ONTOLOGY_TYPE,
-  type Params,
-} from "@/arc/payload";
-import { type ontology } from "@/ontology";
+import { type Arc, arcZ, keyZ, type New, newZ, type Params } from "@/arc/payload";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
 export const SET_CHANNEL_NAME = "sy_arc_set";
 export const DELETE_CHANNEL_NAME = "sy_arc_delete";
 
-const RETRIEVE_ENDPOINT = "/arc/retrieve";
-const CREATE_ENDPOINT = "/arc/create";
-const DELETE_ENDPOINT = "/arc/delete";
-const LSP_ENDPOINT = "/arc/lsp";
-
 const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   searchTerm: z.string().optional(),
-  limit: z.number().optional(),
-  offset: z.number().optional(),
+  limit: z.int().optional(),
+  offset: z.int().optional(),
   includeStatus: z.boolean().optional(),
 });
 const createReqZ = z.object({ arcs: newZ.array() });
@@ -94,7 +79,7 @@ export class Client {
     const isMany = Array.isArray(arcs);
     const res = await sendRequired(
       this.client,
-      CREATE_ENDPOINT,
+      "/arc/create",
       { arcs: array.toArray(arcs) },
       createReqZ,
       createResZ,
@@ -108,7 +93,7 @@ export class Client {
     const isSingle = "key" in args || "name" in args;
     const res = await sendRequired(
       this.client,
-      RETRIEVE_ENDPOINT,
+      "/arc/retrieve",
       args,
       retrieveArgsZ,
       retrieveResZ,
@@ -120,23 +105,14 @@ export class Client {
   async delete(keys: Params): Promise<void> {
     await sendRequired(
       this.client,
-      DELETE_ENDPOINT,
+      "/arc/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,
       emptyResZ,
     );
   }
 
-  /**
-   * Opens a new LSP stream to the server for Language Server Protocol communication.
-   * This allows editor integrations to communicate with the Arc LSP server using
-   * JSON-RPC messages over a WebSocket transport.
-   *
-   * @returns A bidirectional stream for sending and receiving JSON-RPC messages
-   */
   async openLSP(): Promise<Stream<typeof lspMessageZ, typeof lspMessageZ>> {
-    return await this.streamClient.stream(LSP_ENDPOINT, lspMessageZ, lspMessageZ);
+    return await this.streamClient.stream("/arc/lsp", lspMessageZ, lspMessageZ);
   }
 }
-
-export const ontologyID = (key: Key): ontology.ID => ({ type: ONTOLOGY_TYPE, key });

package/src/arc/payload.ts

@@ -10,6 +10,7 @@
 import { record, xy } from "@synnaxlabs/x";
 import { z } from "zod/v4";
 
+import { ontology } from "@/ontology";
 import { statusZ as baseStatusZ } from "@/status/payload";
 import { parseWithoutKeyConversion } from "@/util/parseWithoutKeyConversion";
 
@@ -72,3 +73,6 @@ export interface New extends z.input<typeof newZ> {}
 
 export const ONTOLOGY_TYPE = "arc";
 export type OntologyType = typeof ONTOLOGY_TYPE;
+
+export const ontologyID = ontology.createIDFactory<Key>("arc");
+export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/auth/auth.spec.ts

@@ -13,7 +13,7 @@ import { describe, expect, it, test } from "vitest";
 
 import { auth } from "@/auth";
 import { AuthError, ExpiredTokenError, InvalidTokenError } from "@/errors";
-import { TEST_CLIENT_PROPS } from "@/testutil/client";
+import { TEST_CLIENT_PARAMS } from "@/testutil/client";
 import { Transport } from "@/transport";
 
 const DUMMY_CTX: Context = {
@@ -27,11 +27,11 @@ describe("auth", () => {
   test("valid credentials", async () => {
     const transport = new Transport(
       new URL({
-        host: TEST_CLIENT_PROPS.host,
-        port: Number(TEST_CLIENT_PROPS.port),
+        host: TEST_CLIENT_PARAMS.host,
+        port: Number(TEST_CLIENT_PARAMS.port),
       }),
     );
-    const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+    const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
     const mw = client.middleware();
     const res = await mw(DUMMY_CTX, async () => [DUMMY_CTX, null]);
     expect(res).toEqual([DUMMY_CTX, null]);
@@ -40,12 +40,12 @@ describe("auth", () => {
   test("invalid credentials", async () => {
     const transport = new Transport(
       new URL({
-        host: TEST_CLIENT_PROPS.host,
-        port: Number(TEST_CLIENT_PROPS.port),
+        host: TEST_CLIENT_PARAMS.host,
+        port: Number(TEST_CLIENT_PARAMS.port),
       }),
     );
     const client = new auth.Client(transport.unary, {
-      ...TEST_CLIENT_PROPS,
+      ...TEST_CLIENT_PARAMS,
       password: "wrong",
     });
     const mw = client.middleware();
@@ -59,11 +59,11 @@ describe("auth", () => {
       it(`should re-authenticate and retry the request for ${ErrorType.name}`, async () => {
         const transport = new Transport(
           new URL({
-            host: TEST_CLIENT_PROPS.host,
-            port: Number(TEST_CLIENT_PROPS.port),
+            host: TEST_CLIENT_PARAMS.host,
+            port: Number(TEST_CLIENT_PARAMS.port),
           }),
         );
-        const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+        const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
         const mw = client.middleware();
         let isFirst = true;
         let tkOne: string | undefined;
@@ -86,11 +86,11 @@ describe("auth", () => {
     it("should fail after MAX_RETRIES", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       const mw = client.middleware();
       const [, err] = await mw(DUMMY_CTX, async () => [
         DUMMY_CTX,