@synnaxlabs/client 0.45.1 → 0.46.1

package/src/ranger/payload.ts

@@ -7,6 +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 { math } from "@synnaxlabs/x";
 import { TimeRange } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
@@ -23,7 +24,18 @@ export type Params = Key | Name | Keys | Names;
 export const payloadZ = z.object({
   key: keyZ,
   name: nameZ,
-  timeRange: TimeRange.z,
+  timeRange: TimeRange.z
+    .refine(({ isValid }) => isValid, {
+      error: "Time range start time must be before or equal to time range end time",
+    })
+    .refine(({ end }) => end.valueOf() <= math.MAX_INT64, {
+      error:
+        "Time range end time must be less than or equal to the maximum value of an int64",
+    })
+    .refine(({ start }) => start.valueOf() >= math.MIN_INT64, {
+      error:
+        "Time range start time must be greater than or equal to the minimum value of an int64",
+    }),
   color: z.string().optional(),
   labels: label.labelZ
     .array()

package/src/ranger/ranger.spec.ts

@@ -7,16 +7,80 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+import { math, uuid } from "@synnaxlabs/x";
 import { DataType, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, expect, it } from "vitest";
 
 import { NotFoundError } from "@/errors";
-import { type ranger } from "@/ranger";
+import { ranger } from "@/ranger";
 import { createTestClient } from "@/testutil/client";
 
 const client = createTestClient();
 
 describe("Ranger", () => {
+  describe("payload", () => {
+    it("should validate the time range", () => {
+      const payload = ranger.payloadZ.parse({
+        name: "My New One Second Range",
+        key: uuid.create(),
+        timeRange: { start: 0, end: 1 },
+      });
+      expect(payload).toBeDefined();
+      expect(payload.timeRange.start.valueOf()).toBe(0n);
+      expect(payload.timeRange.end.valueOf()).toBe(1n);
+    });
+    it("should not validate the time range if it is invalid", () => {
+      const input = {
+        name: "My New One Second Range",
+        key: uuid.create(),
+        timeRange: { start: 1, end: 0 },
+      };
+      expect(() => ranger.payloadZ.parse(input)).toThrow(
+        "Time range start time must be before or equal to time range end time",
+      );
+    });
+    it("should validate the time range if the end is less than or equal to the maximum value of an int64", () => {
+      const input = {
+        name: "range with end greater than max int64",
+        key: uuid.create(),
+        timeRange: { start: 1, end: math.MAX_INT64 },
+      };
+      const payload = ranger.payloadZ.parse(input);
+      expect(payload).toBeDefined();
+      expect(payload.timeRange.end.valueOf()).toBe(math.MAX_INT64);
+    });
+    it("should not validate the time range if the end is greater than the maximum value of an int64", () => {
+      const input = {
+        name: "range with end greater than max int64",
+        key: uuid.create(),
+        timeRange: { start: 1, end: math.MAX_INT64 + 1n },
+      };
+      expect(() => ranger.payloadZ.parse(input)).toThrow(
+        "Time range end time must be less than or equal to the maximum value of an int64",
+      );
+    });
+    it("should validate the time range if start is greater than the minimum value of an int64", () => {
+      const input = {
+        name: "range with start greater than min int64",
+        key: uuid.create(),
+        timeRange: { start: math.MIN_INT64, end: 0 },
+      };
+      const payload = ranger.payloadZ.parse(input);
+      expect(payload).toBeDefined();
+      expect(payload.timeRange.start.valueOf()).toBe(math.MIN_INT64);
+      expect(payload.timeRange.end.valueOf()).toBe(0n);
+    });
+    it("should not validate the time range if start is less than the minimum value of an int64", () => {
+      const input = {
+        name: "range with start less than min int64",
+        key: uuid.create(),
+        timeRange: { start: -1n * 2n ** 63n - 1n, end: 0 },
+      };
+      expect(() => ranger.payloadZ.parse(input)).toThrow(
+        "Time range start time must be greater than or equal to the minimum value of an int64",
+      );
+    });
+  });
   describe("create", () => {
     it("should create a single range", async () => {
       const timeRange = TimeStamp.now().spanRange(TimeSpan.seconds(1));

package/src/status/client.ts

@@ -0,0 +1,129 @@
+// 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/array";
+import z from "zod";
+
+import { label } from "@/label";
+import { ontology } from "@/ontology";
+import { type Key, keyZ, type New, newZ, type Status, statusZ } from "@/status/payload";
+import { checkForMultipleOrNoResults } from "@/util/retrieve";
+
+const setReqZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
+  detailsSchema?: DetailsSchema,
+) =>
+  z.object({
+    parent: ontology.idZ.optional(),
+    statuses: newZ(detailsSchema).array(),
+  });
+const setResZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
+  detailsSchema?: DetailsSchema,
+) => z.object({ statuses: statusZ(detailsSchema).array() });
+const deleteReqZ = z.object({ keys: keyZ.array() });
+const emptyResZ = z.object({});
+
+const SET_ENDPOINT = "/status/set";
+const DELETE_ENDPOINT = "/status/delete";
+const RETRIEVE_ENDPOINT = "/status/retrieve";
+
+const retrieveRequestZ = z.object({
+  keys: keyZ.array().optional(),
+  searchTerm: z.string().optional(),
+  offset: z.number().optional(),
+  limit: z.number().optional(),
+  includeLabels: z.boolean().optional(),
+  hasLabels: label.keyZ.array().optional(),
+});
+
+const singleRetrieveArgsZ = z
+  .object({ key: keyZ, includeLabels: z.boolean().optional() })
+  .transform(({ key, includeLabels }) => ({ keys: [key], includeLabels }));
+
+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 retrieveResponseZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
+  detailsSchema?: DetailsSchema,
+) => z.object({ statuses: array.nullableZ(statusZ(detailsSchema)) });
+
+export interface SetOptions {
+  parent?: ontology.ID;
+}
+
+export class Client {
+  readonly type: string = "status";
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async retrieve<DetailsSchema extends z.ZodType>(
+    args: SingleRetrieveArgs & { detailsSchema?: DetailsSchema },
+  ): Promise<Status<DetailsSchema>>;
+  async retrieve(args: SingleRetrieveArgs): Promise<Status>;
+  async retrieve(args: MultiRetrieveArgs): Promise<Status[]>;
+  async retrieve<DetailsSchema extends z.ZodType = z.ZodNever>(
+    args: RetrieveArgs & { detailsSchema?: DetailsSchema },
+  ): Promise<Status<DetailsSchema> | Status<DetailsSchema>[]> {
+    const isSingle = "key" in args;
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      args,
+      retrieveArgsZ,
+      retrieveResponseZ<DetailsSchema>(args.detailsSchema),
+    );
+    checkForMultipleOrNoResults("Status", args, res.statuses, isSingle);
+    const statuses = res.statuses as unknown as Status<DetailsSchema>[];
+    return isSingle ? statuses[0] : statuses;
+  }
+
+  async set<DetailsSchema extends z.ZodType>(
+    status: New<DetailsSchema>,
+    opts?: SetOptions & { detailsSchema?: DetailsSchema },
+  ): Promise<Status<DetailsSchema>>;
+  async set(status: New, opts?: SetOptions): Promise<Status>;
+  async set(statuses: New[], opts?: SetOptions): Promise<Status[]>;
+  async set<DetailsSchema extends z.ZodType = z.ZodNever>(
+    statuses: New<DetailsSchema> | New<DetailsSchema>[],
+    opts: SetOptions & { detailsSchema?: DetailsSchema } = {},
+  ): Promise<Status<DetailsSchema> | Status<DetailsSchema>[]> {
+    const isMany = Array.isArray(statuses);
+    const res = await sendRequired<
+      ReturnType<typeof setReqZ<DetailsSchema>>,
+      ReturnType<typeof setResZ<DetailsSchema>>
+    >(
+      this.client,
+      SET_ENDPOINT,
+      {
+        statuses: array.toArray(statuses),
+        parent: opts.parent,
+      },
+      setReqZ(opts.detailsSchema),
+      setResZ(opts.detailsSchema),
+    );
+    const created = res.statuses as unknown as Status<DetailsSchema>[];
+    return isMany ? created : created[0];
+  }
+
+  async delete(keys: Key | Key[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof emptyResZ>(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: array.toArray(keys) },
+      deleteReqZ,
+      emptyResZ,
+    );
+  }
+}

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

package/src/status/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 status from "@/status/external";

package/src/status/payload.ts

@@ -0,0 +1,35 @@
+// 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 { status } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type ontology } from "@/ontology";
+
+export const keyZ = z.string();
+export type Key = z.infer<typeof keyZ>;
+
+export type Params = Key | Key[];
+
+export const statusZ = status.statusZ;
+
+export const newZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
+  detailsSchema?: DetailsSchema,
+) => statusZ(detailsSchema).omit({ labels: true }).partial({ key: true });
+
+export type New<DetailsSchema extends z.ZodType = z.ZodNever> = z.input<
+  ReturnType<typeof newZ<DetailsSchema>>
+>;
+
+export type Status<Details = never> = status.Status<Details>;
+
+export const SET_CHANNEL_NAME = "sy_status_set";
+export const DELETE_CHANNEL_NAME = "sy_status_delete";
+
+export const ontologyID = (key: Key): ontology.ID => ({ type: "status", key });

package/src/status/status.spec.ts

@@ -0,0 +1,352 @@
+// 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 { TimeStamp, uuid } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+import z from "zod";
+
+import { ontology } from "@/ontology";
+import { group } from "@/ontology/group";
+import { status } from "@/status";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("Status", () => {
+  describe("set", () => {
+    it("should create a new status", async () => {
+      const s = await client.statuses.set({
+        name: "Test Status",
+        key: "test-status-1",
+        variant: "info",
+        message: "This is a test status",
+        time: TimeStamp.now(),
+      });
+      expect(s.key).toBe("test-status-1");
+      expect(s.name).toBe("Test Status");
+      expect(s.variant).toBe("info");
+      expect(s.message).toBe("This is a test status");
+    });
+
+    it("should update an existing status", async () => {
+      const key = "test-status-update";
+      await client.statuses.set({
+        name: "Original Status",
+        key,
+        variant: "info",
+        message: "Original message",
+        time: TimeStamp.now(),
+      });
+
+      const updated = await client.statuses.set({
+        name: "Updated Status",
+        key,
+        variant: "warning",
+        message: "Updated message",
+        time: TimeStamp.now(),
+      });
+
+      expect(updated.key).toBe(key);
+      expect(updated.name).toBe("Updated Status");
+      expect(updated.variant).toBe("warning");
+      expect(updated.message).toBe("Updated message");
+    });
+
+    it("should create multiple statuses at once", async () => {
+      const statuses = await client.statuses.set([
+        {
+          name: "Status 1",
+          key: "batch-1",
+          variant: "success",
+          message: "First batch status",
+          time: TimeStamp.now(),
+        },
+        {
+          name: "Status 2",
+          key: "batch-2",
+          variant: "error",
+          message: "Second batch status",
+          time: TimeStamp.now(),
+        },
+      ]);
+
+      expect(statuses).toHaveLength(2);
+      expect(statuses[0].key).toBe("batch-1");
+      expect(statuses[1].key).toBe("batch-2");
+    });
+
+    it("should set a status with a parent", async () => {
+      const parentGroup = await client.ontology.groups.create({
+        parent: ontology.ROOT_ID,
+        name: "Parent Group",
+      });
+      const parentOntologyID = group.ontologyID(parentGroup.key);
+      const s = await client.statuses.set(
+        {
+          name: "Child Status",
+          key: "child-status",
+          variant: "info",
+          message: "Status with parent",
+          time: TimeStamp.now(),
+        },
+        { parent: parentOntologyID },
+      );
+
+      expect(s.key).toBe("child-status");
+
+      const resources = await client.ontology.retrieveChildren(parentOntologyID);
+
+      const statusResource = resources.find((r) => r.id.key === "child-status");
+      expect(statusResource).toBeDefined();
+    });
+  });
+
+  describe("retrieve", () => {
+    it("should retrieve a status by key", async () => {
+      const created = await client.statuses.set({
+        name: "Retrieve Test",
+        key: "retrieve-test",
+        variant: "loading",
+        message: "Test retrieve",
+        time: TimeStamp.now(),
+      });
+
+      const retrieved = await client.statuses.retrieve({ key: "retrieve-test" });
+      expect(retrieved.key).toBe(created.key);
+      expect(retrieved.name).toBe(created.name);
+      expect(retrieved.variant).toBe(created.variant);
+    });
+
+    it("should retrieve multiple statuses by keys", async () => {
+      await client.statuses.set([
+        {
+          name: "Multi 1",
+          key: "multi-1",
+          variant: "info",
+          message: "First",
+          time: TimeStamp.now(),
+        },
+        {
+          name: "Multi 2",
+          key: "multi-2",
+          variant: "warning",
+          message: "Second",
+          time: TimeStamp.now(),
+        },
+      ]);
+
+      const statuses = await client.statuses.retrieve({
+        keys: ["multi-1", "multi-2"],
+      });
+
+      expect(statuses).toHaveLength(2);
+      const keys = statuses.map((s) => s.key);
+      expect(keys).toContain("multi-1");
+      expect(keys).toContain("multi-2");
+    });
+
+    it("should search for statuses", async () => {
+      const uniqueName = `SearchableStatus_${Date.now()}`;
+      await client.statuses.set({
+        name: uniqueName,
+        key: `searchable-${Date.now()}`,
+        variant: "info",
+        message: "Searchable status",
+        time: TimeStamp.now(),
+      });
+
+      const results = await client.statuses.retrieve({
+        searchTerm: uniqueName,
+      });
+
+      expect(results.length).toBeGreaterThanOrEqual(1);
+      expect(results.some((s) => s.name === uniqueName)).toBe(true);
+    });
+
+    it("should paginate results", async () => {
+      // Create several statuses
+      const keys = [];
+      for (let i = 0; i < 5; i++) {
+        const key = `paginate-${i}-${Date.now()}`;
+        keys.push(key);
+        await client.statuses.set({
+          name: `Paginate ${i}`,
+          key,
+          variant: "info",
+          message: `Message ${i}`,
+          time: TimeStamp.now(),
+        });
+      }
+
+      // Retrieve with limit
+      const page1 = await client.statuses.retrieve({
+        keys,
+        limit: 2,
+        offset: 0,
+      });
+
+      const page2 = await client.statuses.retrieve({
+        keys,
+        limit: 2,
+        offset: 2,
+      });
+
+      expect(page1).toHaveLength(2);
+      expect(page2).toHaveLength(2);
+
+      // Ensure no overlap
+      const page1Keys = page1.map((s) => s.key);
+      const page2Keys = page2.map((s) => s.key);
+      expect(page1Keys.some((k) => page2Keys.includes(k))).toBe(false);
+    });
+
+    it("should retrieve a status with a details schema", async () => {
+      const detailsSchema = z.object({
+        name: z.string(),
+        key: z.string(),
+      });
+      const s = await client.statuses.set<typeof detailsSchema>({
+        name: "Details Schema",
+        key: "details-schema",
+        variant: "info",
+        message: "Test",
+        time: TimeStamp.now(),
+        details: {
+          name: "Details Schema",
+          key: "details-schema",
+        },
+      });
+      const retrieved = await client.statuses.retrieve<typeof detailsSchema>({
+        key: s.key,
+        detailsSchema,
+      });
+      expect(retrieved.key).toBe(s.key);
+      expect(retrieved.name).toBe(s.name);
+      expect(retrieved.details).toBeDefined();
+      expect(retrieved.details.name).toBe(s.details.name);
+      expect(retrieved.details.key).toBe(s.details.key);
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete a status by key", async () => {
+      const s = await client.statuses.set({
+        name: "To Delete",
+        key: "delete-me",
+        variant: "error",
+        message: "Will be deleted",
+        time: TimeStamp.now(),
+      });
+
+      await client.statuses.delete(s.key);
+
+      await expect(
+        async () => await client.statuses.retrieve({ key: s.key }),
+      ).rejects.toThrow();
+    });
+
+    it("should delete multiple statuses", async () => {
+      const keys = ["del-1", "del-2", "del-3"];
+      await client.statuses.set(
+        keys.map((key) => ({
+          name: `Delete ${key}`,
+          key,
+          variant: "info" as status.Status["variant"],
+          message: "To be deleted",
+          time: TimeStamp.now(),
+        })),
+      );
+
+      await client.statuses.delete(keys);
+
+      // Try to retrieve them - should get empty or error
+      const results = await client.statuses.retrieve({ keys }).catch(() => []);
+      expect(results).toHaveLength(0);
+    });
+
+    it("should be idempotent", async () => {
+      const key = "idempotent-delete";
+
+      // Delete a non-existent status - should not throw
+      await expect(client.statuses.delete(key)).resolves.not.toThrow();
+
+      // Create and delete
+      await client.statuses.set({
+        name: "Idempotent",
+        key,
+        variant: "info",
+        message: "Test",
+        time: TimeStamp.now(),
+      });
+
+      await client.statuses.delete(key);
+
+      // Delete again - should not throw
+      await expect(client.statuses.delete(key)).resolves.not.toThrow();
+    });
+  });
+
+  describe("with labels", () => {
+    it("should correctly retrieve a status with labels attached", async () => {
+      const label1 = await client.labels.create({
+        name: "Label 1",
+        color: "#0000FF",
+      });
+      const label2 = await client.labels.create({
+        name: "Label 2",
+        color: "#FF0000",
+      });
+      const stat = await client.statuses.set({
+        name: "Idempotent",
+        key: uuid.create(),
+        variant: "info",
+        message: "Test",
+        time: TimeStamp.now(),
+      });
+      await client.labels.label(status.ontologyID(stat.key), [label1.key, label2.key], {
+        replace: true,
+      });
+
+      const retrievedStat = await client.statuses.retrieve({
+        key: stat.key,
+        includeLabels: true,
+      });
+      expect(retrievedStat.key).toEqual(stat.key);
+      expect(retrievedStat.labels).toHaveLength(2);
+    });
+  });
+
+  describe("status variants", () => {
+    it("should support all status variants", async () => {
+      const variants: status.Status["variant"][] = [
+        "success",
+        "info",
+        "warning",
+        "error",
+        "loading",
+        "disabled",
+      ];
+
+      const statuses = await client.statuses.set(
+        variants.map((variant) => ({
+          name: `Variant ${variant}`,
+          key: `variant-${variant}-${Date.now()}`,
+          variant,
+          message: `Testing ${variant} variant`,
+          time: TimeStamp.now(),
+        })),
+      );
+
+      expect(statuses).toHaveLength(variants.length);
+      statuses.forEach((s, i) => {
+        expect(s.variant).toBe(variants[i]);
+      });
+    });
+  });
+});

package/src/user/client.ts

@@ -14,7 +14,6 @@ import { z } from "zod";
 import { MultipleFoundError, NotFoundError } from "@/errors";
 import { type ontology } from "@/ontology";
 import { type Key, keyZ, type New, newZ, type User, userZ } from "@/user/payload";
-import { nullableArrayZ } from "@/util/zod";
 
 const retrieveRequestZ = z.object({
   keys: keyZ.array().optional(),
@@ -54,7 +53,7 @@ export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
 
 export interface RetrieveRequest extends z.infer<typeof retrieveRequestZ> {}
 
-const retrieveResZ = z.object({ users: nullableArrayZ(userZ) });
+const retrieveResZ = z.object({ users: array.nullableZ(userZ) });
 
 const createReqZ = z.object({ users: newZ.array() });
 const createResZ = z.object({ users: userZ.array() });

package/src/user/payload.ts

@@ -14,7 +14,7 @@ export type Key = z.infer<typeof keyZ>;
 
 export const userZ = z.object({
   key: keyZ,
-  username: z.string().min(1),
+  username: z.string().min(1, "Username is required"),
   // defaults for firstName, lastName, and rootUser are done to give compatibility with
   // servers running v0.30.x and earlier. These defaults should be removed in a future
   // release.