@ontemper/edi 1.1.6 → 1.2.0-beta.1

package/README.md

@@ -1,10 +1,11 @@
 # Temper 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.
+A TypeScript EDI client with structured logging and distributed tracing capabilities, built for processing X12 (including HIPAA) and EDIFACT documents with comprehensive error handling and automatic span tracking.
 
 ## Features
 
-- **X12 EDI Processing**: Complete X12 document parsing, validation, and generation
+- **X12 EDI Processing**: Complete X12 document parsing, validation, and generation — HIPAA guide models resolve automatically from the ST03 implementation reference
+- **EDIFACT Processing**: `fromEdifact` / `toEdifact` / `validateEdifact` / `acknowledgeEdifact` with the same error handling, tracing, and automatic control-reference stamping (UNB-0020 from the central counter service, UNH-0062 local sequence)
 - **Structured Logging**: Built-in integration with Temper 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
@@ -54,10 +55,15 @@ const x12Document = await edi.toX12({
   input: x12Interchanges[0],
 });
 
-// Generate acknowledgment
-const acknowledgment = await edi.acknowledgeX12({
+// Generate and serialize acknowledgments
+const acknowledgments = await edi.acknowledgeX12({
   input: x12Interchanges[0],
 });
+
+for (const acknowledgment of acknowledgments) {
+  // Apply partner-specific outbound envelope IDs here when needed.
+  const acknowledgmentX12 = await edi.toX12({ input: acknowledgment });
+}
 ```
 
 ## API Reference
@@ -104,7 +110,7 @@ const x12Document = await edi.toX12({
 
 **Returns:** X12 document as string
 
-**Control number auto-stamping:** Leave `InterchangeControlNumber_13`, `GroupControlNumber_6`, and `TransactionSetControlNumber_02` empty or omit them. The SDK fetches atomic, per-trading-partner control numbers from a centralized counter service. If values are already set, they are left unchanged.
+**Control number auto-stamping:** Leave `InterchangeControlNumber_13`, `GroupControlNumber_6`, and `TransactionSetControlNumber_02` empty or omit them. Empty and all-zero ISA13, GS06, or ST02 values are treated as unassigned. Valid non-zero values are preserved.
 
 #### `validateX12(options: ValidateX12Options): Promise<OperationResult>`
 
@@ -122,21 +128,29 @@ const validationResult = await edi.validateX12({
 
 **Returns:** Validation result with operation details
 
-#### `acknowledgeX12(options: AcknolwedgeX12Options): Promise<OperationResult>`
+#### `acknowledgeX12(options: AcknolwedgeX12Options): Promise<X12Interchange[]>`
 
-Generates acknowledgment for X12 interchange objects.
+Generates acknowledgment interchange objects. Apply any partner-specific outbound envelope IDs, then serialize
+each acknowledgment with `toX12()`. During serialization, `toX12()` assigns control numbers using the final
+sender and receiver. The method always returns an array because one input can produce more than one
+acknowledgment.
 
 ```typescript
-const acknowledgment = await edi.acknowledgeX12({
+const acknowledgments = await edi.acknowledgeX12({
   input: x12InterchangeObject,
 });
+
+for (const acknowledgment of acknowledgments) {
+  // Apply partner-specific outbound envelope IDs here when needed.
+  const serialized = await edi.toX12({ input: acknowledgment });
+}
 ```
 
 **Parameters:**
 
 - `options.input` - The X12 interchange object to acknowledge
 
-**Returns:** Acknowledgment result with operation details
+**Returns:** The generated acknowledgment interchanges
 
 ## Error Handling
 
@@ -320,9 +334,13 @@ IEA*1*000001000`;
       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');
+      // Generate and serialize acknowledgments. toX12 assigns control numbers
+      // after any partner-specific outbound envelope changes.
+      const acknowledgments = await edi.acknowledgeX12({ input: interchange });
+      for (const acknowledgment of acknowledgments) {
+        const acknowledgmentX12 = await edi.toX12({ input: acknowledgment });
+        logger.info({ acknowledgmentX12 }, 'Generated acknowledgment');
+      }
     }
   } catch (error) {
     logger.error({ err: error }, 'EDI processing failed');
@@ -350,7 +368,9 @@ const current = await getCurrentControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER
 await setControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER', 1000);
 ```
 
-In most cases you don't need these directly — `toX12()` calls `getNextControlNumber` automatically for any empty ISA13/GS06 fields.
+In most cases you don't need these directly — `toX12()` automatically stamps any empty or all-zero
+ISA13/GS06/ST02 fields. ISA13 and GS06 use `getNextControlNumber`; ST02 is assigned `"0001"`. This includes the
+zero placeholders returned by acknowledgment generation.
 Once a counter has incremented, the API rejects later `setControlNumber` calls to avoid resetting active sequences.
 Retried `setControlNumber` calls with the same already-stored seed are treated as idempotent no-ops.
 The SDK surfaces that as a `ControlNumberError` with `code: "counter_already_started"`:

package/dist/control-numbers.js

@@ -123,7 +123,7 @@ function unwrapControlNumberError(error) {
  */
 /** @public */
 async function getNextControlNumber(counterName, senderId, receiverId, maxDigits = 9) {
-    const { data } = await getApiClient().post('/api/internal/edi/control-numbers/increment', {
+    const { data } = await getApiClient().post('/api/v2/internal/edi/control-numbers/increment', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
         counterName,
     });
@@ -134,7 +134,7 @@ async function getNextControlNumber(counterName, senderId, receiverId, maxDigits
  */
 /** @public */
 async function getCurrentControlNumber(counterName, senderId, receiverId, maxDigits = 9) {
-    const { data } = await getApiClient().get('/api/internal/edi/control-numbers/count', {
+    const { data } = await getApiClient().get('/api/v2/internal/edi/control-numbers/count', {
         params: {
             tradingPartnerKey: `${senderId}:${receiverId}`,
             counterName,
@@ -148,7 +148,7 @@ async function getCurrentControlNumber(counterName, senderId, receiverId, maxDig
 /** @public */
 async function setControlNumber(counterName, senderId, receiverId, value, maxDigits = 9) {
     const { data } = await getApiClient()
-        .post('/api/internal/edi/control-numbers/set', {
+        .post('/api/v2/internal/edi/control-numbers/set', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
         counterName,
         value,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type X12Interchange } from './edination-client';
+import { type EdifactInterchange, type X12Interchange } from './edination-client';
 export type { ControlNumberErrorCode } from './control-numbers';
 export { ControlNumberError, getCurrentControlNumber, getNextControlNumber, isControlNumberError, setControlNumber, } from './control-numbers';
 export * from './edination-client/model';
@@ -35,20 +35,48 @@ export interface ValidateX12Options {
 export interface AcknolwedgeX12Options {
     input: X12Interchange;
 }
+export interface FromEdifactOptions {
+    input: unknown;
+}
+export interface ToEdifactOptions {
+    input: EdifactInterchange;
+}
+export interface ValidateEdifactOptions {
+    input: EdifactInterchange;
+}
+export interface AcknowledgeEdifactOptions {
+    input: EdifactInterchange;
+}
 export declare class TemperEdiClient {
     private X12;
+    private Edifact;
     constructor();
     private unwrap;
     private unwrapError;
     fromX12({ input }: FromX12Options): Promise<X12Interchange[]>;
     /**
-     * Stamp ISA13/GS06 control numbers on the interchange if not already set.
+     * Stamp ISA13/GS06/ST02 control numbers on the interchange if not already set.
      * Uses the Restate-backed counter service for atomic, per-trading-partner sequencing.
      * ST02 is always "0001" (one transaction per file per ticket).
-     * If a control number is already set, it is left unchanged (opt-out for manual overrides).
+     * Zero-filled values from acknowledgment generation are placeholders, not manual overrides.
      */
     private stampControlNumbers;
     toX12({ input }: ToX12Options): Promise<unknown>;
     validateX12({ input }: ValidateX12Options): Promise<import("./edination-client").OperationResult>;
     acknowledgeX12({ input }: AcknolwedgeX12Options): Promise<X12Interchange[]>;
+    fromEdifact({ input }: FromEdifactOptions): Promise<EdifactInterchange[]>;
+    /**
+     * Stamp UNB-0020/UNH-0062 control references on the interchange if not already set.
+     *
+     * UNB-0020 (interchange control reference) comes from the same Restate-backed
+     * per-trading-partner counter service X12 uses, under the platform counter name
+     * `UNB0020` — unpadded, since EDIFACT 0020 is an..14 with no fixed width. The
+     * UNZ trailer echo is set to match. UNH-0062 (message reference number) only
+     * needs uniqueness within the interchange, so it is a local 1..n sequence with
+     * no service call, echoed into each UNT — the EDIFACT sibling of ST02="0001".
+     */
+    private stampEdifactControlNumbers;
+    toEdifact({ input }: ToEdifactOptions): Promise<unknown>;
+    validateEdifact({ input }: ValidateEdifactOptions): Promise<import("./edination-client").OperationResult>;
+    acknowledgeEdifact({ input }: AcknowledgeEdifactOptions): Promise<EdifactInterchange[]>;
 }

package/dist/index.js

@@ -79,10 +79,15 @@ exports.EdiInfrastructureError = EdiInfrastructureError;
 const isEdiInfrastructureError = (error) => error instanceof EdiInfrastructureError;
 exports.isEdiInfrastructureError = isEdiInfrastructureError;
 const buildEdiPayload = (edi) => ({ type: 'edi', edi });
-const buildEdiX12Payload = (operation, x12) => buildEdiPayload({ operation, type: 'x12', x12 });
+const buildEdiTransactionPayload = (operation, format, transaction) => buildEdiPayload({ operation, type: format, transaction });
+const needsControlNumber = (value) => {
+    const normalized = value?.trim();
+    return !normalized || /^0+$/.test(normalized);
+};
 const ediAxios = (0, unnbound_logger_sdk_1.traceAxios)(axios_1.default.create(), { getPayload: internal_1.internal });
 class TemperEdiClient {
     X12;
+    Edifact;
     constructor() {
         const apiKey = process.env.UNNBOUND_EDI_API_KEY;
         // When UNNBOUND_EDI_BASE_URL is set, use self-hosted EdiFabric InHouse API
@@ -95,6 +100,7 @@ class TemperEdiClient {
         // but the OpenAPI client requires a non-empty value — use a placeholder.
         const config = new edination_client_1.Configuration({ apiKey: apiKey ?? 'self-hosted', basePath });
         this.X12 = new edination_client_1.X12Api(config, undefined, ediAxios);
+        this.Edifact = new edination_client_1.EdifactApi(config, undefined, ediAxios);
     }
     unwrap(response) {
         return response.data;
@@ -141,13 +147,13 @@ class TemperEdiClient {
             return this.X12.x12ReadPost({ body: input })
                 .then(this.unwrap.bind(this))
                 .catch((error) => this.unwrapError(error, 'edi_read_error'));
-        }, (o) => buildEdiX12Payload('fromX12', { input, output: o?.result }));
+        }, (o) => buildEdiTransactionPayload('fromX12', 'x12', { input, output: o?.result }));
     }
     /**
-     * Stamp ISA13/GS06 control numbers on the interchange if not already set.
+     * Stamp ISA13/GS06/ST02 control numbers on the interchange if not already set.
      * Uses the Restate-backed counter service for atomic, per-trading-partner sequencing.
      * ST02 is always "0001" (one transaction per file per ticket).
-     * If a control number is already set, it is left unchanged (opt-out for manual overrides).
+     * Zero-filled values from acknowledgment generation are placeholders, not manual overrides.
      */
     async stampControlNumbers(input) {
         const { getNextControlNumber } = await import('./control-numbers.js');
@@ -160,12 +166,13 @@ class TemperEdiClient {
         const receiverKey = `${receiverQual}:${receiverId}`;
         // Phase 1: Fetch all needed control numbers (no mutations yet).
         // If any fetch fails, no fields are mutated — avoids partial stamping.
-        const isa13 = !isa.InterchangeControlNumber_13
+        const isa13 = needsControlNumber(isa.InterchangeControlNumber_13)
             ? await getNextControlNumber('ISA13', senderKey, receiverKey, 9)
             : null;
         const gs06Values = [];
-        for (let i = 0; i < input.Groups.length; i++) {
-            if (!input.Groups[i].GS.GroupControlNumber_6) {
+        const groups = input.Groups ?? [];
+        for (let i = 0; i < groups.length; i++) {
+            if (needsControlNumber(groups[i].GS.GroupControlNumber_6)) {
                 const value = await getNextControlNumber('GS06', senderKey, receiverKey, 9);
                 gs06Values.push({ index: i, value });
             }
@@ -178,16 +185,16 @@ class TemperEdiClient {
             }
         }
         for (const { index, value } of gs06Values) {
-            const group = input.Groups[index];
+            const group = groups[index];
             group.GS.GroupControlNumber_6 = value;
             if (group.GETrailers?.length) {
                 group.GETrailers[0].GroupControlNumber_2 = value;
             }
         }
         // ST02 — always "0001" (pure assignment, no external calls)
-        for (const group of input.Groups) {
+        for (const group of groups) {
             for (const tx of group.Transactions) {
-                if (!tx?.ST?.TransactionSetControlNumber_02) {
+                if (needsControlNumber(tx?.ST?.TransactionSetControlNumber_02)) {
                     if (tx?.ST)
                         tx.ST.TransactionSetControlNumber_02 = '0001';
                     if (tx?.SE)
@@ -210,7 +217,7 @@ class TemperEdiClient {
             return this.X12.x12WritePost({ x12Interchange: input })
                 .then(this.unwrap.bind(this))
                 .catch((error) => this.unwrapError(error, 'edi_write_error'));
-        }, (o) => buildEdiX12Payload('toX12', { input, output: o?.result }));
+        }, (o) => buildEdiTransactionPayload('toX12', 'x12', { input, output: o?.result }));
     }
     validateX12({ input }) {
         return (0, unnbound_logger_sdk_1.startSpan)('Validate X12', () => {
@@ -218,7 +225,7 @@ class TemperEdiClient {
                 .then(this.unwrap.bind(this))
                 .catch((error) => this.unwrapError(error, 'edi_validate_error'));
         }, (o) => ({
-            ...buildEdiX12Payload('validateX12', { input, output: o?.result }),
+            ...buildEdiTransactionPayload('validateX12', 'x12', { input, output: o?.result }),
             ...(o?.result?.Status === 'error' && { level: 'warn' }),
         }));
     }
@@ -227,7 +234,87 @@ class TemperEdiClient {
             return this.X12.x12AckPost({ x12Interchange: input })
                 .then(this.unwrap.bind(this))
                 .catch((error) => this.unwrapError(error, 'edi_acknowledge_error'));
-        }, (o) => buildEdiX12Payload('acknowledgeX12', { input, output: o?.result }));
+        }, (o) => buildEdiTransactionPayload('acknowledgeX12', 'x12', { input, output: o?.result }));
+    }
+    fromEdifact({ input }) {
+        return (0, unnbound_logger_sdk_1.startSpan)('EDIFACT to JSON', () => {
+            return this.Edifact.edifactReadPost({ body: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_read_error'));
+        }, (o) => buildEdiTransactionPayload('fromEdifact', 'edifact', { input, output: o?.result }));
+    }
+    /**
+     * Stamp UNB-0020/UNH-0062 control references on the interchange if not already set.
+     *
+     * UNB-0020 (interchange control reference) comes from the same Restate-backed
+     * per-trading-partner counter service X12 uses, under the platform counter name
+     * `UNB0020` — unpadded, since EDIFACT 0020 is an..14 with no fixed width. The
+     * UNZ trailer echo is set to match. UNH-0062 (message reference number) only
+     * needs uniqueness within the interchange, so it is a local 1..n sequence with
+     * no service call, echoed into each UNT — the EDIFACT sibling of ST02="0001".
+     */
+    async stampEdifactControlNumbers(input) {
+        const { getNextControlNumber } = await import('./control-numbers.js');
+        const sender = input.UNB?.INTERCHANGESENDER_2;
+        const recipient = input.UNB?.INTERCHANGERECIPIENT_3;
+        const senderKey = `${(sender?.IdentificationCodeQualifier_2 || '').trim()}:${(sender?.InterchangeSenderIdentification_1 || '').trim()}`;
+        const receiverKey = `${(recipient?.IdentificationCodeQualifier_2 || '').trim()}:${(recipient?.InterchangeRecipientIdentification_1 || '').trim()}`;
+        // Fetch before mutating — if the fetch fails, no fields change.
+        const unb0020 = needsControlNumber(input.UNB?.InterchangeControlReference_5)
+            ? await getNextControlNumber('UNB0020', senderKey, receiverKey, 0)
+            : null;
+        if (unb0020) {
+            input.UNB.InterchangeControlReference_5 = unb0020;
+            if (input.UNZTrailers?.length) {
+                input.UNZTrailers[0].InterchangeControlReference_2 = unb0020;
+            }
+        }
+        // UNH-0062 — local sequence across the interchange's messages (no external calls)
+        let messageReference = 0;
+        for (const group of input.Groups ?? []) {
+            for (const message of group.Transactions ?? []) {
+                messageReference += 1;
+                if (needsControlNumber(message?.UNH?.MessageReferenceNumber_01)) {
+                    if (message?.UNH)
+                        message.UNH.MessageReferenceNumber_01 = String(messageReference);
+                    if (message?.UNT)
+                        message.UNT.MessageReferenceNumber_02 = String(messageReference);
+                }
+            }
+        }
+    }
+    async toEdifact({ input }) {
+        // Auto-stamp control references before writing EDIFACT
+        try {
+            await this.stampEdifactControlNumbers(input);
+        }
+        catch (error) {
+            // Log but don't fail — workflows can still set control references manually
+            const { logger } = await import('unnbound-logger-sdk');
+            logger.warn({ err: error }, '[EDI SDK] Failed to auto-stamp control references, proceeding without');
+        }
+        return (0, unnbound_logger_sdk_1.startSpan)('JSON to EDIFACT', () => {
+            return this.Edifact.edifactWritePost({ edifactInterchange: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_write_error'));
+        }, (o) => buildEdiTransactionPayload('toEdifact', 'edifact', { input, output: o?.result }));
+    }
+    validateEdifact({ input }) {
+        return (0, unnbound_logger_sdk_1.startSpan)('Validate EDIFACT', () => {
+            return this.Edifact.edifactValidatePost({ edifactInterchange: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_validate_error'));
+        }, (o) => ({
+            ...buildEdiTransactionPayload('validateEdifact', 'edifact', { input, output: o?.result }),
+            ...(o?.result?.Status === 'error' && { level: 'warn' }),
+        }));
+    }
+    acknowledgeEdifact({ input }) {
+        return (0, unnbound_logger_sdk_1.startSpan)('Acknowledge EDIFACT', () => {
+            return this.Edifact.edifactAckPost({ edifactInterchange: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_acknowledge_error'));
+        }, (o) => buildEdiTransactionPayload('acknowledgeEdifact', 'edifact', { input, output: o?.result }));
     }
 }
 exports.TemperEdiClient = TemperEdiClient;

package/examples/node-edi.ts

@@ -46,9 +46,13 @@ IEA*1*000001000`;
 
       logger.info({ validated }, 'X12 validated.');
 
-      const acknowledged = await edi.acknowledgeX12({ input: x12Interchange });
+      const acknowledgments = await edi.acknowledgeX12({ input: x12Interchange });
 
-      logger.info({ acknowledged }, 'X12 acknowledged.');
+      for (const acknowledgment of acknowledgments) {
+        // Apply partner-specific outbound envelope IDs before serialization when needed.
+        const acknowledgmentX12 = await edi.toX12({ input: acknowledgment });
+        logger.info({ acknowledgmentX12 }, 'X12 acknowledgment generated.');
+      }
     }),
   );
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ontemper/edi",
   "description": "An EDI client with structured logging.",
-  "version": "1.1.6",
+  "version": "1.2.0-beta.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "axios": "1.16.0",
-    "unnbound-logger-sdk": "3.0.37"
+    "unnbound-logger-sdk": "3.2.0-beta.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",