@roarkanalytics/sdk 3.9.0 → 3.11.0

package/src/resources/simulation-template.ts

@@ -0,0 +1,190 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class SimulationTemplate extends APIResource {
+  /**
+   * Returns the built-in simulation templates, each resolved against this project:
+   * the metric and check definitions it collects, and the flows it runs with the
+   * variants it covers.
+   *
+   * A template is a preset rather than a stored object, so building a run from one
+   * produces an ordinary run plan you own and can edit afterwards. Pass a `slug` as
+   * `template` to POST /v1/simulation/run.
+   *
+   * Every entry is complete, so there is no per-template endpoint to follow up with,
+   * and the list is a fixed catalogue rather than a paginated one. Only templates a
+   * request can actually run are listed.
+   *
+   * @example
+   * ```ts
+   * const simulationTemplates =
+   *   await client.simulationTemplate.list();
+   * ```
+   */
+  list(options?: RequestOptions): APIPromise<SimulationTemplateListResponse> {
+    return this._client.get('/v1/simulation/template', options);
+  }
+}
+
+/**
+ * The built-in simulation templates.
+ */
+export interface SimulationTemplateListResponse {
+  data: Array<SimulationTemplateListResponse.Data>;
+}
+
+export namespace SimulationTemplateListResponse {
+  /**
+   * A built-in simulation template, resolved against this project: what it measures
+   * and what it runs.
+   */
+  export interface Data {
+    /**
+     * Grouping used in the dashboard library
+     */
+    category: string;
+
+    /**
+     * The per-simulation cap a run from this template uses unless the request sets its
+     * own.
+     */
+    defaultMaxSimulationDurationSeconds: number;
+
+    /**
+     * What this template tests
+     */
+    description: string;
+
+    /**
+     * The flows this template runs, and which of their ways of running it covers.
+     *
+     * Empty means the template presets only what to measure, and a run has to say what
+     * to measure it on: pass `flows` to POST /v1/simulation/run. When it is not empty
+     * you can still pass `flows` to narrow it, naming a subset of the ids listed here.
+     */
+    flows: Array<Data.Flow>;
+
+    /**
+     * Whether runs from this template also collect each attached flow's own metrics,
+     * on top of the template's set.
+     */
+    includeFlowMetrics: boolean;
+
+    /**
+     * The metrics this template collects, resolved to this project's definitions.
+     */
+    metrics: Array<Data.Metric>;
+
+    /**
+     * Stable identifier. Name this in a run request.
+     */
+    slug: string;
+
+    /**
+     * The Pass/Fail checks this template attaches alongside its metrics.
+     */
+    thresholds: Array<Data.Threshold>;
+
+    /**
+     * Display name
+     */
+    title: string;
+  }
+
+  export namespace Data {
+    export interface Flow {
+      /**
+       * Customer flow ID
+       */
+      id: string;
+
+      /**
+       * The other ways of running this flow that this template covers.
+       */
+      edgeCases: Array<Flow.EdgeCase>;
+
+      /**
+       * The flow's default way of running, when this template covers it. Null when it
+       * does not, or the flow has none.
+       */
+      happyPath: Flow.HappyPath | null;
+
+      /**
+       * The stable slug of a Roark-curated flow, null for one of your own.
+       *
+       * Prefer this over `id` when you are storing a run in version control: a curated
+       * flow is a global row, so its id is the same for every project but differs
+       * between deployments, while the slug is stable wherever the flow exists. Both are
+       * accepted by a run request.
+       */
+      slug: string | null;
+
+      /**
+       * Flow title
+       */
+      title: string;
+    }
+
+    export namespace Flow {
+      export interface EdgeCase {
+        /**
+         * Customer flow variant ID
+         */
+        id: string;
+
+        /**
+         * The stable slug of a Roark-curated edge case, null for one of your own.
+         *
+         * Prefer this over `id` in a run you keep in version control. A curated edge case
+         * is a global row, so its id differs between deployments, and renaming one
+         * replaces the row and its id outright. The slug survives both.
+         */
+        slug: string | null;
+
+        /**
+         * What this way of running the flow is called
+         */
+        title: string;
+      }
+
+      /**
+       * The flow's default way of running, when this template covers it. Null when it
+       * does not, or the flow has none.
+       */
+      export interface HappyPath {
+        title: string;
+      }
+    }
+
+    export interface Metric {
+      /**
+       * Metric definition ID
+       */
+      id: string;
+
+      /**
+       * Stable metric slug, e.g. "response_time"
+       */
+      slug: string;
+    }
+
+    export interface Threshold {
+      /**
+       * Metric definition ID
+       */
+      id: string;
+
+      /**
+       * Stable metric slug, e.g. "response_time"
+       */
+      slug: string;
+    }
+  }
+}
+
+export declare namespace SimulationTemplate {
+  export { type SimulationTemplateListResponse as SimulationTemplateListResponse };
+}

package/src/resources/simulation.ts

