@celigo/api-specs 0.2.149 → 0.2.151

package/dist/ai-agent.yml

@@ -5689,19 +5689,27 @@ components:
       properties:
         function:
           type: string
-          description: Function to invoke within the referenced script.
+          description: |-
+            Function to invoke: one in the script named by `_scriptId`, or one the code deployed on
+            the stack named by `_stackId` exposes.
           examples:
             - transformRecords
         _scriptId:
           type: string
           format: objectId
           x-celigo-refModel: scripts
-          description: Script containing the hook function named in `function`.
+          description: Script containing the hook function named in `function`. Send this or `_stackId`, not both.
         _stackId:
           type: string
           format: objectId
           x-celigo-refModel: stacks
-          description: Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+          description: |-
+            Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+            The API doesn't enforce the either/or: a save carrying both `_scriptId` and `_stackId`
+            answers 200 and stores both, and the script and the stack then each list the step as a
+            dependent.
+          x-celigo-ai-guidance:
+            - When moving a hook onto a stack, remove `_scriptId` and set `function` to the stack's function in the same update.
         configuration:
           type:
             - object

package/dist/api.yml

@@ -1683,12 +1683,19 @@ paths:
 
         The response carries a `metadata` map keyed by step id (each value is the ordered list of
         stage names that ran for that step), the parent `flowJob`, and the per-step `childJobs[]`.
