@celigo/api-specs 0.2.152 → 0.2.154

package/dist/enduser.yml

@@ -2200,7 +2200,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -2237,16 +2237,21 @@ components:
               type: boolean
               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.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -3221,15 +3226,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -3445,9 +3453,11 @@ components:
           - "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.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-

package/dist/export.yml

@@ -12518,6 +12518,12 @@ components:
             - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
               '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
+            - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+              `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+              path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+              need no brackets (`$.Ship To Name`, `$.Tracking #`)
+            - Filter expressions such as `$.items[?(@.active)]` fail the record with
+              "Eval [?(expr)] prevented in JSONPath expression."
 
             ```json
             "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -12706,6 +12712,12 @@ components:
             **Usage**
 
             The lookupName refers to a named lookup defined in the lookups array of the same resource.
+            On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+            is dropped on save. On an import, a name that matches no lookup fails every record
+            with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+            doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+            the field left out, lets the record succeed with the lookup's `default`, or without
+            the mapped field when there is none.
 
             ```json
             {
@@ -13043,6 +13055,11 @@ components:
                   The system creates special composite objects during processing to maintain
                   hierarchical relationships, allowing easy access to both the current array item
                   and its parent contexts.
+
+                  An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                  element per item, with no error. Child extracts drop the `[*]` but keep the
+                  array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                  element-relative `$.sku` reads the record root instead of the element.
                 examples:
                   - $.items[*]
                   - $.order.lineItems[*]
@@ -13254,14 +13271,17 @@ components:
           type: string
           description: |
             **Purpose**
-            Required on every mapping entry. Controls whether the mapping is applied.
+            Controls whether the mapping is applied. Send it on every mapping entry.
 
             **Guidance**
             Only `Active` rows run. `Draft` and `Inactive` rows keep their
             configuration, are saved with minimal validation, and are skipped at
             runtime and in preview; a non-Active parent skips its whole subtree
-            whatever its children say. The API rejects a mapping missing this field
-            (validation error: "Mapping object must have status field present.").
+            whatever its children say. Imports (on save and in the mapper processor)
+            and API response mappings reject a row missing this field (validation
+            error: "Mapping object must have status field present."); a Tool's
+            output mapping saves and runs one, which is why `required` doesn't
+            list it.
           x-celigo-ai-guidance:
             - |-
               Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -13584,6 +13604,12 @@ components:
               - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
                 '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
+              - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+                `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+                path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+                need no brackets (`$.Ship To Name`, `$.Tracking #`)
+              - Filter expressions such as `$.items[?(@.active)]` fail the record with
+                "Eval [?(expr)] prevented in JSONPath expression."
 
               ```json
               "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -13772,6 +13798,12 @@ components:
               **Usage**
 
               The lookupName refers to a named lookup defined in the lookups array of the same resource.
+              On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+              is dropped on save. On an import, a name that matches no lookup fails every record
+              with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+              doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+              the field left out, lets the record succeed with the lookup's `default`, or without
+              the mapped field when there is none.
 
               ```json
               {
@@ -14109,6 +14141,11 @@ components:
                     The system creates special composite objects during processing to maintain
                     hierarchical relationships, allowing easy access to both the current array item
                     and its parent contexts.
+
+                    An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                    element per item, with no error. Child extracts drop the `[*]` but keep the
+                    array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                    element-relative `$.sku` reads the record root instead of the element.
                   examples:
                     - $.items[*]
                     - $.order.lineItems[*]
@@ -14320,14 +14357,17 @@ components:
             type: string
             description: |
               **Purpose**
-              Required on every mapping entry. Controls whether the mapping is applied.
+              Controls whether the mapping is applied. Send it on every mapping entry.
 
               **Guidance**
               Only `Active` rows run. `Draft` and `Inactive` rows keep their
               configuration, are saved with minimal validation, and are skipped at
               runtime and in preview; a non-Active parent skips its whole subtree
-              whatever its children say. The API rejects a mapping missing this field
-              (validation error: "Mapping object must have status field present.").
+              whatever its children say. Imports (on save and in the mapper processor)
+              and API response mappings reject a row missing this field (validation
+              error: "Mapping object must have status field present."); a Tool's
+              output mapping saves and runs one, which is why `required` doesn't
+              list it.
             x-celigo-ai-guidance:
               - |-
                 Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -14698,8 +14738,8 @@ components:
               - Original value indicators: "{Original Value}", "No mapping found"
               - Neutral values: "Other", "N/A", "Miscellaneous"
 
-              If allowFailures is false and no default is specified, the flow will fail
-              when encountering unmapped values.
+              If allowFailures is false, a record whose value is unmapped fails and the default
+              is ignored.
             examples:
               - Unknown
               - Other
@@ -14720,7 +14760,11 @@ components:
               This field determines how the system handles source values that don't exist in the map:
 
               - true: Use the default value for missing mappings and continue processing
-              - false: Treat missing mappings as errors, failing the record
+              - false: Treat missing mappings as errors, failing the record (`lookup_error` for a
+                static map, `lookupcache_evaluation_failed` for a lookup cache)
+              - omitted or null: the record doesn't fail either. On an import a static lookup writes
+                its default if it has one, and a static or cache lookup without one leaves the
+                mapped field out of the output, with no error
 
               **Recommendation**
 
@@ -14734,11 +14778,14 @@ components:
               - All possible source values are known and controlled
               - Missing mappings indicate serious data problems that should be addressed
 
-              The best practice is typically to set allowFailures to true with a meaningful
-              default value, so flows remain operational while alerting you to missing mappings.
+              A default raises no error: records that miss go out with the default value and
+              nothing reports them. Use true only when that fallback is acceptable at the
+              destination, and set false explicitly when a missing value must stop the record.
             examples:
               - true
               - false
+            x-celigo-ai-guidance:
+              - 'Never leave this field out to mean "fail on a miss": on an import, an omitted or null value lets a missing key through without an error (with the default, or without the mapped field when there is none). Only an explicit false fails the record.'
     Transform:
       type: object
       description: |

package/dist/guardrail.yml

@@ -1985,7 +1985,7 @@ components:
           description: When true, the mapped value cannot be overwritten by later mapping steps.
         lookupName:
           type: string
-          description: Name of an entry in the import's `lookups` array used to translate the value.
+          description: Name of an entry in the import's `lookups` array (`http.lookups` on an HTTP import) used to translate the value.
           x-celigo-ai-guidance:
             - |-
               Name of a lookup defined on ``resource.lookups`` whose result

package/dist/iclient.yml

@@ -491,6 +491,8 @@ paths:
         Permanently deletes an iClient. Blocked while any connection references
         it, including a deleted connection still in the recycle bin: purge that
         connection with `DELETE /v1/recycleBinTTL/connections/{_id}` first.
+        `GET /v1/iclients/{_id}/dependencies` doesn't list a binned connection,
+        so an empty dependency list doesn't mean the delete will succeed.
       operationId: deleteIClient
       tags:
         - iClients
@@ -1623,68 +1625,12 @@ components:
                 endpoint response body.
               x-celigo-ai-guidance:
                 - |-
-                  ## FIELD BEHAVIOR:
-                  - Defines the endpoint path for access token requests in the OAuth2 flow.
-                  - Must be a valid relative URL path starting with a forward slash (/).
-                  - Used during the token exchange phase after obtaining an authorization code or other grant types.
-                  - Typically combined with the authorization server's base URL to form the complete token endpoint URL.
-                - |-
-                  Specifies the relative URL path on the OAuth2 authorization server where the
-                  access token request should be sent.
-                  This path is appended to the base URL of the authorization server to form the
-                  full endpoint for obtaining an access token during the OAuth2 authentication
-                  flow.
-                  It is essential for enabling clients to exchange authorization grants for access
-                  tokens securely.
-                - |-
-                  ## IMPORTANT NOTES:
-                  - This path is critical for the OAuth2 token exchange process; incorrect configuration will prevent successful authentication.
-                  - It should not include the full URL, only the path component.
-                  - Must align with the OAuth2 server's documentation to ensure interoperability.
-                  - Often used in conjunction with other OAuth2 properties like client ID, client secret, and authorization path.
-                - |-
-                  ## DEPENDENCY CHAIN:
-                  - Depends on the base URL of the OAuth2 authorization server.
-                  - Used alongside authorizationPath and other OAuth2 configuration properties.
-                  - Integral to the OAuth2 token grant process.
-                - |-
-                  ## EXAMPLES:
-                  - /oauth2/token
-                  - /api/v1/access_token
-                  - /auth/token
-                - |-
-                  ## IMPLEMENTATION GUIDANCE:
-                  - Ensure the path corresponds exactly to the OAuth2 server's token endpoint specification.
-                  - Validate that the path is correctly formatted and accessible.
-                  - Avoid including query parameters or fragments in this path; it should be a clean URL path.
-                  - Confirm compatibility with the OAuth2 server's expected token endpoint URL structure.
-                - |-
-                  ## TECHNICAL DETAILS:
-                  - Expected to be a URI path string.
-                  - Should begin with a forward slash (/).
-                  - Combined with the OAuth2 server's base URL to form the full token endpoint URI.
-                  - Utilized in HTTP POST requests to obtain access tokens.
-                - |-
-                  Specifies the relative URL path on the OAuth2 authorization server where the
-                  access token request should be sent.
-                  This path is appended to the base URL of the authorization server to form the
-                  full endpoint for obtaining an access token during the OAuth2 authentication
-                  flow.
-                  It is essential for enabling clients to exchange authorization grants for access
-                  tokens securely.
-                - |-
-                  Specifies the relative URL path on the OAuth2 authorization server where the
-                  access token request should be sent.
-                  This path is appended to the base URL of the authorization server to form the
-                  full endpoint for obtaining an access token during the OAuth2 authentication
-                  flow.
-                  It is essential for enabling clients to exchange authorization grants for access
-                  tokens securely.
+                  A path into the token endpoint's JSON response — `access_token`, or
+                  `data.access_token` when the provider nests it — never a URL or an endpoint path.
+                  The token endpoint itself is `token.uri`.
               examples:
                 - access_token
-                - /oauth2/token
-                - /api/v1/access_token
-                - /auth/token
+                - data.access_token
             refreshTokenPath:
               type: string
               description: |-
@@ -1692,72 +1638,12 @@ components:
                 endpoint response body.
               x-celigo-ai-guidance:
                 - |-
-                  ## IMPORTANT NOTES:
-                  - This path is distinct from the initial token request endpoint.
-                  - The refresh token flow requires that the client has previously obtained a refresh token.
-                  - Not all OAuth 2.0 providers support refresh tokens; verify compatibility.
-                  - The endpoint must support secure communication protocols (e.g., HTTPS).
-                - |-
-                  ## EXAMPLES:
-                  - "/oauth2/token/refresh"
-                  - "https://auth.example.com/oauth2/token"
-                  - "/api/v1/auth/refresh-token"
-                - |-
-                  ## DEPENDENCY CHAIN:
-                  - Depends on the existence of a valid refresh token issued during initial authentication.
-                  - Works in conjunction with the access token and client credentials.
-                  - Related to the OAuth 2.0 token endpoint configuration.
-                - |-
-                  The relative or absolute URL path used to request a refresh token from the OAuth
-                  2.0 authorization server.
-                  This endpoint is typically called when the current access token has expired or
-                  is about to expire,
-                  allowing the client to obtain a new access token without requiring the user to re-authenticate.
-                  The path should conform to the OAuth 2.0 specification for token refresh
-                  requests and support the necessary HTTP methods,
-                  usually POST.
-                - |-
-                  ## TECHNICAL DETAILS:
-                  - Typically uses the HTTP POST method with form-encoded parameters.
-                  - Requires parameters such as grant_type=refresh_token and the refresh_token itself.
-                  - Responses include a new access token and optionally a new refresh token.
-                  - Must handle scopes and token expiration as per OAuth 2.0 standards.
-                - |-
-                  ## IMPLEMENTATION GUIDANCE:
-                  - Ensure the path is correctly formatted as a relative or absolute URL.
-                  - Confirm that the authorization server supports refresh token requests at this endpoint.
-                  - Secure the endpoint with appropriate authentication and authorization measures.
-                  - Validate that the client credentials and refresh token are correctly handled during the request.
-                  - Handle error responses gracefully, such as invalid or expired refresh tokens.
-                - |-
-                  ## FIELD BEHAVIOR:
-                  - Specifies the endpoint for refreshing OAuth 2.0 access tokens.
-                  - Used by the client application to maintain authenticated sessions seamlessly.
-                  - Invoked automatically by the client when the access token expires or is near expiration.
-                  - Must be accessible and correctly configured on the authorization server.
-                - |-
-                  The relative or absolute URL path used to request a refresh token from the OAuth
-                  2.0 authorization server.
-                  This endpoint is typically called when the current access token has expired or
-                  is about to expire,
-                  allowing the client to obtain a new access token without requiring the user to re-authenticate.
-                  The path should conform to the OAuth 2.0 specification for token refresh
-                  requests and support the necessary HTTP methods,
-                  usually POST.
-                - |-
-                  The relative or absolute URL path used to request a refresh token from the OAuth
-                  2.0 authorization server.
-                  This endpoint is typically called when the current access token has expired or
-                  is about to expire,
-                  allowing the client to obtain a new access token without requiring the user to re-authenticate.
-                  The path should conform to the OAuth 2.0 specification for token refresh
-                  requests and support the necessary HTTP methods,
-                  usually POST.
+                  A path into the token endpoint's JSON response — `refresh_token`, or
+                  `data.refresh_token` when the provider nests it — never a URL or an endpoint path.
+                  The refresh endpoint itself is `refresh.uri`.
               examples:
                 - refresh_token
-                - /oauth2/token/refresh
-                - https://auth.example.com/oauth2/token
-                - /api/v1/auth/refresh-token
+                - data.refresh_token
             scheme:
               type: string
               description: Authorization scheme prefix (e.g. `Bearer`, `Basic`).