@aiqa/sdk 2.1.0 → 2.1.1

package/dist/browser/browser.d.ts

@@ -1,39 +1,50 @@
 import { Socket } from 'socket.io-client';
 
 /**
- * Rolled-up verdict over the *answers*: `critical_errors` if any critical fact
- * failed, otherwise `errors` if any fact failed, otherwise `no_errors`.
- * Questions that were never asked do not raise it, so a call where everything
- * was skipped and nothing was wrong reads `no_errors`.
+ * Overall result for the call: `critical_errors` if a fact you sent with
+ * `critical: true` failed, `errors` if any other fact failed, else
+ * `no_errors`.
  *
- * Distinct from the per-fact `VerificationStatus` — this one describes the
- * call, not an answer.
+ * Only answers count. A question that was never asked never raises it, so a
+ * call where nothing was asked reads `no_errors`.
+ *
+ * Not the same as `VerificationStatus`, which describes a single fact.
  */
 type ApplicationVerificationStatus = "no_errors" | "errors" | "critical_errors";
-/** Verification tally for the application at the moment it was requested. */
+/**
+ * How the facts on one application are counted up. None of these is a count of
+ * facts that passed, and they overlap — to show a pass count, count the facts
+ * whose `verification_status` is `matched` in `getFacts()`.
+ */
 type ApplicationVerificationSummary = {
     status: ApplicationVerificationStatus;
     /** Facts whose answer did not match the expected one. */
     count_errors: number;
-    /** Subset of `count_errors` whose question is marked critical. */
+    /** The facts in `count_errors` that you sent with `critical: true`. */
     count_critical_errors: number;
     /**
-     * Facts on the application, full stop — verdict or not. Not a pass count and
-     * not a count of what has been evaluated: `count_not_asked` and
-     * `count_pending` are subsets of it, not separate buckets.
+     * Every fact on the application, checked or not. The other counters are
+     * subsets of it and can overlap each other, so no subtraction from
+     * `count_total` yields a pass count.
      */
     count_total: number;
-    /** Facts with a verdict of never-asked. Excludes the still-pending ones. */
+    /**
+     * Facts whose question was never asked. Excludes the still-pending ones, but
+     * overlaps `count_errors`: a fact never asked that came back wrong is in both.
+     */
     count_not_asked: number;
-    /** Subset of `count_not_asked` whose question is marked critical. */
+    /** The facts in `count_not_asked` that you sent with `critical: true`. */
     count_critical_not_asked: number;
     /**
-     * Facts still awaiting a verdict — added, but not resolved yet. During a live
-     * call most facts sit here, and they drain into the other counters as the
-     * call proceeds.
+     * Facts added but not resolved yet. During a live call most facts sit here
+     * and move into the other counters as their results arrive.
      */
     count_pending: number;
-    /** Facts the conduct review flagged; a matched fact can still be suspicious. */
+    /**
+     * Facts flagged as suspicious when the call is reviewed — for instance the
+     * agent leading the customer to the expected answer. Independent of the
+     * answer: a matched fact can be flagged. Reads 0 while the call is running.
+     */
     count_suspicious: number;
 };
 type Application = {
@@ -41,12 +52,14 @@ type Application = {
     client_name: string;
     client_phone_number: string;
     agent_id: string;
+    /** Comes back empty. Set an agent name with `updateConversation()`. */
     agent_first_name: string;
+    /** Comes back empty. Set an agent name with `updateConversation()`. */
     agent_last_name: string;
     /**
-     * Absent only when the server predates this field, in which case
-     * `getApplication()` served its cached authentication snapshot. Treat the
-     * absence as "no live data", never as a zeroed summary.
+     * How the call is going so far. When it is missing there is no summary —
+     * which is not the same as all zeros — and the fields above may then be the
+     * ones from authentication, without an `updateConversation()` you made since.
      */
     verification?: ApplicationVerificationSummary;
 };
@@ -84,7 +97,7 @@ type UpdateConversationInput = {
     advisorName?: string;
     agentGroups?: string[];
 };
-/** Echo of the patched subset — only the fields you sent come back. */
+/** Only the fields you sent come back in `conversation`. */
 type UpdateConversationResult = {
     success: boolean;
     conversation: {
@@ -129,11 +142,10 @@ type ApplicationFactAnswerFormat = {
 type ApplicationFactInput = {
     id: string;
     /**
-     * Stable identifier for the underlying question, shared across applications and
-     * conversations. When provided it is used to look up (or create) the matching
-     * question row in the database instead of `id`. Keep this consistent across
-     * calls — accuracy improvements and remaps configured in the management
-     * dashboard are scoped per `questionId`.
+     * Stable identifier for the underlying question, shared across applications
+     * and conversations. When provided it identifies the question instead of
+     * `id`. Keep it consistent across calls: whatever AIQA has tuned for a
+     * question is attached to this identity.
      */
     questionId?: string;
     question: string;
@@ -142,35 +154,41 @@ type ApplicationFactInput = {
     category_id?: string;
     category_name?: string;
     language?: string;
+    /**
+     * Mark the question critical: its failures land in `count_critical_errors`,
+     * and one of them sets the call's `status` to `critical_errors`.
+     */
     critical?: boolean;
     is_skipped?: boolean;
+    /**
+     * 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.
+     * `getFacts()` returns it unchanged — `{}` for a fact you added without
+     * one — and it plays no part in verification.
+     *
+     * Keys and values must all be strings, and each value is limited to 1024
+     * characters. A payload that breaks either rule is rejected.
+     */
     metadata?: Record<string, string>;
 };
 type QuestionStatus = "searching" | "asked" | "not_asked";
 /**
- * Per-fact verification state.
+ * Per-fact verification state. Handle any value you don't recognize as
+ * `processing`.
  *
- * Extended from the original three-state shape to carry progress signals
- * the backend already detects but previously could not express. Consumers
- * that switch on this value MUST treat unknown strings as "processing"
- * (default fall-through) so older SDK builds keep working after the
- * backend starts emitting the additive states.
- *
- * Semantics:
- *  - `processing`                     generic, just queued or transcription not ready
- *  - `awaiting_question`              agent hasn't asked the question yet
- *  - `awaiting_answer`                question asked, customer hasn't answered yet
- *  - `partial`                        partial evidence; backend still working on it
- *  - `pending_confirmation_matched`   backend has a matching answer but is
- *                                     holding a settling window for mid-answer
- *                                     clarifications (e.g. spellings, "I mean…");
- *                                     resolves to `matched`/`unmatched`
- *  - `pending_confirmation_unmatched` same as above but the held verdict is
- *                                     `unmatched`; UI can show "we heard X but it
- *                                     doesn't match, waiting to confirm" instead
- *                                     of a hard red verdict
- *  - `matched`                        terminal: answer matched expected
- *  - `unmatched`                      terminal: budget exhausted with no match
+ *  - `processing`                     queued, or nothing to go on yet
+ *  - `awaiting_question`              the agent hasn't asked the question yet
+ *  - `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
+ *                                     the customer corrects it mid-answer
+ *                                     (spellings, "I mean…"); resolves to
+ *                                     `matched`/`unmatched`
+ *  - `pending_confirmation_unmatched` same, with an unmatched answer held; show
+ *                                     "we heard X but it doesn't match, waiting
+ *                                     to confirm" rather than a hard result
+ *  - `matched`                        final: the answer matched
+ *  - `unmatched`                      final: the answer did not match
  */
 type VerificationStatus = "processing" | "awaiting_question" | "awaiting_answer" | "partial" | "pending_confirmation_matched" | "pending_confirmation_unmatched" | "matched" | "unmatched";
 type ApplicationFact = ApplicationFactInput & {
@@ -181,7 +199,7 @@ type ApplicationFact = ApplicationFactInput & {
     flagged: boolean;
 };
 interface AddFactResult {
-    /** Conversation the fact was attached to. Useful for cross-fact correlation in agent UIs. */
+    /** Conversation the fact was attached to. */
     conversation_id?: string;
     /** Echo of the original question text from the fact input. */
     question?: string;
@@ -192,24 +210,19 @@ interface AddFactResult {
     is_valid_answer: boolean;
     question_asked?: boolean;
     /**
-     * 0–1 (or 0–100 — scale matches the configured similarity method).
-     * Similarity between the agent's utterance and the expected question.
-     * Renamed from `match_score` to disambiguate from the answer-side score.
+     * How closely the agent's utterance matched the expected question, on a 0–1
+     * or a 0–100 scale. Higher is closer.
      */
     question_match_score?: number;
     /**
-     * 0–1 score derived from how well the customer's answer matched expected.
-     * Derived from partial-match heuristics (numeric-prefix ratio,
-     * matched-components ratio). Undefined when no partial signal exists,
-     * or on older server versions.
+     * 0–1 score for how closely the customer's answer matched the expected one.
+     * Undefined when there is no partial signal to score.
      */
     answer_match_score?: number;
     metadata?: Record<string, string>;
     /**
-     * Top-level state at terminal resolution. Always one of `matched`
-     * or `unmatched` because the `addFact()` Promise only
-     * resolves on terminals. Optional for compatibility with older
-     * server versions.
+     * The final state: `matched` or `unmatched` whenever it is present. Fall
+     * back to `is_valid_answer` when it is missing.
      */
     verification_status?: VerificationStatus;
     /**
@@ -221,18 +234,9 @@ interface AddFactResult {
     missing_components?: string[];
 }
 /**
- * Payload of the `FACT_VERIFIED` broadcast event.
- *
- * Fires on EVERY state transition the server produces —
- * non-terminal (`partial`, `awaiting_question`, `awaiting_answer`,
- * `pending_confirmation_matched`, `pending_confirmation_unmatched`,
- * `processing`) AND terminal (`matched`, `unmatched`).
- *
- * Subscribe with:
- *   sdk.on("FACT_VERIFIED", (payload: FactVerifiedPayload) => {...});
- *
- * `addFact()`'s Promise resolves only on terminals; this event stream
- * is the channel for rendering live progress in the agent UI.
+ * 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.
  */
 interface FactVerifiedPayload {
     factId: string;
@@ -242,12 +246,7 @@ interface FactVerifiedPayload {
     answer_match_score?: number;
     matched_components?: string[];
     missing_components?: string[];
-    /**
-     * Inner data payload. Shape matches `AddFactResult` (minus the
-     * top-level envelope fields) so consumers can reuse the same
-     * rendering code for the terminal addFact() resolution and the
-     * broadcast event.
-     */
+    /** Inner payload, shaped like `AddFactResult`. */
     data?: AddFactResult;
     error?: string;
 }
@@ -255,38 +254,26 @@ type FlagFactResult = {
     success: boolean;
 };
 /**
- * Coarse dialog-act label classified server-side. Advisory only — do
- * not gate production behaviour on this value; it is a best-effort
- * categorical guess, paired with a separate `dialog_act_confidence`
- * band.
+ * What the utterance appears to be doing in the conversation. A best-effort
+ * guess: display it if it helps, but do not gate behaviour on it. Its
+ * confidence band is `dialog_act_confidence`.
  */
 type DialogAct = "question" | "answer" | "acknowledgement" | "filler" | "other";
 /**
- * Categorical confidence band for `dialog_act` ONLY. Named distinctly
- * from the numeric STT `confidence` field on the same utterance — the
- * two are unrelated, so do not compare or conflate them.
+ * Confidence band for `dialog_act` only. Unrelated to the numeric
+ * `confidence` field on the same utterance — do not compare the two.
  */
 type DialogActConfidence = "high" | "medium" | "low";
 /**
- * Persisted utterance shape, sent over the wire by the
- * `TRANSCRIPTION_UPDATED` broadcast.
+ * An utterance from the `TRANSCRIPTION_UPDATED` event.
  *
- * The 7 classification fields are all optional because utterances
- * persisted by older server versions lack them.
- * Treat any missing or nullish value as "unknown" — NOT as a deliberate
- * negative signal. `is_ivr_filler_candidate === false` in particular
- * does NOT round-trip through `undefined`, so consumer logic that wants
- * "definitely not a filler" must check `=== false` after confirming the
- * field is present.
+ * A missing optional field means "unknown", not "no".
  */
 type Utterance = {
-    /** UUIDv7 — chronologically sortable. Use `id` (NOT `order`) for sorting. */
+    /** Sort utterances by this: ids sort in chronological order. */
     id: string;
     call_id: number;
-    /**
-     * Reserved — currently always 0. Do not use for sorting; sort by `id`
-     * (UUIDv7) instead.
-     */
+    /** Always 0. Sort by `id`, not this. */
     order: number;
     is_agent: boolean | null;
     speaker: number;
@@ -302,10 +289,7 @@ type Utterance = {
     spoken_digits_normalized?: string | null;
     vendor?: string | null;
 };
-/**
- * Payload of the `TRANSCRIPTION_UPDATED` broadcast event. Mirrors
- * `TranscriptionUpdateResponseDto` on the gateway.
- */
+/** Payload of the `TRANSCRIPTION_UPDATED` broadcast event. */
 type TranscriptionUpdate = {
     policyNumber: string;
     conversationId: string;

package/dist/browser/browser.js

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