@ontemper/edi 1.1.6 → 1.1.7

package/README.md

@@ -54,10 +54,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 +109,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 +127,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 +333,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 +367,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/index.d.ts

@@ -42,10 +42,10 @@ export declare class TemperEdiClient {
     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>;

package/dist/index.js

@@ -80,6 +80,10 @@ const isEdiInfrastructureError = (error) => error instanceof EdiInfrastructureEr
 exports.isEdiInfrastructureError = isEdiInfrastructureError;
 const buildEdiPayload = (edi) => ({ type: 'edi', edi });
 const buildEdiX12Payload = (operation, x12) => buildEdiPayload({ operation, type: 'x12', x12 });
+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;
@@ -144,10 +148,10 @@ class TemperEdiClient {
         }, (o) => buildEdiX12Payload('fromX12', { 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 +164,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 +183,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)

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.1.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",