@roarkanalytics/sdk 5.11.0 → 5.13.0

package/src/lib/config.ts

@@ -0,0 +1,131 @@
+// Code-first config authoring: a typed, ergonomic alternative to hand-written
+// config YAML. Build agents, tools, personas, flows, metrics and the rest in
+// TypeScript, then ship them with `client.config.apply(...)` (or preview with
+// `client.config.diff(...)`).
+//
+// Each `define*` helper injects the resource's `kind` (and any fixed
+// discriminator) and returns the exact param object the config endpoints expect,
+// so the output is identical to the YAML path: both produce a config bundle.
+// Input types are DERIVED from the generated `ConfigApplyParams`, so a new field
+// on a resource (for example a tool `handler`) shows up here automatically on the
+// next codegen, with no change to this file.
+//
+// This lives in `src/lib`, which Stainless codegen never touches. Import it from
+// `@roarkanalytics/sdk/lib/config`.
+
+import type { ConfigApplyParams } from '../resources/config';
+
+// ── Cross-references ──
+// A resource that points at another by name accepts either the construct a
+// `define*` helper returned (its `name` is used) or a bare name string.
+export type Ref<T extends { name: string }> = T | string;
+
+const refName = <T extends { name: string }>(ref: Ref<T>): string =>
+  typeof ref === 'string' ? ref : ref.name;
+
+// ── Friendly aliases for the generated param types ──
+export type AgentConfig = ConfigApplyParams.AgentConfig;
+export type HTTPRequestDefinitionConfig = ConfigApplyParams.HTTPRequestDefinitionConfig;
+export type PersonaConfig = ConfigApplyParams.PersonaConfig;
+export type ImprovFlowConfig = ConfigApplyParams.ImprovFlowConfig;
+export type ScriptedFlowConfig = ConfigApplyParams.ScriptedFlowConfig;
+export type CollectorConfig = ConfigApplyParams.CollectorConfig;
+export type MetricConfig = ConfigApplyParams.MetricConfig;
+export type SimulationPlanConfig = ConfigApplyParams.SimulationPlanConfig;
+export type QaSimulationPlanConfig = ConfigApplyParams.QaSimulationPlanConfig;
+export type SimulationGroupConfig = ConfigApplyParams.SimulationGroupConfig;
+export type AlertConfig = ConfigApplyParams.AlertConfig;
+export type ToolConfig = ConfigApplyParams.ToolConfig;
+export type DashboardConfig = ConfigApplyParams.DashboardConfig;
+export type ProjectConfig = ConfigApplyParams.ProjectConfig;
+
+/** Any resource a config bundle can carry. */
+export type ResourceConfig = ConfigApplyParams['resources'][number];
+
+// ── Builders ──
+// Prompts are just strings here: pass an inline template literal or
+// `readFileSync('./prompt.md', 'utf8')`. No `file://` sentinel needed.
+
+export const defineAgent = (agent: Omit<AgentConfig, 'kind'>): AgentConfig => ({ kind: 'agent', ...agent });
+
+export const defineHTTPRequestDefinition = (
+  def: Omit<HTTPRequestDefinitionConfig, 'kind'>,
+): HTTPRequestDefinitionConfig => ({ kind: 'httpRequestDefinition', ...def });
+
+export const definePersona = (persona: Omit<PersonaConfig, 'kind'>): PersonaConfig => ({
+  kind: 'persona',
+  ...persona,
+});
+
+export const defineImprovFlow = (flow: Omit<ImprovFlowConfig, 'kind' | 'type'>): ImprovFlowConfig => ({
+  kind: 'flow',
+  type: 'improv',
+  ...flow,
+});
+
+export const defineScriptedFlow = (flow: Omit<ScriptedFlowConfig, 'kind' | 'type'>): ScriptedFlowConfig => ({
+  kind: 'flow',
+  type: 'scripted',
+  ...flow,
+});
+
+export const defineCollector = (collector: Omit<CollectorConfig, 'kind'>): CollectorConfig => ({
+  kind: 'collector',
+  ...collector,
+});
+
+export const defineMetric = (metric: Omit<MetricConfig, 'kind'>): MetricConfig => ({
+  kind: 'metric',
+  ...metric,
+});
+
+export const defineSimulationPlan = (plan: Omit<SimulationPlanConfig, 'kind'>): SimulationPlanConfig => ({
+  kind: 'simulationPlan',
+  ...plan,
+});
+
+export const defineQaSimulationPlan = (
+  plan: Omit<QaSimulationPlanConfig, 'kind' | 'template'>,
+): QaSimulationPlanConfig => ({ kind: 'simulationPlan', template: 'question-answer-check', ...plan });
+
+export const defineSimulationGroup = (group: Omit<SimulationGroupConfig, 'kind'>): SimulationGroupConfig => ({
+  kind: 'simulationGroup',
+  ...group,
+});
+
+export const defineAlert = (alert: Omit<AlertConfig, 'kind'>): AlertConfig => ({ kind: 'alert', ...alert });
+
+export const defineDashboard = (dashboard: Omit<DashboardConfig, 'kind'>): DashboardConfig => ({
+  kind: 'dashboard',
+  ...dashboard,
+});
+
+export const defineProject = (project: Omit<ProjectConfig, 'kind'>): ProjectConfig => ({
+  kind: 'project',
+  ...project,
+});
+
+/** Input to `defineTool`: `agent` accepts the agent construct or a name string. */
+export type DefineToolInput = Omit<ToolConfig, 'kind' | 'agent'> & {
+  /** Scope the tool to one agent (omit for a project-wide tool). */
+  agent?: Ref<AgentConfig>;
+};
+
+export const defineTool = (tool: DefineToolInput): ToolConfig => {
+  const { agent, ...rest } = tool;
+  return { kind: 'tool', ...rest, ...(agent === undefined ? {} : { agent: refName(agent) }) };
+};
+
+// ── The bundle ──
+// `defineConfig` assembles the bundle you hand to `client.config.apply(bundle)`
+// or `client.config.diff(bundle)`. `resources` accepts both construct outputs
+// and raw resource objects, so a kind without a dedicated builder still fits.
+
+export const defineConfig = (bundle: {
+  resources: Array<ResourceConfig>;
+  /** When true (the server default) config-managed resources absent from the bundle are deleted. */
+  prune?: boolean;
+}): ConfigApplyParams => ({
+  resources: bundle.resources,
+  ...(bundle.prune === undefined ? {} : { prune: bundle.prune }),
+});

package/src/resources/call.ts

@@ -560,7 +560,8 @@ export namespace CallAppendToolInvocationsResponse {
       completedAt: string | null;
 
       /**
-       * Number of successfully completed items
+       * Number of items that finished without failing: a value was written, or the
+       * metric did not apply to the conversation
        */
       completedItems: number;
 
@@ -570,12 +571,14 @@ export namespace CallAppendToolInvocationsResponse {
       createdAt: string;
 
       /**
-       * Error message if the job failed
+       * Why the job failed or, on a COMPLETED job with failedItems above 0, why those
+       * items failed
        */
       errorMessage: string | null;
 
       /**
-       * Number of failed items
+       * Number of items that could not be computed, for example because an artifact the
+       * metric reads (such as diarization) failed to generate
        */
       failedItems: number;
 
@@ -1764,7 +1767,8 @@ export namespace CallUpdatePropertiesResponse {
       completedAt: string | null;
 
       /**
-       * Number of successfully completed items
+       * Number of items that finished without failing: a value was written, or the
+       * metric did not apply to the conversation
        */
       completedItems: number;
 
@@ -1774,12 +1778,14 @@ export namespace CallUpdatePropertiesResponse {
       createdAt: string;
 
       /**
-       * Error message if the job failed
+       * Why the job failed or, on a COMPLETED job with failedItems above 0, why those
+       * items failed
        */
       errorMessage: string | null;
 
       /**
-       * Number of failed items
+       * Number of items that could not be computed, for example because an artifact the
+       * metric reads (such as diarization) failed to generate
        */
       failedItems: number;
 

package/src/resources/index.ts

@@ -189,6 +189,7 @@ export {
   MetricCollectionJob,
   type MetricCollectionJobCreateResponse,
   type MetricCollectionJobListResponse,
+  type MetricCollectionJobCancelResponse,
   type MetricCollectionJobGetByIDResponse,
   type MetricCollectionJobCreateParams,
   type MetricCollectionJobListParams,

package/src/resources/metric-collection-job.ts

@@ -42,6 +42,28 @@ export class MetricCollectionJob extends APIResource {
     return this._client.get('/v1/metric/collection-jobs', { query, ...options });
   }
 
+  /**
+   * Stops a metric collection job that has not finished. No further conversations
+   * are processed and the job ends in CANCELED.
+   *
+   * Items the job had not reached are marked SKIPPED. Metric values already produced
+   * are kept, and items that were mid-computation when the cancel arrived may still
+   * complete. Only the items that completed are billed.
+   *
+   * Safe to call more than once: a job that has already finished (COMPLETED, FAILED,
+   * or CANCELED) is returned unchanged.
+   *
+   * @example
+   * ```ts
+   * const response = await client.metricCollectionJob.cancel(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  cancel(jobID: string, options?: RequestOptions): APIPromise<MetricCollectionJobCancelResponse> {
+    return this._client.post(path`/v1/metric/collection-jobs/${jobID}/cancel`, options);
+  }
+
   /**
    * Returns a specific metric collection job with progress information.
    *
@@ -80,7 +102,8 @@ export namespace MetricCollectionJobCreateResponse {
     completedAt: string | null;
 
     /**
-     * Number of successfully completed items
+     * Number of items that finished without failing: a value was written, or the
+     * metric did not apply to the conversation
      */
     completedItems: number;
 
@@ -90,12 +113,14 @@ export namespace MetricCollectionJobCreateResponse {
     createdAt: string;
 
     /**
-     * Error message if the job failed
+     * Why the job failed or, on a COMPLETED job with failedItems above 0, why those
+     * items failed
      */
     errorMessage: string | null;
 
     /**
-     * Number of failed items
+     * Number of items that could not be computed, for example because an artifact the
+     * metric reads (such as diarization) failed to generate
      */
     failedItems: number;
 
@@ -156,7 +181,8 @@ export namespace MetricCollectionJobListResponse {
     completedAt: string | null;
 
     /**
-     * Number of successfully completed items
+     * Number of items that finished without failing: a value was written, or the
+     * metric did not apply to the conversation
      */
     completedItems: number;
 
@@ -166,12 +192,14 @@ export namespace MetricCollectionJobListResponse {
     createdAt: string;
 
     /**
-     * Error message if the job failed
+     * Why the job failed or, on a COMPLETED job with failedItems above 0, why those
+     * items failed
      */
     errorMessage: string | null;
 
     /**
-     * Number of failed items
+     * Number of items that could not be computed, for example because an artifact the
+     * metric reads (such as diarization) failed to generate
      */
     failedItems: number;
 
@@ -224,6 +252,83 @@ export namespace MetricCollectionJobListResponse {
   }
 }
 
+export interface MetricCollectionJobCancelResponse {
+  /**
+   * A metric collection job that processes metrics for calls or chats
+   */
+  data: MetricCollectionJobCancelResponse.Data;
+}
+
+export namespace MetricCollectionJobCancelResponse {
+  /**
+   * A metric collection job that processes metrics for calls or chats
+   */
+  export interface Data {
+    /**
+     * Unique identifier of the metric collection job
+     */
+    id: string;
+
+    /**
+     * When the job completed
+     */
+    completedAt: string | null;
+
+    /**
+     * Number of items that finished without failing: a value was written, or the
+     * metric did not apply to the conversation
+     */
+    completedItems: number;
+
+    /**
+     * When the job was created
+     */
+    createdAt: string;
+
+    /**
+     * Why the job failed or, on a COMPLETED job with failedItems above 0, why those
+     * items failed
+     */
+    errorMessage: string | null;
+
+    /**
+     * Number of items that could not be computed, for example because an artifact the
+     * metric reads (such as diarization) failed to generate
+     */
+    failedItems: number;
+
+    /**
+     * IDs of the metric policies that triggered this job
+     */
+    policyIds: Array<string>;
+
+    /**
+     * When the job started processing
+     */
+    startedAt: string | null;
+
+    /**
+     * Current status of the job
+     */
+    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELED';
+
+    /**
+     * Total number of call-metric pairs to process
+     */
+    totalItems: number;
+
+    /**
+     * What triggered this job
+     */
+    triggeredBy: 'USER_MANUAL' | 'USER_API' | 'METRIC_POLICY' | 'SIMULATION';
+
+    /**
+     * When the job was last updated
+     */
+    updatedAt: string;
+  }
+}
+
 export interface MetricCollectionJobGetByIDResponse {
   /**
    * A metric collection job that processes metrics for calls or chats
@@ -247,7 +352,8 @@ export namespace MetricCollectionJobGetByIDResponse {
     completedAt: string | null;
 
     /**
-     * Number of successfully completed items
+     * Number of items that finished without failing: a value was written, or the
+     * metric did not apply to the conversation
      */
     completedItems: number;
 
@@ -257,12 +363,14 @@ export namespace MetricCollectionJobGetByIDResponse {
     createdAt: string;
 
     /**
-     * Error message if the job failed
+     * Why the job failed or, on a COMPLETED job with failedItems above 0, why those
+     * items failed
      */
     errorMessage: string | null;
 
     /**
-     * Number of failed items
+     * Number of items that could not be computed, for example because an artifact the
+     * metric reads (such as diarization) failed to generate
      */
     failedItems: number;
 
@@ -356,6 +464,7 @@ export declare namespace MetricCollectionJob {
   export {
     type MetricCollectionJobCreateResponse as MetricCollectionJobCreateResponse,
     type MetricCollectionJobListResponse as MetricCollectionJobListResponse,
+    type MetricCollectionJobCancelResponse as MetricCollectionJobCancelResponse,
     type MetricCollectionJobGetByIDResponse as MetricCollectionJobGetByIDResponse,
     type MetricCollectionJobCreateParams as MetricCollectionJobCreateParams,
     type MetricCollectionJobListParams as MetricCollectionJobListParams,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '5.11.0'; // x-release-please-version
+export const VERSION = '5.13.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

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

package/version.js

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

package/version.mjs

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