@celigo/api-specs 0.2.139 → 0.2.141

package/dist/export.yml

@@ -6127,7 +6127,12 @@ components:
               - The connection is a cloud file provider used in FOLDER mode (Google Drive, Box, Dropbox,
                 Azure Blob Storage, Google Cloud Storage, Celigo Storage): the export reads the files
                 in a folder and the 'file' object's `type` (csv, json, xml, xlsx, filedefinition)
-                parses each one into records — the same file layer as an FTP or S3 export
+                parses each one into records — the same file layer as an FTP or S3 export. In folder
+                mode `relativeURI` is a folder path: an API endpoint path there fails the run with
+                "Directory is not found. Please create one and provide the path." To download one
+                file per record through the provider's API instead, leave `http.type` unset, set the
+                export's top-level `type` to `blob` (typically on a lookup) and point `relativeURI`
+                at the file-download endpoint
 
               Examples of when to set type: "file":
               - "Download PDF invoices from the API" → type: "file"
@@ -6262,7 +6267,10 @@ components:
           x-celigo-agent:
             - handlebars
           x-celigo-handlebars-context: pre-mapped
-          description: 'Resource path appended to the connection''s `baseURI` to form the complete request URL. Path segments, query parameters, or the entire value can be built with handlebars expressions for endpoints determined at runtime. For lookup exports (`isLookup: true`) with mappings configured, handlebars always render against the original pre-mapped input record, so fields removed or renamed by mappings remain available for URI construction. On `NetSuiteHTTPExport` the base URL is derived from the NetSuite connection and `nsDomainType`, so the path starts at `/services/rest/...` or `/app/site/hosting/restlet.nl`.'
+          description: |-
+            Resource path appended to the connection's `baseURI` to form the complete request URL. Path segments, query parameters, or the entire value can be built with handlebars expressions for endpoints determined at runtime. For lookup exports (`isLookup: true`) with mappings configured, handlebars always render against the original pre-mapped input record, so fields removed or renamed by mappings remain available for URI construction. On `NetSuiteHTTPExport` the base URL is derived from the NetSuite connection and `nsDomainType`, so the path starts at `/services/rest/...` or `/app/site/hosting/restlet.nl`.
+
+            Leave it empty to call the connection's `baseURI` exactly; `/` appends a trailing slash, which is a different URL. An export saved with an empty relative URI and no `http.body` comes back from reads without its `http` block, so a PUT built from such a read loses the stored settings: send the complete `http` block with every PUT.
           x-celigo-ai-guidance:
             - The resource path portion of the API endpoint used for this export.
             - |-
@@ -11121,7 +11129,7 @@ components:
                   webstore: Triggered by SuiteCommerce web store transactions.
                   userevent: Triggered by user event script executions.
                   mapreduce: Triggered by Map/Reduce script operations.
-                  restlet: Triggered by RESTlet API calls.
+                  restlet: Triggered by RESTlet API calls, including the records a NetSuite Distributed import writes.
                   webapplication: Triggered by web application interactions.
                   restwebservices: Triggered by REST web services API calls.
             disabled:
@@ -11129,7 +11137,9 @@ components:
               description: |-
                 When true, the listener's NetSuite deployment is inactive and record saves no longer
                 trigger the export. Maintained by the platform as the flow is disabled and re-enabled;
-                re-enabling the flow re-registers the deployment.
+                re-enabling the flow re-registers the deployment. A listener is created disabled, and
+                a flow created already enabled leaves it that way until a flow update sets
+                `disabled: false`, which activates it within seconds.
               x-celigo-ai-guidance:
                 - |-
                   Pause a listener by disabling its flow, not by setting this field. A listener that has
@@ -12752,7 +12762,7 @@ components:
             **When to Use**
             - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
             - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
-            - NEVER used with simple types (string, number, boolean, date)
+            - NEVER used with simple types (string, number, boolean)
 
             **Behavior**
             - Each mapping in this array becomes a property of the parent object
@@ -13818,7 +13828,7 @@ components:
               **When to Use**
               - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
               - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
-              - NEVER used with simple types (string, number, boolean, date)
+              - NEVER used with simple types (string, number, boolean)
 
               **Behavior**
               - Each mapping in this array becomes a property of the parent object
@@ -16365,14 +16375,11 @@ components:
 
               **Lookup Exports (isLookup: true)**: Transforms the lookup results returned by the external system.
 
-              ## CRITICAL REQUIREMENT FOR LOOKUPS
+              ## LOOKUPS
 
