@ontemper/edi 1.2.0-beta.3 → 1.2.0-beta.4

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [1.1.7](https://github.com/ontemper/temper/releases/tag/%40ontemper%2Fedi-v1.1.7) (2026-07-28)
+
+
+### Bug Fixes
+
+* stamp zero acknowledgment envelope control numbers ([#2421](https://github.com/ontemper/temper/pull/2421))
+
+## [1.0.13](https://github.com/unnbounddev/unnbound-sdks/compare/unnbound-edi-sdk-v1.0.12...unnbound-edi-sdk-v1.0.13) (2025-11-25)
+
+
+### Bug Fixes
+
+* setup ci/cd ([dd2640f](https://github.com/unnbounddev/unnbound-sdks/commit/dd2640f01e39f1342f3e08dc882164b50331c7bb))
+* setup ci/cd ([520c03a](https://github.com/unnbounddev/unnbound-sdks/commit/520c03aacd978d7923b3bcf45c4f74a870be019d))
+
+## [1.0.12](https://github.com/unnbounddev/unnbound-sdks/compare/unnbound-edi-sdk-v1.0.11...unnbound-edi-sdk-v1.0.12) (2025-11-25)
+
+
+### Bug Fixes
+
+* remove unused files ([6dc00c2](https://github.com/unnbounddev/unnbound-sdks/commit/6dc00c20b092b17e9eb2108ef83dc5beafdef3f5))
+* setup ci/cd ([d3759c1](https://github.com/unnbounddev/unnbound-sdks/commit/d3759c14f7863e4c8d2f5e80bdbbf2446df79f1a))
+* setup ci/cd ([7e06fc8](https://github.com/unnbounddev/unnbound-sdks/commit/7e06fc84ae7bafba3e9c2c0225f9f9d614fa9207))

package/README.md

@@ -354,21 +354,20 @@ run().catch(console.error);
 
 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"`.
+centralized counter service. ST02 is assigned `"0001"`.
 
-Each Temper environment now has its own ISA13 and GS06 counter ledger.
+Each Temper environment has a separate counter ledger. Production allocations continue the partner's production
+sequence. Sandbox and staging allocations do not consume production control numbers. A ledger rolls over after
+`999999999`, so the next value is `000000001`.
 
 ### Automatic environment routing
 
-Automatic allocation reads `UNNBOUND_ENVIRONMENT`. Its value must be exactly `sandbox`, `staging`, or
-`production`. If the variable is missing or invalid, the SDK throws a `ControlNumberError` with the
-`control_number_environment_missing` code before making an HTTP request. This fail-closed behavior prevents an
-automatic allocation from using the wrong environment.
+Temper injects `TEMPER_ENVIRONMENT` into workflows. The SDK uses `UNNBOUND_ENVIRONMENT` only when
+`TEMPER_ENVIRONMENT` is absent. The value must be `sandbox`, `staging`, or `production`. A missing or invalid value
+causes a `ControlNumberError` with the `control_number_environment_missing` code before any HTTP request.
 
-`getNextControlNumber()` and `toX12()` always use this ambient environment. ISA15 (`UsageIndicator_15`) does not
-select a counter, and `toX12()` does not change it.
-
-### Manage counters directly
+`getNextControlNumber()`, `getCurrentControlNumber()`, and `toX12()` use this environment. They do not accept an
+environment override. ISA15 (`UsageIndicator_15`) does not select a counter, and `toX12()` does not change it.
 
 ```typescript
 import { getCurrentControlNumber, getNextControlNumber, setControlNumber } from '@ontemper/edi';
@@ -379,25 +378,18 @@ const receiverId = 'ZZ:RECEIVER';
 const next = await getNextControlNumber('ISA13', senderId, receiverId);
 const current = await getCurrentControlNumber('ISA13', senderId, receiverId);
 
-// A sandbox onboarding workflow can inspect and seed the production ledger explicitly.
-const productionCurrent = await getCurrentControlNumber('ISA13', senderId, receiverId, 9, {
-  environment: 'production',
-});
-await setControlNumber('ISA13', senderId, receiverId, 4600, 9, {
-  environment: 'production',
-});
+// Legacy production migration: store 4599 as the last-used value.
+await setControlNumber('ISA13', senderId, receiverId, 4599);
 ```
 
-`getCurrentControlNumber()` and `setControlNumber()` accept an optional
-`{ environment: 'sandbox' | 'staging' | 'production' }` argument for cross-environment inspection and seeding.
-An explicit environment takes precedence over `UNNBOUND_ENVIRONMENT`. Without this option, both methods require
-the ambient environment. `getNextControlNumber()` accepts no environment override.
+`setControlNumber()` is the legacy production setter. Its value is the last-used number, so setting `4599` makes the
+next allocation `4600`. It uses the flat production route and does not use the environment variables.
 
-A seed is the last-used value: seeding 4600 makes the next allocation 4601. Seed a counter only before its first
-increment. A repeated seed with the same stored value is idempotent; a different seed after the counter starts
-throws a `ControlNumberError` with the `counter_already_started` code.
+Use the Builder agent `set_edi_control_number` tool for per-environment seeding. The tool value is the next number.
+For example, seeding `4600` makes the next allocation `4600`. Seeding is forward-only. Re-seeding the same value is
+a no-op.
 
-These helpers require `UNNBOUND_API_URL`, which is preconfigured in workflow environments.
+These helpers require `UNNBOUND_API_URL`. Temper configures it in workflow environments.
 
 ## Requirements
 
@@ -405,6 +397,7 @@ These helpers require `UNNBOUND_API_URL`, which is preconfigured in workflow env
 - TypeScript (for TypeScript projects)
 - 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)
+- `TEMPER_ENVIRONMENT` for counter routing, with `UNNBOUND_ENVIRONMENT` as the legacy fallback
 
 ## Dependencies
 

package/dist/control-numbers.d.ts

@@ -3,11 +3,7 @@ export type TemperEnvironment = 'sandbox' | 'staging' | 'production';
 /** @public */
 export type ControlNumberCounterName = 'ISA13' | 'GS06';
 /** @public */
-export interface ControlNumberEnvironmentOptions {
-    readonly environment?: TemperEnvironment;
-}
-/** @public */
-export type ControlNumberErrorCode = 'control_number_environment_missing' | 'counter_already_started' | 'control_number_bad_request' | 'control_number_unauthorized' | 'control_number_unknown_error';
+export type ControlNumberErrorCode = 'counter_already_started' | 'control_number_environment_missing' | 'control_number_bad_request' | 'control_number_unauthorized' | 'control_number_unknown_error';
 interface ControlNumberErrorOptions extends ErrorOptions {
     code: ControlNumberErrorCode;
     message: string;
@@ -18,12 +14,12 @@ export declare class ControlNumberError extends Error {
     constructor({ code, message, ...options }: ControlNumberErrorOptions);
 }
 /** @public */
-export declare const isControlNumberError: (error: unknown) => error is ControlNumberError;
+export declare const isControlNumberError: (error: ErrorOptions['cause']) => error is ControlNumberError;
 /**
  * Get the next control number for an EDI counter.
  *
- * Calls the API-hosted Restate counter object which persists state
- * and handles rollover (999999999 → 1) automatically.
+ * The centralized service isolates counters by Temper environment.
+ * It rolls 999999999 over to 1.
  *
  * @param counterName - Counter type: 'ISA13' or 'GS06'
  * @param senderId - Sender qualifier + ID (e.g. "ZZ:SENDER123")
@@ -36,10 +32,12 @@ export declare function getNextControlNumber(counterName: ControlNumberCounterNa
  * Get the current control number value without incrementing.
  */
 /** @public */
-export declare function getCurrentControlNumber(counterName: ControlNumberCounterName, senderId: string, receiverId: string, maxDigits?: number, options?: ControlNumberEnvironmentOptions): Promise<string>;
+export declare function getCurrentControlNumber(counterName: ControlNumberCounterName, senderId: string, receiverId: string, maxDigits?: number): Promise<string>;
 /**
- * Set a control number to a specific value before the counter starts (for migration/seeding).
+ * Set the last-used production control number through the legacy endpoint.
+ *
+ * Use the Builder agent `set_edi_control_number` tool for per-environment seeding.
  */
 /** @public */
-export declare function setControlNumber(counterName: ControlNumberCounterName, senderId: string, receiverId: string, value: number, maxDigits?: number, options?: ControlNumberEnvironmentOptions): Promise<string>;
+export declare function setControlNumber(counterName: ControlNumberCounterName, senderId: string, receiverId: string, value: number, maxDigits?: number): Promise<string>;
 export {};

package/dist/control-numbers.js

@@ -79,19 +79,26 @@ exports.ControlNumberError = ControlNumberError;
 const isControlNumberError = (error) => error instanceof ControlNumberError;
 exports.isControlNumberError = isControlNumberError;
 const requireEnvironment = () => {
-    const environment = process.env.UNNBOUND_ENVIRONMENT;
+    const environment = process.env.TEMPER_ENVIRONMENT ?? process.env.UNNBOUND_ENVIRONMENT;
     if (environment === 'sandbox' || environment === 'staging' || environment === 'production') {
         return environment;
     }
     throw new ControlNumberError({
         code: 'control_number_environment_missing',
-        message: "UNNBOUND_ENVIRONMENT must be set to 'sandbox', 'staging', or 'production' because automatic control-number routing needs it.",
+        message: "TEMPER_ENVIRONMENT or UNNBOUND_ENVIRONMENT must be set to 'sandbox', 'staging', or 'production' because automatic control-number routing needs it.",
     });
 };
-function unwrapControlNumberError(error) {
+function unwrapControlNumberError(error, environmentScoped = false) {
     if (error instanceof ControlNumberError)
         throw error;
     if ((0, axios_1.isAxiosError)(error)) {
+        if (environmentScoped && error.response?.status === 404) {
+            throw new ControlNumberError({
+                code: 'control_number_unknown_error',
+                message: 'The Temper API does not support environment-scoped EDI control numbers yet.',
+                cause: error,
+            });
+        }
         if (error.response?.status === 409) {
             throw new ControlNumberError({
                 code: 'counter_already_started',
@@ -102,7 +109,7 @@ function unwrapControlNumberError(error) {
         if (error.response?.status === 400) {
             throw new ControlNumberError({
                 code: 'control_number_bad_request',
-                message: "Invalid EDI control number request. Use counter name 'ISA13' or 'GS06' with trading partner IDs and, for set, a value.",
+                message: "Invalid EDI control number request. Use counter name 'ISA13' or 'GS06' with trading partner IDs.",
                 cause: error,
             });
         }
@@ -120,25 +127,24 @@ function unwrapControlNumberError(error) {
         cause: error,
     });
 }
-async function requestControlNumber(operation, input, environment) {
-    const request = { ...input, environment: environment ?? requireEnvironment() };
+async function requestControlNumber(operation, input) {
+    const environment = requireEnvironment();
+    const path = `/api/v2/internal/edi/control-numbers/${environment}/${operation}`;
     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);
+            ? await getApiClient().get(path, { params: input })
+            : await getApiClient().post(path, input);
         return response.data;
     }
     catch (error) {
-        return unwrapControlNumberError(error);
+        return unwrapControlNumberError(error, true);
     }
 }
 /**
  * Get the next control number for an EDI counter.
  *
- * Calls the API-hosted Restate counter object which persists state
- * and handles rollover (999999999 → 1) automatically.
+ * The centralized service isolates counters by Temper environment.
+ * It rolls 999999999 over to 1.
  *
  * @param counterName - Counter type: 'ISA13' or 'GS06'
  * @param senderId - Sender qualifier + ID (e.g. "ZZ:SENDER123")
@@ -157,22 +163,29 @@ async function getNextControlNumber(counterName, senderId, receiverId, maxDigits
  * Get the current control number value without incrementing.
  */
 /** @public */
-async function getCurrentControlNumber(counterName, senderId, receiverId, maxDigits = 9, options) {
+async function getCurrentControlNumber(counterName, senderId, receiverId, maxDigits = 9) {
     const data = await requestControlNumber('count', {
         tradingPartnerKey: `${senderId}:${receiverId}`,
         counterName,
-    }, options?.environment);
+    });
     return String(data.value).padStart(maxDigits, '0');
 }
 /**
- * Set a control number to a specific value before the counter starts (for migration/seeding).
+ * Set the last-used production control number through the legacy endpoint.
+ *
+ * Use the Builder agent `set_edi_control_number` tool for per-environment seeding.
  */
 /** @public */
-async function setControlNumber(counterName, senderId, receiverId, value, maxDigits = 9, options) {
-    const data = await requestControlNumber('set', {
-        tradingPartnerKey: `${senderId}:${receiverId}`,
-        counterName,
-        value,
-    }, options?.environment);
-    return String(data.value).padStart(maxDigits, '0');
+async function setControlNumber(counterName, senderId, receiverId, value, maxDigits = 9) {
+    try {
+        const { data } = await getApiClient().post('/api/v2/internal/edi/control-numbers/set', {
+            tradingPartnerKey: `${senderId}:${receiverId}`,
+            counterName,
+            value,
+        });
+        return String(data.value).padStart(maxDigits, '0');
+    }
+    catch (error) {
+        return unwrapControlNumberError(error);
+    }
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { X12Interchange } from './edination-client';
-export type { ControlNumberCounterName, ControlNumberEnvironmentOptions, ControlNumberErrorCode, } from './control-numbers';
+import { 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';
 interface UnnboundErrorOptions<C extends string = string> extends ErrorOptions {
@@ -14,7 +14,7 @@ export type TemperEdiClientErrorCode = 'edi_read_error' | 'edi_write_error' | 'e
 export declare class TemperEdiClientError extends UnnboundError<TemperEdiClientErrorCode> {
     constructor({ message, code, ...o }: UnnboundErrorOptions<TemperEdiClientErrorCode>);
 }
-export declare const isTemperEdiClientError: (error: unknown) => error is TemperEdiClientError;
+export declare const isTemperEdiClientError: (error: ErrorOptions['cause']) => error is TemperEdiClientError;
 /**
  * A retryable failure that does not indicate an invalid EDI document.
  */
@@ -22,7 +22,7 @@ export declare class EdiInfrastructureError extends UnnboundError<'infrastructur
     readonly retryable = true;
     constructor({ message, ...o }: Omit<UnnboundErrorOptions<'infrastructure_error'>, 'code'>);
 }
-export declare const isEdiInfrastructureError: (error: unknown) => error is EdiInfrastructureError;
+export declare const isEdiInfrastructureError: (error: ErrorOptions['cause']) => error is EdiInfrastructureError;
 export interface FromX12Options {
     input: unknown;
 }
@@ -43,12 +43,12 @@ export declare class TemperEdiClient {
     fromX12({ input }: FromX12Options): Promise<X12Interchange[]>;
     /**
      * 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.
+     * Uses the centralized per-environment service for atomic partner sequencing.
      * ST02 is always "0001" (one transaction per file per ticket).
      * Zero-filled values from acknowledgment generation are placeholders, not manual overrides.
      */
     private stampControlNumbers;
-    toX12({ input }: ToX12Options): Promise<unknown>;
+    toX12({ input }: ToX12Options): Promise<File>;
     validateX12({ input }: ValidateX12Options): Promise<import("./edination-client").OperationResult>;
     acknowledgeX12({ input }: AcknolwedgeX12Options): Promise<X12Interchange[]>;
 }

package/dist/index.js

@@ -118,12 +118,13 @@ class TemperEdiClient {
                 });
             // Gateway normalises EdiFabric's camelCase to PascalCase before forwarding
             const responseData = error.response?.data;
-            const details = typeof responseData === 'object' &&
-                responseData !== null &&
+            let details;
+            if (responseData instanceof Object &&
                 'Details' in responseData &&
-                Array.isArray(responseData.Details)
-                ? responseData.Details
-                : undefined;
+                Array.isArray(responseData.Details) &&
+                responseData.Details.every((detail) => String(detail) === detail)) {
+                details = responseData.Details.map(String);
+            }
             if (status === 400 && details?.length) {
                 throw new TemperEdiClientError({
                     message: `EDI validation failed: ${details.join('; ')}`,
@@ -143,6 +144,7 @@ class TemperEdiClient {
     }
     fromX12({ input }) {
         return (0, unnbound_logger_sdk_1.startSpan)('X12 to JSON', () => {
+            // SAFETY: generated client accepts File; Buffer/Blob inputs are valid File-like bodies
             return this.X12.x12ReadPost({ body: input })
                 .then(this.unwrap.bind(this))
                 .catch((error) => this.unwrapError(error, 'edi_read_error'));
@@ -150,7 +152,7 @@ class TemperEdiClient {
     }
     /**
      * 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.
+     * Uses the centralized per-environment service for atomic partner sequencing.
      * ST02 is always "0001" (one transaction per file per ticket).
      * Zero-filled values from acknowledgment generation are placeholders, not manual overrides.
      */
@@ -199,12 +201,11 @@ class TemperEdiClient {
         }
     }
     async toX12({ input }) {
+        // Auto-stamp control numbers before writing X12
         try {
             await this.stampControlNumbers(input);
         }
         catch (error) {
-            if (error instanceof control_numbers_1.ControlNumberError)
-                throw error;
             // Workflows can still serialize documents whose control numbers were set manually.
             unnbound_logger_sdk_1.logger.warn({ err: error }, '[EDI SDK] Failed to auto-stamp control numbers, proceeding without');
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ontemper/edi",
   "description": "An EDI client with structured logging.",
-  "version": "1.2.0-beta.3",
+  "version": "1.2.0-beta.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",
@@ -16,12 +16,13 @@
   },
   "dependencies": {
     "axios": "1.18.0",
-    "unnbound-logger-sdk": "3.0.37"
+    "unnbound-logger-sdk": "3.1.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
     "@types/node": "^24.12.2",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.15",
+    "zod": "3.25.76"
   },
   "files": [
     "examples/*",