@aiqa/sdk 3.0.0 → 3.1.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)
@@ -281,6 +283,42 @@ 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. Then link the call to the advisor with
+`updateConversation({ advisorEmail })`, passing the same email, or with
+`updateConversation({ advisorId })`, passing the returned `advisor_id`.
+
+**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 link the call to it with `advisorEmail` or `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({ advisorEmail: "advisor@example.com" });
+// or: await sdk.updateConversation({ advisorId: result.advisor.advisor_id });
+```
+
 ### Fact Management
 
 #### `addFact(fact)`
@@ -325,6 +363,13 @@ a timeout, a rejected payload.
     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. Use `true` for a value you already know is correct, such as data
+     * from your own records. Unlike `prefilled`, it is about trusting the value, not
+     * when it was collected. It is stored and visible to whoever reviews the call,
+     * never verified, and left out of the verification summary counts.
+     */
+    reference?: 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
@@ -541,6 +586,12 @@ Rules:
 - **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.
+- **A fact sent with `reference: true` is never verified either.** Use it for
+  a value you already know is correct, such as the plan name from your own
+  records. It is stored, visible to whoever reviews the call, and left out of
+  the verification summary counts. `addFact()` still resolves, with
+  `is_valid_answer: false` and no `verification_status`, and no `FACT_VERIFIED`
+  event is emitted for it.
 - **`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
@@ -791,6 +842,13 @@ type ApplicationFactInput = {
   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. Use `true` for a value you already know is correct, such as data
+   * from your own records. Unlike `prefilled`, it is about trusting the value, not
+   * when it was collected. It is stored and visible to whoever reviews the call,
+   * never verified, and left out of the verification summary counts.
+   */
+  reference?: 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.
@@ -883,15 +941,43 @@ type ConversationWarningCode =
   | (string & {});
 ```
 
-| `code`                       | meaning                                                           | conversation's advisor | what to do                                         |
-| ---------------------------- | ----------------------------------------------------------------- | ---------------------- | -------------------------------------------------- |
-| `advisor_not_found`          | no AIQA user in your organization has the `advisorEmail`          | unchanged              | check the email                                    |
-| `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                         |
+| `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

@@ -82,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;
@@ -137,6 +138,28 @@ type UpdateConversationResult = {
     };
     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",
@@ -185,6 +208,13 @@ type ApplicationFactInput = {
     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. Use `true` for a value you already know is correct, such as data
+     * from your own records. Unlike `prefilled`, it is about trusting the value, not
+     * when it was collected. It is stored and visible to whoever reviews the call,
+     * never verified, and left out of the verification summary counts.
+     */
+    reference?: 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.
@@ -243,7 +273,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. */
+    /** `false` for a fact that was never verified, such as a prefilled or reference one. */
     is_valid_answer: boolean;
     question_asked?: boolean;
     /**
@@ -351,6 +381,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 {
@@ -375,6 +411,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>;
@@ -384,4 +421,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: "3.0.0-develop.1",
+  version: "3.1.0-develop.1",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3783,6 +3784,15 @@ var AiQaSdk = class {
     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() {
     try {
       const result = await this.sendMessage("AUTHENTICATE" /* AUTHENTICATE */, {