@ontemper/edi 1.1.3 → 1.1.5

package/README.md

@@ -22,9 +22,12 @@ yarn add @ontemper/edi
 
 ## Environment Variables
 
-### Required
+`TemperEdiClient` is a thin HTTP client for Temper's EDI service, and it configures itself entirely from the environment — the platform injects the right values per environment, the same way it injects `UNNBOUND_API_URL`, so you don't set these by hand.
 
-- `UNNBOUND_EDI_API_KEY` - Your API key for authentication
+- **`UNNBOUND_EDI_BASE_URL`** — where the EDI service is reachable *from this environment*. A deployed workflow runs inside the cluster and gets the service's internal URL directly (no credential — cluster networking is the trust boundary). The builder sandbox runs outside the cluster, so it gets Temper's authenticated `/api/edi-gateway` proxy instead.
+- **`UNNBOUND_EDI_API_KEY`** — the credential for whichever path needs one: a platform-minted JWT through the sandbox gateway, or an EDINation-cloud key in the legacy no-base-URL setup. The direct in-cluster path needs no key and ignores it.
+
+The client throws only if it finds *neither*. There's nothing to provision, hardcode, or gate on — just `new TemperEdiClient()`.
 
 ## Quick Start
 
@@ -32,9 +35,8 @@ yarn add @ontemper/edi
 import { TemperEdiClient } from '@ontemper/edi';
 import { logger } from 'unnbound-logger-sdk';
 
-// Set your API key
-process.env.UNNBOUND_EDI_API_KEY = 'your-api-key';
-
+// In a Temper workflow environment the EDI connection is already configured
+// via env (platform-injected) — just construct the client:
 const edi = new TemperEdiClient();
 
 // Parse X12 document to JSON
