@ontemper/edi 1.1.5 → 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,30 +127,36 @@ 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
 
 The EDI client throws two distinct error classes. The distinction matters for file routing:
 a `TemperEdiClientError` is a verdict on the input document (bad file — don't retry) or a
-persistent auth failure, while an `EdiInfrastructureError` is a transient platform fault —
-the SDK's own plumbing failed (tracing/logging/serialization) or the EDI service was
-transiently unavailable (network failure, timeout, 5xx, rate limit). It says nothing about
-the document, so keep the file and retry (`error.retryable === true`).
+persistent authentication failure, while an `EdiInfrastructureError` is retryable and does
+not indicate that the document is invalid (`error.retryable === true`).
 
 ```typescript
 import { isEdiInfrastructureError, isTemperEdiClientError } from '@ontemper/edi';
@@ -155,11 +166,14 @@ async function processFile(rawX12: string) {
     return await edi.fromX12({ input: rawX12 });
   } catch (error) {
     if (isEdiInfrastructureError(error)) {
-      // Transient platform fault — the document is fine. Keep the file and rethrow
-      // so your poll loop / caller retries.
+      // Keep the file and rethrow so the caller can retry.
       throw error;
     }
     if (isTemperEdiClientError(error)) {
+      if (error.code === 'edi_unauthorized_error') {
+        // Surface authentication failures instead of quarantining the file.
+        throw error;
+      }
       // A verdict on the document (see codes below) — handle it terminally (e.g.
       // quarantine the file) and STOP. Do not rethrow into retry paths.
       console.error('EDI Error:', error.code, error.message);
@@ -183,11 +197,11 @@ async function processFile(rawX12: string) {
 | `edi_unauthorized_error` | Unauthorized access to EDI service   |
 | `edi_unknown_error`      | Legacy — no longer produced          |
 
-`EdiInfrastructureError` (transient platform fault, `retryable: true`):
+`EdiInfrastructureError` (`retryable: true`):
 
 | Code                   | Description                                                                          |
 | ---------------------- | ------------------------------------------------------------------------------------ |
-| `infrastructure_error` | SDK plumbing failure or transient EDI-service fault — not caused by the input document |
+| `infrastructure_error` | Retryable failure unrelated to the input document                              |
 
 ## Type Definitions
 
@@ -319,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');
@@ -349,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

@@ -16,10 +16,7 @@ export declare class TemperEdiClientError extends UnnboundError<TemperEdiClientE
 }
 export declare const isTemperEdiClientError: (error: unknown) => error is TemperEdiClientError;
 /**
- * A failure in the SDK's own plumbing (logging/instrumentation/tracing), not a verdict
- * on the EDI payload. Deliberately NOT a TemperEdiClientError and NOT an `edi_*` code:
- * workflows route `edi_*` errors as bad files, while these are transient platform
- * faults the workflow should retry (T-3235).
+ * A retryable failure that does not indicate an invalid EDI document.
  */
 export declare class EdiInfrastructureError extends UnnboundError<'infrastructure_error'> {
     readonly retryable = true;
@@ -45,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

@@ -66,10 +66,7 @@ exports.TemperEdiClientError = TemperEdiClientError;
 const isTemperEdiClientError = (error) => error instanceof TemperEdiClientError;
 exports.isTemperEdiClientError = isTemperEdiClientError;
 /**
- * A failure in the SDK's own plumbing (logging/instrumentation/tracing), not a verdict
- * on the EDI payload. Deliberately NOT a TemperEdiClientError and NOT an `edi_*` code:
- * workflows route `edi_*` errors as bad files, while these are transient platform
- * faults the workflow should retry (T-3235).
+ * A retryable failure that does not indicate an invalid EDI document.
  */
 class EdiInfrastructureError extends UnnboundError {
     retryable = true;
@@ -83,10 +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 });
-// One traced instance for the whole process, created once at module load. Never trace
-// the global axios export: in-place wrapping there accumulated a span layer per
-// TemperEdiClient construction (stack overflow after enough polls) and leaked EDI
-// payload capture into unrelated code sharing global axios (T-3235).
+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;
@@ -112,24 +109,12 @@ class TemperEdiClient {
         if (error instanceof EdiInfrastructureError)
             throw error;
         if ((0, axios_1.isAxiosError)(error)) {
-            // 401 = missing/expired/invalid credential (e.g. the sandbox EDI-gateway JWT),
-            // 403 = access denied. Neither is a verdict on the document.
-            if (error.status === 401 || error.status === 403)
+            const status = error.response?.status ?? error.status;
+            if (status === 401 || status === 403)
                 throw new TemperEdiClientError({
                     message: 'Unauthorized access to EDI service (credentials missing, expired, or invalid). Reach out to support.',
                     code: 'edi_unauthorized_error',
                 });
-            // Transport failures (no response: ECONNREFUSED/timeout/DNS), 5xx, and
-            // rate-limit/timeout statuses are transient service faults, not verdicts on
-            // the document — a brief EDI-service outage must never quarantine valid
-            // files in /error (T-3235).
-            const status = error.response?.status;
-            if (status === undefined || status >= 500 || status === 408 || status === 429) {
-                throw new EdiInfrastructureError({
-                    message: `EDI service unreachable or transiently failing (${status ?? error.code ?? 'no response'}): ${error.message}`,
-                    cause: error,
-                });
-            }
             // Gateway normalises EdiFabric's camelCase to PascalCase before forwarding
             const responseData = error.response?.data;
             const details = typeof responseData === 'object' &&
@@ -138,18 +123,18 @@ class TemperEdiClient {
                 Array.isArray(responseData.Details)
                 ? responseData.Details
                 : undefined;
-            const message = error.response?.status === 400 && details?.length
-                ? `EDI validation failed: ${details.join('; ')}`
-                : responseData && typeof responseData === 'object'
-                    ? `EDI request failed (${error.response?.status}): ${JSON.stringify(responseData)}`
-                    : error.message;
-            throw new TemperEdiClientError({ message, code, cause: error });
+            if (status === 400 && details?.length) {
+                throw new TemperEdiClientError({
+                    message: `EDI validation failed: ${details.join('; ')}`,
+                    code,
+                    cause: error,
+                });
+            }
+            throw new EdiInfrastructureError({
+                message: `EDI service request failed (${status ?? error.code ?? 'no response'}): ${error.message}`,
+                cause: error,
+            });
         }
-        // Not an axios error → the failure never reached the EDI HTTP exchange. It was
-        // raised by the SDK's own plumbing (span/logging instrumentation, request
-        // serialization), so it must not be reported as a verdict on the file: workflows
-        // route `edi_*` errors to /error, and that misrouted valid partner files when the
-        // instrumentation layer crashed (T-3235).
         throw new EdiInfrastructureError({
             message: `EDI client infrastructure failure (not caused by the input document): ${error instanceof Error ? error.message : String(error)}`,
             cause: error,
@@ -163,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');
@@ -179,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 });
             }
@@ -197,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.5",
+  "version": "1.1.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",