@celigo/api-specs 0.2.103 → 0.2.105

package/dist/flow.yml

@@ -892,6 +892,110 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/flows/{_flowId}/runs/stats:
+    post:
+      x-internal: false
+      operationId: getFlowRuntimeChartStats
+      tags:
+        - Flows
+      summary: Get flow runtime chart stats
+      description: |-
+        Returns historical runtime statistics and chart buckets for a single flow.
+        Used by the proactive alerts UI to suggest and preview long-runtime
+        thresholds.
+
+        This is not the job-dashboard aggregate API. Dashboard totals live at
+        `POST /v1/flows/runs/stats` (job spec). This path is
+        `POST /v1/flows/{_flowId}/runs/stats`.
+
+        Requires the proactive alerts feature flag and ClickHouse to be enabled for
+        the user. When ClickHouse is unavailable, returns
+        `{ "clickhouseAvailable": false }`.
+
+        Time range constraints:
+        - `startTime` is required (ISO 8601 UTC)
+        - `endTime` defaults to now when omitted
+        - Minimum range: 1 hour
+        - Maximum range: 90 days
+        - Granularity: hourly buckets for ranges ≤ 24h; daily buckets for longer ranges
+
+        Chart `alertsTriggered` / `totalAlertsTriggered` count completed runs whose
+        runtime is **strictly greater than** the threshold used for the query.
+        That is a historical chart count, not the number of alert emails sent.
+      parameters:
+        - name: _flowId
+          in: path
+          required: true
+          description: Flow id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 507f1f77bcf86cd799439011
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FlowRunsStatsRequest'
+            examples:
+              default:
+                value:
+                  type: runtimeSummary
+                  startTime: '2026-05-01T00:00:00.000Z'
+                  endTime: '2026-06-01T00:00:00.000Z'
+                  thresholdMinutes: 45
+      responses:
+        '200':
+          description: Runtime summary, empty-state payload, or ClickHouse-unavailable marker.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlowRunsStatsResponse'
+              examples:
+                summary:
+                  summary: Runtime summary with chart buckets
+                  value:
+                    _flowId: 507f1f77bcf86cd799439011
+                    startTime: '2026-05-01T00:00:00.000Z'
+                    endTime: '2026-06-01T00:00:00.000Z'
+                    granularity: day
+                    thresholdMinutes: 45
+                    totalRuns: 120
+                    totalAlertsTriggered: 8
+                    emptyState: false
+                    truncated: false
+                    statistics:
+                      suggestedThreshold: 45
+                    chartEntries:
+                      - bucket: '2026-05-01'
+                        totalRuns: 10
+                        alertsTriggered: 1
+                        avgRuntimeMinutes: 22.5
+                        p5RuntimeMinutes: 5
+                        p95RuntimeMinutes: 60
+                emptyState:
+                  summary: Fewer than 3 completed runs
+                  value:
+                    _flowId: 507f1f77bcf86cd799439011
+                    startTime: '2026-05-01T00:00:00.000Z'
+                    endTime: '2026-06-01T00:00:00.000Z'
+                    emptyState: true
+                clickhouseUnavailable:
+                  summary: ClickHouse not available
+                  value:
+                    clickhouseAvailable: false
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
   /v1/flows/{_id}/traceKey:
     get:
       x-internal: false
@@ -6151,6 +6255,166 @@ components:
             error:
               type: string
               description: Human-readable reason the run was not started.