-        Inspect a specific step's stages with `GET /v1/apis/{_id}/test/run/{runId}/{_stepId}`, where
-        `runId` is the parent `flowJob._id`.
+        The response the run selected appears in `metadata` too, keyed by its `id` (`success`,
+        `fail`, or a custom response's `id`). Inspect a specific step's stages with
+        `GET /v1/apis/{_id}/test/run/{runId}/{_stepId}`, where `runId` is the parent `flowJob._id`.
 
         Test-run invocations do **not** surface in `GET /v1/apis/{_id}/logs`.
 
-        A test run is not free of outside calls: lookups call their sources live. Imports never
+        A test run is not free of outside calls: a lookup export with no saved `mockOutput` calls
+        its source live, and the run then saves that response on the export as its `mockOutput`
+        (the export's `lastModified` changes). Every later test run that uses the export, from any
+        API or Tool and whatever its request, answers that lookup from the saved `mockOutput`
+        instead of calling the source: the lookup's `request` stage shows the request rendered
+        from the new record, and its `response` stage holds the saved records. Remove `mockOutput`
+        from the export to call the source again. Real calls to the API don't read it. Imports never
         send; each returns its saved `mockResponse`, or a placeholder response when none is saved
         (see `mockResponse` on imports).
 
@@ -1748,10 +1755,10 @@ paths:
                 summary: Run without test input (the first step gets an empty record)
                 value: {}
               withMockRequest:
-                summary: Run with an explicit test request
+                summary: Run with an explicit test request (only the body reaches the first step)
                 value:
                   mockRequest:
-                    queryParams:
+                    body:
                       sku: SKU-001
       responses:
         '200':
@@ -1765,7 +1772,8 @@ paths:
                     type: object
                     description: |-
                       Map keyed by step id; each value is the ordered list of stage names that ran for
-                      that step.
+                      that step. The selected response is one of the keys (`success`, `fail`, or a
+                      custom response's `id`), so it names the response the run returned.
                     additionalProperties:
                       type: array
                       items:
@@ -1787,6 +1795,11 @@ paths:
                         - parse
                       main:
                         - router
+                      apiRouter:
+                        - router
+                      success:
+                        - mapping
+                        - response
                     flowJob:
                       _id: 6a2e23bbcf5b64ca6b93b757
                       type: flow
@@ -2793,8 +2806,9 @@ components:
           type: object
           description: |-
             Sample request saved with the API for testing. `POST /v1/apis/{_id}/test/run` doesn't
-            read it; send it as that call's `mockRequest`. A test run still makes outside calls:
-            its lookups call their sources live.
+            read it; send it as that call's `mockRequest`. A test run still makes outside calls: a
+            lookup with no saved `mockOutput` calls its source live, and the run saves that response
+            as the lookup's `mockOutput`, which later test runs answer from.
           properties:
             body:
               type: object
@@ -2813,9 +2827,10 @@ components:
             - |-
               Saving a mockRequest doesn't make test runs use it: a test run without its own
               mockRequest starts from an empty record. A test run isn't free of outside calls
-              either: lookups run live, and only imports are kept from sending (each returns its
-              mockResponse or a placeholder). Can include body, headers, pathParams, and
-              queryParams.
+              either: a lookup without a saved mockOutput runs live (and the run then saves its
+              response as that mockOutput), and only imports are kept from sending (each returns
+              its mockResponse or a placeholder). Can include body, headers, pathParams, and
+              queryParams; only the body reaches the record the steps see.
         transform:
           type: object
           description: |-
@@ -3269,17 +3284,19 @@ components:
             - fail
             - custom
           x-enumDescriptions:
-            success: Default response returned when the API operation completes successfully.
-            fail: Default response returned when the API operation encounters an error.
-            custom: Additional response for specific scenarios, routed via the response router.
-          description: Response type.
+            success: The happy-path response; returned when it's the first response, in list order, whose `inputFilter` matches.
+            fail: The error response; returned when a step fails and that step's `proceedOnFailure` is off.
+            custom: Additional response for specific scenarios, selected by its own `inputFilter`.
+          description: |-
+            Response type. `success` isn't a fallback checked after the `custom` responses: list
+            `custom` responses before it (see `inputFilter`).
           examples:
             - success
           x-celigo-ai-guidance:
             - |-
-              - **success**: Default response for successful operations (required, exactly one)
-              - **fail**: Default response for errors (required, exactly one)
-              - **custom**: Additional responses for specific scenarios (optional, multiple allowed)
+              - **success**: Response for successful operations (required, exactly one)
+              - **fail**: Response for errors (required, exactly one)
+              - **custom**: Additional responses for specific scenarios (optional, multiple allowed), listed before `success`
         statusCode:
           type: integer
           minimum: 100
@@ -3320,7 +3337,13 @@ components:
                   - Content type of the response body
         inputFilter:
           type: object
-          description: Filter criteria for response selection by the response router.
+          description: |-
+            Filter criteria for response selection by the response router, which returns the first
+            response in `responses` whose filter matches. A response without an `inputFilter` matches
+            every request, so a `success` listed first answers requests a later `custom` filter
+            matches; the typed `context.success` filter doesn't prevent that, because
+            `context.success` is true whenever no step failed, including when a lookup found nothing.
+            A step that fails with `proceedOnFailure` off selects the `fail` response.
           properties:
             version:
               type: string
@@ -3334,19 +3357,20 @@ components:
               description: Celigo expression-based filter rules.
               items: {}
               examples:
-                - - equals
-                  - - boolean
-                    - - context
-                      - success
-                  - true
+                - - empty
+                  - - string
+                    - - extract
+                      - customerId
                 - - and
-                  - - equals
-                    - - get
-                      - statusCode
-                    - 200
-                  - - exists
-                    - - get
-                      - data
+                  - - notempty
+                    - - string
+                      - - extract
+                        - orderId
+                  - - greaterthan
+                    - - number
+                      - - extract
+                        - amount
+                    - 1000
               x-celigo-ai-guidance:
                 - |-
                   Array-based DSL where the first element is an operator (e.g., "equals", "and", "or"),
@@ -3552,6 +3576,9 @@ components:
           - Exactly one 'success' response (for successful operations)
           - Exactly one 'fail' response (for errors)
           - Zero or more 'custom' responses (for specific scenarios)
+          The response router returns the first response whose `inputFilter` matches, and a
+          response without one matches every request, so list the 'custom' responses ahead of
+          'success'.
     Builder:
       type: object
       description: Builder-mode configuration defining request structure, routing, and response mapping.
@@ -3573,13 +3600,16 @@ components:
           type: array
           description: |-
             Response configurations. Must include exactly one `success` and one `fail`
-            response; additional `custom` responses are optional.
+            response; additional `custom` responses are optional. Order matters: the response
+            router returns the first response whose `inputFilter` matches, and a response without
+            one matches every request.
           items:
             $ref: '#/components/schemas/ApiResponse'
           x-celigo-ai-guidance:
             - |-
               Must include exactly one 'success' response and one 'fail' response.
-              Additional custom responses can be added for specific scenarios.
+              Additional custom responses can be added for specific scenarios; list them before
+              'success', which otherwise answers the requests their filters match.
       x-celigo-ai-guidance:
         - |-
           The builder mode allows you to define your API using visual configuration:
@@ -6336,7 +6366,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -6465,7 +6500,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -7056,7 +7091,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -9262,7 +9301,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location:

package/dist/connection.yml

@@ -5196,7 +5196,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -5325,7 +5330,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -5916,7 +5921,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -8122,7 +8131,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location:

package/dist/enduser.yml

@@ -3308,7 +3308,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -3437,7 +3442,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -4028,7 +4033,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -6234,7 +6243,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location: