@synnaxlabs/client 0.38.0 → 0.39.0

package/src/access/policy/ontology.ts

@@ -0,0 +1,17 @@
+// 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.
+
+// This needs to be a separate file because these types are imported by the ontology
+// module, but the policy module need to import the ID schema from the ontology module.
+
+export const ONTOLOGY_TYPE = "policy";
+export type OntologyType = typeof ONTOLOGY_TYPE;
+
+export const ALLOW_ALL_ONTOLOGY_TYPE = "allow_all";
+export type AllowAllOntologyType = typeof ALLOW_ALL_ONTOLOGY_TYPE;

package/src/access/policy/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.
@@ -16,30 +16,18 @@ import { nullableArrayZ } from "@/util/zod";
 export const keyZ = z.string().uuid();
 export type Key = z.infer<typeof keyZ>;
 
-export const newPolicyZ = z.object({
-  key: keyZ.optional(),
-  subjects: ontology.crudeIDZ.array().or(ontology.crudeIDZ),
-  objects: ontology.crudeIDZ.array().or(ontology.crudeIDZ),
-  actions: actionZ.array().or(actionZ),
-});
-export type NewPolicy = z.input<typeof newPolicyZ>;
-
 export const policyZ = z.object({
   key: keyZ,
   subjects: nullableArrayZ(ontology.idZ),
   objects: nullableArrayZ(ontology.idZ),
   actions: nullableArrayZ(actionZ),
 });
