@roarkanalytics/sdk 2.23.1 → 2.25.0

package/src/resources/metric.ts

@@ -5,16 +5,112 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 export class Metric extends APIResource {
+  /**
+   * Create a new custom metric definition. The metric will be added to the specified
+   * analysis package and can be used for evaluating calls.
+   *
+   * @example
+   * ```ts
+   * const response = await client.metric.createDefinition({
+   *   analysisPackageId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   name: 'Customer Satisfaction',
+   *   outputType: 'BOOLEAN',
+   * });
+   * ```
+   */
+  createDefinition(
+    body: MetricCreateDefinitionParams,
+    options?: RequestOptions,
+  ): APIPromise<MetricCreateDefinitionResponse> {
+    return this._client.post('/v1/metric/definitions', { body, ...options });
+  }
+
   /**
    * Fetch all metric definitions available in the project, including both
    * system-generated and custom metrics. Only returns metrics from enabled analysis
    * packages.
+   *
+   * @example
+   * ```ts
+   * const response = await client.metric.listDefinitions();
+   * ```
    */
   listDefinitions(options?: RequestOptions): APIPromise<MetricListDefinitionsResponse> {
     return this._client.get('/v1/metric/definitions', options);
   }
 }
 
+export interface MetricCreateDefinitionResponse {
+  /**
+   * Metric definition data
+   */
+  data: MetricCreateDefinitionResponse.Data;
+}
+
+export namespace MetricCreateDefinitionResponse {
+  /**
+   * Metric definition data
+   */
+  export interface Data {
+    /**
+     * Unique identifier for the metric definition
+     */
+    id: string;
+
+    /**
+     * Description of what the metric measures
+     */
+    description: string;
+
+    /**
+     * Stable metric identifier (e.g. "call_reason", "customer_satisfaction")
+     */
+    metricId: string;
+
+    /**
+     * Name of the metric
+     */
+    name: string;
+
+    /**
+     * Whether metric is global or per-participant
+     */
+    scope: 'GLOBAL' | 'PER_PARTICIPANT';
+
+    /**
+     * Which levels this metric can produce values at
+     */
+    supportedContexts: Array<'CALL' | 'SEGMENT' | 'TURN'>;
+
+    /**
+     * Type of value this metric produces
+     */
+    type: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET';
+
+    /**
+     * Unit information if applicable
+     */
+    unit?: Data.Unit;
+  }
+
+  export namespace Data {
+    /**
+     * Unit information if applicable
+     */
+    export interface Unit {
+      /**
+       * Name of the unit
+       */
+      name: string;
+
+      /**
+       * Symbol for the unit
+       */
+      symbol: string | null;
+    }
+  }
+}
+
 export interface MetricListDefinitionsResponse {
   /**
    * Metrics response payload
@@ -38,7 +134,7 @@ export namespace MetricListDefinitionsResponse {
     description: string;
 
     /**
-     * Stable metric identifier
+     * Stable metric identifier (e.g. "call_reason", "customer_satisfaction")
      */
     metricId: string;
 
@@ -86,6 +182,141 @@ export namespace MetricListDefinitionsResponse {
   }
 }
 