-              For NetSuite and most other API-based lookups, this field is **ESSENTIAL**. Raw lookup results often come in nested or complex formats that differ from what the flow requires. You **MUST** use a transform to:
-              1. Flatten nested structures (e.g., `results[0].id` -> `id`)
-              2. Map specific fields to the top level
-              3. Handle empty results gracefully
+              Optional on lookups; use one to flatten nested results (e.g., `results[0].id` -> `id`). A lookup's response mapping reads the transformed records, so its extracts name the transformed fields (`data[0].id`), not the raw response paths.
 
-              Note that transformed results are not automatically merged back into source records - merging is handled separately by the 'response mapping' configuration in your flow definition.
+              Transformed results are not merged back into source records automatically; the flow's response mapping does that.
         hooks:
           type: object
           description: |-

package/dist/import.yml

@@ -8496,7 +8496,7 @@ components:
           without the array); a mapping reshapes the message instead.
         - |-
           Publishing is not limited to flows. Verified surfaces: a flow step; an API step (the API
-          invoked at `POST /apis/{version}/{relativeURI}`); a Tool reached through a `ToolImport`
+          invoked at `POST /apis/{version}{relativeURI}`); a Tool reached through a `ToolImport`
           step in a flow; and `POST /v1/imports/{_id}/invoke` with `{"data": [record, ...]}`. A flow
           or API test run (`/test/run`) publishes nothing — import steps are mocked there.
       properties:
@@ -12929,7 +12929,7 @@ components:
             **When to Use**
             - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
             - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
-            - NEVER used with simple types (string, number, boolean, date)
+            - NEVER used with simple types (string, number, boolean)
 
             **Behavior**
             - Each mapping in this array becomes a property of the parent object
@@ -13995,7 +13995,7 @@ components:
               **When to Use**
               - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
               - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
-              - NEVER used with simple types (string, number, boolean, date)
+              - NEVER used with simple types (string, number, boolean)
 
               **Behavior**
               - Each mapping in this array becomes a property of the parent object
@@ -16493,8 +16493,9 @@ components:
             - array
             - string
           description: |-
-            Sample response payload used to preview response mappings and test downstream steps
-            without calling the destination system.
+            Sample destination response kept with the import for authoring its response mapping.
+            Flow test runs and previews don't read it; they substitute `mockResponse`, or a
+            placeholder when none is saved.
         responseTransform:
           x-celigo-agent:
             - transform
@@ -16622,7 +16623,9 @@ components:
           description: |-
             Field mappings that transform incoming records into the destination system's field
             structure — renaming fields, converting types, building nested objects, and applying
-            formulas or lookups to derive values.
+            formulas or lookups to derive values. The mapped output builds only the request this
+            import sends: the next step receives the record as it arrived here, plus whatever this
+            step's response mapping merges back.
           x-celigo-ai-guidance:
             - |-
               ## Extract evaluation root

package/dist/mcp-server.yml

@@ -15,7 +15,7 @@ info:
       - Contains a collection of **tools** (referencing Tool resources), **APIs** (referencing builder-mode API resources), **prompts** (inline reusable templates), and **resources** (Celigo Storage files served to clients)
       - Can be enabled or disabled at both the server level and individual tool/API level
       - Supports MCP annotations on tools for hinting behavior (read-only, idempotent, destructive, etc.)
-      - Supports tool overrides for customizing connections, exports, imports, and routing per-server
+      - Binds the connections each tool's steps run on, per server (`tools[].overrides`); calls fail with "Missing connection overrides" until every lookup step's connection is bound
       - Exposes prompts via `prompts/list` and `prompts/get` with Handlebars-style argument substitution
       - Carries **permission sets** ("Capability Sets" in the UI) — named bundles of its tools, APIs, prompts, and resources granted to end users via `pset:<_id>` capability strings on end-user, group, and role resource grants
       - Carries optional **traffic limits** (`policies[]`) — a server-level rate limit, a per-user rate limit for OAuth end users, and a usage quota — enforced before a tool runs; a rejected call gets HTTP 429 with `Retry-After`
@@ -176,7 +176,7 @@ paths:
                   name: Customer Integration MCP
                   relativeURI: /customers
               with_tool:
-                summary: With a tool and Celigo OAuth
+                summary: With a tool (its lookup step bound) and Celigo OAuth
                 value:
                   name: Customer Integration MCP
                   relativeURI: /customers
@@ -188,6 +188,10 @@ paths:
                       disabled: false
                       annotations:
                         readOnlyHint: true
+                      overrides:
+                        exports:
+                          - _abstractId: 69d462d5b9c28ea0b7f82530
+                            _id: 69d462d5b9c28ea0b7f82530
                   oauth:
                     useCeligoOauth: true
       responses:
@@ -1564,12 +1568,27 @@ components:
     Overrides:
       type: object
       description: |
-        Per-server overrides for a tool's internal resources.
+        Per-server bindings for a tool's steps, applied on this server without changing the
+        Tool itself.
 
-        When a tool is added to an MCP server, its connections, exports, imports,
-        and routers can be customized for this specific server context without
-        modifying the underlying tool definition. This enables reusing the same
-        tool across multiple MCP servers with different configurations.
+        Each lookup (export) step's connection must be bound here, or each `tools/call` fails
+        with "Missing connection overrides. The following connection IDs must be overridden: …".
+        The export and router fields described below as not applied are stored but don't change
+        a call.
+      x-celigo-ai-guidance:
+        - |-
+          Bind each lookup step with an `exports[]` entry whose `_abstractId` and `_id` are both
+          the step's export id; add `_connectionId` to run that step on another connection. An
+          entry with `_connectionId` but no `_id` returns a 404, and binding only some of the
+          Tool's steps still fails the call with "Missing connection overrides".
+        - |-
+          A `connections[]` pair binds only when `_id` names a different connection than
+          `_abstractId`; it then re-maps the steps that use that connection. An identity pair
+          (`_abstractId` equal to `_id`) on a connection that doesn't require end-user
+          credentials leaves the steps unbound. When a step has both, its `exports[]` entry wins.
+        - |-
+          `connections[]` ids aren't validated on save, and the server caches its configuration,
+          so a saved change can take tens of seconds to reach `tools/call`.
       properties:
         connections:
           type: array
@@ -1619,9 +1638,9 @@ components:
         exports:
           type: array
           description: |
-            Export (lookup) overrides. Customize export resources used within the tool,
-            including connection bindings, scheduling, response mappings, and
-            adaptor-specific settings.
+            Export (lookup) step bindings. The binding (`_abstractId`, `_id`, and optionally
+            `_connectionId`) is applied to calls; the settings marked below as not applied are
+            stored but ignored.
           items:
             type: object
             properties:
@@ -1666,25 +1685,27 @@ components:
                   simple: Basic export that fetches all matching records on each run.
                   blob: Binary large object export for file-based data.
                   all: Export that retrieves all records without filtering.
-                description: Override the export type
+                description: Export type override. Not applied on an MCP server; stored, but calls ignore it.
               pageSize:
                 type: number
-                description: Override the page size for pagination
+                description: Page size override. Not applied on an MCP server; stored, but calls ignore it.
                 examples:
                   - 100
               skipRetries:
                 type: boolean
-                description: When true, skips retries on failure.
-                x-celigo-ai-guidance:
-                  - Whether to skip retries on failure
+                description: |-
+                  When true, skips retries on failure. Not applied on an MCP server; stored, but
+                  calls ignore it.
               proceedOnFailure:
                 type: boolean
-                description: When true, continues processing subsequent records after a failure.
-                x-celigo-ai-guidance:
-                  - Whether to continue processing on failure
+                description: |-
+                  When true, continues processing subsequent records after a failure. Not applied
+                  on an MCP server; stored, but calls ignore it.
               responseMapping:
                 type: object
-                description: Override the response field mappings
+                description: |-
+                  Response field mappings override. Not applied on an MCP server; stored, but calls
+                  ignore it.
                 properties:
                   fields:
                     type: array
@@ -1847,8 +1868,8 @@ components:
         routers:
           type: array
           description: |
-            Router overrides. Customize routing behavior for specific branches
-            within the tool, including branch filters and routing strategies.
+            Router overrides. On an MCP server `name`, `routeRecordsTo` and branch
+            `inputFilter` are stored but not applied to calls.
           items:
             type: object
             properties:
@@ -1859,7 +1880,7 @@ components:
                   - router_001
               name:
                 type: string
-                description: Override the router name
+                description: Router name override. Not applied on an MCP server; stored, but calls ignore it.
                 examples:
                   - route_by_region
               routeRecordsTo:
@@ -1870,7 +1891,7 @@ components:
                 x-enumDescriptions:
                   first_matching_branch: Routes each record to only the first branch whose criteria match.
                   all_matching_branches: Routes each record to every branch whose criteria match, creating copies.
-                description: Override the routing strategy
+                description: Routing strategy override. Not applied on an MCP server; stored, but calls ignore it.
               routeRecordsUsing:
                 type: string
                 enum:
@@ -1917,7 +1938,9 @@ components:
                         - Records routed to the North America region
                     inputFilter:
                       type: object
-                      description: Override the branch filter criteria
+                      description: |-
+                        Branch filter override. Not applied on an MCP server; stored, but calls
+                        ignore it.
                       properties:
                         version:
                           type: string
@@ -4040,7 +4063,11 @@ components:
               $ref: '#/components/schemas/AIDescription'
             offline:
               type: boolean
-              description: When true, the connection has been taken offline and is skipped during flow execution.
+              description: |-
+                When true, the connection has been taken offline and is skipped during flow execution.
+                The platform tests the connection after a create or `PUT` and updates this shortly
+                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
+                read it again a few seconds after the write.
               readOnly: true
             needsAuthorization:
               type: boolean

package/dist/tool.yml

@@ -1224,8 +1224,9 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            The Tool ran but a step failed. Includes `invocationId` when logging is active, so
-            the failed run can be opened in the run history.
+            A step failed, or the Tool was refused before any step ran because its branches
+            don't all merge back (`tool_dangling_branch`). Either way the response includes
+            `invocationId` when logging is active, so the run can be opened in the run history.
           content:
             application/json:
               schema:
@@ -2398,6 +2399,11 @@ paths:
         `GET /v1/tools/{_id}/test/run/{runId}/{_stepId}` to inspect stage-by-stage
         results. The run id for follow-up calls is the `flowJob._id` value.
 
+        A test run is not free of outside calls: lookups call their sources live. Imports never
+        send; each returns its saved `mockResponse`, or a placeholder response when none is saved
+        (see `mockResponse` on imports). A second test run started while one is still running is
+        refused with `test_run_not_allowed`.
+
         Test runs are a separate, short-lived history from normal runs — capture
         any follow-up step or log details soon after the run completes.
       operationId: testRunTool
@@ -2520,7 +2526,14 @@ paths:
                         status: completed
                         numError: 1
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: |-
+            The run was refused before any step ran. A Tool with no steps fails with
+            `tool_empty_router`, and one whose branches don't all merge back with
+            `tool_dangling_branch`; re-running the same document fails the same way.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -3894,7 +3907,7 @@ components:
             **When to Use**
             - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
             - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
-            - NEVER used with simple types (string, number, boolean, date)
+            - NEVER used with simple types (string, number, boolean)
 
             **Behavior**
             - Each mapping in this array becomes a property of the parent object
@@ -4960,7 +4973,7 @@ components:
               **When to Use**
               - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
               - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
-              - NEVER used with simple types (string, number, boolean, date)
+              - NEVER used with simple types (string, number, boolean)
 
               **Behavior**
               - Each mapping in this array becomes a property of the parent object
@@ -7433,7 +7446,11 @@ components:
               $ref: '#/components/schemas/AIDescription'
             offline:
               type: boolean
-              description: When true, the connection has been taken offline and is skipped during flow execution.
+              description: |-
+                When true, the connection has been taken offline and is skipped during flow execution.
+                The platform tests the connection after a create or `PUT` and updates this shortly
+                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
+                read it again a few seconds after the write.
               readOnly: true
             needsAuthorization:
               type: boolean
@@ -19863,7 +19880,7 @@ components:
           without the array); a mapping reshapes the message instead.
         - |-
           Publishing is not limited to flows. Verified surfaces: a flow step; an API step (the API
-          invoked at `POST /apis/{version}/{relativeURI}`); a Tool reached through a `ToolImport`
+          invoked at `POST /apis/{version}{relativeURI}`); a Tool reached through a `ToolImport`
           step in a flow; and `POST /v1/imports/{_id}/invoke` with `{"data": [record, ...]}`. A flow
           or API test run (`/test/run`) publishes nothing — import steps are mocked there.
       properties:
@@ -25353,8 +25370,9 @@ components:
             - array
             - string
           description: |-
-            Sample response payload used to preview response mappings and test downstream steps
-            without calling the destination system.
+            Sample destination response kept with the import for authoring its response mapping.
+            Flow test runs and previews don't read it; they substitute `mockResponse`, or a
+            placeholder when none is saved.
         responseTransform:
           x-celigo-agent:
             - transform
@@ -25482,7 +25500,9 @@ components:
           description: |-
             Field mappings that transform incoming records into the destination system's field
             structure — renaming fields, converting types, building nested objects, and applying
-            formulas or lookups to derive values.
+            formulas or lookups to derive values. The mapped output builds only the request this
+            import sends: the next step receives the record as it arrived here, plus whatever this
+            step's response mapping merges back.
           x-celigo-ai-guidance:
             - |-
               ## Extract evaluation root
