@ontemper/edi 1.1.0

package/dist/edination-client/model/ung.d.ts

@@ -0,0 +1,70 @@
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { S004 } from './s004';
+import type { S006 } from './s006';
+import type { S007 } from './s007';
+import type { S008 } from './s008';
+/**
+ *
+ * @export
+ * @interface UNG
+ */
+export interface UNG {
+    /**
+     *
+     * @type {string}
+     * @memberof UNG
+     */
+    MessageGroupIdentification_1?: string | null;
+    /**
+     *
+     * @type {S006}
+     * @memberof UNG
+     */
+    APPLICATIONSENDERIDENTIFICATION_2?: S006;
+    /**
+     *
+     * @type {S007}
+     * @memberof UNG
+     */
+    APPLICATIONRECIPIENTIDENTIFICATION_3?: S007;
+    /**
+     *
+     * @type {S004}
+     * @memberof UNG
+     */
+    DATEANDTIMEOFPREPARATION_4?: S004;
+    /**
+     *
+     * @type {string}
+     * @memberof UNG
+     */
+    GroupReferenceNumber_5?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof UNG
+     */
+    ControllingAgency_6?: string | null;
+    /**
+     *
+     * @type {S008}
+     * @memberof UNG
+     */
+    MESSAGEVERSION_7?: S008;
+    /**
+     *
+     * @type {string}
+     * @memberof UNG
+     */
+    ApplicationPassword_8?: string | null;
+}

package/dist/edination-client/model/ung.js

@@ -0,0 +1,15 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/edination-client/model/unz.d.ts

@@ -0,0 +1,30 @@
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ *
+ * @export
+ * @interface UNZ
+ */
+export interface UNZ {
+    /**
+     *
+     * @type {string}
+     * @memberof UNZ
+     */
+    InterchangeControlCount_1?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof UNZ
+     */
+    InterchangeControlReference_2?: string | null;
+}

package/dist/edination-client/model/unz.js

@@ -0,0 +1,15 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/edination-client/model/x12-group.d.ts

@@ -0,0 +1,38 @@
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { GE } from './ge';
+import type { GS } from './gs';
+/**
+ *
+ * @export
+ * @interface X12Group
+ */
+export interface X12Group {
+    /**
+     *
+     * @type {GS}
+     * @memberof X12Group
+     */
+    GS: GS;
+    /**
+     *
+     * @type {Array<any>}
+     * @memberof X12Group
+     */
+    Transactions: Array<any>;
+    /**
+     *
+     * @type {Array<GE>}
+     * @memberof X12Group
+     */
+    GETrailers?: Array<GE> | null;
+}

package/dist/edination-client/model/x12-group.js

@@ -0,0 +1,15 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/edination-client/model/x12-interchange.d.ts

@@ -0,0 +1,65 @@
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { IEA } from './iea';
+import type { ISA } from './isa';
+import type { OperationResult } from './operation-result';
+import type { TA1 } from './ta1';
+import type { X12Group } from './x12-group';
+/**
+ *
+ * @export
+ * @interface X12Interchange
+ */
+export interface X12Interchange {
+    /**
+     *
+     * @type {string}
+     * @memberof X12Interchange
+     */
+    SegmentDelimiter: string;
+    /**
+     *
+     * @type {string}
+     * @memberof X12Interchange
+     */
+    DataElementDelimiter: string;
+    /**
+     *
+     * @type {ISA}
+     * @memberof X12Interchange
+     */
+    ISA: ISA;
+    /**
+     *
+     * @type {TA1}
+     * @memberof X12Interchange
+     */
+    TA1?: TA1;
+    /**
+     *
+     * @type {Array<X12Group>}
+     * @memberof X12Interchange
+     */
+    Groups: Array<X12Group>;
+    /**
+     *
+     * @type {Array<IEA>}
+     * @memberof X12Interchange
+     */
+    IEATrailers?: Array<IEA> | null;
+    /**
+     *
+     * @type {OperationResult}
+     * @memberof X12Interchange
+     */
+    Result?: OperationResult;
+}

package/dist/edination-client/model/x12-interchange.js

