@synnaxlabs/client 0.38.0 → 0.39.0

package/src/ontology/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.
@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { observe, toArray } from "@synnaxlabs/x";
+import { observe, strings, toArray } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { z } from "zod";
 
@@ -25,8 +25,8 @@ import {
   type RelationshipDirection,
   type Resource,
   type ResourceChange,
-  resourceSchemaZ,
   resourceTypeZ,
+  resourceZ,
 } from "@/ontology/payload";
 import { Writer } from "@/ontology/writer";
 
@@ -43,17 +43,12 @@ const retrieveReqZ = z.object({
   offset: z.number().optional(),
   types: resourceTypeZ.array().optional(),
 });
+interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
 
-type RetrieveRequest = z.infer<typeof retrieveReqZ>;
+export interface RetrieveOptions
+  extends Pick<RetrieveRequest, "includeSchema" | "excludeFieldData" | "types"> {}
 
-export type RetrieveOptions = Pick<
-  RetrieveRequest,
-  "includeSchema" | "excludeFieldData" | "types"
->;
-
-const retrieveResZ = z.object({
-  resources: resourceSchemaZ.array(),
-});
+const retrieveResZ = z.object({ resources: resourceZ.array() });
 
 export const parseIDs = (ids: CrudeID | CrudeID[] | string | string[]): IDPayload[] =>
   toArray(ids).map((id) => new ID(id).payload);
@@ -123,7 +118,11 @@ export class Client implements AsyncTermSearcher<string, string, Resource> {
     const resources = await this.execRetrieve({ ids: parseIDs(ids), ...options });
     if (Array.isArray(ids)) return resources;
     if (resources.length === 0)
-      throw new QueryError(`No resource found with ID ${ids.toString()}`);
+      throw new QueryError(
+        `No resource found with ID ${strings.naturalLanguageJoin(
+          toArray(ids).map((id) => new ID(id).toString()),
+        )}`,
+      );
     return resources[0];
   }
 
@@ -250,10 +249,10 @@ export class Client implements AsyncTermSearcher<string, string, Resource> {
   }
 }
 
