@aiqa/sdk 2.1.0-develop.2 → 2.1.0-develop.4

package/README.md

@@ -10,20 +10,28 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
 - [API Reference](#api-reference)
   - [Connection Management](#connection-management)
   - [Application Management](#application-management)
-  - [Recording Management](#recording-management)
   - [Fact Management](#fact-management)
+  - [Recording Management](#recording-management)
   - [Event Handling](#event-handling)
 - [Verification lifecycle](#verification-lifecycle)
 - [Types](#types)
+  - [Application](#application)
+  - [ApplicationVerificationSummary](#applicationverificationsummary)
+  - [ApplicationVerificationStatus](#applicationverificationstatus)
+  - [ApplicationFact](#applicationfact)
+  - [ApplicationFactInput](#applicationfactinput)
   - [AddFactResult](#addfactresult)
   - [VerificationStatus](#verificationstatus)
   - [FactVerifiedPayload](#factverifiedpayload)
+  - [FactUpdateEvent](#factupdateevent)
   - [FlagFactResult](#flagfactresult)
+  - [ConversationLanguage](#conversationlanguage)
   - [UpdateConversationInput](#updateconversationinput)
   - [UpdateConversationResult](#updateconversationresult)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
-- [Semantic Versioning](#semantic-versioning)
+- [Version Requirements](#version-requirements)
+- [License](#license)
 
 ## Installation
 
@@ -65,6 +73,14 @@ sdk.on("error", (error) => {
 new AiQaSdk(applicationId, applicationSecret, url?)
 ```
 
+**Parameters:**
+
+- `applicationId: string` - your application id
+- `applicationSecret: string` - your application secret
+- `url?: string` - the AIQA service endpoint. Pass it explicitly: the
+  built-in fallback is a local development address, so omitting it in a
+  deployed app connects to `localhost` instead of the service.
+
 ## API Reference
 
 ### Connection Management
@@ -73,6 +89,11 @@ new AiQaSdk(applicationId, applicationSecret, url?)
 
 Establishes a WebSocket connection to the AIQA service.
 
+**Returns:**
+
+- `void` — connection progress is reported through the `connect`,
+  `authenticated`, and `error` events.
+
 ```typescript
 sdk.connect();
 ```
@@ -81,6 +102,10 @@ sdk.connect();
 
 Closes the WebSocket connection.
 
+**Returns:**
+
+- `void`
+
 ```typescript
 sdk.disconnect();
 ```
@@ -89,20 +114,70 @@ sdk.disconnect();
 
 #### `getApplication()`
 
-Returns the cached application loaded during authentication.
-If authentication hasn't completed yet, this throws. Use the `authenticated` event to know when it's ready.
+Returns the application, its conversation participants, and the current
+verification tally for the call.
+
+**Returns:**
+
+- `Promise<`[`Application`](#application)`>`
+
+  ```typescript
+  {
+    application_id: string;
+    client_name: string;
+    client_phone_number: string;
+    agent_id: string;
+    agent_first_name: string;
+    agent_last_name: string;
+    verification?: ApplicationVerificationSummary;
+  }
+  ```
+
+  The identity fields are read fresh, so an `updateConversation()` earlier in
+  the call is reflected. It **rejects** if authentication hasn't completed yet
+  — wait for the `authenticated` event before calling it — and it rejects on a
+  failed request rather than quietly handing back older values.
 
 ```typescript
 const application = await sdk.getApplication();
+
+console.log(application.application_id, application.client_name);
+
+if (application.verification) {
+  const v = application.verification;
+  console.log(v.status, `${v.count_errors} errors`);
+}
 ```
 
+##### Reading `verification` during a live call
+
+The summary is computed when you ask for it, so it moves as the call
+progresses. Two things to know before you render it:
+
+- **Most facts start in `count_pending`.** A fact is pending from the moment
+  you add it until the server reaches a verdict on it, so early in a call
+  nearly everything sits there and drains into the other counters as the call
+  proceeds. `count_not_asked` means the question was genuinely never asked; it
+  does not absorb the ones still in flight.
+- **`count_total` is the total, not a pass count.** It is every fact on the
+  application, verdict or not, so `count_total - count_errors` is _not_ the
+  number that passed — the pending ones are in there too.
+- **`status` only reflects answers.** A skipped question never raises it, so a
+  call where nothing was asked and nothing was wrong reads `no_errors`. Read
+  the counters, not just the status, if "incomplete" matters to you.
+- **`verification` is absent only against a server that predates it**, in which
+  case this method returns the identity fields it cached at authentication.
+  Every other failure — a rejected request, a dropped socket, a server-side
+  error — rejects instead, so an absent `verification` always means "this
+  server has no summary to give", never "something went wrong just now".
+
 #### `setConversationProduct(product)`
 
 Sets the conversation product using a valid product code.
 
 **Parameters:**
 
-- `product: string` - product code (from the `service.code` catalog)
+- `product: string` - product code; the accepted values for your account are listed in the AIQA dashboard
 
 **Returns:**
 
@@ -187,6 +262,11 @@ fact resolves with `is_valid_answer: false` and (where the backend
 provides it) `verification_status: "unmatched"`.
 Reject paths are reserved for transport / protocol errors.
 
+**Returns:**
+
+- `Promise<`[`AddFactResult`](#addfactresult)`>` — resolves once the fact
+  reaches a terminal `verification_status`.
+
 **Parameters:**
 
 - `fact: ApplicationFactInput`
@@ -269,13 +349,19 @@ otherwise `id`. So:
   send a stable `questionId`. Otherwise each call looks like a new question and
   you lose the features above.
 - Once you've picked an identity for a question, don't change it. If you must
-  rename, coordinate with the team owning the dashboard so remaps and
-  historical signals can be migrated.
+  rename, contact AIQA support first so remaps and historical signals can
+  be migrated.
 
 #### `getFacts()`
 
 Retrieves all facts for the application (Promise-based). Each fact includes a `metadata` field containing whatever was passed to `addFact()`. Facts added without `metadata` return `{}`.
 
+**Returns:**
+
+- `Promise<`[`ApplicationFact[]`](#applicationfact)`>` — every fact of the
+  application, each with its current `question_status` /
+  `verification_status`.
+
 ```typescript
 const facts = await sdk.getFacts();
 facts.forEach((fact) => {
@@ -304,7 +390,11 @@ console.log(result.success); // true
 
 #### `startRecording()`
 
-Starts audio recording (Promise-based).
+Starts audio recording.
+
+**Returns:**
+
+- `Promise<boolean>` — `true` once the server has started recording.
 
 ```typescript
 const started = await sdk.startRecording();
@@ -312,7 +402,11 @@ const started = await sdk.startRecording();
 
 #### `stopRecording()`
 
-Stops audio recording (Promise-based).
+Stops audio recording.
+
+**Returns:**
+
+- `Promise<boolean>` — `true` once the server has stopped recording.
 
 ```typescript
 const stopped = await sdk.stopRecording();
@@ -320,7 +414,11 @@ const stopped = await sdk.stopRecording();
 
 #### `isRecordingNow()`
 
-Checks if recording is currently active (Promise-based).
+Checks if recording is currently active.
+
+**Returns:**
+
+- `Promise<boolean>` — `true` while a recording is in progress.
 
 ```typescript
 const isRecording = await sdk.isRecordingNow();
@@ -332,6 +430,10 @@ const isRecording = await sdk.isRecordingNow();
 
 Registers an event listener. Call `connect()` before `on()`.
 
+**Returns:**
+
+- `void`
+
 **Available Events:**
 
 - `connect` - Socket.IO connection established
@@ -397,13 +499,18 @@ Rules for consumers:
   The enum is additive — older SDK builds must fall through gracefully
   when the backend ships a new state.
 - **`pending_confirmation_*` is never terminal.** The wire-visible
-  latency penalty is bounded by `settling_window_ms` on the server
-  (default 2000 ms). The held verdict can flip — that's the whole
-  point — so don't treat it as a commit.
+  latency penalty is bounded by a short server-side settling window
+  (currently around 2s; not part of the SDK contract). The held verdict
+  can flip — that's the whole point — so don't treat it as a commit.
 
 #### `off(eventName, callback?)`
 
-Removes an event listener.
+Removes an event listener. Omit `callback` to remove every listener
+registered for the event.
+
+**Returns:**
+
+- `void`
 
 ```typescript
 sdk.off("connect");
@@ -413,6 +520,10 @@ sdk.off("connect");
 
 ### Application
 
+Returned by [`getApplication()`](#getapplication): the application, the two
+participants of the conversation, and the verification tally at the moment of
+the call.
+
 ```typescript
 type Application = {
   application_id: string;
@@ -421,9 +532,61 @@ type Application = {
   agent_id: string;
   agent_first_name: string;
   agent_last_name: string;
+  // Absent on servers that predate this field.
+  verification?: ApplicationVerificationSummary;
 };
 ```
 
+### ApplicationVerificationSummary
+
+```typescript
+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.
+  count_critical_errors: number;
+
+  // Every fact on the application, verdict or not. Neither a pass count nor a
+  // count of what has been evaluated: the two counters below are subsets of
+  // it, not separate buckets.
+  count_total: number;
+
+  // Facts whose question was genuinely never asked. Does not include the ones
+  // still awaiting a verdict — those are count_pending.
+  count_not_asked: number;
+
+  // Subset of count_not_asked whose question is marked critical.
+  count_critical_not_asked: number;
+
+  // Facts added but not yet resolved. Most of the call's facts sit here early
+  // on and drain as verdicts land.
+  count_pending: number;
+
+  // Facts the conduct review flagged. Independent of the answer verdict — a
+  // matched fact can still be suspicious.
+  count_suspicious: number;
+};
+```
+
+### ApplicationVerificationStatus
+
+Rolled-up verdict over the answers, for the whole application. Distinct from
+[`VerificationStatus`](#verificationstatus), which describes a single fact.
+Questions that were never asked do not raise it.
+
+```typescript
+type ApplicationVerificationStatus =
+  // At least one critical fact failed.
+  | "critical_errors"
+  // At least one fact failed, none of them critical.
+  | "errors"
+  // No fact has failed — which is not the same as "everything was asked".
+  | "no_errors";
+```
+
 ### ApplicationFact
 
 Returned by `getFacts()`. Extends `ApplicationFactInput` and adds server-side fields.
@@ -465,24 +628,23 @@ interface AddFactResult {
 
   /**
    * 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).
+   * Derived from partial-match heuristics (numeric-prefix ratio,
+   * matched-components ratio).
    */
   answer_match_score?: number;
 
   /**
    * 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.
+   * resolves on terminals. Optional for compatibility with older
+   * server versions.
    */
   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[];
@@ -667,36 +829,6 @@ type FactUpdateEvent = {
 };
 ```
 
-## Semantic Versioning
-
-Version bumps are automated with semantic commits and `semantic-release` in Bitbucket Pipelines:
-
-- `master` creates stable releases.
-- `develop` creates prereleases on the `develop` channel (for example `1.2.3-develop.1`).
-
-### Commit types and version bump
-
-- `fix: ...` -> patch bump (`0.0.6` -> `0.0.7`)
-- `feat: ...` -> minor bump (`0.0.6` -> `0.1.0`)
-- `feat!: ...` or commit body with `BREAKING CHANGE:` -> major bump (`0.0.6` -> `1.0.0`)
-- `chore: ...`
-- Other commit types (for example `docs:`, `chore:`) do not trigger a release by default.
-
-### Examples
-
-```text
-fix: handle socket timeout error
-feat: add isRecordingNow helper
-feat!: change addFact response contract
-```
-
-### Pipeline requirements
-
-Set these repository variables so the release step can push tags/commits and publish to npm:
-
-- `BB_TOKEN_BASIC_AUTH` with value `user:token`
-- `NPM_TOKEN` with publish access to `@aiqa/sdk`
-
 ## Examples
 
 ### Complete Example: Recording Session

package/dist/browser/browser.d.ts

@@ -1,5 +1,41 @@
 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`.
+ *
+ * Distinct from the per-fact `VerificationStatus` — this one describes the
+ * call, not an answer.
+ */
+type ApplicationVerificationStatus = "no_errors" | "errors" | "critical_errors";
+/** Verification tally for the application at the moment it was requested. */
+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. */
+    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.
+     */
+    count_total: number;
+    /** Facts with a verdict of never-asked. Excludes the still-pending ones. */
+    count_not_asked: number;
+    /** Subset of `count_not_asked` whose question is marked critical. */
+    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.
+     */
+    count_pending: number;
+    /** Facts the conduct review flagged; a matched fact can still be suspicious. */
+    count_suspicious: number;
+};
 type Application = {
     application_id: string;
     client_name: string;
@@ -7,10 +43,17 @@ type Application = {
     agent_id: string;
     agent_first_name: string;
     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.
+     */
+    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",
@@ -156,24 +199,23 @@ interface AddFactResult {
     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.
+     * Derived from partial-match heuristics (numeric-prefix ratio,
+     * matched-components ratio). Undefined when no partial signal exists,
+     * or on older server versions.
      */
     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.
+     * resolves on terminals. Optional for compatibility with older
+     * server versions.
      */
     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[];
@@ -181,7 +223,7 @@ interface AddFactResult {
 /**
  * Payload of the `FACT_VERIFIED` broadcast event.
  *
- * Fires on EVERY state transition the verification queue produces —
+ * 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`).
@@ -213,33 +255,24 @@ 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.
+ * 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.
  */
 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.
+ * two are unrelated, so do not compare or conflate them.
  */
 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.
+ * Persisted utterance shape, sent over the wire by the
+ * `TRANSCRIPTION_UPDATED` broadcast.
  *
- * The 7 enricher classification fields are all optional because
- * pre-cutover utterances (persisted before backend PR #234) lack them.
+ * 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
@@ -251,8 +284,8 @@ type Utterance = {
     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.
+     * Reserved — currently always 0. Do not use for sorting; sort by `id`
+     * (UUIDv7) instead.
      */
     order: number;
     is_agent: boolean | null;
@@ -328,4 +361,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.1",
+  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;
     }