Unnbound EDI Client

A TypeScript EDI client with structured logging and distributed tracing capabilities, built for processing X12 EDI documents with comprehensive error handling and automatic span tracking.

Features

- X12 EDI Processing: Complete X12 document parsing, validation, and generation
- Structured Logging: Built-in integration with Unnbound Logger for comprehensive operation tracking
- Distributed Tracing: Automatic span creation for all EDI operations with detailed payload information
- Type Safety: Full TypeScript support with comprehensive type definitions
- Error Handling: Custom error types with detailed error codes and context

Installation

``bash
npm install unnbound-edi-sdk


or

pnpm add unnbound-edi-sdk

or

yarn add unnbound-edi-sdk
`

Environment Variables

$3

- UNNBOUND_EDI_API_KEY - Your API key for authentication

Quick Start

`typescript
import { UnnboundEdiClient } from 'unnbound-edi-sdk';
import { logger } from 'unnbound-logger-sdk';

// Set your API key
process.env.UNNBOUND_EDI_API_KEY = 'your-api-key';

const edi = new UnnboundEdiClient();

// Parse X12 document to JSON
const x12Interchanges = await edi.fromX12({
input: 'ISA00 00 12NOTP...',
});

// Validate X12 interchange
const validationResult = await edi.validateX12({
input: x12Interchanges[0],
});

// Convert JSON back to X12
const x12Document = await edi.toX12({
input: x12Interchanges[0],
});

// Generate acknowledgment
const acknowledgment = await edi.acknowledgeX12({
input: x12Interchanges[0],
});
`

API Reference

$3

`typescript
new UnnboundEdiClient();
`

Creates a new EDI client instance. Requires UNNBOUND_EDI_API_KEY environment variable to be set.

$3

#### fromX12(options: FromX12Options): Promise

Parses X12 EDI documents into JSON format.

`typescript
const x12Interchanges = await edi.fromX12({
input: 'ISA00 00 12NOTP...',
});
`

Parameters:

- options.input - The X12 document as a string or File object

Returns: Array of parsed X12 interchange objects

#### toX12(options: ToX12Options): Promise

Converts JSON X12 interchange objects back to X12 format.

`typescript
const x12Document = await edi.toX12({
input: x12InterchangeObject,
});
`

Parameters:

- options.input - The X12 interchange object to convert

Returns: X12 document as string

#### validateX12(options: ValidateX12Options): Promise

Validates X12 interchange objects against EDI standards.

`typescript
const validationResult = await edi.validateX12({
input: x12InterchangeObject,
});
`

Parameters:

- options.input - The X12 interchange object to validate

Returns: Validation result with operation details

#### acknowledgeX12(options: AcknolwedgeX12Options): Promise

Generates acknowledgment for X12 interchange objects.

`typescript
const acknowledgment = await edi.acknowledgeX12({
input: x12InterchangeObject,
});
`

Parameters:

- options.input - The X12 interchange object to acknowledge

Returns: Acknowledgment result with operation details

Error Handling

The EDI client provides custom error types for different operation failures:

$3

`typescript
import { UnnboundEdiClientError, isUnnboundEdiClientError } from 'unnbound-edi-sdk';

