@synnaxlabs/client 0.56.2 → 0.57.0

package/src/ontology/payload.ts

@@ -7,39 +7,57 @@
 // 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 change, primitive, record } from "@synnaxlabs/x";
+import { array, type change, primitive, record, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { RESOURCE_TYPES, type ResourceType, resourceTypeZ } from "@/ontology/types.gen";
 
 export { RESOURCE_TYPES, type ResourceType, resourceTypeZ };
 
+/** A resource created, updated, or deleted. */
 export type ResourceChange = change.Change<ID, Resource>;
 export interface ResourceSet extends change.Set<ID, Resource> {}
 export interface ResourceDelete extends change.Delete<ID, Resource> {}
+/** A relationship created or deleted. Relationships carry no value of their own. */
 export type RelationshipChange = change.Change<Relationship, undefined>;
 export interface RelationshipSet extends change.Set<Relationship, undefined> {}
 export interface RelationshipDelete extends change.Delete<Relationship, undefined> {}
 
 export interface RelationshipDelete extends change.Delete<Relationship, undefined> {}
 
-const stringIDZ = z.string().transform((v) => {
+/** Zod schema parsing a `"type:key"` string into an {@link ID}. */
+export const stringIDZ = z.string().transform((v, ctx) => {
   const [type, key] = v.split(":");
-  return { type: resourceTypeZ.parse(type), key: key ?? "" };
+  const res = resourceTypeZ.safeParse(type);
+  if (!res.success) {
+    ctx.addIssue({ code: "custom", message: `invalid resource type: ${type}` });
+    return z.NEVER;
+  }
+  return { type: res.data, key: key ?? "" };
 });
 
+/** Zod schema for {@link ID}, accepting either the object or the `"type:key"` string. */
 export const idZ = z.object({ type: resourceTypeZ, key: z.string() }).or(stringIDZ);
 
+/** Names one resource in the ontology: what kind it is, and which one. */
 export type ID = z.infer<typeof idZ>;
 
+/** The root of the ontology. Every other resource descends from it. */
 export const ROOT_ID: ID = { type: "builtin", key: "root" };
 
+/** Builds {@link ID}s of one resource type, singly or in bulk. */
 export interface CreateID<K extends record.Key> {
   (key: K): ID;
   (keys: K[]): ID[];
   (keys: K | K[]): ID | ID[];
 }
 
+/**
+ * @returns a {@link CreateID} that stamps the given resource type onto keys. Each
+ * resource package exports one as `ontologyID`.
+ *
+ * @example const ontologyID = createIDFactory<Key>("channel");
+ */
 export const createIDFactory = <K extends record.Key>(
   type: ResourceType,
 ): CreateID<K> => {
@@ -55,14 +73,27 @@ export interface IDToString {
   (ids: (ID | string)[]): string[];
 }
 
+/** Renders an {@link ID} as `"type:key"`, the form used as a map key. */
 export const idToString = ((id: ID | string | (ID | string)[]) => {
-  if (typeof id === "string") id = stringIDZ.parse(id);
+  if (typeof id === "string") id = zod.parse(stringIDZ, id, { label: "ontology ID" });
   if (Array.isArray(id)) return id.map((id) => idToString(id));
   return `${id.type}:${id.key}`;
 }) as IDToString;
 
+/** @returns whether the two IDs name the same resource. */
 export const idsEqual = (a: ID, b: ID) => a.type === b.type && a.key === b.key;
 
+/**
+ * Parses a crude ID (an object or a "type:key" string) into an ID.
+ * @throws {zod.ParseError} if the value is not a valid ontology ID.
+ */
+export const parseID = (id: unknown): ID =>
+  zod.parse(idZ, id, { label: "ontology ID" });
+
+/**
+ * Resolves IDs, `"type:key"` strings, or whole resources into an {@link ID} array.
+ * @throws {zod.ParseError} if a value is not a valid ontology ID.
+ */
 export const parseIDs = (
   ids: ID | string | Resource | (ID | string | Resource)[],
 ): ID[] => {
@@ -70,9 +101,10 @@ export const parseIDs = (
   if (arr.length === 0) return [];
   if (typeof arr[0] === "object" && "id" in arr[0])
     return (arr as Resource[]).map(({ id }) => id);
-  return arr.map((id) => idZ.parse(id));
+  return arr.map(parseID);
 };
 
+/** Zod schema for {@link Resource}. */
 export const resourceZ = z
   .object({
     id: idZ,
@@ -80,6 +112,7 @@ export const resourceZ = z
     data: record.unknownZ().optional().nullable(),
   })
   .transform((resource) => ({ key: idToString(resource.id), ...resource }));
+/** A node in the ontology: its ID, its display name, and the payload it stands for. */
 export interface Resource<T extends record.Unknown = record.Unknown> extends Omit<
   z.infer<typeof resourceZ>,
   "data"
@@ -87,34 +120,42 @@ export interface Resource<T extends record.Unknown = record.Unknown> extends Omi
   data?: T | null;
 }
 
+/** Which end of a relationship a traversal starts from. */
 export type RelationshipDirection = "to" | "from";
 
+/** @returns the other end of a relationship. */
 export const oppositeRelationshipDirection = (
   direction: RelationshipDirection,
 ): RelationshipDirection => (direction === "to" ? "from" : "to");
 
+/** Zod schema for {@link Relationship}, accepting the `"from->type->to"` string too. */
 export const relationshipZ = z.object({ from: idZ, type: z.string(), to: idZ }).or(
   z.string().transform((v) => {
     const [from, type, to] = v.split("->");
     return { from: idZ.parse(from), type, to: idZ.parse(to) };
   }),
 );
+/** A directed edge between two resources, such as a group and its child. */
 export type Relationship = z.infer<typeof relationshipZ>;
 
+/** Renders a {@link Relationship} as `"from->type->to"`. */
 export const relationshipToString = (relationship: Relationship) =>
   `${idToString(relationship.from)}->${relationship.type}->${idToString(relationship.to)}`;
 
+/** Relationship type joining a parent resource to its children. */
 export const PARENT_OF_RELATIONSHIP_TYPE = "parent";
 
-export interface MatchRelationshipArgs {
+/** A relationship pattern. An absent field, or field part, matches anything. */
+export interface MatchRelationshipParams {
   from?: Partial<ID>;
   type: string;
   to?: Partial<ID>;
 }
 
+/** @returns whether the relationship fits the pattern. */
 export const matchRelationship = (
   relationship: Relationship,
-  match: MatchRelationshipArgs,
+  match: MatchRelationshipParams,
 ) => {
   if (match.type != null && match.type !== relationship.type) return false;
   if (match.from?.type != null && match.from.type !== relationship.from.type)

package/src/ontology/store.ts

@@ -0,0 +1,83 @@
+// 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 destructor } from "@synnaxlabs/x";
+
+import {
+  type ID,
+  idsEqual,
+  idToString,
+  matchRelationship,
+  PARENT_OF_RELATIONSHIP_TYPE,
+  type Relationship,
+  type Resource,
+} from "@/ontology/payload";
+import { query } from "@/query";
+
+/** Channels the Core writes ontology changes to. */
+export const RESOURCE_SET_CHANNEL_NAME = "sy_ontology_resource_set";
+export const RESOURCE_DELETE_CHANNEL_NAME = "sy_ontology_resource_delete";
+export const RELATIONSHIP_SET_CHANNEL_NAME = "sy_ontology_relationship_set";
+export const RELATIONSHIP_DELETE_CHANNEL_NAME = "sy_ontology_relationship_delete";
+
+/** The ontology record tables: resources and the relationships between them. */
+export class Cache {
+  readonly relationships: query.Table<string, Relationship>;
+  readonly resources: query.Table<string, Resource>;
+
+  constructor(
+    relationships: query.Table<string, Relationship>,
+    resources: query.Table<string, Resource>,
+  ) {
+    this.relationships = relationships;
+    this.resources = resources;
+  }
+
+  /** Returns the cached parent ID of the given ontology ID, or null if unknown. */
+  parentID(id: ID): ID | null {
+    const res = this.relationships.get((r) =>
+      matchRelationship(r, { type: PARENT_OF_RELATIONSHIP_TYPE, to: id }),
+    );
+    if (res.length === 0) return null;
+    return res[0].from;
+  }
+
+  /**
+   * Optimistically renames the cached resource for the given ID. Returns a
+   * rollback restoring the prior name. A no-op when the resource isn't cached.
+   */
+  renameResource(id: ID, name: string): destructor.Destructor {
+    return query.partialUpdate(this.resources, idToString(id), { name });
+  }
+
+  /**
+   * Optimistically drops every cached relationship touching the given IDs.
+   * Returns a rollback restoring them.
+   */
+  deleteRelationships(ids: ID | ID[]): destructor.Destructor {
+    const idsArr = Array.isArray(ids) ? ids : [ids];
+    return this.relationships.delete((rel) =>
+      idsArr.some((id) => idsEqual(rel.to, id) || idsEqual(rel.from, id)),
+    );
+  }
+
+  /**
+   * Optimistically drops the cached resources for the given IDs along with
+   * every relationship touching them. Returns a rollback restoring both.
+   */
+  deleteResources(ids: ID | ID[]): destructor.Destructor {
+    const idsArr = Array.isArray(ids) ? ids : [ids];
+    const undoRels = this.deleteRelationships(idsArr);
+    const undoResources = this.resources.delete(idToString(idsArr));
+    return () => {
+      undoResources();
+      undoRels();
+    };
+  }
+}

package/src/ontology/types.gen.ts

@@ -22,7 +22,9 @@ export const RESOURCE_TYPES = [
   "lineplot",
   "log",
   "node",
+  "panel",
   "policy",
+  "project",
   "rack",
   "range",
   "range-alias",
@@ -34,7 +36,6 @@ export const RESOURCE_TYPES = [
   "task",
   "user",
   "view",
-  "workspace",
 ] as const;
 export const resourceTypeZ = z.enum(RESOURCE_TYPES);
 export type ResourceType = z.infer<typeof resourceTypeZ>;

package/src/ontology/writer.ts

@@ -16,6 +16,7 @@ export const addRemoveChildrenReqZ = z.object({ id: idZ, children: idZ.array() }
 export const moveChildrenReqZ = z.object({ from: idZ, to: idZ, children: idZ.array() });
 export const emptyResZ = z.object({});
 
+/** Edits the parent-child relationships in the ontology. Reach it through the client. */
 export class Writer {
   client: UnaryClient;
 

package/src/opcua/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 "@/opcua/types.gen";

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

package/src/opcua/types.gen.ts

@@ -0,0 +1,65 @@
+// 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";
+
+/** BaseChannel carries the fields every OPC UA channel shares. */
+export const baseChannelZ = z.object({
+  /** key uniquely identifies the channel within the task. */
+  key: z.string().default(id.create),
+  /** name is the human-readable channel name. */
+  name: z.string().default(""),
+  /** disabled is true when the channel is excluded from the task. */
+  disabled: z.boolean().default(false),
+  /** nodeId is the OPC UA node ID the channel is bound to. */
+  nodeId: z.string().default(""),
+  /** nodeName is the browse name of the OPC UA node. */
+  nodeName: z.string().default(""),
+  /** dataType is the data type of the Synnax channel. */
+  dataType: z.string().default("float32"),
+});
+export interface BaseChannel extends z.infer<typeof baseChannelZ> {}
+
+export const scanConfigZ = task.scanConfigZ;
+export interface ScanConfig extends z.infer<typeof scanConfigZ> {}
+
+export const readChannelZ = baseChannelZ.extend({
+  channel: channel.keyZ.default(0),
+  isIndex: z.boolean().default(false),
+});
+export interface ReadChannel extends z.infer<typeof readChannelZ> {}
+
+export const writeChannelZ = baseChannelZ.extend({
+  cmdChannel: channel.keyZ.default(0),
+});
+export interface WriteChannel extends z.infer<typeof writeChannelZ> {}
+
+export const readConfigZ = task.readConfigZ
+  .omit({ sampleRate: true, streamRate: true })
+  .extend({
+    sampleRate: z.number().default(50),
+    streamRate: z.number().default(25),
+    device: device.keyZ.default(""),
+    arrayMode: z.boolean().default(false),
+    arraySize: z.int32().default(1),
+    channels: readChannelZ.array().default(() => []),
+  });
+export interface ReadConfig extends z.infer<typeof readConfigZ> {}
+
+export const writeConfigZ = task.writeConfigZ.extend({
+  channels: writeChannelZ.array().default(() => []),
+});
+export interface WriteConfig extends z.infer<typeof writeConfigZ> {}

package/src/pagerduty/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 "@/pagerduty/types.gen";

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

package/src/pagerduty/types.gen.ts

@@ -0,0 +1,41 @@
+// 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 { status } from "@/status";
+import { task } from "@/task";
+
+/** Alert maps a Synnax status to a PagerDuty event routing rule. */
+export const alertZ = z.object({
+  /** key uniquely identifies the alert within the task. */
+  key: z.string().default(id.create),
+  /** status is the key of the Synnax status the alert watches. */
+  status: status.keyZ.default(""),
+  /** errorsCritical is true when the error variant maps to PagerDuty critical. */
+  errorsCritical: z.boolean().default(false),
+  /** component is the PagerDuty component attached to triggered events. */
+  component: z.string().default(""),
+  /** group is the PagerDuty group attached to triggered events. */
+  group: z.string().default(""),
+  /** class is the PagerDuty class attached to triggered events. */
+  class: z.string().default(""),
+  /** disabled is true when the alert is excluded from the task. */
+  disabled: z.boolean().default(false),
+});
+export interface Alert extends z.infer<typeof alertZ> {}
+
+export const taskConfigZ = task.startConfigZ.extend({
+  routingKey: z.string().default(""),
+  alerts: alertZ.array().default(() => []),
+});
+export interface TaskConfig extends z.infer<typeof taskConfigZ> {}