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

npm install unnbound-edi-sdk
# or
pnpm add unnbound-edi-sdk
# or
yarn add unnbound-edi-sdk

Environment Variables

Required

• UNNBOUND_EDI_API_KEY - Your API key for authentication

Quick Start

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: 'ISA*00*          *00*          *12*NOTP...',
});

// 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

Constructor

new UnnboundEdiClient();

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

Methods

fromX12(options: FromX12Options): Promise<X12Interchange[]>

Parses X12 EDI documents into JSON format.

const x12Interchanges = await edi.fromX12({
  input: 'ISA*00*          *00*          *12*NOTP...',
});

Parameters:

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

Returns: Array of parsed X12 interchange objects

toX12(options: ToX12Options): Promise<unknown>

Converts JSON X12 interchange objects back to X12 format.

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<OperationResult>

Validates X12 interchange objects against EDI standards.

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<OperationResult>

Generates acknowledgment for X12 interchange objects.

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:

UnnboundEdiClientError

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
  }
}

Error Codes

| 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

FromX12Options

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

ToX12Options

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

ValidateX12Options

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

AcknolwedgeX12Options

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

OperationResult

interface OperationResult {
  LastIndex?: number;
  Details?: Array<OperationDetail> | null;
  Status?: string | null;
}

OperationDetail

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

Example Log Output

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

Complete Example

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

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

  const x12Data = `ISA*00*          *00*          *12*NOTP           *12*NOTP           *080501*1700*U*00401*000001000*0*P*>
GS*PO*NOTP*NOTP*20080501*1700*1000*X*004010
ST*850*000000010
BEG*00*SA*08292243254**20010501*610385388
REF*DP*030
REF*PS*
ITD*14*3*2**45**46
DTM*001*20010510
PKG*F*68***PALLET, SHRINKWRAP 48W X 40D X 45H
PKG*F*66***REGULAR
TD5*A*92*P3**SEE ROUTING GUIDE FOR ROUTING
N1*ST*RETAIL STORE*9*0001234567890
N3*123 ANYWHERE AVENUE
N4*CITY*ST*12345
PO1*1*120*EA*9.25*TE*CB*(12) 0-083628-838*PR*RO*VN*ABA18783
PO1*2*220*EA*13.7 9*TE*CB*(69) 0-093 83 7-991*PR*RO*VN*RUP83112
PO1*3*126*EA*10.9 9*TE*CB*(71) 0-099172-837*PR*RO*VN*CPR19293
PO1*4*76*EA*4.35*TE*CB*(71) 0-012110-737*PR*RO*VN*PIW28173
PO1*5*72*EA*7.5*TE*CB*(71) 0-0848 88-9 75*PR*RO*VN*JBM1938 7
PO1*6*696*EA*9.55*TE*CB*(71) 0-003 922-121*PR*RO*VN*IUI19283
CTT*6
SE*20*000000010
GE*1*1000
IEA*1*000001000`;

  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.