@celigo/api-specs 0.2.45 → 0.2.47

package/dist/export.yml

@@ -12683,6 +12683,13 @@ components:
               There are two main parsing strategies available:
               - **Automatic parsing**: Simple but produces more complex output
               - **Custom parsing**: More control over the resulting JSON structure
+            x-celigo-ai-guidance:
+              - |-
+                With V0_json false, an empty element (`<FirstName></FirstName>`, `<FirstName/>`) parses to
+                an empty object `{}` under every setting here, not an empty string. A Handlebars template
+                that outputs the field renders `[object Object]`; guard it with
+                `{{#if (eq (typeOf FirstName) "string")}}{{FirstName}}{{/if}}` — a bare `{{#if FirstName}}`
+                does not skip it because `{}` is truthy.
             properties:
               V0_json:
                 type: boolean
@@ -12704,22 +12711,29 @@ components:
               listNodes:
                 type: array
                 description: |
-                  Specifies which XML nodes should be treated as arrays (lists) in the output JSON.
-
-                  It's not always possible to automatically determine if an XML node should be a single value
-                  or an array. Use this field to explicitly identify nodes that should be treated as arrays,
-                  even if they appear only once in the XML.
-
-                  Each entry should be a simplified XPath expression pointing to the node that should be
-                  treated as an array.
-
-                  Only relevant when V0_json is set to false (Custom parsing).
+                  Paths of elements that always parse as arrays. An element that can repeat parses as an
+                  object when it occurs once and as an array when it occurs more than once, so list every
+                  repeating element here to give each record the same shape regardless of item count.
+                  Each entry is the element's full path from the record element selected by the resource
+                  path (from the document root when there is no resource path), with an optional leading
+                  slash. Only relevant when V0_json is set to false (Custom parsing).
                 items:
                   type: string
                 examples:
                   - - /product-lineitems/product-lineitem
                     - /shipping-lineitems/shipping-lineitem
                     - /shipments/shipment
+                x-celigo-ai-guidance:
+                  - |-
+                    Add every element that can repeat. Left out, a one-item record parses it as an object:
+                    a Handlebars `{{#each}}` over it iterates the object's fields (each field reference
+                    renders empty) and mappings or filters written against an array find nothing.
+                  - |-
+                    Write the full path from the record element: `Items/LineItemInfo` for records at
+                    resource path `/Orders/Order`. A bare descendant name (`LineItemInfo`) or a
+                    document-rooted path (`/Orders/Order/Items/LineItemInfo`) matches nothing while a
+                    resource path is set; without a resource path the path must start at the document
+                    root. `//Element` descendant paths never match.
               includeNodes:
                 type: array
                 description: |

package/dist/integration.yml

@@ -725,7 +725,9 @@ paths:
         '400':
           description: |-
             Revision is not in a diffable state. Error code `invalid_revision_state`. Occurs on
-            snapshot revisions (no source to diff against), `canceled` revisions (diff dropped), and
+            snapshot revisions (no source to diff against), `canceled` revisions (diff dropped),
+            `failed` revisions (read their cause from
+            `GET /v1/integrations/{_id}/revisions/{_revisionId}/errors` instead), and
             `inprogress` revisions whose install steps haven't materialized yet.
           content:
             application/json:
@@ -741,6 +743,79 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/revisions/{_revisionId}/errors:
+    get:
+      x-internal: false
+      operationId: listIntegrationRevisionErrors
+      tags:
+        - Integrations
+      summary: List a failed revision's errors
+      description: |-
+        Returns the error records recorded while a `pull` or `revert` revision was being applied — the
+        same list the Revisions tab shows for a `failed` revision. Read this, not the diff, to learn why
+        a revision failed: `GET /v1/integrations/{_id}/revisions/{_revisionId}/diff` rejects `failed`
+        revisions with `invalid_revision_state`. Only `failed` revisions have error records; every
+        other state is rejected with the same `invalid_revision_state` code.
+
+        Each record names the resource the apply step rejected. Ids inside a message use the revision's
+        change-set keys: a `LifeCycleError` of the form `<type> - <id> references a deleted resource:
+        <type> - <id>.deleted` reports that the merged document still points at an entry the same change
+        set marks `.deleted`. The suffix is that marker, not the resource's state in the account — the
+        resource may still exist there.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _revisionId
+          in: path
+          required: true
+          description: Revision id. Must be a revision in `failed` state.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a28d2af6d42eb08f8e863e7
+      responses:
+        '200':
+          description: Error records for the failed revision.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevisionErrorsResponse'
+              examples:
+                deleted_reference:
+                  summary: Pull rejected because the merged integration references a removed lookup cache
+                  value:
+                    - _id: 6aaceb3c8b19ac878dd7cd41
+                      code: LifeCycleError
+                      message: integration - 6a90467b117405485e64787e references a deleted resource:lookupcache - 6aa912fd3ec91536bee07e41.deleted.
+                      createdAt: '2026-09-18T07:41:37.675Z'
+        '400':
+          description: |-
+            Revision is not in `failed` state, so it has no error records. Error code
+            `invalid_revision_state` — returned for `completed`, `canceled`, and `inprogress` revisions
+            of every type, including snapshots.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_revision_state:
+                  value:
+                    errors:
+                      - message: Failed to perform operation. Revision is in an invalid state
+                        code: invalid_revision_state
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
   /v1/integrations/{_id}/errors:
     get:
       x-internal: false
@@ -4515,7 +4590,7 @@ components:
           x-enumDescriptions:
             inprogress: The revision is currently being prepared and can be diffed, applied, or canceled.
             completed: The revision has been finalized and applied successfully.
