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

package/README.md

@@ -10,20 +10,27 @@ 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)
   - [AddFactResult](#addfactresult)
   - [VerificationStatus](#verificationstatus)
   - [FactVerifiedPayload](#factverifiedpayload)
+  - [ApplicationFactInput](#applicationfactinput)
   - [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 +72,15 @@ 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. Always pass it; the default
+  only works for local development.
+
+The constructor throws if either credential is empty.
+
 ## 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,73 @@ 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 how the call is
+going so far.
+
+**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;
+  }
+  ```
+
+  Wait for the `authenticated` event before calling it: until authentication
+  has completed, and whenever the connection is down, it **rejects**.
+  `client_name`, `client_phone_number` and `agent_id` normally carry any change
+  you made with `updateConversation()` earlier in the call — see
+  [Reading `verification`](#reading-verification) for the exception.
+  `agent_first_name` and `agent_last_name` come back empty; use
+  `updateConversation({ agentName })` if you need to record an agent's name.
 
 ```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`
+
+The numbers change during a call. A fact counts as pending from the moment you
+add it until its result arrives, so call `getApplication()` again whenever you
+want current figures.
+
+**A fact that was never asked and came back wrong is counted twice: once in
+`count_not_asked` and once in `count_errors`.** That is ordinary, not an edge
+case, and `count_total` also includes every fact that is still pending. So no
+subtraction from `count_total` gives you a reliable number of facts that
+passed. To show one, count the facts whose `verification_status` is `matched`
+in [`getFacts()`](#getfacts).
+
+`status` summarises the answers only, so a call where nothing was asked reads
+`no_errors`. Read `count_pending` and `count_not_asked` if your UI cares
+whether the call is complete.
+
+`verification` is not always there. When it is missing, there is no summary for
+this call — treat that as unknown rather than as all zeros, and note that
+the identity fields alongside it may then be the ones from when you
+authenticated, without an `updateConversation()` you made since.
+
 #### `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:**
 
@@ -154,8 +232,9 @@ change.
   | `agentGroups`               | `string[]` | 32 × 128 | entries cannot contain a comma              |
 
   Every string (including each `agentGroups` entry) must be non-empty;
-  surrounding whitespace is trimmed. `null` is rejected — omit the field
-  instead. At least one field is required.
+  surrounding whitespace is trimmed first, so a value of only spaces is
+  rejected. `null` is rejected — omit the field instead. At least one field is
+  required, and any field not in the table is rejected.
 
 **Returns:**
 
@@ -174,18 +253,23 @@ console.log(result.success, result.conversation.policy_number);
 
 #### `addFact(fact)`
 
-Adds a fact to the active application and waits for the **terminal**
-verification verdict (Promise-based). The Promise resolves with an
+Adds a fact to the active application and waits for the **final**
+verification result. The Promise resolves with an
 [`AddFactResult`](#addfactresult); subscribe to the
-[`FACT_VERIFIED`](#event-handling) broadcast event to render progress
+[`FACT_VERIFIED`](#event-handling) event to show progress
 (`awaiting_question`, `awaiting_answer`, `partial`,
 `pending_confirmation_matched`, `pending_confirmation_unmatched`)
 while you wait.
 
-`addFact()` does not throw on verification failure — an unmatched
-fact resolves with `is_valid_answer: false` and (where the backend
-provides it) `verification_status: "unmatched"`.
-Reject paths are reserved for transport / protocol errors.
+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,
+a timeout, a rejected payload.
+
+**Returns:**
+
+- `Promise<`[`AddFactResult`](#addfactresult)`>` — resolves once the fact
+  reaches a final `verification_status`.
 
 **Parameters:**
 
@@ -195,11 +279,10 @@ Reject paths are reserved for transport / protocol errors.
     id: string;
     /**
      * Optional. 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`. When
-     * omitted, `id` is used (legacy behavior).
+     * applications and conversations. When provided it identifies the
+     * question instead of `id`. When omitted, `id` is used.
      *
-     * Keep this consistent across calls for the "same" question — see
+     * Keep it consistent across calls for the "same" question — see
      * "Question identity and questionId" below.
      */
     questionId?: string;
@@ -207,14 +290,12 @@ Reject paths are reserved for transport / protocol errors.
     expected_answer: any;
     answer_format: { type: "STRING" }
     /**
-     * Optional. Use this to attach your own identifiers to a fact so your UI
-     * can map the server response back to the right field or component.
-     * For example, store a form field ID, a section name, or any internal
-     * reference you need — the server stores it as-is and returns it unchanged
-     * in getFacts().
+     * 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. getFacts() returns it unchanged.
      *
-     * Constraints: all keys and values must be strings; each value is limited
-     * to 1024 characters. Payloads that exceed this limit are rejected.
+     * 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>
   }
@@ -231,50 +312,48 @@ const result = await sdk.addFact({
 });
 
 if (result.is_valid_answer) {
-  // verification_status will be "matched".
+  // verification_status, when present, is "matched".
   console.log("matched:", result.ai_answer);
 } else {
-  // verification_status will be "unmatched". matched_components /
-  // missing_components describe what the partial-match heuristics
-  // were able to extract.
+  // verification_status, when present, is "unmatched". matched_components /
+  // missing_components describe which parts of the expected answer
+  // were and were not found.
   console.log("unmatched:", result.missing_components);
 }
 ```
 
 ##### Question identity and `questionId`
 
-`id` identifies an instance of a fact within a single conversation. `questionId`
-is an optional field that identifies the underlying question across every
-application and conversation that asks it. They're separated so you can give
-each fact instance its own `id` (e.g. a per-call uuid) while still pointing at a
-stable question identity.
-
-Two server-side features are scoped per question identity:
-
-- **Accuracy improvements.** Per-question signals (flags, model tweaks, fuzzy
-  matches) accumulate against the question row. Splitting the same logical
-  question across multiple identities splits these signals and resets the
-  accuracy gains you've already earned.
-- **Remaps from the management dashboard.** When an operator remaps a question
-  in the dashboard, the remap is stored on the question row. A subsequent call
-  with a different identity won't pick up the remap.
-
-The "question identity" the server uses is `questionId` if you sent one,
-otherwise `id`. So:
-
-- If your `id` is already stable across calls for the same logical question,
-  omitting `questionId` is fine — both features above still work, just keyed off
-  `id`.
-- If your `id` varies per call (per-call uuid, ephemeral instance id, etc.),
-  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.
+`id` identifies one fact within a single conversation. `questionId` identifies
+the underlying question across every application and conversation that asks it.
+They are separate fields so you can give each fact its own `id` — a per-call
+uuid, say — while still pointing at a stable question.
+
+The question identity is `questionId` when you send one, otherwise `id`.
+Anything AIQA has tuned for a question is attached to that identity: the
+corrections that decide how its answers are read, the phrasings that count as
+asking it, the outcome of reviewing facts you flagged. A call that arrives
+under a different identity gets none of it. So:
+
+- If your `id` is already stable across calls for the same question, omitting
+  `questionId` is fine — the identity is then your `id`.
+- If your `id` varies per call (a per-call uuid, an ephemeral instance id),
+  send a stable `questionId`. Otherwise every call looks like a brand-new
+  question.
+- Once you have picked an identity for a question, don't change it. If you have
+  to rename one, contact AIQA support first so the tuning can move with it.
 
 #### `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 `{}`.
+Retrieves every fact on the application, whatever state it is in. Each one
+carries the `metadata` you passed to `addFact()`, or `{}` if you passed none.
+This is also where to count facts by outcome — for a pass count, count the ones
+whose `verification_status` is `matched`.
+
+**Returns:**
+
+- `Promise<`[`ApplicationFact[]`](#applicationfact)`>` — each fact with its
+  current `question_status` and `verification_status`.
 
 ```typescript
 const facts = await sdk.getFacts();
@@ -285,7 +364,7 @@ facts.forEach((fact) => {
 
 #### `flagFact(factId)`
 
-Flags a fact for human review. Creates a signal that allow AIQA to improve review quality.
+Flags a fact for human review.
 
 **Parameters:**
 
@@ -304,7 +383,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 +395,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 +407,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,23 +423,26 @@ const isRecording = await sdk.isRecordingNow();
 
 Registers an event listener. Call `connect()` before `on()`.
 
+**Returns:**
+
+- `void`
+
 **Available Events:**
 
-- `connect` - Socket.IO connection established
-- `disconnect` - Socket.IO connection closed
-- `close` - Socket.IO connection closed
-- `error` - Connection or socket error
-- `reconnect_attempt` - Socket.IO reconnection attempt
-- `reconnect_error` - Socket.IO reconnection error
-- `reconnect_failed` - Socket.IO reconnection failed
-- `authenticated` - Local event fired after successful authentication (provides Application object)
-- `app_version` - Server event with version requirements `{ min, max }`
-- `FACT_VERIFIED` - Broadcast event fired on **every** verification
-  state transition (both non-terminal progress and terminal verdicts)
-  for **every** fact in the active conversation. Payload shape:
-  [`FactVerifiedPayload`](#factverifiedpayload). Use this to render
-  live verification progress in your UI; `addFact()`'s Promise only
-  resolves on the terminal state.
+- `connect` - connection established
+- `disconnect` - connection closed
+- `close` - connection closed
+- `error` - connection or socket error
+- `reconnect_attempt` - reconnection attempt
+- `reconnect_error` - reconnection attempt failed
+- `reconnect_failed` - reconnection gave up
+- `authenticated` - authentication succeeded; receives the
+  [`Application`](#application)
+- `app_version` - the SDK version range the service supports, `{ min, max }`
+- `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.
 
 ```typescript
 sdk.connect();
@@ -366,6 +460,19 @@ sdk.on("FACT_VERIFIED", (payload) => {
 });
 ```
 
+#### `off(eventName, callback?)`
+
+Removes an event listener. Omit `callback` to remove every listener
+registered for the event.
+
+**Returns:**
+
+- `void`
+
+```typescript
+sdk.off("connect");
+```
+
 ## Verification lifecycle
 
 A single `addFact()` call walks through a sequence of states emitted
@@ -377,56 +484,103 @@ processing
         └─> awaiting_answer (asked, customer hasn't answered yet)
               └─> partial   (partial evidence — e.g. "305" of "30521")
                     └─> pending_confirmation_matched
-                          (backend has a match but is holding a settling
-                           window for mid-answer clarifications like
-                           spellings or "I mean…" corrections)
+                          (a match is held briefly in case the customer
+                           corrects it mid-answer — spellings, "I mean…")
                     └─> pending_confirmation_unmatched
-                          (same, but for a held unmatched verdict)
+                          (same, but for a held unmatched answer)
                           │
                           ▼
-                    matched | unmatched   ← terminal
+                    matched | unmatched   ← final
 ```
 
-Rules for consumers:
+Rules:
 
-- **`addFact()` resolves only on a terminal state** (`matched`,
-  `unmatched`). Render progress from the
-  `FACT_VERIFIED` event, render the final verdict from the Promise
-  result.
-- **Treat unknown `verification_status` strings as `processing`.**
-  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.
-
-#### `off(eventName, callback?)`
-
-Removes an event listener.
-
-```typescript
-sdk.off("connect");
-```
+- **`addFact()` resolves only on a final state** (`matched`,
+  `unmatched`). Show progress from the `FACT_VERIFIED` event, show the final
+  result from the Promise.
+- **Handle a `verification_status` you don't recognize as `processing`.**
+- **`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`.
 
 ## Types
 
 ### Application
 
+Returned by [`getApplication()`](#getapplication): the application, the two
+participants of the conversation, and how the call is going so far.
+
 ```typescript
 type Application = {
   application_id: string;
   client_name: string;
   client_phone_number: string;
   agent_id: string;
-  agent_first_name: string;
-  agent_last_name: string;
+  agent_first_name: string; // comes back empty
+  agent_last_name: string; // comes back empty
+  // Missing when there is no summary for the call — not the same as zeros.
+  // See "Reading verification" above.
+  verification?: ApplicationVerificationSummary;
 };
 ```
 
+### ApplicationVerificationSummary
+
+```typescript
+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 gives you a pass count.
+  count_total: number;
+
+  // Facts whose question was never asked. Does not include the ones still
+  // waiting for a result — those are count_pending. It does overlap
+  // 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 yet resolved. Most of the call's facts sit here early
+  // on and move out 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;
+};
+```
+
+### ApplicationVerificationStatus
+
+Overall result for the whole call, based on the answers. Distinct from
+[`VerificationStatus`](#verificationstatus), which describes a single fact.
+Questions that were never asked do not raise it.
+
+```typescript
+type ApplicationVerificationStatus =
+  // At least one fact you sent with critical: true 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.
+Returned by `getFacts()`. Extends `ApplicationFactInput` with the fields the service fills in.
 
 ```typescript
 type ApplicationFact = ApplicationFactInput & {
@@ -434,13 +588,14 @@ type ApplicationFact = ApplicationFactInput & {
   question_status: "searching" | "asked" | "not_asked";
   verification_status: VerificationStatus;
   flagged: boolean; // true once flagFact() has been called for this fact
-  metadata: Record<string, string>; // always present; {} when not set on addFact
+  // metadata is inherited from ApplicationFactInput, where it is optional.
+  // getFacts() always fills it in: {} for a fact you added without one.
 };
 ```
 
 ### AddFactResult
 
-Resolved value of `addFact()`. Only emitted at the terminal verification
+Resolved value of `addFact()`. Only sent once the fact reaches its final
 state — see [Verification lifecycle](#verification-lifecycle).
 
 ```typescript
@@ -458,31 +613,27 @@ interface AddFactResult {
   question_asked?: boolean;
 
   /**
-   * 0–1 (or 0–100 — scale matches the configured similarity method).
-   * Similarity between the agent's utterance and the expected question.
+   * 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).
+   * 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;
 
   /**
-   * 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[];
@@ -505,16 +656,15 @@ type VerificationStatus =
   | "unmatched";
 ```
 
-The enum is additive: consumers that `switch` on this value MUST
-treat unknown strings as `"processing"` so older SDK builds keep
-working after the backend ships a new state. See the
-[Verification lifecycle](#verification-lifecycle) for the transitions
-and which states are terminal.
+Code that `switch`es on this value must treat any string it doesn't
+recognize as `"processing"`. See the
+[Verification lifecycle](#verification-lifecycle) for the transitions and
+which states are final.
 
 ### FactVerifiedPayload
 
-Payload of the `FACT_VERIFIED` broadcast event. Same shape as
-`AddFactResult` plus the `factId` / `success` / `error` envelope.
+Payload of the `FACT_VERIFIED` event: which fact the update is about, its
+current state, and the full [`AddFactResult`](#addfactresult) shape in `data`.
 
 ```typescript
 interface FactVerifiedPayload {
@@ -525,7 +675,7 @@ interface FactVerifiedPayload {
   answer_match_score?: number;
   matched_components?: string[];
   missing_components?: string[];
-  /** Same shape as AddFactResult so the same renderer handles both. */
+  /** Inner payload, same shape as AddFactResult. */
   data?: AddFactResult;
   error?: string;
 }
@@ -538,12 +688,12 @@ type ApplicationFactInput = {
   id: string;
   /**
    * Optional. Stable identifier for the underlying question, shared across
-   * applications and conversations. Used to look up (or create) the matching
-   * question row in the database when provided. When omitted, `id` is used.
+   * applications and conversations. When provided it identifies the question
+   * instead of `id`. When omitted, `id` is used.
    *
-   * Keep this consistent across calls — accuracy improvements and remaps
-   * configured in the management dashboard are scoped per `questionId`. See
-   * "Question identity and questionId" under `addFact()`.
+   * Keep it consistent across calls: whatever AIQA has tuned for a question is
+   * attached to this identity. See "Question identity and questionId" under
+   * `addFact()`.
    */
   questionId?: string;
   question: string;
@@ -564,21 +714,18 @@ 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 status to "critical_errors".
   critical?: boolean;
   is_skipped?: boolean;
   /**
-   * Optional. Attach your own identifiers to a fact so your UI can map the
-   * server response back to the right field or component — for example a form
-   * field ID, a section name, or any internal reference you need.
-   *
-   * The server stores this value encrypted alongside the fact and returns it
-   * unchanged in getFacts(). It is never inspected, indexed, or used for
-   * verification logic.
+   * 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.
+   * getFacts() returns it unchanged (as {} for a fact you added without one),
+   * and it plays no part in verification.
    *
-   * Constraints:
-   * - All keys and values must be strings.
-   * - Each individual value is limited to 1024 characters.
-   * - Payloads that violate either constraint are rejected by the server.
+   * 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>;
 };
@@ -648,55 +795,6 @@ type UpdateConversationResult = {
 };
 ```
 
-### FactUpdateEvent
-
-```typescript
-type FactUpdateEvent = {
-  fact_id: string;
-  question_id?: string;
-  status:
-    | "asked"
-    | "answered_detected"
-    | "agent_answered"
-    | "verification_pending"
-    | "verified"
-    | "failed";
-  detectedAnswer?: any;
-  agentAnswer?: any;
-  verifiedAnswer?: any;
-};
-```
-
-## 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
@@ -713,8 +811,9 @@ const sdk = new AiQaSdk(
 
 sdk.connect();
 
-sdk.on("connect", async () => {
-  console.log("Connected!");
+// getApplication() is only available once authentication has completed.
+sdk.on("authenticated", async () => {
+  console.log("Authenticated!");
 
   try {
     const application = await sdk.getApplication();
@@ -732,7 +831,7 @@ sdk.on("connect", async () => {
       );
     });
 
-    // Add a fact (Promise resolves at the terminal verdict)
+    // Add a fact (the Promise resolves once verification finishes)
     const result = await sdk.addFact({
       id: "q1",
       question: "What is your name?",
@@ -743,7 +842,7 @@ sdk.on("connect", async () => {
     });
 
     console.log(
-      "Terminal verdict:",
+      "Final result:",
       result.verification_status,
       "is_valid_answer:",
       result.is_valid_answer,
@@ -779,14 +878,15 @@ try {
 
 ### Common Error Scenarios
 
-1. **Connection Errors**: Fired through the `error` event
-2. **Version Mismatch**: Thrown when the server version is incompatible
-3. **Invalid Data**: Returned as rejected promises
-4. **Network Issues**: Handled through reconnection events
+1. **Connection errors** - reported through the `error` event.
+2. **Unsupported SDK version** - the SDK disconnects and reports it through
+   the `error` event.
+3. **Invalid data** - the method's Promise rejects.
+4. **Network drops** - reported through the `reconnect_*` events.
 
 ## Version Requirements
 
-The server emits an `app_version` payload with `{ min, max }` supported SDK versions. If the current SDK version is outside that range, the SDK disconnects and emits an `error` event.
+If your SDK version is outside the range the service supports, the SDK disconnects and emits an `error` event. The supported range arrives on the `app_version` event as `{ min, max }`.
 
 ## License