try {
await edi.fromX12({ input: invalidX12 });
} catch (error) {
if (isUnnboundEdiClientError(error)) {
console.error('EDI Error:', error.code, error.message);
// Handle specific EDI errors
}
}
`

$3

| Code | Description |
| ----------------------- | ------------------------------- |
| edi_read_error | Error parsing X12 document |
| edi_write_error | Error converting JSON to X12 |
| edi_validate_error | Error validating X12 document |
| edi_acknowledge_error | Error generating acknowledgment |
| edi_unknown_error | Unknown error occurred |

Type Definitions

$3

`typescript
interface FromX12Options {
input: unknown; // X12 document as string or File
}
`

$3

`typescript
interface ToX12Options {
input: X12Interchange; // X12 interchange object
}
`

$3

`typescript
interface ValidateX12Options {
input: X12Interchange; // X12 interchange object
}
`

$3

`typescript
interface AcknolwedgeX12Options {
input: X12Interchange; // X12 interchange object
}
`

$3

`typescript
interface OperationResult {
LastIndex?: number;
Details?: Array | null;
Status?: string | null;
}
`

$3

`typescript
interface OperationDetail {
Index?: number;
TransactionIndex?: number;
TransactionRef?: string | null;
SpecRef?: string | null;
SegmentId?: string | null;
DataElementId?: string | null;
DataElementIndex?: number;
CompositeIndex?: number;
RepIndex?: number;
Value?: string | null;
Message?: string | null;
Status?: string | null;
}
`

Logging and Tracing

The Unnbound EDI Client automatically creates spans for all operations and logs detailed information including:

- Operation type and timing
- Input and output data
- API request/response details
- Error details (if any)
- Validation results
- Acknowledgment status

$3

`json
{"level":"info","spanId":"556c53e6-3bb8-4118-b3b8-570e41c27654","type":"edi","edi":{"type":"x12","x12":{"input":"ISA00...","output":[...]}},"message":"X12 to JSON started."}
{"level":"info","spanId":"556c53e6-3bb8-4118-b3b8-570e41c27654","type":"edi","edi":{"type":"x12","x12":{"input":"ISA00...","output":[...]}},"duration":1250,"message":"X12 to JSON completed."}
`

Complete Example

`typescript
import { UnnboundEdiClient } from 'unnbound-edi-sdk';
import { logger } from 'unnbound-logger-sdk';

const run = async () => {
const edi = new UnnboundEdiClient();

const x12Data = ISA00 00 12NOTP 12NOTP 0805011700U004010000010000P>
GSPONOTPNOTP2008050117001000X004010
ST850000000010
BEG00SA0829224325420010501610385388
REFDP030
REFPS
ITD143*24546
DTM00120010510
PKGF68*PALLET, SHRINKWRAP 48W X 40D X 45H
PKGF66*REGULAR
TD5A92P3*SEE ROUTING GUIDE FOR ROUTING
N1STRETAIL STORE90001234567890
N3*123 ANYWHERE AVENUE
N4CITYST*12345
PO11120EA9.25TECB(12) 0-083628-838PRROVN*ABA18783
PO12220EA13.7 9TECB(69) 0-093 83 7-991PRROVN*RUP83112
PO13126EA10.9 9TECB(71) 0-099172-837PRROVN*CPR19293
PO1476EA4.35TECB(71) 0-012110-737PRROVN*PIW28173
PO1572EA7.5TECB(71) 0-0848 88-9 75PRROVN*JBM1938 7
PO16696EA9.55TECB(71) 0-003 922-121PRROVN*IUI19283
CTT*6
SE20000000010
GE11000
IEA1000001000;

try {
// Parse X12 to JSON
const x12Interchanges = await edi.fromX12({ input: x12Data });
logger.info({ count: x12Interchanges.length }, 'Parsed X12 interchanges');

// Process each interchange
for (const interchange of x12Interchanges) {
// Validate
const validation = await edi.validateX12({ input: interchange });
logger.info({ validation }, 'X12 validated');

// Convert back to X12
const x12Output = await edi.toX12({ input: interchange });
logger.info({ x12Output }, 'Converted back to X12');

// Generate acknowledgment
const acknowledgment = await edi.acknowledgeX12({ input: interchange });
logger.info({ acknowledgment }, 'Generated acknowledgment');
}
} catch (error) {
logger.error({ err: error }, 'EDI processing failed');
throw error;
}
};

run().catch(console.error);
`

Requirements

- Node.js >= 22.0.0
- TypeScript (for TypeScript projects)
- Unnbound EDI API key

Dependencies

- unnbound-logger-sdk`: Structured logging and tracing

Support

For support, please open an issue on the GitHub repository.