@synnaxlabs/client 0.53.1 → 0.54.1

package/src/arc/module/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 module from "@/arc/module/types.gen";

package/src/arc/module/types.gen.ts

@@ -0,0 +1,18 @@
+// Copyright 2026 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { type z } from "zod";
+
+import { compiler } from "@/arc/compiler";
+import { ir } from "@/arc/ir";
+
+export const moduleZ = ir.irZ.extend(compiler.outputZ.shape);
+export interface Module extends z.infer<typeof moduleZ> {}

package/src/arc/program/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 program from "@/arc/program/types.gen";

package/src/arc/program/types.gen.ts

@@ -0,0 +1,18 @@
+// Copyright 2026 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { type z } from "zod";
+
+import { compiler } from "@/arc/compiler";
+import { ir } from "@/arc/ir";
+
+export const programZ = ir.irZ.extend(compiler.outputZ.shape);
+export interface Program extends z.infer<typeof programZ> {}

package/src/arc/text/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 text from "@/arc/text/types.gen";

package/src/arc/text/types.gen.ts

@@ -0,0 +1,19 @@
+// Copyright 2026 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { z } from "zod";
+
+/** Text is text-based Arc source code with optional parsed AST for compilation. */
+export const textZ = z.object({
+  /** raw is the raw Arc source code in text form. */
+  raw: z.string(),
+});
+export interface Text extends z.infer<typeof textZ> {}

package/src/arc/types/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 types from "@/arc/types/types.gen";

package/src/arc/types/types.gen.ts

@@ -0,0 +1,132 @@
+// Copyright 2026 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { array, zod } from "@synnaxlabs/x";
+import { z } from "zod";
+
+export enum Kind {
+  invalid = 0,
+  u8 = 1,
+  u16 = 2,
+  u32 = 3,
+  u64 = 4,
+  i8 = 5,
+  i16 = 6,
+  i32 = 7,
+  i64 = 8,
+  f32 = 9,
+  f64 = 10,
+  string = 11,
+  chan = 14,
+  series = 15,
+  variable = 16,
+  numeric_constant = 17,
+  integer_constant = 18,
+  float_constant = 19,
+  exact_integer_float_constant = 20,
+  function = 21,
+  sequence = 22,
+  stage = 23,
+}
+export const kindZ = z.enum(Kind);
+
+export enum ChanDirection {
+  none = 0,
+  read = 1,
+  write = 2,
+}
+export const chanDirectionZ = z.enum(ChanDirection);
+
+/** Channels contains channel declarations for reading from and writing to Synnax channels. */
+export const channelsZ = z.object({
+  /** read contains readable channel indices mapped to parameter names. */
+  read: z.record(z.uint32(), z.string()),
+  /** write contains writable channel indices mapped to parameter names. */
+  write: z.record(z.uint32(), z.string()),
+});
+export interface Channels extends z.infer<typeof channelsZ> {}
+
+/** Dimensions contains physical dimension exponents for dimensional analysis (SI base quantities). */
+export const dimensionsZ = z.object({
+  /** length is the length dimension exponent (meters). */
+  length: zod.int8,
+  /** mass is the mass dimension exponent (kilograms). */
+  mass: zod.int8,
+  /** time is the time dimension exponent (seconds). */
+  time: zod.int8,
+  /** current is the electric current dimension exponent (amperes). */
+  current: zod.int8,
+  /** temperature is the temperature dimension exponent (kelvin). */
+  temperature: zod.int8,
+  /** angle is the angle dimension exponent (radians). */
+  angle: zod.int8,
+  /** count is the count dimension exponent (dimensionless quantity). */
+  count: zod.int8,
+  /** data is the data size dimension exponent (bytes). */
+  data: zod.int8,
+});
+export interface Dimensions extends z.infer<typeof dimensionsZ> {}
+
+/** Unit is a physical unit with dimensions and scale factor for unit-aware computation. */
+export const unitZ = z.object({
+  /** dimensions contains physical dimension exponents. */
+  dimensions: dimensionsZ,
+  /** scale is the scale factor relative to SI base units. */
+  scale: z.number(),
+  /** name is the unit name (e.g., 'psi', 'ns', 'm/s'). */
+  name: z.string(),
+});
+export interface Unit extends z.infer<typeof unitZ> {}
+
+/** FunctionProperties contains common parameter definitions for function-like types. */
+export const functionPropertiesZ = z.object({
+  /** inputs contains input parameter definitions. */
+  get inputs(): z.ZodOptional<typeof paramsZ> {
+    return paramsZ.optional();
+  },
+  /** outputs contains output parameter definitions. */
+  get outputs(): z.ZodOptional<typeof paramsZ> {
+    return paramsZ.optional();
+  },
+  /** config contains configuration parameter definitions. */
+  get config(): z.ZodOptional<typeof paramsZ> {
+    return paramsZ.optional();
+  },
+});
+export interface FunctionProperties extends z.infer<typeof functionPropertiesZ> {}
+
+export const typeZ = functionPropertiesZ.extend({
+  kind: kindZ,
+  name: z.string(),
+  get elem(): z.ZodOptional<typeof typeZ> {
+    return typeZ.optional();
+  },
+  unit: unitZ.optional(),
+  get constraint(): z.ZodOptional<typeof typeZ> {
+    return typeZ.optional();
+  },
+  chanDirection: chanDirectionZ.optional(),
+});
+export interface Type extends z.infer<typeof typeZ> {}
+
+/** Param is a named, typed parameter with optional default value. */
+export const paramZ = z.object({
+  /** name is the parameter name. */
+  name: z.string(),
+  /** type is the parameter type. */
+  type: typeZ,
+  /** value is an optional default value. */
+  value: z.unknown().optional(),
+});
+export interface Param extends z.infer<typeof paramZ> {}
+
+export const paramsZ = array.nullishToEmpty(paramZ);
+export type Params = z.infer<typeof paramsZ>;