@@ -8,9 +8,16 @@ export class Simulation extends APIResource {
   /**
    * Starts a simulation and returns the run.
    *
-   * Send `plan` to describe a simulation and run it once. Add `saveAsPlan` to keep
-   * that configuration as a reusable run plan. Send `planId` instead to run a plan
-   * you already have.
+   * Send `template` to run one of the built-in templates: it supplies the metrics
+   * and checks, and for some templates the flows too, so the request only names the
+   * agent and the direction. Send `plan` to describe a simulation yourself and run
+   * it once. Send `planId` to run a plan you already have.
+   *
+   * `template` and `plan` both resolve to a run plan, returned as
+   * `simulationRunPlanId`. Add `saveAsPlan` to keep it, or read it back to see
+   * exactly what ran. A plan built from a template is a snapshot: retuning the
+   * template later never changes what that plan runs, which is what makes a saved
+   * one safe to pin in CI.
    *
    * @example
    * ```ts
@@ -92,7 +99,8 @@ export namespace SimulationRunResponse {
 
 export type SimulationRunParams =
   | SimulationRunParams.RunSimulationFromConfig
-  | SimulationRunParams.RunSimulationFromPlanID;
+  | SimulationRunParams.RunSimulationFromPlanID
+  | SimulationRunParams.RunSimulationFromTemplate;
 
 export declare namespace SimulationRunParams {
   export interface RunSimulationFromConfig {
@@ -211,6 +219,20 @@ export declare namespace SimulationRunParams {
        */
       flows?: Array<Plan.Flow>;
 
+      /**
+       * Also collect each attached flow's own metrics, on top of the `metrics` named
+       * here.
+       *
+       * Default true, which is what you want when you brought your own flows and their
+       * graders. Set false for a run whose metric list is meant to be exhaustive: a
+       * template like Load Testing or Voicemail deliberately grades a narrow set, and
+       * inheriting every flow metric on top multiplies analysis cost across the volume
+       * without adding signal.
+       *
+       * GET /v1/simulation/template returns the value each template expects.
+       */
+      includeFlowMetrics?: boolean;
+
       /**
        * Number of iterations to run for each test case (1-10000)
        */
@@ -292,7 +314,7 @@ export declare namespace SimulationRunParams {
         /**
          * The customer flow to run.
          */
-        id: string;
+        id?: string;
 
         /**
          * `"ALL"` runs every edge case the flow has when the run starts, so one added
@@ -311,6 +333,13 @@ export declare namespace SimulationRunParams {
          */
         personaOverrideId?: string | null;
 
+        /**
+         * The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run
+         * you keep in version control: a curated flow’s id differs between deployments,
+         * its slug does not. Your own flows have no slug and are named by `id`.
+         */
+        slug?: string;
+
         /**
          * Values for everything it resolves.
          */
@@ -322,13 +351,21 @@ export declare namespace SimulationRunParams {
           /**
            * The edge case to run.
            */
-          id: string;
+          id?: string;
 
           /**
            * Run this one as that persona instead of its own.
            */
           personaOverrideId?: string | null;
 
+          /**
+           * The edge case to run, by its stable slug, matched within this flow. Use instead
+           * of `id` for a run you keep in version control: a curated edge case’s id differs
+           * between deployments and changes outright if it is renamed. Your own edge cases
+           * have no slug and are named by `id`.
+           */
+          slug?: string;
+
           /**
            * Values for this one only.
            */
@@ -462,6 +499,207 @@ export declare namespace SimulationRunParams {
       variables: { [key: string]: string };
     }
   }
+
+  export interface RunSimulationFromTemplate {
+    /**
+     * The agent endpoints to call. No template can know these.
+     */
+    agentEndpoints: Array<RunSimulationFromTemplate.AgentEndpoint>;
+
+    /**
+     * Direction of the simulation (INBOUND or OUTBOUND)
+     */
+    direction: 'INBOUND' | 'OUTBOUND';
+
+    /**
+     * The template to run, as listed by GET /v1/simulation/template.
+     */
+    template: string;
+
+    /**
+     * Phrases that trigger end of call. Empty array disables the feature.
+     */
+    endCallPhrases?: Array<string>;
+
+    /**
+     * Semantic conditions that trigger end of call. The LLM evaluates the conversation
+     * against these conditions. Empty array disables the feature.
+     */
+    endCallReasons?: Array<string>;
+
+    /**
+     * Merge the customer's own recording of the real call into each simulation, so
+     * metrics can be scored against the live leg as well as the simulated one. This is
+     * the API equivalent of the dashboard's live-enrichment toggle.
+     *
+     * With this on, the run provisions a phone number and holds each call open for up
+     * to 15 minutes waiting for a matching call to be posted to POST /v1/call. A call
+     * matches on the provisioned number (`roarkPhoneNumber` on the job) with a start
+     * time inside the simulation window. If nothing arrives, the simulation still
+     * completes and any `LIVE`-sourced metric produces no value.
+     *
+     * Required by any metric whose `requiresLiveConversation` is true: without it that
+     * metric is silently skipped.
+     */
+    enrichWithLiveConversation?: boolean;
+
+    /**
+     * Execution mode (PARALLEL or SEQUENTIAL)
+     */
+    executionMode?: 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT';
+
+    /**
+     * The flows to run, in the same shape a run plan takes them.
+     *
+     * Required when the template lists no flows of its own: it presets what to
+     * measure, and this says what to measure it on. Optional when it does, where these
+     * REPLACE the ones it would have run, so you can narrow a suite to the cases you
+     * care about. Either way, GET /v1/simulation/template lists the flows and variant
+     * ids each template covers.
+     */
+    flows?: Array<RunSimulationFromTemplate.Flow>;
+
+    /**
+     * Number of iterations to run for each test case (1-10000)
+     */
+    iterationCount?: number;
+
+    /**
+     * Maximum number of concurrent simulation jobs
+     */
+    maxConcurrentJobs?: number;
+
+    /**
+     * Defaults to the template's `defaultMaxSimulationDurationSeconds`, as returned by
+     * GET /v1/simulation/template.
+     */
+    maxSimulationDurationSeconds?: number;
+
+    /**
+     * What to call this. Defaults to the template's name and the date, and required
+     * with `saveAsPlan`.
+     */
+    name?: string;
+
+    /**
+     * Keeps the resolved configuration as a run plan, listed by GET
+     * /v1/simulation/plan and re-runnable with `planId`. Requires `name`.
+     */
+    saveAsPlan?: boolean;
+
+    /**
+     * Timeout in seconds for silence detection
+     */
+    silenceTimeoutSeconds?: number;
+
+    /**
+     * Values for the {{variables}} the run resolves. An object applies them
+     * everywhere; an array targets a flow, its happy path, or one of its edge cases
+     * with `flowId`.
+     *
+     * The scenario-scoped form the other variants accept is not valid here: a template
+     * run is always flow-based, so there would be no scenario for it to reach.
+     */
+    variables?: { [key: string]: string } | Array<RunSimulationFromTemplate.UnionMember1>;
+  }
+
+  export namespace RunSimulationFromTemplate {
+    export interface AgentEndpoint {
+      id: string;
+    }
+
+    /**
+     * One customer flow attached to a run plan, and which of its ways of running you
+     * cover.
+     *
+     * Attaching the same flow more than once with different overrides is how you fan
+     * it out across personas or values.
+     */
+    export interface Flow {
+      /**
+       * The customer flow to run.
+       */
+      id?: string;
+
+      /**
+       * `"ALL"` runs every edge case the flow has when the run starts, so one added
+       * later is covered. An array runs only the ones you name, each able to carry its
+       * own persona override and values.
+       */
+      edgeCases?: 'ALL' | Array<Flow.UnionMember1>;
+
+      /**
+       * Run the flow's happy path. Resolved when the run starts, so it follows the flow.
+       */
+      happyPath?: boolean;
+
+      /**
+       * Runs everything this attachment resolves as that persona instead of its own.
+       */
+      personaOverrideId?: string | null;
+
+      /**
+       * The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run
+       * you keep in version control: a curated flow’s id differs between deployments,
+       * its slug does not. Your own flows have no slug and are named by `id`.
+       */
+      slug?: string;
+
+      /**
+       * Values for everything it resolves.
+       */
+      variables?: { [key: string]: string };
+    }
+
+    export namespace Flow {
+      export interface UnionMember1 {
+        /**
+         * The edge case to run.
+         */
+        id?: string;
+
+        /**
+         * Run this one as that persona instead of its own.
+         */
+        personaOverrideId?: string | null;
+
+        /**
+         * The edge case to run, by its stable slug, matched within this flow. Use instead
+         * of `id` for a run you keep in version control: a curated edge case’s id differs
+         * between deployments and changes outright if it is renamed. Your own edge cases
+         * have no slug and are named by `id`.
+         */
+        slug?: string;
+
+        /**
+         * Values for this one only.
+         */
+        variables?: { [key: string]: string };
+      }
+    }
+
+    export interface UnionMember1 {
+      /**
+       * A customer flow this plan runs.
+       */
+      flowId: string;
+
+      /**
+       * The values to apply.
+       */
+      variables: { [key: string]: string };
+
+      /**
+       * Narrow to one edge case of that flow.
+       */
+      edgeCaseId?: string;
+
+      /**
+       * Narrow to the flow's happy path.
+       */
+      happyPath?: true;
+    }
+  }
 }
 
 export declare namespace Simulation {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '3.9.0'; // x-release-please-version
+export const VERSION = '3.11.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "3.9.0";
+export declare const VERSION = "3.11.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "3.9.0";
+export declare const VERSION = "3.11.0";
 //# sourceMappingURL=version.d.ts.map

package/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '3.9.0'; // x-release-please-version
+exports.VERSION = '3.11.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,OAAO,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,QAAQ,CAAC,CAAC,2BAA2B"}

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '3.9.0'; // x-release-please-version
+export const VERSION = '3.11.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map

package/version.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,2BAA2B"}