@revenexx/studio-integrations 1.3.0 → 1.4.1

package/dist/runtime/utils/apiEnvelope.js

@@ -0,0 +1,20 @@
+import { IntegrationsApiError } from "./apiError.js";
+export function unwrapRecord(res, ownFields = []) {
+  if (res === null || res === void 0) {
+    throw new IntegrationsApiError(200, res, "");
+  }
+  if (typeof res === "object" && "data" in res && !ownFields.some((f) => f in res)) {
+    const data = res.data;
+    if (data === null || data === void 0) {
+      throw new IntegrationsApiError(200, res, "");
+    }
+    return data;
+  }
+  return res;
+}
+export function unwrapList(res) {
+  if (Array.isArray(res)) return res;
+  const data = res?.data;
+  if (Array.isArray(data)) return data;
+  throw new IntegrationsApiError(200, res, "");
+}

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

@@ -35,21 +35,48 @@ export declare function apiValidationIssues(err: unknown): {
     path: string;
     message: string;
 }[];
+/** One message the service keyed to a field, as it keyed it. */
+export interface RefusalMessage {
+    key: string;
+    message: string;
+}
+/**
+ * A refusal split by what the form on screen can show of it.
+ *
+ * `atFields` is what goes under an input, keyed the way the form draws it; `unshown`
+ * is everything left over — the reasons that have no input to stand at, in the order
+ * the service listed them.
+ */
+export interface Refusal {
+    atFields: Record<string, string>;
+    unshown: RefusalMessage[];
+}
 /**
- * Field-keyed validation messages from a rejection, as `{ field: message }`.
+ * A rejection split into the messages a form can show at a field and the messages it
+ * cannot, given the keys that form actually draws.
  *
  * The counterpart to `apiValidationIssues` above, for the ordinary case that has
  * nothing to do with the workflow blob: a form field the service refused, named the
  * way the form names it. Laravel answers a `422` with `errors` keyed by field and a
- * list of messages per key; the first message is the one a person reads, so that is
- * the one kept.
+ * list of messages per key; at a field the first message is the one a person reads,
+ * so that is the one kept.
+ *
+ * **`drawn` is the form's own list, in the order the form draws it** — the name, then
+ * the fields of the chosen type, and nothing while those are hidden behind another
+ * source. A key absent from it has no input to be shown at, whether because no form
+ * draws that field (`config` as a whole, a field the type never declared, a key that
+ * is not a field at all) or because this form is currently drawing something else.
+ * Both cases go to `unshown`, which is what the surface states below the form: a
+ * refusal nobody can see is the same as no answer at all (PO-275, PO-477).
+ *
+ * A container that is only at fault because one of its members is — `config` beside
+ * `config.authKey`, which the service reports as two — is dropped wherever the member
+ * is reported too: it says the same thing twice, and the member carries it either way.
  *
- * A form uses this to put the refusal where the operator is looking — "The name has
- * already been taken." under the Name field, rather than as a sentence somewhere
- * else about a field they then have to find (PO-275). Keys that address the blob are
- * left out: those belong to `apiValidationIssues`, which resolves them to nodes.
+ * Keys that address the blob are left out: those belong to `apiValidationIssues`,
+ * which resolves them to nodes. No credential surface can receive one.
  */
