@aiqa/sdk 2.3.0 → 2.4.0-develop.2

package/README.md

@@ -20,6 +20,7 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [ApplicationVerificationStatus](#applicationverificationstatus)
   - [ApplicationFact](#applicationfact)
   - [AddFactResult](#addfactresult)
+  - [FactWarning](#factwarning)
   - [VerificationStatus](#verificationstatus)
   - [FactVerifiedPayload](#factverifiedpayload)
   - [ApplicationFactInput](#applicationfactinput)
@@ -27,6 +28,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)
@@ -226,36 +228,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`
@@ -284,6 +306,8 @@ a timeout, a rejected payload.
 
 - `Promise<`[`AddFactResult`](#addfactresult)`>` — resolves once the fact
   reaches a final `verification_status`.
+  - `warnings`: present only when part of this `addFact()` was not applied.
+    See [`FactWarning`](#factwarning).
 
 **Parameters:**
 
@@ -327,6 +351,10 @@ const result = await sdk.addFact({
   metadata: { uiFieldId: "policy-agreement", section: "consent" },
 });
 
+for (const warning of result.warnings ?? []) {
+  console.warn(warning.code, warning.message);
+}
+
 if (result.is_valid_answer) {
   // verification_status, when present, is "matched".
   console.log("matched:", result.ai_answer);
@@ -660,10 +688,36 @@ interface AddFactResult {
   matched_components?: string[];
   missing_components?: string[];
 
+  // Present only when part of this addFact() was not applied.
+  warnings?: FactWarning[];
+
   metadata?: Record<string, string>;
 }
 ```
 
+### FactWarning
+
+Listed in `warnings` on the [`AddFactResult`](#addfactresult) returned by the
+`addFact()` call that caused them. `FACT_VERIFIED` events never include
+warnings, so read them from the `addFact()` result.
+
+```typescript
+interface FactWarning {
+  code: FactWarningCode;
+  message: string;
+}
+
+type FactWarningCode = "category_not_found" | (string & {});
+```
+
+| `code`               | meaning                                              | question's category | what to do                                                                            |
+| -------------------- | ---------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
+| `category_not_found` | there is no category with the `category_id` you sent | unchanged           | check the `category_id` and send it again with the next `addFact()` for this question |
+| 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 `category_id` you sent, and may change.
+- The rest of the fact is saved, and `addFact()` resolves as usual with its result.
+
 ### VerificationStatus
 
 ```typescript
@@ -686,7 +740,8 @@ which states are final.
 ### FactVerifiedPayload
 
 Payload of the `FACT_VERIFIED` event: which fact the update is about, its
-current state, and the full [`AddFactResult`](#addfactresult) shape in `data`.
+current state, and the [`AddFactResult`](#addfactresult) shape in `data`,
+without `warnings`.
 
 ```typescript
 interface FactVerifiedPayload {
@@ -697,8 +752,8 @@ interface FactVerifiedPayload {
   answer_match_score?: number;
   matched_components?: string[];
   missing_components?: string[];
-  /** Inner payload, same shape as AddFactResult. */
-  data?: AddFactResult;
+  /** Inner payload, same shape as AddFactResult without warnings. */
+  data?: Omit<AddFactResult, "warnings">;
   error?: string;
 }
 ```
@@ -787,7 +842,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;
@@ -798,8 +854,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 = {
@@ -818,9 +876,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

@@ -110,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: {
@@ -134,6 +144,7 @@ type UpdateConversationResult = {
         agent_groups?: string[];
         external_status?: string;
     };
+    warnings?: ConversationWarning[];
 };
 declare enum ConversationLanguage {
     EN = "en",
@@ -221,6 +232,17 @@ type ApplicationFact = ApplicationFactInput & {
     /** True once `flagFact(factId)` has been called for this fact. */
     flagged: boolean;
 };
+/**
+ * Why part of an `addFact()` was not applied. Use it to choose what to do; do
+ * not parse `message`. Later versions may add codes: log `message` and
+ * continue. See "FactWarning" in the README.
+ */
+type FactWarningCode = "category_not_found" | (string & {});
+/** Part of an `addFact()` that was not applied. The rest of the fact is saved. */
+interface FactWarning {
+    code: FactWarningCode;
+    message: string;
+}
 interface AddFactResult {
     /** Conversation the fact was attached to. */
     conversation_id?: string;
@@ -256,6 +278,8 @@ interface AddFactResult {
      */
     matched_components?: string[];
     missing_components?: string[];
+    /** Present only when part of this `addFact()` was not applied. */
+    warnings?: FactWarning[];
 }
 /**
  * Payload of the `FACT_VERIFIED` event, which fires on every state change —
@@ -270,8 +294,8 @@ interface FactVerifiedPayload {
     answer_match_score?: number;
     matched_components?: string[];
     missing_components?: string[];
-    /** Inner payload, shaped like `AddFactResult`. */
-    data?: AddFactResult;
+    /** Inner payload, shaped like `AddFactResult` without `warnings`. */
+    data?: Omit<AddFactResult, "warnings">;
     error?: string;
 }
 type FlagFactResult = {
@@ -369,4 +393,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 FactWarning, type FactWarningCode, 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.3.0-develop.1",
+  version: "2.4.0-develop.1",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3732,7 +3732,7 @@ var AiQaSdk = class {
     const result = await this.sendMessage("ADD_FACT" /* ADD_FACT */, payload);
     if (!result) return result;
     const inner = result.data !== void 0 ? result.data : result;
-    const hasEnvelope = result.verification_status !== void 0 || result.matched_components !== void 0 || result.missing_components !== void 0;
+    const hasEnvelope = result.verification_status !== void 0 || result.matched_components !== void 0 || result.missing_components !== void 0 || result.warnings !== void 0;
     if (!hasEnvelope || typeof inner !== "object" || inner === null) {
       return inner;
     }
@@ -3746,6 +3746,9 @@ var AiQaSdk = class {
     if (result.missing_components !== void 0) {
       merged.missing_components = result.missing_components;
     }
+    if (result.warnings !== void 0) {
+      merged.warnings = result.warnings;
+    }
     return merged;
   }
   async flagFact(factId) {