@aiqa/sdk 2.1.0 → 2.1.1

package/README.md

@@ -19,11 +19,10 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [ApplicationVerificationSummary](#applicationverificationsummary)
   - [ApplicationVerificationStatus](#applicationverificationstatus)
   - [ApplicationFact](#applicationfact)
-  - [ApplicationFactInput](#applicationfactinput)
   - [AddFactResult](#addfactresult)
   - [VerificationStatus](#verificationstatus)
   - [FactVerifiedPayload](#factverifiedpayload)
-  - [FactUpdateEvent](#factupdateevent)
+  - [ApplicationFactInput](#applicationfactinput)
   - [FlagFactResult](#flagfactresult)
   - [ConversationLanguage](#conversationlanguage)
   - [UpdateConversationInput](#updateconversationinput)
@@ -77,9 +76,10 @@ new AiQaSdk(applicationId, applicationSecret, url?)
 
 - `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.
+- `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
 
@@ -114,8 +114,8 @@ sdk.disconnect();
 
 #### `getApplication()`
 
-Returns the application, its conversation participants, and the current
-verification tally for the call.
+Returns the application, its conversation participants, and how the call is
+going so far.
 
 **Returns:**
 
@@ -133,10 +133,13 @@ verification tally for the call.
   }
   ```
 
-  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.
+  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();
@@ -149,27 +152,27 @@ if (application.verification) {
 }
 ```
 
-##### 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".
+##### 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)`
 
@@ -229,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:**
 
@@ -249,23 +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 terminal `verification_status`.
+  reaches a final `verification_status`.
 
 **Parameters:**
 
@@ -275,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;
@@ -287,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>
   }
@@ -311,56 +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, contact AIQA support first 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)`>` — every fact of the
-  application, each with its current `question_status` /
-  `verification_status`.
+- `Promise<`[`ApplicationFact[]`](#applicationfact)`>` — each fact with its
+  current `question_status` and `verification_status`.
 
 ```typescript
 const facts = await sdk.getFacts();
@@ -371,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:**
 
@@ -436,21 +429,20 @@ Registers an event listener. Call `connect()` before `on()`.
 
 **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();
@@ -468,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
@@ -479,50 +484,33 @@ 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 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. Omit `callback` to remove every listener
-registered for the event.
-
-**Returns:**
-
-- `void`
-
-```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 the verification tally at the moment of
-the call.
+participants of the conversation, and how the call is going so far.
 
 ```typescript
 type Application = {
@@ -530,9 +518,10 @@ type Application = {
   client_name: string;
   client_phone_number: string;
   agent_id: string;
-  agent_first_name: string;
-  agent_last_name: string;
-  // Absent on servers that predate this field.
+  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;
 };
 ```
@@ -546,40 +535,42 @@ type ApplicationVerificationSummary = {
   // 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;
 
-  // 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.
+  // 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 genuinely never asked. Does not include the ones
-  // still awaiting a verdict — those are count_pending.
+  // 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;
 
-  // 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 added but not yet resolved. Most of the call's facts sit here early
-  // on and drain as verdicts land.
+  // on and move out as their results arrive.
   count_pending: number;
 
-  // Facts the conduct review flagged. Independent of the answer verdict — 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;
 };
 ```
 
 ### ApplicationVerificationStatus
 
-Rolled-up verdict over the answers, for the whole application. Distinct from
+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 critical fact failed.
+  // At least one fact you sent with critical: true failed.
   | "critical_errors"
   // At least one fact failed, none of them critical.
   | "errors"
@@ -589,7 +580,7 @@ type ApplicationVerificationStatus =
 
 ### 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 & {
@@ -597,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
@@ -621,23 +613,20 @@ 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.
-   * Derived 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 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;
 
@@ -667,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 {
@@ -687,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;
 }
@@ -700,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;
@@ -726,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.
+   * 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.
    *
-   * 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.
-   *
-   * 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>;
 };
@@ -810,25 +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;
-};
-```
-
 ## Examples
 
 ### Complete Example: Recording Session
@@ -845,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();
@@ -864,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?",
@@ -875,7 +842,7 @@ sdk.on("connect", async () => {
     });
 
     console.log(
-      "Terminal verdict:",
+      "Final result:",
       result.verification_status,
       "is_valid_answer:",
       result.is_valid_answer,
@@ -911,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