@aiqa/sdk 2.1.0-develop.3 → 2.1.0-develop.5

package/dist/browser/browser.d.ts

@@ -1,16 +1,72 @@
 import { Socket } from 'socket.io-client';
 
+/**
+ * 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`.
+ *
+ * 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";
+/**
+ * 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;
+    /** The facts in `count_errors` that you sent with `critical: true`. */
+    count_critical_errors: number;
+    /**
+     * 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 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;
+    /** The facts in `count_not_asked` that you sent with `critical: true`. */
+    count_critical_not_asked: number;
+    /**
+     * 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 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 = {
     application_id: string;
     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;
+    /**
+     * 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;
 };
 declare enum Methods {
     AUTHENTICATE = "AUTHENTICATE",
     GET_FACTS = "GET_FACTS",
+    GET_APPLICATION = "GET_APPLICATION",
     START_RECORDING = "START_RECORDING",
     STOP_RECORDING = "STOP_RECORDING",
     IS_RECORDING = "IS_RECORDING",
@@ -41,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: {
@@ -86,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;
@@ -99,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 & {
@@ -138,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;
@@ -149,48 +210,33 @@ 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.
-     * Populated by the verification queue from partial-match heuristics
-     * (numeric-prefix ratio, matched-components ratio). Undefined when no
-     * partial signal exists or for terminal results before this rolls out.
+     * 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 during the rollout window for
-     * backwards compatibility with older backends.
+     * The final state: `matched` or `unmatched` whenever it is present. Fall
+     * back to `is_valid_answer` when it is missing.
      */
     verification_status?: VerificationStatus;
     /**
-     * Per-fact partial-match breakdown carried through from the
-     * verification queue's component-wise comparators. For numeric-prefix
-     * facts these are `["prefix"]` / `["suffix"]`; future work will
-     * generalise to addresses, names, dates, etc.
+     * Component labels describing which parts of the expected answer
+     * matched. Currently `["prefix"]` / `["suffix"]` for numeric facts;
+     * treat the set as open-ended.
      */
     matched_components?: string[];
     missing_components?: string[];
 }
 /**
- * Payload of the `FACT_VERIFIED` broadcast event.
- *
- * Fires on EVERY state transition the verification queue 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;
@@ -200,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;
 }
@@ -213,47 +254,26 @@ type FlagFactResult = {
     success: boolean;
 };
 /**
- * Coarse dialog-act label produced by the backend's `UtteranceEnricher`.
- * Advisory only — do not gate production behaviour on this value; the
- * enricher emits its best-effort categorical guess plus a separate
- * `dialog_act_confidence` band.
- *
- * Mirrors `DialogAct` in
- * `libs/types/src/utterance-enrichment.ts` on the backend.
+ * 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 and conflating them is a documented drift hazard on
- * the backend.
- *
- * Mirrors `DialogActConfidence` in
- * `libs/types/src/utterance-enrichment.ts` on the backend.
+ * 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 — matches `TranscriptionUtteranceDto` on the
- * gateway (`apps/realtime-verification/src/socket/realtimeVerification.gateway.output.dto.ts`)
- * and the `Utterance` interface in `libs/types/src/common.ts` field for
- * field. Sent over the wire by the `TRANSCRIPTION_UPDATED` broadcast.
+ * An utterance from the `TRANSCRIPTION_UPDATED` event.
  *
- * The 7 enricher classification fields are all optional because
- * pre-cutover utterances (persisted before backend PR #234) 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;
-    /**
-     * NOT YET IMPLEMENTED — currently hardcoded to 0 at write sites on
-     * the backend. 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;
@@ -269,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;
@@ -328,4 +345,4 @@ declare class AiQaSdk implements IAiqaSdk {
     private isManagerEvent;
 }
 
-export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, type DialogAct, type DialogActConfidence, FactAnswerFormatType, type FactVerifiedPayload, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type TranscriptionUpdate, type UpdateConversationInput, type UpdateConversationResult, type Utterance, type VerificationStatus };
+export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, type ApplicationVerificationStatus, type ApplicationVerificationSummary, ConversationLanguage, type DialogAct, type DialogActConfidence, FactAnswerFormatType, type FactVerifiedPayload, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type TranscriptionUpdate, type UpdateConversationInput, type UpdateConversationResult, type Utterance, type VerificationStatus };

package/dist/browser/browser.js

@@ -3341,6 +3341,7 @@ Object.assign(lookup2, {
 var Methods = /* @__PURE__ */ ((Methods2) => {
   Methods2["AUTHENTICATE"] = "AUTHENTICATE";
   Methods2["GET_FACTS"] = "GET_FACTS";
+  Methods2["GET_APPLICATION"] = "GET_APPLICATION";
   Methods2["START_RECORDING"] = "START_RECORDING";
   Methods2["STOP_RECORDING"] = "STOP_RECORDING";
   Methods2["IS_RECORDING"] = "IS_RECORDING";
@@ -3397,7 +3398,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "2.1.0-develop.2",
+  version: "2.1.0-develop.4",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3481,6 +3482,9 @@ var DEFAULT_URL = "ws://localhost:3025/ws";
 var DEFAULT_TIMEOUT_MS = 6e4;
 var RUNTIME = typeof window !== "undefined" && typeof window.document !== "undefined" ? "browser" : "node";
 var USER_AGENT = RUNTIME === "browser" ? typeof navigator !== "undefined" ? navigator.userAgent : "browser/unknown" : typeof process !== "undefined" ? `node ${process.version} ${process.platform}` : "node/unknown";
+function isRequestTimeout(error, method) {
+  return error instanceof Error && error.message === `Request timed out for ${method}`;
+}
 function isThenable(value2) {
   return value2 !== null && typeof value2 === "object" && typeof value2.then === "function";
 }
@@ -3688,6 +3692,18 @@ var AiQaSdk = class {
     });
   }
   async getApplication() {
+    try {
+      const result = await this.sendMessage("GET_APPLICATION" /* GET_APPLICATION */);
+      const application = result && result.data !== void 0 ? result.data : result;
+      if (application && application.application_id !== void 0) {
+        return application;
+      }
+      throw new Error("GET_APPLICATION returned no application");
+    } catch (error) {
+      if (!isRequestTimeout(error, "GET_APPLICATION" /* GET_APPLICATION */)) {
+        throw error;
+      }
+    }
     if (this.cachedApplication) {
       return this.cachedApplication;
     }