@salesforce/lds-adapters-analytics-wave 1.465.0 → 1.467.0

package/src/raml/api.raml

@@ -2786,20 +2786,24 @@ types:
         type: string
       runStatus:
         description: The runtime status of the platform audit run. RUNNING until every check
-          has finished or the run ends early. A run that ended before every check finished,
+          has finished, the run ends early, or a user cancels it. A run cancelled while RUNNING
+          is CANCELLED - its check results are discarded, every check it lists is CANCELLED,
+          and it is not scored. A run that ended before every check finished in any other way,
           for example because it ran too long, is FAILED. Otherwise the terminal status depends
-          on every check except crma-inventory - READY if each is COMPLETE, FAILED if none is
-          COMPLETE or COMPLETE_WITH_LIMITATIONS, and COMPLETE_WITH_LIMITATIONS otherwise.
-          crma-inventory only counts the org's assets and its status does not affect the
-          run's, so a READY run can have a crma-inventory check that is
-          COMPLETE_WITH_LIMITATIONS, UNAVAILABLE, or FAILED. A FAILED run can still carry finished checks,
-          findings, and a health score; any unfinished check it lists is NOT_FINISHED.
+          on every check except crma-inventory (or on every check, if crma-inventory is the
+          only one) - READY if each is COMPLETE, FAILED if none is COMPLETE or
+          COMPLETE_WITH_LIMITATIONS, and COMPLETE_WITH_LIMITATIONS otherwise. crma-inventory
+          only counts the org's assets and its status does not affect the run's, so a READY run
+          can have a crma-inventory check that is COMPLETE_WITH_LIMITATIONS, UNAVAILABLE, or
+          FAILED; the run still waits for it to finish. A FAILED run can still carry finished
+          checks, findings, and a health score; any unfinished check it lists is NOT_FINISHED.
         type: string
         enum:
           - RUNNING
           - READY
           - COMPLETE_WITH_LIMITATIONS
           - FAILED
+          - CANCELLED # TODO Hand-rolled W-24626646
       scope:
         description: The scope of assets covered by the platform audit run.
         type: string
@@ -2812,8 +2816,8 @@ types:
         type: number
       checksTerminal:
         description: The number of checks that have finished. It stays below checksTotal
-          for a run that ended early, so use runStatus, not this count, to tell whether the
-          run is still going.
+          for a run that ended early, and is 0 for a CANCELLED run, so use runStatus, not this
+          count, to tell whether the run is still going.
         # TODO: Hand-rolled from "format: int64, type: integer" due to W-8274943
         format: double
         type: number
@@ -2821,37 +2825,43 @@ types:
         description: The date the platform audit run was created.
         type: string
       completedDate:
-        description: The date the platform audit run completed. Absent while the run is RUNNING.
+        description: The date the platform audit run completed, or for a CANCELLED run, the
+          date it was cancelled. Absent while the run is RUNNING.
         type: string | nil
         required: false
       checks:
         description: Every check of the audit run with its status - finished checks with
-          their results, and checks that have not finished without one.
+          their results, and checks that have not finished without one. Every check of a
+          CANCELLED run is listed as CANCELLED, without a result.
         type: PlatformAuditCheckCollectionRepresentation
       healthScore:
         description: The aggregated health score for the run, computed from its finished
-          checks on every read, including while RUNNING. Absent when the score is suppressed
-          (the scored checks scanned less than half of their candidates, or had no
-          candidates, as when no finished check could be scored) or could not be computed.
+          checks on every read, including while RUNNING. crma-inventory is not scored. Absent
+          when the score is suppressed (the scored checks scanned less than half of their
+          candidates, or had no candidates, as when no finished check could be scored) or
+          could not be computed, and always absent for a CANCELLED run, which is not scored.
         type: integer | nil
         required: false
       verdict:
         description: The aggregated health verdict for the run (Healthy, NeedsAttention,
           Critical, or Indeterminate when the score is suppressed), computed from its
-          finished checks on every read, including while RUNNING. Absent only when scoring
-          could not be computed.
+          finished checks on every read, including while RUNNING; crma-inventory does not
+          affect it. NotApplicable for a CANCELLED run, which is not scored. Absent only when
+          scoring could not be computed.
         type: string | nil
         required: false
       urgency:
         description: The aggregated health urgency triage, split into critical-now and
           needs-attention tiers, computed from the finished checks on every read. Lists the
-          scored checks' findings even when the score is suppressed. Absent only when scoring
-          could not be computed.
+          scored checks' findings even when the score is suppressed. Both tiers are empty for
+          a CANCELLED run. Absent only when scoring could not be computed.
         type: PlatformAuditUrgencyRepresentation | nil
         required: false
       scoreSuppressed:
