@revenexx/studio-integrations 1.2.0 → 1.3.0

package/dist/runtime/types/integrations.d.ts

@@ -158,11 +158,28 @@ export interface WorkflowIcon {
     /** Image URL, e.g. a node-package logo (kind=image). */
     src?: string;
 }
+/** The four things a workflow can remember between runs (PO-374). */
+export type WorkflowStateRole = 'mapping' | 'cursor' | 'dedupe' | 'digest';
+/** `private` belongs to this workflow; `shared` is tenant-wide and outlives it. */
+export type WorkflowStateVisibility = 'private' | 'shared';
+/**
+ * One state namespace a workflow declares it may reach. The engine mints the
+ * run's grant from exactly this list, so an undeclared namespace is not
+ * undocumented — it is refused at run time.
+ */
+export interface WorkflowStateNamespace {
+    namespace: string;
+    role: WorkflowStateRole;
+    /** Absent means `private`, which is what the engine's schema defaults to. */
+    visibility?: WorkflowStateVisibility;
+}
 export interface WorkflowBlob {
     nodeManifestVersion: string;
     name: LocalizedString;
     description?: LocalizedString;
     variables?: Record<string, WorkflowVariable>;
+    /** State namespaces this workflow may reach at run time (BlobDef `state`). */
+    state?: WorkflowStateNamespace[];
     triggers: WorkflowTrigger[];
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
@@ -247,11 +264,25 @@ export interface NodeManifestOutput {
      *  publishes them. Author-time schema only, never live run data. */
     fields?: string[] | Record<string, unknown>;
 }
-export type ConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+export type ConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref'
+/** Names one of the workflow's declared state namespaces (PO-374). */
+ | 'state-ref' | 'dynamic-schema';
 export interface ConfigFieldOption {
     value: string | number | boolean;
     label: LocalizedString;
 }
+/** The comparison words a settings condition may use. One vocabulary with the
+ *  condition and filter nodes, so an author who has met these words in one
+ *  place does not learn a second set for the other. */
+export type SettingConditionOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'exists' | 'notExists' | 'isEmpty' | 'isNotEmpty';
+/** A condition on another setting's value, deciding whether this one applies. */
+export interface SettingCondition {
+    /** The `key` of another setting at the same level. */
+    key: string;
+    op: SettingConditionOperator;
+    /** Left out by the four operators that read presence rather than content. */
+    value?: string | number | boolean;
+}
 export interface ConfigField {
     key: string;
     label: LocalizedString;
@@ -278,8 +309,20 @@ export interface ConfigField {
      *  (e.g. 'revenexx:business-central'). An array lets a node accept more than
      *  one credential type; the picker merges the tenant's credentials across all. */
     credentialType?: string | string[];
+    /**
+     * Only for `type: 'state-ref'` (PO-374): which kind of state namespace the
+     * field accepts. The picker lists the workflow's declarations of that role;
+     * the stored value is the namespace NAME.
+     */
+    stateRole?: WorkflowStateRole;
     /** keys of other config fields this field's options/schema depend on. */
     dependsOn?: string[];
+    /** When this setting applies at all (PO-410): another setting's key, an
+     *  operator, and where the operator takes one, the value to compare against.
+     *  Drawn only while the condition holds — see utils/settingCondition. Not
+     *  `dependsOn`, which decides what a setting resolves to rather than whether
+     *  it is drawn. */
+    showIf?: SettingCondition;
     validation?: {
         pattern?: string;
         min?: number;

package/dist/runtime/utils/buildSettle.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Watching a queued bundle build out, on any surface that reports one.
+ *
+ * A save queues a build, and until the platform has finished it the workflow cannot
+ * run. Both surfaces that say so read the state off the workflow row — the editor's
+ * chip beside Save, the build column in the workflows list — so neither of them
+ * learns that a build finished unless the row is read again.
+ *
+ * Two things can make that happen. A realtime build report, which is the fast path
+ * and is not always there: the topics have no producer in every environment, the
+ * connection can be off for a tenant, and a socket can drop in the second after the
+ * save. And re-reading the row, which is this — the floor under the fast path, and
+ * the only one of the two that works everywhere today.
+ *
+ * The editor has had it since PO-398, where a chip that never cleared was reported
+ * as "saving does not work"; the list kept the same defect for as long as it had no
+ * loop of its own (PO-416). So the loop lives here rather than in either surface:
+ * one interval, one ceiling, and one rule about which call wins, for both.
+ *
+ * WHAT A CALLER SUPPLIES is what differs between the two surfaces, and it is only
+ * ever these two things: whether anything is still unsettled — one workflow in the
+ * editor, any row in the list — and how to read it again. `settle()` decides
+ * nothing about the answer; the caller's own state is what every surface renders
+ * from.
+ *
+ * A GENERATION RATHER THAN A BUSY FLAG. Two saves in quick succession must not
+ * leave the second one unwatched, and the earlier loop cannot be relied on to cover
+ * it: a read already in flight can land after the newer save and put the pre-save
+ * row back into the cache, after which the older loop reads `ready` and stops. So
+ * the newest call wins and every older loop retires at its next turn.
+ *
+ * THE CEILING is not a timeout in the usual sense — nothing is reported when it is
+ * reached. A build is seconds; a build still queued after five minutes is a state
+ * worth leaving on screen rather than asking about forever, and the operator's own
+ * reload starts a fresh watch (which is why arriving on an unsettled row starts one).
+ */
+/** Between reads. Same cadence the editor's queued-run wait uses. */
+export declare const BUILD_SETTLE_POLL_MS = 2500;
+/** After this, the state stands as last read and nothing asks again. */
+export declare const BUILD_SETTLE_TIMEOUT_MS: number;
+/**
+ * Whether a build state is one that changes on its own.
+ *
+ * `ready` and `failed` are where a build lands; anything else — including a row
+ * whose state the platform did not send — is nothing to wait for.
+ */
+export declare function isBuildUnsettled(status?: string | null): boolean;
+export interface BuildSettleWatch {
+    /** Whether anything is still worth waiting for. Read fresh on every turn. */
+    unsettled: () => boolean;
+    /** Reads the state again. Its own failures are its business — see below. */
+    read: () => Promise<unknown>;
+}
+export interface BuildSettleOptions {
+    pollMs?: number;
+    timeoutMs?: number;
+}
+export interface BuildSettle {
+    /**
+     * Reads until nothing is unsettled, or until the ceiling. Resolves either way and
+     * throws nothing: a read that fails leaves the state as it stands and the next
+     * turn tries again, which is the same answer a surface gives its reader anyway.
+     */
+    settle: (watch: BuildSettleWatch) => Promise<void>;
+    /** Retires whatever is watching — for a surface being left. */
+    stop: () => void;
+}
+export declare function createBuildSettle(options?: BuildSettleOptions): BuildSettle;

package/dist/runtime/utils/buildSettle.js

@@ -0,0 +1,29 @@
+export const BUILD_SETTLE_POLL_MS = 2500;
+export const BUILD_SETTLE_TIMEOUT_MS = 5 * 6e4;
+export function isBuildUnsettled(status) {
+  return status === "pending" || status === "building";
+}
+export function createBuildSettle(options = {}) {
+  const pollMs = options.pollMs ?? BUILD_SETTLE_POLL_MS;
+  const timeoutMs = options.timeoutMs ?? BUILD_SETTLE_TIMEOUT_MS;
+  let generation = 0;
+  return {
+    async settle({ unsettled, read }) {
+      const mine = ++generation;
+      const started = Date.now();
+      while (Date.now() - started < timeoutMs) {
+        if (mine !== generation) return;
+        if (!unsettled()) return;
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        if (mine !== generation || !unsettled()) return;
+        try {
+          await read();
+        } catch {
+        }
+      }
+    },
+    stop() {
+      generation += 1;
+    }
+  };
+}

package/dist/runtime/utils/settingCondition.d.ts

@@ -0,0 +1,48 @@
+import type { ConfigField, SettingConditionOperator } from '../types/integrations.js';
+/**
+ * What an operator means. Mirrors the SDK's `evaluate` row for row, including
+ * the leniency of `equals` across the string/number line: a select carries `1`
+ * where a text box carries `'1'`, and an author means one thing by both.
+ */
+export declare function evaluateOperator(left: unknown, op: SettingConditionOperator, right: unknown): boolean;
+/**
+ * Whether one setting applies, given the values at its own level — inside a
+ * group, the siblings in that group, which is where the node wrote the
+ * condition and where the platform resolves it.
+ *
+ * A setting with no condition always applies, and so does one whose condition
+ * is malformed: whatever the node meant, an author is better off seeing a field
+ * than having it silently withheld.
+ */
+export declare function settingApplies(field: Pick<ConfigField, 'showIf'>, values: Record<string, unknown>): boolean;
+/**
+ * Whether a change to `changedKey` leaves this setting's value stale.
+ *
+ * Two reasons a setting can depend on another, and they do not go stale at the
+ * same moment. `dependsOn` names what a dynamic field resolves its options
+ * from, and any change to it invalidates what was chosen out of the old
+ * options. A condition names the setting that decides whether the field is
+ * drawn at all, and what was typed only becomes unreachable when the condition
+ * stops holding: while it still holds the field is on screen, and clearing it
+ * on every keystroke in the setting it reads would empty a field the author is
+ * looking at — `showIf: { key: 'url', op: 'isNotEmpty' }` stays true from the
+ * first character on.
+ */
+export declare function valueGoesStale(field: Pick<ConfigField, 'dependsOn' | 'showIf'>, changedKey: string, values: Record<string, unknown>): boolean;
+/**
+ * The settings of one level whose values are stale once `changedKey` has been
+ * set — the cascade, walked to a fixpoint over that level's own fields.
+ *
+ * `after` is the config as it stands *after* the write, because a condition is
+ * read against it: whether a setting still applies is the whole question for a
+ * `showIf` dependant. Each cleared key is taken out of that config as the walk
+ * goes, so a setting withdrawn by a clearing is found in the same pass.
+ *
+ * The setting being written is never cleared, which is also what guards a
+ * cyclic `dependsOn`.
+ */
+export declare function staleKeys(fields: Pick<ConfigField, 'key' | 'dependsOn' | 'showIf'>[], changedKey: string, after: Record<string, unknown>): Set<string>;
+/**
+ * The settings of a level that apply, in the order the node declared them.
+ */
+export declare function applyingFields(fields: ConfigField[], values: Record<string, unknown>): ConfigField[];

package/dist/runtime/utils/settingCondition.js

@@ -0,0 +1,84 @@
+const READS_PRESENCE = ["exists", "notExists", "isEmpty", "isNotEmpty"];
+const OPERATORS = [
+  "equals",
+  "notEquals",
+  "contains",
+  "notContains",
+  "startsWith",
+  "endsWith",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  ...READS_PRESENCE
+];
+export function evaluateOperator(left, op, right) {
+  switch (op) {
+    case "exists":
+      return left !== void 0 && left !== null;
+    case "notExists":
+      return left === void 0 || left === null;
+    case "isEmpty":
+      return left === "" || left === null || left === void 0 || Array.isArray(left) && left.length === 0;
+    case "isNotEmpty":
+      return !evaluateOperator(left, "isEmpty", right);
+    case "equals":
+      return String(left) === String(right);
+    case "notEquals":
+      return String(left) !== String(right);
+    case "contains":
+      return typeof left === "string" && left.includes(String(right));
+    case "notContains":
+      return typeof left === "string" && !left.includes(String(right));
+    case "startsWith":
+      return typeof left === "string" && left.startsWith(String(right));
+    case "endsWith":
+      return typeof left === "string" && left.endsWith(String(right));
+    case "greaterThan":
+      return Number(left) > Number(right);
+    case "greaterThanOrEqual":
+      return Number(left) >= Number(right);
+    case "lessThan":
+      return Number(left) < Number(right);
+    case "lessThanOrEqual":
+      return Number(left) <= Number(right);
+    default: {
+      const unhandled = op;
+      void unhandled;
+      return false;
+    }
+  }
+}
+export function settingApplies(field, values) {
+  const condition = field.showIf;
+  if (!condition || typeof condition !== "object")
+    return true;
+  const { key, op } = condition;
+  if (typeof key !== "string" || !OPERATORS.includes(op))
+    return true;
+  return evaluateOperator(values[key], op, condition.value);
+}
+export function valueGoesStale(field, changedKey, values) {
+  if ((field.dependsOn ?? []).includes(changedKey))
+    return true;
+  return field.showIf?.key === changedKey && !settingApplies(field, values);
+}
+export function staleKeys(fields, changedKey, after) {
+  const remaining = { ...after };
+  const out = /* @__PURE__ */ new Set();
+  const queue = [changedKey];
+  while (queue.length > 0) {
+    const dep = queue.shift();
+    for (const f of fields) {
+      if (f.key === changedKey || out.has(f.key)) continue;
+      if (!valueGoesStale(f, dep, remaining)) continue;
+      out.add(f.key);
+      delete remaining[f.key];
+      queue.push(f.key);
+    }
+  }
+  return out;
+}
+export function applyingFields(fields, values) {
+  return fields.filter((field) => settingApplies(field, values));
+}

package/dist/runtime/utils/stateNamespaceName.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The engine's grammar for a state namespace (PO-374), mirrored in the browser
+ * so a name it would refuse is rejected while the author types rather than as a
+ * 422 about `blob.state.0` on save.
+ *
+ * One copy on purpose. Two surfaces declare namespaces — the workflow's State
+ * dialog and the picker inside a node's state setting — and a grammar spelled
+ * once per surface is one that widens or narrows in a single place, leaving the
+ * other accepting names the engine has stopped taking.
+ */
+export declare const STATE_NAMESPACE_PATTERN: RegExp;
+/**
+ * Which message a typed namespace name earns, as a translation key — or `null`
+ * when there is nothing to say. Both callers show the same sentence for the same
+ * mistake, which is the other half of holding the grammar in one place.
+ *
+ * An empty field returns `null`: nobody has answered yet, and a rejection shown
+ * before the first keystroke reads as a rejection of the dialog.
+ *
+ * @param name  what the author has typed, trimmed here rather than by the caller
+ * @param taken the names the workflow already declares
+ */
+export declare function stateNamespaceErrorKey(name: string, taken: string[]): string | null;

package/dist/runtime/utils/stateNamespaceName.js

@@ -0,0 +1,8 @@
+export const STATE_NAMESPACE_PATTERN = /^[a-z][a-z0-9]*([._-][a-z0-9]+)*$/;
+export function stateNamespaceErrorKey(name, taken) {
+  const value = name.trim();
+  if (!value) return null;
+  if (!STATE_NAMESPACE_PATTERN.test(value)) return "integration.workflows.state.error.invalidName";
+  if (taken.includes(value)) return "integration.workflows.state.error.nameExists";
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/studio-integrations",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Integration Studio (core: workflows, node editor, runs, schedules, credentials, secrets, audit) as a standalone, publishable Nuxt module.",
   "repository": {