@@ -0,0 +1,15 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * EdiNation API
+ * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+ *
+ * The version of the OpenAPI document: 2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { type X12Interchange } from './edination-client';
+export * from './edination-client/model';
+export { getNextControlNumber, getCurrentControlNumber, setControlNumber } from './control-numbers';
+interface UnnboundErrorOptions<C extends string = string> extends ErrorOptions {
+    message: string;
+    code: C;
+}
+declare class UnnboundError<C extends string = string> extends Error {
+    code: C;
+    constructor({ message, code, ...o }: UnnboundErrorOptions<C>);
+}
+export type UnnboundEdiClientErrorCode = 'edi_read_error' | 'edi_write_error' | 'edi_validate_error' | 'edi_acknowledge_error' | 'edi_unauthorized_error' | 'edi_unknown_error';
+export declare class UnnboundEdiClientError extends UnnboundError<UnnboundEdiClientErrorCode> {
+    constructor({ message, code, ...o }: UnnboundErrorOptions<UnnboundEdiClientErrorCode>);
+}
+export declare const isUnnboundEdiClientError: (error: unknown) => error is UnnboundEdiClientError;
+export interface FromX12Options {
+    input: unknown;
+}
+export interface ToX12Options {
+    input: X12Interchange;
+}
+export interface ValidateX12Options {
+    input: X12Interchange;
+}
+export interface AcknolwedgeX12Options {
+    input: X12Interchange;
+}
+export declare class UnnboundEdiClient {
+    private X12;
+    constructor();
+    private unwrap;
+    private unwrapError;
+    fromX12({ input }: FromX12Options): Promise<X12Interchange[]>;
+    /**
+     * Stamp ISA13/GS06 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).
+     */
+    private stampControlNumbers;
+    toX12({ input }: ToX12Options): Promise<unknown>;
+    validateX12({ input }: ValidateX12Options): Promise<import("./edination-client").OperationResult>;
+    acknowledgeX12({ input }: AcknolwedgeX12Options): Promise<X12Interchange[]>;
+}

package/dist/index.js

