@celigo/api-specs 0.2.169 → 0.2.171

package/dist/tool.yml

@@ -13387,12 +13387,25 @@ components:
               Use `assistant_graphql` as the default value if there is a connector available
               for the system and the connector supports GraphQL.
             - |-
-              The value selects the editor only. Each `http.body[]` entry stays a template STRING — a
+              The value selects the editor and changes one thing in a GraphQL request: under
+              `graph_ql` and `assistant_graphql`, a `variables` member stored as a JSON string is
+              parsed and sent as an object, while under `http` it is sent as the string; an object
+              `variables` goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with import
+              previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
+            - |-
+              Each `http.body[]` entry stays a template STRING — a
               stringified `{"query", "operationName", "variables"}` envelope, one per operation for the
               update/create pair (`http.body[0]` / `http.body[1]`); never an object entry, which is stored
               as-is and does not render. The GraphQL form parses that string to show each member in its
               own field and re-stringifies it on save; an entry that is not parseable JSON at rest renders
-              those fields empty, so keep templated variables inside a JSON string value.
+              those fields empty, so keep templated variables inside a JSON string value. When
+              `variables` is itself a JSON string, the string values inside it sit two JSON levels
+              deep: write them as `\"{{jsonEncode record.x}}\"` with double braces, because a plain
+              `{{record.x}}`, or a triple-brace `jsonEncode`, fails a record whose value holds a quote
+              with 422 `invalid_json` before the request is sent. An object or array there is
+              `{{jsonSerialize record.x}}`, also with double braces; `{{{jsonSerialize record.x}}}`
+              fails the same way (live-verified 2026-10-22).
             - |-
               Create GraphQL imports on a `graph_ql` connection (or a connector connection bound to its
               GraphQL API): that setup offers the Form view toggle between the GraphQL editor and the
@@ -14209,13 +14222,20 @@ components:
 
                 Each entry is a DOT-PATH STRING, or null for an operation
                 with no ID path configured. When not specified, the platform
-                looks for standard `id` or `_id` fields automatically.
+                looks for standard `id` or `_id` fields automatically. When
+                set, a response with no value at the path fails the record
+                with `missing_id`, quoting the response.
               x-celigo-ai-guidance:
                 - |-
                   Common LLM mistake:
                   splitting a single dot-path like ``"data.id"`` into array segments ``["data",
                   "id"]`` — DO NOT do this.
                   See the ``response`` object docs above.
+                - |-
+                  For a GraphQL mutation, point it at the id only a successful call returns
+                  (``["data.customerCreate.customer.id"]``): a 200 that carries top-level ``errors``
+                  or the mutation's ``userErrors`` then fails the record with ``missing_id`` instead
+                  of counting as written. Live-verified 2026-10-22 against an echo endpoint.
               examples:
                 - - id
                 - - data.id
@@ -14289,11 +14309,23 @@ components:
                 available, set both — the platform evaluates ``successPath``
                 first and falls through to ``failPath`` only when the
                 success check is inconclusive.
+
+                Without ``failValues``, a truthy value at the path fails
+                the response. A path that resolves to an array matches only
+                when the array has exactly one element.
+              x-celigo-ai-guidance:
+                - |-
+                  A GraphQL API usually reports a failed mutation with HTTP 200 and an ``errors`` array, which
+                  counts as written when no rule catches it. ``failPath: ["errors"]`` fails the record
+                  for one error and lets two or more through; use ``["errors[0].message"]`` with
+                  ``errorPath: "errors[0].message"`` so the record fails with the server's message.
+                  Live-verified 2026-10-22 with import runs against an echo endpoint.
               examples:
                 - - error
                 - - success
                 - - error
                   - error
+                - - errors[0].message
             failValues:
               type: array
               items:
@@ -21181,7 +21213,7 @@ components:
                       x-enumDescriptions:
                         text: Free-form text response from the model.
                         json_schema: Structured JSON output conforming to a defined schema.
-                        blob: Binary data output for non-text content.
+                        blob: Image generation — the run calls the image generation tool and returns the stored image's `blobKey`, not `_text` or `_json`.
                       default: text
                       description: Output format type.
                     schemaMode:
@@ -21403,11 +21435,6 @@ components:
                               an object without a non-empty name fails with a
                               missing-required-field error. String entries are the
                               legacy form and stay valid.
-                      allowedPrompts:
-                        type: array
-                        description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                        items:
-                          type: string
                   tool:
                     type: object
                     description: |
@@ -21550,7 +21577,7 @@ components:
                   x-enumDescriptions:
                     text: Free-form text response from the model.
                     json_schema: Structured JSON output conforming to a defined schema.
