Building the Resolve.ai Clocked EDI Engine

Source Code

Pre-requisite

New to EDI (Electronic Data Interchange), please take a look into the following YouTube Video

What is Electronic Data Interchange (EDI) and How Does It Work? A Comprehensive Overview

New to Resolve.ai Clocked? Please take a look into the following documentation.

Introduction

Clocked EDI Engine is a modern, secure X12 EDI transaction processing engine built for enterprise-grade electronic data interchange. It's a runnable Node.js service for ANSI X12 transaction sets below

850 (Purchase Order)
810 (Invoice)
856 (Advance Ship Notice)
820 (Payment Order/Remittance Advice).

It parses the X12 structure, maps common segments into normalized JSON, runs Clocked PII Protection and Injection Guard before sending content to Clocked Extract and Decide, and exposes REST/n8n-compatible webhooks.

Working with ANSI X12 EDI has traditionally required specialized knowledge - delimiter parsing, segment dictionaries, control numbers, trading partner companion guides, and legacy translators that feel like they belong in the 1990s. clocked-edi-engine removes that barrier. It is a modern, open-source Node.js service (Express, ESM, Node 20+) that sits between your trading partners and your ERP, turning decades-old X12 transaction sets into clean, secure, JSON-powered workflows without requiring EDI expertise.

The engine processes raw X12 through a single pipeline:

Parse - Auto-detects ISA delimiters, segments the text, and preserves raw segment data with 1-based element positions.
Validate - Checks required ISA/GS/ST/SE envelopes, ST/SE control numbers, segment counts, and implementation-specific constraints.
Secure - Sends content through Clocked PII Protection and Injection Guard before any AI model sees it. PII is redacted first; injection-flagged content is blocked with a 422 response.
Extract + Decide - Runs Clocked Extract and Decide in parallel on the protected text to surface structured fields and assess processing readiness.
Serve - Returns normalized JSON over REST (/api/edi/process) or an n8n-compatible webhook (/webhooks/edi), with idempotency keys, bounded retries, and fail-closed security behavior.

Best of all, it ships with a mock mode (CLOCKED_MODE=mock), so you can develop and test the parser and API locally without a Clocked API key or any EDI experience. Switch to live mode when you are ready to process real EDI with sensitive data.

Architecture Diagram

Features

Node.js 20+, ES modules; Express REST API.
X12 delimiter detection for ISA envelopes and basic delimiter fallback.
Raw segment preservation, ST/SE control number and segment-count checks.
Transaction adapters for 850, 810, 856 and 820.
856 HL parent-child hierarchy preservation.
Party loops (N1/N2/N3/N4/PER), references (REF), dates (DTM), line items and remittance mappings.
Clocked sequence: PII Protection - Injection Guard - Extract + Decide.
Idempotency-Key support and bounded retry for retryable Clocked failures (network errors, 429, >=500; 409 Conflict is non-retryable).
Fail-closed behavior for live security API failures (configurable via CLOCKED_FAIL_CLOSED).
Mock mode for local parser/API development without Clocked credentials.
File upload and JSON webhook endpoints for n8n.
Segment validation: validateRequiredSegments and validateImplementationGuide check for required envelopes, control numbers, and implementation-specific constraints.

Quick start

cp .env.example .env # creates .env if it exists; otherwise create .env manually see Config Clocked section below npm install npm test npm run start

The default is CLOCKED_MODE=mock, so no Clocked API key is needed for local testing. Health check:

curl http://localhost:8080/health

Parse one of the supplied samples without calling Clocked:

npm run parse:sample -- examples/sample-810.edi

Configure Clocked

Edit .env:

CLOCKED_MODE=live CLOCKED_API_BASE_URL=https://clocked.rezolve.ai CLOCKED_API_KEY=YOUR_CLOCKED_API_KEY CLOCKED_EXTRACT_PATH=/clocked/extract CLOCKED_DECIDE_PATH=/clocked/decide CLOCKED_PII_PATH=/clocked/pii CLOCKED_INJECTION_PATH=/clocked/injection CLOCKED_FAIL_CLOSED=true

Verify each path and payload contract with your Clocked API documentation. If your PII or Injection endpoint expects a different body (for example content, input, or additional policy options), update the corresponding call in src/services/pipeline.js. If the API returns its protected text or injection flag under a different property, update extractSafeText() or injectionFlagged() in src/clocked/client.js.

Clocked request sequence

pii: { "text": "<raw EDI>" } - PII Protection.
injection: { "text": "<PII-protected EDI>" } - Injection Guard.
extract: { "text": "<protected EDI>", "instructions": "...", "fields": { ... } } - Extraction of structured data.
decide: { "state": "<normalized transaction + structural validation>", "instructions": "...", "fields": { ... }, "questions": { ... } } - Typed decisions and probabilities behind them.