@@ -0,0 +1,197 @@
+"use strict";
+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;
+    };
+})();
+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.UnnboundEdiClient = exports.isUnnboundEdiClientError = exports.UnnboundEdiClientError = exports.setControlNumber = exports.getCurrentControlNumber = exports.getNextControlNumber = 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");
+__exportStar(require("./edination-client/model"), exports);
+var control_numbers_1 = require("./control-numbers");
+Object.defineProperty(exports, "getNextControlNumber", { enumerable: true, get: function () { return control_numbers_1.getNextControlNumber; } });
+Object.defineProperty(exports, "getCurrentControlNumber", { enumerable: true, get: function () { return control_numbers_1.getCurrentControlNumber; } });
+Object.defineProperty(exports, "setControlNumber", { enumerable: true, get: function () { return control_numbers_1.setControlNumber; } });
+class UnnboundError extends Error {
+    code;
+    constructor({ message, code, ...o }) {
+        super(message, o);
+        this.name = 'UnnboundError';
+        this.code = code;
+    }
+}
+class UnnboundEdiClientError extends UnnboundError {
+    constructor({ message, code, ...o }) {
+        super({ message, code, ...o });
+        this.name = 'UnnboundEdiClientError';
+    }
+}
+exports.UnnboundEdiClientError = UnnboundEdiClientError;
+const isUnnboundEdiClientError = (error) => error instanceof UnnboundEdiClientError;
+exports.isUnnboundEdiClientError = isUnnboundEdiClientError;
+const buildEdiPayload = (edi) => ({ type: 'edi', edi });
+const buildEdiX12Payload = (operation, x12) => buildEdiPayload({ operation, type: 'x12', x12 });
+class UnnboundEdiClient {
+    X12;
+    constructor() {
+        const apiKey = process.env.UNNBOUND_EDI_API_KEY;
+        // When UNNBOUND_EDI_BASE_URL is set, use self-hosted EdiFabric InHouse API
+        // instead of the EDINation cloud API (eliminates 300 calls/min shared rate limit)
+        const basePath = process.env.UNNBOUND_EDI_BASE_URL || undefined;
+        if (!basePath && !apiKey) {
+            throw new Error('EDI service not configured. Set UNNBOUND_EDI_BASE_URL (self-hosted) or UNNBOUND_EDI_API_KEY (EDINation cloud).');
+        }
+        // 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);
+    }
+    unwrap(response) {
+        return response.data;
+    }
+    unwrapError(error, code) {
+        if (error instanceof UnnboundEdiClientError)
+            throw error;
+        if ((0, axios_1.isAxiosError)(error)) {
+            if (error.status === 403)
+                throw new UnnboundEdiClientError({
+                    message: 'Unauthorized access to EDI service. Reach out to support.',
+                    code: 'edi_unauthorized_error',
+                });
+            throw new UnnboundEdiClientError({ message: error.message, code, cause: error });
+        }
+        if (error instanceof Error)
+            throw new UnnboundEdiClientError({
+                message: error.message,
+                code: 'edi_unknown_error',
+                cause: error,
+            });
+        throw new UnnboundEdiClientError({
+            message: 'Unknown error occured in EDI client.',
+            code: 'edi_unknown_error',
+            cause: error,
+        });
+    }
+    fromX12({ input }) {
+        return (0, unnbound_logger_sdk_1.startSpan)('X12 to JSON', () => {
+            return this.X12.x12ReadPost({ body: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_read_error'));
+        }, (o) => buildEdiX12Payload('fromX12', { input, output: o?.result }));
+    }
+    /**
+     * Stamp ISA13/GS06 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).
+     */
+    async stampControlNumbers(input) {
+        const { getNextControlNumber } = await Promise.resolve().then(() => __importStar(require('./control-numbers')));
+        const isa = input.ISA;
+        const senderQual = (isa.SenderIDQualifier_5 || '').trim();
+        const senderId = (isa.InterchangeSenderID_6 || '').trim();
+        const receiverQual = (isa.ReceiverIDQualifier_7 || '').trim();
+        const receiverId = (isa.InterchangeReceiverID_8 || '').trim();
+        const senderKey = `${senderQual}:${senderId}`;
+        const receiverKey = `${receiverQual}:${receiverId}`;
+        // ISA13 — interchange control number (9 digits, zero-padded)
+        if (!isa.InterchangeControlNumber_13) {
+            const isa13 = await getNextControlNumber('ISA13', senderKey, receiverKey, 9);
+            isa.InterchangeControlNumber_13 = isa13;
+            // IEA02 must match ISA13
+            if (input.IEATrailers?.length) {
+                input.IEATrailers[0].InterchangeControlNumber_2 = isa13;
+            }
+        }
+        // GS06 — functional group control number (per group)
+        for (const group of input.Groups) {
+            if (!group.GS.GroupControlNumber_6) {
+                const gs06 = await getNextControlNumber('GS06', senderKey, receiverKey, 9);
+                group.GS.GroupControlNumber_6 = gs06;
+                // GE02 must match GS06
+                if (group.GETrailers?.length) {
+                    group.GETrailers[0].GroupControlNumber_2 = gs06;
+                }
+            }
+        }
+        // ST02 — always "0001" (one transaction per file, no persistence needed)
+        for (const group of input.Groups) {
+            for (const tx of group.Transactions) {
+                if (tx?.ST?.TransactionSetControlNumber_2 === undefined || tx?.ST?.TransactionSetControlNumber_2 === null) {
+                    if (tx?.ST)
+                        tx.ST.TransactionSetControlNumber_2 = '0001';
+                    if (tx?.SE)
+                        tx.SE.TransactionSetControlNumber_2 = '0001';
+                }
+            }
+        }
+    }
+    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
+            console.warn('[EDI SDK] Failed to auto-stamp control numbers, proceeding without:', error);
+        }
+        return (0, unnbound_logger_sdk_1.startSpan)('JSON to X12', () => {
+            return this.X12.x12WritePost({ x12Interchange: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_write_error'));
+        }, (o) => buildEdiX12Payload('toX12', { input, output: o?.result }));
+    }
+    validateX12({ input }) {
+        return (0, unnbound_logger_sdk_1.startSpan)('Validate X12', () => {
+            return this.X12.x12ValidatePost({ x12Interchange: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_validate_error'));
+        }, (o) => ({
+            ...buildEdiX12Payload('validateX12', { input, output: o?.result }),
+            ...(o?.result?.Status === 'error' && { level: 'warn' }),
+        }));
+    }
+    acknowledgeX12({ input }) {
+        return (0, unnbound_logger_sdk_1.startSpan)('Acknolwedge X12', () => {
+            return this.X12.x12AckPost({ x12Interchange: input })
+                .then(this.unwrap.bind(this))
+                .catch((error) => this.unwrapError(error, 'edi_acknowledge_error'));
+        }, (o) => buildEdiX12Payload('acknowledgeX12', { input, output: o?.result }));
+    }
+}
+exports.UnnboundEdiClient = UnnboundEdiClient;

package/examples/node-edi.ts

@@ -0,0 +1,58 @@
+import { logger } from 'unnbound-logger-sdk';
+
+import { UnnboundEdiClient } from '../src';
+
+const run = async () => {
+  const edi = new UnnboundEdiClient();
+
+  const data = `ISA*00*          *00*          *12*NOTP           *12*NOTP           *080501*1700*U*00401*000001000*0*P*>
+GS*PO*NOTP*NOTP*20080501*1700*1000*X*004010
+ST*850*000000010
+BEG*00*SA*08292243254**20010501*610385388
+REF*DP*030
+REF*PS*
+ITD*14*3*2**45**46
+DTM*001*20010510
+PKG*F*68***PALLET, SHRINKWRAP 48W X 40D X 45H
+PKG*F*66***REGULAR
+TD5*A*92*P3**SEE ROUTING GUIDE FOR ROUTING
+N1*ST*RETAIL STORE*9*0001234567890
+N3*123 ANYWHERE AVENUE
+N4*CITY*ST*12345
+PO1*1*120*EA*9.25*TE*CB*(12) 0-083628-838*PR*RO*VN*ABA18783
+PO1*2*220*EA*13.7 9*TE*CB*(69) 0-093 83 7-991*PR*RO*VN*RUP83112
+PO1*3*126*EA*10.9 9*TE*CB*(71) 0-099172-837*PR*RO*VN*CPR19293
+PO1*4*76*EA*4.35*TE*CB*(71) 0-012110-737*PR*RO*VN*PIW28173
+PO1*5*72*EA*7.5*TE*CB*(71) 0-0848 88-9 75*PR*RO*VN*JBM1938 7
+PO1*6*696*EA*9.55*TE*CB*(71) 0-003 922-121*PR*RO*VN*IUI19283
+CTT*6
+SE*20*000000010
+GE*1*1000
+IEA*1*000001000`;
+
+  const x12Interchanges = await edi.fromX12({ input: data });
+
+  logger.info({ x12Interchanges: x12Interchanges.length }, 'Input parsed.');
+
+  await Promise.all(
+    x12Interchanges.map(async (x12Interchange) => {
+      const validated = await edi.validateX12({ input: x12Interchange });
+
+      logger.info({ validated }, 'X12 validated.');
+
+      const x12 = await edi.toX12({ input: x12Interchange });
+
+      logger.info({ x12 }, 'X12 unparsed.');
+
+      logger.info({ validated }, 'X12 validated.');
+
+      const acknowledged = await edi.acknowledgeX12({ input: x12Interchange });
+
+      logger.info({ acknowledged }, 'X12 acknowledged.');
+    }),
+  );
+};
+
+run()
+  .then(() => logger.info('Done'))
+  .catch((error) => logger.error({ err: error }, 'Error'));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ontemper/edi",
+  "description": "An EDI client with structured logging.",
+  "version": "1.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo 'No tests'",
+    "typecheck": "tsc -noEmit",
+    "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
+    "lint:fix": "bun run lint --fix",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "prepublishOnly": "bun run build",
+    "start:example": "bun --watch examples/node-edi.ts",
+    "version:bump": "npm version patch",
+    "release": "bun run build && bun publish --access public",
+    "codegen": "npx --yes @openapitools/openapi-generator-cli generate -c openapitools.json -o ./src/edination-client"
+  },
+  "author": "Unnbound Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnbounddev/unnbound-sdks.git"
+  },
+  "homepage": "https://github.com/unnbounddev/unnbound-sdks#readme",
+  "bugs": {
+    "url": "https://github.com/unnbounddev/unnbound-sdks/issues"
+  },
+  "dependencies": {
+    "axios": "^1.12.2",
+    "unnbound-logger-sdk": "3.0.35"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22"
+  },
+  "files": [
+    "examples/*",
+    "dist/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false
+}