@synnaxlabs/client 0.56.2 → 0.57.1

package/src/http/external.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 * from "@/http/types.gen";

package/src/{cluster → http}/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 cluster from "@/cluster/types.gen";
+export * as http from "@/http/external";

package/src/http/types.gen.ts

@@ -0,0 +1,245 @@
+// 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 { id } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { channel } from "@/channel";
+import { device } from "@/device";
+import { task } from "@/task";
+
+export const TIME_FORMATS = [
+  "iso8601",
+  "unix_sec",
+  "unix_ms",
+  "unix_us",
+  "unix_ns",
+] as const;
+export const timeFormatZ = z.enum(TIME_FORMATS);
+export type TimeFormat = z.infer<typeof timeFormatZ>;
+
+export const METHODS = [
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "OPTIONS",
+  "TRACE",
+  "CONNECT",
+] as const;
+export const methodZ = z.enum(METHODS);
+export type Method = z.infer<typeof methodZ>;
+
+export const JSON_TYPES = ["number", "string", "boolean"] as const;
+export const jsonTypeZ = z.enum(JSON_TYPES);
+export type JSONType = z.infer<typeof jsonTypeZ>;
+
+export const GENERATOR_TYPES = ["uuid", "timestamp"] as const;
+export const generatorTypeZ = z.enum(GENERATOR_TYPES);
+export type GeneratorType = z.infer<typeof generatorTypeZ>;
+
+/** Header is a single HTTP header sent with a request. */
+export const headerZ = z.object({
+  /** name is the header name, unique within a request. */
+  name: z.string().default(""),
+  /** value is the header value. */
+  value: z.string().default(""),
+});
+export interface Header extends z.infer<typeof headerZ> {}
+
+/** QueryParam is a single URL query parameter sent with a request. */
+export const queryParamZ = z.object({
+  /** parameter is the parameter name, unique within a request. */
+  parameter: z.string().default(""),
+  /** value is the parameter value. */
+  value: z.string().default(""),
+});
+export interface QueryParam extends z.infer<typeof queryParamZ> {}
+
+/**
+ * EnumEntry maps a string label in a JSON body to a numeric channel value for
+ * enum-style parsing (e.g. "ON" -> 1, "OFF" -> 0).
+ */
+export const enumEntryZ = z.object({
+  /** label is the string label in the JSON body. */
+  label: z.string().default(""),
+  /** value is the numeric channel value the label maps to. */
+  value: z.number().default(0),
+});
+export interface EnumEntry extends z.infer<typeof enumEntryZ> {}
+
+/** BaseWriteField carries the fields every write body field shares. */
+export const baseWriteFieldZ = z.object({
+  /** key uniquely identifies the field within the endpoint. */
+  key: z.string().default(id.create),
+  /** pointer is the JSON Pointer where the value is placed in the body. */
+  pointer: z.string().default(""),
+});
+export interface BaseWriteField extends z.infer<typeof baseWriteFieldZ> {}
+
+export const scanConfigZ = task.scanConfigZ;
+export interface ScanConfig extends z.infer<typeof scanConfigZ> {}
+
+/** ReadField is a single value extracted from an endpoint's JSON response. */
+export const readFieldZ = z.object({
+  /** key uniquely identifies the field within the endpoint. */
+  key: z.string().default(id.create),
+  /** name is the human-readable field name. */
+  name: z.string().default(""),
+  /** disabled is true when the field is excluded from polling. */
+  disabled: z.boolean().default(false),
+  /** channel is the Synnax channel the extracted value is written to. */
+  channel: channel.keyZ.default(0),
+  /** pointer is the JSON Pointer to the value within the response body. */
+  pointer: z.string().default(""),
+  /** dataType is the data type of the extracted value. */
+  dataType: z.string().default("float64"),
+  /**
+   * timeFormat is the encoding of the JSON value when the target channel holds
+   * timestamps. Required for timestamp channels.
+   */
+  timeFormat: timeFormatZ.optional(),
+  /** enumValues maps string labels in the response to numeric channel values. */
+  enumValues: enumEntryZ.array().default(() => []),
+});
+export interface ReadField extends z.infer<typeof readFieldZ> {}
+
+/** ChannelField is the command channel value placed into a write endpoint's body. */
+export const channelFieldZ = z.object({
+  /**
+   * pointer is the JSON Pointer where the channel value is placed in the body. An empty
+   * pointer sends the bare value as the entire body, in which case the endpoint may not
+   * declare any additional fields.
+   */
+  pointer: z.string().default(""),
+  /** jsonType is the JSON type the channel value is serialized as. */
+  jsonType: jsonTypeZ.default("number"),
+  /** channel is the Synnax command channel that triggers the request. */
+  channel: channel.keyZ.default(0),
+  /** name is the human-readable name of the command channel. */
+  name: z.string().default(""),
+  /** dataType is the data type of the command channel. */
+  dataType: z.string().default("float64"),
+  /**
+   * timeFormat is the output encoding when the command channel holds timestamps.
+   * Required for timestamp channels.
+   */
+  timeFormat: timeFormatZ.optional(),
+  /**
+   * enumValues maps numeric channel values to string labels. Only valid when json_type
+   * is 'string'.
+   */
+  enumValues: enumEntryZ.array().default(() => []),
+});
+export interface ChannelField extends z.infer<typeof channelFieldZ> {}
+
+/** StaticWriteField places a fixed value in the request body. */
+export const staticWriteFieldZ = baseWriteFieldZ.extend({
+  type: z.literal("static"),
+  /** jsonType is the JSON type the value is serialized as. */
+  jsonType: jsonTypeZ.default("number"),
+  /** value is the fixed JSON value placed at the pointer. */
+  value: z.unknown(),
+});
+export interface StaticWriteField extends z.infer<typeof staticWriteFieldZ> {}
+
+/** GeneratedWriteField places a freshly generated UUID or timestamp in the body. */
+export const generatedWriteFieldZ = baseWriteFieldZ.extend({
+  type: z.literal("generated"),
+  /** generator is the generator that produces a fresh value per request. */
+  generator: generatorTypeZ.default("uuid"),
+  /**
+   * timeFormat is the output encoding for timestamp generators. Defaults to iso8601.
+   */
+  timeFormat: timeFormatZ.optional(),
+});
+export interface GeneratedWriteField extends z.infer<typeof generatedWriteFieldZ> {}
+
+export const WRITE_FIELD_TYPES = ["static", "generated"] as const;
+export const writeFieldTypeZ = z.enum(WRITE_FIELD_TYPES);
+export type WriteFieldType = z.infer<typeof writeFieldTypeZ>;
+
+/**
+ * WriteField is an additional body field on a write endpoint. The type field selects
+ * whether the value is fixed or generated per request.
+ */
+export const writeFieldZ = z.discriminatedUnion("type", [
+  staticWriteFieldZ,
+  generatedWriteFieldZ,
+]);
+export type WriteField = StaticWriteField | GeneratedWriteField;
+
+export const WRITE_FIELD_SCHEMAS: {
+  [K in WriteFieldType]: z.ZodType<Extract<WriteField, { type: K }>>;
+} = {
+  static: staticWriteFieldZ,
+  generated: generatedWriteFieldZ,
+};
+
+/** ReadEndpoint is a single HTTP endpoint polled by a read task. */
+export const readEndpointZ = z.object({
+  /** key uniquely identifies the endpoint within the task. */
+  key: z.string().default(id.create),
+  /** method is the HTTP method used to poll the endpoint. */
+  method: methodZ.default("GET"),
+  /** path is the URL path appended to the device's base URL. */
+  path: z.string().default(""),
+  /** headers contains additional headers merged into the request. */
+  headers: headerZ.array().default(() => []),
+  /** queryParams contains query parameters appended to the request URL. */
+  queryParams: queryParamZ.array().default(() => []),
+  /** body is a static body sent with each request. Empty sends no body. */
+  body: z.string().default(""),
+  /** fields contains the values to extract from the response. */
+  fields: readFieldZ.array().default(() => []),
+  /**
+   * index is the key of the field whose channel indexes the others. Empty when the task
+   * stamps samples on arrival.
+   */
+  index: z.string().default(""),
+});
+export interface ReadEndpoint extends z.infer<typeof readEndpointZ> {}
+
+/** WriteEndpoint is a single HTTP endpoint written to by a write task. */
+export const writeEndpointZ = z.object({
+  /** key uniquely identifies the endpoint within the task. */
+  key: z.string().default(id.create),
+  /** disabled is true when the endpoint is excluded from the task. */
+  disabled: z.boolean().default(false),
+  /** method is the HTTP method used to send the request. */
+  method: methodZ.default("POST"),
+  /** path is the URL path appended to the device's base URL. */
+  path: z.string().default(""),
+  /** headers contains additional headers merged into the request. */
+  headers: headerZ.array().default(() => []),
+  /** queryParams contains query parameters appended to the request URL. */
+  queryParams: queryParamZ.array().default(() => []),
+  /** channel is the command channel whose writes trigger this endpoint. */
+  channel: channelFieldZ.prefault({}),
+  /** fields contains additional static or generated body fields. */
+  fields: writeFieldZ.array().default(() => []),
+});
+export interface WriteEndpoint extends z.infer<typeof writeEndpointZ> {}
+
+export const readConfigZ = task.persistConfigZ.extend({
+  device: device.keyZ.default(""),
+  rate: z.number().default(1),
+  endpoints: readEndpointZ.array().default(() => []),
+});
+export interface ReadConfig extends z.infer<typeof readConfigZ> {}
+
+export const writeConfigZ = task.startConfigZ.extend({
+  device: device.keyZ.default(""),
+  endpoints: writeEndpointZ.array().default(() => []),
+});
+export interface WriteConfig extends z.infer<typeof writeConfigZ> {}

