@aiqa/sdk 2.3.0 → 2.4.0-develop.1

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)
@@ -226,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`
@@ -787,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;
@@ -798,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 = {
@@ -818,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

@@ -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",
@@ -369,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.3.0-develop.1",
+  version: "2.3.0-develop.2",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",