An EDI client with structured logging.
npm install unnbound-edi-sdkA TypeScript EDI client with structured logging and distributed tracing capabilities, built for processing X12 EDI documents with comprehensive error handling and automatic span tracking.
- 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
``bash`
npm install unnbound-edi-sdkor
pnpm add unnbound-edi-sdkor
yarn add unnbound-edi-sdk
- UNNBOUND_EDI_API_KEY - Your API key for authentication
`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],
});
`
`typescript`
new UnnboundEdiClient();
Creates a new EDI client instance. Requires UNNBOUND_EDI_API_KEY environment variable to be set.
#### 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
The EDI client provides custom error types for different operation failures:
`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
}
}
`
| 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 |
`typescript`
interface FromX12Options {
input: unknown; // X12 document as string or File
}
`typescript`
interface ToX12Options {
input: X12Interchange; // X12 interchange object
}
`typescript`
interface ValidateX12Options {
input: X12Interchange; // X12 interchange object
}
`typescript`
interface AcknolwedgeX12Options {
input: X12Interchange; // X12 interchange object
}
`typescript`
interface OperationResult {
LastIndex?: number;
Details?: Array
Status?: string | null;
}
`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;
}
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
`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."}
`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);
`
- Node.js >= 22.0.0
- TypeScript (for TypeScript projects)
- Unnbound EDI API key
- unnbound-logger-sdk`: Structured logging and tracing
For support, please open an issue on the GitHub repository.