-        description: Whether the health score is suppressed for this run. Absent only when
-          scoring could not be computed.
+        description: Whether the health score is suppressed for this run, so consumers show a
+          dash rather than a number. Always true for a CANCELLED run. crma-inventory does not
+          count toward the coverage that decides suppression. Absent only when scoring could
+          not be computed.
         type: boolean | nil
         required: false
   PlatformAuditSnapshotRepresentation: # TODO Hand-rolled W-24314623
@@ -2866,20 +2876,24 @@ types:
         type: string
       runStatus:
         description: The runtime status of the platform audit run. RUNNING until every check
-          has finished or the run ends early. A run that ended before every check finished,
+          has finished, the run ends early, or a user cancels it. A run cancelled while RUNNING
+          is CANCELLED - its check results are discarded, every check it lists is CANCELLED,
+          and it is not scored. A run that ended before every check finished in any other way,
           for example because it ran too long, is FAILED. Otherwise the terminal status depends
-          on every check except crma-inventory - READY if each is COMPLETE, FAILED if none is
-          COMPLETE or COMPLETE_WITH_LIMITATIONS, and COMPLETE_WITH_LIMITATIONS otherwise.
-          crma-inventory only counts the org's assets and its status does not affect the
-          run's, so a READY run can have a crma-inventory check that is
-          COMPLETE_WITH_LIMITATIONS, UNAVAILABLE, or FAILED. A FAILED run can still carry finished checks,
-          findings, and a health score; any unfinished check it lists is NOT_FINISHED.
+          on every check except crma-inventory (or on every check, if crma-inventory is the
+          only one) - READY if each is COMPLETE, FAILED if none is COMPLETE or
+          COMPLETE_WITH_LIMITATIONS, and COMPLETE_WITH_LIMITATIONS otherwise. crma-inventory
+          only counts the org's assets and its status does not affect the run's, so a READY run
+          can have a crma-inventory check that is COMPLETE_WITH_LIMITATIONS, UNAVAILABLE, or
+          FAILED; the run still waits for it to finish. A FAILED run can still carry finished
+          checks, findings, and a health score; any unfinished check it lists is NOT_FINISHED.
         type: string
         enum:
           - RUNNING
           - READY
           - COMPLETE_WITH_LIMITATIONS
           - FAILED
+          - CANCELLED # TODO Hand-rolled W-24626646
       scope:
         description: The scope of assets covered by the platform audit run.
         type: string
@@ -2892,8 +2906,8 @@ types:
         type: number
       checksTerminal:
         description: The number of checks that have finished. It stays below checksTotal
-          for a run that ended early, so use runStatus, not this count, to tell whether the
-          run is still going.
+          for a run that ended early, and is 0 for a CANCELLED run, so use runStatus, not this
+          count, to tell whether the run is still going.
         # TODO: Hand-rolled from "format: int64, type: integer" due to W-8274943
         format: double
         type: number
@@ -2901,37 +2915,43 @@ types:
         description: The date the platform audit run was created.
         type: string
       completedDate:
-        description: The date the platform audit run completed. Absent while the run is RUNNING.
+        description: The date the platform audit run completed, or for a CANCELLED run, the
+          date it was cancelled. Absent while the run is RUNNING.
         type: string | nil
         required: false
       checks:
         description: Every check of the audit run with its status - finished checks with
-          their results, and checks that have not finished without one.
+          their results, and checks that have not finished without one. Every check of a
+          CANCELLED run is listed as CANCELLED, without a result.
         type: PlatformAuditCheckCollectionRepresentation
       healthScore:
         description: The aggregated health score for the run, computed from its finished
-          checks on every read, including while RUNNING. Absent when the score is suppressed
-          (the scored checks scanned less than half of their candidates, or had no
-          candidates, as when no finished check could be scored) or could not be computed.
+          checks on every read, including while RUNNING. crma-inventory is not scored. Absent
+          when the score is suppressed (the scored checks scanned less than half of their
+          candidates, or had no candidates, as when no finished check could be scored) or
+          could not be computed, and always absent for a CANCELLED run, which is not scored.
         type: integer | nil
         required: false
       verdict:
         description: The aggregated health verdict for the run (Healthy, NeedsAttention,
           Critical, or Indeterminate when the score is suppressed), computed from its
-          finished checks on every read, including while RUNNING. Absent only when scoring
-          could not be computed.
+          finished checks on every read, including while RUNNING; crma-inventory does not
+          affect it. NotApplicable for a CANCELLED run, which is not scored. Absent only when
+          scoring could not be computed.
         type: string | nil
         required: false
       urgency:
         description: The aggregated health urgency triage, split into critical-now and
           needs-attention tiers, computed from the finished checks on every read. Lists the
