@zerodot/node-sdk 0.0.0-stage → 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,531 @@
+import { z } from "zod";
+/**
+ * Binary data in a node output. zerodot has no separate binary store, so the bytes are base64
+ * text under `binary.<property>` in the JSON output. The size limit of a node output applies.
+ */
+type BinaryData = {
+  data: string;
+  mimeType: string;
+  fileName?: string;
+};
+export declare function mimeTypeOf(fileName: string): string;
+export declare function toBinary(bytes: Uint8Array, fileName: string, mimeType?: string): BinaryData;
+/** The binary data that an earlier node put under `input.binary[property]`. */
+export declare function readBinary(input: unknown, property: string): BinaryData;
+declare const sandboxRequestSchema: z.ZodObject<{
+  code: z.ZodString;
+  scope: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  timeoutMs: z.ZodNumber;
+  maxOutputBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SandboxRequest = z.infer<typeof sandboxRequestSchema>;
+declare const SANDBOX_LOG_LEVELS: readonly ["log", "info", "warn", "error", "debug"];
+/** One `console` call in the code. */
+type CodeLog = {
+  level: (typeof SANDBOX_LOG_LEVELS)[number];
+  message: string;
+};
+type SandboxClient = {
+  /**
+   * Resolves with the value the code returned. Throws `SandboxError` when the code fails.
+   * `onLogs` gets the `console` calls of the code, also when the code fails.
+   */
+  run(request: SandboxRequest, signal: AbortSignal, onLogs?: (logs: CodeLog[]) => void): Promise<unknown>;
+};
+/**
+ * Rules that decide when a config field shows in the editor. A condition maps a config key to the
+ * values that it accepts. A value is a plain value, or an operator object `{ _cnd: { gte: 1.1 } }`.
+ * All keys of one condition must match. A list of conditions needs one match.
+ */
+type FieldCondition = Record<string, unknown[]>;
+type ShowRules = {
+  showWhen?: FieldCondition | FieldCondition[];
+  /** The field hides when one of these conditions holds. This wins over `showWhen`. */
+  hideWhen?: FieldCondition | FieldCondition[];
+};
+/** A row as workflows see it: the system fields, then the columns. A missing value is null. */
+type TableRow = {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  [column: string]: unknown;
+};
+declare const FILTER_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "contains", "isNull"];
+type FilterOp = (typeof FILTER_OPS)[number];
+type FilterCondition = {
+  field: string;
+  op: FilterOp;
+  value?: unknown;
+};
+type Filter = FilterCondition | {
+  and: Filter[];
+} | {
+  or: Filter[];
+};
+declare const sortSchema: z.ZodArray<z.ZodObject<{
+  field: z.ZodString;
+  direction: z.ZodDefault<z.ZodEnum<{
+    asc: "asc";
+    desc: "desc";
+  }>>;
+}, z.core.$strip>>;
+type Sort = z.output<typeof sortSchema>;
+type RowQuery = {
+  filter?: Filter;
+  sort?: Sort;
+  limit?: number;
+  cursor?: string | null;
+};
+type RowPage = {
+  rows: TableRow[];
+  nextCursor: string | null;
+};
+type UpdateInput = {
+  filter?: Filter;
+  /** Needed when there is no filter. */
+  all?: boolean;
+  set?: Record<string, unknown>;
+  /** Adds to number columns. The database does it in one statement. */
+  increment?: Record<string, number>;
+};
+type UpsertInput = {
+  /** A unique column. The value comes from `row`. */
+  column: string;
+  row: Record<string, unknown>;
+  increment?: Record<string, number>;
+};
+/**
+ * What the table nodes use. The database package implements it.
+ * `table` is the id or the name of a table.
+ */
+type TableStore = {
+  insert(table: string, rows: Record<string, unknown>[]): Promise<TableRow[]>;
+  query(table: string, query: RowQuery): Promise<RowPage>;
+  get(table: string, by: {
+    field: string;
+    value: unknown;
+  }): Promise<TableRow | null>;
+  /** `rows` holds up to 100 of the changed rows. `count` is the total. */
+  update(table: string, input: UpdateInput): Promise<{
+    count: number;
+    rows: TableRow[];
+  }>;
+  upsert(table: string, input: UpsertInput): Promise<{
+    row: TableRow;
+    created: boolean;
+  }>;
+  delete(table: string, input: {
+    filter?: Filter;
+    all?: boolean;
+  }): Promise<{
+    count: number;
+  }>;
+};
+/** The workflow that a sub-workflow node runs: one of the organization, or a graph in the config. */
+type SubWorkflowSource = {
+  kind: "database";
+  workflowId: string;
+} | {
+  kind: "parameter";
+  graph: unknown;
+};
+type SubWorkflowRunner = (source: SubWorkflowSource, input: unknown, options: {
+  wait: boolean;
+}) => Promise<unknown>;
+type NodeCategory = "trigger" | "core" | "logic" | "data" | "flow" | "code" | "integration";
+/** A credential after decryption. The type is the credential type, for example "http.bearer". */
+type ResolvedCredential = {
+  type: string;
+  data: Record<string, unknown>;
+};
+type NodeRunContext<Config> = {
+  /** Config with expressions resolved and checked against the Zod schema. */
+  config: Config;
+  /** Output data of the parent node. For a trigger node, the trigger input. */
+  input: unknown;
+  /** Decrypted credential, if the node has one. */
+  credential: ResolvedCredential | null;
+  signal: AbortSignal;
+  /** Plain values that the expression language can read: $trigger, $node, $input, $vars, $run, $resumeUrl. */
+  scope: Record<string, unknown>;
+  /** Adds `console` logs of the node to the result of this node. They show in the run. */
+  log?: (logs: CodeLog[]) => void;
+  /** The code sandbox, or null when the worker has none. */
+  sandbox: SandboxClient | null;
+  /** Data tables of the project, or null when the worker has none. */
+  tables: TableStore | null;
+  /**
+   * Address that answers this node while it waits. A person opens it, and the run goes on with
+   * their answer as the node output. Not set when the worker does not know the public address.
+   */
+  resumeUrl?: string | null;
+  /**
+   * Runs another workflow of the same organization with `input` as its trigger input. With
+   * `wait: true` it returns the output of the last node that ran. With `wait: false` it only
+   * starts the run and returns `{ runId }`. Null when the worker cannot run a sub-workflow.
+   */
+  runWorkflow?: SubWorkflowRunner | null;
+  /**
+   * True when the data came back along a loop: the edge into this node starts at a node that
+   * this node feeds, directly or through other nodes. False for a first entry and for a trigger.
+   */
+  loopBack?: boolean;
+  /**
+   * What this node returned as `state` the last time it ran in this run. Only for a node with
+   * `stateful: true`. It is not kept when the run stops, because the engine builds it again.
+   */
+  state?: unknown;
+};
+export declare const FORM_FIELD_TYPES: readonly ["text", "number", "email", "textarea", "dropdown", "checkbox", "radio", "password", "date"];
+/** A field of the page that a person fills in to answer a node that waits. */
+type WaitFormField = {
+  fieldLabel: string;
+  /** The key of the answer in the output. Default: the label. */
+  key?: string;
+  fieldType?: (typeof FORM_FIELD_TYPES)[number];
+  placeholder?: string;
+  requiredField?: boolean;
+  /** For dropdown, checkbox, and radio. */
+  fieldOptions?: {
+    values: {
+      option: string;
+    }[];
+  };
+};
+type WaitForm = {
+  title?: string;
+  description?: string;
+  buttonLabel?: string;
+  fields: WaitFormField[];
+};
+type NodeResult = {
+  port: string;
+  data: unknown;
+  /**
+   * Epoch ms. The node is done, but the run must not go on before this time.
+   * The engine stops the run and the worker resumes it later. Nothing waits in memory.
+   */
+  waitUntil?: number;
+  /**
+   * The answer to the HTTP request that started the run. A "respond to webhook" node sets it.
+   * The worker passes it to the web app, which holds the request open.
+   */
+  respond?: RunResponse;
+  /**
+   * Kept in memory for the next run of this node in the same run (a loop). Only for a node with
+   * `stateful: true`. It never goes to the database.
+   */
+  state?: unknown;
+};
+/** The answer to a webhook request: status, headers, and body. */
+type RunResponse = {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+};
+/** A request to the webhook address of a trigger: `/hooks/:token`. */
+type WebhookRequest = {
+  method: string;
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  body: unknown;
+  /** The body as text, before it was parsed. */
+  rawBody?: string;
+  /** The body bytes as base64. The Webhook node saves them as binary data. */
+  bodyBase64?: string;
+  /** The address of the caller. Set only when the server trusts the proxy headers. */
+  ip?: string | null;
+};
+/** What a trigger node says about a request. `response` replaces the default answer of the route. */
+type WebhookVerdict = {
+  verdict: "accept";
+  input: unknown;
+  response?: {
+    status: number;
+    body: unknown;
+  };
+} | {
+  verdict: "ignore";
+  response?: {
+    status: number;
+    body: unknown;
+  };
+} | {
+  verdict: "forbidden";
+  status?: number;
+  headers?: Record<string, string>;
+};
+/** What a trigger node gets when it handles a request, or when its workflow starts or stops. */
+type WebhookContext<Config = Record<string, unknown>> = {
+  config: Config;
+  credential: ResolvedCredential | null;
+  /** Address of the webhook of this trigger, for example `https://zerodot.example/hooks/abc`. */
+  url: string;
+  workflow: {
+    id: string;
+    name: string;
+  };
+  node: {
+    id: string;
+    name: string;
+  };
+  /** Data that the node kept before. A node writes it by returning it from `activate` or `deactivate`. */
+  state: unknown;
+  signal: AbortSignal;
+};
+/**
+ * A trigger that gets requests at its webhook address. `receive` checks a request and gives the
+ * trigger input of the run. `activate` and `deactivate` register and remove the webhook at
+ * another service. They return the new `state`.
+ */
+type NodeWebhook = {
+  receive(ctx: WebhookContext & {
+    request: WebhookRequest;
+  }): Promise<WebhookVerdict>;
+  activate?(ctx: WebhookContext): Promise<unknown>;
+  deactivate?(ctx: WebhookContext): Promise<unknown>;
+};
+/** What a polling trigger gets on each tick. */
+type PollContext<Config = Record<string, unknown>> = {
+  config: Config;
+  credential: ResolvedCredential | null;
+  /** What the last poll returned as `cursor`. Null on the first poll after activation. */
+  cursor: unknown;
+  /** True on the first poll after activation. The items of this poll start no runs. */
+  firstPoll: boolean;
+  workflow: {
+    id: string;
+    name: string;
+  };
+  node: {
+    id: string;
+    name: string;
+  };
+  signal: AbortSignal;
+};
+/** One new thing at another service. Each item starts one run. */
+type PollItem = {
+  /** Stable id of the item. The engine skips a key it has seen, so the same item starts one run. */
+  key: string;
+  /** The trigger input of the run. */
+  data: unknown;
+};
+type PollResult = {
+  /** New items, oldest first. */
+  items: PollItem[];
+  /** Kept and given back to the next poll. Not changed when the poll throws. */
+  cursor: unknown;
+};
+/** What a listening trigger gets when the worker starts it. */
+type ListenContext<Config = Record<string, unknown>> = {
+  config: Config;
+  credential: ResolvedCredential | null;
+  workflow: {
+    id: string;
+    name: string;
+  };
+  node: {
+    id: string;
+    name: string;
+  };
+  /** Aborts when the worker stops. */
+  signal: AbortSignal;
+  /**
+   * Starts one production run. The `key` is stable for one event, so the same event starts
+   * one run. Resolves when the run is stored. Throws when the run cannot be stored.
+   */
+  emit(item: PollItem): Promise<void>;
+  /** Reports a problem of the connection. The trigger shows it as its last error. */
+  fail(error: Error): void;
+};
+/** What a listening trigger gives back. The worker calls `close` when the trigger stops. */
+type ListenHandle = {
+  /**
+   * `remove` is true when the workflow is not active any more, or the trigger changed. The node
+   * then removes what it made at another service. It is false when only the worker stops.
+   */
+  close(options: {
+    remove: boolean;
+  }): Promise<void>;
+};
+/** The most items one poll may return. A poll that returns more fails and the cursor stays. */
+export declare const POLL_MAX_ITEMS = 1000;
+type NodeDefinition<Schema extends z.ZodType = z.ZodType> = {
+  type: string;
+  label: string;
+  /** One line under the name in the Add node list. */
+  description?: string;
+  category: NodeCategory;
+  /**
+   * Rows of the Add node list for this node, one for each thing it does, for example one for each
+   * operation. A row adds the node with `config` on top of the default config.
+   */
+  actions?: {
+    label: string;
+    config: Record<string, unknown>;
+  }[];
+  /** App the node belongs to, for example "Postgres". The Add node list shows one row for the app. */
+  app?: string;
+  /** Name of a Lucide icon, in PascalCase, for example "Globe". The editor shows it. */
+  icon: string;
+  /** Image of the node, as a data URL. The editor shows it in place of `icon`. */
+  iconUrl?: string;
+  config: Schema;
+  /** Config for a node that the user just added. */
+  defaultConfig: z.input<Schema>;
+  /** Credential types this node accepts. The user picks one credential of these types. */
+  credentialTypes?: string[];
+  /**
+   * When a credential type applies, by config value. For example `{ "http.basic": { showWhen:
+   * { authentication: ["basic"] } } }`. A type with no rule always applies. The editor shows only
+   * the types that apply. The run accepts every type in `credentialTypes`.
+   */
+  credentialRules?: Record<string, ShowRules>;
+  /** Short text under the node name in the editor. Config can hold unresolved expressions. */
+  subtitle?(config: Record<string, unknown>): string | undefined;
+  ports: {
+    in: string[];
+    out: string[];
+  };
+  /**
+   * Input ports that depend on the config (a merge node has one port for each input). Without
+   * it the node has `ports.in`. An edge into a port that this list does not have is ignored by
+   * the engine and reported by the graph check.
+   */
+  inPorts?(config: Record<string, unknown>): string[];
+  /**
+   * A join node waits for all of its parents. Its input is an object with the data of each
+   * input port, for example `{ input1, input2 }`. A parent that was skipped sends no data.
+   */
+  join?: boolean;
+  /**
+   * The node keeps `state` between its runs in one run (a loop counter). When a stopped run
+   * goes on, the engine runs the node again with its saved inputs to build the state again, and
+   * keeps the saved result. So `run` must have no side effects and must give the same answer for
+   * the same inputs.
+   */
+  stateful?: boolean;
+  /** Config keys (top level) whose text is not an expression. The engine leaves `{{ }}` as it is. */
+  rawConfigKeys?: string[];
+  /**
+   * For a node that waits for a person: the form that the resume page shows, or null when
+   * the node needs no form (a click on a button is the answer, as `?approved=true`).
+   */
+  waitForm?(config: Record<string, unknown>): WaitForm | null;
+  /**
+   * For a node that waits for an HTTP call to its resume address. Returns true when the config
+   * asks for it. Any method works. The method, headers, query, and body of the call are the
+   * node output. The address is also in the expression scope as `$resumeUrl["Node name"]`.
+   */
+  waitsForCallback?(config: Record<string, unknown>): boolean;
+  /** For a trigger node with a webhook that needs its own checks or registration. */
+  webhook?: NodeWebhook;
+  /**
+   * For a trigger node that asks another service for news. The worker calls it on a timer
+   * (config key `intervalSeconds`, in seconds) while the workflow is active.
+   */
+  poll?(ctx: PollContext<z.output<Schema>>): Promise<PollResult>;
+  /**
+   * For a trigger node that gets events through a connection that stays open. The worker calls
+   * it when the workflow is active, and keeps the handle until the trigger stops.
+   */
+  listen?(ctx: ListenContext<z.output<Schema>>): Promise<ListenHandle>;
+  /** Output ports that depend on the config (a switch has one port for each case). */
+  outPorts?(config: Record<string, unknown>): string[];
+  run(ctx: NodeRunContext<z.output<Schema>>): Promise<NodeResult> | NodeResult;
+};
+export declare function defineNode<Schema extends z.ZodType>(definition: NodeDefinition<Schema>): NodeDefinition<Schema>;
+/** How the client sends its id and secret to the token URL. */
+type OAuth2Authentication = "header" | "body";
+type OAuth2Config = {
+  authUrl: string;
+  tokenUrl: string;
+  scopes: string[];
+  /** Extra query parameters for the authorize URL, for example `access_type=offline`. */
+  authQuery?: Record<string, string>;
+  authentication: OAuth2Authentication;
+  pkce?: boolean;
+};
+type OAuth2Resolver = (data: Record<string, unknown>) => OAuth2Config | null;
+type CredentialTypeDefinition = {
+  type: string;
+  label: string;
+  fields: z.ZodObject<Record<string, z.ZodType<string | undefined>>>;
+  /** Fields the form shows as password inputs. The form never shows a saved value of any field. */
+  secretFields: string[];
+  /** Fields that only the server sets. The form hides them, and a client cannot write them. */
+  serverFields?: string[];
+  /**
+   * An OAuth2 credential. A preset has fixed endpoints. A function builds the endpoints from the
+   * credential data (for example a server address). `"custom"` reads `authUrl`, `tokenUrl`,
+   * `scope` and `authentication` from the credential data.
+   */
+  oauth2?: OAuth2Config | OAuth2Resolver | "custom";
+  /** Lucide icon name. */
+  icon?: string;
+  /** Image URL. It replaces `icon`. */
+  iconUrl?: string;
+  /**
+   * Checks a saved credential, for the "Test" button of the credential form. It throws with a
+   * short message when the credential does not work. zerodot removes secrets from the message.
+   */
+  test?(credential: ResolvedCredential): Promise<void>;
+};
+/** A string with one `` and nothing else keeps the value type. Otherwise the result is text. */
+export declare function resolveTemplate(input: string, scope: Record<string, unknown>): unknown;
+/** Resolve every string inside a config value. Errors carry the path to the bad value. */
+export declare function resolveConfig(value: unknown, scope: Record<string, unknown>, path?: string): unknown;
+/**
+ * The shape of a nested field (a collection or a fixed collection), as plain data. A node writes
+ * it into the JSON Schema of its config. The editor draws a form from it.
+ * A key of a condition that starts with "/" reads from the top level of the config.
+ */
+type FieldSpec = {
+  name: string;
+  label: string;
+  kind: "string" | "number" | "boolean" | "options" | "filter" | "collection" | "fixed";
+  description?: string;
+  placeholder?: string;
+  default?: unknown;
+  multiline?: boolean;
+  options?: {
+    value: string | number | boolean;
+    label: string;
+    hint?: string;
+  }[];
+  show?: FieldCondition | FieldCondition[];
+  hide?: FieldCondition;
+  /** `collection`: the fields that the user can add. */
+  fields?: FieldSpec[];
+  /** `fixed`: the groups. A group holds a list when `multiple` is set, or one object. */
+  groups?: {
+    name: string;
+    label: string;
+    fields: FieldSpec[];
+  }[];
+  multiple?: boolean;
+};
+/** One item of a node run: a plain object. */
+type Item = Record<string, unknown>;
+export declare const isRecord: (value: unknown) => value is Item;
+/** The items of a node run. A list is the items. One object is one item. Null is one empty item. */
+export declare function toItems(input: unknown): Item[];
+/**
+ * Reads an icon file of a package and returns it as a data URL, for `iconUrl` of a node or a
+ * credential type. `from` is `import.meta.url` of the file that calls it, and `path` is relative
+ * to that file, for example `fileIcon(import.meta.url, "./redis.svg")`. The icon file must be in
+ * the `files` of the package.
+ */
+export declare function fileIcon(from: string, path: string): string;
+/**
+ * Version of the node contract (the shape of `NodeDefinition` and what a node can use).
+ * A minor version only adds. A major version can break a node package.
+ */
+export declare const SDK_VERSION = "1.1.0";
+/**
+ * True when `version` fits `range`. A range is a caret range (`^1.4`, `^1.4.2`) or one exact
+ * version (`1.4.2`). A caret range allows the same major version, from the given version up.
+ * For major 0 it allows the same minor version only, as npm does.
+ */
+export declare function satisfiesSdk(range: string, version?: string): boolean;
+export type { BinaryData, CredentialTypeDefinition, FieldSpec, Item, ListenContext, ListenHandle, NodeCategory, NodeDefinition, NodeResult, NodeRunContext, NodeWebhook, OAuth2Config, PollContext, PollItem, PollResult, ResolvedCredential, ShowRules, WaitForm, WaitFormField, WebhookContext, WebhookRequest, WebhookVerdict };