@epilot/app-client 0.15.0 → 0.16.0

package/dist/openapi.d.ts

@@ -314,7 +314,11 @@ declare namespace Components {
             surfaces?: {
                 [key: string]: any;
             };
-        } & (JourneyBlockComponent | PortalBlockComponent | PortalExtensionComponent | CustomFlowActionComponent | ErpInformToolkitComponent | CustomCapabilityComponent | ExternalProductCatalogComponent | CustomPageComponent | ApiProxyComponent);
+        } & (JourneyBlockComponent | PortalBlockComponent | PortalExtensionComponent | CustomFlowActionComponent | ErpInformToolkitComponent | CustomCapabilityComponent | ExternalProductCatalogComponent | CustomPageComponent | ApiProxyComponent | /**
+         * Exposes typed values resolved from an external system at runtime (e.g. a meter reading prediction). Consumers such as validation rules reference a hook and one of its results by id. Resolution is performed by the external-values-api on behalf of authenticated epilot 360 users and portal end customers.
+         *
+         */
+        ExternalValuesComponent);
         export interface BaseComponentCommon {
             /**
              * Unique identifier for the component
@@ -547,7 +551,7 @@ declare namespace Components {
         /**
          * Type of app component
          */
-        export type ComponentType = "CUSTOM_JOURNEY_BLOCK" | "CUSTOM_PORTAL_BLOCK" | "PORTAL_EXTENSION" | "CUSTOM_FLOW_ACTION" | "ERP_INFORM_TOOLKIT" | "CUSTOM_CAPABILITY" | "EXTERNAL_PRODUCT_CATALOG" | "CUSTOM_PAGE" | "API_PROXY" | "APP_FUNCTION";
+        export type ComponentType = "CUSTOM_JOURNEY_BLOCK" | "CUSTOM_PORTAL_BLOCK" | "PORTAL_EXTENSION" | "CUSTOM_FLOW_ACTION" | "ERP_INFORM_TOOLKIT" | "CUSTOM_CAPABILITY" | "EXTERNAL_PRODUCT_CATALOG" | "CUSTOM_PAGE" | "API_PROXY" | "EXTERNAL_VALUES" | "APP_FUNCTION";
         /**
          * Configuration of the published app
          */
@@ -1264,6 +1268,167 @@ declare namespace Components {
                 };
             };
         }