@@ -30510,7 +30530,12 @@ components:
               - The connection is a cloud file provider used in FOLDER mode (Google Drive, Box, Dropbox,
                 Azure Blob Storage, Google Cloud Storage, Celigo Storage): the export reads the files
                 in a folder and the 'file' object's `type` (csv, json, xml, xlsx, filedefinition)
-                parses each one into records — the same file layer as an FTP or S3 export
+                parses each one into records — the same file layer as an FTP or S3 export. In folder
+                mode `relativeURI` is a folder path: an API endpoint path there fails the run with
+                "Directory is not found. Please create one and provide the path." To download one
+                file per record through the provider's API instead, leave `http.type` unset, set the
+                export's top-level `type` to `blob` (typically on a lookup) and point `relativeURI`
+                at the file-download endpoint
 
               Examples of when to set type: "file":
               - "Download PDF invoices from the API" → type: "file"
@@ -30645,7 +30670,10 @@ components:
           x-celigo-agent:
             - handlebars
           x-celigo-handlebars-context: pre-mapped
-          description: 'Resource path appended to the connection''s `baseURI` to form the complete request URL. Path segments, query parameters, or the entire value can be built with handlebars expressions for endpoints determined at runtime. For lookup exports (`isLookup: true`) with mappings configured, handlebars always render against the original pre-mapped input record, so fields removed or renamed by mappings remain available for URI construction. On `NetSuiteHTTPExport` the base URL is derived from the NetSuite connection and `nsDomainType`, so the path starts at `/services/rest/...` or `/app/site/hosting/restlet.nl`.'
+          description: |-
+            Resource path appended to the connection's `baseURI` to form the complete request URL. Path segments, query parameters, or the entire value can be built with handlebars expressions for endpoints determined at runtime. For lookup exports (`isLookup: true`) with mappings configured, handlebars always render against the original pre-mapped input record, so fields removed or renamed by mappings remain available for URI construction. On `NetSuiteHTTPExport` the base URL is derived from the NetSuite connection and `nsDomainType`, so the path starts at `/services/rest/...` or `/app/site/hosting/restlet.nl`.
+
+            Leave it empty to call the connection's `baseURI` exactly; `/` appends a trailing slash, which is a different URL. An export saved with an empty relative URI and no `http.body` comes back from reads without its `http` block, so a PUT built from such a read loses the stored settings: send the complete `http` block with every PUT.
           x-celigo-ai-guidance:
             - The resource path portion of the API endpoint used for this export.
             - |-
@@ -35504,7 +35532,7 @@ components:
                   webstore: Triggered by SuiteCommerce web store transactions.
                   userevent: Triggered by user event script executions.
                   mapreduce: Triggered by Map/Reduce script operations.
-                  restlet: Triggered by RESTlet API calls.
+                  restlet: Triggered by RESTlet API calls, including the records a NetSuite Distributed import writes.
                   webapplication: Triggered by web application interactions.
                   restwebservices: Triggered by REST web services API calls.
             disabled:
@@ -35512,7 +35540,9 @@ components:
               description: |-
                 When true, the listener's NetSuite deployment is inactive and record saves no longer
                 trigger the export. Maintained by the platform as the flow is disabled and re-enabled;
-                re-enabling the flow re-registers the deployment.
+                re-enabling the flow re-registers the deployment. A listener is created disabled, and
+                a flow created already enabled leaves it that way until a flow update sets
+                `disabled: false`, which activates it within seconds.
               x-celigo-ai-guidance:
                 - |-
                   Pause a listener by disabling its flow, not by setting this field. A listener that has
@@ -37346,14 +37376,11 @@ components:
 
               **Lookup Exports (isLookup: true)**: Transforms the lookup results returned by the external system.
 
-              ## CRITICAL REQUIREMENT FOR LOOKUPS
+              ## LOOKUPS
 
-              For NetSuite and most other API-based lookups, this field is **ESSENTIAL**. Raw lookup results often come in nested or complex formats that differ from what the flow requires. You **MUST** use a transform to:
-              1. Flatten nested structures (e.g., `results[0].id` -> `id`)
-              2. Map specific fields to the top level
-              3. Handle empty results gracefully
+              Optional on lookups; use one to flatten nested results (e.g., `results[0].id` -> `id`). A lookup's response mapping reads the transformed records, so its extracts name the transformed fields (`data[0].id`), not the raw response paths.
 
-              Note that transformed results are not automatically merged back into source records - merging is handled separately by the 'response mapping' configuration in your flow definition.
+              Transformed results are not merged back into source records automatically; the flow's response mapping does that.
         hooks:
           type: object
           description: |-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.139",
+  "version": "0.2.141",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [