@ontemper/edi 1.1.7 → 1.2.0-beta.2

package/README.md

@@ -350,43 +350,83 @@ IEA*1*000001000`;
 run().catch(console.error);
 ```
 
-## Control Numbers
+## Control numbers
 
-The SDK provides functions for managing EDI control numbers (ISA13, GS06) via the centralized counter service:
+The SDK manages ISA13 and GS06 control numbers for each sender and receiver pair. `toX12()` automatically stamps
+empty or all-zero ISA13, GS06, and ST02 fields. It preserves valid non-zero values. ISA13 and GS06 use the
+centralized counters. ST02 is assigned `"0001"`.
+
+**By default, every environment draws from one shared sequence per trading partner. No setup is required.**
+Separating test traffic onto its own sequence is an optional, per-partner opt-in for agreements that demand it.
+
+### Separate test counters (optional)
+
+Skip this section unless a trading-partner agreement requires test traffic on an independent sequence. To opt in,
+configure the trading partner once, then seed and verify the lanes before sending test traffic. A seeded value is the
+last-used number, so the next allocation returns the seed plus one. To make the next ISA13 value 4601, seed 4600:
 
 ```typescript
-import { getNextControlNumber, getCurrentControlNumber, setControlNumber } from '@ontemper/edi';
+import {
+  getControlNumberPolicy,
+  getCurrentControlNumber,
+  setControlNumber,
+  setControlNumberPolicy,
+} from '@ontemper/edi';
 
-// Get next control number (atomic increment)
-const next = await getNextControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER');
+const senderId = 'ZZ:SENDER';
+const receiverId = 'ZZ:RECEIVER';
 
-// Peek at current value without incrementing
-const current = await getCurrentControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER');
+await setControlNumberPolicy(senderId, receiverId, { separateCounters: true });
 
-// Set a starting value before the counter has incremented (for migrations)
-await setControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER', 1000);
+// Seed the production lane explicitly before it starts.
+await setControlNumber('ISA13', senderId, receiverId, 4600, 9, { lane: 'production' });
+
+const policy = await getControlNumberPolicy(senderId, receiverId);
+const production = await getCurrentControlNumber('ISA13', senderId, receiverId, 9, { lane: 'production' });
+const test = await getCurrentControlNumber('ISA13', senderId, receiverId, 9, { lane: 'test' });
 ```
 
-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"`:
+`getControlNumberPolicy()` returns `configured` and `separateCounters`. After test traffic starts, you cannot turn
+separate counters off. `setControlNumberPolicy()` reports this as a `ControlNumberError` with the
+`counter_policy_locked` code.
+
+### Automatic environment routing
+
+The SDK reads `UNNBOUND_ENVIRONMENT` and sends it with counter operations only when its value is `sandbox`,
+`staging`, or `production`. The service selects the lane:
+
+| Policy | Production environment | Sandbox or staging |
+| --- | --- | --- |
+| No policy row | Production lane | Production lane |
+| `separateCounters: false` | Production lane | Production lane |
+| `separateCounters: true` | Production lane | Test lane |
+
+Older SDK versions do not send the environment, so their operations use the production lane. This is the historical
+sequence that all environments use when separation is off. ISA15
+(`UsageIndicator_15`) never selects a counter. Set ISA15 independently to the value required by the interchange.
+`toX12()` does not change it.
+
+### Manage counters directly
 
 ```typescript
-import { isControlNumberError, setControlNumber } from '@ontemper/edi';
+import { getCurrentControlNumber, getNextControlNumber, 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.
-  }
-}
+const next = await getNextControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER');
+const current = await getCurrentControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER');
+// The seed is last-used. To allocate 4601 next, seed 4600.
+await setControlNumber('ISA13', 'ZZ:SENDER', 'ZZ:RECEIVER', 4600, 9, { lane: 'production' });
 ```
 
-Requires `UNNBOUND_API_URL` environment variable (pre-configured in all workflow environments).
+Use the optional `{ lane: 'production' | 'test' }` argument on `getCurrentControlNumber()` and `setControlNumber()`
+to inspect or seed a specific lane. `getNextControlNumber()` always uses automatic environment routing and does not
+accept a lane.
+
+The seeded value is the last-used number, and the next allocation returns the seed plus one. For example, if you
+expect the next ISA13 value to be 4601, seed 4600. Set this value before the counter increments. The service treats a
+repeated seed with the same stored value as an idempotent operation. It rejects other updates after the counter
+starts with a `ControlNumberError` whose code is `counter_already_started`.
+
+These helpers require `UNNBOUND_API_URL`, which is preconfigured in workflow environments.
 
 ## Requirements
 

package/dist/control-numbers.d.ts

@@ -1,5 +1,27 @@
 /** @public */
-export type ControlNumberErrorCode = 'counter_already_started' | 'control_number_bad_request' | 'control_number_unauthorized' | 'control_number_unknown_error';
+export type ControlNumberCounterName = 'ISA13' | 'GS06';
+/** @public */
+export type ControlNumberLane = 'production' | 'test';
+/** @public */
+export interface ControlNumberLaneOptions {
+    readonly lane?: ControlNumberLane;
+}
+/** @public */
+export interface SetControlNumberPolicyOptions {
+    readonly separateCounters: boolean;
+}
+/** @public */
+export interface SetControlNumberPolicyResponse {
+    readonly tradingPartnerKey: string;
+    readonly separateCounters: boolean;
+}
+/** @public */
+export interface GetControlNumberPolicyResponse {
+    readonly configured: boolean;
+    readonly separateCounters: boolean;
+}
+/** @public */
+export type ControlNumberErrorCode = 'counter_already_started' | 'counter_policy_locked' | 'control_number_bad_request' | 'control_number_unauthorized' | 'control_number_unknown_error';
 interface ControlNumberErrorOptions extends ErrorOptions {
     code: ControlNumberErrorCode;
     message: string;
@@ -23,15 +45,19 @@ export declare const isControlNumberError: (error: unknown) => error is ControlN
  * @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>;
+export declare function getNextControlNumber(counterName: ControlNumberCounterName, 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>;
+export declare function getCurrentControlNumber(counterName: ControlNumberCounterName, senderId: string, receiverId: string, maxDigits?: number, options?: ControlNumberLaneOptions): Promise<string>;
 /**
  * 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 declare function setControlNumber(counterName: ControlNumberCounterName, senderId: string, receiverId: string, value: number, maxDigits?: number, options?: ControlNumberLaneOptions): Promise<string>;
+/** @public */
+export declare function setControlNumberPolicy(senderId: string, receiverId: string, { separateCounters }: SetControlNumberPolicyOptions): Promise<SetControlNumberPolicyResponse>;
+/** @public */
+export declare function getControlNumberPolicy(senderId: string, receiverId: string): Promise<GetControlNumberPolicyResponse>;
 export {};

package/dist/control-numbers.js

@@ -37,6 +37,8 @@ exports.isControlNumberError = exports.ControlNumberError = void 0;
 exports.getNextControlNumber = getNextControlNumber;
 exports.getCurrentControlNumber = getCurrentControlNumber;
 exports.setControlNumber = setControlNumber;
+exports.setControlNumberPolicy = setControlNumberPolicy;
+exports.getControlNumberPolicy = getControlNumberPolicy;
 const axios_1 = __importStar(require("axios"));
 let _client = null;
 function getApiClient() {
@@ -78,10 +80,23 @@ exports.ControlNumberError = ControlNumberError;
 /** @public */
 const isControlNumberError = (error) => error instanceof ControlNumberError;
 exports.isControlNumberError = isControlNumberError;
-function unwrapControlNumberError(error) {
+const getEnvironment = () => {
+    const environment = process.env.UNNBOUND_ENVIRONMENT;
+    return environment === 'sandbox' || environment === 'staging' || environment === 'production'
+        ? environment
+        : undefined;
+};
+function unwrapControlNumberError(error, operation) {
     if (error instanceof ControlNumberError)
         throw error;
     if ((0, axios_1.isAxiosError)(error)) {
+        if (error.response?.status === 409 && operation === 'policy') {
+            throw new ControlNumberError({
+                code: 'counter_policy_locked',
+                message: 'Separate counters cannot be disabled after test traffic has started. Keep separate counters enabled or contact Temper support.',
+                cause: error,
+            });
+        }
         if (error.response?.status === 409) {
             throw new ControlNumberError({
                 code: 'counter_already_started',
@@ -92,7 +107,7 @@ function unwrapControlNumberError(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.',
+                message: "Invalid EDI control number request. Use counter name 'ISA13' or 'GS06' with trading partner IDs and, for set, a value.",
                 cause: error,
             });
         }
@@ -110,6 +125,21 @@ function unwrapControlNumberError(error) {
         cause: error,
     });
 }
+async function requestControlNumber(operation, input) {
+    const environment = getEnvironment();
+    const request = { ...input, ...(environment ? { environment } : {}) };
+    try {
+        const response = operation === 'count'
+            ? await getApiClient().get(`/api/v2/internal/edi/control-numbers/${operation}`, {
+                params: request,
+            })
+            : await getApiClient().post(`/api/v2/internal/edi/control-numbers/${operation}`, request);
+        return response.data;
+    }
+    catch (error) {
+        return unwrapControlNumberError(error, operation);
+    }
+}
 /**
  * Get the next control number for an EDI counter.
  *
@@ -123,7 +153,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 requestControlNumber('increment', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
         counterName,
     });
@@ -133,12 +163,11 @@ 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: {
-            tradingPartnerKey: `${senderId}:${receiverId}`,
-            counterName,
-        },
+async function getCurrentControlNumber(counterName, senderId, receiverId, maxDigits = 9, options) {
+    const data = await requestControlNumber('count', {
+        tradingPartnerKey: `${senderId}:${receiverId}`,
+        counterName,
+        ...(options?.lane ? { lane: options.lane } : {}),
     });
     return String(data.value).padStart(maxDigits, '0');
 }
@@ -146,13 +175,40 @@ async function getCurrentControlNumber(counterName, senderId, receiverId, maxDig
  * 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', {
+async function setControlNumber(counterName, senderId, receiverId, value, maxDigits = 9, options) {
+    const data = await requestControlNumber('set', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
         counterName,
         value,
-    })
-        .catch(unwrapControlNumberError);
+        ...(options?.lane ? { lane: options.lane } : {}),
+    });
     return String(data.value).padStart(maxDigits, '0');
 }
+/** @public */
+async function setControlNumberPolicy(senderId, receiverId, { separateCounters }) {
+    try {
+        const response = await getApiClient().post('/api/v2/internal/edi/control-numbers/policy', {
+            tradingPartnerKey: `${senderId}:${receiverId}`,
+            separateCounters,
+        });
+        return response.data;
+    }
+    catch (error) {
+        return unwrapControlNumberError(error, 'policy');
+    }
+}
+/** @public */
+async function getControlNumberPolicy(senderId, receiverId) {
+    try {
+        const response = await getApiClient().get('/api/v2/internal/edi/control-numbers/policy', {
+            params: { tradingPartnerKey: `${senderId}:${receiverId}` },
+        });
+        return {
+            configured: response.data.configured,
+            separateCounters: response.data.separateCounters,
+        };
+    }
+    catch (error) {
+        return unwrapControlNumberError(error, 'policy');
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { type X12Interchange } from './edination-client';
-export type { ControlNumberErrorCode } from './control-numbers';
-export { ControlNumberError, getCurrentControlNumber, getNextControlNumber, isControlNumberError, setControlNumber, } from './control-numbers';
+import type { X12Interchange } from './edination-client';
+export type { ControlNumberCounterName, ControlNumberErrorCode, ControlNumberLane, ControlNumberLaneOptions, GetControlNumberPolicyResponse, SetControlNumberPolicyOptions, SetControlNumberPolicyResponse, } from './control-numbers';
+export { ControlNumberError, getControlNumberPolicy, getCurrentControlNumber, getNextControlNumber, isControlNumberError, setControlNumber, setControlNumberPolicy, } from './control-numbers';
 export * from './edination-client/model';
 interface UnnboundErrorOptions<C extends string = string> extends ErrorOptions {
     message: string;

package/dist/index.js

@@ -36,17 +36,20 @@ 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.isEdiInfrastructureError = exports.EdiInfrastructureError = exports.isTemperEdiClientError = exports.TemperEdiClientError = exports.setControlNumber = exports.isControlNumberError = exports.getNextControlNumber = exports.getCurrentControlNumber = exports.ControlNumberError = void 0;
+exports.TemperEdiClient = exports.isEdiInfrastructureError = exports.EdiInfrastructureError = exports.isTemperEdiClientError = exports.TemperEdiClientError = exports.setControlNumberPolicy = exports.setControlNumber = exports.isControlNumberError = exports.getNextControlNumber = exports.getCurrentControlNumber = exports.getControlNumberPolicy = 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 control_numbers_1 = require("./control-numbers");
 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; } });
+var control_numbers_2 = require("./control-numbers");
+Object.defineProperty(exports, "ControlNumberError", { enumerable: true, get: function () { return control_numbers_2.ControlNumberError; } });
+Object.defineProperty(exports, "getControlNumberPolicy", { enumerable: true, get: function () { return control_numbers_2.getControlNumberPolicy; } });
+Object.defineProperty(exports, "getCurrentControlNumber", { enumerable: true, get: function () { return control_numbers_2.getCurrentControlNumber; } });
+Object.defineProperty(exports, "getNextControlNumber", { enumerable: true, get: function () { return control_numbers_2.getNextControlNumber; } });
+Object.defineProperty(exports, "isControlNumberError", { enumerable: true, get: function () { return control_numbers_2.isControlNumberError; } });
+Object.defineProperty(exports, "setControlNumber", { enumerable: true, get: function () { return control_numbers_2.setControlNumber; } });
+Object.defineProperty(exports, "setControlNumberPolicy", { enumerable: true, get: function () { return control_numbers_2.setControlNumberPolicy; } });
 __exportStar(require("./edination-client/model"), exports);
 class UnnboundError extends Error {
     code;
@@ -154,7 +157,6 @@ class TemperEdiClient {
      * Zero-filled values from acknowledgment generation are placeholders, not manual overrides.
      */
     async stampControlNumbers(input) {
-        const { getNextControlNumber } = await import('./control-numbers.js');
         const isa = input.ISA;
         const senderQual = (isa.SenderIDQualifier_5 || '').trim();
         const senderId = (isa.InterchangeSenderID_6 || '').trim();
@@ -162,20 +164,18 @@ class TemperEdiClient {
         const receiverId = (isa.InterchangeReceiverID_8 || '').trim();
         const senderKey = `${senderQual}:${senderId}`;
         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.
+        // Allocate before mutating so a failed request cannot leave partial stamps.
         const isa13 = needsControlNumber(isa.InterchangeControlNumber_13)
-            ? await getNextControlNumber('ISA13', senderKey, receiverKey, 9)
+            ? await (0, control_numbers_1.getNextControlNumber)('ISA13', senderKey, receiverKey, 9)
             : null;
         const gs06Values = [];
         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);
+                const value = await (0, control_numbers_1.getNextControlNumber)('GS06', senderKey, receiverKey, 9);
                 gs06Values.push({ index: i, value });
             }
         }
-        // Phase 2: Apply all mutations (only reached if all fetches succeeded).
         if (isa13) {
             isa.InterchangeControlNumber_13 = isa13;
             if (input.IEATrailers?.length) {
@@ -189,7 +189,6 @@ class TemperEdiClient {
                 group.GETrailers[0].GroupControlNumber_2 = value;
             }
         }
-        // ST02 — always "0001" (pure assignment, no external calls)
         for (const group of groups) {
             for (const tx of group.Transactions) {
                 if (needsControlNumber(tx?.ST?.TransactionSetControlNumber_02)) {
@@ -202,14 +201,12 @@ class TemperEdiClient {
         }
     }
     async toX12({ input }) {
-        // Auto-stamp control numbers before writing X12
         try {
             await this.stampControlNumbers(input);
         }
         catch (error) {
             // Log but don't fail — workflows can still set control numbers manually
-            const { logger } = await import('unnbound-logger-sdk');
-            logger.warn({ err: error }, '[EDI SDK] Failed to auto-stamp control numbers, proceeding without');
+            unnbound_logger_sdk_1.logger.warn({ err: error }, '[EDI SDK] Failed to auto-stamp control numbers, proceeding without');
         }
         return (0, unnbound_logger_sdk_1.startSpan)('JSON to X12', () => {
             return this.X12.x12WritePost({ x12Interchange: input })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ontemper/edi",
   "description": "An EDI client with structured logging.",
-  "version": "1.1.7",
+  "version": "1.2.0-beta.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",
@@ -15,7 +15,7 @@
     "url": "https://github.com/unnbounddev/unnbound-sdks/issues"
   },
   "dependencies": {
-    "axios": "1.16.0",
+    "axios": "1.18.0",
     "unnbound-logger-sdk": "3.0.37"
   },
   "devDependencies": {