@@ -66,7 +68,7 @@ const acknowledgment = await edi.acknowledgeX12({
 new TemperEdiClient();
 ```
 
-Creates a new EDI client instance. Requires `UNNBOUND_EDI_API_KEY` environment variable to be set.
+Creates a new EDI client instance. It configures itself from two platform-owned environment variables — `UNNBOUND_EDI_BASE_URL` (where Temper's EDI service is reachable from this environment: the in-cluster URL in a deployed workflow, or the `/api/edi-gateway` proxy in the builder sandbox) and `UNNBOUND_EDI_API_KEY` (the credential for whichever path needs one — a gateway JWT, or a legacy EDINation-cloud key; the direct in-cluster path ignores it). In a Temper workflow environment the platform injects the right pair. Throws only if neither is set.
 
 ### Methods
 
@@ -138,32 +140,54 @@ const acknowledgment = await edi.acknowledgeX12({
 
 ## Error Handling
 
-The EDI client provides custom error types for different operation failures:
-
-### TemperEdiClientError
+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`).
 
 ```typescript
-import { TemperEdiClientError, isTemperEdiClientError } from '@ontemper/edi';
+import { isEdiInfrastructureError, isTemperEdiClientError } from '@ontemper/edi';
 
-try {
-  await edi.fromX12({ input: invalidX12 });
-} catch (error) {
-  if (isTemperEdiClientError(error)) {
-    console.error('EDI Error:', error.code, error.message);
-    // Handle specific EDI errors
+async function processFile(rawX12: string) {
+  try {
+    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.
+      throw error;
+    }
+    if (isTemperEdiClientError(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);
+      return undefined;
+    }
+    throw error; // unrecognized — surface to the caller
   }
 }
 ```
 
 ### 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          |
+`TemperEdiClientError` (verdict on the document):
+
+| 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_unauthorized_error` | Unauthorized access to EDI service   |
+| `edi_unknown_error`      | Legacy — no longer produced          |
+
+`EdiInfrastructureError` (transient platform fault, `retryable: true`):
+
+| Code                   | Description                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| `infrastructure_error` | SDK plumbing failure or transient EDI-service fault — not caused by the input document |
 
 ## Type Definitions
 
@@ -321,11 +345,26 @@ const next = await getNextControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER');
 // Peek at current value without incrementing
 const current = await getCurrentControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER');
 
-// Set a starting value (for migrations)
+// Set a starting value before the counter has incremented (for migrations)
 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.
+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"`:
+
+```typescript
+import { isControlNumberError, setControlNumber } from '@ontemper/edi';
+
+try {
+  await setControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER', 1000);
+} catch (error) {
+  if (isControlNumberError(error) && error.code === 'counter_already_started') {
+    // Counter is already active; do not reset it.
+  }
+}
+```
 
 Requires `UNNBOUND_API_URL` environment variable (pre-configured in all workflow environments).
 
@@ -333,7 +372,7 @@ Requires `UNNBOUND_API_URL` environment variable (pre-configured in all workflow
 
 - Node.js >= 22.0.0
 - TypeScript (for TypeScript projects)
-- Temper EDI API key
+- The EDI connection env — `UNNBOUND_EDI_BASE_URL`, plus `UNNBOUND_EDI_API_KEY` where the path needs a credential — is platform-injected per environment in Temper workflows; nothing to configure. Supply a key yourself only for the standalone legacy EDINation-cloud path.
 - `UNNBOUND_API_URL` (for control number auto-stamping, pre-configured in workflow environments)
 
 ## Dependencies

package/dist/control-numbers.d.ts

@@ -1,3 +1,16 @@
+/** @public */
+export type ControlNumberErrorCode = 'counter_already_started' | 'control_number_bad_request' | 'control_number_unauthorized' | 'control_number_unknown_error';
+interface ControlNumberErrorOptions extends ErrorOptions {
+    code: ControlNumberErrorCode;
+    message: string;
+}
+/** @public */
+export declare class ControlNumberError extends Error {
+    code: ControlNumberErrorCode;
+    constructor({ code, message, ...options }: ControlNumberErrorOptions);
+}
+/** @public */
+export declare const isControlNumberError: (error: unknown) => error is ControlNumberError;
 /**
  * Get the next control number for an EDI counter.
  *
@@ -9,12 +22,16 @@
  * @param receiverId - Receiver qualifier + ID (e.g. "ZZ:RECEIVER456")
  * @param maxDigits - Zero-pad to this width (default: 9 for ISA13)
  */
+/** @public */
 export declare function getNextControlNumber(counterName: string, senderId: string, receiverId: string, maxDigits?: number): Promise<string>;
 /**
  * Get the current control number value without incrementing.
  */
+/** @public */
 export declare function getCurrentControlNumber(counterName: string, senderId: string, receiverId: string, maxDigits?: number): Promise<string>;
 /**
- * Set a control number to a specific value (for migration/seeding).
+ * Set a control number to a specific value before the counter starts (for migration/seeding).
  */
+/** @public */
 export declare function setControlNumber(counterName: string, senderId: string, receiverId: string, value: number, maxDigits?: number): Promise<string>;
+export {};

package/dist/control-numbers.js

@@ -1,12 +1,43 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isControlNumberError = exports.ControlNumberError = void 0;
 exports.getNextControlNumber = getNextControlNumber;
 exports.getCurrentControlNumber = getCurrentControlNumber;
 exports.setControlNumber = setControlNumber;
-const axios_1 = __importDefault(require("axios"));
+const axios_1 = __importStar(require("axios"));
 let _client = null;
 function getApiClient() {
     if (_client)
@@ -34,6 +65,51 @@ function getApiClient() {
     });
     return _client;
 }
+/** @public */
+class ControlNumberError extends Error {
+    code;
+    constructor({ code, message, ...options }) {
+        super(message, options);
+        this.name = 'ControlNumberError';
+        this.code = code;
+    }
+}
+exports.ControlNumberError = ControlNumberError;
+/** @public */
+const isControlNumberError = (error) => error instanceof ControlNumberError;
+exports.isControlNumberError = isControlNumberError;
+function unwrapControlNumberError(error) {
+    if (error instanceof ControlNumberError)
+        throw error;
+    if ((0, axios_1.isAxiosError)(error)) {
+        if (error.response?.status === 409) {
+            throw new ControlNumberError({
+                code: 'counter_already_started',
+                message: 'Cannot set EDI control number after counter has started. Set the starting value before calling getNextControlNumber or toX12 for this trading partner.',
+                cause: error,
+            });
+        }
+        if (error.response?.status === 400) {
+            throw new ControlNumberError({
+                code: 'control_number_bad_request',
+                message: 'Invalid EDI control number request. Counter name, trading partner IDs, and value are required.',
+                cause: error,
+            });
+        }
+        if (error.response?.status === 401) {
+            throw new ControlNumberError({
+                code: 'control_number_unauthorized',
+                message: 'Unauthorized access to EDI control number service.',
+                cause: error,
+            });
+        }
+    }
+    throw new ControlNumberError({
+        code: 'control_number_unknown_error',
+        message: error instanceof Error ? error.message : 'Unknown EDI control number error.',
+        cause: error,
+    });
+}
 /**
  * Get the next control number for an EDI counter.
  *
@@ -45,6 +121,7 @@ function getApiClient() {
  * @param receiverId - Receiver qualifier + ID (e.g. "ZZ:RECEIVER456")
  * @param maxDigits - Zero-pad to this width (default: 9 for ISA13)
  */
+/** @public */
 async function getNextControlNumber(counterName, senderId, receiverId, maxDigits = 9) {
     const { data } = await getApiClient().post('/api/internal/edi/control-numbers/increment', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
@@ -55,6 +132,7 @@ async function getNextControlNumber(counterName, senderId, receiverId, maxDigits
 /**
  * Get the current control number value without incrementing.
  */
+/** @public */
 async function getCurrentControlNumber(counterName, senderId, receiverId, maxDigits = 9) {
     const { data } = await getApiClient().get('/api/internal/edi/control-numbers/count', {
         params: {
@@ -65,13 +143,16 @@ async function getCurrentControlNumber(counterName, senderId, receiverId, maxDig
     return String(data.value).padStart(maxDigits, '0');
 }
 /**
- * Set a control number to a specific value (for migration/seeding).
+ * Set a control number to a specific value before the counter starts (for migration/seeding).
  */
+/** @public */
 async function setControlNumber(counterName, senderId, receiverId, value, maxDigits = 9) {
-    const { data } = await getApiClient().post('/api/internal/edi/control-numbers/set', {
+    const { data } = await getApiClient()
+        .post('/api/internal/edi/control-numbers/set', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
         counterName,
         value,
-    });
+    })
+        .catch(unwrapControlNumberError);
     return String(data.value).padStart(maxDigits, '0');
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type X12Interchange } from './edination-client';
-export { getCurrentControlNumber, getNextControlNumber, setControlNumber } from './control-numbers';
+export type { ControlNumberErrorCode } from './control-numbers';
+export { ControlNumberError, getCurrentControlNumber, getNextControlNumber, isControlNumberError, setControlNumber, } from './control-numbers';
 export * from './edination-client/model';
 interface UnnboundErrorOptions<C extends string = string> extends ErrorOptions {
     message: string;
@@ -14,6 +15,17 @@ export declare class TemperEdiClientError extends UnnboundError<TemperEdiClientE
     constructor({ message, code, ...o }: UnnboundErrorOptions<TemperEdiClientErrorCode>);
 }
 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).
+ */
+export declare class EdiInfrastructureError extends UnnboundError<'infrastructure_error'> {
+    readonly retryable = true;
+    constructor({ message, ...o }: Omit<UnnboundErrorOptions<'infrastructure_error'>, 'code'>);
+}
+export declare const isEdiInfrastructureError: (error: unknown) => error is EdiInfrastructureError;
 export interface FromX12Options {
     input: unknown;
 }

package/dist/index.js

@@ -36,14 +36,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TemperEdiClient = exports.isTemperEdiClientError = exports.TemperEdiClientError = exports.setControlNumber = exports.getNextControlNumber = exports.getCurrentControlNumber = void 0;
+exports.TemperEdiClient = exports.isEdiInfrastructureError = exports.EdiInfrastructureError = exports.isTemperEdiClientError = exports.TemperEdiClientError = exports.setControlNumber = exports.isControlNumberError = exports.getNextControlNumber = exports.getCurrentControlNumber = exports.ControlNumberError = void 0;
 const axios_1 = __importStar(require("axios"));
 const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
 const internal_1 = require("unnbound-logger-sdk/dist/internal");
 const edination_client_1 = require("./edination-client");
 var control_numbers_1 = require("./control-numbers");
+Object.defineProperty(exports, "ControlNumberError", { enumerable: true, get: function () { return control_numbers_1.ControlNumberError; } });
 Object.defineProperty(exports, "getCurrentControlNumber", { enumerable: true, get: function () { return control_numbers_1.getCurrentControlNumber; } });
 Object.defineProperty(exports, "getNextControlNumber", { enumerable: true, get: function () { return control_numbers_1.getNextControlNumber; } });
+Object.defineProperty(exports, "isControlNumberError", { enumerable: true, get: function () { return control_numbers_1.isControlNumberError; } });
 Object.defineProperty(exports, "setControlNumber", { enumerable: true, get: function () { return control_numbers_1.setControlNumber; } });
 __exportStar(require("./edination-client/model"), exports);
 class UnnboundError extends Error {
@@ -63,8 +65,29 @@ class TemperEdiClientError extends UnnboundError {
 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).
+ */
+class EdiInfrastructureError extends UnnboundError {
+    retryable = true;
+    constructor({ message, ...o }) {
+        super({ message, code: 'infrastructure_error', ...o });
+        this.name = 'EdiInfrastructureError';
+    }
+}
+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 });
+// 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 ediAxios = (0, unnbound_logger_sdk_1.traceAxios)(axios_1.default.create(), { getPayload: internal_1.internal });
 class TemperEdiClient {
     X12;
     constructor() {
@@ -78,8 +101,7 @@ class TemperEdiClient {
         // Self-hosted service ignores the API key header (ClusterIP, no auth needed),
         // but the OpenAPI client requires a non-empty value — use a placeholder.
         const config = new edination_client_1.Configuration({ apiKey: apiKey ?? 'self-hosted', basePath });
-        const client = (0, unnbound_logger_sdk_1.traceAxios)(axios_1.default, { getPayload: internal_1.internal });
-        this.X12 = new edination_client_1.X12Api(config, undefined, client);
+        this.X12 = new edination_client_1.X12Api(config, undefined, ediAxios);
     }
     unwrap(response) {
         return response.data;
@@ -87,12 +109,27 @@ class TemperEdiClient {
     unwrapError(error, code) {
         if (error instanceof TemperEdiClientError)
             throw error;
+        if (error instanceof EdiInfrastructureError)
+            throw error;
         if ((0, axios_1.isAxiosError)(error)) {
-            if (error.status === 403)
+            // 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)
                 throw new TemperEdiClientError({
-                    message: 'Unauthorized access to EDI service. Reach out to support.',
+                    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' &&
@@ -108,15 +145,13 @@ class TemperEdiClient {
                     : error.message;
             throw new TemperEdiClientError({ message, code, cause: error });
         }
-        if (error instanceof Error)
-            throw new TemperEdiClientError({
-                message: error.message,
-                code: 'edi_unknown_error',
-                cause: error,
-            });
-        throw new TemperEdiClientError({
-            message: 'Unknown error occured in EDI client.',
-            code: 'edi_unknown_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,
         });
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ontemper/edi",
   "description": "An EDI client with structured logging.",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",
@@ -15,12 +15,13 @@
     "url": "https://github.com/unnbounddev/unnbound-sdks/issues"
   },
   "dependencies": {
-    "axios": "1.15.1",
-    "unnbound-logger-sdk": "3.0.36"
+    "axios": "1.16.0",
+    "unnbound-logger-sdk": "3.0.37"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
-    "@types/node": "^24.12.2"
+    "@types/node": "^24.12.2",
+    "vitest": "^4.0.15"
   },
   "files": [
     "examples/*",
@@ -34,10 +35,8 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc",
-    "test": "echo 'No tests'",
-    "typecheck": "tsgo --noEmit",
-    "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
-    "lint:fix": "pnpm run lint --fix",
+    "test": "vitest run src",
+    "typecheck": "tsc --noEmit",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "start:example": "tsx watch examples/node-edi.ts",