@revenexx/integrations-node-sdk 0.18.0 → 1.0.0

package/dist/cli.cjs

@@ -74,7 +74,7 @@ function isSafeRelativePath(src) {
     return false;
   }
   const normalized = (0, import_node_path.normalize)(src);
-  return normalized !== ".." && !normalized.startsWith(".." + import_node_path.sep);
+  return normalized !== ".." && !normalized.startsWith(`..${import_node_path.sep}`);
 }
 
 // src/extract.ts
@@ -192,6 +192,7 @@ async function main() {
         "The `publish` command has been removed. Node packages are no longer published from the repos themselves \u2014 registration happens through the Revenexx Console/Cockpit. For local development, use `integrations/scripts/register-nodes-core.sh`, which packs and uploads the tarball to the admin API."
       );
       process.exit(1);
+      break;
     default:
       console.error("Usage: rvnxx-nodes <manifest>");
       process.exit(1);

package/dist/cli.js

@@ -55,7 +55,7 @@ function isSafeRelativePath(src) {
     return false;
   }
   const normalized = normalize(src);
-  return normalized !== ".." && !normalized.startsWith(".." + sep);
+  return normalized !== ".." && !normalized.startsWith(`..${sep}`);
 }
 
 // src/cli.ts
@@ -132,6 +132,7 @@ async function main() {
         "The `publish` command has been removed. Node packages are no longer published from the repos themselves \u2014 registration happens through the Revenexx Console/Cockpit. For local development, use `integrations/scripts/register-nodes-core.sh`, which packs and uploads the tarball to the admin API."
       );
       process.exit(1);
+      break;
     default:
       console.error("Usage: rvnxx-nodes <manifest>");
       process.exit(1);

package/dist/index.cjs

