@envoy/envoy-integrations-sdk 2.4.3 → 2.5.0

package/dist/base/EnvoyAPI.d.ts

@@ -3,6 +3,21 @@ import JSONAPIData from '../util/json-api/JSONAPIData';
 interface EnvoyWebDataLoaderKey extends JSONAPIData {
     include?: string;
 }
+/**
+ * Options for configuring EnvoyAPI client
+ */
+export interface EnvoyAPIOptions {
+    /** Access token for authentication */
+    accessToken: string;
+    /**
+     * Custom application identifier appended to User-Agent header.
+     * Format: "AppName/Version"
+     * Example: "MyCompanyApp/1.0.0"
+     *
+     * This identifier helps track API usage by application and aids in debugging.
+     */
+    userAgent?: string;
+}
 /**
  * Make typed API calls to Envoy.
  * Uses a data loader to leverage JSONAPI's "include" functionality.
@@ -14,6 +29,7 @@ interface EnvoyWebDataLoaderKey extends JSONAPIData {
 export default class EnvoyAPI {
     /**
      * HTTP Client with Envoy's defaults.
+     * User-Agent headers are set in the constructor after client instantiation.
      */
     readonly axios: import("axios").AxiosInstance;
     /**
@@ -22,7 +38,24 @@ export default class EnvoyAPI {
      * unless they exist in cache (which they usually will).
      */
     protected readonly dataLoader: DataLoader<EnvoyWebDataLoaderKey, any, string>;
-    constructor(accessToken: string);
+    /**
+     * Create an EnvoyAPI client instance
+     *
+     * @param options - Either an access token string or an EnvoyAPIOptions object
+     *                  with accessToken and optional userAgent
+     *
+     * @example
+     * // Simple usage with access token only
+     * const client = new EnvoyAPI('access-token-here');
+     *
+     * @example
+     * // Usage with custom User-Agent for tracking and debugging
+     * const client = new EnvoyAPI({
+     *   accessToken: 'access-token-here',
+     *   userAgent: 'MyApp/1.0.0'
+     * });
+     */
+    constructor(options: EnvoyAPIOptions | string);
 }
 export {};
 //# sourceMappingURL=EnvoyAPI.d.ts.map

package/dist/base/EnvoyAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnvoyAPI.d.ts","sourceRoot":"","sources":["../../src/base/EnvoyAPI.ts"],"names":[],"mappings":"AACA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,WAAW,MAAM,8BAA8B,CAAC;AAKvD,UAAU,qBAAsB,SAAQ,WAAW;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,QAAQ;IAC3B;;OAEG;IACH,QAAQ,CAAC,KAAK,gCAWX;IAEH;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,iDAW3B;gBAEU,WAAW,EAAE,MAAM;CA2BhC"}
+{"version":3,"file":"EnvoyAPI.d.ts","sourceRoot":"","sources":["../../src/base/EnvoyAPI.ts"],"names":[],"mappings":"AACA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,WAAW,MAAM,8BAA8B,CAAC;AAMvD,UAAU,qBAAsB,SAAQ,WAAW;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,QAAQ;IAC3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,gCAWX;IAEH;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,iDAW3B;IAEF;;;;;;;;;;;;;;;;OAgBG;gBACS,OAAO,EAAE,eAAe,GAAG,MAAM;CAqD9C"}

package/dist/base/EnvoyAPI.js

@@ -44,6 +44,7 @@ var dataloader_1 = __importDefault(require("dataloader"));
 var constants_1 = require("../constants");
 var axiosConstructor_1 = require("../util/axiosConstructor");
 var errorHandling_1 = require("../util/errorHandling");