-          scored checks' findings even when the score is suppressed. Absent only when scoring
-          could not be computed.
+          scored checks' findings even when the score is suppressed. Both tiers are empty for
+          a CANCELLED run. Absent only when scoring could not be computed.
         type: PlatformAuditUrgencyRepresentation | nil
         required: false
       scoreSuppressed:
-        description: Whether the health score is suppressed for this run. Absent only when
-          scoring could not be computed.
+        description: Whether the health score is suppressed for this run, so consumers show a
+          dash rather than a number. Always true for a CANCELLED run. crma-inventory does not
+          count toward the coverage that decides suppression. Absent only when scoring could
+          not be computed.
         type: boolean | nil
         required: false
   PlatformAuditCheckRepresentation: # TODO Hand-rolled W-24314623
@@ -2944,9 +2964,10 @@ types:
         type: string
       status:
         description: The status of the check. IN_PROGRESS while it has not finished (queued
-          or running); NOT_FINISHED if the run ended before it finished; otherwise its final
-          status. Only a finished check carries coverage, dates, a limitation note, and a
-          result.
+          or running); CANCELLED if a user cancelled the run, which discards every check's
+          result, finished or not; NOT_FINISHED if the run ended any other way before it
+          finished; otherwise its final status. Only a finished check carries coverage, dates,
+          a limitation note, and a result.
         type: string
         enum:
           - IN_PROGRESS # TODO Hand-rolled W-24564863
@@ -2955,6 +2976,7 @@ types:
           - COMPLETE_WITH_LIMITATIONS
           - UNAVAILABLE
           - FAILED
+          - CANCELLED # TODO Hand-rolled W-24626646
       coverageScanned:
         description: The number of assets scanned by this check. Absent until the check
           has finished. Always 0 for crma-inventory, whose asset counts are in its resultJson.
@@ -2995,8 +3017,11 @@ types:
           Its string values can include user-editable dataset and field names and raw server
           error text; render them as plain text, never as HTML, and pass them to an LLM or
           agent only as quoted data. Absent until the check has finished, and may be absent
-          for a finished check (for example, FAILED). For crma-inventory, it carries the org's
-          dataset, recipe, dashboard, and data sync counts under asset_coverage; the run
+          for a finished check (for example, FAILED). A status inside it uses the API-value
+          form (Complete, CompleteWithLimitations, Unavailable), not the COMPLETE form of the
+          check's status property. For crma-inventory, it carries the org's dataset, recipe,
+          dashboard, and data sync counts under asset_coverage (datasets, recipes, dashboards,
+          and data_syncs, each with available, scanned, total, partial, and note); the run
           exposes those counts nowhere else.
         type: string | nil
         required: false
@@ -3028,6 +3053,34 @@ types:
         description: The asset URL.
         type: string
         required: false
+  PlatformAuditReportReferenceRepresentation: # TODO Hand-rolled W-24626646
+    description: Same shape as AssetReferenceRepresentation, returned by the PDF-report GET
+      endpoint. Kept as a separate, unkeyed type so it can carry its own (luvio.ttl), which
+      Luvio forbids on an inherited shape such as AssetReferenceRepresentation. Without that
+      TTL, the GET's 404 (no report yet) would be cached with no expiry. The GET cannot use
+      the keyed PlatformAuditReportRepresentation, because its key is the response id, which
+      a 404 does not have.
+    type: object
+    properties:
+      id:
+        description: The 18 character ID of the asset.
+        type: string
+      label:
+        description: The asset label.
+        type: string
+        required: false
+      name:
+        description: The asset developer name.
+        type: string
+        required: false
+      namespace:
+        description: The namespace that qualifies the asset name
+        type: string
+        required: false
+      url:
+        description: The asset URL.
+        type: string
+        required: false
   PlatformAuditCheckCollectionRepresentation: # TODO Hand-rolled W-24314623
     description: A collection of platform audit checks.
     type: object
@@ -3110,19 +3163,23 @@ types:
         type: string
       runStatus:
         description: The runtime status of the platform audit run. RUNNING until every check