+    FlowRunsStatsRequest:
+      type: object
+      required:
+        - type
+        - startTime
+      properties:
+        type:
+          type: string
+          description: Request type.
+          enum:
+            - runtimeSummary
+          x-enumDescriptions:
+            runtimeSummary: Historical runtime summary and chart buckets for alert threshold preview.
+          examples:
+            - runtimeSummary
+        startTime:
+          type: string
+          format: date-time
+          description: Start of query window (ISO 8601 UTC). Must not be in the future.
+          examples:
+            - '2026-05-01T00:00:00.000Z'
+        endTime:
+          type: string
+          format: date-time
+          description: End of query window (ISO 8601 UTC). Defaults to now. Must not be in the future.
+          examples:
+            - '2026-06-01T00:00:00.000Z'
+        thresholdMinutes:
+          type: integer
+          minimum: 5
+          maximum: 59940
+          description: |-
+            Optional threshold override in minutes. When omitted, the response uses
+            `statistics.suggestedThreshold` (ceil of p99 runtime, floored at 5).
+            Chart counts use this value with a strict greater-than comparison.
+          examples:
+            - 45
+    FlowRunsStatsResponse:
+      type: object
+      description: |-
+        Runtime statistics response for the proactive alert threshold chart.
+
+        Three shapes are possible:
+        - **Summary** — `emptyState: false` with `statistics`, `chartEntries`, and
+          run totals. Returned when the time range has 3 or more completed runs.
+        - **Empty state** — `{ _flowId, startTime, endTime, emptyState: true }` with
+          no chart data. Returned when the time range has fewer than 3 completed
+          runs.
+        - **ClickHouse unavailable** — only `clickhouseAvailable: false`. Returned
+          when ClickHouse is not enabled for the caller.
+      properties:
+        _flowId:
+          type: string
+          format: objectId
+          x-celigo-refModel: flows
+          description: Echoed flow id.
+          examples:
+            - 507f1f77bcf86cd799439011
+        startTime:
+          type: string
+          format: date-time
+          description: Echoed query start time.
+          examples:
+            - '2026-05-01T00:00:00.000Z'
+        endTime:
+          type: string
+          format: date-time
+          description: Echoed query end time.
+          examples:
+            - '2026-06-01T00:00:00.000Z'
+        granularity:
+          type: string
+          description: Bucket granularity for chart entries. Absent on empty-state and ClickHouse-unavailable responses.
+          enum:
+            - hour
+            - day
+          x-enumDescriptions:
+            hour: Hourly buckets (ranges ≤ 24h).
+            day: Daily buckets (ranges longer than 24h).
+        thresholdMinutes:
+          type: integer
+          description: Threshold used for chart alert-count computation. Absent on empty-state and ClickHouse-unavailable responses.
+          examples:
+            - 45
+        totalRuns:
+          type: integer
+          description: Total completed runs in the time range. Absent on empty-state and ClickHouse-unavailable responses.
+          examples:
+            - 120
+        totalAlertsTriggered:
+          type: integer
+          description: |-
+            Count of completed runs in the window whose runtime is strictly greater
+            than `thresholdMinutes`. Historical chart metric only — not the number
+            of alert emails sent. Absent on empty-state and ClickHouse-unavailable
+            responses.
+          examples:
+            - 8
+        emptyState:
+          type: boolean
+          description: |-
+            `true` when the time range has fewer than 3 completed runs (no chart
+            data). `false` on summary responses. Absent on ClickHouse-unavailable
+            responses.
+          examples:
+            - false
+        truncated:
+          type: boolean
+          description: |-
+            True when totalRuns exceeds 5000. Indicates a high-volume warning; chart
+            data is still complete for the requested time range. Absent on
+            empty-state and ClickHouse-unavailable responses.
+          examples:
+            - false
+        clickhouseAvailable:
+          type: boolean
+          description: |-
+            Present only when ClickHouse is not available for the caller. Value is
+            always `false` when present. Absent on successful summary and
+            empty-state responses.
+          examples:
+            - false
+        statistics:
+          type: object
+          description: |-
+            Present on successful summary responses. Used by the UI for the
+            suggested threshold hint. Absent on empty-state and
+            ClickHouse-unavailable responses.
+          properties:
+            suggestedThreshold:
+              type: integer
+              description: |-
+                Suggested threshold in minutes: ceil of the p99 completed-run
+                runtime in the window, then floored at the platform minimum (5).
+              examples:
+                - 45
+        chartEntries:
+          type: array
+          description: |-
+            Chart data buckets. Present on successful summary responses. Absent on
+            empty-state and ClickHouse-unavailable responses.
+          items:
+            type: object
+            properties:
+              bucket:
+                type: string
+                description: ISO hourly timestamp or YYYY-MM-DD date.
+                examples:
+                  - '2026-05-01'
+              totalRuns:
+                type: integer
+              alertsTriggered:
+                type: integer
+                description: Completed runs in this bucket with runtime strictly greater than the query threshold.
+              avgRuntimeMinutes:
+                type: number
+              p5RuntimeMinutes:
+                type: number
+              p95RuntimeMinutes:
+                type: number
     FlowTraceKeyResponse:
       type: array
       description: |-
@@ -8179,5 +8443,18 @@ components:
                 errors:
                   - code: dependencies_not_deleted
                     message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
 x-enable-proxy: true
 x-internal: false

package/dist/iclient.yml

@@ -321,7 +321,10 @@ paths:
         Replaces an iClient. All mutable fields must be provided — omitted
         fields are reset to defaults. Secrets returned as `"******"` can be
         sent back as-is to keep the existing value, except a Google service
-        account: every update must include the full JSON key.
+        account: every update must include the full JSON key. An Azure
+        service principal keeps its stored `clientSecret` or `certificate`
+        when the field is omitted — only a new value replaces it, and
+        `certificate` is never returned.
       operationId: updateIClient
       tags:
         - iClients
@@ -639,7 +642,7 @@ components:
             netsuite: NetSuite token-based authentication.
             amazonmws: Amazon Marketplace Web Service (MWS) authentication.
             awsIam: AWS IAM cross-account role authentication (assume-role with an external ID).
-            azureserviceprincipal: Azure AD service principal (client credentials) authentication.
+            azureserviceprincipal: Microsoft Entra service principal (client secret or certificate) for Azure Data Lake Storage Gen2, Microsoft SQL Server and Azure Synapse connections
             googleserviceaccount: Google Cloud service-account key authentication (JSON key file).
             integrator: Celigo integrator.io internal authentication.
             salesforce: Salesforce OAuth 2.0 authentication.