-export declare function apiFieldErrors(err: unknown): Record<string, string>;
+export declare function apiRefusal(err: unknown, drawn: readonly string[]): Refusal;
 /**
  * The reason a rejection gives, without the count of everything else it found.
  *

package/dist/runtime/utils/apiError.js

@@ -18,20 +18,20 @@ export function apiValidationIssues(err) {
   }
   return issues;
 }
-export function apiFieldErrors(err) {
-  if (!(err instanceof IntegrationsApiError) || err.status !== 422) return {};
+export function apiRefusal(err, drawn) {
+  const refusal = { atFields: {}, unshown: [] };
+  if (!(err instanceof IntegrationsApiError) || err.status !== 422) return refusal;
   const errors = err.body?.errors;
-  if (!errors || typeof errors !== "object") return {};
-  const out = {};
-  for (const [key, val] of Object.entries(errors)) {
-    if (key === "blob" || key.startsWith("blob.")) continue;
-    const first = Array.isArray(val) ? val[0] : val;
-    if (first !== void 0 && first !== null) out[key] = String(first);
-  }
-  for (const key of Object.keys(out)) {
-    if (Object.keys(out).some((other) => other.startsWith(`${key}.`))) delete out[key];
+  if (!errors || typeof errors !== "object") return refusal;
+  const keys = Object.keys(errors).filter((key) => key !== "blob" && !key.startsWith("blob."));
+  for (const key of keys) {
+    if (keys.some((other) => other.startsWith(`${key}.`))) continue;
+    const messages = (Array.isArray(errors[key]) ? errors[key] : [errors[key]]).filter((message) => message !== void 0 && message !== null).map(String);
+    if (!messages.length) continue;
+    if (drawn.includes(key)) refusal.atFields[key] = messages[0];
+    else refusal.unshown.push(...messages.map((message) => ({ key, message })));
   }
-  return out;
+  return refusal;
 }
 export function errorReason(err, fallback) {
   const raw = err?.message?.trim();

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

@@ -0,0 +1,18 @@
+import type { ConfigField } from '../types/integrations.js';
+/**
+ * The config a set of settings starts life with: what each one declares as its
+ * default, and nothing else.
+ *
+ * A setting with no `default` is left OUT rather than written as an empty
+ * string, because the two are different answers. `''` is a value — the engine
+ * reads it, `??` does not replace it, and a node whose own default would have
+ * applied never gets to apply it. An absent key is the absence the node's
+ * default answers to.
+ *
+ * Used in the two places a fresh set of values is made: a node dropped on the
+ * canvas (WorkflowEditor), and a row added to a list setting (NodeConfigField).
+ * Flat on purpose — it reads `default` at the level it is given and does not
+ * descend into `properties` or `items`, so what a newly inserted node carries
+ * is exactly what it carried before this became shared.
+ */
+export declare function defaultsFor(fields?: ReadonlyArray<Pick<ConfigField, 'key' | 'default'>>): Record<string, unknown>;

package/dist/runtime/utils/configDefaults.js

@@ -0,0 +1,7 @@
+export function defaultsFor(fields = []) {
+  const out = {};
+  for (const f of fields ?? []) {
+    if (f.default !== void 0) out[f.key] = f.default;
+  }
+  return out;
+}

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

@@ -0,0 +1,60 @@
+import type { WorkflowBlob } from '../types/integrations.js';
+/**
+ * Nodes that route failures to an error output nothing is connected to
+ * (specs/workflow-advice.md).
+ *
+ * A step that fails on a path its author drew is handled. A step that fails on a
+ * path nobody drew is not: the engine ends the run there
+ * (`specs/node-failure-handling.md` AC-8 in the service repository), and before
+ * it did, the failure vanished and the run reported success. Either way the
+ * author never chose it — they simply never saw the port.
+ *
+ * ## Why this is advice and not a finding
+ *
+ * The backend's validation findings feed the activation gate AND an
+ * unconditional refusal to start a run. A finding here would therefore stop
+ * every workflow with an unwired error port from running at all — turning
+ * "delivers nothing quietly" into "does not start", for authors who never asked
+ * for either. Computing it in the editor makes that impossible rather than
+ * merely unlikely: there is no value for a blocking consumer to read.
+ *
+ * What the client cannot do is be authoritative — the catalogue may not be
+ * loaded, and a workflow built through the API never passes here at all. For
+ * advice that is the right trade; for a gate it would not be, which is why the
+ * gate stays where the manifests are.
+ *
+ * ## Deliberately not in `validationFindings.ts`
+ *
+ * Everything there is a backend finding addressed by blob path, and the node
+ * card counts those as *incomplete settings*. An unwired port is neither. Sent
+ * through `groupFindingsByNode` it would type-check perfectly and quietly
+ * corrupt two counts — the banner's and the card badge's.
+ */
+export interface ErrorPathAdvice {
+    /** Blob node id — not an index, so it survives a node being added or removed. */
+    nodeId: string;
+    /** The error output with nothing attached. */
+    port: string;
+}
+/**
+ * Every unwired error output in the blob, in node order.
+ *
+ * Runs against the blob the author is *editing*, not the saved one, so wiring a
+ * port clears its line in the same tick — no save, and no second copy of this
+ * rule to decide when the advice went stale.
+ *
+ * **Resolved against whichever manifest version the catalogue has.**
+ * `findManifest` falls back to another version of the same slug when the pinned
+ * one is absent, and that fallback is accepted here: a node pinned to a version
+ * nobody serves any more is better described by a sibling version than by
+ * silence. The cost is real though — where the versions disagree about their
+ * ports, the advice describes the sibling's, so a port could be named that the
+ * author's own node does not have.
+ *
+ * **Reads the manifest's static outputs only.** A node whose ports are named at
+ * author time (`sourceFromConfig` / `resolveOutputs`) cannot be judged from the
+ * declaration alone, so nothing is claimed about it — the same forbearance the
+ * engine shows. No shipped node has a dynamic error port today; if one appears,
+ * this is where it would silently escape notice.
+ */
+export declare function unwiredErrorPorts(blob: Pick<WorkflowBlob, 'nodes' | 'edges'>): ErrorPathAdvice[];