+export interface MetricCreateDefinitionParams {
+  /**
+   * ID of the analysis package to add this metric to
+   */
+  analysisPackageId: string;
+
+  /**
+   * Name of the metric
+   */
+  name: string;
+
+  /**
+   * Type of value this metric produces
+   */
+  outputType: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET';
+
+  /**
+   * Label for the false/negative case (only for BOOLEAN type)
+   */
+  booleanFalseLabel?: string;
+
+  /**
+   * Label for the true/positive case (only for BOOLEAN type)
+   */
+  booleanTrueLabel?: string;
+
+  /**
+   * Options for classification. Required for CLASSIFICATION type.
+   */
+  classificationOptions?: Array<MetricCreateDefinitionParams.ClassificationOption>;
+
+  /**
+   * LLM prompt/criteria for evaluating this metric. Used to instruct the model on
+   * how to score. Required for BOOLEAN, NUMERIC, TEXT, and SCALE types.
+   */
+  llmPrompt?: string;
+
+  /**
+   * Maximum number of classifications that can be selected (only for CLASSIFICATION
+   * type)
+   */
+  maxClassifications?: number;
+
+  /**
+   * Unique identifier for the metric (e.g. "customer_satisfaction"). Auto-generated
+   * from name if not provided.
+   */
+  metricId?: string;
+
+  /**
+   * Participant role to evaluate. Required when scope is PER_PARTICIPANT.
+   */
+  participantRole?: 'AGENT' | 'CUSTOMER' | 'SIMULATED_CUSTOMER' | 'BACKGROUND_SPEAKER';
+
+  /**
+   * Labels for scale ranges (only for SCALE type)
+   */
+  scaleLabels?: Array<MetricCreateDefinitionParams.ScaleLabel>;
+
+  /**
+   * Maximum value for scale. Required for SCALE type.
+   */
+  scaleMax?: number;
+
+  /**
+   * Minimum value for scale. Required for SCALE type.
+   */
+  scaleMin?: number;
+
+  /**
+   * Whether metric is global or per-participant (default: GLOBAL)
+   */
+  scope?: 'GLOBAL' | 'PER_PARTICIPANT';
+
+  /**
+   * Which levels this metric can produce values at (default: ["CALL"])
+   */
+  supportedContexts?: Array<'CALL' | 'SEGMENT' | 'TURN'>;
+}
+
+export namespace MetricCreateDefinitionParams {
+  export interface ClassificationOption {
+    /**
+     * Description of what this option means
+     */
+    description: string;
+
+    /**
+     * Display order of this option
+     */
+    displayOrder: number;
+
+    /**
+     * Label for this classification option
+     */
+    label: string;
+  }
+
+  export interface ScaleLabel {
+    /**
+     * Display order of this label
+     */
+    displayOrder: number;
+
+    /**
+     * Label for this range
+     */
+    label: string;
+
+    /**
+     * Maximum value for this label range
+     */
+    rangeMax: number;
+
+    /**
+     * Minimum value for this label range
+     */
+    rangeMin: number;
+
+    /**
+     * Hex color code for this label (e.g. "#FF0000")
+     */
+    colorHex?: string;
+
+    /**
+     * Description of what this range means
+     */
+    description?: string;
+  }
+}
+
 export declare namespace Metric {
-  export { type MetricListDefinitionsResponse as MetricListDefinitionsResponse };
+  export {
+    type MetricCreateDefinitionResponse as MetricCreateDefinitionResponse,
+    type MetricListDefinitionsResponse as MetricListDefinitionsResponse,
+    type MetricCreateDefinitionParams as MetricCreateDefinitionParams,
+  };
 }

package/src/resources/simulation-job.ts