package/src/imex/client.ts

@@ -0,0 +1,125 @@
+// 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.
+
+import { type FileTransport, type UploadBody } from "@synnaxlabs/freighter";
+import { z } from "zod";
+
+import { ontology } from "@/ontology";
+
+/**
+ * The serialized wire formats a resource can be imported from or exported to. Today
+ * only "JSON" is supported.
+ */
+export const encodingZ = z.enum(["JSON"]);
+
+/** The serialized wire format of an imported or exported resource. */
+export type Encoding = z.infer<typeof encodingZ>;
+
+/**
+ * Options shared by import and export. Carries the wire format of the resource and is
+ * the extension point for any future per-call settings.
+ */
+export interface Options {
+  /** The serialized format of the resource. */
+  encoding: Encoding;
+}
+
+/** The standard options for a JSON import or export. */
+export const JSON_OPTIONS: Options = { encoding: "JSON" };
+
+/** The wire shape of the per-import request params. Both fields are required. */
+const importParamsZ = z.object({
+  fileName: z.string().min(1),
+  parent: ontology.idZ.transform((id) => ontology.idToString(id)),
+});
+
+/** Options for a single import call. */
+export interface ImportOptions extends Options {
+  /**
+   * The name of the file the resource was read from. When the file's contents carry no
+   * top-level `name` field, the Core names the imported resource after the file, with
+   * any trailing extension stripped. A `name` in the file always wins.
+   */
+  fileName: string;
+  /**
+   * The ontology resource to create the imported resource under — a project for project
+   * items, a group for symbols. The Core creates the resource and its parent
+   * relationship in a single transaction, so a parenting failure rolls back the import.
+   */
+  parent: ontology.ID;
+}
+
+/**
+ * Imports and exports resources to and from a Synnax cluster as serialized bytes — the
+ * same on-disk representation a user reads from or writes to a file. The bytes are
+ * opaque to the client: nothing is parsed or transformed on the way through, so the
+ * wire format is exactly the file's contents.
+ *
+ * Each call moves exactly one resource. When source is a Blob, the client never holds
+ * the payload in its own memory; bytes are sent as-is (already in memory). Exports
+ * always stream back without buffering. The Core, however, currently materializes each
+ * payload, so a single import or export is bounded by its available memory.
+ *
+ * The client is environment-agnostic — the byte streams are standard Web Streams that
+ * work in browsers, Node 18+, and Tauri webviews. Callers bridge the filesystem with
+ * their own runtime's primitives:
+ *
+ * - Node: `import(Readable.toWeb(createReadStream(path)), opts)` and `(await export(id,
+ *   opts)).pipeTo(Writable.toWeb(createWriteStream(path)))`.
+ * - Browser: `import(fileInput.files[0], opts)` and pipe the export into a
+ *   showSaveFilePicker writable (or buffer it with `new Response(stream).blob()`).
+ * - Tauri/Console: read the picked file into a Blob to import, and hand the export
+ *   stream to the Console's download hook.
+ */
+export interface ClientConfig {
+  file: FileTransport;
+}
+
+export class Client {
+  private readonly cfg: ClientConfig;
+
+  constructor(cfg: ClientConfig) {
+    this.cfg = cfg;
+  }
+
+  /**
+   * Imports a resource from the given serialized source and returns its new ontology
+   * ID.
+   * @param source - the serialized resource (e.g. a file's contents). A Blob is sent
+   * from wherever the engine holds it, so a file never enters client memory; bytes are
+   * sent as-is.
+   * @param options - the import options, including the wire format of source, the
+   * source file's name (used to name the resource when the file carries no name), and
+   * the parent resource to create the resource under.
+   * @returns the new resource's ontology ID as stamped by the Core.
+   */
+  async import(
+    source: UploadBody,
+    { encoding, ...params }: ImportOptions,
+  ): Promise<ontology.ID> {
+    return await this.cfg.file.upload(
+      "/imex/import",
+      source,
+      { encoding, params, paramsSchema: importParamsZ },
+      ontology.idZ,
+    );
+  }
+
+  /**
+   * Exports the resource identified by id as a byte stream. The caller pipes the stream
+   * wherever it likes — a file on disk, a browser download, or an in-memory buffer via
+   * `new Response(stream).json()` — without the client ever buffering the whole
+   * payload.
+   * @param options - the export options, including the desired wire format.
+   * @returns the serialized resource as a stream of bytes.
+   */
+  async export(id: ontology.ID, options: Options): Promise<ReadableStream<Uint8Array>> {
+    return await this.cfg.file.download("/imex/export", id, ontology.idZ, options);
+  }
+}