Every call includes an Idempotency-Key header. When retrying the same inbound request, send the same Idempotency-Key value. Clocked API retry behavior: network errors, 429, and status >= 500 are retried (up to CLOCKED_RETRIES attempts, default 2); 409 Conflict is not retryable.

Security note: In live mode, PII and Injection failures stop downstream processing by default (governed by CLOCKED_FAIL_CLOSED). The engine blocks when the response contains a recognized boolean flag (flagged, is_injection, injection_detected, or blocked). Confirm your tenant's response shape and extend the mapping in src/clocked/client.js (injectionFlagged()) if needed. Do not silently disable fail-closed behavior in production without a security review.

Clocked Protect Playground

The Clocked Protect Playground lets you interactively test PII Protection and Injection Guard on raw EDI content before integrating it into the engine. Use it to experiment with redaction policies, injection detection thresholds, and response shapes without writing code.

Demo 1 - PII Protection

The first demo shows raw X12 EDI (an 850 Purchase Order) being submitted to the PII Protection endpoint. Sensitive fields such as names, addresses, and other personally identifiable information are detected and redacted in the protected output.

Demo 2 - Injection Guard

The second demo shows the same EDI content being evaluated by the Injection Guard. The playground analyzes the text for prompt injection, jailbreak attempts, and other adversarial patterns, returning a verdict, severity score, and category probabilities.

How it maps to the engine

The engine mirrors these two playground capabilities in its pipeline:

Playground capability	Engine pipeline stage	Source
PII Protection	`pii` - redacts/protects sensitive data	`src/clocked/client.js` (`extractSafeText()`)
Injection Guard	`injection` - blocks malicious content	`src/clocked/client.js` (`injectionFlagged()`)

Use the playground to confirm your tenant's response schema (e.g., which field holds the protected text, which boolean indicates injection risk), then update extractSafeText() and injectionFlagged() in src/clocked/client.js accordingly before running in live mode.

API

`POST /api/edi/process`

JSON body:

{ "edi": "ST*810*0001~\\nBIG*20261031*INV-10025**PO-50021~\\n..." }

Or upload a file as multipart form-data with field name file:

curl -X POST http://localhost:8080/api/edi/process \\ -H 'Idempotency-Key: edi-inbound-000123' \\ -F 'file=@examples/sample-810.edi'

Example with a sample 850 Purchase Order file:

curl --location 'http://localhost:8080/api/edi/process' \ --header 'Idempotency-Key: 8a2c1a7f-d9a4-4599-9097-d06c174cb92b' \ --form 'file=@"sample-850.edi"'

Response:

