@mahdaad/automation-contract

Universal typed data contract for Oktuple automation nodes across PMN, Automation Engine, n8n Addons, and Frontend.

Features

• Standard Envelope (OktupleEnvelope<T>): Underscore-prefixed metadata fields (_v, _entityType, _outputKey, _context, _meta, _schema, _error) preventing payload collision.
• Backward Compatible: Automatically spreads legacy fields at root level (workspace_id, project_id, action_type, etc.) for seamless compatibility with older workflows.
• Entity Schemas: Pre-registered schemas for issue, comment, user, project, http_response.
• Type Compatibility Matrix: Robust isTypeCompatible() and isAssignable() methods for dynamic type checking.
• Path & Expression Utilities: buildVariableTree() for building UI variable pickers and generateExpression() for n8n expressions (={{ $('Node').item.json.data.field }}).
• Zero Runtime Dependencies: Works anywhere (Node.js, browser, Vite, n8n runners).

Installation

npm install @mahdaad/automation-contract
# or
pnpm add @mahdaad/automation-contract
# or
yarn add @mahdaad/automation-contract

Quick Start

1. Build an Envelope (Node/Addon Output)

import { buildEnvelope } from '@mahdaad/automation-contract';

const envelope = buildEnvelope({
  data: { id: 'iss_123', title: 'Fix Bug', type: 'task' },
  entityType: 'issue',
  outputKey: 'issue',
  context: {
    workspaceId: 'ws_abc',
    projectId: 'prj_xyz',
  },
  meta: {
    source: 'oktuple-nats-trigger',
    actionType: 'issue.created',
  },
});

console.log(envelope._v); // "1.0"
console.log(envelope.data.title); // "Fix Bug"
console.log(envelope.workspace_id); // "ws_abc" (legacy support)

2. Runtime Validation

import { isOktupleEnvelope, validateEnvelope } from '@mahdaad/automation-contract';

if (isOktupleEnvelope(payload)) {
  console.log('Valid envelope from:', payload._meta.source);
}

const result = validateEnvelope(payload);
if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

3. Generate n8n Expressions for Variable Picker

import { generateExpression, buildVariableTree, ISSUE_NODE_SCHEMA } from '@mahdaad/automation-contract';

// Build tree for UI variable picker
const tree = buildVariableTree(ISSUE_NODE_SCHEMA.fields);

// Generate standard n8n expression
const expr = generateExpression('Oktuple Trigger', 'data.id', 'n8n');
// => "={{ $('Oktuple Trigger').item.json.data.id }}"

// Generate inline template expression
const templateExpr = generateExpression('Oktuple Trigger', 'data.title', 'inline-template');
// => "{{ $('Oktuple Trigger').item.json.data.title }}"

4. Check Type Compatibility

import { isTypeCompatible } from '@mahdaad/automation-contract';

isTypeCompatible('id', 'string'); // true
isTypeCompatible('string', 'id'); // false
isTypeCompatible('number', 'string'); // true
isTypeCompatible('any', 'number'); // true

License

MIT © Oktuple Team