@@ -46,12 +46,15 @@ __export(index_exports, {
   NodeError: () => NodeError,
   OAuth2AuthCodeCredential: () => OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential: () => OAuth2ClientCredentialsCredential,
+  OPERATORS: () => OPERATORS,
   RetryableError: () => RetryableError,
   SimpleValueCredential: () => SimpleValueCredential,
+  VALUELESS_OPERATORS: () => VALUELESS_OPERATORS,
   assertPublicUrl: () => assertPublicUrl,
   backoffDelay: () => backoffDelay,
   buildManifest: () => buildManifest,
   clampResponseBytes: () => clampResponseBytes,
+  evaluate: () => evaluate,
   extractCredentialManifest: () => extractCredentialManifest,
   extractCredentialManifests: () => extractCredentialManifests,
   extractManifest: () => extractManifest,
@@ -59,6 +62,7 @@ __export(index_exports, {
   isBlockedAddress: () => isBlockedAddress,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
+  isOperator: () => isOperator,
   maxBytesConfigField: () => maxBytesConfigField,
   normalizeCredentialType: () => normalizeCredentialType,
   normalizeLocalized: () => normalizeLocalized,
@@ -68,7 +72,9 @@ __export(index_exports, {
   readText: () => readText,
   retryConfigFields: () => retryConfigFields,
   safeFetch: () => safeFetch,
+  settingApplies: () => settingApplies,
   sleepWithSignal: () => sleepWithSignal,
+  takesValue: () => takesValue,
   timeoutConfigField: () => timeoutConfigField,
   withRetry: () => withRetry
 });
@@ -103,6 +109,75 @@ function normalizeLocalized(value, fallbackLang = "en") {
   return void 0;
 }
 
+// src/operators.ts
+var OPERATORS = [
+  "equals",
+  "notEquals",
+  "contains",
+  "notContains",
+  "startsWith",
+  "endsWith",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "exists",
+  "notExists",
+  "isEmpty",
+  "isNotEmpty"
+];
+var VALUELESS_OPERATORS = ["exists", "notExists", "isEmpty", "isNotEmpty"];
+function isOperator(value) {
+  return typeof value === "string" && OPERATORS.includes(value);
+}
+function takesValue(op) {
+  return !VALUELESS_OPERATORS.includes(op);
+}
+function evaluate(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 !evaluate(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 _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+
+// src/conditions.ts
+function settingApplies(field, config) {
+  const condition = field.showIf;
+  if (!condition) return true;
+  return evaluate(config[condition.key], condition.op, condition.value);
+}
+
 // src/credentialType.ts
 function normalizeCredentialType(value) {
   const raw = value === void 0 ? [] : Array.isArray(value) ? value : [value];
@@ -526,7 +601,7 @@ function abortReason(signal) {
 }
 function backoffDelay(attempt, policy) {
   const exponent = Math.max(0, attempt - 1);
-  const raw = policy.baseDelayMs * Math.pow(policy.factor, exponent);
+  const raw = policy.baseDelayMs * policy.factor ** exponent;
   const cap = Math.min(policy.maxDelayMs, raw);
   return policy.jitter ? Math.random() * cap : cap;
 }
@@ -628,7 +703,25 @@ var BaseCredential = class {
     }
     return { ok: true };
   }
-  /** POST `application/x-www-form-urlencoded` and parse a JSON token response. */
+  /**
+   * POST `application/x-www-form-urlencoded` and parse a JSON token response.
+   *
+   * Goes through {@link safeFetch}, not a raw `fetch` (PO-185). The token
+   * endpoint is not a constant: `tokenUrl(config)` derives it from credential
+   * config, i.e. from a value someone types into a credential form. A raw fetch
+   * would happily POST the client secret at `http://169.254.169.254/…` or any
+   * other internal address, which is precisely what `assertPublicUrl` exists to
+   * prevent. Every OAuth token exchange in this file — client-credentials,
+   * auth-code, refresh — funnels through here, so this is the one call site that
+   * has to hold.
+   *
+   * Two behaviours safeFetch adds, both wanted here: a request budget
+   * (`DEFAULT_TIMEOUT_MS`) on top of `ctx.signal`, and manual redirect handling
+   * that re-checks each hop and drops `Authorization` across an origin boundary.
+   * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
+   * per the redirect rules, not a quirk of ours. Real token endpoints do not
+   * redirect; one that does was never going to complete the exchange anyway.
+   */
   async postForm(ctx, url, form, headers = {}) {
     const body = new URLSearchParams();
     for (const [key, value] of Object.entries(form)) {
@@ -636,7 +729,7 @@ var BaseCredential = class {
         body.set(key, value);
       }
     }
-    const res = await fetch(url, {
+    const res = await safeFetch(url, {
       method: "POST",
       signal: ctx.signal,
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", ...headers },
@@ -821,12 +914,15 @@ function base64Url(buf) {
   NodeError,
   OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential,
+  OPERATORS,
   RetryableError,
   SimpleValueCredential,
+  VALUELESS_OPERATORS,
   assertPublicUrl,
   backoffDelay,
   buildManifest,
   clampResponseBytes,
+  evaluate,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
@@ -834,6 +930,7 @@ function base64Url(buf) {
   isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
+  isOperator,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
@@ -843,7 +940,9 @@ function base64Url(buf) {
   readText,
   retryConfigFields,
   safeFetch,
+  settingApplies,
   sleepWithSignal,
+  takesValue,
   timeoutConfigField,
   withRetry
 });

package/dist/index.d.cts

@@ -1,8 +1,36 @@
+/**
+ * The comparison vocabulary, in one place because it is read in three:
+ * a node that compares two values (a condition, a filter), a settings condition
+ * saying when a field applies (`IConfigField.showIf`), and the editor drawing
+ * that field. An author who has met these words in one of the three must not
+ * have to learn a second set for the others.
+ *
+ * The names are the vocabulary; what each one *means* is {@link evaluate}, and
+ * the answer table in `operators.test.ts` is what a second implementation of it
+ * — the editor, the platform's workflow validator — is checked against.
+ */
+declare const OPERATORS: readonly ["equals", "notEquals", "contains", "notContains", "startsWith", "endsWith", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "exists", "notExists", "isEmpty", "isNotEmpty"];
+type Operator = (typeof OPERATORS)[number];
+/** The four that read whether a value is there rather than what it is. */
+declare const VALUELESS_OPERATORS: readonly Operator[];
+declare function isOperator(value: unknown): value is Operator;
+/** Whether an operator reads a second value at all, or only the first. */
+declare function takesValue(op: Operator): boolean;
+/**
+ * What an operator means.
+ *
+ * Equality is deliberately lenient across the string/number line: a `select`
+ * carries `1` where a text box carries `'1'`, and an author means one thing by
+ * both. A second implementation has to reproduce that — and has to be careful
+ * with booleans, whose default stringification differs between languages.
+ */
+declare function evaluate(left: unknown, op: Operator, right: unknown): boolean;
+
 type LocalizedString = string | Record<string, string>;
 type DataType = 'any' | 'object' | 'array' | 'string' | 'number' | 'boolean';
 type OutputKind = 'default' | 'branch' | 'error';
 type NodeCategory = 'trigger' | 'action' | 'transform' | 'control' | 'io';
-type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'state-ref' | 'dynamic-schema';
 /**
  * Semantic category of an image, driving how the registry/CDN organises and
  * displays it.
@@ -63,6 +91,26 @@ interface IConfigValidation {
     minLength?: number;
     maxLength?: number;
 }
+/**
+ * A condition on another setting's value, deciding whether this one applies.
+ *
+ * One condition, one key, one operator — `showIf: { key: 'source', op:
+ * 'equals', value: 'field' }` reads as the sentence a node would otherwise
+ * write under the field. The driving key MUST be a literal (it may not set
+ * `expressionAllowed`), because applicability has to be decidable while the
+ * author is typing; the same limit `dependsOn` carries, for the same reason.
+ */
+interface IShowIfCondition {
+    /** The `key` of another config field on the same node. */
+    key: string;
+    /** How to compare it — the shared comparison vocabulary, see `OPERATORS`. */
+    op: Operator;
+    /**
+     * What to compare it to. Left out by the four operators that read presence
+     * rather than content (`exists`, `notExists`, `isEmpty`, `isNotEmpty`).
+     */
+    value?: string | number | boolean;
+}
 interface IConfigFieldBase {
     key: string;
     label: LocalizedString;
@@ -92,6 +140,20 @@ interface IConfigFieldBase {
      * `expressionAllowed`), so its value is known at author time.
      */
     dependsOn?: string[];
+    /**
+     * When this field applies at all. The editor draws it only while the
+     * condition holds, so a node says once in its manifest what it would
+     * otherwise have to explain in prose under every affected field.
+     *
+     * Not to be confused with `dependsOn`, which sits beside it and does a
+     * different thing: `dependsOn` re-*resolves* a dynamic field's options when
+     * another field changes, and never decides whether the field is drawn.
+     *
+     * Left unset, the field always applies — so this is additive: a node that
+     * says nothing behaves as it always did, and so does an editor that does not
+     * know the key.
+     */
+    showIf?: IShowIfCondition;
     /**
      * Only meaningful when `type === 'credentials-ref'`: the namespaced slug(s) of
      * the credential type(s) this field accepts (e.g. `revenexx:smtp`). The editor
@@ -101,6 +163,19 @@ interface IConfigFieldBase {
      * a node that works with both an OAuth and an API-token credential).
      */
     credentialType?: string | string[];
+    /**
+     * Only meaningful when `type === 'state-ref'`: which kind of state namespace
+     * this field accepts (PO-374). The editor lists the workflow's declared
+     * namespaces of that role — and lets the author declare a new one without
+     * leaving the node — and the blob stores the chosen NAME.
+     *
+     * Declare the field rather than hardcoding a namespace name in `execute`: a
+     * literal is a contract nothing checks, and the mismatch surfaces as a 403 in
+     * the first production run rather than as an empty picker while authoring. It
+     * also narrows what the node may reach — a namespace is reachable only from
+     * the node whose config names it.
+     */
+    stateRole?: 'mapping' | 'cursor' | 'dedupe' | 'digest';
 }
 interface IConfigField extends IConfigFieldBase {
     properties?: IConfigFieldBase[];
@@ -122,6 +197,14 @@ interface INodeDescription {
     /** Associated images (screenshots, logos, banners) shipped with the package. */
     images?: IImage[];
     inputs: Record<string, IInputPort>;
+    /**
+     * Output ports the workflow editor wires to downstream nodes. An empty array
+     * marks a **terminal node**: the path ends here and no edge may leave it —
+     * the mirror image of `inputs: {}` on a trigger. `StopAndErrorNode` is the
+     * canonical case; it always throws, so there is no success path to wire, and
+     * a port that can never fire would leave a dead handle on the canvas. The
+     * key stays required so terminality is declared, not forgotten.
+     */
     outputs: IOutputPort[];
     config?: IConfigField[];
 }
@@ -145,6 +228,101 @@ interface INodeContext {
     credentials: {
         get(credentialsId: string): Promise<Record<string, unknown>>;
     };
+    /**
+     * The tenant state store: what this workflow already knows from earlier runs
+     * (PO-374). Every call names a namespace the workflow declared in its
+     * `state[]` block; anything else is refused by the engine, so a node cannot
+     * reach state its workflow did not ask for.
+     */
+    state: INodeState;
+}
+/**
+ * The four things a workflow can remember between runs, and the reason each is
+ * its own operation rather than a generic get/set: the role decides *when* a
+ * write becomes visible, and that decision is the engine's to make, not the
+ * node author's.
+ *
+ * The four roles are named **mapping**, **cursor**, **dedupe** and **digest** —
+ * those are the values a `state-ref` field's `stateRole` takes. `claim` below is
+ * the *operation* on a dedupe namespace, not a role of its own.
+ *
+ * - **mapping** and **dedupe** take effect immediately. A correlation discarded
+ *   because the run failed afterwards is how the next run creates a duplicate
+ *   in the target system; a claim invisible to other runs protects against
+ *   nothing.
+ * - **cursor** and **digest** are staged and adopted only when the run
+ *   completes. A watermark that advances on a failed run leaves exactly the gap
+ *   it exists to prevent, and a digest may only count once the write it
+ *   describes actually went through.
+ *
+ * At author time — the editor's "test this node" button — the store is
+ * **read-only**: a rehearsal must not leave correlations behind that a later
+ * production run would treat as truth. The write calls reject there.
+ */
+interface INodeState {
+    /** Correlate an id on each side of an integration (PIM article ↔ ERP number). */
+    mapping: {
+        /**
+         * The partner id of a correlation, or `null` when it is unknown — which is
+         * the usual way to decide between creating and updating in the target
+         * system.
+         *
+         * `side` says which side of the pair `key` is on, not which side to return:
+         * the default `'left'` matches `key` against the left id and answers with
+         * the right one, and `'right'` does the reverse. It never searches both, so
+         * a lookup on the wrong side answers `null` rather than falling back — and
+         * `null` on the create path is what makes the target record a second time.
+         */
+        get(namespace: string, key: string, side?: 'left' | 'right'): Promise<string | null>;
+        /**
+         * Record a correlation. Takes effect immediately, and re-pointing one side
+         * of an existing pair is refused: an id correlated two ways is always a bug,
+         * and no later sync can untangle it.
+         */
+        put(namespace: string, left: string, right: string, metadata?: Record<string, unknown>): Promise<void>;
+    };
+    /** How far an incremental sync has read. */
+    cursor: {
+        /**
+         * The committed watermark — an arbitrary JSON value such as
+         * `{ updatedAfter }` or a provider page token — or `undefined` when the
+         * sync has never run. A value staged by *this* run is not visible yet.
+         */
+        get(namespace: string, partitionKey?: string): Promise<unknown>;
+        /**
+         * Stage a watermark. Adopted only if the run completes, so a failed run
+         * leaves the previous value in place and the next run picks the gap up.
+         * `partitionKey` separates e.g. one shop or company code from another.
+         */
+        set(namespace: string, value: unknown, partitionKey?: string): Promise<void>;
+    };
+    /**
+     * Claim a key for the duration of its TTL. `true` means this caller got it;
+     * `false` means the key is held and this delivery is a duplicate — the normal
+     * answer under at-least-once delivery, and a value to branch on rather than an
+     * error.
+     *
+     * **A claim outlives the attempt that made it.** The holder is not identified:
+     * a claim is taken over only once it has expired, so a retry of the very
+     * attempt that claimed the key — after a transient failure that happened
+     * *after* the claim — is also told `false`. Treating that as a duplicate drops
+     * the delivery for the rest of the TTL, which makes `ttlSeconds` the retry
+     * window as much as the duplicate-suppression window. Choose it against both,
+     * and do not claim earlier in the node than necessary.
+     *
+     * `ttlSeconds` defaults to 604800 (seven days) and is accepted between 1 and
+     * 31536000.
+     */
+    claim(namespace: string, key: string, opts?: {
+        ttlSeconds?: number;
+    }): Promise<boolean>;
+    /** Skip expensive writes for entities that have not changed. */
+    digest: {
+        /** Whether the entity still carries this hash — i.e. the write can be skipped. */
+        unchanged(namespace: string, entityKey: string, digest: string): Promise<boolean>;
+        /** Stage a hash; adopted only if the run completes. Call it *after* the write. */
+        set(namespace: string, entityKey: string, digest: string): Promise<void>;
+    };
 }
 interface INodeResult {
     outputs: Record<string, unknown>;
@@ -412,6 +590,22 @@ interface ITemplateDescription {
  */
 declare function normalizeLocalized(value: LocalizedString | undefined | null, fallbackLang?: string): string | undefined;
 
+/**
+ * Whether a setting applies, given what the author has filled in so far.
+ *
+ * A setting with no condition always applies — which is what makes `showIf`
+ * additive: a node that says nothing gets the behaviour it has today, and an
+ * editor that does not know the key draws every field as before.
+ *
+ * The value the condition reads is taken from the config as it stands mid-edit,
+ * so it is routinely `undefined`: the moment a node is dropped on the canvas
+ * nothing is filled in. That is why `equals` against a missing value is `false`
+ * rather than an error — the setting does not apply *yet*.
+ */
+declare function settingApplies(field: {
+    showIf?: IShowIfCondition;
+}, config: Record<string, unknown>): boolean;
+
 /**
  * Reduce an `IConfigField.credentialType` (a single slug or an array of slugs)
  * to a normalized, deduplicated `string[]`.
@@ -720,7 +914,25 @@ declare abstract class BaseCredential implements ICredential {
     abstract readonly description: ICredentialDescription;
     abstract resolve(ctx: ICredentialContext, config: Config, durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
-    /** POST `application/x-www-form-urlencoded` and parse a JSON token response. */
+    /**
+     * POST `application/x-www-form-urlencoded` and parse a JSON token response.
+     *
+     * Goes through {@link safeFetch}, not a raw `fetch` (PO-185). The token
+     * endpoint is not a constant: `tokenUrl(config)` derives it from credential
+     * config, i.e. from a value someone types into a credential form. A raw fetch
+     * would happily POST the client secret at `http://169.254.169.254/…` or any
+     * other internal address, which is precisely what `assertPublicUrl` exists to
+     * prevent. Every OAuth token exchange in this file — client-credentials,
+     * auth-code, refresh — funnels through here, so this is the one call site that
+     * has to hold.
+     *
+     * Two behaviours safeFetch adds, both wanted here: a request budget
+     * (`DEFAULT_TIMEOUT_MS`) on top of `ctx.signal`, and manual redirect handling
+     * that re-checks each hop and drops `Authorization` across an origin boundary.
+     * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
+     * per the redirect rules, not a quirk of ours. Real token endpoints do not
+     * redirect; one that does was never going to complete the exchange anyway.
+     */
     protected postForm(ctx: ICredentialContext, url: string, form: Record<string, string | undefined>, headers?: Record<string, string>): Promise<OAuthTokenResponse>;
 }
 /**
@@ -796,4 +1008,4 @@ declare abstract class OAuth2AuthCodeCredential extends BaseCredential implement
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
 }
 
-export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, withRetry };

package/dist/index.d.ts

@@ -1,8 +1,36 @@
+/**
+ * The comparison vocabulary, in one place because it is read in three:
+ * a node that compares two values (a condition, a filter), a settings condition
+ * saying when a field applies (`IConfigField.showIf`), and the editor drawing
+ * that field. An author who has met these words in one of the three must not
+ * have to learn a second set for the others.
+ *
+ * The names are the vocabulary; what each one *means* is {@link evaluate}, and
+ * the answer table in `operators.test.ts` is what a second implementation of it
+ * — the editor, the platform's workflow validator — is checked against.
+ */
+declare const OPERATORS: readonly ["equals", "notEquals", "contains", "notContains", "startsWith", "endsWith", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "exists", "notExists", "isEmpty", "isNotEmpty"];
+type Operator = (typeof OPERATORS)[number];
+/** The four that read whether a value is there rather than what it is. */
+declare const VALUELESS_OPERATORS: readonly Operator[];
+declare function isOperator(value: unknown): value is Operator;
+/** Whether an operator reads a second value at all, or only the first. */
+declare function takesValue(op: Operator): boolean;
+/**
+ * What an operator means.
+ *
+ * Equality is deliberately lenient across the string/number line: a `select`
+ * carries `1` where a text box carries `'1'`, and an author means one thing by
+ * both. A second implementation has to reproduce that — and has to be careful
+ * with booleans, whose default stringification differs between languages.
+ */
+declare function evaluate(left: unknown, op: Operator, right: unknown): boolean;
+
 type LocalizedString = string | Record<string, string>;
 type DataType = 'any' | 'object' | 'array' | 'string' | 'number' | 'boolean';
 type OutputKind = 'default' | 'branch' | 'error';
 type NodeCategory = 'trigger' | 'action' | 'transform' | 'control' | 'io';
-type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'state-ref' | 'dynamic-schema';
 /**
  * Semantic category of an image, driving how the registry/CDN organises and
  * displays it.
@@ -63,6 +91,26 @@ interface IConfigValidation {
     minLength?: number;
     maxLength?: number;
 }
+/**
+ * A condition on another setting's value, deciding whether this one applies.
+ *
+ * One condition, one key, one operator — `showIf: { key: 'source', op:
+ * 'equals', value: 'field' }` reads as the sentence a node would otherwise
+ * write under the field. The driving key MUST be a literal (it may not set
+ * `expressionAllowed`), because applicability has to be decidable while the
+ * author is typing; the same limit `dependsOn` carries, for the same reason.
+ */
+interface IShowIfCondition {
+    /** The `key` of another config field on the same node. */
+    key: string;
+    /** How to compare it — the shared comparison vocabulary, see `OPERATORS`. */
+    op: Operator;
+    /**
+     * What to compare it to. Left out by the four operators that read presence
+     * rather than content (`exists`, `notExists`, `isEmpty`, `isNotEmpty`).
+     */
+    value?: string | number | boolean;
+}
 interface IConfigFieldBase {
     key: string;
     label: LocalizedString;
@@ -92,6 +140,20 @@ interface IConfigFieldBase {
      * `expressionAllowed`), so its value is known at author time.
      */
     dependsOn?: string[];
+    /**
+     * When this field applies at all. The editor draws it only while the
+     * condition holds, so a node says once in its manifest what it would
+     * otherwise have to explain in prose under every affected field.
+     *
+     * Not to be confused with `dependsOn`, which sits beside it and does a
+     * different thing: `dependsOn` re-*resolves* a dynamic field's options when
+     * another field changes, and never decides whether the field is drawn.
+     *
+     * Left unset, the field always applies — so this is additive: a node that
+     * says nothing behaves as it always did, and so does an editor that does not
+     * know the key.
+     */
+    showIf?: IShowIfCondition;
     /**
      * Only meaningful when `type === 'credentials-ref'`: the namespaced slug(s) of
      * the credential type(s) this field accepts (e.g. `revenexx:smtp`). The editor
@@ -101,6 +163,19 @@ interface IConfigFieldBase {
      * a node that works with both an OAuth and an API-token credential).
      */
     credentialType?: string | string[];
+    /**
+     * Only meaningful when `type === 'state-ref'`: which kind of state namespace
+     * this field accepts (PO-374). The editor lists the workflow's declared
+     * namespaces of that role — and lets the author declare a new one without
+     * leaving the node — and the blob stores the chosen NAME.
+     *
+     * Declare the field rather than hardcoding a namespace name in `execute`: a
+     * literal is a contract nothing checks, and the mismatch surfaces as a 403 in
+     * the first production run rather than as an empty picker while authoring. It
+     * also narrows what the node may reach — a namespace is reachable only from
+     * the node whose config names it.
+     */
+    stateRole?: 'mapping' | 'cursor' | 'dedupe' | 'digest';
 }
 interface IConfigField extends IConfigFieldBase {
     properties?: IConfigFieldBase[];
@@ -122,6 +197,14 @@ interface INodeDescription {
     /** Associated images (screenshots, logos, banners) shipped with the package. */
     images?: IImage[];
     inputs: Record<string, IInputPort>;
+    /**
+     * Output ports the workflow editor wires to downstream nodes. An empty array
+     * marks a **terminal node**: the path ends here and no edge may leave it —
+     * the mirror image of `inputs: {}` on a trigger. `StopAndErrorNode` is the
+     * canonical case; it always throws, so there is no success path to wire, and
+     * a port that can never fire would leave a dead handle on the canvas. The
+     * key stays required so terminality is declared, not forgotten.
+     */
     outputs: IOutputPort[];
     config?: IConfigField[];
 }
@@ -145,6 +228,101 @@ interface INodeContext {
     credentials: {
         get(credentialsId: string): Promise<Record<string, unknown>>;
     };
+    /**
+     * The tenant state store: what this workflow already knows from earlier runs
+     * (PO-374). Every call names a namespace the workflow declared in its
+     * `state[]` block; anything else is refused by the engine, so a node cannot
+     * reach state its workflow did not ask for.
+     */
+    state: INodeState;
+}
+/**
+ * The four things a workflow can remember between runs, and the reason each is
+ * its own operation rather than a generic get/set: the role decides *when* a
+ * write becomes visible, and that decision is the engine's to make, not the
+ * node author's.
+ *
+ * The four roles are named **mapping**, **cursor**, **dedupe** and **digest** —
+ * those are the values a `state-ref` field's `stateRole` takes. `claim` below is
+ * the *operation* on a dedupe namespace, not a role of its own.
+ *
+ * - **mapping** and **dedupe** take effect immediately. A correlation discarded
+ *   because the run failed afterwards is how the next run creates a duplicate
+ *   in the target system; a claim invisible to other runs protects against
+ *   nothing.
+ * - **cursor** and **digest** are staged and adopted only when the run
+ *   completes. A watermark that advances on a failed run leaves exactly the gap
+ *   it exists to prevent, and a digest may only count once the write it
+ *   describes actually went through.
+ *
+ * At author time — the editor's "test this node" button — the store is
+ * **read-only**: a rehearsal must not leave correlations behind that a later
+ * production run would treat as truth. The write calls reject there.
+ */
+interface INodeState {
+    /** Correlate an id on each side of an integration (PIM article ↔ ERP number). */
+    mapping: {
+        /**
+         * The partner id of a correlation, or `null` when it is unknown — which is
+         * the usual way to decide between creating and updating in the target
+         * system.
+         *
+         * `side` says which side of the pair `key` is on, not which side to return:
+         * the default `'left'` matches `key` against the left id and answers with
+         * the right one, and `'right'` does the reverse. It never searches both, so
+         * a lookup on the wrong side answers `null` rather than falling back — and
+         * `null` on the create path is what makes the target record a second time.
+         */
+        get(namespace: string, key: string, side?: 'left' | 'right'): Promise<string | null>;
+        /**
+         * Record a correlation. Takes effect immediately, and re-pointing one side
+         * of an existing pair is refused: an id correlated two ways is always a bug,
+         * and no later sync can untangle it.
+         */
+        put(namespace: string, left: string, right: string, metadata?: Record<string, unknown>): Promise<void>;
+    };
+    /** How far an incremental sync has read. */
+    cursor: {
+        /**
+         * The committed watermark — an arbitrary JSON value such as
+         * `{ updatedAfter }` or a provider page token — or `undefined` when the
+         * sync has never run. A value staged by *this* run is not visible yet.
+         */
+        get(namespace: string, partitionKey?: string): Promise<unknown>;
+        /**
+         * Stage a watermark. Adopted only if the run completes, so a failed run
+         * leaves the previous value in place and the next run picks the gap up.
+         * `partitionKey` separates e.g. one shop or company code from another.
+         */
+        set(namespace: string, value: unknown, partitionKey?: string): Promise<void>;
+    };
+    /**
+     * Claim a key for the duration of its TTL. `true` means this caller got it;
+     * `false` means the key is held and this delivery is a duplicate — the normal
+     * answer under at-least-once delivery, and a value to branch on rather than an
+     * error.
+     *
+     * **A claim outlives the attempt that made it.** The holder is not identified:
+     * a claim is taken over only once it has expired, so a retry of the very
+     * attempt that claimed the key — after a transient failure that happened
+     * *after* the claim — is also told `false`. Treating that as a duplicate drops
+     * the delivery for the rest of the TTL, which makes `ttlSeconds` the retry
+     * window as much as the duplicate-suppression window. Choose it against both,
+     * and do not claim earlier in the node than necessary.
+     *
+     * `ttlSeconds` defaults to 604800 (seven days) and is accepted between 1 and
+     * 31536000.
+     */
+    claim(namespace: string, key: string, opts?: {
+        ttlSeconds?: number;
+    }): Promise<boolean>;
+    /** Skip expensive writes for entities that have not changed. */
+    digest: {
+        /** Whether the entity still carries this hash — i.e. the write can be skipped. */
+        unchanged(namespace: string, entityKey: string, digest: string): Promise<boolean>;
+        /** Stage a hash; adopted only if the run completes. Call it *after* the write. */
+        set(namespace: string, entityKey: string, digest: string): Promise<void>;
+    };
 }
 interface INodeResult {
     outputs: Record<string, unknown>;
@@ -412,6 +590,22 @@ interface ITemplateDescription {
  */
 declare function normalizeLocalized(value: LocalizedString | undefined | null, fallbackLang?: string): string | undefined;
 
+/**
+ * Whether a setting applies, given what the author has filled in so far.
+ *
+ * A setting with no condition always applies — which is what makes `showIf`
+ * additive: a node that says nothing gets the behaviour it has today, and an
+ * editor that does not know the key draws every field as before.
+ *
+ * The value the condition reads is taken from the config as it stands mid-edit,
+ * so it is routinely `undefined`: the moment a node is dropped on the canvas
+ * nothing is filled in. That is why `equals` against a missing value is `false`
+ * rather than an error — the setting does not apply *yet*.
+ */
+declare function settingApplies(field: {
+    showIf?: IShowIfCondition;
+}, config: Record<string, unknown>): boolean;
+
 /**
  * Reduce an `IConfigField.credentialType` (a single slug or an array of slugs)
  * to a normalized, deduplicated `string[]`.
@@ -720,7 +914,25 @@ declare abstract class BaseCredential implements ICredential {
     abstract readonly description: ICredentialDescription;
     abstract resolve(ctx: ICredentialContext, config: Config, durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
-    /** POST `application/x-www-form-urlencoded` and parse a JSON token response. */
+    /**
+     * POST `application/x-www-form-urlencoded` and parse a JSON token response.
+     *
+     * Goes through {@link safeFetch}, not a raw `fetch` (PO-185). The token
+     * endpoint is not a constant: `tokenUrl(config)` derives it from credential
+     * config, i.e. from a value someone types into a credential form. A raw fetch
+     * would happily POST the client secret at `http://169.254.169.254/…` or any
+     * other internal address, which is precisely what `assertPublicUrl` exists to
+     * prevent. Every OAuth token exchange in this file — client-credentials,
+     * auth-code, refresh — funnels through here, so this is the one call site that
+     * has to hold.
+     *
+     * Two behaviours safeFetch adds, both wanted here: a request budget
+     * (`DEFAULT_TIMEOUT_MS`) on top of `ctx.signal`, and manual redirect handling
+     * that re-checks each hop and drops `Authorization` across an origin boundary.
+     * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
+     * per the redirect rules, not a quirk of ours. Real token endpoints do not
+     * redirect; one that does was never going to complete the exchange anyway.
+     */
     protected postForm(ctx: ICredentialContext, url: string, form: Record<string, string | undefined>, headers?: Record<string, string>): Promise<OAuthTokenResponse>;
 }
 /**
@@ -796,4 +1008,4 @@ declare abstract class OAuth2AuthCodeCredential extends BaseCredential implement
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
 }
 
-export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, withRetry };

package/dist/index.js

@@ -37,6 +37,75 @@ function normalizeLocalized(value, fallbackLang = "en") {
   return void 0;
 }
 
+// src/operators.ts
+var OPERATORS = [
+  "equals",
+  "notEquals",
+  "contains",
+  "notContains",
+  "startsWith",
+  "endsWith",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "exists",
+  "notExists",
+  "isEmpty",
+  "isNotEmpty"
+];
+var VALUELESS_OPERATORS = ["exists", "notExists", "isEmpty", "isNotEmpty"];
+function isOperator(value) {
+  return typeof value === "string" && OPERATORS.includes(value);
+}
+function takesValue(op) {
+  return !VALUELESS_OPERATORS.includes(op);
+}
+function evaluate(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 !evaluate(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 _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+
+// src/conditions.ts
+function settingApplies(field, config) {
+  const condition = field.showIf;
+  if (!condition) return true;
+  return evaluate(config[condition.key], condition.op, condition.value);
+}
+
 // src/credentialType.ts
 function normalizeCredentialType(value) {
   const raw = value === void 0 ? [] : Array.isArray(value) ? value : [value];
@@ -446,7 +515,7 @@ function abortReason(signal) {
 }
 function backoffDelay(attempt, policy) {
   const exponent = Math.max(0, attempt - 1);
-  const raw = policy.baseDelayMs * Math.pow(policy.factor, exponent);
+  const raw = policy.baseDelayMs * policy.factor ** exponent;
   const cap = Math.min(policy.maxDelayMs, raw);
   return policy.jitter ? Math.random() * cap : cap;
 }
@@ -521,7 +590,25 @@ var BaseCredential = class {
     }
     return { ok: true };
   }
-  /** POST `application/x-www-form-urlencoded` and parse a JSON token response. */
+  /**
+   * POST `application/x-www-form-urlencoded` and parse a JSON token response.
+   *
+   * Goes through {@link safeFetch}, not a raw `fetch` (PO-185). The token
+   * endpoint is not a constant: `tokenUrl(config)` derives it from credential
+   * config, i.e. from a value someone types into a credential form. A raw fetch
+   * would happily POST the client secret at `http://169.254.169.254/…` or any
+   * other internal address, which is precisely what `assertPublicUrl` exists to
+   * prevent. Every OAuth token exchange in this file — client-credentials,
+   * auth-code, refresh — funnels through here, so this is the one call site that
+   * has to hold.
+   *
+   * Two behaviours safeFetch adds, both wanted here: a request budget
+   * (`DEFAULT_TIMEOUT_MS`) on top of `ctx.signal`, and manual redirect handling
+   * that re-checks each hop and drops `Authorization` across an origin boundary.
+   * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
+   * per the redirect rules, not a quirk of ours. Real token endpoints do not
+   * redirect; one that does was never going to complete the exchange anyway.
+   */
   async postForm(ctx, url, form, headers = {}) {
     const body = new URLSearchParams();
     for (const [key, value] of Object.entries(form)) {
@@ -529,7 +616,7 @@ var BaseCredential = class {
         body.set(key, value);
       }
     }
-    const res = await fetch(url, {
+    const res = await safeFetch(url, {
       method: "POST",
       signal: ctx.signal,
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", ...headers },
@@ -713,12 +800,15 @@ export {
   NodeError,
   OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential,
+  OPERATORS,
   RetryableError,
   SimpleValueCredential,
+  VALUELESS_OPERATORS,
   assertPublicUrl,
   backoffDelay,
   buildManifest,
   clampResponseBytes,
+  evaluate,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
@@ -726,6 +816,7 @@ export {
   isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
+  isOperator,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
@@ -735,7 +826,9 @@ export {
   readText,
   retryConfigFields,
   safeFetch,
+  settingApplies,
   sleepWithSignal,
+  takesValue,
   timeoutConfigField,
   withRetry
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "0.18.0",
+  "version": "1.0.0",
   "description": "TypeScript interfaces and utilities for Revenexx integration nodes",
   "license": "MIT",
   "author": "revenexx GmbH",
@@ -45,6 +45,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "spec:check": "node scripts/spec-check.mjs",
+    "lint": "biome check src",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "release": "changeset publish"
@@ -53,6 +55,7 @@
     "node": ">=20.3.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
     "@changesets/cli": "^2.31.0",
     "@types/node": "^24.0.0",
     "tsup": "^8.0.0",