@roarkanalytics/sdk 2.30.0 → 2.33.0

package/src/resources/call.ts

@@ -42,16 +42,14 @@ export class Call extends APIResource {
     return this._client.get(path`/v1/call/${callID}/transcript`, { query, ...options });
   }
 
-  /**
-   * Fetch all evaluation run results for a specific call.
-   */
-  listEvaluationRuns(callID: string, options?: RequestOptions): APIPromise<CallListEvaluationRunsResponse> {
-    return this._client.get(path`/v1/call/${callID}/evaluation-run`, options);
-  }
-
   /**
    * Fetch all call-level metrics for a specific call, including both
-   * system-generated and custom metrics. Only returns successfully computed metrics.
+   * system-generated and custom metrics. Only returns rows from the **latest**
+   * metric-collection job per metric — if the same metric has been recomputed, prior
+   * runs are excluded and remain in the metric history. By default returns only
+   * successfully computed metrics; pass `?status=all` to also include rows that
+   * resolved as NOT_APPLICABLE / DATA_MISSING / ERROR (the `value` field is omitted
+   * on those entries — check `captureStatus`).
    */
   listMetrics(
     callID: string,
@@ -98,6 +96,8 @@ export namespace CallCreateResponse {
 
     customers: Array<Data.Customer> | null;
 
+    externalId: string | null;
+
     /**
      * ID of the project this call belongs to
      */
@@ -162,6 +162,14 @@ export namespace CallListResponse {
      */
     projectId: string;
 
+    /**
+     * Indicates the status of `recordingUrl`. `AVAILABLE`: signed URL returned.
+     * `NOT_AVAILABLE`: no recording on file yet (e.g. still processing). `RESTRICTED`:
+     * the calling API key does not have the `recording:read` permission and the URL
+     * has been withheld.
+     */
+    recordingUrlAccess: 'AVAILABLE' | 'NOT_AVAILABLE' | 'RESTRICTED';
+
     /**
      * Timestamp when the call started
      */
@@ -217,6 +225,12 @@ export namespace CallListResponse {
       | 'UNKNOWN'
       | null;
 
+    /**
+     * Caller-supplied correlation ID echoed back from the create request, if any was
+     * provided
+     */
+    externalId?: string | null;
+
     /**
      * IDs of metric policies that have been applied to this call
      */
@@ -332,6 +346,14 @@ export namespace CallGetByIDResponse {
      */
     projectId: string;
 
+    /**
+     * Indicates the status of `recordingUrl`. `AVAILABLE`: signed URL returned.
+     * `NOT_AVAILABLE`: no recording on file yet (e.g. still processing). `RESTRICTED`:
+     * the calling API key does not have the `recording:read` permission and the URL
+     * has been withheld.
+     */
+    recordingUrlAccess: 'AVAILABLE' | 'NOT_AVAILABLE' | 'RESTRICTED';
+
     /**
      * Timestamp when the call started
      */
@@ -387,6 +409,12 @@ export namespace CallGetByIDResponse {
       | 'UNKNOWN'
       | null;
 
+    /**
+     * Caller-supplied correlation ID echoed back from the create request, if any was
+     * provided
+     */
+    externalId?: string | null;
+
     /**
      * IDs of metric policies that have been applied to this call
      */
@@ -493,12 +521,12 @@ export namespace CallGetTranscriptResponse {
      */
     export interface Entry {
       /**
-       * End time offset in milliseconds from the start of the call
+       * End time offset in milliseconds from the start of the conversation
        */
       endOffsetMs: number;
 
       /**
-       * ID of the conversation participant who spoke this entry. References
+       * ID of the conversation participant who produced this entry. References
        * participants[].id.
        */
       participantId: string | null;
@@ -509,7 +537,7 @@ export namespace CallGetTranscriptResponse {
       role: 'AGENT' | 'CUSTOMER' | null;
 
       /**
-       * Start time offset in milliseconds from the start of the call
+       * Start time offset in milliseconds from the start of the conversation
        */
       startOffsetMs: number;
 
@@ -584,276 +612,277 @@ export namespace CallGetTranscriptResponse {
   }
 }
 
-export interface CallListEvaluationRunsResponse {
+export interface CallListMetricsResponse {
   /**
-   * Evaluation run response payload
+   * Conversation metrics response payload grouped by metric definition
    */
-  data: Array<CallListEvaluationRunsResponse.Data>;
+  data: Array<CallListMetricsResponse.Data>;
 }
 
-export namespace CallListEvaluationRunsResponse {
+export namespace CallListMetricsResponse {
+  /**
+   * Metric data grouped by metric definition
+   */
   export interface Data {
     /**
-     * All block runs for this evaluator, including skipped ones
+     * Description of what the metric measures
      */
-    blockRuns: Array<Data.BlockRun>;
-
-    evaluator: Data.Evaluator;
-
-    evidence: Array<Data.Evidence>;
+    description: string;
 
-    metrics: Array<Data.Metric>;
+    /**
+     * Unique identifier for the metric definition
+     */
+    metricDefinitionId: string;
 
     /**
-     * Status of the evaluator run
+     * Alias of `slug` retained for backwards compatibility. Same value as `slug`.
      */
-    status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
+    metricId: string;
 
     /**
-     * ID of the evaluator run
+     * Name of the metric
      */
-    id?: string;
+    name: string;
 
     /**
-     * When the evaluator run completed
+     * Whether metric is global or per-participant
      */
-    completedAt?: string | null;
+    scope: 'GLOBAL' | 'PER_PARTICIPANT';
 
     /**
-     * Result of the evaluator run based on score threshold (IRRELEVANT is mapped to
-     * SKIPPED)
+     * Stable metric slug
      */
-    result?: 'SUCCESS' | 'FAILURE' | 'SKIPPED' | null;
+    slug: string;
 
     /**
-     * Score of the evaluation run (0-1)
+     * Type of value this metric produces
      */
-    score?: number | null;
+    type: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET';
 
     /**
-     * When the evaluator run started
+     * Array of metric values (multiple for PER_PARTICIPANT metrics, or multiple
+     * segments/turns)
      */
-    startedAt?: string | null;
+    values: Array<Data.StandardMetricValue | Data.PropertyVerificationMetricValue>;
 
     /**
-     * Summary of the evaluation run
+     * Unit information if applicable
      */
-    summary?: string | null;
+    unit?: Data.Unit;
   }
 
   export namespace Data {
-    export interface BlockRun {
-      /**
-       * ID of the block definition
-       */
-      blockDefinitionId: string;
-
+    /**
+     * A metric value entry. Applies to every metric.
+     */
+    export interface StandardMetricValue {
       /**
-       * Name of the evaluation block
+       * Result state of this metric computation. SUCCESS carries a real `value`;
+       * NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted).
+       * Non-SUCCESS rows only appear when the request includes ?status=all.
        */
-      blockName: string;
+      captureStatus: 'SUCCESS' | 'NOT_APPLICABLE' | 'DATA_MISSING' | 'ERROR';
 
       /**
-       * ID of the block run instance
+       * ISO 8601 timestamp when the metric was computed
        */
-      blockRunId: string;
+      computedAt: string;
 
       /**
-       * When the block run was created
+       * Context level: CALL (entire conversation), SEGMENT (single segment),
+       * SEGMENT_RANGE (between/across segments)
        */
-      createdAt: string;
+      context: 'CALL' | 'SEGMENT' | 'SEGMENT_RANGE';
 
       /**
-       * Reason for the outcome (pass/fail explanation or skip reason)
+       * ID of the call this value was computed on. Only set when the response spans
+       * multiple conversations (e.g. job-scoped metric values).
        */
-      reason: string | null;
+      callId?: string;
 
       /**
-       * Result of the block run
+       * ID of the chat this value was computed on. Only set when the response spans
+       * multiple conversations (e.g. job-scoped metric values).
        */
-      result: 'PASSED' | 'FAILED' | 'SKIPPED' | null;
+      chatId?: string;
 
       /**
-       * Score of the block run (0-1)
+       * Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic
+       * metrics. Omitted on non-SUCCESS rows.
        */
-      score: number | null;
+      confidence?: number;
 
       /**
-       * Status of the block run
+       * Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout.
+       * Undefined for other statuses.
        */
-      status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED';
-    }
+      errorMessage?: string;
 
-    export interface Evaluator {
       /**
-       * ID of the evaluator
+       * Starting segment information (for SEGMENT_RANGE context metrics)
        */
-      id: string;
+      fromSegment?: StandardMetricValue.FromSegment;
 
       /**
-       * Name of the evaluator
+       * Role of participant (only for PER_PARTICIPANT metrics)
        */
-      name: string;
+      participantRole?: 'agent' | 'customer';
 
       /**
-       * Weight of the evaluator
+       * IDs of metric policies that triggered this metric computation
        */
-      weight?: number;
-    }
+      policyIds?: Array<string>;
 
-    export interface Evidence {
       /**
-       * Comment text of the evidence
+       * Segment information (for SEGMENT context metrics)
        */
-      commentText: string | null;
+      segment?: StandardMetricValue.Segment;
 
       /**
-       * Created at of the evidence
+       * Ending segment information (for SEGMENT_RANGE context metrics)
        */
-      createdAt: string;
+      toSegment?: StandardMetricValue.ToSegment;
 
       /**
-       * Is positive of the evidence
+       * The metric value (type depends on outputType). Present only on SUCCESS rows;
+       * omitted for NOT_APPLICABLE / DATA_MISSING / ERROR.
        */
-      isPositive: boolean;
+      value?: number | boolean | string;
 
       /**
-       * Snippet text of the evidence
+       * Explanation for the metric value (especially useful for AI-computed metrics)
        */
-      snippetText: string;
+      valueReasoning?: string;
     }
 
-    export interface Metric {
+    export namespace StandardMetricValue {
       /**
-       * Boolean value of the metric
+       * Starting segment information (for SEGMENT_RANGE context metrics)
        */
-      booleanValue: boolean | null;
+      export interface FromSegment {
+        /**
+         * Segment ID
+         */
+        id: string;
 
-      /**
-       * Confidence level of the metric (0-1)
-       */
-      confidence: number | null;
+        /**
+         * End time offset in milliseconds
+         */
+        endOffsetMs: number;
 
-      /**
-       * Created at of the metric
-       */
-      createdAt: string;
+        /**
+         * Start time offset in milliseconds
+         */
+        startOffsetMs: number;
 
-      /**
-       * Name of the metric
-       */
-      name: string;
+        /**
+         * Segment text content
+         */
+        text: string;
+      }
 
       /**
-       * Numeric value of the metric
+       * Segment information (for SEGMENT context metrics)
        */
-      numericValue: number | null;
+      export interface Segment {
+        /**
+         * Segment ID
+         */
+        id: string;
 
-      /**
-       * Reasoning of the metric
-       */
-      reasoning: string | null;
+        /**
+         * End time offset in milliseconds
+         */
+        endOffsetMs: number;
 
-      /**
-       * Role of the metric
-       */
-      role: string;
+        /**
+         * Start time offset in milliseconds
+         */
+        startOffsetMs: number;
 
-      /**
-       * Text value of the metric
-       */
-      textValue: string | null;
+        /**
+         * Segment text content
+         */
+        text: string;
+      }
 
       /**
-       * Value type of the metric
+       * Ending segment information (for SEGMENT_RANGE context metrics)
        */
-      valueType: string;
-    }
-  }
-}
-
-export interface CallListMetricsResponse {
-  /**
-   * Call metrics response payload grouped by metric definition
-   */
-  data: Array<CallListMetricsResponse.Data>;
-}
-
-export namespace CallListMetricsResponse {
-  /**
-   * Call metric data grouped by metric definition
-   */
-  export interface Data {
-    /**
-     * Description of what the metric measures
-     */
-    description: string;
-
-    /**
-     * Unique identifier for the metric definition
-     */
-    metricDefinitionId: string;
-
-    /**
-     * Stable metric identifier
-     */
-    metricId: string;
-
-    /**
-     * Name of the metric
-     */
-    name: string;
+      export interface ToSegment {
+        /**
+         * Segment ID
+         */
+        id: string;
 
-    /**
-     * Whether metric is global or per-participant
-     */
-    scope: 'GLOBAL' | 'PER_PARTICIPANT';
+        /**
+         * End time offset in milliseconds
+         */
+        endOffsetMs: number;
 
-    /**
-     * Type of value this metric produces
-     */
-    type: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET';
+        /**
+         * Start time offset in milliseconds
+         */
+        startOffsetMs: number;
 
-    /**
-     * Array of metric values (multiple for PER_PARTICIPANT metrics, or multiple
-     * segments/turns)
-     */
-    values: Array<Data.Value>;
+        /**
+         * Segment text content
+         */
+        text: string;
+      }
+    }
 
     /**
-     * Unit information if applicable
+     * Returned for the Property Mismatch metric (`property_transcript_mismatch`): the
+     * standard entry plus the per-property verdict breakdown.
      */
-    unit?: Data.Unit;
-  }
+    export interface PropertyVerificationMetricValue {
+      /**
+       * Result state of this metric computation. SUCCESS carries a real `value`;
+       * NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted).
+       * Non-SUCCESS rows only appear when the request includes ?status=all.
+       */
+      captureStatus: 'SUCCESS' | 'NOT_APPLICABLE' | 'DATA_MISSING' | 'ERROR';
 
-  export namespace Data {
-    export interface Value {
       /**
        * ISO 8601 timestamp when the metric was computed
        */
       computedAt: string;
 
       /**
-       * Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic
-       * metrics.
+       * Context level: CALL (entire conversation), SEGMENT (single segment),
+       * SEGMENT_RANGE (between/across segments)
        */
-      confidence: number;
+      context: 'CALL' | 'SEGMENT' | 'SEGMENT_RANGE';
 
       /**
-       * Context level: CALL (entire call), SEGMENT (single segment), SEGMENT_RANGE
-       * (between/across segments)
+       * ID of the call this value was computed on. Only set when the response spans
+       * multiple conversations (e.g. job-scoped metric values).
        */
-      context: 'CALL' | 'SEGMENT' | 'SEGMENT_RANGE';
+      callId?: string;
 
       /**
-       * The metric value (type depends on outputType)
+       * ID of the chat this value was computed on. Only set when the response spans
+       * multiple conversations (e.g. job-scoped metric values).
        */
-      value: number | boolean | string;
+      chatId?: string;
+
+      /**
+       * Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic
+       * metrics. Omitted on non-SUCCESS rows.
+       */
+      confidence?: number;
+
+      /**
+       * Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout.
+       * Undefined for other statuses.
+       */
+      errorMessage?: string;
 
       /**
        * Starting segment information (for SEGMENT_RANGE context metrics)
        */
-      fromSegment?: Value.FromSegment;
+      fromSegment?: PropertyVerificationMetricValue.FromSegment;
 
       /**
        * Role of participant (only for PER_PARTICIPANT metrics)
@@ -865,15 +894,27 @@ export namespace CallListMetricsResponse {
        */
       policyIds?: Array<string>;
 
+      /**
+       * Per-property verdicts for the Property Mismatch metric, in the order the
+       * properties were checked. Omitted for every other metric.
+       */
+      propertyVerdicts?: Array<PropertyVerificationMetricValue.PropertyVerdict>;
+
       /**
        * Segment information (for SEGMENT context metrics)
        */
-      segment?: Value.Segment;
+      segment?: PropertyVerificationMetricValue.Segment;
 
       /**
        * Ending segment information (for SEGMENT_RANGE context metrics)
        */
-      toSegment?: Value.ToSegment;
+      toSegment?: PropertyVerificationMetricValue.ToSegment;
+
+      /**
+       * The metric value (type depends on outputType). Present only on SUCCESS rows;
+       * omitted for NOT_APPLICABLE / DATA_MISSING / ERROR.
+       */
+      value?: number | boolean | string;
 
       /**
        * Explanation for the metric value (especially useful for AI-computed metrics)
@@ -881,13 +922,13 @@ export namespace CallListMetricsResponse {
       valueReasoning?: string;
     }
 
-    export namespace Value {
+    export namespace PropertyVerificationMetricValue {
       /**
        * Starting segment information (for SEGMENT_RANGE context metrics)
        */
       export interface FromSegment {
         /**
-         * Starting segment ID
+         * Segment ID
          */
         id: string;
 
@@ -902,11 +943,75 @@ export namespace CallListMetricsResponse {
         startOffsetMs: number;
 
         /**
-         * Starting segment text content
+         * Segment text content
          */
         text: string;
       }
 
+      export interface PropertyVerdict {
+        /**
+         * The value supplied at ingest, frozen at scoring time
+         */
+        expectedValue: string;
+
+        /**
+         * The call property checked, as sent at ingest
+         */
+        propertyName: string;
+
+        /**
+         * How this property resolved against the transcript. NOT_MENTIONED means the
+         * subject never came up and is not a mismatch.
+         */
+        verdict: 'MATCH' | 'MISMATCH' | 'NOT_MENTIONED';
+
+        /**
+         * What the transcript said instead. Only present when verdict is MISMATCH.
+         */
+        observedValue?: string;
+
+        /**
+         * Judge reasoning for this verdict
+         */
+        reasoning?: string;
+
+        /**
+         * The transcript segment this property was referred to in: the conflicting value
+         * for MISMATCH, the confirming reference for MATCH. Omitted for NOT_MENTIONED and
+         * when the verdict could not be anchored.
+         */
+        segment?: PropertyVerdict.Segment;
+      }
+
+      export namespace PropertyVerdict {
+        /**
+         * The transcript segment this property was referred to in: the conflicting value
+         * for MISMATCH, the confirming reference for MATCH. Omitted for NOT_MENTIONED and
+         * when the verdict could not be anchored.
+         */
+        export interface Segment {
+          /**
+           * Segment ID
+           */
+          id: string;
+
+          /**
+           * End time offset in milliseconds
+           */
+          endOffsetMs: number;
+
+          /**
+           * Start time offset in milliseconds
+           */
+          startOffsetMs: number;
+
+          /**
+           * Segment text content
+           */
+          text: string;
+        }
+      }
+
       /**
        * Segment information (for SEGMENT context metrics)
        */
@@ -937,7 +1042,7 @@ export namespace CallListMetricsResponse {
        */
       export interface ToSegment {
         /**
-         * Ending segment ID
+         * Segment ID
          */
         id: string;
 
@@ -952,7 +1057,7 @@ export namespace CallListMetricsResponse {
         startOffsetMs: number;
 
         /**
-         * Ending segment text content
+         * Segment text content
          */
         text: string;
       }
@@ -1085,6 +1190,20 @@ export interface CallCreateParams {
     | 'MAX_DURATION_REACHED'
     | 'UNKNOWN';
 
+  /**
+   * A stable identifier from your own system (e.g. session ID, conversation ID) used
+   * to correlate this call with OpenTelemetry traces. Set the same value as a
+   * `roark.external_id` span or resource attribute on your traces and the matching
+   * trace will be linked automatically. Must be unique within a project.
+   */
+  externalId?: string;
+
+  /**
+   * The LiveKit Cloud room ID to link this call with OpenTelemetry trace data from
+   * LiveKit. Used for matching calls with OTEL traces.
+   */
+  livekitRoomId?: string;
+
   /**
    * Custom properties to include with the call. These can be used for filtering and
    * will show in the call details page
@@ -1106,6 +1225,12 @@ export interface CallCreateParams {
    * List of transcript entries made during the call
    */
   transcript?: Array<CallCreateParams.TranscriptEntryAgent | CallCreateParams.TranscriptEntryCustomer>;
+
+  /**
+   * The Vapi call ID (UUID) to link this call with OpenTelemetry trace data from
+   * Vapi. Used for matching calls with OTEL traces.
+   */
+  vapiCallId?: string;
 }
 
 export namespace CallCreateParams {
@@ -1567,8 +1692,14 @@ export namespace CallCreateParams {
      * the agents array this tool invocation belongs to
      */
     export interface Agent {
+      /**
+       * The custom ID set on the agent
+       */
       customId?: string;
 
+      /**
+       * The Roark ID of the agent
+       */
       roarkId?: string;
     }
   }
@@ -1582,15 +1713,31 @@ export namespace CallCreateParams {
 
     text: string;
 
+    /**
+     * Metadata about the agent that spoke this turn - used to match which agent from
+     * the `agents` array this transcript entry belongs to
+     */
     agent?: TranscriptEntryAgent.Agent;
 
     languageCode?: string;
+
+    payload?: { [key: string]: unknown } | null;
   }
 
   export namespace TranscriptEntryAgent {
+    /**
+     * Metadata about the agent that spoke this turn - used to match which agent from
+     * the `agents` array this transcript entry belongs to
+     */
     export interface Agent {
+      /**
+       * The custom ID set on the agent
+       */
       customId?: string;
 
+      /**
+       * The Roark ID of the agent
+       */
       roarkId?: string;
     }
   }
@@ -1611,6 +1758,8 @@ export namespace CallCreateParams {
     customer?: TranscriptEntryCustomer.Customer;
 
     languageCode?: string;
+
+    payload?: { [key: string]: unknown } | null;
   }
 
   export namespace TranscriptEntryCustomer {
@@ -1686,6 +1835,15 @@ export interface CallListMetricsParams {
    * false)
    */
   flatten?: string;
+
+  /**
+   * Filter metrics by capture status. `success` (default) returns only successfully
+   * computed metrics — backwards-compatible with the historical behavior. `all` also
+   * returns NOT_APPLICABLE / DATA_MISSING / ERROR rows (with `value` omitted), so
+   * clients can distinguish "still computing" from "computed but no value" and exit
+   * retry loops correctly.
+   */
+  status?: 'success' | 'all';
 }
 
 export declare namespace Call {
@@ -1694,7 +1852,6 @@ export declare namespace Call {
     type CallListResponse as CallListResponse,
     type CallGetByIDResponse as CallGetByIDResponse,
     type CallGetTranscriptResponse as CallGetTranscriptResponse,
-    type CallListEvaluationRunsResponse as CallListEvaluationRunsResponse,
     type CallListMetricsResponse as CallListMetricsResponse,
     type CallListSentimentRunsResponse as CallListSentimentRunsResponse,
     type CallCreateParams as CallCreateParams,