@revenexx/studio-integrations 2.0.0 → 2.2.0

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

@@ -359,6 +359,13 @@ export interface NodeManifest {
      * source package + slug heuristics.
      */
     groups?: LocalizedString[];
+    /**
+     * Where the node stands inside its innermost palette folder, among the nodes
+     * of the same package; lower comes first (PO-537). Optional manifest field —
+     * nodes without it follow, in their package's own order
+     * (`__packagePosition`), then by slug.
+     */
+    paletteOrder?: number;
     /** Brand images (category `logo` drives palette/canvas rendering); src is a signed URL. */
     images?: Array<{
         src: string;
@@ -405,6 +412,12 @@ export interface NodeManifest {
         name: string;
         label: string | null;
     };
+    /**
+     * Where this node stands in its package's own list of nodes, 0 first
+     * (editor-side enrichment from `GET /nodes`; not manifest data). Absent for a
+     * node registered before the service recorded it, or without a package.
+     */
+    __packagePosition?: number;
     /**
      * Whether this version's code was built and can therefore be executed
      * (editor-side enrichment from `GET /nodes`; not manifest data). Absent means

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

@@ -61,11 +61,4 @@ export declare function credentialStateLabel(key: CredentialConnState): string;
  * called from inside the table's `computed()` on every render anyway.
  */
 export declare function credentialState(c: TestableCredential): CredentialStateInfo;
-/**
- * "just now" / "3m ago" / "2h ago" / "5d ago" / a date. Empty for no timestamp.
- *
- * Reuses the studio's common time words (`integration.common.time.*`) rather
- * than minting its own — the same rule as the dashboard's `formatRelative`.
- */
-export declare function relativeTime(iso?: string | null): string;
 export {};

package/dist/runtime/utils/credentialState.js

@@ -34,15 +34,3 @@ export function credentialState(c) {
   }
   return { key: "untested", label: t(MESSAGE_KEY.untested), toneClass: TONE.untested };
 }
-export function relativeTime(iso) {
-  if (!iso) return "";
-  const at = new Date(iso).getTime();
-  if (Number.isNaN(at)) return "";
-  const t = useIntegrationsT();
-  const ms = Date.now() - at;
-  if (ms < 6e4) return t("integration.common.time.justNow");
-  if (ms < 36e5) return t("integration.common.time.minutesAgo", Math.floor(ms / 6e4));
-  if (ms < 864e5) return t("integration.common.time.hoursAgo", Math.floor(ms / 36e5));
-  if (ms < 30 * 864e5) return t("integration.common.time.daysAgo", Math.floor(ms / 864e5));
-  return new Date(iso).toLocaleDateString();
-}

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

@@ -11,6 +11,18 @@
 export declare function setStudioLocale(locale: string | null | undefined): void;
 /** The language the studio is currently rendering in. Reactive when read in an effect. */
 export declare function studioLocale(): string;
+/**
+ * The language a locale tag means, in the form the API accepts as a key.
+ *
+ * Lowercased, split on `_` as well as `-` — `en_US` is not a tag this studio
+ * produces but it is one a host can pass — and refused unless it is the two or
+ * three letters a language subtag is, because the key ends up in a map the API
+ * validates against `^[a-z]{2,3}(-[A-Z]{2})?$` with `additionalProperties: false`.
+ * A host that sets `deutsch` or `x-klingon` would otherwise take the whole workflow
+ * save down over a description nobody could see was at fault; it gets `en` instead,
+ * which is the same answer reading already gives such a host.
+ */
+export declare function baseLanguage(locale: string): string;
 /**
  * The key a read answers from — which is the key a *deletion* has to remove, since
  * what the user is clearing is the text in front of them.

package/dist/runtime/utils/localize.js

@@ -7,7 +7,7 @@ export function setStudioLocale(locale) {
 export function studioLocale() {
   return uiLocale.value;
 }
-function baseLanguage(locale) {
+export function baseLanguage(locale) {
   const base = locale.toLowerCase().split(/[-_]/)[0] ?? "";
   return /^[a-z]{2,3}$/.test(base) ? base : "en";
 }

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

@@ -0,0 +1,29 @@
+import type { NodeManifest } from '../types/integrations.js';
+/**
+ * The order of the nodes inside one palette folder (PO-537,
+ * `specs/node-palette.md` AC-8).
+ *
+ * The package decides the order of its own nodes: those that declare a
+ * `paletteOrder` come first, lowest first; the rest follow in the order the
+ * package lists them (`__packagePosition`), and a node for which neither is
+ * known falls back to its slug. Ties on a declared position are broken the same
+ * way, so the result never depends on the order the catalogue arrived in.
+ *
+ * Between packages nothing moves. A folder can take nodes from several packages
+ * (core's own folders do), and no package may reorder another's, so each package
+ * keeps exactly the places its nodes held in the incoming order and only the
+ * nodes within those places are rearranged.
+ */
+export declare function orderFolderLeaves(leaves: readonly NodeManifest[]): NodeManifest[];
+/**
+ * The order of the folders on one palette level: alphabetical, in the language
+ * the studio is shown in. Case does not count, so a brand written in lower case
+ * (`revenexx`) stands among the others rather than after them, and a letter with
+ * an accent stands where a reader of that language looks for it.
+ *
+ * Before, the folders stood in the order their first node arrived from the
+ * catalogue, which the API sorts by slug — so a folder's place depended on what
+ * its first node happened to be called (`resolve-playground` put Test Nodes
+ * before Shipcloud).
+ */
+export declare function orderFolders<T>(folders: ReadonlyMap<string, T>, locale: string): Map<string, T>;

package/dist/runtime/utils/paletteOrder.js

@@ -0,0 +1,46 @@
+import { baseLanguage } from "./localize.js";
+export function orderFolderLeaves(leaves) {
+  const byPackage = /* @__PURE__ */ new Map();
+  const keyOf = (m) => m.__package?.name ?? "";
+  for (const m of leaves) {
+    const list = byPackage.get(keyOf(m));
+    if (list) list.push(m);
+    else byPackage.set(keyOf(m), [m]);
+  }
+  for (const list of byPackage.values()) list.sort(compareWithinPackage);
+  const next = /* @__PURE__ */ new Map();
+  return leaves.map((m) => {
+    const key = keyOf(m);
+    const i = next.get(key) ?? 0;
+    next.set(key, i + 1);
+    return byPackage.get(key)[i];
+  });
+}
+function compareWithinPackage(a, b) {
+  const declared = compareOptional(finite(a.paletteOrder), finite(b.paletteOrder));
+  if (declared !== 0) return declared;
+  const listed = compareOptional(a.__packagePosition, b.__packagePosition);
+  if (listed !== 0) return listed;
+  return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
+}
+function finite(n) {
+  return typeof n === "number" && Number.isFinite(n) ? n : void 0;
+}
+function compareOptional(a, b) {
+  if (a === void 0 && b === void 0) return 0;
+  if (a === void 0) return 1;
+  if (b === void 0) return -1;
+  return a - b;
+}
+export function orderFolders(folders, locale) {
+  const collator = collatorFor(locale);
+  return new Map([...folders.entries()].sort(([a], [b]) => collator.compare(a, b)));
+}
+function collatorFor(locale) {
+  const options = { sensitivity: "base", numeric: true };
+  try {
+    return new Intl.Collator(locale, options);
+  } catch {
+    return new Intl.Collator(baseLanguage(locale), options);
+  }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * How long ago a moment was — `just now`, `40s ago`, `3m ago`, `2h ago`, `5d ago`, or
+ * a date beyond thirty days. `—` for a moment that is missing or will not parse.
+ *
+ * The one place this is worked out, for the dashboard's two panels, the runs list's
+ * **Started** column and a credential's last check (PO-393). They used to share the
+ * words (`integration.common.time.*`) and each carry its own arithmetic, and the
+ * copies disagreed: the same run read "just now" on the dashboard and "8s ago" one
+ * click away, and the dashboard's copy could print "NaNd ago".
+ *
+ * **Under ten seconds is `just now`; from there to a minute it counts seconds.** The
+ * runs list and the dashboard are live — a realtime event puts a run there moments
+ * after it happened — so "40s ago" is information an operator watching them can use.
+ * Below ten seconds the count would be finer than the three-second clock it is read
+ * against (`useNow`), and "3s ago" would skip to "6s ago".
+ *
+ * **Pass `now` from `useNow` wherever the text stays on screen.** Left at
+ * `Date.now()`, the answer is re-read only when something else re-renders, so a
+ * seconds count stands still beside an entry no event touches.
+ *
+ * **Beyond thirty days is a date, not a count of days.** "412d ago" makes the reader
+ * do the arithmetic the page should have done. The date is written in the studio's
+ * language rather than the browser's, like the words beside it.
+ *
+ * **What was not computed is not printed.** A timestamp that will not parse returns
+ * `—`, the same as none at all: `Date.now() - NaN` fails every threshold and would
+ * otherwise fall through to `daysAgo` with `NaN` as its count.
+ */
+export declare function relativeTime(iso: string | null | undefined, now?: number): string;

package/dist/runtime/utils/relativeTime.js

@@ -0,0 +1,23 @@
+import { useIntegrationsT } from "../composables/useIntegrationsT.js";
+import { studioLocale } from "./localize.js";
+const JUST_NOW = 1e4;
+const MINUTE = 6e4;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+export function relativeTime(iso, now = Date.now()) {
+  if (!iso) return "\u2014";
+  const at = new Date(iso).getTime();
+  if (Number.isNaN(at)) return "\u2014";
+  const t = useIntegrationsT();
+  const ms = now - at;
+  if (ms < JUST_NOW) return t("integration.common.time.justNow");
+  if (ms < MINUTE) return t("integration.common.time.secondsAgo", Math.floor(ms / 1e3));
+  if (ms < HOUR) return t("integration.common.time.minutesAgo", Math.floor(ms / MINUTE));
+  if (ms < DAY) return t("integration.common.time.hoursAgo", Math.floor(ms / HOUR));
+  if (ms < 30 * DAY) return t("integration.common.time.daysAgo", Math.floor(ms / DAY));
+  try {
+    return new Date(at).toLocaleDateString(studioLocale());
+  } catch {
+    return new Date(at).toLocaleDateString();
+  }
+}

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

@@ -33,12 +33,18 @@ export declare const API_RUN_STATUSES: readonly ["pending", "running", "complete
 /**
  * Platform status → the word the studio draws.
  *
- * Tolerant on purpose, and wider than {@link API_RUN_STATUSES}: the status column
- * is an uncast string on the platform's side, so a row can arrive carrying a word
- * the enum does not list. `terminated` and `timed_out` are failures to an
- * operator and the column says so; anything else fails closed for the reason it
- * does everywhere else — a run the platform cannot classify must never read as a
- * stuck `running`.
+ * The fold is not written here: {@link normalisedRunStatus} owns the one table of
+ * what each platform word means to the studio — case, separators, Temporal's
+ * American `canceled` — and this reads it. It kept a table of its own once, which
+ * knew neither `canceled` nor `COMPLETED`, so a row drew as failed a run its own
+ * record called cancelled (PO-391).
+ *
+ * What IS this function's is the clamp. The status column is an uncast string on
+ * the platform's side, so a row can arrive carrying a word no table lists; that
+ * word fails closed here for the reason it does everywhere else — a run the
+ * platform cannot classify must never read as a stuck `running`. The label passes
+ * the same word through instead, because it stores it as an identity; both clamps
+ * are deliberate, and only the table is shared.
  */
 export declare function mapRunStatus(status: string): RunStatus;
 /**

package/dist/runtime/utils/runFeedQuery.js

@@ -1,3 +1,4 @@
+import { isRunStatusWord, normalisedRunStatus } from "./statusStyle.js";
 export const API_RUN_STATUSES = [
   "pending",
   "running",
@@ -7,24 +8,8 @@ export const API_RUN_STATUSES = [
   "terminated"
 ];
 export function mapRunStatus(status) {
-  switch (status) {
-    case "completed":
-      return "succeeded";
-    case "pending":
-      return "queued";
-    case "terminated":
-      return "failed";
-    case "timed_out":
-      return "failed";
-    case "running":
-      return "running";
-    case "failed":
-      return "failed";
-    case "cancelled":
-      return "cancelled";
-    default:
-      return "failed";
-  }
+  const word = normalisedRunStatus(status);
+  return isRunStatusWord(word) ? word : "failed";
 }
 export function apiStatusesFor(words) {
   if (!words.length) return [];

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

@@ -0,0 +1,33 @@
+import type { ConfigField } from '../types/integrations.js';
+/**
+ * What a setting stores for what was typed into it.
+ *
+ * A numeric setting is filled in through either of two boxes — the plain one,
+ * and the one that also takes a mapped value — and only the plain one used to
+ * keep the number. A number typed in the other was stored as text, saved
+ * without a word, and refused the first time the workflow ran, in a message
+ * naming a setting whose own box had produced the text (PO-521). So the rule
+ * lives here, in one place, rather than in the box that happens to have it.
+ *
+ * WHEN it is applied differs by box, and has to: the plain one converts as it is
+ * typed, the mapped-value one is a document editor that reads its own value back,
+ * so it stores what was typed and converts when it is left. See `commitTyped` in
+ * NodeConfigField.
+ *
+ * Only a numeric setting is touched. A yes/no setting has the same shape of
+ * defect and is deliberately left alone: the platform refuses text there on
+ * purpose, and answering it is a different argument — recorded in the Gaps of
+ * `specs/node-configuration.md`.
+ *
+ * Three things are kept exactly as they were written:
+ *  - a mapped value, which is what the second box is for, and which resolves to
+ *    its own type when the workflow runs;
+ *  - text denoting no number, so the operator still sees what they typed and
+ *    the setting is refused by name rather than silently emptied;
+ *  - anything that is not text at all.
+ *
+ * An emptied box reads as no value rather than as `''`, which is the answer the
+ * plain numeric box has always given: `''` is a value a node reads, while the
+ * absence is what its own default answers to.
+ */
+export declare function coerceSettingValue(field: Pick<ConfigField, 'type'>, value: unknown): unknown;

package/dist/runtime/utils/settingValue.js

@@ -0,0 +1,8 @@
+export function coerceSettingValue(field, value) {
+  if (field?.type !== "number" || typeof value !== "string") return value;
+  if (value.includes("${{")) return value;
+  if (value.trim() === "") return null;
+  const n = Number(value);
+  if (!Number.isFinite(n) || /^\s*[+-]?0[xbo]/i.test(value)) return value;
+  return n;
+}

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

@@ -47,14 +47,8 @@ export declare const RUN_STATUS_WORDS: readonly ["running", "succeeded", "failed
  * this number is the fix at that point — not making the track elastic.
  */
 export declare const RUN_STATUS_COLUMN_WIDTH = "160px";
-/**
- * Raw API/Temporal run vocabulary → the cockpit's run-status labels, so a run
- * never reads "completed" in one surface and "succeeded" in another. This IS
- * the studio's own chrome (Temporal's "completed" becomes our "succeeded"), so
- * unlike a raw `run.status` read elsewhere, it is translated. Unknown statuses
- * still pass through lowercased, untranslated — this function only relabels
- * the fixed run-status vocabulary, not arbitrary strings.
- */
+/** Whether a normalised status is one of the studio's own five words. */
+export declare function isRunStatusWord(word: string): word is (typeof RUN_STATUS_WORDS)[number];
 /**
  * The platform's run vocabulary reduced to the studio's own five words — Temporal's
  * `completed` is our `succeeded`, `pending` is `queued`, and two ways of dying are
@@ -64,6 +58,12 @@ export declare const RUN_STATUS_COLUMN_WIDTH = "160px";
  * list narrows by it, and what a filter stores has to be something that does not move
  * when the reader's language does. Both sides read this, so a filter and a row can
  * never disagree about which status they mean.
+ *
+ * **The table below is the only one.** `mapRunStatus` reads it too and adds a clamp of
+ * its own — an unknown word fails closed there. The clamp here is this function's: an
+ * unknown word passes through, lower-cased, because it is stored as an identity and
+ * labelled as a raw field rather than as one of the studio's words. Change what a
+ * platform word *means* here; change what an *unknown* one becomes at the caller.
  */
 export declare function normalisedRunStatus(status: string | null | undefined): string;
 /**

package/dist/runtime/utils/statusStyle.js

@@ -79,6 +79,9 @@ export function toneClass(tone) {
 export const RUN_STATUS_WORDS = ["running", "succeeded", "failed", "cancelled", "queued"];
 export const RUN_STATUS_COLUMN_WIDTH = "160px";
 const RUN_STATUS_WORD_SET = new Set(RUN_STATUS_WORDS);
+export function isRunStatusWord(word) {
+  return RUN_STATUS_WORD_SET.has(word);
+}
 export function normalisedRunStatus(status) {
   if (!status) return "";
   const s = String(status).toLowerCase().replace(/[\s-]+/g, "_");
@@ -106,7 +109,7 @@ export function runStatusClass(status) {
 export function runStatusLabel(status) {
   const normalized = normalisedRunStatus(status);
   if (!normalized) return "";
-  if (!RUN_STATUS_WORD_SET.has(normalized)) return normalized;
+  if (!isRunStatusWord(normalized)) return normalized;
   return useIntegrationsT()(`integration.runs.status.${normalized}`);
 }
 const MISSED_RUN_STATUS_TONE = /* @__PURE__ */ new Map([

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

@@ -0,0 +1,119 @@
+import type { ConfigField, Workflow, WorkflowBlob, WorkflowExecutionMode, WorkflowNode, WorkflowTrigger } from '../types/integrations.js';
+/**
+ * A workflow as a file — what Export writes and Import reads (specs/workflow-file.md).
+ *
+ * Versioned like the editor's clipboard envelope (`revenexx.workflow.nodes`), and for
+ * the same reason: a file outlives the build that wrote it, so the reader has to be
+ * able to tell "not one of ours" and "one of ours from a format I do not know" apart
+ * from "broken", and refuse each of them rather than guess.
+ *
+ * Everything here is pure. The stores, the download and the dialogs live with the
+ * callers; what a file may carry and how it lands in a tenant is decided here once, so
+ * the list, the new-workflow dialog and the editor cannot disagree about it.
+ */
+export declare const WORKFLOW_FILE_KIND = "revenexx.workflow";
+export declare const WORKFLOW_FILE_VERSION = 1;
+export interface WorkflowFile {
+    kind: typeof WORKFLOW_FILE_KIND;
+    version: typeof WORKFLOW_FILE_VERSION;
+    workflow: {
+        name: string;
+        description: string | null;
+        executionMode: WorkflowExecutionMode;
+        blobDefinitionVersion: string;
+        blob: WorkflowBlob;
+    };
+}
+/** The settings a node declares, or null where this environment does not know the node. */
+export type FieldsFor = (node: WorkflowNode) => ReadonlyArray<ConfigField> | null;
+/**
+ * The blob with every credential reference taken out of every node's settings.
+ *
+ * Two sweeps, because neither is complete alone:
+ *  - **By declaration.** A setting the node declares as a credential is removed,
+ *    also inside an object setting and inside each row of a list setting. This is
+ *    what catches a reference to a credential of ANOTHER tenant — a file written
+ *    elsewhere — which no list of this tenant's credentials would recognise.
+ *  - **By value.** Any string equal to one of `credentialIds` is removed wherever
+ *    it stands. This is what catches the settings no declaration describes: a node
+ *    this environment does not have, and a setting whose shape is resolved while
+ *    authoring rather than declared up front.
+ *
+ * Removed, not blanked: an absent key is what an unset setting looks like, and it
+ * is what the editor and the platform both report as "needs a credential".
+ */
+export declare function withoutCredentials(blob: WorkflowBlob, fieldsFor: FieldsFor, credentialIds?: ReadonlySet<string>): WorkflowBlob;
+/** The file for a saved workflow: its settings, never its credentials. */
+export declare function toWorkflowFile(wf: Workflow, fieldsFor: FieldsFor, credentialIds: ReadonlySet<string>): WorkflowFile;
+/**
+ * Whether the workflow holds values of its own the operator may not mean to send
+ * along — the only case Export stops to say what the file contains. A variable
+ * declared without a value carries nothing.
+ */
+export declare function hasVariableValues(blob: WorkflowBlob): boolean;
+/** `Order sync (staging)` → `order-sync-staging.workflow.json`. */
+export declare function workflowFileName(name: string): string;
+/** Why a file was refused — each one is a different sentence to the operator. */
+export type WorkflowFileRefusal = 'unreadable' | 'kind' | 'version' | 'definition';
+export type ParsedWorkflowFile = {
+    ok: true;
+    file: WorkflowFile;
+} | {
+    ok: false;
+    reason: WorkflowFileRefusal;
+};
+/**
+ * Reads a file, or says why not. Nothing a refused file contains reaches the caller.
+ *
+ * A definition version this studio does not know is refused here, not left to the
+ * platform: the studio writes its own version on every save, so a newer definition
+ * would not be refused on the way in — it would be relabelled and saved as one it
+ * is not.
+ */
+export declare function parseWorkflowFile(text: string): ParsedWorkflowFile;
+/**
+ * Gives each trigger a handle, keeping the one it has wherever the tenant can take it.
+ *
+ * A trigger's id IS its handle at the platform, unique per tenant. Keeping it across
+ * environments is what lets a later import over the same workflow recognise its
+ * triggers — and with them the webhook addresses callers already use. Where it cannot
+ * be kept (another workflow of this tenant holds it, it is not a handle the platform
+ * accepts, or it is `taken` for any other reason) the trigger gets a fresh one, and
+ * every connection and canvas position keyed by the old one follows.
+ *
+ * With every id in `taken`, this is exactly what duplicating does.
+ */
+export declare function assignTriggerHandles(blob: WorkflowBlob, taken: ReadonlySet<string>, keep?: (trigger: WorkflowTrigger) => boolean): WorkflowBlob;
+/** Every trigger off: nothing a copy brings may act before somebody has looked at it. */
+export declare function pausedTriggers(blob: WorkflowBlob): WorkflowBlob;
+/** The blob a new workflow is created from: no credentials, handles kept where free, nothing on. */
+export declare function blobForNewWorkflow(file: WorkflowFile, fieldsFor: FieldsFor, tenantHandles: ReadonlySet<string>, credentialIds?: ReadonlySet<string>): WorkflowBlob;
+export interface OverwritePlan {
+    blob: WorkflowBlob;
+    /** What the workflow holds now, and what it will hold — for the confirmation. */
+    replaced: {
+        nodes: number;
+        triggers: number;
+    };
+    incoming: {
+        nodes: number;
+        triggers: number;
+    };
+}
+/**
+ * The content a file puts in place of an existing workflow's — all of it.
+ *
+ * Nodes, connections, variables, groups and notes come from the file. What the target
+ * keeps is what callers outside the studio depend on: a trigger in the file with the
+ * same id and kind as one the workflow already has stays THAT trigger — its handle,
+ * its endpoint, its secret and whether it is on — and takes its settings from the
+ * file. A trigger only the target had is gone; one only the file has arrives off,
+ * keeping its id where the tenant can take it.
+ *
+ * Credentials are not carried over from the target either. A node that had one before
+ * the import has none after it, and saving an active workflow is refused until they
+ * are chosen again — which is what keeps the running version running meanwhile.
+ *
+ * `otherHandles` are the trigger handles held by the tenant's OTHER workflows.
+ */
+export declare function overwritePlan(target: WorkflowBlob, file: WorkflowFile, fieldsFor: FieldsFor, otherHandles: ReadonlySet<string>, credentialIds?: ReadonlySet<string>): OverwritePlan;