package/dist/runtime/utils/errorPathAdvice.js

@@ -0,0 +1,19 @@
+import { findManifest } from "../data/integrationNodeCatalog.js";
+export function unwiredErrorPorts(blob) {
+  const advice = [];
+  for (const node of blob.nodes) {
+    const manifest = findManifest(node.nodeSlug, node.nodeVersion);
+    if (!manifest) continue;
+    const errorPorts = (manifest.outputs ?? []).filter((o) => o.kind === "error" && o.name).map((o) => o.name);
+    if (!errorPorts.length) continue;
+    if (!isReachable(node, blob, errorPorts)) continue;
+    for (const port of errorPorts) {
+      const wired = blob.edges.some((e) => e.from.nodeId === node.id && e.from.output === port);
+      if (!wired) advice.push({ nodeId: node.id, port });
+    }
+  }
+  return advice;
+}
+function isReachable(node, blob, errorPorts) {
+  return blob.edges.some((e) => e.to.nodeId === node.id) || blob.edges.some((e) => e.from.nodeId === node.id && !errorPorts.includes(e.from.output));
+}

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

@@ -13,10 +13,10 @@ export declare const toast: ((message: string | (() => string | import("vue").Co
     custom: (component: import("vue").Component, data?: import("vue-sonner").ExternalToast) => string | number;
     message: (message: string | (() => string | import("vue").Component) | import("vue").Component, data?: import("vue-sonner").ExternalToast) => string | number;
     promise: <ToastData>(promise: Promise<ToastData> | (() => Promise<ToastData>), data?: ({
+        id?: number | string | undefined;
+        class?: string | undefined;
         action?: (import("vue-sonner").Action | import("vue").Component) | undefined;
         icon?: import("vue").Component | undefined;
-        class?: string | undefined;
-        id?: number | string | undefined;
         position?: ("top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center") | undefined;
         toasterId?: string | undefined;
         component?: import("vue").Component | undefined;

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

@@ -11,6 +11,13 @@ export type RunLike = Record<string, unknown>;
  * looks like a run (`status`, `temporal_run_id`) is the run, whatever else it has
  * on it.
  *
+ * The two guards are `RUN_OWN_FIELDS`, exported because `unwrapRecord` reads the
+ * same endpoint from `useIntegrationsRuns.ts` and has to apply the same rule —
+ * one list, two readers, rather than the two literals that used to sit here
+ * (PO-394). What stays different is deliberate: this one answers `null` where
+ * `unwrapRecord` throws, because a caller following a run has to count an
+ * unusable answer as a failed read rather than have it raised at it.
+ *
  * This is deliberately generous about the *rest* of the shape. It answers "where
  * is the run in this body", not "is this a usable run" — the caller decides that,
  * because a caller following a run has to be able to count an unusable answer as
@@ -28,4 +35,9 @@ export declare const RUN_TERMINAL: Set<string>;
 export declare function isTerminalRun(run: {
     status?: unknown;
 } | null | undefined): boolean;
+/**
+ * The fields that mark a body as the run itself rather than an envelope around
+ * one. A run carrying its own `data` field would otherwise be unwrapped into it.
+ */
+export declare const RUN_OWN_FIELDS: readonly ["status", "temporal_run_id"];
 export declare function unwrapRun(res: unknown): RunLike | null;

package/dist/runtime/utils/runEnvelope.js

@@ -2,10 +2,11 @@ export const RUN_TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "can
 export function isTerminalRun(run) {
   return RUN_TERMINAL.has(String(run?.status ?? "").toLowerCase());
 }
+export const RUN_OWN_FIELDS = ["status", "temporal_run_id"];
 export function unwrapRun(res) {
   if (!res || typeof res !== "object") return null;
   const o = res;
-  if ("data" in o && o.data && typeof o.data === "object" && !("status" in o) && !("temporal_run_id" in o)) {
+  if ("data" in o && o.data && typeof o.data === "object" && !RUN_OWN_FIELDS.some((f) => f in o)) {
     return o.data;
   }
   return o;

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

@@ -0,0 +1,48 @@
+/**
+ * Carrying a node's declared options through a select that reserves the empty
+ * string for "nothing chosen".
+ *
+ * "No choice" is a legitimate thing for a node to offer — "as the file came in",
+ * "unchanged", "all kinds" — and three node types in two packages arrived at the
+ * same way of writing it: an option with an empty value. The select underneath
+ * this UI refuses it: the empty string is how it says nothing is selected, so an
+ * item may not also carry it. Handed one anyway it throws while the list mounts,
+ * and takes the surrounding dialog's dismissal machinery down with it — nothing
+ * opened afterwards could be closed again.
+ *
+ * So every option value is carried under a substitute and swapped back on the way
+ * out. **Every** one, rather than only the empty value: a sentinel that stood
+ * beside untouched values would be a value a node could declare itself, and
+ * declaring it would silently store the empty string instead. Here a declared
+ * value always arrives prefixed and the empty one never is, so the two cannot
+ * collide whatever a node writes. What the node reads is unchanged.
+ */
+/** What the option meaning "no choice" is carried under. */
+export declare const EMPTY_OPTION_VALUE = "option-empty";
+/** Does this list of options ask for the substitute at all? */
+export declare function hasEmptyOption(options: Array<{
+    value: unknown;
+}> | undefined): boolean;
+/**
+ * An option's value as the select may receive it. That is the guard: the item
+ * component cannot be handed an empty value from here, whatever a node declares.
+ */
+export declare function toItemValue(value: unknown): string;
+/**
+ * The stored value as the select's model — encoded the way the items are, or it
+ * matches none of them and the trigger falls back to its placeholder.
+ *
+ * `null` is read as the empty option alongside the empty string, because that is
+ * what the platform hands back for one: Laravel converts an empty string to null
+ * anywhere in a request body, so the value chosen here returns as null on the next
+ * open and the choice would otherwise be gone. A setting with no value at all is
+ * not: nothing is stored for it, and a trigger claiming a choice the config does
+ * not hold would be the placeholder's lie in the other direction. A node that
+ * offers "no choice" declares it as the field's default, so a step placed on the
+ * canvas has the empty string from the start.
+ */
+export declare function toModelValue(value: unknown, options: Array<{
+    value: unknown;
+}> | undefined): string;
+/** What the select hands back, as the node wants it stored. */
+export declare function fromModelValue(value: string): string;

package/dist/runtime/utils/selectOptions.js

@@ -0,0 +1,19 @@
+const OPTION_VALUE_PREFIX = "option:";
+export const EMPTY_OPTION_VALUE = "option-empty";
+export function hasEmptyOption(options) {
+  return (options ?? []).some((o) => String(o.value) === "");
+}
+export function toItemValue(value) {
+  const s = String(value);
+  return s === "" ? EMPTY_OPTION_VALUE : OPTION_VALUE_PREFIX + s;
+}
+export function toModelValue(value, options) {
+  if (value === "" || value === null || value === void 0) {
+    return value !== void 0 && hasEmptyOption(options) ? EMPTY_OPTION_VALUE : "";
+  }
+  return OPTION_VALUE_PREFIX + String(value);
+}
+export function fromModelValue(value) {
+  if (value === EMPTY_OPTION_VALUE) return "";
+  return value.startsWith(OPTION_VALUE_PREFIX) ? value.slice(OPTION_VALUE_PREFIX.length) : value;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * How a keyboard shortcut is written for a reader, and which physical modifier
+ * `mod` stands for.
+ *
+ * ONE COPY, deliberately. This table existed twice — in the canvas context
+ * menu and in the control pane's tooltip — and the platform test existed a
+ * third time inside the shortcuts composable. The two tables had already
+ * drifted: the tooltip's knew nothing about `backspace`, `tab` or `space`, so a
+ * token it was never handed would have rendered as `BACKSPACE`. A shortcut is
+ * about to be shown in a third place (the overview the canvas opens), which is
+ * two copies too many.
+ *
+ * `IS_MAC` reads `navigator.platform`, which is deprecated and reports
+ * `MacIntel` for an iPad. It is kept because the replacement
+ * (`navigator.userAgentData.platform`) is not in every browser we serve, and
+ * because being wrong here costs a wrong glyph rather than a wrong key: the
+ * MATCHING side reads the same flag, so a machine we misread is a machine where
+ * ⌘ and Ctrl swap together and nothing goes silent.
+ */
+export declare const IS_MAC: boolean;
+/**
+ * A shortcut token string as a reader sees it: `'mod+enter'` → `⌘↵` on a mac,
+ * `Ctrl+↵` elsewhere.
+ *
+ * Alternatives are not rendered — `'f2|space'` is two ways to press one thing,
+ * and a caller that wants both writes both. Pass `isMac` to render for the other
+ * platform, which is what the unit suite does.
+ */
+/**
+ * A token string split into its tokens, where one of the tokens may be the
+ * separator itself.
+ *
+ * `'+'.split('+')` is two empty strings, and `'mod++'` is `['mod', '', '']` — so
+ * a pair of empties is a literal `+`. Without this the character disappeared:
+ * on a mac, where caps are joined with nothing, `+` rendered as an empty key cap,
+ * and elsewhere the join only put it back by accident. Exported so the matcher
+ * reads a binding the same way this writes it.
+ */
+export declare function shortcutTokens(tokens: string): string[];
+export declare function formatShortcut(tokens: string, isMac?: boolean): string;

package/dist/runtime/utils/shortcutLabel.js

@@ -0,0 +1,48 @@
+export const IS_MAC = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform ?? "");
+const MAC_TOKENS = {
+  mod: "\u2318",
+  shift: "\u21E7",
+  alt: "\u2325",
+  ctrl: "\u2303"
+};
+const OTHER_TOKENS = {
+  mod: "Ctrl",
+  shift: "Shift",
+  alt: "Alt",
+  ctrl: "Ctrl"
+};
+const KEY_TOKENS = {
+  enter: "\u21B5",
+  backspace: "\u232B",
+  delete: "Del",
+  escape: "Esc",
+  tab: "Tab",
+  space: "Space",
+  arrowup: "\u2191",
+  arrowdown: "\u2193",
+  arrowleft: "\u2190",
+  arrowright: "\u2192"
+};
+export function shortcutTokens(tokens) {
+  const parts = tokens.split("+");
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === "" && parts[i + 1] === "") {
+      out.push("+");
+      i++;
+      continue;
+    }
+    if (parts[i] === "") continue;
+    out.push(parts[i]);
+  }
+  return out;
+}
+export function formatShortcut(tokens, isMac = IS_MAC) {
+  const mods = isMac ? MAC_TOKENS : OTHER_TOKENS;
+  const out = [];
+  for (const raw of shortcutTokens(tokens)) {
+    const t = raw.toLowerCase();
+    out.push(mods[t] ?? KEY_TOKENS[t] ?? (t.length === 1 ? t.toUpperCase() : t.charAt(0).toUpperCase() + t.slice(1)));
+  }
+  return isMac ? out.join("") : out.join("+");
+}

package/package.json

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