@epilot/sdk 2.18.7 → 2.18.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/definitions/integration-toolkit.json +298 -15
  2. package/dist/apis/access-token.cjs +6 -6
  3. package/dist/apis/access-token.js +1 -1
  4. package/dist/apis/address-suggestions.cjs +6 -6
  5. package/dist/apis/address-suggestions.js +1 -1
  6. package/dist/apis/address.cjs +6 -6
  7. package/dist/apis/address.js +1 -1
  8. package/dist/apis/ai-agents.cjs +6 -6
  9. package/dist/apis/ai-agents.js +1 -1
  10. package/dist/apis/app.cjs +6 -6
  11. package/dist/apis/app.js +1 -1
  12. package/dist/apis/audit-logs.cjs +6 -6
  13. package/dist/apis/audit-logs.js +1 -1
  14. package/dist/apis/automation.cjs +6 -6
  15. package/dist/apis/automation.js +1 -1
  16. package/dist/apis/billing.cjs +6 -6
  17. package/dist/apis/billing.js +1 -1
  18. package/dist/apis/blueprint-manifest.cjs +6 -6
  19. package/dist/apis/blueprint-manifest.js +1 -1
  20. package/dist/apis/calendar.cjs +6 -6
  21. package/dist/apis/calendar.js +1 -1
  22. package/dist/apis/configuration-hub.cjs +6 -6
  23. package/dist/apis/configuration-hub.js +1 -1
  24. package/dist/apis/consent.cjs +6 -6
  25. package/dist/apis/consent.js +1 -1
  26. package/dist/apis/customer-portal.cjs +6 -6
  27. package/dist/apis/customer-portal.js +1 -1
  28. package/dist/apis/dashboard.cjs +6 -6
  29. package/dist/apis/dashboard.js +1 -1
  30. package/dist/apis/data-governance.cjs +6 -6
  31. package/dist/apis/data-governance.js +1 -1
  32. package/dist/apis/deduplication.cjs +6 -6
  33. package/dist/apis/deduplication.js +1 -1
  34. package/dist/apis/design.cjs +6 -6
  35. package/dist/apis/design.js +1 -1
  36. package/dist/apis/document.cjs +6 -6
  37. package/dist/apis/document.js +1 -1
  38. package/dist/apis/email-settings.cjs +6 -6
  39. package/dist/apis/email-settings.js +1 -1
  40. package/dist/apis/email-template.cjs +6 -6
  41. package/dist/apis/email-template.js +1 -1
  42. package/dist/apis/entity-mapping.cjs +6 -6
  43. package/dist/apis/entity-mapping.js +1 -1
  44. package/dist/apis/entity.cjs +6 -6
  45. package/dist/apis/entity.js +1 -1
  46. package/dist/apis/environments.cjs +6 -6
  47. package/dist/apis/environments.js +1 -1
  48. package/dist/apis/event-catalog.cjs +6 -6
  49. package/dist/apis/event-catalog.js +1 -1
  50. package/dist/apis/file.cjs +6 -6
  51. package/dist/apis/file.js +1 -1
  52. package/dist/apis/iban.cjs +6 -6
  53. package/dist/apis/iban.js +1 -1
  54. package/dist/apis/integration-toolkit.cjs +6 -6
  55. package/dist/apis/integration-toolkit.d.cts +2 -2
  56. package/dist/apis/integration-toolkit.d.ts +2 -2
  57. package/dist/apis/integration-toolkit.js +1 -1
  58. package/dist/apis/journey.cjs +6 -6
  59. package/dist/apis/journey.js +1 -1
  60. package/dist/apis/kanban.cjs +6 -6
  61. package/dist/apis/kanban.js +1 -1
  62. package/dist/apis/message.cjs +6 -6
  63. package/dist/apis/message.js +1 -1
  64. package/dist/apis/metering.cjs +6 -6
  65. package/dist/apis/metering.js +1 -1
  66. package/dist/apis/notes.cjs +6 -6
  67. package/dist/apis/notes.js +1 -1
  68. package/dist/apis/notification.cjs +6 -6
  69. package/dist/apis/notification.js +1 -1
  70. package/dist/apis/organization.cjs +6 -6
  71. package/dist/apis/organization.js +1 -1
  72. package/dist/apis/partner-directory.cjs +6 -6
  73. package/dist/apis/partner-directory.js +1 -1
  74. package/dist/apis/permissions.cjs +6 -6
  75. package/dist/apis/permissions.js +1 -1
  76. package/dist/apis/pricing-tier.cjs +6 -6
  77. package/dist/apis/pricing-tier.js +1 -1
  78. package/dist/apis/pricing.cjs +6 -6
  79. package/dist/apis/pricing.js +1 -1
  80. package/dist/apis/purpose.cjs +6 -6
  81. package/dist/apis/purpose.js +1 -1
  82. package/dist/apis/query.cjs +6 -6
  83. package/dist/apis/query.js +1 -1
  84. package/dist/apis/sandbox.cjs +6 -6
  85. package/dist/apis/sandbox.js +1 -1
  86. package/dist/apis/sharing.cjs +6 -6
  87. package/dist/apis/sharing.js +1 -1
  88. package/dist/apis/snapshot.cjs +6 -6
  89. package/dist/apis/snapshot.js +1 -1
  90. package/dist/apis/submission.cjs +6 -6
  91. package/dist/apis/submission.js +1 -1
  92. package/dist/apis/target.cjs +6 -6
  93. package/dist/apis/target.js +1 -1
  94. package/dist/apis/targeting.cjs +6 -6
  95. package/dist/apis/targeting.js +1 -1
  96. package/dist/apis/template-variables.cjs +6 -6
  97. package/dist/apis/template-variables.js +1 -1
  98. package/dist/apis/user.cjs +6 -6
  99. package/dist/apis/user.js +1 -1
  100. package/dist/apis/validation-rules.cjs +6 -6
  101. package/dist/apis/validation-rules.js +1 -1
  102. package/dist/apis/webhooks.cjs +6 -6
  103. package/dist/apis/webhooks.js +1 -1
  104. package/dist/apis/workflow-definition.cjs +6 -6
  105. package/dist/apis/workflow-definition.js +1 -1
  106. package/dist/apis/workflow.cjs +6 -6
  107. package/dist/apis/workflow.js +1 -1
  108. package/dist/{chunk-2L5YHQFJ.cjs → chunk-JMRPVDMK.cjs} +1 -1
  109. package/dist/{chunk-FMM7LLAO.js → chunk-M44TEEFZ.js} +1 -1
  110. package/dist/index.cjs +8 -8
  111. package/dist/index.d.cts +1 -1
  112. package/dist/index.d.ts +1 -1
  113. package/dist/index.js +1 -1
  114. package/dist/integration-toolkit-OSK5M75F.js +7 -0
  115. package/dist/integration-toolkit-W5IENOJW.cjs +7 -0
  116. package/dist/{integration-toolkit.d-CVI89-A-.d.cts → integration-toolkit.d-D5LjhCQB.d.cts} +564 -38
  117. package/dist/{integration-toolkit.d-CVI89-A-.d.ts → integration-toolkit.d-D5LjhCQB.d.ts} +564 -38
  118. package/docs/integration-toolkit.md +442 -141
  119. package/package.json +1 -1
  120. package/dist/integration-toolkit-MT7RPOOG.js +0 -7
  121. package/dist/integration-toolkit-S5BHYFIW.cjs +0 -7