package/src/arc/types.gen.ts

@@ -0,0 +1,85 @@
+// Copyright 2026 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { status } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { graph } from "@/arc/graph";
+import { program } from "@/arc/program";
+import { text } from "@/arc/text";
+import { ontology } from "@/ontology";
+
+export const MODES = ["text", "graph"] as const;
+export const modeZ = z.enum(MODES);
+export type Mode = z.infer<typeof modeZ>;
+
+/** StatusDetails contains Arc-specific status details for execution state. */
+export const statusDetailsZ = z.object({
+  /** running indicates whether the Arc module is currently executing. */
+  running: z.boolean(),
+});
+export interface StatusDetails extends z.infer<typeof statusDetailsZ> {}
+
+export const keyZ = z.uuid();
+export type Key = z.infer<typeof keyZ>;
+
+export const statusZ = status.statusZ({ details: statusDetailsZ });
+export type Status = z.infer<typeof statusZ>;
+
+/** New contains parameters for creating a new Arc module. */
+export const newZ = z.object({
+  /**
+   * key is an optional key for the module. If not provided, one will be
+   * automatically assigned.
+   */
+  key: keyZ.optional(),
+  /** name is a human-readable name for the module. */
+  name: z.string(),
+  /**
+   * mode specifies the representation mode for this module.
+   * Either "text" for text-based Arc code or "graph" for visual dataflow.
+   */
+  mode: modeZ,
+  /** graph is the visual dataflow graph representation. */
+  graph: graph.graphZ,
+  /** text is the text-based Arc source code. */
+  text: text.textZ,
+});
+export interface New extends z.input<typeof newZ> {}
+
+/**
+ * Arc is an Arc module combining visual graph representation and text-based
+ * source code for reactive control systems. Compiles to WebAssembly for
+ * sandboxed execution.
+ */
+export const arcZ = z.object({
+  /** key is the unique identifier for this module. */
+  key: keyZ,
+  /** name is a human-readable name for the module. */
+  name: z.string(),
+  /**
+   * mode specifies the representation mode for this module.
+   * Either "text" for text-based Arc code or "graph" for visual dataflow.
+   */
+  mode: modeZ,
+  /** graph is the visual dataflow graph representation of the module. */
+  graph: graph.graphZ,
+  /** text is the text-based Arc source code. */
+  text: text.textZ,
+  /** program is the compiled module output including IR and WebAssembly bytecode. */
+  program: program.programZ.optional(),
+  /** status is the current execution status of the module. */
+  status: statusZ.optional(),
+});
+export interface Arc extends z.infer<typeof arcZ> {}
+
+export const ontologyID = ontology.createIDFactory<Key>("arc");
+export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/channel/client.ts