-            failed: The revision encountered an error during processing.
+            failed: The apply step rejected the revision; the recorded errors are returned by `GET /v1/integrations/{_id}/revisions/{_revisionId}/errors`.
             canceled: The revision was aborted before being applied.
         description:
           type: string
@@ -4541,6 +4616,14 @@ components:
             `revert` revisions.
           examples:
             - 7d9e2b4a1c3f5068ab82d4e0fc16937255ab8c40
+        errorFileKey:
+          type: string
+          readOnly: true
+          description: |-
+            Storage key of the error file written when the apply step fails. Present only on `failed`
+            revisions; the file's records are read through `GET /v1/integrations/{_id}/revisions/{_revisionId}/errors`.
+          examples:
+            - a574f7e1294645f68e141ac6ab4eed92
         _revertToRevisionId:
           type: string
           format: objectId
@@ -4615,6 +4698,43 @@ components:
         before/after blocks. Treated as an opaque envelope here; specific field layout is not guaranteed
         stable across platform versions.
       additionalProperties: true
+    RevisionError:
+      type: object
+      description: One error recorded while a revision was being applied.
+      required:
+        - code
+        - message
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Error record id; the Revisions tab uses it to open the record's detail view.
+          examples:
+            - 6aaceb3c8b19ac878dd7cd41
+        code:
+          type: string
+          description: Error class assigned by the apply step, such as `LifeCycleError` for change-set consistency failures.
+          examples:
+            - LifeCycleError
+        message:
+          type: string
+          description: |-
+            Human-readable cause. Resource references inside it use the change set's own ids, so a
+            `<id>.deleted` suffix identifies an entry of the revision, not the state of the resource in
+            the account.
+          examples:
+            - integration - 6a90467b117405485e64787e references a deleted resource:lookupcache - 6aa912fd3ec91536bee07e41.deleted.
+        createdAt:
+          type: string
+          format: date-time
+          description: When the error was recorded.
+          examples:
+            - '2026-09-18T07:41:37.675Z'
+    RevisionErrorsResponse:
+      type: array
+      description: Error records for one revision, oldest first.
+      items:
+        $ref: '#/components/schemas/RevisionError'
     IntegrationErrorsResponse:
       type: array
       description: |-

package/dist/processor.yml

@@ -195,9 +195,14 @@ paths:
                                     items:
                                       type: string
                                     description: |-
-                                      Element names that should always be arrays in the
-                                      output, even when containing a single item. Only
-                                      active when `V0_json` is `false`.
+                                      Paths of elements that always parse as arrays. An
+                                      element that occurs once otherwise parses as an
+                                      object, and as an array only when it repeats. Each
+                                      entry is the element's full path from the record
+                                      element selected by `resourcePath` (from the
+                                      document root when `resourcePath` is unset), with
+                                      an optional leading slash; `//` descendant paths do
+                                      not match. Only active when `V0_json` is `false`.
                                   includeNodes:
                                     type: array
                                     items:

package/dist/tool.yml

@@ -35639,6 +35639,13 @@ components:
               There are two main parsing strategies available:
               - **Automatic parsing**: Simple but produces more complex output
               - **Custom parsing**: More control over the resulting JSON structure
+            x-celigo-ai-guidance:
+              - |-
+                With V0_json false, an empty element (`<FirstName></FirstName>`, `<FirstName/>`) parses to
+                an empty object `{}` under every setting here, not an empty string. A Handlebars template
+                that outputs the field renders `[object Object]`; guard it with
+                `{{#if (eq (typeOf FirstName) "string")}}{{FirstName}}{{/if}}` — a bare `{{#if FirstName}}`
+                does not skip it because `{}` is truthy.
             properties:
               V0_json:
                 type: boolean
@@ -35660,22 +35667,29 @@ components:
               listNodes:
                 type: array
                 description: |
-                  Specifies which XML nodes should be treated as arrays (lists) in the output JSON.
-
-                  It's not always possible to automatically determine if an XML node should be a single value
-                  or an array. Use this field to explicitly identify nodes that should be treated as arrays,
-                  even if they appear only once in the XML.
-
-                  Each entry should be a simplified XPath expression pointing to the node that should be
-                  treated as an array.
-
-                  Only relevant when V0_json is set to false (Custom parsing).
+                  Paths of elements that always parse as arrays. An element that can repeat parses as an
+                  object when it occurs once and as an array when it occurs more than once, so list every
+                  repeating element here to give each record the same shape regardless of item count.
+                  Each entry is the element's full path from the record element selected by the resource
+                  path (from the document root when there is no resource path), with an optional leading
+                  slash. Only relevant when V0_json is set to false (Custom parsing).
                 items:
                   type: string
                 examples:
                   - - /product-lineitems/product-lineitem
                     - /shipping-lineitems/shipping-lineitem
                     - /shipments/shipment
+                x-celigo-ai-guidance:
+                  - |-
+                    Add every element that can repeat. Left out, a one-item record parses it as an object:
+                    a Handlebars `{{#each}}` over it iterates the object's fields (each field reference
+                    renders empty) and mappings or filters written against an array find nothing.
+                  - |-
+                    Write the full path from the record element: `Items/LineItemInfo` for records at
+                    resource path `/Orders/Order`. A bare descendant name (`LineItemInfo`) or a
+                    document-rooted path (`/Orders/Order/Items/LineItemInfo`) matches nothing while a
+                    resource path is set; without a resource path the path must start at the document
+                    root. `//Element` descendant paths never match.
               includeNodes:
                 type: array
                 description: |

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "fc7b08d",
-		"generatedAt": "2026-09-22"
+		"iasCommit": "f237220",
+		"generatedAt": "2026-09-23"
 	},
 	"roots": {
 		"aiagent": 133,