@roarkanalytics/sdk 3.21.0 → 4.1.0

package/resources/customer-flow.d.ts

@@ -164,15 +164,32 @@ export declare class CustomerFlow extends APIResource {
  * flow's policy. Use it where one missed step makes the rest of the call
  * meaningless: an authentication menu, say, with `then: HANG_UP_INVALIDATE`.
  *
- * Any step may set `requiredForValidRun`, which marks a step the flow requires a
- * run to reach for its result to count. A run that ends without ever reaching it
- * is invalidated: it stays in the report, labelled with the step it never reached
- * and where it stopped, and is left out of the run score and the success-criteria
- * verdict. Put it on the step where the test itself begins, typically the first
- * one after an IVR or a login, so an agent that never gets past the menu does not
- * fail every check in a scenario it never started. A path may have one; a
- * branching flow may mark one step per branch, and reaching any of them makes the
- * call valid. A path that marks none behaves exactly as before.
+ * Any step may set `stage`, the named phase of the flow it belongs to: the IVR,
+ * the login, the scenario itself. Steps in one stage are drawn as a group in the
+ * editor, and the name is yours: the reports say it back to you. The stage does
+ * not have to exist first, it is created the first time a step names it, and a
+ * name already in the project is matched ignoring case.
+ *
+ * A stage with `required: true` is a gate. A run that ends without getting PAST it
+ * never reached what was being measured, so it stays in the report, labelled with
+ * the stage it never completed and the one it stopped in, and is left out of the
+ * run score and the success-criteria verdict: an agent that never clears the IVR
+ * does not fail every check in a scenario it never started. `required` belongs to
+ * the stage rather than to the step, so a read returns it on every step in that
+ * stage, and a write that sets it on any one of them marks the whole stage. A flow
+ * that requires no stage is scored exactly as before.
+ *
+ * A stage with `analyze: false` is not measured. Its turns are kept out of the
+ * core call metrics (talk time, speech pace, turn and response timings), which is
+ * what an IVR usually wants alongside `required: true`: the run has to get through
+ * the menu, but how the agent sounded reading it is not what is being tested.
+ * Coverage is being extended package by package, so the judged metrics (quality,
+ * compliance, repetition, escalation, tone) still read the whole call for now.
+ * Nothing is cut and nothing is re-timed, so a turn at 4:10 is still at 4:10 with
+ * an earlier stage excluded, and rate metrics divide by the part of the call that
+ * was measured rather than by the whole of it. Defaults to true, belongs to the
+ * stage the same way `required` does, and turning it off on any one step turns it
+ * off for the stage.
  */
 export type FlowStep = FlowStep.UnionMember0 | FlowStep.UnionMember1 | FlowStep.UnionMember2 | FlowStep.UnionMember3 | FlowStep.UnionMember4 | FlowStep.UnionMember5 | FlowStep.UnionMember6 | FlowStep.UnionMember7 | FlowStep.UnionMember8 | FlowStep.UnionMember9;
 export declare namespace FlowStep {
@@ -183,7 +200,7 @@ export declare namespace FlowStep {
         nodeId?: string;
         offScriptPolicy?: UnionMember0.OffScriptPolicy | null;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember0.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
     namespace UnionMember0 {
@@ -194,6 +211,11 @@ export declare namespace FlowStep {
             sayLine?: string | null;
             waitSeconds?: number | null;
         }
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
     }
     interface UnionMember1 {
         type: 'CUSTOMER_TURN';
@@ -201,71 +223,127 @@ export declare namespace FlowStep {
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember1.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember1 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember2 {
         type: 'CUSTOMER_FIRST_MESSAGE';
         content?: string | null;
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember2.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember2 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember3 {
         type: 'CUSTOMER_VERBATIM_TURN';
         content?: string | null;
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember3.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember3 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember4 {
         type: 'CUSTOMER_SILENCE';
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
         silenceDurationSeconds?: number | null;
+        stage?: UnionMember4.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember4 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember5 {
         type: 'CUSTOMER_DTMF';
         dtmfDigits?: string | null;
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember5.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember5 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember6 {
         type: 'AGENT_DTMF';
         dtmfDigits?: string | null;
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember6.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember6 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember7 {
         type: 'VOICEMAIL';
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember7.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember7 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember8 {
         type: 'CUSTOMER_HANDOFF';
         handoffPersonaId?: string | null;
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember8.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember8 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
     interface UnionMember9 {
         type: 'SCENARIO_LINK';
         linkedCustomerFlowId?: string | null;
@@ -273,9 +351,16 @@ export declare namespace FlowStep {
         mergeIntoNodeIds?: Array<string>;
         nodeId?: string;
         ref?: string;
-        requiredForValidRun?: boolean;
+        stage?: UnionMember9.Stage | null;
         steps?: Array<CustomerFlowAPI.FlowStep>;
     }
+    namespace UnionMember9 {
+        interface Stage {
+            name: string;
+            analyze?: boolean;
+            required?: boolean;
+        }
+    }
 }
 export interface CustomerFlowCreateResponse {
     /**