@@ -20,18 +20,7 @@ import {
 } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import {
-  type Key,
-  type KeyOrName,
-  keyZ,
-  type New,
-  ontologyID,
-  type Operation,
-  type Params,
-  type Payload,
-  payloadZ,
-  type Status,
-} from "@/channel/payload";
+import { type Params } from "@/channel/payload";
 import {
   analyzeParams,
   CacheRetriever,
@@ -41,6 +30,16 @@ import {
   type Retriever,
   type RetrieveRequest,
 } from "@/channel/retriever";
+import {
+  type Key,
+  keyZ,
+  type Name,
+  type New,
+  ontologyID,
+  type Operation,
+  type Payload,
+  payloadZ,
+} from "@/channel/types.gen";
 import { type Writer } from "@/channel/writer";
 import { ValidationError } from "@/errors";
 import { type framer } from "@/framer";
@@ -117,7 +116,7 @@ export class Channel {
   /**
    * The status of the channel.
    */
-  readonly status?: Status;
+  readonly status?: status.Status;
 
   constructor({
     dataType,
@@ -137,7 +136,7 @@ export class Channel {
     internal?: boolean;
     frameClient?: framer.Client;
     density?: CrudeDensity;
-    status?: status.Crude;
+    status?: status.New;
     operations?: Operation[];
   }) {
     this.key = keyZ.parse(key);
@@ -344,7 +343,7 @@ export class Client {
    * const channel = await client.channels.retrieve(1);
    * ```
    */
-  async retrieve(params: KeyOrName, options?: RetrieveOptions): Promise<Channel>;
+  async retrieve(params: Key | Name, options?: RetrieveOptions): Promise<Channel>;
 
   /**
    * Retrieves multiple channels from the database using the provided keys or the

package/src/channel/external.ts

@@ -10,4 +10,5 @@
 export * from "@/channel/client";
 export * from "@/channel/payload";
 export * from "@/channel/retriever";
+export * from "@/channel/types.gen";
 export * from "@/channel/writer";

package/src/channel/payload.spec.ts

@@ -10,7 +10,7 @@
 import { DataType } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 
-import { escapeInvalidName, nameZ, newZ } from "@/channel/payload";
+import { channel } from "@/channel";
 
 describe("nameZ", () => {
   describe("valid names", () => {
@@ -31,7 +31,7 @@ describe("nameZ", () => {
     ];
     validNames.forEach(([name, description]) => {
       it(`should accept ${name} (${description})`, () => {
-        const result = nameZ.safeParse(name);
+        const result = channel.nameZ.safeParse(name);
         expect(result.success).toBe(true);
       });
     });
@@ -39,9 +39,9 @@ describe("nameZ", () => {
 
   describe("invalid names", () => {
     it("should reject empty string", () => {
-      const result = nameZ.safeParse("");
+      const result = channel.nameZ.safeParse("");
       expect(result.success).toBe(false);
-      expect(result.error?.issues[0].message).toContain("Name must not be empty");
+      expect(result.error?.issues[0].message).toContain("Name is required");
     });
   });
 });
@@ -55,17 +55,17 @@ describe("newZ", () => {
 
   describe("name validation", () => {
     it("should accept valid channel names", () => {
-      const result = newZ.safeParse(validNewChannel);
+      const result = channel.newZ.safeParse(validNewChannel);
       expect(result.success).toBe(true);
     });
 
     it("should reject empty name", () => {
-      const result = newZ.safeParse({ ...validNewChannel, name: "" });
+      const result = channel.newZ.safeParse({ ...validNewChannel, name: "" });
       expect(result.success).toBe(false);
     });
 
     it("should accept name with underscores", () => {
-      const result = newZ.safeParse({
+      const result = channel.newZ.safeParse({
         ...validNewChannel,
         name: "sensor_temp_123",
       });
@@ -73,42 +73,45 @@ describe("newZ", () => {
     });
 
     it("should accept name starting with underscore", () => {
-      const result = newZ.safeParse({ ...validNewChannel, name: "_private_sensor" });
+      const result = channel.newZ.safeParse({
+        ...validNewChannel,
+        name: "_private_sensor",
+      });
       expect(result.success).toBe(true);
     });
   });
 });
 describe("escapeInvalidName", () => {
   it("should escape invalid name", () => {
-    const result = escapeInvalidName("sensor-temp");
+    const result = channel.escapeInvalidName("sensor-temp");
     expect(result).toBe("sensor_temp");
   });
   it("should escape name starting with digit", () => {
-    const result = escapeInvalidName("1sensor");
+    const result = channel.escapeInvalidName("1sensor");
     expect(result).toBe("_1sensor");
   });
   it("should escape name with spaces", () => {
-    const result = escapeInvalidName("my channel");
+    const result = channel.escapeInvalidName("my channel");
     expect(result).toBe("my_channel");
   });
   it("should escape name with special characters", () => {
-    const result = escapeInvalidName("sensor!");
+    const result = channel.escapeInvalidName("sensor!");
     expect(result).toBe("sensor_");
   });
   it("should escape name with hyphens", () => {
-    const result = escapeInvalidName("sensor-temp");
+    const result = channel.escapeInvalidName("sensor-temp");
     expect(result).toBe("sensor_temp");
   });
   it("should escape name with dots", () => {
-    const result = escapeInvalidName("sensor.temp");
+    const result = channel.escapeInvalidName("sensor.temp");
     expect(result).toBe("sensor_temp");
   });
   it("should allow an empty string by default", () => {
-    const result = escapeInvalidName("");
+    const result = channel.escapeInvalidName("");
     expect(result).toBe("");
   });
   it("should change empty string to underscore when changeEmptyToUnderscore is true", () => {
-    const result = escapeInvalidName("", true);
+    const result = channel.escapeInvalidName("", true);
     expect(result).toBe("_");
   });
 });

package/src/channel/payload.ts

@@ -7,89 +7,21 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import {
-  array,
-  type CrudeDataType,
-  DataType,
-  math,
-  status,
-  TimeSpan,
-  zod,
-} from "@synnaxlabs/x";
+import { zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
+import {
+  type Key,
+  keyZ,
+  type Name,
+  nameZ,
+  ontologyID,
+  type Payload,
+  payloadZ,
+} from "@/channel/types.gen";
 import { ontology } from "@/ontology";
 
-const errorMessage = "Channel key must be a valid uint32.";
-export const keyZ = z.uint32().or(
-  z
-    .string()
-    .refine((val) => !isNaN(Number(val)), { message: errorMessage })
-    .transform(Number)
-    .refine((val) => val < math.MAX_UINT32, { message: errorMessage }),
-);
-export type Key = z.infer<typeof keyZ>;
-export type Keys = Key[];
-export const nameZ = z.string().min(1, "Name must not be empty");
-export type KeyOrName = Key | string;
-export type KeysOrNames = Keys | string[];
-export type PrimitiveParams = KeyOrName | KeysOrNames;
-
-export const OPERATION_TYPES = ["min", "max", "avg", "none"] as const;
-export const operationType = z.enum(OPERATION_TYPES);
-export type OperationType = z.infer<typeof operationType>;
-
-export const operationZ = z.object({
-  type: operationType,
-  resetChannel: keyZ.optional(),
-  duration: TimeSpan.z.optional(),
-});
-
-export type Operation = z.infer<typeof operationZ>;
-
-export const statusZ = status.statusZ();
-export type Status = z.infer<typeof statusZ>;
-
-export const calculationStatusDetailsZ = z.object({ channel: keyZ });
-export type CalculationStatusDetails = z.infer<typeof calculationStatusDetailsZ>;
-export const calculationStatusZ = status.statusZ(calculationStatusDetailsZ);
-export type CalculationStatus = z.infer<typeof calculationStatusZ>;
-
-export const statusKey = (key: Key): string => ontology.idToString(ontologyID(key));
-export const payloadZ = z.object({
-  name: z.string(),
-  key: keyZ,
-  dataType: DataType.z,
-  leaseholder: zod.uint12,
-  index: keyZ,
-  isIndex: z.boolean(),
-  internal: z.boolean(),
-  virtual: z.boolean(),
-  alias: z.string().optional(),
-  expression: z.string().default(""),
-  status: statusZ.optional(),
-  operations: array.nullableZ(operationZ),
-});
-export interface Payload extends z.infer<typeof payloadZ> {}
-
-export const newZ = payloadZ.extend({
-  key: keyZ.optional(),
-  name: nameZ,
-  leaseholder: zod.uint12.optional(),
-  index: keyZ.optional(),
-  isIndex: z.boolean().optional(),
-  internal: z.boolean().default(false),
-  virtual: z.boolean().default(false),
-  expression: z.string().default(""),
-  operations: array.nullableZ(operationZ).optional(),
-});
-
-export interface New extends Omit<
-  z.input<typeof newZ>,
-  "dataType" | "status" | "internal"
-> {
-  dataType: CrudeDataType;
-}
+export type PrimitiveParams = Key | Name | Key[] | Name[];
 
 export const paramsZ = z.union([
   zod.toArray(keyZ),
@@ -98,9 +30,6 @@ export const paramsZ = z.union([
 ]);
 export type Params = PrimitiveParams | Payload | Payload[];
 
-export const ontologyID = ontology.createIDFactory<Key>("channel");
-export const TYPE_ONTOLOGY_ID = ontologyID(0);
-
 const CHAR_REGEX = /[a-zA-Z0-9_]/;
 
 const VALID_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -117,3 +46,6 @@ export const escapeInvalidName = (name: string, changeEmptyToUnderscore = false)
   if (result[0].match(/^\d/)) result = `_${result}`;
   return result;
 };
+
+export const statusKey = (channel: Key): string =>
+  ontology.idToString(ontologyID(channel));