-                    blob: Binary data output for non-text content.
+                    blob: Image generation — the run returns the stored image's `blobKey`, not `_text` or `_json`.
                   default: text
                 schemaMode:
                   type: string
@@ -21719,11 +21746,6 @@ components:
                                       description: Display description shown for the tool.
                                   required:
                                     - name
-                              allowedPrompts:
-                                type: array
-                                description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                                items:
-                                  type: string
                           tool:
                             type: object
                             description: Reference to a Celigo Tool resource, used when type is "tool".
@@ -22236,9 +22258,9 @@ components:
         LLM configuration for an `ai_agent` guardrail — which provider and model evaluate each
         record, with instructions, parameter tuning, and output format. Guardrails never invoke
         tools, so unlike an AI agent import no block here accepts a `tools` array. MCP `prompts`
-        and `resources` are accepted on save, but an unreachable MCP server doesn't fail the
-        run (verified on OpenAI), so put the policy the guardrail must apply in its
-        instructions. Providers come in two families with two configuration formats:
+        and `resources` are accepted on save but never used at run time, so put the policy the
+        guardrail must apply in its instructions. Providers come in two families with two
+        configuration formats:
 
         - **Built-in providers** — each has its own configuration block.
           - **openai**: OpenAI models (GPT-4.1, GPT-5, etc.). Configure via the `openai` object.
@@ -22403,7 +22425,7 @@ components:
           type: array
           description: |-
             MCP prompt entries saved with a catalog-provider guardrail (generic flat format).
-            Each entry references one MCP connection and the prompt names allowed from it.
+            Each entry references one MCP connection and prompt names; a guardrail's run never fetches them.
           items:
             type: object
             properties:
@@ -22424,7 +22446,7 @@ components:
                     description: Connection to the MCP server that exposes the prompts.
                   allowedPrompts:
                     type: array
-                    description: Prompt names the model may fetch from the server.
+                    description: Prompt names saved with the entry; a guardrail's run never fetches them.
                     items:
                       type: string
           x-celigo-ai-guidance:
@@ -22681,7 +22703,7 @@ components:
               type: array
               description: |-
                 MCP prompt entries saved with the guardrail. Each item references one
-                MCP connection and the prompt names allowed from it.
+                MCP connection and prompt names; a guardrail's run never fetches them.
               items:
                 type: object
                 properties:
@@ -22703,7 +22725,7 @@ components:
                         description: Connection to the MCP server.
                       allowedPrompts:
                         type: array
-                        description: Prompt names to allow from the MCP server.
+                        description: Prompt names saved with the entry; a guardrail's run never fetches them.
                         items:
                           type: string
             resources:
@@ -22870,7 +22892,7 @@ components:
                       type: array
                       description: |-
                         MCP prompt entries saved with a Gemini guardrail. Each item references one
-                        MCP connection and the prompt names allowed from it.
+                        MCP connection and prompt names; a guardrail's run never fetches them.
                       items:
                         type: object
                         properties:
@@ -22892,7 +22914,7 @@ components:
                                 description: Connection to the MCP server.
                               allowedPrompts:
                                 type: array
-                                description: Prompt names to allow from the MCP server.
+                                description: Prompt names saved with the entry; a guardrail's run never fetches them.
                                 items:
                                   type: string
                     resources:
@@ -23092,7 +23114,7 @@ components:
                       type: array
                       description: |-
                         MCP prompt entries saved with a Claude guardrail. Each item references one
-                        MCP connection and the prompt names allowed from it.
+                        MCP connection and prompt names; a guardrail's run never fetches them.
                       items:
                         type: object
                         properties:
@@ -23114,7 +23136,7 @@ components:
                                 description: Connection to the MCP server.
                               allowedPrompts:
                                 type: array
-                                description: Prompt names to allow from the MCP server.
+                                description: Prompt names saved with the entry; a guardrail's run never fetches them.
                                 items:
                                   type: string
                     resources:
@@ -23216,8 +23238,8 @@ components:
           `aiAgent.openai.tools`, `aiAgent.litellm._overrides.gemini.tools`, `….anthropic.tools`) —
           any non-empty array fails the save with 422 `guardrail_tools_not_allowed` ("Tools aren't
           supported on a guardrail AI agent configuration…"), on create and on update. `prompts` and
-          `resources` are accepted on save, but an unreachable MCP server doesn't fail the run
-          (verified on OpenAI), so put the policy in the instructions. The server still echoes
+          `resources` are accepted on save but never used at run time, so put the policy in the
+          instructions. The server still echoes
           `openai.tools: []` on OpenAI guardrails.
       properties:
         type:
@@ -30955,9 +30977,12 @@ components:
             request fields are interpreted. When omitted, the standard HTTP form is used.
           x-celigo-ai-guidance:
             - |-
-              The value changes only the editor, never the request: the same `http.body` is sent
-              identically under `http` and `graph_ql`, and the value can be changed on an existing
-              export without touching the body.
+              The value picks the editor and changes one thing in a GraphQL request: under `graph_ql`
+              and `assistant_graphql`, a `variables` member stored as a JSON string is parsed and sent
+              as an object, while under `http` it is sent as the string. A body whose `variables` is
+              already an object goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with
+              export previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
             - |-
               The GraphQL form reads `http.body` as the JSON envelope `{"query", "operationName",
               "variables"}` and shows each member in its own editor, recompiling the envelope on save
@@ -31174,9 +31199,15 @@ components:
               XML, etc.).
             - |-
               A GraphQL request is this field holding the stringified JSON envelope `{"query":
-              "<document>", "operationName": "...", "variables": ...}` whatever `formType` says;
-              `variables` may be an object or a JSON-encoded string, and a templated variables value
-              must stay inside a string so the body remains parseable JSON at rest (see `formType`).
+              "<document>", "operationName": "...", "variables": ...}`. `variables` may be an object
+              or a JSON-encoded string, and a string is sent as an object only under the GraphQL
+              form types (see `formType`). Variables with unquoted Handlebars (a number, `null`, an
+              `{{#if}}` block) must be a string so the body remains parseable JSON at rest; string
+              values inside that string sit two JSON levels deep, so write them as
+              `\"{{jsonEncode record.x}}\"` with double braces: a plain `{{record.x}}`, or a
+              triple-brace `jsonEncode`, fails a value holding a quote with 422 `invalid_json`.
+              An object or array there is `{{jsonSerialize record.x}}`, also with double braces;
+              triple braces fail the same way.
             - |-
               You can use handlebars expressions to create dynamic content:
               ```
@@ -32000,7 +32031,7 @@ components:
                 - response.records
             lastPageStatusCode:
               type: integer
-              description: HTTP status code that signals the last page, replacing the default behavior of treating 404 as the end of pagination. When this status is received, paging stops and the response is not treated as an error. Set only when the API uses a non-404 code (such as 204 or 400) to indicate no more pages.
+              description: 'HTTP status code that signals the last page, replacing the default behavior of treating 404 as the end of pagination. When this status is received (any code but `200` paired with `lastPagePath`), paging stops and the response is not treated as an error. Set it when the API uses a non-404 code (such as 204 or 400) to indicate no more pages, or to `200` together with `lastPagePath` when the last page is an ordinary 200 response: then the response is parsed, its records are kept, and paging stops only when `lastPagePath` matches `lastPageValues`.'
               x-celigo-ai-guidance:
                 - Specifies a custom HTTP status code that indicates the last page of results.
                 - |-
@@ -32035,36 +32066,45 @@ components:
                 - |-
                   ## TECHNICAL DETAILS
 
-                  When this status code is received, the system:
+                  When this status code is received (any code but `200` paired with
+                  `lastPagePath`), the system:
                   - Stops the pagination process
                   - Considers the data collection complete
                   - Does not treat the response as an error
                   - Does not attempt to process any response body
 
                   IMPORTANT: Only set this if your API explicitly uses a non-404 status code
-                  to indicate the end of pagination. Setting this incorrectly could cause
-                  premature termination of data collection or error handling issues.
+                  to indicate the end of pagination, or to `200` with `lastPagePath` (below).
+                  Setting this incorrectly could cause premature termination of data
+                  collection or error handling issues.
+                - |-
+                  `200` is the exception, for an API whose last page is an ordinary 200 response:
+                  together with `lastPagePath`, paging stops on the first 200 whose `lastPagePath`
+                  value matches `lastPageValues`, and that page's records are kept. Live-verified
+                  2026-10-22 with token paging.
               examples:
                 - 204
                 - 400
                 - 500
             lastPagePath:
               type: string
-              description: JSON path to a response-body field that signals the end of pagination, such as a "has more" flag or a cursor that empties on the last page. Must be used with `lastPageValues`, which lists the values at this path that stop paging. If the path does not exist in a response, the condition is not considered met.
+              description: 'JSON path to a response-body field that signals the end of pagination, such as a "has more" flag or a cursor that empties on the last page. Must be used with `lastPageValues`, which lists the values at this path that stop paging. If the path does not exist in a response, the condition is not considered met. With `method: token` the path is read only on a response whose status code equals `lastPageStatusCode`, so pair it with `lastPageStatusCode: 200` for an ordinary last page; with `method: body` it is read on every response.'
               x-celigo-ai-guidance:
                 - |-
                   ## FIELD BEHAVIOR
 
                   - OPTIONAL: Only needed for APIs with field-based pagination completion signals
-                  - Works with all pagination methods
+                  - Accepted on all pagination methods; when it is read depends on the method (see
+                    the method note below)
                   - Used in conjunction with lastPageValues
                   - JSON path notation to a field in the response body
                 - |-
                   ## IMPLEMENTATION GUIDANCE
 
                   This field is used when an API indicates the last page through a field
-                  in the response body rather than using HTTP status codes. The system
-                  checks this path in each response to determine if pagination is complete.
+                  in the response body rather than using HTTP status codes. Which responses
+                  the system checks it on depends on the paging method (see the method note
+                  below).
 
                   Common patterns include:
 
@@ -32098,8 +32138,19 @@ components:
                   "lastPageValues": ["false", "0"]
                   ```
 
-                  IMPORTANT: The path is evaluated against each response using JSON path notation.
-                  If the path doesn't exist in the response, the condition is not considered met.
+                  IMPORTANT: The path is evaluated using JSON path notation, on the responses the
+                  method note below describes. If the path doesn't exist in the response, the
+                  condition is not considered met.
+                - |-
+                  On `method: token` the path is checked only on a response whose status code equals
+                  `lastPageStatusCode`. For an API whose last page is an ordinary 200 (a GraphQL
+                  `pageInfo.hasNextPage: false`), set `lastPageStatusCode: 200` with it; without that,
+                  paging goes on while the token at `path` is non-empty, so a last page that still
+                  carries a cursor costs one more request. On `method: body` the path is read on
+                  every response, with no status code needed. Live-verified 2026-10-22 against an echo
+                  endpoint for `token` (two requests without `lastPageStatusCode`, one with 200) and
+                  `body` (stopped on the second response); `page`, `skip` and `url` paging were not
+                  verified.
               examples:
                 - meta.isLastPage
                 - pagination.hasMore
@@ -32523,22 +32574,30 @@ components:
                   - '201'
             errorPath:
               type: string
-              description: Path to the error message in the response body. The value at this path is included in error logs and error records when the API returns an error.
+              description: Path to the error message in the response body. The value at this path is included in error logs and error records when the API returns an error; without it, the message is the whole response body.
               examples:
                 - error.message
                 - errorMessage
                 - errors[0].detail
+                - errors[0].message
             failPath:
               type: string
-              description: Path to a response field that signals failure even when the HTTP status code is 200 — the inverse of `successPath`. Must be used with `failValues`.
+              description: Path to a response field that signals failure even when the HTTP status code is 200 — the inverse of `successPath`. With `failValues`, the response fails when the value there matches one of them; without, when the path holds a truthy value. A path that resolves to an array matches only when the array has exactly one element.
               x-celigo-ai-guidance:
-                - |-
-                  Similar to `successPath` but inverted logic — checks for failure indicators.
-                  Must be used together with `failValues`.
+                - Similar to `successPath` but inverted logic — checks for failure indicators.
+                - |-
+                  A path that resolves to an array matches only when the array has exactly one
+                  element. GraphQL APIs usually report a failed query with HTTP 200 and an `errors` array:
+                  `failPath: errors` fails the response for one error and lets two or more through,
+                  so set `failPath` (and `errorPath`) to `errors[0].message`. Without a fail path the
+                  response counts as a success, and an export whose `resourcePath` points into
+                  `data` returns zero records with no error. Live-verified 2026-10-22 with export
+                  and import previews against an echo endpoint.
               examples:
                 - error
                 - status
                 - result.error
+                - errors[0].message
             failValues:
               type: array
               items:
@@ -35356,8 +35415,9 @@ components:
                 Number of records the RESTlet returns per request (default 1000). This, not the
                 export's `pageSize`, sizes each NetSuite call; the export keeps requesting until the
                 search is exhausted. Larger batches reduce round-trips but raise NetSuite governance
-                and memory use per call; tune to the record's size. In a test run or preview the
-                request is capped at the export's `pageSize` (default 20) instead.
+                and memory use per call; tune to the record's size. The RESTlet caps a call at 1000,
+                so a larger value acts as 1000. In a test run or preview the request is capped at the
+                export's `pageSize` (default 20) instead.
               examples:
                 - 100
                 - 200
@@ -35636,8 +35696,9 @@ components:
               type: array
               description: |-
                 Search columns the RESTlet returns for each matching record. With a saved search,
-                omit this to return the search's own result columns; an ad-hoc search (no
-                `searchId`) must list its columns here.
+                the RESTlet returns the search's own result columns followed by any listed here: a
+                list adds columns and never removes one of the search's, so remove a column in the
+                saved search itself. An ad-hoc search (no `searchId`) must list its columns here.
               x-celigo-ai-guidance:
                 - |-
                   Entries are objects keyed by `name` — `[{"name": "internalid"}, {"name":

package/package.json

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