@@ -1343,12 +1343,17 @@ declare namespace Components {
1343
1343
  */
1344
1344
  export interface CreateErpImportRequest {
1345
1345
  s3_reference: S3Reference;
1346
+ /**
1347
+ * Return a sample of the file's first rows. Informational only — `:validate` is still the authority. `preview` is present iff this is true.
1348
+ */
1349
+ include_preview?: boolean;
1346
1350
  }
1347
1351
  export interface CreateErpImportResponse {
1348
1352
  /**
1349
1353
  * `imp_{ULID}` — time-ordered, also used as the job's correlation_id.
1350
1354
  */
1351
1355
  import_id: string;
1356
+ preview?: /* Sample of the file's first rows, using the same parser as `:validate`. `status` is the outcome of this read, not a verdict on the file. */ ErpImportFilePreview;
1352
1357
  }
1353
1358
  export interface CreateFileProxyUseCaseRequest {
1354
1359
  /**
@@ -1369,11 +1374,25 @@ declare namespace Components {
1369
1374
  */
1370
1375
  type: "file_proxy";
1371
1376
  configuration?: /**
1372
- * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
1377
+ * Configuration for file_proxy use cases. Defines how to authenticate and move files
1378
+ * between epilot and an external document system, in either direction (see `direction`).
1379
+ *
1380
+ * **Download** (`direction: download`, the default) fetches a file from the external system
1381
+ * and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and
1382
+ * either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
1383
+ * The `orgId` is included in the signed URL to establish organization context without
1384
+ * requiring authentication. Additional use-case-specific parameters are declared in the
1385
+ * `params` array. `response` is REQUIRED for download use cases.
1386
+ *
1387
+ * **Upload** (`direction: upload`) pushes epilot files to the external system. It is not
1388
+ * reachable over the download endpoint; an outbound use case points at it via a `file_proxy`
1389
+ * delivery, and this configuration owns everything about what gets sent: `fan_out` decides
1390
+ * how many deliveries one event produces, `params_mapping` builds the values, and the
1391
+ * `steps` place those values into requests via `{{ params.* }}`.
1392
+ * `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted.
1373
1393
  *
1374
- * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
1375
- * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
1376
- * Additional use-case-specific parameters are declared in the `params` array.
1394
+ * OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the
1395
+ * server-side validator, which returns an explicit message naming the offending field.
1377
1396
  *
1378
1397
  */
1379
1398
  FileProxyUseCaseConfiguration;
@@ -1526,9 +1545,26 @@ declare namespace Components {
1526
1545
  component_id: string; // uuid
1527
1546
  }
1528
1547
  /**
1529
- * Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload)
1548
+ * Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload); file_proxy = one push per event attachment to an external document system, through a file_proxy use case (JSONata-transformed payload carrying the file bytes)
1530
1549
  */
1531
- export type DeliveryConfig = /* Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload) */ /* Push delivery of the transformed event to a webhook via svc-webhooks */ WebhookDeliveryConfig | /* Pull-based queue delivery. Items carry the raw standardized event-catalog payload; no JSONata mapping is applied in poll mode. Consumers fetch and acknowledge items via the poll API. */ PollDeliveryConfig;
1550
+ export type DeliveryConfig = /* Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload); file_proxy = one push per event attachment to an external document system, through a file_proxy use case (JSONata-transformed payload carrying the file bytes) */ /* Push delivery of the transformed event to a webhook via svc-webhooks */ WebhookDeliveryConfig | /* Pull-based queue delivery. Items carry the raw standardized event-catalog payload; no JSONata mapping is applied in poll mode. Consumers fetch and acknowledge items via the poll API. */ PollDeliveryConfig | /**
1551
+ * Push delivery to an external document system through a `file_proxy` use case.
1552
+ *
1553
+ * A pure pointer, deliberately. The outbound use case decides WHEN to deliver — its event
1554
+ * name plus `event_filter` — and the referenced `file_proxy` use case decides WHAT and HOW:
1555
+ * which items to fan out over (`fan_out`), what values to build (`params_mapping`,
1556
+ * `lookups`, `constants`), and the steps that send them. Keeping every file concern on the
1557
+ * file_proxy side is what lets one upload recipe be shared by several event subscriptions
1558
+ * without duplicating any of it.
1559
+ *
1560
+ * `jsonata_expression` on the mapping is NOT used for this delivery type and is rejected.
1561
+ *
1562
+ * The slug is resolved at delivery time, not at save time, so use cases can be saved in any
1563
+ * order; a dangling reference surfaces as a `USE_CASE_NOT_FOUND` monitoring event naming
1564
+ * the referencing mapping.
1565
+ *
1566
+ */
1567
+ FileProxyDeliveryConfig;
1532
1568
  export interface EmbeddedFileProxyUseCaseRequest {
1533
1569
  /**
1534
1570
  * Optional use case ID for update matching.
@@ -1560,11 +1596,25 @@ declare namespace Components {
1560
1596
  */
1561
1597
  type: "file_proxy";
1562
1598
  configuration?: /**
1563
- * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
1599
+ * Configuration for file_proxy use cases. Defines how to authenticate and move files
1600
+ * between epilot and an external document system, in either direction (see `direction`).
1601
+ *
1602
+ * **Download** (`direction: download`, the default) fetches a file from the external system
1603
+ * and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and
1604
+ * either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
1605
+ * The `orgId` is included in the signed URL to establish organization context without
1606
+ * requiring authentication. Additional use-case-specific parameters are declared in the
1607
+ * `params` array. `response` is REQUIRED for download use cases.
1564
1608
  *
1565
- * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
1566
- * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
1567
- * Additional use-case-specific parameters are declared in the `params` array.
1609
+ * **Upload** (`direction: upload`) pushes epilot files to the external system. It is not
1610
+ * reachable over the download endpoint; an outbound use case points at it via a `file_proxy`
1611
+ * delivery, and this configuration owns everything about what gets sent: `fan_out` decides
1612
+ * how many deliveries one event produces, `params_mapping` builds the values, and the
1613
+ * `steps` place those values into requests via `{{ params.* }}`.
1614
+ * `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted.
1615
+ *
1616
+ * OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the
1617
+ * server-side validator, which returns an explicit message naming the offending field.
1568
1618
  *
1569
1619
  */
1570
1620
  FileProxyUseCaseConfiguration;
@@ -2041,6 +2091,23 @@ declare namespace Components {
2041
2091
  */
2042
2092
  message: string;
2043
2093
  }
2094
+ /**
2095
+ * Sample of the file's first rows, using the same parser as `:validate`. `status` is the outcome of this read, not a verdict on the file.
2096
+ */
2097
+ export interface ErpImportFilePreview {
2098
+ /**
2099
+ * Treat an unrecognized value as "no preview available". Values may be added. UNREADABLE covers empty, header-only, malformed, or gone — there is no breakdown; `:validate` reports the reason.
2100
+ */
2101
+ status: "AVAILABLE" | "FORMAT_UNSUPPORTED" | "UNREADABLE";
2102
+ /**
2103
+ * Effective column names (trimmed, duplicates collapsed). Set iff `status` is AVAILABLE.
2104
+ */
2105
+ columns?: string[];
2106
+ /**
2107
+ * Up to the first 5 data rows, aligned to `columns`.
2108
+ */
2109
+ rows?: string[][];
2110
+ }
2044
2111
  /**
2045
2112
  * A problem found during validation, scoped to the file as a whole rather than to individual rows. See `code` for the kinds reported.
2046
2113
  */
@@ -2125,6 +2192,10 @@ declare namespace Components {
2125
2192
  integration_name: string;
2126
2193
  use_case_slug: string;
2127
2194
  use_case_name: string;
2195
+ /**
2196
+ * How many distinct entity schemas this mapping uses.
2197
+ */
2198
+ entity_types: number;
2128
2199
  /**
2129
2200
  * How many of the FILE's columns this use case reads, by exact trimmed name.
2130
2201
  */
@@ -2320,6 +2391,110 @@ declare namespace Components {
2320
2391
  [name: string]: string;
2321
2392
  };
2322
2393
  }
2394
+ /**
2395
+ * Push delivery to an external document system through a `file_proxy` use case.
2396
+ *
2397
+ * A pure pointer, deliberately. The outbound use case decides WHEN to deliver — its event
2398
+ * name plus `event_filter` — and the referenced `file_proxy` use case decides WHAT and HOW:
2399
+ * which items to fan out over (`fan_out`), what values to build (`params_mapping`,
2400
+ * `lookups`, `constants`), and the steps that send them. Keeping every file concern on the
2401
+ * file_proxy side is what lets one upload recipe be shared by several event subscriptions
2402
+ * without duplicating any of it.
2403
+ *
2404
+ * `jsonata_expression` on the mapping is NOT used for this delivery type and is rejected.
2405
+ *
2406
+ * The slug is resolved at delivery time, not at save time, so use cases can be saved in any
2407
+ * order; a dangling reference surfaces as a `USE_CASE_NOT_FOUND` monitoring event naming
2408
+ * the referencing mapping.
2409
+ *
2410
+ */
2411
+ export interface FileProxyDeliveryConfig {
2412
+ /**
2413
+ * Delivery mechanism type
2414
+ */
2415
+ type: "file_proxy";
2416
+ /**
2417
+ * Slug of a `file_proxy` use case with `direction: upload` in the SAME integration.
2418
+ *
2419
+ * example:
2420
+ * wemag_d3_document_upload
2421
+ */
2422
+ use_case_slug: string;
2423
+ }
2424
+ /**
2425
+ * Splits one event into several independent deliveries.
2426
+ *
2427
+ * Mirrors the inbound mapping idiom, where an entity's JSONata expression returning an array
2428
+ * produces one entity update per element. Made explicit with a toggle here because an upload
2429
+ * is also legitimately used without splitting, and because auto-detecting "array means
2430
+ * split" would make a single-element result ambiguous.
2431
+ *
2432
+ * Each resulting delivery is fully independent: its own idempotency record, its own retry
2433
+ * schedule, its own monitoring events. A four-item event can therefore end up three-of-four
2434
+ * delivered, which is the honest state to report.
2435
+ *
2436
+ * The split is evaluated ONCE, when the event is enqueued, so item indices — and therefore
2437
+ * idempotency keys — stay stable across retries.
2438
+ *
2439
+ */
2440
+ export interface FileProxyFanOutConfig {
2441
+ /**
2442
+ * When false (or absent), the event produces exactly one delivery and `$item` is not
2443
+ * bound in `params_mapping`.
2444
+ *
2445
+ */
2446
+ enabled: boolean;
2447
+ /**
2448
+ * JSONata over the event that MUST return an array; one delivery is created per element,
2449
+ * bound as `$item` in `params_mapping`. Required when `enabled` is true.
2450
+ *
2451
+ * Keep this a plain projection — scoping which events are handled at all belongs in the
2452
+ * outbound use case's `event_filter`, not here. A non-array result fails the event with
2453
+ * `FAN_OUT_INVALID_RESULT`; an empty array produces no deliveries and one info-level
2454
+ * `FAN_OUT_EMPTY`, which is the normal outcome for a catch-all subscription seeing an
2455
+ * event with nothing to send.
2456
+ *
2457
+ * example:
2458
+ * event_attachments
2459
+ */
2460
+ split_expression?: string;
2461
+ }
2462
+ /**
2463
+ * A named translation from a value in the event to a value the external system expects.
2464
+ *
2465
+ */
2466
+ export interface FileProxyLookup {
2467
+ /**
2468
+ * JSONata expression over the event producing the lookup key
2469
+ * example:
2470
+ * ticket._purpose_name[0]
2471
+ */
2472
+ source: string;
2473
+ /**
2474
+ * Key-to-value translation table
2475
+ * example:
2476
+ * {
2477
+ * "Zählerstandsmeldung": "Zählerstand",
2478
+ * "Kündigung": "Kündigung"
2479
+ * }
2480
+ */
2481
+ entries: {
2482
+ [name: string]: string;
2483
+ };
2484
+ /**
2485
+ * Value used when the key is absent from `entries`
2486
+ */
2487
+ default?: string;
2488
+ /**
2489
+ * What happens when the key is not in `entries`.
2490
+ * `default` substitutes `default` silently; `warn` substitutes it and emits a
2491
+ * `LOOKUP_UNMAPPED` warning so the gap is visible without stopping delivery;
2492
+ * `fail` aborts the delivery terminally.
2493
+ * Defaults to `default` when a `default` is set, and to `warn` when it is not.
2494
+ *
2495
+ */
2496
+ on_miss?: "default" | "warn" | "fail";
2497
+ }
2323
2498
  export interface FileProxyParam {
2324
2499
  /**
2325
2500
  * Parameter name as it appears in the query string
@@ -2334,6 +2509,11 @@ declare namespace Components {
2334
2509
  */
2335
2510
  description?: string;
2336
2511
  }
2512
+ /**
2513
+ * How to extract the file from the step results. REQUIRED when `direction` is `download`;
2514
+ * rejected when `direction` is `upload` (an upload has no file to extract).
2515
+ *
2516
+ */
2337
2517
  export interface FileProxyResponseConfig {
2338
2518
  /**
2339
2519
  * JSONata expression to extract file content from step results
@@ -2366,7 +2546,7 @@ declare namespace Components {
2366
2546
  /**
2367
2547
  * HTTP method
2368
2548
  */
2369
- method: "GET" | "POST";
2549
+ method: "GET" | "POST" | "PUT" | "PATCH";
2370
2550
  /**
2371
2551
  * Handlebars templates for request headers
2372
2552
  */
@@ -2374,7 +2554,21 @@ declare namespace Components {
2374
2554
  [name: string]: string;
2375
2555
  };
2376
2556
  /**
2377
- * Handlebars template for the request body (POST only)
2557
+ * Handlebars template for the request body (write methods only). On an `upload` use
2558
+ * case this is where the payload is assembled, reading `{{ params.* }}` built by
2559
+ * `params_mapping`, plus `{{ env.* }}` and `{{ steps.N.body }}`.
2560
+ *
2561
+ * **Route every user-controlled value through the `json` helper**: the template engine
2562
+ * does not escape, so `"name":"{{ params.fileName }}"` produces invalid JSON the moment
2563
+ * a filename contains a quote. Write `"name": {{json params.fileName}}` instead — the
2564
+ * helper emits the surrounding quotes itself and renders absent values as `null`. Use
2565
+ * `{{jsonEscape v}}` if you prefer to keep your own quotes. Upload configurations whose
2566
+ * body would break on such input are rejected at save time.
2567
+ *
2568
+ * Handlebars block helpers work, so optional fields can be omitted rather than sent
2569
+ * empty: `{{#if params.pin}},"pin": {{json params.pin}}{{/if}}`. Note that `{{/if}}}`
2570
+ * fails to parse — leave a space before a closing brace: `{{/if}} }`.
2571
+ *
2378
2572
  */
2379
2573
  body?: string;
2380
2574
  /**
@@ -2382,6 +2576,54 @@ declare namespace Components {
2382
2576
  */
2383
2577
  response_type: "json" | "binary";
2384
2578
  }
2579
+ /**
2580
+ * Upload-side settings for a file_proxy use case with `direction: upload`.
2581
+ * Everything about WHAT is sent lives on the outbound mapping
2582
+ * (see `FileProxyDeliveryConfig`); this object only governs HOW the transfer is bounded
2583
+ * and judged.
2584
+ *
2585
+ */
2586
+ export interface FileProxyUploadConfig {
2587
+ /**
2588
+ * Per-file ceiling for this use case, in bytes. Files above it fail terminally with
2589
+ * `FILE_TOO_LARGE` before any bytes are fetched. Defaults to — and is clamped by — the
2590
+ * platform ceiling of 100 MiB (104857600).
2591
+ *
2592
+ */
2593
+ max_file_bytes?: number;
2594
+ /**
2595
+ * Maximum delivery attempts per item before the delivery is marked failed and the
2596
+ * message is dead-lettered. Attempts are spaced by an exponential, jittered backoff
2597
+ * spanning roughly 16 hours over the default 8 attempts, so an ERP maintenance window
2598
+ * does not exhaust them.
2599
+ *
2600
+ * Lives here rather than on the outbound delivery because how hard to retry is a
2601
+ * property of the transport — the same judgement as `max_file_bytes` — and the outbound
2602
+ * delivery is a pure pointer.
2603
+ *
2604
+ */
2605
+ max_delivery_attempts?: number;
2606
+ /**
2607
+ * Optional JSONata predicate evaluated against the final step result
2608
+ * (`{ statusCode, headers, body }`) to decide whether the external system really
2609
+ * accepted the file. When omitted, any 2xx counts as delivered. Use this for systems
2610
+ * that return 200 with an error envelope.
2611
+ *
2612
+ * example:
2613
+ * body.status = 'OK'
2614
+ */
2615
+ success_when?: string;
2616
+ /**
2617
+ * Optional JSONata expression over the step results yielding the external system's
2618
+ * identifier for the stored document. Recorded on the delivery record and on the
2619
+ * `FILE_PROXY_UPLOADED` monitoring event so an operator can find the document in the
2620
+ * target system.
2621
+ *
2622
+ * example:
2623
+ * steps[-1].body.documentId
2624
+ */
2625
+ external_id?: string;
2626
+ }
2385
2627
  /**
2386
2628
  * 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.
2387
2629
  *
@@ -2472,24 +2714,169 @@ declare namespace Components {
2472
2714
  */
2473
2715
  updated_at: string; // date-time
2474
2716
  configuration?: /**
2475
- * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
2717
+ * Configuration for file_proxy use cases. Defines how to authenticate and move files
2718
+ * between epilot and an external document system, in either direction (see `direction`).
2719
+ *
2720
+ * **Download** (`direction: download`, the default) fetches a file from the external system
2721
+ * and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and
2722
+ * either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
2723
+ * The `orgId` is included in the signed URL to establish organization context without
2724
+ * requiring authentication. Additional use-case-specific parameters are declared in the
2725
+ * `params` array. `response` is REQUIRED for download use cases.
2476
2726
  *
2477
- * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
2478
- * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
2479
- * Additional use-case-specific parameters are declared in the `params` array.
2727
+ * **Upload** (`direction: upload`) pushes epilot files to the external system. It is not
2728
+ * reachable over the download endpoint; an outbound use case points at it via a `file_proxy`
2729
+ * delivery, and this configuration owns everything about what gets sent: `fan_out` decides
2730
+ * how many deliveries one event produces, `params_mapping` builds the values, and the
2731
+ * `steps` place those values into requests via `{{ params.* }}`.
2732
+ * `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted.
2733
+ *
2734
+ * OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the
2735
+ * server-side validator, which returns an explicit message naming the offending field.
2480
2736
  *
2481
2737
  */
2482
2738
  FileProxyUseCaseConfiguration;
2483
2739
  }
2484
2740
  /**
2485
- * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
2741
+ * Configuration for file_proxy use cases. Defines how to authenticate and move files
2742
+ * between epilot and an external document system, in either direction (see `direction`).
2743
+ *
2744
+ * **Download** (`direction: download`, the default) fetches a file from the external system
2745
+ * and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and
2746
+ * either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
2747
+ * The `orgId` is included in the signed URL to establish organization context without
2748
+ * requiring authentication. Additional use-case-specific parameters are declared in the
2749
+ * `params` array. `response` is REQUIRED for download use cases.
2750
+ *
2751
+ * **Upload** (`direction: upload`) pushes epilot files to the external system. It is not
2752
+ * reachable over the download endpoint; an outbound use case points at it via a `file_proxy`
2753
+ * delivery, and this configuration owns everything about what gets sent: `fan_out` decides
2754
+ * how many deliveries one event produces, `params_mapping` builds the values, and the
2755
+ * `steps` place those values into requests via `{{ params.* }}`.
2756
+ * `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted.
2486
2757
  *
2487
- * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
2488
- * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
2489
- * Additional use-case-specific parameters are declared in the `params` array.
2758
+ * OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the
2759
+ * server-side validator, which returns an explicit message naming the offending field.
2490
2760
  *
2491
2761
  */
2492
2762
  export interface FileProxyUseCaseConfiguration {
2763
+ /**
2764
+ * Direction of file travel. `download` (default) pulls a file from the external system
2765
+ * into epilot; `upload` pushes an epilot file out to the external system. Omitted means
2766
+ * `download`, so every pre-existing configuration keeps its exact meaning.
2767
+ *
2768
+ * Note this is the direction of the FILE, not the epilot use-case type — an `upload`
2769
+ * file_proxy use case is still a `file_proxy` use case, never an `outbound` one.
2770
+ *
2771
+ */
2772
+ direction?: "download" | "upload";
2773
+ upload?: /**
2774
+ * Upload-side settings for a file_proxy use case with `direction: upload`.
2775
+ * Everything about WHAT is sent lives on the outbound mapping
2776
+ * (see `FileProxyDeliveryConfig`); this object only governs HOW the transfer is bounded
2777
+ * and judged.
2778
+ *
2779
+ */
2780
+ FileProxyUploadConfig;
2781
+ fan_out?: /**
2782
+ * Splits one event into several independent deliveries.
2783
+ *
2784
+ * Mirrors the inbound mapping idiom, where an entity's JSONata expression returning an array
2785
+ * produces one entity update per element. Made explicit with a toggle here because an upload
2786
+ * is also legitimately used without splitting, and because auto-detecting "array means
2787
+ * split" would make a single-element result ambiguous.
2788
+ *
2789
+ * Each resulting delivery is fully independent: its own idempotency record, its own retry
2790
+ * schedule, its own monitoring events. A four-item event can therefore end up three-of-four
2791
+ * delivered, which is the honest state to report.
2792
+ *
2793
+ * The split is evaluated ONCE, when the event is enqueued, so item indices — and therefore
2794
+ * idempotency keys — stay stable across retries.
2795
+ *
2796
+ */
2797
+ FileProxyFanOutConfig;
2798
+ /**
2799
+ * Upload-only, REQUIRED when `direction` is `upload`. JSONata expression evaluated once
2800
+ * per fan-out item, producing the `params` object that step templates read as
2801
+ * `{{ params.* }}`.
2802
+ *
2803
+ * The evaluation root is the hydrated event, so `contact.customer_pin` and
2804
+ * `ticket._purpose` are reachable directly, unprefixed.
2805
+ *
2806
+ * **Everything per-item is a `$`-prefixed JSONata binding**: `$item` (the fan-out
2807
+ * element, absent when `fan_out` is disabled), `$file_base64` and `$file`
2808
+ * (`{filename, mime_type, size_bytes}`) for the resolved file, plus `$constants`,
2809
+ * `$lookups`, `$ack_id`, `$germanDate(iso)` and `$now()`. Writing `item.filename`
2810
+ * instead of `$item.filename` yields nothing — it reads a field named `item` on the
2811
+ * event, which does not exist.
2812
+ *
2813
+ * Must evaluate to an object. `constants` are shallow-merged underneath the result, so
2814
+ * the expression wins on any key collision.
2815
+ *
2816
+ * example:
2817
+ * { "documentType": $lookups.documentType, "fileName": $item.filename, "fileData": $file_base64, "pin": contact.customer_pin }
2818
+ */
2819
+ params_mapping?: string;
2820
+ /**
2821
+ * Upload-only. Named translation tables resolved BEFORE `params_mapping` runs and bound
2822
+ * as `$lookups`, so an expression reads `$lookups.documentType` rather than carrying a
2823
+ * conditional chain. Deliberately generic: the next ERP calls the same concept
2824
+ * `Belegart`.
2825
+ *
2826
+ */
2827
+ lookups?: {
2828
+ [name: string]: /**
2829
+ * A named translation from a value in the event to a value the external system expects.
2830
+ *
2831
+ */
2832
+ FileProxyLookup;
2833
+ };
2834
+ /**
2835
+ * Upload-only. Fixed values shallow-merged UNDERNEATH the `params_mapping` result — the
2836
+ * expression wins on key collisions, constants only add. Use for the unchanging strings
2837
+ * (tenant, sender, channel) that would otherwise be repeated in every expression.
2838
+ *
2839
+ * example:
2840
+ * {
2841
+ * "mandant": "EPILOT_WNG",
2842
+ * "sender": "KSSP"
2843
+ * }
2844
+ */
2845
+ constants?: {
2846
+ [name: string]: any;
2847
+ };
2848
+ /**
2849
+ * Upload-only. JSONata returning the attachment-shaped object (`entity_id`, optionally
2850
+ * `s3ref`) whose bytes should be fetched for this delivery. The evaluation root is the
2851
+ * event; the fan-out element is the `$item` binding, same as in `params_mapping`.
2852
+ *
2853
+ * Usually unnecessary: when the fan-out item is itself attachment-shaped it is used
2854
+ * directly. Supply this only when splitting over something that is not the attachment
2855
+ * — for example one delivery per meter reading, each carrying a file referenced from
2856
+ * elsewhere in the event. When nothing resolves, no file is fetched and `file_base64`
2857
+ * is undefined, which is valid for a fan-out that sends metadata only.
2858
+ *
2859
+ * example:
2860
+ * event_attachments[entity_id = $item.file_id][0]
2861
+ */
2862
+ file_source?: string;
2863
+ /**
2864
+ * Upload-only. Params that MUST be present after `params_mapping` runs. Any listed name
2865
+ * resolving to null or undefined fails the delivery terminally with
2866
+ * `REQUIRED_PARAM_MISSING` before a single step executes.
2867
+ *
2868
+ * This is the generic net behind a lookup's `on_miss: fail`: it catches a required field
2869
+ * going missing for any reason, so the external system never receives a body that is
2870
+ * silently short a field its API requires.
2871
+ *
2872
+ * example:
2873
+ * [
2874
+ * "documentType",
2875
+ * "fileName",
2876
+ * "fileData"
2877
+ * ]
2878
+ */
2879
+ required_params?: string[];
2493
2880
  /**
2494
2881
  * Optional secure proxy attachment for routing all outbound file proxy requests.
2495
2882
  * Only `use_case_slug` is supported and the referenced secure_proxy use case
@@ -2504,22 +2891,37 @@ declare namespace Components {
2504
2891
  };
2505
2892
  auth?: FileProxyAuth;
2506
2893
  /**
2507
- * Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, and useCaseSlug or useCaseId)
2894
+ * Download-only. Additional use-case-specific parameters expected in the download URL
2895
+ * query string (beyond the required orgId, integrationId, and useCaseSlug or useCaseId).
2896
+ * Rejected when `direction` is `upload`.
2897
+ *
2508
2898
  */
2509
2899
  params?: FileProxyParam[];
2510
2900
  /**
2511
- * Additional origins permitted to call /download for this use case (CORS, exact match). Portal origins are always allowed.
2901
+ * Download-only. Additional origins permitted to call /download for this use case
2902
+ * (CORS, exact match). Portal origins are always allowed. Rejected when `direction`
2903
+ * is `upload`.
2904
+ *
2512
2905
  */
2513
2906
  allowed_origins?: string /* uri ^https?:// */[];
2514
2907
  /**
2515
- * Ordered list of HTTP steps to execute to retrieve the file
2908
+ * Ordered list of HTTP steps to execute. For `download` these retrieve the file; for
2909
+ * `upload` they deliver it, each assembling its own request body from `{{ params.* }}`
2910
+ * built by `params_mapping`.
2911
+ *
2516
2912
  */
2517
2913
  steps: [
2518
2914
  FileProxyStep,
2519
2915
  ...FileProxyStep[]
2520
2916
  ];
2521
- response: FileProxyResponseConfig;
2917
+ response?: /**
2918
+ * How to extract the file from the step results. REQUIRED when `direction` is `download`;
2919
+ * rejected when `direction` is `upload` (an upload has no file to extract).
2920
+ *
2921
+ */
2922
+ FileProxyResponseConfig;
2522
2923
  /**
2924
+ * Download-only; rejected when `direction` is `upload`.
2523
2925
  * When `true`, this use case is served via the streaming endpoint: mapped file URLs
2524
2926
  * are built as `/stream/download`, files of any size are streamed inline over HTTP
2525
2927
  * response streaming, and buffered `/download` requests for oversize files are
@@ -2580,11 +2982,25 @@ declare namespace Components {
2580
2982
  */
2581
2983
  type: "file_proxy";
2582
2984
  configuration?: /**
2583
- * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
2985
+ * Configuration for file_proxy use cases. Defines how to authenticate and move files
2986
+ * between epilot and an external document system, in either direction (see `direction`).
2987
+ *
2988
+ * **Download** (`direction: download`, the default) fetches a file from the external system
2989
+ * and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and
2990
+ * either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
2991
+ * The `orgId` is included in the signed URL to establish organization context without
2992
+ * requiring authentication. Additional use-case-specific parameters are declared in the
2993
+ * `params` array. `response` is REQUIRED for download use cases.
2584
2994
  *
2585
- * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
2586
- * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
2587
- * Additional use-case-specific parameters are declared in the `params` array.
2995
+ * **Upload** (`direction: upload`) pushes epilot files to the external system. It is not
2996
+ * reachable over the download endpoint; an outbound use case points at it via a `file_proxy`
2997
+ * delivery, and this configuration owns everything about what gets sent: `fan_out` decides
2998
+ * how many deliveries one event produces, `params_mapping` builds the values, and the
2999
+ * `steps` place those values into requests via `{{ params.* }}`.
3000
+ * `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted.
3001
+ *
3002
+ * OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the
3003
+ * server-side validator, which returns an explicit message naming the offending field.
2588
3004
  *
2589
3005
  */
2590
3006
  FileProxyUseCaseConfiguration;
@@ -4749,6 +5165,49 @@ declare namespace Components {
4749
5165
  */
4750
5166
  expires_at?: string; // date-time
4751
5167
  }
5168
+ /**
5169
+ * Resolution state of one file_proxy mapping's referenced upload use case.
5170
+ *
5171
+ * Because the transport lives on a separate use case, edits to the endpoint or credentials
5172
+ * do not appear in THIS use case's history. `target_updated_at` is the hook that lets an
5173
+ * operator notice a target changed underneath a delivery that started failing.
5174
+ *
5175
+ */
5176
+ export interface OutboundFileProxyTargetStatus {
5177
+ /**
5178
+ * The mapping holding this file_proxy delivery
5179
+ */
5180
+ mapping_id: string;
5181
+ /**
5182
+ * Slug of the referenced file_proxy use case
5183
+ */
5184
+ use_case_slug: string;
5185
+ /**
5186
+ * Whether the slug currently resolves to an enabled `file_proxy` use case with
5187
+ * `direction: upload` in this integration. References are resolved at delivery time,
5188
+ * so `false` is a live warning rather than a save-time error.
5189
+ *
5190
+ */
5191
+ resolved: boolean;
5192
+ /**
5193
+ * Id of the referenced use case — absent when unresolved
5194
+ */
5195
+ target_use_case_id?: string; // uuid
5196
+ /**
5197
+ * Whether the referenced use case is enabled — absent when unresolved
5198
+ */
5199
+ target_enabled?: boolean;
5200
+ /**
5201
+ * When the referenced use case was last modified — absent when unresolved. Surfaced
5202
+ * because a change here is invisible in this use case's own history diff.
5203
+ *
5204
+ */
5205
+ target_updated_at?: string; // date-time
5206
+ /**
5207
+ * Why the reference did not resolve — absent when `resolved` is true
5208
+ */
5209
+ unresolved_reason?: "not_found" | "wrong_type" | "wrong_direction" | "disabled";
5210
+ }
4752
5211
  /**
4753
5212
  * Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings.
4754
5213
  */
@@ -4759,16 +5218,49 @@ declare namespace Components {
4759
5218
  * contract.created
4760
5219
  */
4761
5220
  event_catalog_event: string;
5221
+ /**
5222
+ * JSONata boolean predicate over the hydrated event payload. The use case handles the
5223
+ * event only when this evaluates truthy; when absent it handles every event of its name,
5224
+ * which is the behaviour of every pre-existing configuration.
5225
+ *
5226
+ * This is where event scoping belongs — narrowing to certain ticket purposes, contract
5227
+ * types or channels. Evaluation input is the full hydrated event, so relation nodes such
5228
+ * as `ticket` and `contact` are populated. An expression that throws is treated as no
5229
+ * match and logged, so one malformed filter cannot block the other use cases subscribed
5230
+ * to the same event.
5231
+ *
5232
+ * example:
5233
+ * $count(ticket._purpose[$ in ['bae4b4d1-d728-49ef-92ff-54486dd301b4']]) > 0
5234
+ */
5235
+ event_filter?: string;
4762
5236
  /**
4763
5237
  * List of mappings that transform and deliver the event
4764
5238
  */
4765
5239
  mappings: [
4766
- /* A mapping that delivers an event to an external system — either pushed to a webhook (with a JSONata payload transformation) or made available on the pull-based poll queue (raw event payload, no transformation) */ OutboundMapping,
4767
- .../* A mapping that delivers an event to an external system — either pushed to a webhook (with a JSONata payload transformation) or made available on the pull-based poll queue (raw event payload, no transformation) */ OutboundMapping[]
5240
+ /* A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (raw event payload, no transformation), or handed to a file_proxy use case that uploads files to an external document system (a pointer only; the referenced use case owns the payload and the fan-out) */ OutboundMapping,
5241
+ .../* A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (raw event payload, no transformation), or handed to a file_proxy use case that uploads files to an external document system (a pointer only; the referenced use case owns the payload and the fan-out) */ OutboundMapping[]
4768
5242
  ];
5243
+ /**
5244
+ * Whether this use case participates in the acknowledgement protocol.
5245
+ *
5246
+ * `on` (the default, and the behaviour of every pre-existing use case) records an
5247
+ * ACK_PENDING on each event and expects the consumer to confirm receipt via
5248
+ * `POST /v1/erp/tracking/acknowledgement`; unconfirmed events raise ACK_TIMEOUT after
5249
+ * the timeout window.
5250
+ *
5251
+ * `off` opts the use case out entirely: no tracking row, no ACK_PENDING, no
5252
+ * ACK_TIMEOUT. Set it for consumers that never acknowledge — otherwise every event
5253
+ * produces a guaranteed timeout warning — and for deliveries that already keep their
5254
+ * own durable per-item record, such as `file_proxy`.
5255
+ *
5256
+ * The tracking row is per-event, not per-use-case, so it is suppressed only when EVERY
5257
+ * enabled use case matching the event has opted out.
5258
+ *
5259
+ */
5260
+ ack_tracking?: "on" | "off";
4769
5261
  }
4770
5262
  /**
4771
- * A mapping that delivers an event to an external system — either pushed to a webhook (with a JSONata payload transformation) or made available on the pull-based poll queue (raw event payload, no transformation)
5263
+ * A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (raw event payload, no transformation), or handed to a file_proxy use case that uploads files to an external document system (a pointer only; the referenced use case owns the payload and the fan-out)
4772
5264
  */
4773
5265
  export interface OutboundMapping {
4774
5266
  /**
@@ -4782,7 +5274,7 @@ declare namespace Components {
4782
5274
  */
4783
5275
  name: string;
4784
5276
  /**
4785
- * JSONata expression to transform the event payload. Required for webhook delivery; ignored for poll delivery.
5277
+ * JSONata expression to transform the event payload. Required for webhook delivery, ignored for poll delivery, and rejected for file_proxy delivery — a file_proxy payload is built by the referenced use case's `params_mapping`, so accepting an expression here would silently do nothing.
4786
5278
  * example:
4787
5279
  * { "id": entity._id, "customer": entity.customer_name }
4788
5280
  */
@@ -4791,7 +5283,7 @@ declare namespace Components {
4791
5283
  * Whether this mapping is active
4792
5284
  */
4793
5285
  enabled: boolean;
4794
- delivery: /* Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload) */ DeliveryConfig;
5286
+ delivery: /* Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload); file_proxy = one push per event attachment to an external document system, through a file_proxy use case (JSONata-transformed payload carrying the file bytes) */ DeliveryConfig;
4795
5287
  /**
4796
5288
  * Timestamp when the mapping was created
4797
5289
  */
@@ -5077,6 +5569,20 @@ declare namespace Components {
5077
5569
  *
5078
5570
  */
5079
5571
  OutboundPollStatus;
5572
+ /**
5573
+ * One entry per file_proxy mapping on this use case. Present only on use cases with a
5574
+ * file_proxy delivery mapping.
5575
+ *
5576
+ */
5577
+ file_proxy?: /**
5578
+ * Resolution state of one file_proxy mapping's referenced upload use case.
5579
+ *
5580
+ * Because the transport lives on a separate use case, edits to the endpoint or credentials
5581
+ * do not appear in THIS use case's history. `target_updated_at` is the hook that lets an
5582
+ * operator notice a target changed underneath a delivery that started failing.
5583
+ *
5584
+ */
5585
+ OutboundFileProxyTargetStatus[];
5080
5586
  }
5081
5587
  /**
5082
5588
  * Pull-based queue delivery. Items carry the raw standardized event-catalog payload; no JSONata mapping is applied in poll mode. Consumers fetch and acknowledge items via the poll API.
@@ -6464,11 +6970,25 @@ declare namespace Components {
6464
6970
  */
6465
6971
  type?: "file_proxy";
6466
6972
  configuration?: /**
6467
- * Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.
6973
+ * Configuration for file_proxy use cases. Defines how to authenticate and move files
6974
+ * between epilot and an external document system, in either direction (see `direction`).
6975
+ *
6976
+ * **Download** (`direction: download`, the default) fetches a file from the external system
6977
+ * and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and
6978
+ * either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
6979
+ * The `orgId` is included in the signed URL to establish organization context without
6980
+ * requiring authentication. Additional use-case-specific parameters are declared in the
6981
+ * `params` array. `response` is REQUIRED for download use cases.
6982
+ *
6983
+ * **Upload** (`direction: upload`) pushes epilot files to the external system. It is not
6984
+ * reachable over the download endpoint; an outbound use case points at it via a `file_proxy`
6985
+ * delivery, and this configuration owns everything about what gets sent: `fan_out` decides
6986
+ * how many deliveries one event produces, `params_mapping` builds the values, and the
6987
+ * `steps` place those values into requests via `{{ params.* }}`.
6988
+ * `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted.
6468
6989
  *
6469
- * The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.
6470
- * The `orgId` is included in the signed URL to establish organization context without requiring authentication.
6471
- * Additional use-case-specific parameters are declared in the `params` array.
6990
+ * OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the
6991
+ * server-side validator, which returns an explicit message naming the offending field.
6472
6992
  *
6473
6993
  */
6474
6994
  FileProxyUseCaseConfiguration;
@@ -9622,6 +10142,7 @@ type EnvironmentFieldConfig = Components.Schemas.EnvironmentFieldConfig;
9622
10142
  type ErpEvent = Components.Schemas.ErpEvent;
9623
10143
  type ErpEventV3 = Components.Schemas.ErpEventV3;
9624
10144
  type ErpImportError = Components.Schemas.ErpImportError;
10145
+ type ErpImportFilePreview = Components.Schemas.ErpImportFilePreview;
9625
10146
  type ErpImportIssue = Components.Schemas.ErpImportIssue;
9626
10147
  type ErpImportJob = Components.Schemas.ErpImportJob;
9627
10148
  type ErpImportList = Components.Schemas.ErpImportList;
@@ -9634,10 +10155,14 @@ type ErrorResponseBase = Components.Schemas.ErrorResponseBase;
9634
10155
  type ExecuteErpImportRequest = Components.Schemas.ExecuteErpImportRequest;
9635
10156
  type ExternalMonitoringSpan = Components.Schemas.ExternalMonitoringSpan;
9636
10157
  type FileProxyAuth = Components.Schemas.FileProxyAuth;
10158
+ type FileProxyDeliveryConfig = Components.Schemas.FileProxyDeliveryConfig;
10159
+ type FileProxyFanOutConfig = Components.Schemas.FileProxyFanOutConfig;
10160
+ type FileProxyLookup = Components.Schemas.FileProxyLookup;
9637
10161
  type FileProxyParam = Components.Schemas.FileProxyParam;
9638
10162
  type FileProxyResponseConfig = Components.Schemas.FileProxyResponseConfig;
9639
10163
  type FileProxySecureProxyAttachment = Components.Schemas.FileProxySecureProxyAttachment;
9640
10164
  type FileProxyStep = Components.Schemas.FileProxyStep;
10165
+ type FileProxyUploadConfig = Components.Schemas.FileProxyUploadConfig;
9641
10166
  type FileProxyUrlConfig = Components.Schemas.FileProxyUrlConfig;
9642
10167
  type FileProxyUrlParam = Components.Schemas.FileProxyUrlParam;
9643
10168
  type FileProxyUrlParams = Components.Schemas.FileProxyUrlParams;
@@ -9701,6 +10226,7 @@ type NotificationStatusResponse = Components.Schemas.NotificationStatusResponse;
9701
10226
  type OutboundConflict = Components.Schemas.OutboundConflict;
9702
10227
  type OutboundDlqListResponse = Components.Schemas.OutboundDlqListResponse;
9703
10228
  type OutboundDlqMessage = Components.Schemas.OutboundDlqMessage;
10229
+ type OutboundFileProxyTargetStatus = Components.Schemas.OutboundFileProxyTargetStatus;
9704
10230
  type OutboundIntegrationEventConfiguration = Components.Schemas.OutboundIntegrationEventConfiguration;
9705
10231
  type OutboundMapping = Components.Schemas.OutboundMapping;
9706
10232
  type OutboundMessage = Components.Schemas.OutboundMessage;
@@ -9776,4 +10302,4 @@ type ValidateErpImportRequest = Components.Schemas.ValidateErpImportRequest;
9776
10302
  type WebhookDeliveryConfig = Components.Schemas.WebhookDeliveryConfig;
9777
10303
  type WebhookStatus = Components.Schemas.WebhookStatus;
9778
10304
 
9779
- export { type FileProxySecureProxyAttachment as $, type AccessLogEntry as A, type EntityPruneScopeUpdate as B, type Client as C, type DeleteIntegrationAppMappingRequest as D, type EmbeddedFileProxyUseCaseRequest as E, type EntityUpdate as F, type EnvVarRefConfig as G, type EnvironmentFieldConfig as H, type ErpEvent as I, type ErpEventV3 as J, type ErpImportError as K, type ErpImportIssue as L, type ErpImportJob as M, type ErpImportList as N, type OperationMethods as O, Paths as P, type ErpImportProgress as Q, type ErpImportUseCaseSuggestion as R, type ErpImportValidation as S, type ErpUpdatesEventsV2Request as T, type ErpUpdatesEventsV3Request as U, type ErrorResponseBase as V, type ExecuteErpImportRequest as W, type ExternalMonitoringSpan as X, type FileProxyAuth as Y, type FileProxyParam as Z, type FileProxyResponseConfig as _, Components as a, type OutboundDlqMessage as a$, type FileProxyStep as a0, type FileProxyUrlConfig as a1, type FileProxyUrlParam as a2, type FileProxyUrlParams as a3, type FileProxyUseCase as a4, type FileProxyUseCaseConfiguration as a5, type FileProxyUseCaseHistoryEntry as a6, type GenerateTypesPreviewResponse as a7, type GenerateTypesRequest as a8, type GenerateTypesResponse as a9, type ManagedCallExecuteResponse as aA, type ManagedCallOperation as aB, type ManagedCallOperationConfig as aC, type ManagedCallUseCase as aD, type ManagedCallUseCaseHistoryEntry as aE, type MappingSimulationRequest as aF, type MappingSimulationResponse as aG, type MappingSimulationV2Request as aH, type MappingSimulationWarning as aI, type MeterReadingPruneScopeConfig as aJ, type MeterReadingPruneScopeUpdate as aK, type MeterReadingUpdate as aL, type MeterUniqueIdsConfig as aM, type MonitoringEventV2 as aN, type MonitoringStats as aO, type MonitoringStatsV2 as aP, type MonitoringTraceResponse as aQ, type NotificationChannelSet as aR, type NotificationDigestConfig as aS, type NotificationHistoryItem as aT, type NotificationHistoryResponse as aU, type NotificationRecipient as aV, type NotificationRule as aW, type NotificationRuleStatus as aX, type NotificationStatusResponse as aY, type OutboundConflict as aZ, type OutboundDlqListResponse as a_, type GetMonitoringStatsRequest as aa, type GetMonitoringStatsV2Request as ab, type GetMonitoringTimeSeriesRequest as ac, type GetMonitoringTimeSeriesV2Request as ad, type InboundIntegrationEventConfiguration as ae, type InboundMonitoringEvent as af, type InboundUseCase as ag, type InboundUseCaseHistoryEntry as ah, type IngestExternalMonitoringEventsRequest as ai, type IngestExternalMonitoringEventsResponse as aj, type Integration as ak, type IntegrationAppMapping as al, type IntegrationConfigurationV1 as am, type IntegrationConfigurationV2 as an, type IntegrationEditableFields as ao, type IntegrationEntity as ap, type IntegrationEntityField as aq, type IntegrationFieldV1 as ar, type IntegrationMeterReading as as, type IntegrationNotificationConfig as at, type IntegrationObjectV1 as au, type IntegrationSettings as av, type IntegrationWithUseCases as aw, type ManagedCallAuth as ax, type ManagedCallErrorResponse as ay, type ManagedCallExecuteRequest as az, type PathsDictionary as b, type UpdateUseCaseRequest as b$, type OutboundIntegrationEventConfiguration as b0, type OutboundMapping as b1, type OutboundMessage as b2, type OutboundMonitoringEvent as b3, type OutboundPollStatus as b4, type OutboundStatusResponse as b5, type OutboundUseCase as b6, type OutboundUseCaseHistoryEntry as b7, type OutboundUseCaseStatus as b8, type PollDeliveryConfig as b9, type SecureProxyResponse as bA, type SecureProxySummary as bB, type SecureProxyUpstreamError as bC, type SecureProxyUseCase as bD, type SecureProxyUseCaseConfiguration as bE, type SecureProxyUseCaseHistoryEntry as bF, type SecureProxyWhitelist as bG, type SecureProxyWhitelistUpdate as bH, type SetIntegrationAppMappingRequest as bI, type SuggestErpImportUseCasesResponse as bJ, type TestNotificationRequest as bK, type TestNotificationResponse as bL, type TimeSeriesBreakdownItemV2 as bM, type TimeSeriesBucket as bN, type TimeSeriesBucketV2 as bO, type TriggerErpActionRequest as bP, type TriggerWebhookResp as bQ, type TypeAnnotations as bR, type TypeDescriptor as bS, type UnblockOutboundStreamRequest as bT, type UnblockOutboundStreamResponse as bU, type UpdateFileProxyUseCaseRequest as bV, type UpdateInboundUseCaseRequest as bW, type UpdateIntegrationRequest as bX, type UpdateManagedCallUseCaseRequest as bY, type UpdateOutboundUseCaseRequest as bZ, type UpdateSecureProxyUseCaseRequest as b_, type PollOutboundMessagesRequest as ba, type PollOutboundMessagesResponse as bb, type PortalOrigin as bc, type PortalRefConfig as bd, type PortalRefFilter as be, type PruneScopeConfig as bf, type QueryAccessLogsRequest as bg, type QueryEventsRequest as bh, type QueryInboundMonitoringEventsRequest as bi, type QueryMonitoringEventsV2Request as bj, type QueryOutboundMonitoringEventsRequest as bk, type RedriveOutboundDlqRequest as bl, type RedriveOutboundDlqResponse as bm, type RedriveOutboundDlqResult as bn, type RelationConfig as bo, type RelationItemConfig as bp, type RelationRefItemConfig as bq, type RelationRefValueConfig as br, type RelationRefsConfig as bs, type RelationUniqueIdField as bt, type RepeatableFieldType as bu, type ReplayEventsRequest as bv, type RuleBaselineBucket as bw, type RuleBaselineStatus as bx, type S3Reference as by, type SecureProxyRequest as bz, type AckOutboundMessagesRequest as c, type UpdateUseCaseRequestBase as c0, type UpsertIntegrationWithUseCasesRequest as c1, type UseCase as c2, type UseCaseBase as c3, type UseCaseHistoryEntry as c4, type UseCaseHistoryEntryBase as c5, type UseCaseTypePreview as c6, type ValidateErpImportRequest as c7, type WebhookDeliveryConfig as c8, type WebhookStatus as c9, type AckOutboundMessagesResponse as d, type AckResult as e, type AutoRefreshSettings as f, type CommitTypesRequest as g, type CommitTypesResponse as h, type ConnectorConfig as i, type CreateErpImportRequest as j, type CreateErpImportResponse as k, type CreateFileProxyUseCaseRequest as l, type CreateInboundUseCaseRequest as m, type CreateIntegrationRequest as n, type CreateManagedCallUseCaseRequest as o, type CreateOutboundUseCaseRequest as p, type CreateSecureProxyUseCaseRequest as q, type CreateUseCaseRequest as r, type CreateUseCaseRequestBase as s, type DeliveryConfig as t, type EmbeddedInboundUseCaseRequest as u, type EmbeddedManagedCallUseCaseRequest as v, type EmbeddedOutboundUseCaseRequest as w, type EmbeddedSecureProxyUseCaseRequest as x, type EmbeddedUseCaseRequest as y, type EmbeddedUseCaseRequestBase as z };
10305
+ export { type FileProxyFanOutConfig as $, type AccessLogEntry as A, type EntityPruneScopeUpdate as B, type Client as C, type DeleteIntegrationAppMappingRequest as D, type EmbeddedFileProxyUseCaseRequest as E, type EntityUpdate as F, type EnvVarRefConfig as G, type EnvironmentFieldConfig as H, type ErpEvent as I, type ErpEventV3 as J, type ErpImportError as K, type ErpImportFilePreview as L, type ErpImportIssue as M, type ErpImportJob as N, type OperationMethods as O, Paths as P, type ErpImportList as Q, type ErpImportProgress as R, type ErpImportUseCaseSuggestion as S, type ErpImportValidation as T, type ErpUpdatesEventsV2Request as U, type ErpUpdatesEventsV3Request as V, type ErrorResponseBase as W, type ExecuteErpImportRequest as X, type ExternalMonitoringSpan as Y, type FileProxyAuth as Z, type FileProxyDeliveryConfig as _, Components as a, type NotificationRule as a$, type FileProxyLookup as a0, type FileProxyParam as a1, type FileProxyResponseConfig as a2, type FileProxySecureProxyAttachment as a3, type FileProxyStep as a4, type FileProxyUploadConfig as a5, type FileProxyUrlConfig as a6, type FileProxyUrlParam as a7, type FileProxyUrlParams as a8, type FileProxyUseCase as a9, type IntegrationSettings as aA, type IntegrationWithUseCases as aB, type ManagedCallAuth as aC, type ManagedCallErrorResponse as aD, type ManagedCallExecuteRequest as aE, type ManagedCallExecuteResponse as aF, type ManagedCallOperation as aG, type ManagedCallOperationConfig as aH, type ManagedCallUseCase as aI, type ManagedCallUseCaseHistoryEntry as aJ, type MappingSimulationRequest as aK, type MappingSimulationResponse as aL, type MappingSimulationV2Request as aM, type MappingSimulationWarning as aN, type MeterReadingPruneScopeConfig as aO, type MeterReadingPruneScopeUpdate as aP, type MeterReadingUpdate as aQ, type MeterUniqueIdsConfig as aR, type MonitoringEventV2 as aS, type MonitoringStats as aT, type MonitoringStatsV2 as aU, type MonitoringTraceResponse as aV, type NotificationChannelSet as aW, type NotificationDigestConfig as aX, type NotificationHistoryItem as aY, type NotificationHistoryResponse as aZ, type NotificationRecipient as a_, type FileProxyUseCaseConfiguration as aa, type FileProxyUseCaseHistoryEntry as ab, type GenerateTypesPreviewResponse as ac, type GenerateTypesRequest as ad, type GenerateTypesResponse as ae, type GetMonitoringStatsRequest as af, type GetMonitoringStatsV2Request as ag, type GetMonitoringTimeSeriesRequest as ah, type GetMonitoringTimeSeriesV2Request as ai, type InboundIntegrationEventConfiguration as aj, type InboundMonitoringEvent as ak, type InboundUseCase as al, type InboundUseCaseHistoryEntry as am, type IngestExternalMonitoringEventsRequest as an, type IngestExternalMonitoringEventsResponse as ao, type Integration as ap, type IntegrationAppMapping as aq, type IntegrationConfigurationV1 as ar, type IntegrationConfigurationV2 as as, type IntegrationEditableFields as at, type IntegrationEntity as au, type IntegrationEntityField as av, type IntegrationFieldV1 as aw, type IntegrationMeterReading as ax, type IntegrationNotificationConfig as ay, type IntegrationObjectV1 as az, type PathsDictionary as b, type UpdateFileProxyUseCaseRequest as b$, type NotificationRuleStatus as b0, type NotificationStatusResponse as b1, type OutboundConflict as b2, type OutboundDlqListResponse as b3, type OutboundDlqMessage as b4, type OutboundFileProxyTargetStatus as b5, type OutboundIntegrationEventConfiguration as b6, type OutboundMapping as b7, type OutboundMessage as b8, type OutboundMonitoringEvent as b9, type RepeatableFieldType as bA, type ReplayEventsRequest as bB, type RuleBaselineBucket as bC, type RuleBaselineStatus as bD, type S3Reference as bE, type SecureProxyRequest as bF, type SecureProxyResponse as bG, type SecureProxySummary as bH, type SecureProxyUpstreamError as bI, type SecureProxyUseCase as bJ, type SecureProxyUseCaseConfiguration as bK, type SecureProxyUseCaseHistoryEntry as bL, type SecureProxyWhitelist as bM, type SecureProxyWhitelistUpdate as bN, type SetIntegrationAppMappingRequest as bO, type SuggestErpImportUseCasesResponse as bP, type TestNotificationRequest as bQ, type TestNotificationResponse as bR, type TimeSeriesBreakdownItemV2 as bS, type TimeSeriesBucket as bT, type TimeSeriesBucketV2 as bU, type TriggerErpActionRequest as bV, type TriggerWebhookResp as bW, type TypeAnnotations as bX, type TypeDescriptor as bY, type UnblockOutboundStreamRequest as bZ, type UnblockOutboundStreamResponse as b_, type OutboundPollStatus as ba, type OutboundStatusResponse as bb, type OutboundUseCase as bc, type OutboundUseCaseHistoryEntry as bd, type OutboundUseCaseStatus as be, type PollDeliveryConfig as bf, type PollOutboundMessagesRequest as bg, type PollOutboundMessagesResponse as bh, type PortalOrigin as bi, type PortalRefConfig as bj, type PortalRefFilter as bk, type PruneScopeConfig as bl, type QueryAccessLogsRequest as bm, type QueryEventsRequest as bn, type QueryInboundMonitoringEventsRequest as bo, type QueryMonitoringEventsV2Request as bp, type QueryOutboundMonitoringEventsRequest as bq, type RedriveOutboundDlqRequest as br, type RedriveOutboundDlqResponse as bs, type RedriveOutboundDlqResult as bt, type RelationConfig as bu, type RelationItemConfig as bv, type RelationRefItemConfig as bw, type RelationRefValueConfig as bx, type RelationRefsConfig as by, type RelationUniqueIdField as bz, type AckOutboundMessagesRequest as c, type UpdateInboundUseCaseRequest as c0, type UpdateIntegrationRequest as c1, type UpdateManagedCallUseCaseRequest as c2, type UpdateOutboundUseCaseRequest as c3, type UpdateSecureProxyUseCaseRequest as c4, type UpdateUseCaseRequest as c5, type UpdateUseCaseRequestBase as c6, type UpsertIntegrationWithUseCasesRequest as c7, type UseCase as c8, type UseCaseBase as c9, type UseCaseHistoryEntry as ca, type UseCaseHistoryEntryBase as cb, type UseCaseTypePreview as cc, type ValidateErpImportRequest as cd, type WebhookDeliveryConfig as ce, type WebhookStatus as cf, type AckOutboundMessagesResponse as d, type AckResult as e, type AutoRefreshSettings as f, type CommitTypesRequest as g, type CommitTypesResponse as h, type ConnectorConfig as i, type CreateErpImportRequest as j, type CreateErpImportResponse as k, type CreateFileProxyUseCaseRequest as l, type CreateInboundUseCaseRequest as m, type CreateIntegrationRequest as n, type CreateManagedCallUseCaseRequest as o, type CreateOutboundUseCaseRequest as p, type CreateSecureProxyUseCaseRequest as q, type CreateUseCaseRequest as r, type CreateUseCaseRequestBase as s, type DeliveryConfig as t, type EmbeddedInboundUseCaseRequest as u, type EmbeddedManagedCallUseCaseRequest as v, type EmbeddedOutboundUseCaseRequest as w, type EmbeddedSecureProxyUseCaseRequest as x, type EmbeddedUseCaseRequest as y, type EmbeddedUseCaseRequestBase as z };