@aiqa/sdk 3.0.0 → 3.1.0

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)`
@@ -883,15 +921,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",
@@ -351,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 {
@@ -375,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>;
@@ -384,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: "3.0.0-develop.1",
+  version: "3.0.0-develop.2",
   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 */, {