@epilot/erp-integration-client 0.26.1 → 0.27.0

package/dist/openapi.d.ts

@@ -205,6 +205,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -216,7 +221,7 @@ declare namespace Components {
             configuration?: /**
              * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
              *
-             * The file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.
+             * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
              * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
              * Additional use-case-specific parameters are declared in the `params` array.
              *
@@ -228,6 +233,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -266,6 +276,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -282,6 +297,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -331,6 +351,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -358,6 +383,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -386,6 +416,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -489,6 +524,11 @@ declare namespace Components {
             payload: /* The object data payload - can be either a serialized string or a direct JSON object */ string | {
                 [name: string]: any;
             };
+            /**
+             * Recommended. Use case slug for routing this event to the correct use case configuration. If provided, takes precedence over event_name for use case lookup. Preferred over event_name-based routing as slugs are portable across environments.
+             *
+             */
+            use_case_slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Optional unique identifier for idempotency - prevents duplicate processing of the same event within 24 hours in context of the same integration. Must contain only alphanumeric characters, hyphens, and underscores.
              *
@@ -556,6 +596,32 @@ declare namespace Components {
              * Optional OAuth2 scope
              */
             scope?: string;
+            /**
+             * Handlebars template for the OAuth2 audience parameter
+             */
+            audience?: string;
+            /**
+             * Handlebars template for the OAuth2 resource parameter
+             */
+            resource?: string;
+            /**
+             * Additional key-value pairs to include in the token request body. Values support Handlebars templates.
+             */
+            body_params?: {
+                [name: string]: string;
+            };
+            /**
+             * Additional headers to include in the token request. Values support Handlebars templates.
+             */
+            headers?: {
+                [name: string]: string;
+            };
+            /**
+             * Additional query parameters to append to the token URL. Values support Handlebars templates.
+             */
+            query_params?: {
+                [name: string]: string;
+            };
         }
         export interface FileProxyParam {
             /**
@@ -614,20 +680,28 @@ declare namespace Components {
             response_type: "json" | "binary";
         }
         /**
-         * Auto-constructs a file proxy download URL. orgId and integrationId are injected from context.
+         * Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.
+         *
          */
-        export interface FileProxyUrlConfig {
+        export type FileProxyUrlConfig = /**
+         * Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.
+         *
+         */
+        {
             /**
-             * UUID of the file_proxy use case. Maps to useCaseId query parameter.
+             * Recommended. Slug of the file_proxy use case. Maps to useCaseSlug query parameter. Portable across environments.
+             *
              */
-            use_case_id: string;
+            use_case_slug: string; // ^[a-z0-9][a-z0-9_-]*$
+            params?: /* Custom query parameters. Keys become URL param names, values resolved from payload. */ FileProxyUrlParams;
+        } | {
             /**
-             * Custom query parameters. Keys become URL param names, values resolved from payload.
+             * Legacy. UUID of the file_proxy use case. Maps to useCaseId query parameter. Prefer use_case_slug for portable configuration.
+             *
              */
-            params?: {
-                [name: string]: /* Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set. */ FileProxyUrlParam;
-            };
-        }
+            use_case_id: string;
+            params?: /* Custom query parameters. Keys become URL param names, values resolved from payload. */ FileProxyUrlParams;
+        };
         /**
          * Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set.
          */
@@ -647,6 +721,12 @@ declare namespace Components {
              */
             jsonataExpression: string;
         };
+        /**
+         * Custom query parameters. Keys become URL param names, values resolved from payload.
+         */
+        export interface FileProxyUrlParams {
+            [name: string]: /* Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set. */ FileProxyUrlParam;
+        }
         export interface FileProxyUseCase {
             /**
              * Unique identifier for the use case
@@ -660,6 +740,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Use case type
              */
@@ -680,7 +765,7 @@ declare namespace Components {
             configuration?: /**
              * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
              *
-             * The file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.
+             * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
              * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
              * Additional use-case-specific parameters are declared in the `params` array.
              *
@@ -690,7 +775,7 @@ declare namespace Components {
         /**
          * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
          *
-         * The file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.
+         * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
          * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
          * Additional use-case-specific parameters are declared in the `params` array.
          *
@@ -702,7 +787,7 @@ declare namespace Components {
             requires_vpc?: boolean;
             auth?: FileProxyAuth;
             /**
-             * Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, useCaseId)
+             * Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, and useCaseSlug or useCaseId)
              */
             params?: FileProxyParam[];
             /**
@@ -731,6 +816,10 @@ declare namespace Components {
              * Use case name at this point in history
              */
             name: string;
+            /**
+             * Use case slug at this point in history
+             */
+            slug?: string;
             /**
              * Whether the use case was enabled at this point in history
              */
@@ -758,7 +847,7 @@ declare namespace Components {
             configuration?: /**
              * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
              *
-             * The file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.
+             * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
              * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
              * Additional use-case-specific parameters are declared in the `params` array.
              *
@@ -911,6 +1000,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Use case type
              */
@@ -947,6 +1041,10 @@ declare namespace Components {
              * Use case name at this point in history
              */
             name: string;
+            /**
+             * Use case slug at this point in history
+             */
+            slug?: string;
             /**
              * Whether the use case was enabled at this point in history
              */
@@ -1146,7 +1244,11 @@ declare namespace Components {
              *
              */
             RelationRefsConfig;
-            file_proxy_url?: /* Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. */ FileProxyUrlConfig;
+            file_proxy_url?: /**
+             * Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.
+             *
+             */
+            FileProxyUrlConfig;
         }
         export interface IntegrationFieldV1 {
             /**
@@ -1604,6 +1706,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Use case type
              */
@@ -1640,6 +1747,10 @@ declare namespace Components {
              * Use case name at this point in history
              */
             name: string;
+            /**
+             * Use case slug at this point in history
+             */
+            slug?: string;
             /**
              * Whether the use case was enabled at this point in history
              */
@@ -2299,6 +2410,11 @@ declare namespace Components {
              * Use case name
              */
             name?: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -2314,7 +2430,7 @@ declare namespace Components {
             configuration?: /**
              * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
              *
-             * The file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.
+             * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
              * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
              * Additional use-case-specific parameters are declared in the `params` array.
              *
@@ -2326,6 +2442,11 @@ declare namespace Components {
              * Use case name
              */
             name?: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -2346,6 +2467,11 @@ declare namespace Components {
              * Use case name
              */
             name?: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -2366,6 +2492,11 @@ declare namespace Components {
              * Use case name
              */
             name?: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Whether the use case is enabled
              */
@@ -2425,6 +2556,11 @@ declare namespace Components {
              * Use case name
              */
             name: string;
+            /**
+             * URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.
+             *
+             */
+            slug?: string; // ^[a-z0-9][a-z0-9_-]*$
             /**
              * Use case type
              */
@@ -2461,6 +2597,10 @@ declare namespace Components {
              * Use case name at this point in history
              */
             name: string;
+            /**
+             * Use case slug at this point in history
+             */
+            slug?: string;
             /**
              * Whether the use case was enabled at this point in history
              */
@@ -3870,6 +4010,7 @@ export type FileProxyResponseConfig = Components.Schemas.FileProxyResponseConfig
 export type FileProxyStep = Components.Schemas.FileProxyStep;
 export type FileProxyUrlConfig = Components.Schemas.FileProxyUrlConfig;
 export type FileProxyUrlParam = Components.Schemas.FileProxyUrlParam;
+export type FileProxyUrlParams = Components.Schemas.FileProxyUrlParams;
 export type FileProxyUseCase = Components.Schemas.FileProxyUseCase;
 export type FileProxyUseCaseConfiguration = Components.Schemas.FileProxyUseCaseConfiguration;
 export type FileProxyUseCaseHistoryEntry = Components.Schemas.FileProxyUseCaseHistoryEntry;

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.43.0",
+    "version": "0.45.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -2404,6 +2404,13 @@
             ],
             "description": "The object data payload - can be either a serialized string or a direct JSON object"
           },
+          "use_case_slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Recommended. Use case slug for routing this event to the correct use case configuration. If provided, takes precedence over event_name for use case lookup. Preferred over event_name-based routing as slugs are portable across environments.\n"
+          },
           "deduplication_id": {
             "type": "string",
             "pattern": "^[a-zA-Z0-9_-]+$",
@@ -3095,25 +3102,48 @@
           }
         ]
       },
-      "FileProxyUrlConfig": {
+      "FileProxyUrlParams": {
         "type": "object",
-        "required": [
-          "use_case_id"
-        ],
-        "description": "Auto-constructs a file proxy download URL. orgId and integrationId are injected from context.",
-        "properties": {
-          "use_case_id": {
-            "type": "string",
-            "description": "UUID of the file_proxy use case. Maps to useCaseId query parameter."
+        "description": "Custom query parameters. Keys become URL param names, values resolved from payload.",
+        "additionalProperties": {
+          "$ref": "#/components/schemas/FileProxyUrlParam"
+        }
+      },
+      "FileProxyUrlConfig": {
+        "description": "Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.\n",
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "use_case_slug"
+            ],
+            "properties": {
+              "use_case_slug": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9_-]*$",
+                "description": "Recommended. Slug of the file_proxy use case. Maps to useCaseSlug query parameter. Portable across environments.\n"
+              },
+              "params": {
+                "$ref": "#/components/schemas/FileProxyUrlParams"
+              }
+            }
           },
-          "params": {
+          {
             "type": "object",
-            "description": "Custom query parameters. Keys become URL param names, values resolved from payload.",
-            "additionalProperties": {
-              "$ref": "#/components/schemas/FileProxyUrlParam"
+            "required": [
+              "use_case_id"
+            ],
+            "properties": {
+              "use_case_id": {
+                "type": "string",
+                "description": "Legacy. UUID of the file_proxy use case. Maps to useCaseId query parameter. Prefer use_case_slug for portable configuration.\n"
+              },
+              "params": {
+                "$ref": "#/components/schemas/FileProxyUrlParams"
+              }
             }
           }
-        }
+        ]
       },
       "EmbeddedUseCaseRequest": {
         "oneOf": [
@@ -3151,6 +3181,13 @@
             "maxLength": 255,
             "description": "Use case name"
           },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation.\n"
+          },
           "enabled": {
             "type": "boolean",
             "description": "Whether the use case is enabled"
@@ -3238,6 +3275,13 @@
             "type": "string",
             "description": "Use case name"
           },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.\n"
+          },
           "type": {
             "type": "string",
             "enum": [
@@ -3398,6 +3442,13 @@
             "maxLength": 255,
             "description": "Use case name"
           },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.\n"
+          },
           "enabled": {
             "type": "boolean",
             "description": "Whether the use case is enabled"
@@ -3509,6 +3560,13 @@
             "maxLength": 255,
             "description": "Use case name"
           },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.\n"
+          },
           "enabled": {
             "type": "boolean",
             "description": "Whether the use case is enabled"
@@ -3640,6 +3698,10 @@
             "type": "string",
             "description": "Use case name at this point in history"
           },
+          "slug": {
+            "type": "string",
+            "description": "Use case slug at this point in history"
+          },
           "enabled": {
             "type": "boolean",
             "description": "Whether the use case was enabled at this point in history"
@@ -3746,7 +3808,7 @@
           "steps",
           "response"
         ],
-        "description": "Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.\n\nThe file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.\nThe `orgId` is included in the signed URL to establish organization context without requiring authentication.\nAdditional use-case-specific parameters are declared in the `params` array.\n",
+        "description": "Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.\n\nThe file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.\nThe `orgId` is included in the signed URL to establish organization context without requiring authentication.\nAdditional use-case-specific parameters are declared in the `params` array.\n",
         "properties": {
           "requires_vpc": {
             "type": "boolean",
@@ -3762,7 +3824,7 @@
             "items": {
               "$ref": "#/components/schemas/FileProxyParam"
             },
-            "description": "Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, useCaseId)"
+            "description": "Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, and useCaseSlug or useCaseId)"
           },
           "steps": {
             "type": "array",
@@ -3808,6 +3870,35 @@
           "scope": {
             "type": "string",
             "description": "Optional OAuth2 scope"
+          },
+          "audience": {
+            "type": "string",
+            "description": "Handlebars template for the OAuth2 audience parameter"
+          },
+          "resource": {
+            "type": "string",
+            "description": "Handlebars template for the OAuth2 resource parameter"
+          },
+          "body_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional key-value pairs to include in the token request body. Values support Handlebars templates."
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional headers to include in the token request. Values support Handlebars templates."
+          },
+          "query_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional query parameters to append to the token URL. Values support Handlebars templates."
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/erp-integration-client",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Client library for ePilot ERP Integration API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",