-export type Policy = z.infer<typeof policyZ>;
-
-export const ONTOLOGY_TYPE: ontology.ResourceType = "policy";
+export interface Policy extends z.infer<typeof policyZ> {}
 
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key });
-
-export const ALLOW_ALL_ONTOLOGY_TYPE: ontology.ResourceType = "allow_all";
-
-export const ALLOW_ALL_ONTOLOGY_ID = new ontology.ID({
-  type: ALLOW_ALL_ONTOLOGY_TYPE,
-  key: "",
+export const newZ = z.object({
+  key: keyZ.optional(),
+  subjects: ontology.crudeIDZ.array().or(ontology.crudeIDZ),
+  objects: ontology.crudeIDZ.array().or(ontology.crudeIDZ),
+  actions: actionZ.array().or(actionZ),
 });
+export interface New extends z.input<typeof newZ> {}

package/src/access/policy/policy.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.
@@ -94,7 +94,7 @@ describe("Policy", () => {
     });
     describe("many", () => {
       test("with keys", async () => {
-        const policiesToCreate: policy.NewPolicy[] = [
+        const policiesToCreate: policy.New[] = [
           {
             subjects: [{ type: user.ONTOLOGY_TYPE, key: "10" }],
             objects: [
@@ -185,8 +185,8 @@ describe("Policy", () => {
       await client.access.policy.delete([policies[0].key, policies[1].key]);
     });
     test("by subject", async () => {
-      const key1 = id.id();
-      const key2 = id.id();
+      const key1 = id.create();
+      const key2 = id.create();
       const created = await client.access.policy.create([
         {
           subjects: [
@@ -216,10 +216,10 @@ describe("Policy", () => {
   });
   describe("delete", async () => {
     test("one", async () => {
-      const id1 = id.id();
-      const id2 = id.id();
-      const id3 = id.id();
-      const policies: policy.NewPolicy[] = [
+      const id1 = id.create();
+      const id2 = id.create();
+      const id3 = id.create();
+      const policies: policy.New[] = [
         {
           subjects: [
             { type: user.ONTOLOGY_TYPE, key: id1 },
@@ -250,10 +250,10 @@ describe("Policy", () => {
       await client.access.policy.delete(created[1].key);
     });
     test("many", async () => {
-      const id1 = id.id();
-      const id2 = id.id();
-      const id3 = id.id();
-      const policies: policy.NewPolicy[] = [
+      const id1 = id.create();
+      const id2 = id.create();
+      const id3 = id.create();
+      const policies: policy.New[] = [
         {
           subjects: [
             { type: user.ONTOLOGY_TYPE, key: id1 },
@@ -288,7 +288,7 @@ describe("Policy", () => {
 
 describe("privilege", async () => {
   test("new user", async () => {
-    const username = id.id();
+    const username = id.create();
     const user2 = await client.user.create({ username, password: "pwd1" });
     expect(user2).toBeDefined();
     const client2 = new Synnax({
@@ -298,7 +298,7 @@ describe("privilege", async () => {
       password: "pwd1",
     });
     await expect(
-      client2.user.create({ username: id.id(), password: id.id() }),
+      client2.user.create({ username: id.create(), password: id.create() }),
     ).rejects.toThrow(AuthError);
 
     const policy = await client.access.policy.create({
@@ -307,11 +307,11 @@ describe("privilege", async () => {
       actions: ["create"],
     });
 
-    const newUsername = id.id();
+    const newUsername = id.create();
 
     const newUser = await client2.user.create({
       username: newUsername,
-      password: id.id(),
+      password: id.create(),
     });
 
     expect(newUser.username).toEqual(newUsername);
@@ -320,7 +320,7 @@ describe("privilege", async () => {
     await client.access.policy.delete(policy.key);
 
     await expect(
-      client2.user.create({ username: id.id(), password: id.id() }),
+      client2.user.create({ username: id.create(), password: id.create() }),
     ).rejects.toThrow(AuthError);
   });
 });

package/src/access/policy/retriever.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.
@@ -18,7 +18,8 @@ const reqZ = z.object({
   keys: keyZ.array().optional(),
   subjects: ontology.idZ.array().optional(),
 });
-type Request = z.infer<typeof reqZ>;
+interface Request extends z.infer<typeof reqZ> {}
+
 const resZ = z.object({ policies: nullableArrayZ(policyZ) });
 
 const ENDPOINT = "/access/policy/retrieve";

package/src/access/policy/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.
@@ -14,8 +14,8 @@ import { z } from "zod";
 import {
   type Key,
   keyZ,
-  type NewPolicy,
-  newPolicyZ,
+  type New,
+  newZ,
   type Policy,
   policyZ,
 } from "@/access/policy/payload";
@@ -36,8 +36,8 @@ export class Writer {
     this.client = client;
   }
 
-  async create(policies: NewPolicy | NewPolicy[]): Promise<Policy[]> {
-    const parsedPolicies = newPolicyZ.array().parse(toArray(policies));
+  async create(policies: New | New[]): Promise<Policy[]> {
+    const parsedPolicies = newZ.array().parse(toArray(policies));
     const req = parsedPolicies.map((policy) => ({
       objects: toArray(policy.objects),
       actions: toArray(policy.actions),

package/src/auth/auth.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.
@@ -12,7 +12,7 @@ import { URL } from "@synnaxlabs/x/url";
 import { describe, expect, it, test } from "vitest";
 
 import { auth } from "@/auth";
-import { AuthError, InvalidTokenError } from "@/errors";
+import { AuthError, ExpiredTokenError, InvalidTokenError } from "@/errors";
 import { HOST, PORT } from "@/setupspecs";
 import { Transport } from "@/transport";
 
@@ -46,30 +46,34 @@ describe("auth", () => {
     expect(err).toBeInstanceOf(AuthError);
   });
 
-  describe("invalid token retry", async () => {
-    it("should re-authenticate and retry the request", async () => {
-      const transport = new Transport(new URL({ host: HOST, port: PORT }));
-      const client = new auth.Client(transport.unary, {
-        username: "synnax",
-        password: "seldon",
+  describe("token retry", () => {
+    const ERROR_TYPES = [InvalidTokenError, ExpiredTokenError];
+    ERROR_TYPES.forEach((ErrorType) => {
+      it(`should re-authenticate and retry the request for ${ErrorType.name}`, async () => {
+        const transport = new Transport(new URL({ host: HOST, port: PORT }));
+        const client = new auth.Client(transport.unary, {
+          username: "synnax",
+          password: "seldon",
+        });
+        const mw = client.middleware();
+        let isFirst = true;
+        let tkOne: string | undefined;
+        let tkTwo: string | undefined;
+        const [, err] = await mw(DUMMY_CTX, async () => {
+          if (isFirst) {
+            isFirst = false;
+            tkOne = client.token;
+            return [DUMMY_CTX, new ErrorType()];
+          }
+          tkTwo = client.token;
+          return [DUMMY_CTX, null];
+        });
+        expect(err).toBeNull();
+        expect(tkOne).toBeDefined();
+        expect(tkTwo).toBeDefined();
       });
-      const mw = client.middleware();
-      let isFirst = true;
-      let tkOne: string | undefined;
-      let tkTwo: string | undefined;
-      const [, err] = await mw(DUMMY_CTX, async () => {
-        if (isFirst) {
-          isFirst = false;
-          tkOne = client.token;
-          return [DUMMY_CTX, new InvalidTokenError()];
-        }
-        tkTwo = client.token;
-        return [DUMMY_CTX, null];
-      });
-      expect(err).toBeNull();
-      expect(tkOne).toBeDefined();
-      expect(tkTwo).toBeDefined();
     });
+
     it("should fail after MAX_RETRIES", async () => {
       const transport = new Transport(new URL({ host: HOST, port: PORT }));
       const client = new auth.Client(transport.unary, {

package/src/auth/auth.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,19 +10,13 @@
 import { type Middleware, sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { InvalidTokenError } from "@/errors";
+import { ExpiredTokenError, InvalidTokenError } from "@/errors";
 import { user } from "@/user";
 
-const insecureCredentialsZ = z.object({
-  username: z.string(),
-  password: z.string(),
-});
-type InsecureCredentials = z.infer<typeof insecureCredentialsZ>;
+const insecureCredentialsZ = z.object({ username: z.string(), password: z.string() });
+interface InsecureCredentials extends z.infer<typeof insecureCredentialsZ> {}
 
-const tokenResponseZ = z.object({
-  token: z.string(),
-  user: user.userZ,
-});
+const tokenResponseZ = z.object({ token: z.string(), user: user.userZ });
 
 const LOGIN_ENDPOINT = "/auth/login";
 
@@ -37,6 +31,8 @@ const changePasswordReqZ = z.object({
 });
 const changePasswordResZ = z.object({});
 
+const RETRY_ON = [InvalidTokenError, ExpiredTokenError] as const;
+
 export class Client {
   token: string | undefined;
   private readonly client: UnaryClient;
@@ -94,7 +90,7 @@ export class Client {
       }
       reqCtx.params.Authorization = `Bearer ${this.token}`;
       const [resCtx, err] = await next(reqCtx);
-      if (InvalidTokenError.matches(err) && this.retryCount < MAX_RETRIES) {
+      if (RETRY_ON.some((e) => e.matches(err)) && this.retryCount < MAX_RETRIES) {
         this.authenticated = false;
         this.authenticating = undefined;
         this.retryCount += 1;

package/src/auth/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/channel/batchRetriever.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.
@@ -10,42 +10,45 @@
 import { DataType, Rate } from "@synnaxlabs/x/telem";
 import { describe, expect, it, vi } from "vitest";
 
-import { type Params, type Payload } from "@/channel/payload";
-import {
-  analyzeChannelParams,
-  DebouncedBatchRetriever,
-  type RetrieveOptions,
-  type Retriever,
-} from "@/channel/retriever";
+import { channel } from "@/channel";
 
-class MockRetriever implements Retriever {
-  func: (channels: Params, options?: RetrieveOptions) => Promise<Payload[]>;
+class MockRetriever implements channel.Retriever {
+  func: (
+    channels: channel.Params,
+    options?: channel.RetrieveOptions,
+  ) => Promise<channel.Payload[]>;
 
   constructor(
-    func: (channels: Params, options?: RetrieveOptions) => Promise<Payload[]>,
+    func: (
+      channels: channel.Params,
+      options?: channel.RetrieveOptions,
+    ) => Promise<channel.Payload[]>,
   ) {
     this.func = func;
   }
 
-  async search(): Promise<Payload[]> {
+  async search(): Promise<channel.Payload[]> {
     throw new Error("Method not implemented.");
   }
 
-  async page(): Promise<Payload[]> {
+  async page(): Promise<channel.Payload[]> {
     throw new Error("Method not implemented.");
   }
 
-  async retrieve(channels: Params, options?: RetrieveOptions): Promise<Payload[]> {
+  async retrieve(
+    channels: channel.Params,
+    options?: channel.RetrieveOptions,
+  ): Promise<channel.Payload[]> {
     return await this.func(channels, options);
   }
 }
 
-describe("channelRetriever", () => {
+describe("channelchannel.Retriever", () => {
   it("should batch multiple retrieve requests", async () => {
     const called = vi.fn();
-    const base = new MockRetriever(async (batch): Promise<Payload[]> => {
+    const base = new MockRetriever(async (batch): Promise<channel.Payload[]> => {
       called(batch);
-      const { normalized } = analyzeChannelParams(batch);
+      const { normalized } = channel.analyzeParams(batch);
       return normalized.map((key) => ({
         key: key as number,
         name: `channel-${key}`,
@@ -60,7 +63,7 @@ describe("channelRetriever", () => {
         requires: [],
       }));
     });
-    const retriever = new DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(base, 10);
     const res = await Promise.all([
       retriever.retrieve([1]),
       retriever.retrieve([2]),
@@ -72,9 +75,9 @@ describe("channelRetriever", () => {
   });
   it("should only fetch duplicate keys once", async () => {
     const called = vi.fn();
-    const base = new MockRetriever(async (batch): Promise<Payload[]> => {
+    const base = new MockRetriever(async (batch): Promise<channel.Payload[]> => {
       called(batch);
-      const { normalized } = analyzeChannelParams(batch);
+      const { normalized } = channel.analyzeParams(batch);
       return normalized.map((key) => ({
         key: key as number,
         name: `channel-${key}`,
@@ -89,7 +92,7 @@ describe("channelRetriever", () => {
         requires: [],
       }));
     });
-    const retriever = new DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(base, 10);
     const res = await Promise.all([
       retriever.retrieve([1]),
       retriever.retrieve([2]),
@@ -100,10 +103,10 @@ describe("channelRetriever", () => {
     expect(res.map((r) => r.map((c) => c.key))).toEqual([[1], [2], [1, 2]]);
   });
   it("should throw an error if the fetch fails", async () => {
-    const base = new MockRetriever(async (): Promise<Payload[]> => {
+    const base = new MockRetriever(async (): Promise<channel.Payload[]> => {
       throw new Error("failed to fetch");
     });
-    const retriever = new DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(base, 10);
     await expect(retriever.retrieve([1])).rejects.toThrow("failed to fetch");
   });
 });

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

package/src/channel/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.
@@ -22,16 +22,17 @@ import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
 import {
+  channelZ,
   type Key,
   type KeyOrName,
-  type NewPayload,
-  ontologyID as payloadOntologyID,
+  type Name,
+  type New,
+  ONTOLOGY_TYPE,
   type Params,
   type Payload,
-  payload,
 } from "@/channel/payload";
 import {
-  analyzeChannelParams,
+  analyzeParams,
   CacheRetriever,
   ClusterRetriever,
   DebouncedBatchRetriever,
@@ -41,7 +42,7 @@ import {
 import { type Writer } from "@/channel/writer";
 import { ValidationError } from "@/errors";
 import { type framer } from "@/framer";
-import { type ontology } from "@/ontology";
+import { ontology } from "@/ontology";
 import { group } from "@/ontology/group";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
@@ -69,7 +70,7 @@ export class Channel {
    * A human-readable name for the channel. This name is not guaranteed to be
    * unique.
    */
-  readonly name: string;
+  readonly name: Name;
   /**
    * The rate at which the channel samples telemetry. This only applies to fixed rate
    * channels, and will be 0 if the channel is indexed.
@@ -109,7 +110,7 @@ export class Channel {
    */
   readonly virtual: boolean;
   /**
-   * Only used for calculated channels. Specifies the python expression to evaluate
+   * Only used for calculated channels. Specifies the Lua expression used to evaluate
    * the calculated value
    */
   readonly expression: string;
@@ -132,10 +133,7 @@ export class Channel {
     alias,
     expression = "",
     requires = [],
-  }: NewPayload & {
-    frameClient?: framer.Client;
-    density?: CrudeDensity;
-  }) {
+  }: New & { frameClient?: framer.Client; density?: CrudeDensity }) {
     this.key = key;
     this.name = name;
     this.rate = new Rate(rate ?? 0);
@@ -163,7 +161,7 @@ export class Channel {
    * network transportation, but also provided to you as a convenience.
    */
   get payload(): Payload {
-    return payload.parse({
+    return channelZ.parse({
       key: this.key,
       name: this.name,
       rate: this.rate.valueOf(),
@@ -186,7 +184,7 @@ export class Channel {
    * @returns the ontology ID of the channel
    */
   get ontologyID(): ontology.ID {
-    return payloadOntologyID(this.key);
+    return ontologyID(this.key);
   }
 
   /**
@@ -215,9 +213,7 @@ const RETRIEVE_GROUP_ENDPOINT = "/channel/retrieve-group";
 
 const retrieveGroupReqZ = z.object({});
 
-const retrieveGroupResZ = z.object({
-  group: group.groupZ,
-});
+const retrieveGroupResZ = z.object({ group: group.groupZ });
 
 /**
  * The core client class for executing channel operations against a Synnax
@@ -225,7 +221,7 @@ const retrieveGroupResZ = z.object({
  * through the `channels` property of an {@link Synnax} client.
  */
 export class Client implements AsyncTermSearcher<string, Key, Channel> {
-  readonly type = "channel";
+  readonly type = ONTOLOGY_TYPE;
   private readonly frameClient: framer.Client;
   private readonly client: UnaryClient;
   readonly retriever: Retriever;
@@ -278,7 +274,7 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    * });
    * ```
    */
-  async create(channel: NewPayload, options?: CreateOptions): Promise<Channel>;
+  async create(channel: New, options?: CreateOptions): Promise<Channel>;
 
   /**
    * Creates multiple channels with the given properties. The order of the channels
@@ -303,10 +299,10 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    *
    * @param channels
    */
-  async create(channels: NewPayload[], options?: CreateOptions): Promise<Channel[]>;
+  async create(channels: New[], options?: CreateOptions): Promise<Channel[]>;
 
   async create(
-    channels: NewPayload | NewPayload[],
+    channels: New | New[],
     options: CreateOptions = {},
   ): Promise<Channel | Channel[]> {
     const { retrieveIfNameExists = false } = options;
@@ -387,7 +383,7 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    * @param channels - The keys or names of the channels to delete.
    */
   async delete(channels: Params): Promise<void> {
-    const { normalized, variant } = analyzeChannelParams(channels);
+    const { normalized, variant } = analyzeParams(channels);
     if (variant === "keys")
       return await this.writer.delete({ keys: normalized as Key[] });
     return await this.writer.delete({ names: normalized as string[] });
@@ -395,7 +391,6 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
 
   async rename(key: Key, name: string): Promise<void>;
   async rename(keys: Key[], names: string[]): Promise<void>;
-
   async rename(keys: Key | Key[], names: string | string[]): Promise<void> {
     return await this.writer.rename(toArray(keys), toArray(names));
   }
@@ -447,16 +442,18 @@ export const isCalculated = ({ virtual, expression }: Payload): boolean =>
   virtual && expression !== "";
 
 export const resolveCalculatedIndex = async (
-  retrieve: (key: Key) => Promise<Payload>,
+  retrieve: (key: Key) => Promise<Payload | null>,
   channel: Payload,
 ): Promise<Key | null> => {
   if (!isCalculated(channel)) return channel.index;
   for (const required of channel.requires) {
     const requiredChannel = await retrieve(required);
+    if (requiredChannel == null) return null;
     if (!requiredChannel.virtual) return requiredChannel.index;
   }
   for (const required of channel.requires) {
     const requiredChannel = await retrieve(required);
+    if (requiredChannel == null) return null;
     if (isCalculated(requiredChannel)) {
       const index = await resolveCalculatedIndex(retrieve, requiredChannel);
       if (index != null) return index;
@@ -464,3 +461,6 @@ export const resolveCalculatedIndex = async (
   }
   return null;
 };
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: ONTOLOGY_TYPE, key: key.toString() });

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