package/src/imex/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 imex from "@/imex/client";

package/src/index.ts

@@ -8,14 +8,15 @@
 // included in the file licenses/APL.txt.
 
 export { access } from "@/access";
+export type { Policy } from "@/access/policy/types.gen";
+export type { Role } from "@/access/role/types.gen";
 export { actions } from "@/actions";
 export { arc } from "@/arc";
+export type { Param } from "@/arc/types/types.gen";
 export { channel } from "@/channel";
 export { Channel, isCalculated } from "@/channel/client";
 export {
-  checkConnection,
-  type CheckConnectionParams,
-  newConnectionChecker,
+  type ConnectOptions,
   default as Synnax,
   type SynnaxParams,
   synnaxParamsZ,
@@ -24,9 +25,11 @@ export * from "@/connection";
 export { control } from "@/control";
 export { device } from "@/device";
 export {
+  AccessDeniedError,
   AuthError,
   ContiguityError,
   DisconnectedError,
+  isConnectionError,
   MultipleFoundError,
   NotFoundError,
   QueryError,
@@ -34,24 +37,34 @@ export {
   UnexpectedError,
   ValidationError,
 } from "@/errors";
+export { ethercat } from "@/ethercat";
 export { framer } from "@/framer";
 export { Frame } from "@/framer/frame";
 export { group } from "@/group";
+export { http } from "@/http";
+export { imex } from "@/imex";
 export { label } from "@/label";
+export { labjack } from "@/labjack";
 export { lineplot } from "@/lineplot";
 export { log } from "@/log";
+export { modbus } from "@/modbus";
+export { ni } from "@/ni";
+export { node } from "@/node";
 export { ontology } from "@/ontology";
+export { opcua } from "@/opcua";
+export { pagerduty } from "@/pagerduty";
+export { panel } from "@/panel";
+export { project } from "@/project";
+export { query } from "@/query";
 export { rack } from "@/rack";
 export { ranger } from "@/ranger";
 export { schematic } from "@/schematic";
 export { status } from "@/status";
+export type { StatusZodObject } from "@/status/types.gen";
 export { table } from "@/table";
 export { task } from "@/task";
-export { createTestClientWithPolicy } from "@/testutil/access";
-export { createTestClient, TEST_CLIENT_PARAMS } from "@/testutil/client";
 export { user } from "@/user";
 export { view } from "@/view";
-export { workspace } from "@/workspace";
 export {
   type CrudeDataType,
   type CrudeDensity,