@aiqa/sdk 2.2.0 → 2.3.0-develop.2

package/README.md

@@ -27,6 +27,7 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [ConversationLanguage](#conversationlanguage)
   - [UpdateConversationInput](#updateconversationinput)
   - [UpdateConversationResult](#updateconversationresult)
+  - [ConversationWarning](#conversationwarning)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
 - [Version Requirements](#version-requirements)
@@ -129,6 +130,7 @@ going so far.
     agent_id: string;
     agent_first_name: string;
     agent_last_name: string;
+    external_status?: string;
     verification?: ApplicationVerificationSummary;
   }
   ```
@@ -140,6 +142,12 @@ going so far.
   [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.
+  `external_status` is the value you last sent with
+  `updateConversation({ externalStatus })`, lowercased — one of
+  [`ExternalStatus`](#externalstatus) — and is **missing** until you send one.
+  Read it to recover the status after a reconnect instead of keeping your own
+  copy. It is the one field here that never comes from the authentication
+  snapshot, so on the fallback path it is absent rather than stale.
 
 ```typescript
 const application = await sdk.getApplication();
@@ -219,36 +227,56 @@ change.
 
 - `input: UpdateConversationInput` - partial set of conversation fields to update
 
-  | field                       | type       | max      | notes                                       |
-  | --------------------------- | ---------- | -------- | ------------------------------------------- |
-  | `policyNumber`              | `string`   | 128      |                                             |
-  | `insuredPhone`              | `string`   | 32       | the insured, who may differ from the caller |
-  | `clientName`                | `string`   | 128      |                                             |
-  | `clientPhone`               | `string`   | 32       |                                             |
-  | `clientEmail`               | `string`   | 254      | must be a valid email address               |
-  | `clientId`                  | `string`   | 64       | your own CRM identifier                     |
-  | `agentId` / `agentName`     | `string`   | 64/128   |                                             |
-  | `advisorId` / `advisorName` | `string`   | 64/128   |                                             |
-  | `agentGroups`               | `string[]` | 32 × 128 | entries cannot contain a comma              |
-  | `externalStatus`            | `string`   | —        | see [`ExternalStatus`](#externalstatus)     |
+  | field                       | type       | max      | notes                                                                   |
+  | --------------------------- | ---------- | -------- | ----------------------------------------------------------------------- |
+  | `policyNumber`              | `string`   | 128      |                                                                         |
+  | `insuredPhone`              | `string`   | 32       | the insured, who may differ from the caller                             |
+  | `clientName`                | `string`   | 128      |                                                                         |
+  | `clientPhone`               | `string`   | 32       |                                                                         |
+  | `clientEmail`               | `string`   | 254      | must be a valid email address                                           |
+  | `clientId`                  | `string`   | 64       | your own CRM identifier                                                 |
+  | `agentId`                   | `string`   | 64       | the agent's AIQA user id; used instead of `agentEmail` if both are sent |
+  | `agentEmail`                | `string`   | 254      | valid email; alternative to `agentId`                                   |
+  | `agentName`                 | `string`   | 128      |                                                                         |
+  | `advisorId` / `advisorName` | `string`   | 64/128   |                                                                         |
+  | `agentGroups`               | `string[]` | 32 × 128 | entries cannot contain a comma                                          |
+  | `externalStatus`            | `string`   | —        | see [`ExternalStatus`](#externalstatus)                                 |
 
   Every string (including each `agentGroups` entry) must be non-empty;
   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.
 
+  **Agent identification**
+
+  | sent                                  | conversation's agent | `conversation.agent_id`                                                                       | `warnings`                 |
+  | ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- | -------------------------- |
+  | `agentId`                             | set to `agentId`     | `agentId`                                                                                     | —                          |
+  | `agentId` + `agentEmail`              | set to `agentId`     | `agentId` (`agentEmail` is ignored)                                                           | —                          |
+  | `agentEmail`, a user matches          | set to that user     | the user's AIQA user id: their email in lowercase (compare it to what you sent ignoring case) | —                          |
+  | `agentEmail`, no user matches         | unchanged            | absent                                                                                        | `agent_not_found`          |
+  | `agentEmail`, temporarily not checked | unchanged            | absent                                                                                        | `agent_lookup_unavailable` |
+  - `conversation` never contains `agentEmail`.
+  - With a warning, `success` is `true` and every other field you sent is saved.
+  - After `agent_lookup_unavailable`, call `updateConversation({ agentEmail })` again later. You do not need to resend the other fields.
+
 **Returns:**
 
-- `Promise<UpdateConversationResult>` - `conversation` echoes only the fields
-  you sent.
+- `Promise<UpdateConversationResult>`
+  - `conversation`: only the fields you sent; a matched `agentEmail` comes back as `agent_id`.
+  - `warnings`: present only when part of the update was not applied.
 
 ```typescript
 const result = await sdk.updateConversation({
   policyNumber: "POL-123",
   clientEmail: "jane@example.com",
+  agentEmail: "vio.agent@example.com",
   externalStatus: ExternalStatus.COMPLETED,
 });
 console.log(result.success, result.conversation.policy_number);
+for (const warning of result.warnings ?? []) {
+  console.warn(warning.code, warning.message);
+}
 ```
 
 ##### `ExternalStatus`
@@ -296,6 +324,8 @@ a timeout, a rejected payload.
     question: string;
     expected_answer: any;
     answer_format: { type: "STRING" }
+    /** Optional (default: `false`). Use `true` when the fact was collected before the conversation started. It is stored, not verified. */
+    prefilled?: boolean
     /**
      * 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
@@ -506,6 +536,8 @@ Rules:
   `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`.**
+- **A fact sent with `prefilled: true` is never verified**, so it gets no
+  `verification_status` and no `FACT_VERIFIED` event.
 - **`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
@@ -527,6 +559,10 @@ type Application = {
   agent_id: string;
   agent_first_name: string; // comes back empty
   agent_last_name: string; // comes back empty
+  // The externalStatus you last sent, lowercased. Missing until you send one
+  // — not the same as "draft". Never in the authentication snapshot, so on the
+  // fallback path below it is absent, not stale.
+  external_status?: ExternalStatus | (string & {});
   // Missing when there is no summary for the call — not the same as zeros.
   // See "Reading verification" above.
   verification?: ApplicationVerificationSummary;
@@ -725,6 +761,8 @@ type ApplicationFactInput = {
   // and one of them sets status to "critical_errors".
   critical?: boolean;
   is_skipped?: boolean;
+  /** Optional (default: `false`). Use `true` when the fact was collected before the conversation started. It is stored, not verified. */
+  prefilled?: boolean;
   /**
    * 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.
@@ -770,7 +808,8 @@ type UpdateConversationInput = {
   clientPhone?: string;
   clientEmail?: string;
   clientId?: string;
-  agentId?: string;
+  agentId?: string; // or agentEmail
+  agentEmail?: string; // or agentId
   agentName?: string;
   advisorId?: string;
   advisorName?: string;
@@ -781,8 +820,10 @@ type UpdateConversationInput = {
 
 ### UpdateConversationResult
 
-Returned by `updateConversation()`. `conversation` echoes only the fields you
-sent.
+Returned by `updateConversation()`.
+
+- `conversation`: only the fields you sent; a matched `agentEmail` comes back as `agent_id`.
+- `warnings`: present only when part of the update was not applied.
 
 ```typescript
 type UpdateConversationResult = {
@@ -801,9 +842,34 @@ type UpdateConversationResult = {
     agent_groups?: string[];
     external_status?: string;
   };
+  // Present only when part of the update was not applied.
+  warnings?: ConversationWarning[];
 };
 ```
 
+### ConversationWarning
+
+```typescript
+interface ConversationWarning {
+  code: ConversationWarningCode;
+  message: string;
+}
+
+type ConversationWarningCode =
+  | "agent_not_found"
+  | "agent_lookup_unavailable"
+  | (string & {});
+```
+
+| `code`                     | meaning                                                         | conversation's agent | what to do                                       |
+| -------------------------- | --------------------------------------------------------------- | -------------------- | ------------------------------------------------ |
+| `agent_not_found`          | no AIQA user in your organization has the `agentEmail`          | unchanged            | check the email                                  |
+| `agent_lookup_unavailable` | the `agentEmail` could not be checked at the moment (temporary) | unchanged            | retry `updateConversation({ agentEmail })` later |
+| any other                  | added in a later version                                        | —                    | log `message` and continue                       |
+
+- Use `code` to choose what to do; do not parse `message`. `message` is human-readable, includes the email you sent, and may change.
+- `success` is `true` and every other field you sent is saved.
+
 ## Examples
 
 ### Complete Example: Recording Session

package/dist/browser/browser.d.ts

@@ -56,6 +56,17 @@ type Application = {
     agent_first_name: string;
     /** Comes back empty. Set an agent name with `updateConversation()`. */
     agent_last_name: string;
+    /**
+     * The status you last reported with `updateConversation({ externalStatus })`,
+     * folded to lowercase by the server. Missing when you never reported one —
+     * which is not the same as `"draft"`. Unlike the fields above it is never in
+     * the authentication snapshot, so on the fallback path described under
+     * `verification` it is absent rather than stale.
+     *
+     * Same open union as the input side: the members autocomplete, and a status
+     * the server learns before this package does still type-checks.
+     */
+    external_status?: ExternalStatus | (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
@@ -99,14 +110,24 @@ type UpdateConversationInput = {
     clientPhone?: string;
     clientEmail?: string;
     clientId?: string;
+    /** The agent's AIQA user id. Takes precedence over `agentEmail`. */
     agentId?: string;
+    /** Email of the agent's AIQA user. Results: README, Agent identification. */
+    agentEmail?: string;
     agentName?: string;
     advisorId?: string;
     advisorName?: string;
     agentGroups?: string[];
     externalStatus?: ExternalStatus | (string & {});
 };
-/** Only the fields you sent come back in `conversation`. */
+/** Decide with `code`, not `message`. Codes: README, ConversationWarning. */
+type ConversationWarningCode = "agent_not_found" | "agent_lookup_unavailable" | (string & {});
+/** Part of an `updateConversation()` that was not applied; the rest was saved. */
+interface ConversationWarning {
+    code: ConversationWarningCode;
+    message: string;
+}
+/** `conversation` holds the fields you sent; `warnings` only when part was not applied. */
 type UpdateConversationResult = {
     success: boolean;
     conversation: {
@@ -123,6 +144,7 @@ type UpdateConversationResult = {
         agent_groups?: string[];
         external_status?: string;
     };
+    warnings?: ConversationWarning[];
 };
 declare enum ConversationLanguage {
     EN = "en",
@@ -170,6 +192,8 @@ type ApplicationFactInput = {
      */
     critical?: boolean;
     is_skipped?: boolean;
+    /** Optional (default: `false`). Use `true` when the fact was collected before the conversation started. It is stored, not verified. */
+    prefilled?: 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.
@@ -217,6 +241,7 @@ interface AddFactResult {
     answer_type?: string;
     agent_answer?: string;
     ai_answer?: string;
+    /** `false` for a fact that was never verified, such as a prefilled one. */
     is_valid_answer: boolean;
     question_asked?: boolean;
     /**
@@ -355,4 +380,4 @@ declare class AiQaSdk implements IAiqaSdk {
     private isManagerEvent;
 }
 
-export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, type ApplicationVerificationStatus, type ApplicationVerificationSummary, ConversationLanguage, type DialogAct, type DialogActConfidence, ExternalStatus, 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 ConversationWarning, type ConversationWarningCode, type DialogAct, type DialogActConfidence, ExternalStatus, 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

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