-const RESOURCE_SET_NAME = "sy_ontology_resource_set";
-const RESOURCE_DELETE_NAME = "sy_ontology_resource_delete";
-const RELATIONSHIP_SET_NAME = "sy_ontology_relationship_set";
-const RELATIONSHIP_DELETE_NAME = "sy_ontology_relationship_delete";
+const RESOURCE_SET_CHANNEL_NAME = "sy_ontology_resource_set";
+const RESOURCE_DELETE_CHANNEL_NAME = "sy_ontology_resource_delete";
+const RELATIONSHIP_SET_CHANNEL_NAME = "sy_ontology_relationship_set";
+const RELATIONSHIP_DELETE_CHANNEL_NAME = "sy_ontology_relationship_delete";
 
 /**
  * A class that tracks changes to the ontology's resources and relationships.
@@ -306,7 +305,7 @@ export class ChangeTracker {
   }
 
   private parseRelationshipSets(frame: framer.Frame): RelationshipChange[] {
-    const relationships = frame.get(RELATIONSHIP_SET_NAME);
+    const relationships = frame.get(RELATIONSHIP_SET_CHANNEL_NAME);
     if (relationships.length === 0) return [];
     return Array.from(relationships.as("string")).map((rel) => ({
       variant: "set",
@@ -316,7 +315,7 @@ export class ChangeTracker {
   }
 
   private parseRelationshipDeletes(frame: framer.Frame): RelationshipChange[] {
-    const relationships = frame.get(RELATIONSHIP_DELETE_NAME);
+    const relationships = frame.get(RELATIONSHIP_DELETE_CHANNEL_NAME);
     if (relationships.length === 0) return [];
     return Array.from(relationships.as("string")).map((rel) => ({
       variant: "delete",
@@ -325,7 +324,7 @@ export class ChangeTracker {
   }
 
   private async parseResourceSets(frame: framer.Frame): Promise<ResourceChange[]> {
-    const sets = frame.get(RESOURCE_SET_NAME);
+    const sets = frame.get(RESOURCE_SET_CHANNEL_NAME);
     if (sets.length === 0) return [];
     // We should only ever get one series of sets
     const ids = Array.from(sets.as("string")).map((id: string) => new ID(id));
@@ -343,7 +342,7 @@ export class ChangeTracker {
   }
 
   private parseResourceDeletes(frame: framer.Frame): ResourceChange[] {
-    const deletes = frame.get(RESOURCE_DELETE_NAME);
+    const deletes = frame.get(RESOURCE_DELETE_CHANNEL_NAME);
     if (deletes.length === 0) return [];
     // We should only ever get one series of deletes
     return Array.from(deletes.as("string")).map((str) => ({
@@ -354,10 +353,10 @@ export class ChangeTracker {
 
   static async open(client: framer.Client, retriever: Client): Promise<ChangeTracker> {
     const streamer = await client.openStreamer([
-      RESOURCE_SET_NAME,
-      RESOURCE_DELETE_NAME,
-      RELATIONSHIP_SET_NAME,
-      RELATIONSHIP_DELETE_NAME,
+      RESOURCE_SET_CHANNEL_NAME,
+      RESOURCE_DELETE_CHANNEL_NAME,
+      RELATIONSHIP_SET_CHANNEL_NAME,
+      RELATIONSHIP_DELETE_CHANNEL_NAME,
     ]);
     return new ChangeTracker(streamer, retriever);
   }
@@ -458,10 +457,13 @@ export class DependentTracker
           c.key[oppositeDirection(this.relDir)].type === this.resourceType),
     );
     if (sets.length === 0) return this.notify(this.dependents);
-    this.client.retrieve(sets.map((s) => s.key.to)).then((resources) => {
-      this.dependents = this.dependents.concat(resources);
-      this.notify(this.dependents);
-    });
+    this.client
+      .retrieve(sets.map((s) => s.key.to))
+      .then((resources) => {
+        this.dependents = this.dependents.concat(resources);
+        this.notify(this.dependents);
+      })
+      .catch(console.error);
   };
 
   async close(): Promise<void> {

package/src/ontology/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/ontology/group/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.
@@ -9,10 +9,10 @@
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
 
+import { type ontology } from "@/ontology";
 import { Group } from "@/ontology/group/group";
-import { type Payload } from "@/ontology/group/payload";
+import { type Key, type Name, type Payload } from "@/ontology/group/payload";
 import { Writer } from "@/ontology/group/writer";
-import { type ID } from "@/ontology/payload";
 
 export class Client {
   private readonly creator: Writer;
@@ -21,15 +21,15 @@ export class Client {
     this.creator = new Writer(unary);
   }
 
-  async create(parent: ID, name: string, key?: string): Promise<Group> {
+  async create(parent: ontology.ID, name: Name, key?: Key): Promise<Group> {
     return this.sugar(await this.creator.create(parent, name, key));
   }
 
-  async rename(key: string, name: string): Promise<void> {
+  async rename(key: Key, name: Name): Promise<void> {
     return await this.creator.rename(key, name);
   }
 
-  async delete(...keys: string[]): Promise<void> {
+  async delete(...keys: Key[]): Promise<void> {
     return await this.creator.delete(keys);
   }
 

package/src/ontology/group/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/ontology/group/group.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.
@@ -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 { describe, expect,it } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import { QueryError } from "@/errors";
 import { ontology } from "@/ontology";
@@ -19,14 +19,14 @@ describe("Group", () => {
   describe("create", () => {
     it("should correctly create a group", async () => {
       const name = `group-${Math.random()}`;
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       expect(g.name).toEqual(name);
     });
   });
   describe("rename", () => {
     it("should correctly rename a group", async () => {
       const name = `group-${Math.random()}`;
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const newName = `group-${Math.random()}`;
       await client.ontology.groups.rename(g.key, newName);
       const g2 = await client.ontology.retrieve(g.ontologyID);
@@ -36,7 +36,7 @@ describe("Group", () => {
   describe("delete", () => {
     it("should correctly delete the group", async () => {
       const name = `group-${Math.random()}`;
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       await client.ontology.groups.delete(g.key);
       await expect(
         async () => await client.ontology.retrieve(g.ontologyID),

package/src/ontology/group/group.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.
@@ -7,19 +7,22 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type ontology } from "@/ontology";
-import { ontologyID as payloadOntologyID } from "@/ontology/group/payload";
+import { type Key, type Name, ONTOLOGY_TYPE } from "@/ontology/group/payload";
+import { ID as OntologyID } from "@/ontology/payload";
 
 export class Group {
-  key: string;
-  name: string;
+  key: Key;
+  name: Name;
 
-  constructor(name: string, key: string) {
+  constructor(name: Name, key: Key) {
     this.key = key;
     this.name = name;
   }
 
-  get ontologyID(): ontology.ID {
-    return payloadOntologyID(this.key);
+  get ontologyID(): OntologyID {
+    return ontologyID(this.key);
   }
 }
+
+export const ontologyID = (key: Key): OntologyID =>
+  new OntologyID({ type: ONTOLOGY_TYPE, key });

package/src/ontology/group/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/ontology/group/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,22 @@
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
-import { ontology } from "@/ontology";
-
 export const keyZ = z.string().uuid();
 export type Key = z.infer<typeof keyZ>;
-export type Name = string;
+export const nameZ = z.string();
+export type Name = z.infer<typeof nameZ>;
 export type Keys = Key[];
 export type Names = Name[];
 export type Params = Key | Name | Keys | Names;
 
-export const groupZ = z.object({ key: keyZ, name: z.string() });
-
-export type Payload = z.infer<typeof groupZ>;
+export const groupZ = z.object({ key: keyZ, name: nameZ });
+export interface Payload extends z.infer<typeof groupZ> {}
 
 export type ParamAnalysisResult =
-  | {
-      single: true;
-      variant: "keys";
-      normalized: Keys;
-      actual: Key;
-    }
-  | {
-      single: true;
-      variant: "names";
-      normalized: Names;
-      actual: Name;
-    }
-  | {
-      single: false;
-      variant: "keys";
-      normalized: Keys;
-      actual: Keys;
-    }
-  | {
-      single: false;
-      variant: "names";
-      normalized: Names;
-      actual: Names;
-    };
+  | { single: true; variant: "keys"; normalized: Keys; actual: Key }
+  | { single: true; variant: "names"; normalized: Names; actual: Name }
+  | { single: false; variant: "keys"; normalized: Keys; actual: Keys }
+  | { single: false; variant: "names"; normalized: Names; actual: Names };
 
 export const analyzeParams = (groups: Params): ParamAnalysisResult => {
   const normal = toArray(groups) as Keys | Names;
@@ -58,10 +36,8 @@ export const analyzeParams = (groups: Params): ParamAnalysisResult => {
     variant: isKey ? "keys" : "names",
     normalized: normal,
     actual: groups,
-  } as const as ParamAnalysisResult;
+  } as ParamAnalysisResult;
 };
 
-export const ONTOLOGY_TYPE: ontology.ResourceType = "group";
-
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key });
+export const ONTOLOGY_TYPE = "group";
+export type OntologyType = typeof ONTOLOGY_TYPE;

package/src/ontology/group/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.
@@ -10,42 +10,38 @@
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { groupZ, type Payload } from "@/ontology/group/payload";
-import { type ID, idZ } from "@/ontology/payload";
+import {
+  groupZ,
+  type Key,
+  keyZ,
+  type Name,
+  nameZ,
+  type Payload,
+} from "@/ontology/group/payload";
+import { type ID as OntologyID, idZ as ontologyIDZ } from "@/ontology/payload";
 
-const resZ = z.object({
-  group: groupZ,
-});
+const resZ = z.object({ group: groupZ });
 
-const createReqZ = z.object({
-  parent: idZ,
-  key: z.string().uuid().optional(),
-  name: z.string(),
-});
+const createReqZ = z.object({ parent: ontologyIDZ, key: keyZ.optional(), name: nameZ });
 
-const renameReqZ = z.object({
-  key: z.string(),
-  name: z.string(),
-});
+const renameReqZ = z.object({ key: keyZ, name: nameZ });
 
-const deleteReqZ = z.object({
-  keys: z.array(z.string()),
-});
+const deleteReqZ = z.object({ keys: z.array(keyZ) });
 
 export class Writer {
-  private static readonly ENDPOINT = "/ontology/create-group";
-  private static readonly ENDPOINT_RENAME = "/ontology/rename-group";
-  private static readonly ENDPOINT_DELETE = "/ontology/delete-group";
+  private static readonly CREATE_ENDPOINT = "/ontology/create-group";
+  private static readonly RENAME_ENDPOINT = "/ontology/rename-group";
+  private static readonly DELETE_ENDPOINT = "/ontology/delete-group";
   client: UnaryClient;
 
   constructor(client: UnaryClient) {
     this.client = client;
   }
 
-  async create(parent: ID, name: string, key?: string): Promise<Payload> {
+  async create(parent: OntologyID, name: Name, key?: Key): Promise<Payload> {
     const res = await sendRequired(
       this.client,
-      Writer.ENDPOINT,
+      Writer.CREATE_ENDPOINT,
       { parent, name, key },
       createReqZ,
       resZ,
@@ -53,20 +49,20 @@ export class Writer {
     return res.group;
   }
 
-  async rename(key: string, name: string): Promise<void> {
+  async rename(key: Key, name: Name): Promise<void> {
     await sendRequired(
       this.client,
-      Writer.ENDPOINT_RENAME,
+      Writer.RENAME_ENDPOINT,
       { key, name },
       renameReqZ,
       z.object({}),
     );
   }
 
-  async delete(keys: string[]): Promise<void> {
+  async delete(keys: Key[]): Promise<void> {
     await sendRequired(
       this.client,
-      Writer.ENDPOINT_DELETE,
+      Writer.DELETE_ENDPOINT,
       { keys },
       deleteReqZ,
       z.object({}),

package/src/ontology/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/ontology/ontology.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.
@@ -20,13 +20,13 @@ describe("Ontology", () => {
   describe("retrieve", () => {
     test("retrieve", async () => {
       const name = randomName();
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const g2 = await client.ontology.retrieve(g.ontologyID);
       expect(g2.name).toEqual(name);
     });
     test("retrieve children", async () => {
       const name = randomName();
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const name2 = randomName();
       await client.ontology.groups.create(g.ontologyID, name2);
       const children = await client.ontology.retrieveChildren(g.ontologyID);
@@ -35,7 +35,7 @@ describe("Ontology", () => {
     });
     test("retrieve parents", async () => {
       const name = randomName();
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const name2 = randomName();
       const g2 = await client.ontology.groups.create(g.ontologyID, name2);
       const parents = await client.ontology.retrieveParents(g2.ontologyID);
@@ -46,7 +46,7 @@ describe("Ontology", () => {
   describe("page", () => {
     it("should return a page of resources", async () => {
       for (let i = 0; i < 10; i++)
-        await client.ontology.groups.create(ontology.Root, randomName());
+        await client.ontology.groups.create(ontology.ROOT_ID, randomName());
       const page = await client.ontology.page(0, 5);
       expect(page.length).toEqual(5);
       const page2 = await client.ontology.page(5, 5);
@@ -60,9 +60,9 @@ describe("Ontology", () => {
   describe("write", () => {
     test("add children", async () => {
       const name = randomName();
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const name2 = randomName();
-      const g2 = await client.ontology.groups.create(ontology.Root, name2);
+      const g2 = await client.ontology.groups.create(ontology.ROOT_ID, name2);
       await client.ontology.addChildren(g.ontologyID, g2.ontologyID);
       const children = await client.ontology.retrieveChildren(g.ontologyID);
       expect(children.length).toEqual(1);
@@ -70,9 +70,9 @@ describe("Ontology", () => {
     });
     test("remove children", async () => {
       const name = randomName();
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const name2 = randomName();
-      const g2 = await client.ontology.groups.create(ontology.Root, name2);
+      const g2 = await client.ontology.groups.create(ontology.ROOT_ID, name2);
       await client.ontology.addChildren(g.ontologyID, g2.ontologyID);
       await client.ontology.removeChildren(g.ontologyID, g2.ontologyID);
       const children = await client.ontology.retrieveChildren(g.ontologyID);
@@ -80,15 +80,15 @@ describe("Ontology", () => {
     });
     test("move children", async () => {
       const name = randomName();
-      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g = await client.ontology.groups.create(ontology.ROOT_ID, name);
       const name2 = randomName();
-      const g2 = await client.ontology.groups.create(ontology.Root, name2);
-      const oldRootLength = (await client.ontology.retrieveChildren(ontology.Root))
+      const g2 = await client.ontology.groups.create(ontology.ROOT_ID, name2);
+      const oldRootLength = (await client.ontology.retrieveChildren(ontology.ROOT_ID))
         .length;
-      await client.ontology.moveChildren(ontology.Root, g.ontologyID, g2.ontologyID);
+      await client.ontology.moveChildren(ontology.ROOT_ID, g.ontologyID, g2.ontologyID);
       const children = await client.ontology.retrieveChildren(g.ontologyID);
       expect(children.length).toEqual(1);
-      const newRootLength = (await client.ontology.retrieveChildren(ontology.Root))
+      const newRootLength = (await client.ontology.retrieveChildren(ontology.ROOT_ID))
         .length;
       expect(newRootLength).toEqual(oldRootLength - 1);
     });
@@ -107,7 +107,7 @@ describe("Ontology", () => {
       const p = new Promise<ontology.ResourceChange[]>((resolve) =>
         change.resources.onChange((changes) => resolve(changes)),
       );
-      await client.ontology.groups.create(ontology.Root, randomName());
+      await client.ontology.groups.create(ontology.ROOT_ID, randomName());
       const c = await p;
       expect(c.length).toBeGreaterThan(0);
       await change.close();
@@ -119,7 +119,7 @@ describe("Ontology", () => {
           resolve(changes);
         });
       });
-      await client.ontology.groups.create(ontology.Root, randomName());
+      await client.ontology.groups.create(ontology.ROOT_ID, randomName());
       const c = await p;
       expect(c.length).toBeGreaterThan(0);
       await change.close();