@@ -191,7 +191,7 @@ export namespace SimulationJobGetByIDResponse {
       /**
        * Gender of the persona
        */
-      gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+      gender: 'MALE' | 'FEMALE';
 
       /**
        * Whether the persona uses filler words like "um" and "uh"
@@ -223,6 +223,12 @@ export namespace SimulationJobGetByIDResponse {
        */
       properties: { [key: string]: unknown };
 
+      /**
+       * Controls how quickly the persona responds to pauses in conversation (QUICK,
+       * NORMAL, RELAXED)
+       */
+      responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
       /**
        * Speech clarity of the persona
        */
@@ -422,7 +428,7 @@ export namespace SimulationJobLookupResponse {
       /**
        * Gender of the persona
        */
-      gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+      gender: 'MALE' | 'FEMALE';
 
       /**
        * Whether the persona uses filler words like "um" and "uh"
@@ -454,6 +460,12 @@ export namespace SimulationJobLookupResponse {
        */
       properties: { [key: string]: unknown };
 
+      /**
+       * Controls how quickly the persona responds to pauses in conversation (QUICK,
+       * NORMAL, RELAXED)
+       */
+      responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
       /**
        * Speech clarity of the persona
        */

package/src/resources/simulation-persona.ts

@@ -138,7 +138,7 @@ export namespace SimulationPersonaCreateResponse {
     /**
      * Gender of the persona
      */
-    gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+    gender: 'MALE' | 'FEMALE';
 
     /**
      * Whether the persona uses filler words like "um" and "uh"
@@ -170,6 +170,12 @@ export namespace SimulationPersonaCreateResponse {
      */
     properties: { [key: string]: unknown };
 
+    /**
+     * Controls how quickly the persona responds to pauses in conversation (QUICK,
+     * NORMAL, RELAXED)
+     */
+    responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
     /**
      * Speech clarity of the persona
      */
@@ -265,7 +271,7 @@ export namespace SimulationPersonaUpdateResponse {
     /**
      * Gender of the persona
      */
-    gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+    gender: 'MALE' | 'FEMALE';
 
     /**
      * Whether the persona uses filler words like "um" and "uh"
@@ -297,6 +303,12 @@ export namespace SimulationPersonaUpdateResponse {
      */
     properties: { [key: string]: unknown };
 
+    /**
+     * Controls how quickly the persona responds to pauses in conversation (QUICK,
+     * NORMAL, RELAXED)
+     */
+    responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
     /**
      * Speech clarity of the persona
      */
@@ -394,7 +406,7 @@ export namespace SimulationPersonaListResponse {
     /**
      * Gender of the persona
      */
-    gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+    gender: 'MALE' | 'FEMALE';
 
     /**
      * Whether the persona uses filler words like "um" and "uh"
@@ -426,6 +438,12 @@ export namespace SimulationPersonaListResponse {
      */
     properties: { [key: string]: unknown };
 
+    /**
+     * Controls how quickly the persona responds to pauses in conversation (QUICK,
+     * NORMAL, RELAXED)
+     */
+    responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
     /**
      * Speech clarity of the persona
      */
@@ -538,7 +556,7 @@ export namespace SimulationPersonaGetByIDResponse {
     /**
      * Gender of the persona
      */
-    gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+    gender: 'MALE' | 'FEMALE';
 
     /**
      * Whether the persona uses filler words like "um" and "uh"
@@ -570,6 +588,12 @@ export namespace SimulationPersonaGetByIDResponse {
      */
     properties: { [key: string]: unknown };
 
+    /**
+     * Controls how quickly the persona responds to pauses in conversation (QUICK,
+     * NORMAL, RELAXED)
+     */
+    responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
     /**
      * Speech clarity of the persona
      */
@@ -627,7 +651,7 @@ export interface SimulationPersonaCreateParams {
   /**
    * Gender of the persona
    */
-  gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+  gender: 'MALE' | 'FEMALE';
 
   /**
    * Primary language ISO 639-1 code for the persona
@@ -692,6 +716,12 @@ export interface SimulationPersonaCreateParams {
    */
   properties?: { [key: string]: unknown };
 
+  /**
+   * Controls how quickly the persona responds to pauses in conversation (QUICK,
+   * NORMAL, RELAXED)
+   */
+  responseTiming?: 'RELAXED' | 'NORMAL' | 'QUICK';
+
   /**
    * Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)
    */
@@ -766,7 +796,7 @@ export interface SimulationPersonaUpdateParams {
   /**
    * Gender of the persona
    */
-  gender?: 'MALE' | 'FEMALE' | 'NEUTRAL';
+  gender?: 'MALE' | 'FEMALE';
 
   /**
    * Whether the persona uses filler words like "um" and "uh"
@@ -798,6 +828,12 @@ export interface SimulationPersonaUpdateParams {
    */
   properties?: { [key: string]: unknown };
 
+  /**
+   * Controls how quickly the persona responds to pauses in conversation (QUICK,
+   * NORMAL, RELAXED)
+   */
+  responseTiming?: 'RELAXED' | 'NORMAL' | 'QUICK';
+
   /**
    * Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)
    */

package/src/resources/simulation-run-plan-job.ts

@@ -39,7 +39,8 @@ export class SimulationRunPlanJob extends APIResource {
   }
 
   /**
-   * Create and execute a job for an existing simulation run plan
+   * Create and execute a job for an existing simulation run plan. Optionally provide
+   * runtime variables to override plan-defined variables.
    *
    * @example
    * ```ts
@@ -48,8 +49,12 @@ export class SimulationRunPlanJob extends APIResource {
    * );
    * ```
    */
-  start(planID: unknown, options?: RequestOptions): APIPromise<SimulationRunPlanJobStartResponse> {
-    return this._client.post(path`/v1/simulation/plan/${planID}/job`, options);
+  start(
+    planID: unknown,
+    body: SimulationRunPlanJobStartParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SimulationRunPlanJobStartResponse> {
+    return this._client.post(path`/v1/simulation/plan/${planID}/job`, { body, ...options });
   }
 }
 
@@ -210,6 +215,7 @@ export namespace SimulationRunPlanJobGetByIDResponse {
         | 'SIMULATING'
         | 'ANALYZING'
         | 'EVALUATING'
+        | 'COLLECTING_METRICS'
         | 'COMPLETED';
 
       /**
@@ -342,7 +348,7 @@ export namespace SimulationRunPlanJobGetByIDResponse {
         /**
          * Gender of the persona
          */
-        gender: 'MALE' | 'FEMALE' | 'NEUTRAL';
+        gender: 'MALE' | 'FEMALE';
 
         /**
          * Whether the persona uses filler words like "um" and "uh"
@@ -374,6 +380,12 @@ export namespace SimulationRunPlanJobGetByIDResponse {
          */
         properties: { [key: string]: unknown };
 
+        /**
+         * Controls how quickly the persona responds to pauses in conversation (QUICK,
+         * NORMAL, RELAXED)
+         */
+        responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK';
+
         /**
          * Speech clarity of the persona
          */
@@ -511,11 +523,41 @@ export interface SimulationRunPlanJobListParams {
     | 'CANCELLING';
 }
 
+export interface SimulationRunPlanJobStartParams {
+  /**
+   * Runtime variables that override plan-defined scenario variables. Accepts one of
+   * two formats:
+   *
+   * Option 1 — Global (flat key-value object, applies to ALL scenarios): {
+   * "orderNumber": "12345", "environment": "staging" }
+   *
+   * Option 2 — Per-scenario (array of objects with scenarioId + variables): [ {
+   * "scenarioId": "550e8400-...", "variables": { "orderNumber": "12345" } }, {
+   * "scenarioId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ]
+   */
+  variables?: { [key: string]: string } | Array<SimulationRunPlanJobStartParams.UnionMember1>;
+}
+
+export namespace SimulationRunPlanJobStartParams {
+  export interface UnionMember1 {
+    /**
+     * ID of the scenario to apply variables to
+     */
+    scenarioId: string;
+
+    /**
+     * Key-value pairs for this scenario
+     */
+    variables: { [key: string]: string };
+  }
+}
+
 export declare namespace SimulationRunPlanJob {
   export {
     type SimulationRunPlanJobListResponse as SimulationRunPlanJobListResponse,
     type SimulationRunPlanJobGetByIDResponse as SimulationRunPlanJobGetByIDResponse,
     type SimulationRunPlanJobStartResponse as SimulationRunPlanJobStartResponse,
     type SimulationRunPlanJobListParams as SimulationRunPlanJobListParams,
+    type SimulationRunPlanJobStartParams as SimulationRunPlanJobStartParams,
   };
 }