@@ -3933,8 +3936,12 @@ components:
         azureserviceprincipal:
           type: object
           description: |-
-            Azure AD service principal credentials. Required when `provider`
-            is `azureserviceprincipal`.
+            Microsoft Entra (Azure AD) service principal credentials. Required
+            when `provider` is `azureserviceprincipal`. One iClient of this
+            provider can back Azure Data Lake Storage Gen2, Microsoft SQL Server
+            (cloud) and Azure Synapse Analytics connections; the connection forms
+            offer the certificate method from Microsoft SQL Server connections
+            only.
           required:
             - clientId
             - tenantId
@@ -3951,7 +3958,15 @@ components:
               description: |-
                 Which credential the service principal presents. Defaults to
                 `client-secret` when omitted. Each method rejects the other
-                method's credential fields on save.
+                method's credential fields on save. Changing the method on an
+                update replaces the credential: send the new method's credential
+                and drop the old one.
+              x-celigo-ai-guidance:
+                - |-
+                  Under authMethod "certificate", a clientSecret is rejected with 422 invalid_field_value
+                  on azureserviceprincipal.clientSecret "Client secret is not used when auth method is
+                  certificate."; a missing certificate with 422 missing_required_field on
+                  azureserviceprincipal.certificate "Expected field: certificate to be present."
             clientId:
               type: string
               description: Azure AD application (client) ID.
@@ -3962,24 +3977,35 @@ components:
               description: |-
                 Azure AD client secret. Required when `authMethod` is
                 `client-secret` (or omitted). Returned masked as `"******"`.
-                Re-send that value on update to keep it; it is not preserved if omitted.
+                On update the stored secret is kept when the field is omitted or
+                re-sent as the mask; only a new value replaces it.
             certificate:
               type: string
+              writeOnly: true
               description: |-
                 PEM bundle (certificate + private key) for certificate auth.
                 Required when `authMethod` is `certificate`; rejected under
-                `client-secret`. Maximum 20 KiB of PEM text. Returned masked.
+                `client-secret`. Maximum 20 KiB of PEM text. Never returned in
+                responses, not even masked. On update the stored PEM is kept when
+                the field is omitted; only a new value replaces it.
               x-celigo-ai-guidance:
                 - |-
                   If the PEM's private key is encrypted (BEGIN ENCRYPTED PRIVATE
-                  KEY / Proc-Type 4,ENCRYPTED), certificatePassword is required;
+                  KEY / Proc-Type 4,ENCRYPTED), certificatePassword is required
+                  (422 invalid_field_value on azureserviceprincipal.certificatePassword "This
+                  certificate's private key is encrypted. Enter the client certificate password.");
                   if it is unencrypted, sending certificatePassword is rejected.
+                - |-
+                  The save does not check that the PEM is a usable credential — a placeholder PEM
+                  carrying the BEGIN CERTIFICATE and BEGIN PRIVATE KEY blocks saves (live-verified
+                  201). Enter the real PEM in the iClient editor before testing a connection that
+                  uses the iClient.
             certificatePassword:
               type: string
               description: |-
                 Passphrase for an encrypted private key inside `certificate`.
                 Required exactly when the PEM's key is encrypted; rejected when
-                it is not. Maximum 256 bytes. Returned masked.
+                it is not. Maximum 256 bytes. Returned masked when set.
             tenantId:
               type: string
               description: Azure AD tenant (directory) ID.
@@ -4332,10 +4358,13 @@ components:
         For `custom_oauth2`, credentials go in the `oauth2` sub-object.
         Secrets (`clientSecret`, `privateKey`, and so on) come back masked
         as `"******"`. Re-send that mask on update to keep the stored
-        secret; omitting it does not. A Google service account is the
-        exception: `serviceAccountJSON` is not returned, and every update
-        must send the full key — the mask or an omission fails with 422
-        `invalid_json_key`.
+        secret; omitting it does not. Two providers differ. A Google
+        service account: `serviceAccountJSON` is not returned, and every
+        update must send the full key — the mask or an omission fails with
+        422 `invalid_json_key`. An Azure service principal: the stored
+        `clientSecret` or `certificate` is kept when its field is omitted
+        on update, and only a new value replaces it (`certificate` is never
+        returned, not even masked).
       required:
         - provider
       allOf:

package/dist/lookupcache.yml

@@ -605,7 +605,7 @@ paths:
                         value: New York
                       - key: ZZ
                         error:
-                          message: Key not found
+                          message: The requested key does not match any entry in the lookup cache. Check the key.
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -1169,7 +1169,7 @@ components:
               type: string
               description: Human-readable explanation of the miss.
               examples:
-                - Key not found
+                - The requested key does not match any entry in the lookup cache. Check the key.
     LookupCacheDataReadResponse:
       type: object
       description: |-