@aiqa/sdk 3.1.0-develop.1 → 3.1.0-develop.3

package/README.md

@@ -14,6 +14,7 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [Recording Management](#recording-management)
   - [Event Handling](#event-handling)
 - [Verification lifecycle](#verification-lifecycle)
+  - [Watched facts](#watched-facts)
 - [Types](#types)
   - [Application](#application)
   - [ApplicationVerificationSummary](#applicationverificationsummary)
@@ -331,6 +332,10 @@ verification result. The Promise resolves with an
 `pending_confirmation_matched`, `pending_confirmation_unmatched`)
 while you wait.
 
+A [watched fact](#watched-facts) is the exception: its Promise resolves right
+away with `verification_status: "awaiting_question"`, and the result arrives
+later on `FACT_VERIFIED`.
+
 A failed verification is not an error: an unmatched fact resolves with
 `is_valid_answer: false` and, where present, `verification_status: "unmatched"`.
 The Promise rejects only when the request itself fails — a dropped connection,
@@ -339,7 +344,7 @@ a timeout, a rejected payload.
 **Returns:**
 
 - `Promise<`[`AddFactResult`](#addfactresult)`>` — resolves once the fact
-  reaches a final `verification_status`.
+  reaches a final `verification_status`, or right away for a watched fact.
   - `warnings`: present only when part of this `addFact()` was not applied.
     See [`FactWarning`](#factwarning).
 
@@ -363,6 +368,18 @@ a timeout, a rejected payload.
     answer_format: { type: "STRING" }
     /** Optional (default: `false`). Use `true` when the fact was collected before the conversation started. It is stored, not verified. */
     prefilled?: boolean
+    /**
+     * Optional. Use `true` for a value you already know is correct, such as data
+     * from your own records. Unlike `prefilled`, it is about trusting the value, not
+     * when it was collected. It is stored and visible to whoever reviews the call,
+     * never verified, and left out of the verification summary counts.
+     */
+    reference?: boolean
+    /**
+     * Optional. Use "watch" to check the fact over the whole call instead of
+     * at one moment. See Watched facts below.
+     */
+    evaluation?: "watch"
     /**
      * Optional. Your own identifiers for this fact — a form field ID, a
      * section name, anything that lets your UI map the result back to the
@@ -520,7 +537,8 @@ Registers an event listener. Call `connect()` before `on()`.
 - `FACT_VERIFIED` - fires on **every** verification state change, progress and
   final result alike, for **every** fact in the conversation. Payload:
   [`FactVerifiedPayload`](#factverifiedpayload). Use it to show live progress;
-  `addFact()`'s Promise resolves only on the final result.
+  `addFact()`'s Promise resolves only on the final result, except for a
+  [watched fact](#watched-facts).
 
 ```typescript
 sdk.connect();
@@ -571,20 +589,80 @@ processing
                     matched | unmatched   ← final
 ```
 
+A [watched fact](#watched-facts) does not follow this sequence: it stays at
+`awaiting_question` until it goes straight to `matched` or `unmatched`.
+
 Rules:
 
 - **`addFact()` resolves only on a final state** (`matched`,
-  `unmatched`). Show progress from the `FACT_VERIFIED` event, show the final
-  result from the Promise.
+  `unmatched`), except for a [watched fact](#watched-facts). Show progress from the
+  `FACT_VERIFIED` event, show the final result from the Promise.
 - **Handle a `verification_status` you don't recognize as `processing`.**
 - **A fact sent with `prefilled: true` is never verified**, so it gets no
   `verification_status` and no `FACT_VERIFIED` event.
+- **A fact sent with `reference: true` is never verified either.** Use it for
+  a value you already know is correct, such as the plan name from your own
+  records. It is stored, visible to whoever reviews the call, and left out of
+  the verification summary counts. `addFact()` still resolves, with
+  `is_valid_answer: false` and no `verification_status`, and no `FACT_VERIFIED`
+  event is emitted for it.
 - **`pending_confirmation_*` is never final.** The answer can still change,
   so don't show it as a decision.
 - **A fact can be revised after `addFact()` has resolved.** If you keep its
   result on screen for the rest of the call, leave your `FACT_VERIFIED`
   listener attached and always show the latest state for that `factId`.
 
+### Watched facts
+
+Send `evaluation: "watch"` for a fact you want checked over the whole call
+rather than at one moment: from the moment you send it until it is `matched`
+or the call ends.
+
+```typescript
+const result = await sdk.addFact({
+  id: "my_fact",
+  question: "What you want checked in the call",
+  expected_answer: "the value it has to match",
+  answer_format: { type: FactAnswerFormatType.string },
+  evaluation: "watch",
+});
+```
+
+- **`question`:** describe, in plain words, what has to happen in the call for
+  this fact to be `matched`.
+- **`expected_answer`:** the value it has to match.
+- **Send `evaluation: "watch"` every time** you send the fact. Without it, the
+  fact goes through the regular
+  [Verification lifecycle](#verification-lifecycle): it is checked against one
+  moment of the call, and `addFact()` waits for the final result.
+- **Send the fact before that part of the call starts.** Only the part of the
+  call shortly before you send the fact is checked; anything earlier is
+  missed.
+- **`addFact()` resolves right away** with
+  `verification_status: "awaiting_question"` and `is_valid_answer: false`.
+  This is not a result: don't show it as one.
+- **The result arrives on `FACT_VERIFIED`** for that `factId`. A watched fact
+  goes from `awaiting_question` straight to `matched` or `unmatched`. Read
+  `payload.verification_status` and `payload.error`:
+  - `matched`: it happened in the call, matching `expected_answer` when you
+    sent one.
+  - `unmatched` with `error: "question-not-detected"`: it never happened.
+  - `unmatched` with `error: "answer-not-found"`: it happened, but could not
+    be confirmed against `expected_answer`.
+  - `unmatched` with no `error`: it happened, but with a different value. This
+    result is final.
+- **If it never happens**, the result is `unmatched` and arrives only when the
+  call ends. To get it as an event, keep the SDK connected and your
+  `FACT_VERIFIED` listener attached until then. Otherwise, call `getFacts()`
+  after the call: its `verification_status` shows `matched` or `unmatched`,
+  but not the reason (`error`) for an `unmatched` result.
+- **Sending a watched fact again** with the same `id` and `expected_answer`:
+  if it already matched, `addFact()` resolves with `matched`. Otherwise it
+  resolves with `awaiting_question` and the result arrives on `FACT_VERIFIED`
+  as before. With a different `expected_answer`, the earlier result no longer
+  applies: `addFact()` resolves with `awaiting_question` again, and the new
+  result arrives on `FACT_VERIFIED`.
+
 ## Types
 
 ### Application
@@ -678,7 +756,8 @@ type ApplicationFact = ApplicationFactInput & {
 ### AddFactResult
 
 Resolved value of `addFact()`. Only sent once the fact reaches its final
-state — see [Verification lifecycle](#verification-lifecycle).
+state, except for a [watched fact](#watched-facts) — see
+[Verification lifecycle](#verification-lifecycle).
 
 ```typescript
 interface AddFactResult {
@@ -707,8 +786,9 @@ interface AddFactResult {
   answer_match_score?: number;
 
   /**
-   * The final state: `matched` or `unmatched` whenever it is present.
-   * Fall back to `is_valid_answer` when it is missing.
+   * `matched` or `unmatched`: the final result. For a watched fact it is
+   * `awaiting_question`, which is not a result; the result arrives on
+   * `FACT_VERIFIED`. If this field is missing, use `is_valid_answer`.
    */
   verification_status?: VerificationStatus;
 
@@ -829,6 +909,18 @@ type ApplicationFactInput = {
   is_skipped?: boolean;
   /** Optional (default: `false`). Use `true` when the fact was collected before the conversation started. It is stored, not verified. */
   prefilled?: boolean;
+  /**
+   * Optional. Use `true` for a value you already know is correct, such as data
+   * from your own records. Unlike `prefilled`, it is about trusting the value, not
+   * when it was collected. It is stored and visible to whoever reviews the call,
+   * never verified, and left out of the verification summary counts.
+   */
+  reference?: boolean;
+  /**
+   * Optional. Use `"watch"` to check the fact over the whole call instead of
+   * at one moment. See [Watched facts](#watched-facts).
+   */
+  evaluation?: "watch";
   /**
    * Optional. Your own identifiers for this fact — a form field ID, a section
    * name, anything that lets your UI map the result back to the right place.

package/dist/browser/browser.d.ts

@@ -208,6 +208,18 @@ type ApplicationFactInput = {
     is_skipped?: boolean;
     /** Optional (default: `false`). Use `true` when the fact was collected before the conversation started. It is stored, not verified. */
     prefilled?: boolean;
+    /**
+     * Optional. Use `true` for a value you already know is correct, such as data
+     * from your own records. Unlike `prefilled`, it is about trusting the value, not
+     * when it was collected. It is stored and visible to whoever reviews the call,
+     * never verified, and left out of the verification summary counts.
+     */
+    reference?: boolean;
+    /**
+     * Optional. Use `"watch"` to check the fact over the whole call instead of
+     * at one moment. See "Watched facts" in the README.
+     */
+    evaluation?: "watch";
     /**
      * Your own identifiers for this fact — a form field ID, a section name,
      * anything that lets your UI map the result back to the right place.
@@ -225,7 +237,9 @@ type QuestionStatus = "searching" | "asked" | "not_asked";
  * `processing`.
  *
  *  - `processing`                     queued, or nothing to go on yet
- *  - `awaiting_question`              the advisor hasn't asked the question yet
+ *  - `awaiting_question`              the advisor hasn't asked the question yet;
+ *                                     for a watched fact, its state until the
+ *                                     result arrives
  *  - `awaiting_answer`                asked, the customer hasn't answered yet
  *  - `partial`                        partial evidence so far (e.g. "305" of "30521")
  *  - `pending_confirmation_matched`   a matching answer is held briefly in case
@@ -266,7 +280,7 @@ interface AddFactResult {
     answer_type?: string;
     agent_answer?: string;
     ai_answer?: string;
-    /** `false` for a fact that was never verified, such as a prefilled one. */
+    /** `false` for a fact that was never verified, such as a prefilled or reference one. Also `false` when `addFact()` resolves for a watched fact; its result arrives on `FACT_VERIFIED`. */
     is_valid_answer: boolean;
     question_asked?: boolean;
     /**
@@ -281,8 +295,9 @@ interface AddFactResult {
     answer_match_score?: number;
     metadata?: Record<string, string>;
     /**
-     * The final state: `matched` or `unmatched` whenever it is present. Fall
-     * back to `is_valid_answer` when it is missing.
+     * `matched` or `unmatched`: the final result. For a watched fact it is
+     * `awaiting_question`, which is not a result; the result arrives on
+     * `FACT_VERIFIED`. If this field is missing, use `is_valid_answer`.
      */
     verification_status?: VerificationStatus;
     /**
@@ -298,7 +313,8 @@ interface AddFactResult {
 /**
  * Payload of the `FACT_VERIFIED` event, which fires on every state change —
  * see `VerificationStatus`. Use it to show progress; `addFact()` resolves
- * only once a fact is done.
+ * only once a fact is done, except for a watched fact, whose result arrives only
+ * here.
  */
 interface FactVerifiedPayload {
     factId: string;

package/dist/browser/browser.js

@@ -3407,7 +3407,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "3.0.0-develop.2",
+  version: "3.1.0-develop.2",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",