{ "requestId": "41889602-39ff-4cf8-a3ec-85aee7c94d9f", "transactionType": "810", "structural": { "valid": true, "issues": [], "envelope": { "interchangeControlNumber": "000000001", "senderId": "SENDER ", "receiverId": "RECEIVER ", "functionalGroupCode": "IN", "version": "004010", "transactionCode": "810", "transactionControlNumber": "0001", "declaredSegmentCount": 9, "actualSegmentCount": 9 } }, "normalized": { "transactionType": "810", "documentType": "Invoice", "controlNumber": "0001", "invoice": { "number": "INV-10025", "date": "2026-10-31", "purchaseOrderNumber": "PO-50021", "releaseNumber": null, "changeOrderNumber": null }, "references": [], "dates": [], "parties": [ { "qualifier": "BT", "name": "ABC CORPORATION", "identificationQualifier": null, "identificationCode": null, "address": "123 MAIN STREET", "city": "DALLAS", "state": "TX", "postalCode": "75001", "country": null, "contacts": [ { "functionCode": "AP", "name": "JOHN SMITH", "communicationQualifier1": "EM", "communicationNumber1": "john@abc.com", "communicationQualifier2": null, "communicationNumber2": null } ] } ], "billTo": { "qualifier": "BT", "name": "ABC CORPORATION", "identificationQualifier": null, "identificationCode": null, "address": "123 MAIN STREET", "city": "DALLAS", "state": "TX", "postalCode": "75001", "country": null, "contacts": [ { "functionCode": "AP", "name": "JOHN SMITH", "communicationQualifier1": "EM", "communicationNumber1": "john@abc.com", "communicationQualifier2": null, "communicationNumber2": null } ] }, "remitTo": null, "vendor": null, "lineItems": [ { "lineNumber": "1", "quantity": "10", "unitOfMeasure": "EA", "unitPrice": "150.00", "productIds": [ { "qualifier": "VN", "value": "PROD-100" } ] } ], "totals": { "invoiceTotalRaw": "150000", "invoiceTotal": "1500.00" } }, "security": { "pii": { "model": "clocked-1.0", "entities": [ { "type": "address", "value": "123 MAIN STREET", "start": 236, "end": 251, "confidence": 1, "source": "model", "mentions": 1 }, { "type": "person", "value": "JOHN SMITH", "start": 282, "end": 292, "confidence": 1, "source": "model", "mentions": 1 }, { "type": "email", "value": "john@abc.com", "start": 296, "end": 308, "confidence": 1, "source": "model", "mentions": 1 } ], "counts": { "address": 1, "person": 1, "email": 1 }, "threshold": 0.5, "instructions_used": "default", "mentions": { "candidates": 0, "variants": 0, "reads": 0, "verified": 0, "occurrences": { "read": 0, "kept": 0 }, "rejected": {}, "spans": 0, "ms": 0 }, "checks": { "trimmed": 0, "split": 0, "rejected": {} }, "timing": { "read_ms": 161, "total_ms": 162 } }, "injection": { "model": "clocked-1.0", "injection": 0.0015795449709939957, "verdict": "benign", "threshold": 0.5, "source": "user", "instructions_used": "default", "category": "benign", "categories": { "benign": 0.9843004961596056, "instruction override": 0.0022073039800192735, "role-play or persona jailbreak": 0.001533872345768614, "system prompt or secret extraction": 0.0019157453221000259, "obfuscated or encoded payload": 0.006459213271208008, "tool misuse or data exfiltration": 0.0018455329224156191, "social engineering": 0.0017378359988828838 }, "severity": "none", "severity_expected": 1.011, "severities": { "none": 0.9956599763805926, "low": 0.0011607757555666704, "medium": 0.001044246809191259, "high": 0.0010818527818268694, "critical": 0.0010531482728226415 }, "evidence": [], "timing": { "read_ms": 33, "total_ms": 34 } }, "blocked": false, "blockedReason": null, "blockedAt": null }, "clocked": { "extract": { "model": "clocked-1.0", "fields": { "transaction_type": { "value": "810", "start": 163, "end": 166, "confidence": 0.9999999997988447, "p_verify": 0.9999999997988447, "normalized": { "value": "810", "source": "derived", "rule": "id_explicit_format", "confidence": 0.9999999997988447 } }, "control_number": { "value": "0001", "start": 95, "end": 99, "confidence": 0.9999999986474313, "p_verify": 0.9999999986474313, "normalized": { "value": "0001", "source": "derived", "rule": "id_explicit_format", "confidence": 0.9999999986474313 } }, "validation_issues": { "value": [], "items": [], "confidence": 1 }, "document_type": { "value": "810", "start": 163, "end": 166, "confidence": 0.9999999882467537, "p_verify": 0.9999999882467537 }, "parties": { "value": null, "confidence": 1 }, "line_items_or_remittance": { "value": "IT1*1*10*EA*150.00**VN*PROD-100", "start": 311, "end": 342, "confidence": 0.9999999982356944, "p_verify": 0.9999999982356944 }, "business_summary": { "value": null, "confidence": 1 }, "invoice_number": { "value": "INV-10025", "start": 187, "end": 196, "confidence": 0.9999999989181139, "p_verify": 0.9999999989181139, "normalized": { "value": "INV-10025", "source": "derived", "rule": "id_explicit_format", "confidence": 0.9999999989181139 } }, "purchase_order_reference": { "value": "PO-50021", "start": 198, "end": 206, "confidence": 0.9999999978618255, "p_verify"Source：https://dev.to/ranjancse/building-the-resolveai-clocked-edi-engine-3gnkMy favorites

PreviousWhy Better Financial Records Can Help Small Firms Unlock CapitalNextWhy Mobile Video Editors Are Transitioning to Desktop Setups

`Related posts`


Quiz: Positron IDE: A Hands-on Python Tutorial
In this quiz, you’ll test your understanding of Positron IDE . By working through this quiz, you’ll revisit how to inspe
0Real Python
Agent Answers Need Receipts
Originally published at Trida AI . "Where did nineteen days come from?" Picture a routine review. An agent has summarise
0dev.to
lf-dBFamk:Aymg’Ppc
Self-Hosted Bot Framework: A Systems Engineer’s Perspective Here's the brutal truth: For a tech solopreneur, every syste
0dev.to
Can an agent buy from you? A one-cent till, six refusals, and twelve cold agents
Most agent-payment demos stop at the happy path: an agent hits an endpoint, gets a 402 , signs a payment, gets a 200 , t
0dev.to
Ollama Local vs Cloud: Where Should Your Coding Agent Run?
A coding agent can read a repository, inspect errors, and propose a patch. Before enabling that workflow, there is a les
0dev.to
Google migrated 174,000 lines of Fortran to Rust in 59 minutes: the 11-minute baseline is the part to copy
Google's Antigravity team published a walkthrough on November 3 of an agent migrating the core of FVCOM, a coastal ocean
0dev.to