+var userAgent_1 = require("../util/userAgent");
 /**
  * Sometimes envoy-web will give us back some relationship data
  * with the "type" set to the relationships name instead of the actual model's name.
@@ -59,10 +60,28 @@ var TYPE_ALIASES = new Map([['employee-screening-flows', 'flows']]);
  * @category Base
  */
 var EnvoyAPI = /** @class */ (function () {
-    function EnvoyAPI(accessToken) {
+    /**
+     * Create an EnvoyAPI client instance
+     *
+     * @param options - Either an access token string or an EnvoyAPIOptions object
+     *                  with accessToken and optional userAgent
+     *
+     * @example
+     * // Simple usage with access token only
+     * const client = new EnvoyAPI('access-token-here');
+     *
+     * @example
+     * // Usage with custom User-Agent for tracking and debugging
+     * const client = new EnvoyAPI({
+     *   accessToken: 'access-token-here',
+     *   userAgent: 'MyApp/1.0.0'
+     * });
+     */
+    function EnvoyAPI(options) {
         var _this = this;
         /**
          * HTTP Client with Envoy's defaults.
+         * User-Agent headers are set in the constructor after client instantiation.
          */
         this.axios = axiosConstructor_1.createAxiosClient({
             baseURL: constants_1.envoyBaseURL,
@@ -100,7 +119,32 @@ var EnvoyAPI = /** @class */ (function () {
         }, {
             cacheKeyFn: function (key) { return key.type + "_" + key.id; },
         });
+        // Support both string and options object formats
+        var _a = typeof options === 'string'
+            ? { accessToken: options, userAgent: undefined }
+            : options, accessToken = _a.accessToken, userAgent = _a.userAgent;
+        // Set authorization header (critical - must succeed)
         this.axios.defaults.headers.authorization = "Bearer " + accessToken;
+        // Set User-Agent headers with absolute guarantee that failures won't break SDK
+        // GUARANTEE: This block will NEVER throw an exception, no matter what happens
+        // User-Agent headers are telemetry/debugging aids, not critical for SDK functionality
+        try {
+            // Primary attempt: Use full header generation functions
+            this.axios.defaults.headers['User-Agent'] = userAgent_1.buildUserAgent(userAgent);
+            this.axios.defaults.headers['X-Envoy-Client-Info'] = userAgent_1.buildClientInfoHeader(userAgent);
+        }
+        catch (error) {
+            // Secondary fallback: Set minimal valid headers
+            try {
+                this.axios.defaults.headers['User-Agent'] = 'envoy-integrations-sdk/unknown';
+                this.axios.defaults.headers['X-Envoy-Client-Info'] = '{"sdk":"envoy-integrations-sdk"}';
+            }
+            catch (fallbackError) {
+                // Tertiary fallback: Even setting minimal headers failed
+                // Continue without User-Agent headers - SDK remains fully functional
+                // This catch ensures absolute guarantee that SDK initialization succeeds
+            }
+        }
         /**
          * Saves every model that was "include"ed in the response,
          * which saves us the trouble of fetching related data.

package/dist/index.d.ts

@@ -51,5 +51,6 @@ export * from './sdk/middleware';
 export * from './util/EnvoySignatureVerifier';
 export * from './util/axiosConstructor';
 export * from './util/errorHandling';
+export type { EnvoyAPIOptions } from './base/EnvoyAPI';
 export { EntryPayload, InvitePayload, EnvoyJWT, EnvoyMeta, EnvoyPluginJob, EnvoyPluginJobMock, EnvoyPluginSDK, EnvoyPluginStorage, EnvoyPluginStoragePipeline, EnvoyPluginStoragePipelineMock, EnvoyRequest, EnvoyResponse, EnvoySignatureVerifier, EnvoyStorageItem, EnvoyPluginAPI, EnvoyUserAPI, EnvoyValidationRouteResponseBody, JSONAPIData, JSONAPIResponse, HttpStatus, entryEventBodyFactory, eventBodyFactory, inviteEventBodyFactory, routeBodyFactory, };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAErB,OAAO,0BAA0B,MAAM,mCAAmC,CAAC;AAE3E,OAAO,qBAAqB,MAAM,mCAAmC,CAAC;AACtE,OAAO,gBAAgB,MAAM,8BAA8B,CAAC;AAC5D,OAAO,sBAAsB,MAAM,oCAAoC,CAAC;AACxE,OAAO,gBAAgB,MAAM,8BAA8B,CAAC;AAE5D,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAE/C,OAAO,kBAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,8BAA8B,MAAM,wCAAwC,CAAC;AAEpF,OAAO,YAAY,MAAM,yBAAyB,CAAC;AACnD,OAAO,aAAa,MAAM,0BAA0B,CAAC;AAErD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AACxC,OAAO,cAAc,MAAM,sBAAsB,CAAC;AAClD,OAAO,cAAc,MAAM,sBAAsB,CAAC;AAClD,OAAO,kBAAkB,MAAM,0BAA0B,CAAC;AAC1D,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,aAAa,MAAM,qBAAqB,CAAC;AAChD,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,cAAc,MAAM,sBAAsB,CAAC;AAClD,OAAO,gCAAgC,MAAM,wCAAwC,CAAC;AAEtF,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,sBAAsB,MAAM,+BAA+B,CAAC;AACnE,OAAO,WAAW,MAAM,6BAA6B,CAAC;AACtD,OAAO,eAAe,MAAM,iCAAiC,CAAC;AAE9D,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,0BAA0B,CAAC;AAEzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AAEjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AAErC,OAAO,EACL,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,YAAY,EACZ,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,gCAAgC,EAChC,WAAW,EACX,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAErB,OAAO,0BAA0B,MAAM,mCAAmC,CAAC;AAE3E,OAAO,qBAAqB,MAAM,mCAAmC,CAAC;AACtE,OAAO,gBAAgB,MAAM,8BAA8B,CAAC;AAC5D,OAAO,sBAAsB,MAAM,oCAAoC,CAAC;AACxE,OAAO,gBAAgB,MAAM,8BAA8B,CAAC;AAE5D,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAE/C,OAAO,kBAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,8BAA8B,MAAM,wCAAwC,CAAC;AAEpF,OAAO,YAAY,MAAM,yBAAyB,CAAC;AACnD,OAAO,aAAa,MAAM,0BAA0B,CAAC;AAErD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AACxC,OAAO,cAAc,MAAM,sBAAsB,CAAC;AAClD,OAAO,cAAc,MAAM,sBAAsB,CAAC;AAClD,OAAO,kBAAkB,MAAM,0BAA0B,CAAC;AAC1D,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,aAAa,MAAM,qBAAqB,CAAC;AAChD,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,cAAc,MAAM,sBAAsB,CAAC;AAClD,OAAO,gCAAgC,MAAM,wCAAwC,CAAC;AAEtF,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,sBAAsB,MAAM,+BAA+B,CAAC;AACnE,OAAO,WAAW,MAAM,6BAA6B,CAAC;AACtD,OAAO,eAAe,MAAM,iCAAiC,CAAC;AAE9D,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,0BAA0B,CAAC;AAEzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AAEjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AAErC,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,YAAY,EACZ,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,gCAAgC,EAChC,WAAW,EACX,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,CAAC"}

package/dist/internal/EnvoyOptionsRouteParams.d.ts

@@ -2,6 +2,10 @@ declare type EnvoyOptionsRouteParams = {
     search?: string;
     page?: number;
     cursor?: string;
+    zone_id?: string;
+    location_id?: string;
+    /** ID of selected option when this is a mapped field. */
+    parent_resource_id?: string;
 };
 export default EnvoyOptionsRouteParams;
 //# sourceMappingURL=EnvoyOptionsRouteParams.d.ts.map

package/dist/internal/EnvoyOptionsRouteParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnvoyOptionsRouteParams.d.ts","sourceRoot":"","sources":["../../src/internal/EnvoyOptionsRouteParams.ts"],"names":[],"mappings":"AAAA,aAAK,uBAAuB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAe,uBAAuB,CAAC"}
+{"version":3,"file":"EnvoyOptionsRouteParams.d.ts","sourceRoot":"","sources":["../../src/internal/EnvoyOptionsRouteParams.ts"],"names":[],"mappings":"AAAA,aAAK,uBAAuB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,eAAe,uBAAuB,CAAC"}

package/dist/util/userAgent.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Client information for detailed telemetry
+ */
+export interface ClientInfo {
+    /** SDK name */
+    sdk: string;
+    /** SDK version */
+    version: string;
+    /** Runtime (e.g., 'node') */
+    runtime: string;
+    /** Runtime version (e.g., '18.0.0') */
+    runtimeVersion: string;
+    /** Operating system platform */
+    platform: string;
+    /** Optional custom application identifier (e.g., 'MyApp/1.0.0') */
+    application?: string;
+}
+/**
+ * Build standard User-Agent header value
+ * Format: envoy-integrations-sdk/2.4.4 node/18.0.0
+ * With custom app: envoy-integrations-sdk/2.4.4 node/18.0.0 MyApp/1.0.0
+ *
+ * This function is designed to never throw exceptions. If any error occurs,
+ * it returns a safe fallback value to ensure SDK initialization succeeds.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns User-Agent header value (never throws)
+ */
+export declare function buildUserAgent(customUserAgent?: string): string;
+/**
+ * Build detailed client info for X-Envoy-Client-Info header
+ *
+ * This function is designed to never throw exceptions. If any error occurs
+ * during info collection, it uses safe fallback values.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns ClientInfo object (never throws)
+ */
+export declare function buildClientInfo(customUserAgent?: string): ClientInfo;
+/**
+ * Build X-Envoy-Client-Info header value (JSON string)
+ *
+ * This function is designed to never throw exceptions. If JSON serialization
+ * fails, it returns a minimal safe JSON string.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns JSON string for X-Envoy-Client-Info header (never throws)
+ */
+export declare function buildClientInfoHeader(customUserAgent?: string): string;
+//# sourceMappingURL=userAgent.d.ts.map

package/dist/util/userAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userAgent.d.ts","sourceRoot":"","sources":["../../src/util/userAgent.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8BD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,UAAU,CA8BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAUtE"}

package/dist/util/userAgent.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildClientInfoHeader = exports.buildClientInfo = exports.buildUserAgent = void 0;
+var os_1 = __importDefault(require("os"));
+// Safe version extraction with fallback
+var version = 'unknown';
+try {
+    // Import version from package.json
+    // Note: In compiled code, this resolves correctly
+    version = require('../../package.json').version;
+}
+catch (_a) {
+    // If package.json can't be loaded, use fallback version
+    // This ensures SDK initialization never fails
+    // Silently fail - User-Agent is telemetry, not critical functionality
+}
+/**
+ * Safely get Node.js version, with fallback
+ * @returns Node.js version string without 'v' prefix
+ */
+function getNodeVersion() {
+    try {
+        if (process === null || process === void 0 ? void 0 : process.version) {
+            return process.version.replace('v', '');
+        }
+    }
+    catch (_a) {
+        // Ignore error, use fallback
+    }
+    return 'unknown';
+}
+/**
+ * Safely get platform information, with fallback
+ * @returns Platform string (e.g., 'darwin', 'linux', 'win32')
+ */
+function getPlatform() {
+    try {
+        return os_1.default.platform();
+    }
+    catch (_a) {
+        // If os.platform() fails, return fallback
+        return 'unknown';
+    }
+}
+/**
+ * Build standard User-Agent header value
+ * Format: envoy-integrations-sdk/2.4.4 node/18.0.0
+ * With custom app: envoy-integrations-sdk/2.4.4 node/18.0.0 MyApp/1.0.0
+ *
+ * This function is designed to never throw exceptions. If any error occurs,
+ * it returns a safe fallback value to ensure SDK initialization succeeds.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns User-Agent header value (never throws)
+ */
+function buildUserAgent(customUserAgent) {
+    try {
+        var nodeVersion = getNodeVersion();
+        var baseUA = "envoy-integrations-sdk/" + version + " node/" + nodeVersion;
+        return customUserAgent ? baseUA + " " + customUserAgent : baseUA;
+    }
+    catch (_a) {
+        // Critical fallback - should never happen, but ensures SDK always works
+        // Silently fail - User-Agent is telemetry, not critical functionality
+        return 'envoy-integrations-sdk/unknown node/unknown';
+    }
+}
+exports.buildUserAgent = buildUserAgent;
+/**
+ * Build detailed client info for X-Envoy-Client-Info header
+ *
+ * This function is designed to never throw exceptions. If any error occurs
+ * during info collection, it uses safe fallback values.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns ClientInfo object (never throws)
+ */
+function buildClientInfo(customUserAgent) {
+    try {
+        var nodeVersion = getNodeVersion();
+        var platform = getPlatform();
+        var clientInfo = {
+            sdk: 'envoy-integrations-sdk',
+            version: version,
+            runtime: 'node',
+            runtimeVersion: nodeVersion,
+            platform: platform,
+        };
+        // Only add application if it's a non-empty string
+        if (customUserAgent) {
+            clientInfo.application = customUserAgent;
+        }
+        return clientInfo;
+    }
+    catch (_a) {
+        // Critical fallback - return minimal safe info
+        // Silently fail - User-Agent is telemetry, not critical functionality
+        return {
+            sdk: 'envoy-integrations-sdk',
+            version: 'unknown',
+            runtime: 'node',
+            runtimeVersion: 'unknown',
+            platform: 'unknown',
+        };
+    }
+}
+exports.buildClientInfo = buildClientInfo;
+/**
+ * Build X-Envoy-Client-Info header value (JSON string)
+ *
+ * This function is designed to never throw exceptions. If JSON serialization
+ * fails, it returns a minimal safe JSON string.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns JSON string for X-Envoy-Client-Info header (never throws)
+ */
+function buildClientInfoHeader(customUserAgent) {
+    try {
+        var clientInfo = buildClientInfo(customUserAgent);
+        return JSON.stringify(clientInfo);
+    }
+    catch (_a) {
+        // Critical fallback - return minimal valid JSON
+        // Silently fail - User-Agent is telemetry, not critical functionality
+        // Return minimal valid JSON that won't break parsing
+        return '{"sdk":"envoy-integrations-sdk","version":"unknown","runtime":"node","runtimeVersion":"unknown","platform":"unknown"}';
+    }
+}
+exports.buildClientInfoHeader = buildClientInfoHeader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envoy/envoy-integrations-sdk",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "SDK for building Envoy integrations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/base/EnvoyAPI.ts

@@ -4,11 +4,28 @@ import JSONAPIData from '../util/json-api/JSONAPIData';
 import { envoyBaseURL } from '../constants';
 import { createAxiosClient } from '../util/axiosConstructor';
 import { EMPTY_STORAGE_ERROR_MESSAGE } from '../util/errorHandling';
+import { buildUserAgent, buildClientInfoHeader } from '../util/userAgent';
 
 interface EnvoyWebDataLoaderKey extends JSONAPIData {
   include?: string;
 }
 
+/**
+ * Options for configuring EnvoyAPI client
+ */
+export interface EnvoyAPIOptions {
+  /** Access token for authentication */
+  accessToken: string;
+  /**
+   * Custom application identifier appended to User-Agent header.
+   * Format: "AppName/Version"
+   * Example: "MyCompanyApp/1.0.0"
+   *
+   * This identifier helps track API usage by application and aids in debugging.
+   */
+  userAgent?: string;
+}
+
 /**
  * Sometimes envoy-web will give us back some relationship data
  * with the "type" set to the relationships name instead of the actual model's name.
@@ -27,6 +44,7 @@ const TYPE_ALIASES = new Map<string, string>([['employee-screening-flows', 'flow
 export default class EnvoyAPI {
   /**
    * HTTP Client with Envoy's defaults.
+   * User-Agent headers are set in the constructor after client instantiation.
    */
   readonly axios = createAxiosClient({
     baseURL: envoyBaseURL,
@@ -59,8 +77,51 @@ export default class EnvoyAPI {
     },
   );
 
-  constructor(accessToken: string) {
+  /**
+   * Create an EnvoyAPI client instance
+   *
+   * @param options - Either an access token string or an EnvoyAPIOptions object
+   *                  with accessToken and optional userAgent
+   *
+   * @example
+   * // Simple usage with access token only
+   * const client = new EnvoyAPI('access-token-here');
+   *
+   * @example
+   * // Usage with custom User-Agent for tracking and debugging
+   * const client = new EnvoyAPI({
+   *   accessToken: 'access-token-here',
+   *   userAgent: 'MyApp/1.0.0'
+   * });
+   */
+  constructor(options: EnvoyAPIOptions | string) {
+    // Support both string and options object formats
+    const { accessToken, userAgent } = typeof options === 'string'
+      ? { accessToken: options, userAgent: undefined }
+      : options;
+
+    // Set authorization header (critical - must succeed)
     this.axios.defaults.headers.authorization = `Bearer ${accessToken}`;
+
+    // Set User-Agent headers with absolute guarantee that failures won't break SDK
+    // GUARANTEE: This block will NEVER throw an exception, no matter what happens
+    // User-Agent headers are telemetry/debugging aids, not critical for SDK functionality
+    try {
+      // Primary attempt: Use full header generation functions
+      this.axios.defaults.headers['User-Agent'] = buildUserAgent(userAgent);
+      this.axios.defaults.headers['X-Envoy-Client-Info'] = buildClientInfoHeader(userAgent);
+    } catch (error) {
+      // Secondary fallback: Set minimal valid headers
+      try {
+        this.axios.defaults.headers['User-Agent'] = 'envoy-integrations-sdk/unknown';
+        this.axios.defaults.headers['X-Envoy-Client-Info'] = '{"sdk":"envoy-integrations-sdk"}';
+      } catch (fallbackError) {
+        // Tertiary fallback: Even setting minimal headers failed
+        // Continue without User-Agent headers - SDK remains fully functional
+        // This catch ensures absolute guarantee that SDK initialization succeeds
+      }
+    }
+
     /**
      * Saves every model that was "include"ed in the response,
      * which saves us the trouble of fetching related data.

package/src/index.ts

@@ -63,6 +63,8 @@ export * from './util/EnvoySignatureVerifier';
 export * from './util/axiosConstructor';
 export * from './util/errorHandling';
 
+export type { EnvoyAPIOptions } from './base/EnvoyAPI';
+
 export {
   EntryPayload,
   InvitePayload,

package/src/internal/EnvoyOptionsRouteParams.ts

@@ -2,6 +2,10 @@ type EnvoyOptionsRouteParams = {
   search?: string;
   page?: number;
   cursor?: string;
+  zone_id?: string;
+  location_id?: string;
+  /** ID of selected option when this is a mapped field. */
+  parent_resource_id?: string;
 };
 
 export default EnvoyOptionsRouteParams;

package/src/util/userAgent.ts

@@ -0,0 +1,144 @@
+import os from 'os';
+
+// Safe version extraction with fallback
+let version = 'unknown';
+try {
+  // Import version from package.json
+  // Note: In compiled code, this resolves correctly
+  version = require('../../package.json').version;
+} catch {
+  // If package.json can't be loaded, use fallback version
+  // This ensures SDK initialization never fails
+  // Silently fail - User-Agent is telemetry, not critical functionality
+}
+
+/**
+ * Client information for detailed telemetry
+ */
+export interface ClientInfo {
+  /** SDK name */
+  sdk: string;
+  /** SDK version */
+  version: string;
+  /** Runtime (e.g., 'node') */
+  runtime: string;
+  /** Runtime version (e.g., '18.0.0') */
+  runtimeVersion: string;
+  /** Operating system platform */
+  platform: string;
+  /** Optional custom application identifier (e.g., 'MyApp/1.0.0') */
+  application?: string;
+}
+
+/**
+ * Safely get Node.js version, with fallback
+ * @returns Node.js version string without 'v' prefix
+ */
+function getNodeVersion(): string {
+  try {
+    if (process?.version) {
+      return process.version.replace('v', '');
+    }
+  } catch {
+    // Ignore error, use fallback
+  }
+  return 'unknown';
+}
+
+/**
+ * Safely get platform information, with fallback
+ * @returns Platform string (e.g., 'darwin', 'linux', 'win32')
+ */
+function getPlatform(): string {
+  try {
+    return os.platform();
+  } catch {
+    // If os.platform() fails, return fallback
+    return 'unknown';
+  }
+}
+
+/**
+ * Build standard User-Agent header value
+ * Format: envoy-integrations-sdk/2.4.4 node/18.0.0
+ * With custom app: envoy-integrations-sdk/2.4.4 node/18.0.0 MyApp/1.0.0
+ *
+ * This function is designed to never throw exceptions. If any error occurs,
+ * it returns a safe fallback value to ensure SDK initialization succeeds.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns User-Agent header value (never throws)
+ */
+export function buildUserAgent(customUserAgent?: string): string {
+  try {
+    const nodeVersion = getNodeVersion();
+    const baseUA = `envoy-integrations-sdk/${version} node/${nodeVersion}`;
+    return customUserAgent ? `${baseUA} ${customUserAgent}` : baseUA;
+  } catch {
+    // Critical fallback - should never happen, but ensures SDK always works
+    // Silently fail - User-Agent is telemetry, not critical functionality
+    return 'envoy-integrations-sdk/unknown node/unknown';
+  }
+}
+
+/**
+ * Build detailed client info for X-Envoy-Client-Info header
+ *
+ * This function is designed to never throw exceptions. If any error occurs
+ * during info collection, it uses safe fallback values.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns ClientInfo object (never throws)
+ */
+export function buildClientInfo(customUserAgent?: string): ClientInfo {
+  try {
+    const nodeVersion = getNodeVersion();
+    const platform = getPlatform();
+
+    const clientInfo: ClientInfo = {
+      sdk: 'envoy-integrations-sdk',
+      version,
+      runtime: 'node',
+      runtimeVersion: nodeVersion,
+      platform,
+    };
+
+    // Only add application if it's a non-empty string
+    if (customUserAgent) {
+      clientInfo.application = customUserAgent;
+    }
+
+    return clientInfo;
+  } catch {
+    // Critical fallback - return minimal safe info
+    // Silently fail - User-Agent is telemetry, not critical functionality
+    return {
+      sdk: 'envoy-integrations-sdk',
+      version: 'unknown',
+      runtime: 'node',
+      runtimeVersion: 'unknown',
+      platform: 'unknown',
+    };
+  }
+}
+
+/**
+ * Build X-Envoy-Client-Info header value (JSON string)
+ *
+ * This function is designed to never throw exceptions. If JSON serialization
+ * fails, it returns a minimal safe JSON string.
+ *
+ * @param customUserAgent Optional custom application identifier
+ * @returns JSON string for X-Envoy-Client-Info header (never throws)
+ */
+export function buildClientInfoHeader(customUserAgent?: string): string {
+  try {
+    const clientInfo = buildClientInfo(customUserAgent);
+    return JSON.stringify(clientInfo);
+  } catch {
+    // Critical fallback - return minimal valid JSON
+    // Silently fail - User-Agent is telemetry, not critical functionality
+    // Return minimal valid JSON that won't break parsing
+    return '{"sdk":"envoy-integrations-sdk","version":"unknown","runtime":"node","runtimeVersion":"unknown","platform":"unknown"}';
+  }
+}