-          has finished or the run ends early. A run that ended before every check finished,
-          for example because it ran too long, is FAILED. Otherwise the terminal status depends
-          on every check except crma-inventory - READY if each is COMPLETE, FAILED if none is
-          COMPLETE or COMPLETE_WITH_LIMITATIONS, and COMPLETE_WITH_LIMITATIONS otherwise.
-          crma-inventory only counts the org's assets and its status does not affect the
-          run's, so a READY run can have a crma-inventory check that is
-          COMPLETE_WITH_LIMITATIONS, UNAVAILABLE, or FAILED. A FAILED run can still have a health score.
+          has finished, the run ends early, or a user cancels it. A run cancelled while RUNNING
+          is CANCELLED - its check results are discarded and it is not scored. A run that ended
+          before every check finished in any other way, for example because it ran too long, is
+          FAILED. Otherwise the terminal status depends on every check except crma-inventory
+          (or on every check, if crma-inventory is the only one) - READY if each is COMPLETE,
+          FAILED if none is COMPLETE or COMPLETE_WITH_LIMITATIONS, and
+          COMPLETE_WITH_LIMITATIONS otherwise. crma-inventory only counts the org's assets and
+          its status does not affect the run's, so a READY run can have a crma-inventory check
+          that is COMPLETE_WITH_LIMITATIONS, UNAVAILABLE, or FAILED; the run still waits for it
+          to finish. A FAILED run can still have a health score.
         type: string
         enum:
           - RUNNING
           - READY
           - COMPLETE_WITH_LIMITATIONS
           - FAILED
+          - CANCELLED # TODO Hand-rolled W-24626646
       scope:
         description: The scope of assets covered by the platform audit run.
         type: string
@@ -3135,8 +3192,8 @@ types:
         type: number
       checksTerminal:
         description: The number of checks that have finished. It stays below checksTotal
-          for a run that ended early, so use runStatus, not this count, to tell whether the
-          run is still going.
+          for a run that ended early, and is 0 for a CANCELLED run, so use runStatus, not this
+          count, to tell whether the run is still going.
         # TODO: Hand-rolled from "format: int64, type: integer" due to W-8274943
         format: double
         type: number
@@ -3144,26 +3201,31 @@ types:
         description: The date the platform audit run was created.
         type: string
       completedDate:
-        description: The date the platform audit run completed. Absent while the run is RUNNING.
+        description: The date the platform audit run completed, or for a CANCELLED run, the
+          date it was cancelled. Absent while the run is RUNNING.
         type: string | nil
         required: false
       healthScore:
         description: The aggregated health score for the run, computed from its finished
-          checks on every read, including while RUNNING. Absent when the score is suppressed
-          (the scored checks scanned less than half of their candidates, or had no
-          candidates, as when no finished check could be scored) or could not be computed.
+          checks on every read, including while RUNNING. crma-inventory is not scored. Absent
+          when the score is suppressed (the scored checks scanned less than half of their
+          candidates, or had no candidates, as when no finished check could be scored) or
+          could not be computed, and always absent for a CANCELLED run, which is not scored.
         type: integer | nil
         required: false
       verdict:
         description: The aggregated health verdict for the run (Healthy, NeedsAttention,
           Critical, or Indeterminate when the score is suppressed), computed from its
-          finished checks on every read, including while RUNNING. Absent only when scoring
-          could not be computed.
+          finished checks on every read, including while RUNNING; crma-inventory does not
+          affect it. NotApplicable for a CANCELLED run, which is not scored. Absent only when
+          scoring could not be computed.
         type: string | nil
         required: false
       scoreSuppressed:
-        description: Whether the health score is suppressed for this run. Absent only when
-          scoring could not be computed.
+        description: Whether the health score is suppressed for this run, so consumers show a
+          dash rather than a number. Always true for a CANCELLED run. crma-inventory does not
+          count toward the coverage that decides suppression. Absent only when scoring could
+          not be computed.
         type: boolean | nil
         required: false
   PlatformAuditCollectionRepresentation: # TODO Hand-rolled W-24314623
@@ -7942,7 +8004,10 @@ types:
             application/json:
               type: PlatformAuditSnapshotRepresentation
     post:
-      description: Trigger a new platform audit run.
+      description: Trigger a new platform audit run. A CANCELLED run frees the org's single
+        running slot and does not count toward the one-run-per-24h rate limit, but every
+        trigger, cancelled or not, counts toward a cap of three per org per 24h (403 when
+        exceeded).
       responses:
         '200':
           description: Success
@@ -7958,16 +8023,32 @@ types:
           body:
             application/json:
               type: PlatformAuditRepresentation