+        /**
+         * Exposes typed values resolved from an external system at runtime (e.g. a meter reading prediction). Consumers such as validation rules reference a hook and one of its results by id. Resolution is performed by the external-values-api on behalf of authenticated epilot 360 users and portal end customers.
+         *
+         */
+        export interface ExternalValuesComponent {
+            component_type: "EXTERNAL_VALUES";
+            configuration: /* Configuration for an EXTERNAL_VALUES component */ ExternalValuesConfig;
+        }
+        /**
+         * Configuration for an EXTERNAL_VALUES component
+         */
+        export interface ExternalValuesConfig {
+            /**
+             * Hooks exposed by this component. Hook ids must be unique within the component.
+             */
+            hooks: /**
+             * One external call that returns one or more typed results. Interpolated templates (Liquid) have access to `Input`, `Context`, `Consumer`, `Options`, `Env` and — for `result` templates — `Response` and `AuthResponse`.
+             *
+             */
+            ExternalValuesHook[];
+        }
+        /**
+         * One external call that returns one or more typed results. Interpolated templates (Liquid) have access to `Input`, `Context`, `Consumer`, `Options`, `Env` and — for `result` templates — `Response` and `AuthResponse`.
+         *
+         */
+        export interface ExternalValuesHook {
+            /**
+             * Stable identifier; consumers (e.g. validation rules) reference it. Renaming breaks references.
+             */
+            id: string; // ^[a-zA-Z0-9_-]{1,100}$
+            name: TranslatedString;
+            description?: TranslatedString;
+            /**
+             * Static request authentication applied to the call.
+             * - `none`: no static authentication.
+             * - `header`: sends `auth_secret` in header `auth_header` (default `X-API-Key`).
+             * - `bearer`: sends `Authorization: Bearer <auth_secret>`.
+             * - `hmac`: signs the request per Standard Webhooks (headers `webhook-id`,
+             *   `webhook-timestamp`, `webhook-signature` = `v1,<base64 HMAC-SHA256>` over
+             *   `<id>.<timestamp>.<body>`) using `auth_secret` as a `whsec_`-prefixed
+             *   base64 secret, exactly as epilot webhooks do.
+             *
+             * `auth_secret` is required when `auth_type` is `header`, `bearer` or `hmac`.
+             * Combine with `auth` (a pre-call that fetches a token) when the target needs both.
+             *
+             */
+            auth_type?: "none" | "header" | "bearer" | "hmac";
+            /**
+             * Header name used when `auth_type` is `header`. Defaults to `X-API-Key`.
+             */
+            auth_header?: string;
+            /**
+             * Liquid template resolving to the secret, e.g. "{{Options.api_key}}". Must reference an option declared with `type: secret`; literals are rejected. Required when `auth_type` is `header`, `bearer` or `hmac`.
+             * example:
+             * {{Options.api_key}}
+             */
+            auth_secret?: string;
+            auth?: PortalExtensionAuthBlock;
+            call: {
+                /**
+                 * HTTP method to use for the call
+                 */
+                method?: "GET" | "POST" | "PUT" | "PATCH";
+                /**
+                 * URL to call. Supports variable interpolation.
+                 */
+                url: string;
+                /**
+                 * Headers to send with the call. Supports variable interpolation.
+                 */
+                headers?: {
+                    [name: string]: string;
+                };
+                /**
+                 * Query parameters to append to the URL. Supports variable interpolation.
+                 */
+                params?: {
+                    [name: string]: string;
+                };
+                /**
+                 * JSON body to send. Values support variable interpolation. When omitted, `{ Input, Context, Consumer }` is sent as-is.
+                 */
+                body?: {
+                    [name: string]: any;
+                };
+            };
+            /**
+             * Typed results extracted from the response. Result ids must be unique within the hook.
+             */
+            result: [
+                /**
+                 * A single typed value extracted from the hook response. Exactly one of `template`, `path` or `jsonata` must be set.
+                 *
+                 */
+                ExternalValuesResult,
+                .../**
+                 * A single typed value extracted from the hook response. Exactly one of `template`, `path` or `jsonata` must be set.
+                 *
+                 */
+                ExternalValuesResult[]
+            ];
+            /**
+             * Timeout for the external call in milliseconds.
+             */
+            timeout_ms?: number;
+            /**
+             * Behaviour when the external system is unavailable (timeout, network or upstream error). `skip`: consumers ignore conditions depending on this hook. `block`: consumers treat the dependent action as not allowed.
+             */
+            on_unavailable?: "skip" | "block";
+            /**
+             * Response caching. Off when omitted.
+             */
+            cache?: {
+                /**
+                 * Time to live in seconds. 0 disables caching.
+                 */
+                ttl_seconds: number;
+                /**
+                 * Liquid template for the cache key. Defaults to a hash of org, app, hook, `Input` and `Context`.
+                 */
+                key?: string;
+            };
+            /**
+             * If set, requests are sent from epilot's static egress IPs. Mutually exclusive with secure_proxy.
+             */
+            use_static_ips?: boolean;
+            secure_proxy?: /* If set, requests are routed through the ERP Integration secure proxy. Mutually exclusive with use_static_ips. */ PortalExtensionSecureProxy;
+        }
+        /**
+         * A single typed value extracted from the hook response. Exactly one of `template`, `path` or `jsonata` must be set.
+         *
+         */
+        export interface ExternalValuesResult {
+            /**
+             * Stable identifier of the result within the hook. Renaming breaks references.
+             */
+            id: string; // ^[a-zA-Z0-9_-]{1,100}$
+            /**
+             * Type the extracted value is coerced to.
+             */
+            type: "number" | "text" | "date" | "boolean";
+            name: TranslatedString;
+            /**
+             * Liquid template over `Response` etc.; output coerced to `type`.
+             * example:
+             * {{Response.value}}
+             */
+            template?: string;
+            /**
+             * Dot path into the response body, e.g. "data.limit".
+             * example:
+             * data.limit
+             */
+            path?: string;
+            /**
+             * JSONata expression over `{ Response, Input, Context, Options, Env }`.
+             * example:
+             * $sum(Response.items.amount)
+             */
+            jsonata?: string;
+        }
         /**
          * A named server-side function belonging to the app. Runs in the epilot code-execution sandbox with an installation-scoped app token. Functions with a schedule are executed automatically once per installation.
          *
@@ -4510,6 +4675,10 @@ export type ExternalProductCatalogComponent = Components.Schemas.ExternalProduct
 export type ExternalProductCatalogConfig = Components.Schemas.ExternalProductCatalogConfig;
 export type ExternalProductCatalogHookProductRecommendations = Components.Schemas.ExternalProductCatalogHookProductRecommendations;
 export type ExternalProductCatalogHookProducts = Components.Schemas.ExternalProductCatalogHookProducts;
+export type ExternalValuesComponent = Components.Schemas.ExternalValuesComponent;
+export type ExternalValuesConfig = Components.Schemas.ExternalValuesConfig;
+export type ExternalValuesHook = Components.Schemas.ExternalValuesHook;
+export type ExternalValuesResult = Components.Schemas.ExternalValuesResult;
 export type FunctionDefinition = Components.Schemas.FunctionDefinition;
 export type FunctionRefCustomActionConfig = Components.Schemas.FunctionRefCustomActionConfig;
 export type Grants = Components.Schemas.Grants;

package/dist/openapi.json

@@ -2204,6 +2204,7 @@
           "EXTERNAL_PRODUCT_CATALOG",
           "CUSTOM_PAGE",
           "API_PROXY",
+          "EXTERNAL_VALUES",
           "APP_FUNCTION"
         ],
         "description": "Type of app component"
@@ -2400,7 +2401,8 @@
                 "CUSTOM_CAPABILITY": "#/components/schemas/CustomCapabilityComponent",
                 "EXTERNAL_PRODUCT_CATALOG": "#/components/schemas/ExternalProductCatalogComponent",
                 "CUSTOM_PAGE": "#/components/schemas/CustomPageComponent",
-                "API_PROXY": "#/components/schemas/ApiProxyComponent"
+                "API_PROXY": "#/components/schemas/ApiProxyComponent",
+                "EXTERNAL_VALUES": "#/components/schemas/ExternalValuesComponent"
               }
             },
             "oneOf": [
@@ -2430,6 +2432,9 @@
               },
               {
                 "$ref": "#/components/schemas/ApiProxyComponent"
+              },
+              {
+                "$ref": "#/components/schemas/ExternalValuesComponent"
               }
             ]
           }
@@ -2453,6 +2458,25 @@
           }
         }
       },
+      "ExternalValuesComponent": {
+        "type": "object",
+        "description": "Exposes typed values resolved from an external system at runtime (e.g. a meter reading prediction). Consumers such as validation rules reference a hook and one of its results by id. Resolution is performed by the external-values-api on behalf of authenticated epilot 360 users and portal end customers.\n",
+        "required": [
+          "component_type",
+          "configuration"
+        ],
+        "properties": {
+          "component_type": {
+            "type": "string",
+            "enum": [
+              "EXTERNAL_VALUES"
+            ]
+          },
+          "configuration": {
+            "$ref": "#/components/schemas/ExternalValuesConfig"
+          }
+        }
+      },
       "CustomCapabilityComponent": {
         "type": "object",
         "required": [
@@ -5107,6 +5131,204 @@
           }
         }
       },
+      "ExternalValuesConfig": {
+        "type": "object",
+        "description": "Configuration for an EXTERNAL_VALUES component",
+        "required": [
+          "hooks"
+        ],
+        "properties": {
+          "hooks": {
+            "type": "array",
+            "description": "Hooks exposed by this component. Hook ids must be unique within the component.",
+            "items": {
+              "$ref": "#/components/schemas/ExternalValuesHook"
+            }
+          }
+        }
+      },
+      "ExternalValuesHook": {
+        "type": "object",
+        "description": "One external call that returns one or more typed results. Interpolated templates (Liquid) have access to `Input`, `Context`, `Consumer`, `Options`, `Env` and — for `result` templates — `Response` and `AuthResponse`.\n",
+        "required": [
+          "id",
+          "name",
+          "call",
+          "result"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,100}$",
+            "description": "Stable identifier; consumers (e.g. validation rules) reference it. Renaming breaks references."
+          },
+          "name": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "description": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "auth_type": {
+            "type": "string",
+            "enum": [
+              "none",
+              "header",
+              "bearer",
+              "hmac"
+            ],
+            "default": "none",
+            "description": "Static request authentication applied to the call.\n- `none`: no static authentication.\n- `header`: sends `auth_secret` in header `auth_header` (default `X-API-Key`).\n- `bearer`: sends `Authorization: Bearer <auth_secret>`.\n- `hmac`: signs the request per Standard Webhooks (headers `webhook-id`,\n  `webhook-timestamp`, `webhook-signature` = `v1,<base64 HMAC-SHA256>` over\n  `<id>.<timestamp>.<body>`) using `auth_secret` as a `whsec_`-prefixed\n  base64 secret, exactly as epilot webhooks do.\n\n`auth_secret` is required when `auth_type` is `header`, `bearer` or `hmac`.\nCombine with `auth` (a pre-call that fetches a token) when the target needs both.\n"
+          },
+          "auth_header": {
+            "type": "string",
+            "description": "Header name used when `auth_type` is `header`. Defaults to `X-API-Key`."
+          },
+          "auth_secret": {
+            "type": "string",
+            "description": "Liquid template resolving to the secret, e.g. \"{{Options.api_key}}\". Must reference an option declared with `type: secret`; literals are rejected. Required when `auth_type` is `header`, `bearer` or `hmac`.",
+            "example": "{{Options.api_key}}"
+          },
+          "auth": {
+            "$ref": "#/components/schemas/PortalExtensionAuthBlock"
+          },
+          "call": {
+            "type": "object",
+            "required": [
+              "url"
+            ],
+            "properties": {
+              "method": {
+                "type": "string",
+                "enum": [
+                  "GET",
+                  "POST",
+                  "PUT",
+                  "PATCH"
+                ],
+                "default": "POST",
+                "description": "HTTP method to use for the call"
+              },
+              "url": {
+                "type": "string",
+                "description": "URL to call. Supports variable interpolation."
+              },
+              "headers": {
+                "type": "object",
+                "description": "Headers to send with the call. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "params": {
+                "type": "object",
+                "description": "Query parameters to append to the URL. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "body": {
+                "type": "object",
+                "description": "JSON body to send. Values support variable interpolation. When omitted, `{ Input, Context, Consumer }` is sent as-is.",
+                "additionalProperties": true
+              }
+            }
+          },
+          "result": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Typed results extracted from the response. Result ids must be unique within the hook.",
+            "items": {
+              "$ref": "#/components/schemas/ExternalValuesResult"
+            }
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "minimum": 500,
+            "maximum": 5000,
+            "default": 3000,
+            "description": "Timeout for the external call in milliseconds."
+          },
+          "on_unavailable": {
+            "type": "string",
+            "enum": [
+              "skip",
+              "block"
+            ],
+            "default": "skip",
+            "description": "Behaviour when the external system is unavailable (timeout, network or upstream error). `skip`: consumers ignore conditions depending on this hook. `block`: consumers treat the dependent action as not allowed."
+          },
+          "cache": {
+            "type": "object",
+            "description": "Response caching. Off when omitted.",
+            "required": [
+              "ttl_seconds"
+            ],
+            "properties": {
+              "ttl_seconds": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 3600,
+                "description": "Time to live in seconds. 0 disables caching."
+              },
+              "key": {
+                "type": "string",
+                "description": "Liquid template for the cache key. Defaults to a hash of org, app, hook, `Input` and `Context`."
+              }
+            }
+          },
+          "use_static_ips": {
+            "type": "boolean",
+            "description": "If set, requests are sent from epilot's static egress IPs. Mutually exclusive with secure_proxy."
+          },
+          "secure_proxy": {
+            "$ref": "#/components/schemas/PortalExtensionSecureProxy"
+          }
+        }
+      },
+      "ExternalValuesResult": {
+        "type": "object",
+        "description": "A single typed value extracted from the hook response. Exactly one of `template`, `path` or `jsonata` must be set.\n",
+        "required": [
+          "id",
+          "type",
+          "name"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,100}$",
+            "description": "Stable identifier of the result within the hook. Renaming breaks references."
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "number",
+              "text",
+              "date",
+              "boolean"
+            ],
+            "description": "Type the extracted value is coerced to."
+          },
+          "name": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "template": {
+            "type": "string",
+            "description": "Liquid template over `Response` etc.; output coerced to `type`.",
+            "example": "{{Response.value}}"
+          },
+          "path": {
+            "type": "string",
+            "description": "Dot path into the response body, e.g. \"data.limit\".",
+            "example": "data.limit"
+          },
+          "jsonata": {
+            "type": "string",
+            "description": "JSONata expression over `{ Response, Input, Context, Options, Env }`.",
+            "example": "$sum(Response.items.amount)"
+          }
+        }
+      },
       "Grants": {
         "type": "array",
         "description": "Required grants for the app in order to call APIs for the installing tenant",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/app-client",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "JavaScript client library for the epilot App API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",