@aiqa/sdk 2.5.0 → 3.0.0-develop.2

package/README.md

@@ -29,6 +29,8 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [UpdateConversationInput](#updateconversationinput)
   - [UpdateConversationResult](#updateconversationresult)
   - [ConversationWarning](#conversationwarning)
+  - [UpsertAdvisorInput](#upsertadvisorinput)
+  - [UpsertAdvisorResult](#upsertadvisorresult)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
 - [Version Requirements](#version-requirements)
@@ -129,8 +131,6 @@ going so far.
     client_name: string;
     client_phone_number: string;
     agent_id: string;
-    agent_first_name: string;
-    agent_last_name: string;
     external_status?: string;
     verification?: ApplicationVerificationSummary;
   }
@@ -138,11 +138,11 @@ going so far.
 
   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
+  `agent_id` is the advisor's AIQA user id, the value `updateConversation()`
+  returns as `conversation.advisor_id`. `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.
   `external_status` is the value you last sent with
   `updateConversation({ externalStatus })`, lowercased — one of
   [`ExternalStatus`](#externalstatus) — and is **missing** until you send one.
@@ -228,50 +228,48 @@ 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`                   | `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)                                 |
+  | 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                                                                                         |
+  | `advisorId`      | `string`   | 64       | the advisor's AIQA user id; used instead of `advisorEmail` if both are sent; a longer id goes in `advisorEmail` |
+  | `advisorEmail`   | `string`   | 254      | email of the advisor's AIQA user; AIQA links the call to that user                                              |
+  | `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**
+  **Advisor 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`.
+  | sent                                    | conversation's advisor | `conversation.advisor_id`                                                                     | `warnings`                   |
+  | --------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- | ---------------------------- |
+  | `advisorId`                             | set to `advisorId`     | `advisorId`                                                                                   | —                            |
+  | `advisorId` + `advisorEmail`            | set to `advisorId`     | `advisorId` (`advisorEmail` is ignored)                                                       | —                            |
+  | `advisorEmail`, 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) | —                            |
+  | `advisorEmail`, no user matches         | unchanged              | absent                                                                                        | `advisor_not_found`          |
+  | `advisorEmail`, temporarily not checked | unchanged              | absent                                                                                        | `advisor_lookup_unavailable` |
+  - The result never includes the email you sent; a matched user comes back as their id in `advisor_id`.
   - 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.
+  - After `advisor_lookup_unavailable`, call `updateConversation({ advisorEmail })` again later. You do not need to resend the other fields.
 
 **Returns:**
 
 - `Promise<UpdateConversationResult>`
-  - `conversation`: only the fields you sent; a matched `agentEmail` comes back as `agent_id`.
+  - `conversation`: only the fields you sent; a matched `advisorEmail` comes back as `advisor_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",
+  advisorEmail: "advisor@example.com",
   externalStatus: ExternalStatus.COMPLETED,
 });
 console.log(result.success, result.conversation.policy_number);
@@ -285,6 +283,40 @@ for (const warning of result.warnings ?? []) {
 User-provided application status: `draft`, `pending`, `completed`, `expired`,
 `closed`.
 
+#### `upsertAdvisor()`
+
+Creates an advisor in your organization, or updates the name of an existing
+advisor with the same email. Use the returned `advisor_id` with
+`updateConversation({ advisorId })`.
+
+**Parameters:**
+
+- `input: UpsertAdvisorInput` - `advisorEmail`, `firstName` and `lastName`, all required
+
+**Returns:**
+
+- `Promise<UpsertAdvisorResult>`
+
+| your organization has                                                  | result                                                                                                                                                                                           |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| no user with that email                                                | the advisor is created; `created: true`                                                                                                                                                          |
+| an advisor with that email                                             | its first and last name are updated; `created: false`                                                                                                                                            |
+| a user with that email who is not an advisor, such as an administrator | the user is not changed and keeps its own first and last name, which can differ from what you sent; `created: false`. You can still pass its `advisor_id` to `updateConversation({ advisorId })` |
+
+- `advisor_id` is the email in lowercase.
+- The Promise rejects when the advisor cannot be saved: invalid input (for
+  example, a malformed email), or, rarely, a different user in your
+  organization who already signs in with that email.
+
+```typescript
+const result = await sdk.upsertAdvisor({
+  advisorEmail: "advisor@example.com",
+  firstName: "Jane",
+  lastName: "Doe",
+});
+await sdk.updateConversation({ advisorId: result.advisor.advisor_id });
+```
+
 ### Fact Management
 
 #### `addFact(fact)`
@@ -524,7 +556,7 @@ on the `FACT_VERIFIED` broadcast event before the Promise resolves:
 
 ```
 processing
-  └─> awaiting_question     (agent hasn't asked yet)
+  └─> awaiting_question     (advisor hasn't asked yet)
         └─> awaiting_answer (asked, customer hasn't answered yet)
               └─> partial   (partial evidence — e.g. "305" of "30521")
                     └─> pending_confirmation_matched
@@ -563,9 +595,7 @@ type Application = {
   application_id: string;
   client_name: string;
   client_phone_number: string;
-  agent_id: string;
-  agent_first_name: string; // comes back empty
-  agent_last_name: string; // comes back empty
+  agent_id: string; // the advisor's AIQA user id (conversation.advisor_id)
   // 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.
@@ -606,7 +636,7 @@ type ApplicationVerificationSummary = {
   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
+  // advisor 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;
 };
@@ -663,7 +693,7 @@ interface AddFactResult {
   question_asked?: boolean;
 
   /**
-   * How closely the agent's utterance matched the expected question, on a
+   * How closely the advisor's utterance matched the expected question, on a
    * 0–1 or a 0–100 scale. Higher is closer.
    */
   question_match_score?: number;
@@ -842,11 +872,8 @@ type UpdateConversationInput = {
   clientPhone?: string;
   clientEmail?: string;
   clientId?: string;
-  agentId?: string; // or agentEmail
-  agentEmail?: string; // or agentId
-  agentName?: string;
-  advisorId?: string;
-  advisorName?: string;
+  advisorId?: string; // or advisorEmail
+  advisorEmail?: string; // or advisorId
   agentGroups?: string[];
   externalStatus?: ExternalStatus | (string & {});
 };
@@ -856,7 +883,7 @@ type UpdateConversationInput = {
 
 Returned by `updateConversation()`.
 
-- `conversation`: only the fields you sent; a matched `agentEmail` comes back as `agent_id`.
+- `conversation`: only the fields you sent; a matched `advisorEmail` comes back as `advisor_id`.
 - `warnings`: present only when part of the update was not applied.
 
 ```typescript
@@ -869,10 +896,7 @@ type UpdateConversationResult = {
     client_phone?: string;
     client_email?: string;
     client_id?: string;
-    agent_id?: string;
-    agent_name?: string;
     advisor_id?: string;
-    advisor_name?: string;
     agent_groups?: string[];
     external_status?: string;
   };
@@ -890,20 +914,48 @@ interface ConversationWarning {
 }
 
 type ConversationWarningCode =
-  | "agent_not_found"
-  | "agent_lookup_unavailable"
+  | "advisor_not_found"
+  | "advisor_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                       |
+| `code`                       | meaning                                                           | conversation's advisor | what to do                                                                      |
+| ---------------------------- | ----------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
+| `advisor_not_found`          | no AIQA user in your organization has the `advisorEmail`          | unchanged              | check the email, or create the advisor with [`upsertAdvisor()`](#upsertadvisor) |
+| `advisor_lookup_unavailable` | the `advisorEmail` could not be checked at the moment (temporary) | unchanged              | retry `updateConversation({ advisorEmail })` 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.
 
+### UpsertAdvisorInput
+
+Accepted by `upsertAdvisor()`.
+
+```typescript
+type UpsertAdvisorInput = {
+  advisorEmail: string;
+  firstName: string;
+  lastName: string;
+};
+```
+
+### UpsertAdvisorResult
+
+Returned by `upsertAdvisor()`.
+
+```typescript
+type UpsertAdvisorResult = {
+  success: boolean; // always true when the Promise resolves
+  advisor: {
+    advisor_id: string; // pass it to updateConversation({ advisorId })
+    first_name: string | null; // null only for an existing non-advisor user with no name stored
+    last_name: string | null; // same as first_name
+    created: boolean; // true when created; false when a user in your organization already had this email
+  };
+};
+```
+
 ## Examples
 
 ### Complete Example: Recording Session

package/dist/browser/browser.d.ts

@@ -42,7 +42,7 @@ type ApplicationVerificationSummary = {
     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
+     * advisor 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;
@@ -51,11 +51,8 @@ type Application = {
     application_id: string;
     client_name: string;
     client_phone_number: string;
+    /** The advisor's AIQA user id; `updateConversation()` returns it as `conversation.advisor_id`. */
     agent_id: string;
-    /** Comes back empty. Set an agent name with `updateConversation()`. */
-    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 —
@@ -85,7 +82,8 @@ declare enum Methods {
     FLAG_FACT = "FLAG_FACT",
     SET_CONVERSATION_PRODUCT = "SET_CONVERSATION_PRODUCT",
     SET_CONVERSATION_LANGUAGE = "SET_CONVERSATION_LANGUAGE",
-    UPDATE_CONVERSATION = "UPDATE_CONVERSATION"
+    UPDATE_CONVERSATION = "UPDATE_CONVERSATION",
+    UPSERT_ADVISOR = "UPSERT_ADVISOR"
 }
 type SetConversationProductResult = {
     success: boolean;
@@ -110,18 +108,15 @@ 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;
+    /** The advisor's AIQA user id. Takes precedence over `advisorEmail`. */
     advisorId?: string;
-    advisorName?: string;
+    /** Email of the advisor's AIQA user. Results: README, Advisor identification. */
+    advisorEmail?: string;
     agentGroups?: string[];
     externalStatus?: ExternalStatus | (string & {});
 };
 /** Decide with `code`, not `message`. Codes: README, ConversationWarning. */
-type ConversationWarningCode = "agent_not_found" | "agent_lookup_unavailable" | (string & {});
+type ConversationWarningCode = "advisor_not_found" | "advisor_lookup_unavailable" | (string & {});
 /** Part of an `updateConversation()` that was not applied; the rest was saved. */
 interface ConversationWarning {
     code: ConversationWarningCode;
@@ -137,15 +132,34 @@ type UpdateConversationResult = {
         client_phone?: string;
         client_email?: string;
         client_id?: string;
-        agent_id?: string;
-        agent_name?: string;
         advisor_id?: string;
-        advisor_name?: string;
         agent_groups?: string[];
         external_status?: string;
     };
     warnings?: ConversationWarning[];
 };
+/** The advisor to create or update with `upsertAdvisor()`. */
+type UpsertAdvisorInput = {
+    /** Email of the advisor. Identifies the advisor in your organization. */
+    advisorEmail: string;
+    firstName: string;
+    lastName: string;
+};
+/** Returned by `upsertAdvisor()`. */
+type UpsertAdvisorResult = {
+    /** Always `true` when the Promise resolves. */
+    success: boolean;
+    advisor: {
+        /** Pass it to `updateConversation({ advisorId })`. The email in lowercase. */
+        advisor_id: string;
+        /** The first name stored for this user. `null` only when the email belongs to an existing user who is not an advisor and has no name stored. */
+        first_name: string | null;
+        /** The last name stored for this user. `null` in the same case as `first_name`. */
+        last_name: string | null;
+        /** `true` when the advisor was created. `false` when a user in your organization already had this email: an advisor is updated, any other user is left unchanged. */
+        created: boolean;
+    };
+};
 declare enum ConversationLanguage {
     EN = "en",
     ES = "es",
@@ -211,7 +225,7 @@ type QuestionStatus = "searching" | "asked" | "not_asked";
  * `processing`.
  *
  *  - `processing`                     queued, or nothing to go on yet
- *  - `awaiting_question`              the agent hasn't asked the question yet
+ *  - `awaiting_question`              the advisor hasn't asked the question yet
  *  - `awaiting_answer`                asked, the customer hasn't answered yet
  *  - `partial`                        partial evidence so far (e.g. "305" of "30521")
  *  - `pending_confirmation_matched`   a matching answer is held briefly in case
@@ -256,7 +270,7 @@ interface AddFactResult {
     is_valid_answer: boolean;
     question_asked?: boolean;
     /**
-     * How closely the agent's utterance matched the expected question, on a 0–1
+     * How closely the advisor's utterance matched the expected question, on a 0–1
      * or a 0–100 scale. Higher is closer.
      */
     question_match_score?: number;
@@ -360,6 +374,12 @@ declare abstract class IAiqaSdk {
     abstract setConversationProduct(product: string): Promise<SetConversationProductResult>;
     abstract setConversationLanguage(language: ConversationLanguage): Promise<SetConversationLanguageResult>;
     abstract updateConversation(input: UpdateConversationInput): Promise<UpdateConversationResult>;
+    /**
+     * Creates an advisor in your organization, or updates the name of an existing
+     * advisor with the same email. A user with that email who is not an advisor is
+     * left unchanged. Rejects on invalid input.
+     */
+    abstract upsertAdvisor(input: UpsertAdvisorInput): Promise<UpsertAdvisorResult>;
 }
 
 declare class AiQaSdk implements IAiqaSdk {
@@ -384,6 +404,7 @@ declare class AiQaSdk implements IAiqaSdk {
     setConversationProduct(product: string): Promise<SetConversationProductResult>;
     setConversationLanguage(language: ConversationLanguage): Promise<SetConversationLanguageResult>;
     updateConversation(input: UpdateConversationInput): Promise<UpdateConversationResult>;
+    upsertAdvisor(input: UpsertAdvisorInput): Promise<UpsertAdvisorResult>;
     authenticate(): Promise<void>;
     startRecording(): Promise<boolean>;
     stopRecording(): Promise<boolean>;
@@ -393,4 +414,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 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 };
+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 UpsertAdvisorInput, type UpsertAdvisorResult, type Utterance, type VerificationStatus };

package/dist/browser/browser.js

@@ -3350,6 +3350,7 @@ var Methods = /* @__PURE__ */ ((Methods2) => {
   Methods2["SET_CONVERSATION_PRODUCT"] = "SET_CONVERSATION_PRODUCT";
   Methods2["SET_CONVERSATION_LANGUAGE"] = "SET_CONVERSATION_LANGUAGE";
   Methods2["UPDATE_CONVERSATION"] = "UPDATE_CONVERSATION";
+  Methods2["UPSERT_ADVISOR"] = "UPSERT_ADVISOR";
   return Methods2;
 })(Methods || {});
 var ExternalStatus = /* @__PURE__ */ ((ExternalStatus2) => {
@@ -3406,7 +3407,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "2.5.0-develop.1",
+  version: "3.0.0-develop.1",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3770,7 +3771,26 @@ var AiQaSdk = class {
     return result && result.data !== void 0 ? result.data : result;
   }
   async updateConversation(input) {
-    const result = await this.sendMessage("UPDATE_CONVERSATION" /* UPDATE_CONVERSATION */, input);
+    const { advisorId, advisorEmail, ...fields } = input;
+    const result = await this.sendMessage("UPDATE_CONVERSATION" /* UPDATE_CONVERSATION */, {
+      ...fields,
+      agentId: advisorId,
+      agentEmail: advisorEmail
+    });
+    const data = result && result.data !== void 0 ? result.data : result;
+    if (!data?.conversation || !("agent_id" in data.conversation)) {
+      return data;
+    }
+    const { agent_id, ...conversation } = data.conversation;
+    return { ...data, conversation: { ...conversation, advisor_id: agent_id } };
+  }
+  async upsertAdvisor(input) {
+    const { advisorEmail, firstName, lastName } = input;
+    const result = await this.sendMessage("UPSERT_ADVISOR" /* UPSERT_ADVISOR */, {
+      email: advisorEmail,
+      firstName,
+      lastName
+    });
     return result && result.data !== void 0 ? result.data : result;
   }
   async authenticate() {