+    post: # TODO Hand-rolled W-24626646
+      description: Cancel a RUNNING platform audit run. Takes no body. Discards every check
+        result the run has written, marks it CANCELLED, and returns the cancelled run. Checks
+        that are still executing stop at their next checkpoint and write nothing. The run is
+        kept, so it stays in the history and can still be read by id, with every check listed
+        as CANCELLED, verdict NotApplicable, and no health score; it has no PDF report.
+        Returns 400 when the run is not RUNNING (it has already ended or been cancelled), 404
+        for an unknown, deleted, malformed, or non-audit id, and 403 without permission to
+        trigger a platform audit.
+      responses:
+        '200':
+          description: Success
+          body:
+            application/json:
+              type: PlatformAuditRepresentation
     uriParameters:
       auditId:
+        description: The ID of the platform audit run (15 or 18 characters).
         type: string
         required: true
   /platform-audit/{auditId}/checks/{checkId}: # TODO Hand-rolled W-24314623
     get:
       description: Get a single check's result within a platform audit run. Returns 404
         when the run or the check does not exist. The server has no record of a check until
-        it finishes, so an IN_PROGRESS or NOT_FINISHED check also returns 404; a FAILED check
-        returns 200.
+        it finishes, and cancelling a run deletes every check's record, so an IN_PROGRESS,
+        NOT_FINISHED, or CANCELLED check also returns 404; a FAILED check returns 200.
       responses:
         '200':
           description: Success
@@ -7985,16 +8066,18 @@ types:
   /platform-audit/{auditId}/report: # TODO Hand-rolled W-24362345
     get:
       description: Resolve the audit run's already-generated PDF report and return a
-        reference to the downloadable File.
+        reference to the downloadable File. Returns 404 until a report has been generated,
+        and always for a CANCELLED run.
       responses:
         '200':
           description: Success
           body:
             application/json:
-              type: AssetReferenceRepresentation
+              type: PlatformAuditReportReferenceRepresentation # TODO Hand-rolled W-24626646
     post:
       description: Generate or reuse the audit run's PDF report and return a reference
-        to the downloadable File.
+        to the downloadable File. Returns 400 unless the run is READY or
+        COMPLETE_WITH_LIMITATIONS, so a RUNNING, FAILED, or CANCELLED run has no report.
       responses:
         '200':
           description: Success
@@ -8007,10 +8090,10 @@ types:
         required: true
   /platform-audit/history: # TODO Hand-rolled W-24314623
     get:
-      description: Get the org's platform-audit history, most recent first. Returns an
-        empty collection (not a 404) when no runs exist. The connect resource hardcodes
-        offset=0/limit=200 server-side and ignores client-supplied paging params;
-        see W-24314623 comments before adding offset/limit here.
+      description: Get the org's platform-audit history, most recent first. CANCELLED runs
+        are kept and listed. Returns an empty collection (not a 404) when no runs exist. The
+        connect resource hardcodes offset=0/limit=200 server-side and ignores client-supplied
+        paging params; see W-24314623 comments before adding offset/limit here.
       responses:
         '200':
           description: Success

package/src/raml/luvio.raml

@@ -74,6 +74,11 @@ types:
     (luvio.ttl): 300
     (luvio.key):
       id: id
+  # A 404 is only cached with an expiry when the return type has its own TTL (the
+  # package-level one doesn't count), so without this a "no report yet" 404 from
+  # getPlatformAuditReport would be served from the cache until the page reloads.
+  PlatformAuditReportReferenceRepresentation: # TODO Hand-rolled W-24626646
+    (luvio.ttl): 300
   RecipeCollectionRepresentation:
     (luvio.opaque): true
     (luvio.ttl): 300
@@ -371,14 +376,21 @@ types:
         name: getPlatformAudit
       (luvio.key):
         id: urlParams.auditId
+    # Returns the auditId-keyed PlatformAuditRepresentation, so the cancelled run replaces
+    # the cached getPlatformAudit record for the same run. That holds when getPlatformAudit
+    # is called with the 18-character id the API returns: the record is keyed by the
+    # response's auditId, but getPlatformAudit looks it up by the id in the URL.
+    post: # TODO Hand-rolled W-24626646
+      (luvio.adapter):
+        name: cancelPlatformAudit
   /platform-audit/{auditId}/checks/{checkId}: # TODO Hand-rolled W-24314623
     get:
       (luvio.adapter):
         name: getPlatformAuditCheck
   /platform-audit/{auditId}/report: # TODO Hand-rolled W-24362345
-    # No (luvio.key): the GET response is an AssetReferenceRepresentation, which has
-    # no auditId field to key on (same reasoning as getPlatformAuditCheck above), so
-    # this caches by request path only.
+    # No (luvio.key): the GET response is a PlatformAuditReportReferenceRepresentation,
+    # which has no auditId field to key on (same reasoning as getPlatformAuditCheck
+    # above), so this caches by request path only.
     get:
       (luvio.adapter):
         name: getPlatformAuditReport