@celigo/api-specs 0.2.75 → 0.2.77

package/dist/flow.yml

@@ -3762,23 +3762,33 @@ paths:
       summary: Preview the output of a flow's page processor
       description: |-
         Runs a flow's page generators and page processors through the preview
-        pipeline and returns the record arriving at a specific page-processor
-        node, with the whole upstream chain applied server-side: the source
-        export executes live (its transform, output filter, and preSavePage
-        hook are applied), router branch filters and step input filters gate
-        the records, upstream lookups execute live unless a saved `mockOutput`
-        is present (a saved mock always wins), and upstream imports are NEVER
-        executed — each substitutes its saved `mockResponse`, or a platform
-        placeholder when none is saved, before its response mapping and
-        postResponseMap hook run. A target IMPORT obeys its map entry's
-        options flag: `{preview: true}` composes the request and returns it
-        without sending, while `{sendAndPreview: true}` (the import
-        editor's "Send" button) executes it against the live destination —
-        a real write. A target LOOKUP executes its live query
-        (even when it carries a saved `mockOutput` — the mock substitutes
-        only when the lookup is upstream of the target). With
-        `includeStages: false` the response is the bare result object
-        rather than the `{data, stages}` envelope.
+        pipeline and returns the record arriving at one page-processor node,
+        with the upstream chain applied server-side. A target IMPORT obeys its
+        map entry's options flag: `{preview: true}` composes the request
+        without sending; `{sendAndPreview: true}` (the import editor's "Send"
+        button) executes it against the live destination — a real write — and
+        stops at the parsed response (the target's postSubmit hook does not
+        run). Both composing modes serve HTTP import targets only: a NetSuite,
+        Salesforce, RDBMS or FTP target answers `422 no_data_available` ("You
+        must add at least one mock input record…") whatever records the chain
+        delivers — the generic "no record reached the target", not a data
+        problem; execute such a step as a virtual import instead
+        (`POST /v1/connections/{_id}/import`). No options flag returns the
+        arriving record for any adaptor without touching the target.
+
+        Upstream behavior: the source export executes live (transform, output
+        filter and preSavePage hook applied); router branch filters and step
+        input filters gate the records; upstream lookups execute live unless a
+        saved `mockOutput` is present (a saved mock always wins); upstream
+        imports are NEVER executed — each substitutes its saved `mockResponse`,
+        or a platform placeholder when none is saved, before its response
+        mapping and postResponseMap hook run. A target LOOKUP executes its
+        live query even when it carries a saved `mockOutput` (the mock
+        substitutes only upstream). When a target import's `failPath` rules
+        judge the destination's answer a failure, the response is `422` whose
+        `errors[]` carry `source: application` and `stage: apiCall` — the
+        request did execute. With `includeStages: false` the response is the
+        bare result object rather than the `{data, stages}` envelope.
 
         Body carries the flow shape plus resolved maps of page-generator and
         page-processor docs keyed by `_id`. The server uses those maps as the
@@ -3824,8 +3834,8 @@ paths:
                     6508ab8b20b16404da729c64:
                       doc:
                         _id: 6508ab8b20b16404da729c64
-                        name: Upsert NetSuite Customers
-                        adaptorType: NetSuiteImport
+                        name: Upsert customers in the destination API
+                        adaptorType: HTTPImport
                       options:
                         preview: true
                   includeStages: true
@@ -3878,6 +3888,39 @@ paths:
                         message: 'The pageGenerator doc corresponding to the _id:  is not found in the given pageGeneratorMap.'
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            Two distinct meanings, told apart by `errors[].source`:
+            `no_data_available` with `source: integrator` — no record reached
+            the target in a composing mode (the target is a NetSuite,
+            Salesforce, RDBMS or FTP import, which these modes cannot drive, or
+            the chain's gates dropped every record); `source: application` with
+            `stage: apiCall` after `sendAndPreview` — the request DID execute
+            and the target import's `failPath` rules judged the destination's
+            answer a failure; `message` carries the destination's response body
+            and `code` its HTTP status.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noRecordReachedTarget:
+                  summary: Composing mode on a non-HTTP target, or every record gated out
+                  value:
+                    errors:
+                      - code: no_data_available
+                        source: integrator
+                        message: You must add at least one mock input record. If you still get this error after adding an input record, verify that your current mapping configuration isn't ignoring all record output. Mock input records must pass through the input filter and hooks to qualify for Preview and Send.
+                failPathTripped:
+                  summary: sendAndPreview executed; the target's failPath rules judged the 200 a failure
+                  description: |-
+                    The live error also carries `stage: apiCall`, `classification`,
+                    `resolved` and `occurredAt` beside the fields shown.
+                  value:
+                    errors:
+                      - code: 200
+                        source: application
+                        message: '{"args":{},"json":{"FirstName":"FAILME"}}'
   /v1/flows/{_id}/dependencies:
     get:
       x-internal: false
@@ -7691,6 +7734,17 @@ components:
         Flow-page-processor preview request. Carries the flow shape plus
         side-loaded maps of page-generator and page-processor docs so the
         preview engine can run without reading the persisted flow doc.
+      x-celigo-ai-guidance:
+        - |-
+          The target import's `{preview: true}` / `{sendAndPreview: true}` composing modes serve HTTP
+          import targets only: a NetSuite, Salesforce, RDBMS or FTP target answers `422
+          no_data_available` whatever records the chain delivers — not a data problem. Execute such a
+          step as a virtual import (`POST /v1/connections/{_id}/import`) instead; with no options flag
+          this call still returns the arriving record for any adaptor.
+        - |-
+          A `422` whose `errors[]` carry `source: application` and `stage: apiCall` after
+          `sendAndPreview` means the request DID execute and the target's `failPath` rules judged the
+          destination's answer a failure — a completed send, not a request-validation error.
       properties:
         flow:
           type: object
@@ -7761,10 +7815,12 @@ components:
             the mock input the editor's "Mock input" pane would provide.
             Upstream entries carry `{}`.
             Request composition is adaptor-gated: the `preview`/`sendAndPreview`
-            modes work for HTTP, REST, and GraphQL import targets — RDBMS-family
-            import targets fail with `no_data_available` regardless of supplied
-            input (database imports have no request-preview surface; only the
-            no-flag input-data preview works for them).
+            modes work for HTTP, REST, and GraphQL import targets — a NetSuite,
+            Salesforce, RDBMS or FTP import target fails with
+            `422 no_data_available` regardless of supplied input (those
+            adaptors have no request-preview surface; only the no-flag
+            input-data preview works for them, and the virtual import
+            `POST /v1/connections/{_id}/import` executes them).
           additionalProperties:
             type: object
             properties:
@@ -7778,7 +7834,8 @@ components:
             64a1234567890abcdef12345:
               doc:
                 _id: 64a1234567890abcdef12345
-                name: Import Orders to NetSuite
+                name: Create orders in the destination API
+                adaptorType: HTTPImport
                 _connectionId: 5f7c579b6411271af4e7cefb
               options:
                 preview: true

package/dist/guardrail.yml

@@ -602,8 +602,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the guardrail fails to save with 422
+        `connection_required` on `_connectionId`.
       x-celigo-ai-guidance:
         - |-
           Do not send `tools` on any block. A non-empty array at `tools`, `openai.tools`,
@@ -646,10 +647,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the guardrail saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the guardrail fails to save with 422 `connection_required` on `_connectionId` ("No
+              API key is available for provider 'xai'. Add a connection for this provider with
+              your API key and select it on this agent."). Attach an HTTP connection to the
+              vendor's API (token auth) before saving a catalog-provider guardrail.
         model:
           type: string
           description: |-
@@ -661,11 +663,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider guardrail fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -930,12 +932,17 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                        json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
+                        provider is the same either way. Stored and echoed on guardrails for parity
+                        with the AI-agent format block — the guardrail form does not set it today.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Resend the stored value on every update — a full PUT that omits the field
+                          clears it — and never invent one: a value outside the enum fails the save with
+                          422 `enum` on `guardrail.aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -1124,12 +1131,17 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                    json: The schema editor opens `jsonSchema` in the raw JSON view
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which view a schema editor opens `jsonSchema` in; the schema sent to the provider
+                    is the same either way. Stored and echoed on guardrails for parity with the
+                    AI-agent format block — the guardrail form does not set it today.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Resend the stored value on every update — a full PUT that omits the field clears
+                      it — and never invent one: a value outside the enum fails the save with 422 `enum`
+                      on `guardrail.aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).