@aiqa/sdk 2.0.0-develop.1 → 2.0.0-develop.3

package/README.md

@@ -19,6 +19,8 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [VerificationStatus](#verificationstatus)
   - [FactVerifiedPayload](#factverifiedpayload)
   - [FlagFactResult](#flagfactresult)
+  - [UpdateConversationInput](#updateconversationinput)
+  - [UpdateConversationResult](#updateconversationresult)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
 - [Semantic Versioning](#semantic-versioning)
@@ -130,6 +132,25 @@ const result = await sdk.setConversationLanguage(ConversationLanguage.EN);
 console.log(result.success, result.language);
 ```
 
+#### `updateConversation(input)`
+
+Updates fields on the current conversation. Pass only the fields you want to
+change.
+
+**Parameters:**
+
+- `input: UpdateConversationInput` - partial set of conversation fields to update
+  - `policyNumber?: string` - non-empty; surrounding whitespace is trimmed
+
+**Returns:**
+
+- `Promise<{ success: boolean; conversation: { policy_number?: string } }>`
+
+```typescript
+const result = await sdk.updateConversation({ policyNumber: "POL-123" });
+console.log(result.success, result.conversation.policy_number);
+```
+
 ### Fact Management
 
 #### `addFact(fact)`
@@ -144,7 +165,7 @@ while you wait.
 
 `addFact()` does not throw on verification failure — an unmatched
 fact resolves with `is_valid_answer: false` and (where the backend
-provides it) `verification_status: "unmatched"` or `"contradicted"`.
+provides it) `verification_status: "unmatched"`.
 Reject paths are reserved for transport / protocol errors.
 
 **Parameters:**
@@ -191,8 +212,7 @@ const result = await sdk.addFact({
 });
 
 if (result.is_valid_answer) {
-  // verification_status will be "matched" (or "contradicted" if the
-  // customer explicitly contradicted the expected answer).
+  // verification_status will be "matched".
   console.log("matched:", result.ai_answer);
 } else {
   // verification_status will be "unmatched". matched_components /
@@ -345,13 +365,13 @@ processing
                           (same, but for a held unmatched verdict)
                           │
                           ▼
-                    matched | unmatched | contradicted   ← terminal
+                    matched | unmatched   ← terminal
 ```
 
 Rules for consumers:
 
 - **`addFact()` resolves only on a terminal state** (`matched`,
-  `unmatched`, `contradicted`). Render progress from the
+  `unmatched`). Render progress from the
   `FACT_VERIFIED` event, render the final verdict from the Promise
   result.
 - **Treat unknown `verification_status` strings as `processing`.**
@@ -432,8 +452,8 @@ interface AddFactResult {
   answer_match_score?: number;
 
   /**
-   * Top-level state at terminal resolution. Always one of `matched`,
-   * `unmatched`, or `contradicted` because the `addFact()` Promise only
+   * Top-level state at terminal resolution. Always one of `matched`
+   * or `unmatched` because the `addFact()` Promise only
    * resolves on terminals. Optional during the rollout window for
    * backwards compatibility with older backends.
    */
@@ -463,8 +483,7 @@ type VerificationStatus =
   | "pending_confirmation_matched"
   | "pending_confirmation_unmatched"
   | "matched"
-  | "unmatched"
-  | "contradicted";
+  | "unmatched";
 ```
 
 The enum is additive: consumers that `switch` on this value MUST
@@ -566,6 +585,29 @@ enum ConversationLanguage {
 }
 ```
 
+### UpdateConversationInput
+
+Partial set of conversation fields accepted by `updateConversation()`.
+
+```typescript
+type UpdateConversationInput = {
+  policyNumber?: string;
+};
+```
+
+### UpdateConversationResult
+
+Returned by `updateConversation()`.
+
+```typescript
+type UpdateConversationResult = {
+  success: boolean;
+  conversation: {
+    policy_number?: string;
+  };
+};
+```
+
 ### FactUpdateEvent
 
 ```typescript

package/dist/browser/browser.d.ts

@@ -17,7 +17,8 @@ declare enum Methods {
     ADD_FACT = "ADD_FACT",
     FLAG_FACT = "FLAG_FACT",
     SET_CONVERSATION_PRODUCT = "SET_CONVERSATION_PRODUCT",
-    SET_CONVERSATION_LANGUAGE = "SET_CONVERSATION_LANGUAGE"
+    SET_CONVERSATION_LANGUAGE = "SET_CONVERSATION_LANGUAGE",
+    UPDATE_CONVERSATION = "UPDATE_CONVERSATION"
 }
 type SetConversationProductResult = {
     success: boolean;
@@ -27,6 +28,15 @@ type SetConversationLanguageResult = {
     success: boolean;
     language: string;
 };
+type UpdateConversationInput = {
+    policyNumber?: string;
+};
+type UpdateConversationResult = {
+    success: boolean;
+    conversation: {
+        policy_number?: string;
+    };
+};
 declare enum ConversationLanguage {
     EN = "en",
     ES = "es",
@@ -90,16 +100,15 @@ type QuestionStatus = "searching" | "asked" | "not_asked";
  *  - `pending_confirmation_matched`   backend has a matching answer but is
  *                                     holding a settling window for mid-answer
  *                                     clarifications (e.g. spellings, "I mean…");
- *                                     resolves to `matched`/`unmatched`/`contradicted`
+ *                                     resolves to `matched`/`unmatched`
  *  - `pending_confirmation_unmatched` same as above but the held verdict is
  *                                     `unmatched`; UI can show "we heard X but it
  *                                     doesn't match, waiting to confirm" instead
  *                                     of a hard red verdict
  *  - `matched`                        terminal: answer matched expected
  *  - `unmatched`                      terminal: budget exhausted with no match
- *  - `contradicted`                   terminal (future): customer contradicted expected
  */
-type VerificationStatus = "processing" | "awaiting_question" | "awaiting_answer" | "partial" | "pending_confirmation_matched" | "pending_confirmation_unmatched" | "matched" | "unmatched" | "contradicted";
+type VerificationStatus = "processing" | "awaiting_question" | "awaiting_answer" | "partial" | "pending_confirmation_matched" | "pending_confirmation_unmatched" | "matched" | "unmatched";
 type ApplicationFact = ApplicationFactInput & {
     ai_answer?: any;
     question_status: QuestionStatus;
@@ -133,8 +142,8 @@ interface AddFactResult {
     answer_match_score?: number;
     metadata?: Record<string, string>;
     /**
-     * Top-level state at terminal resolution. Always one of `matched`,
-     * `unmatched`, or `contradicted` because the `addFact()` Promise only
+     * Top-level state at terminal resolution. Always one of `matched`
+     * or `unmatched` because the `addFact()` Promise only
      * resolves on terminals. Optional during the rollout window for
      * backwards compatibility with older backends.
      */
@@ -154,7 +163,7 @@ interface AddFactResult {
  * Fires on EVERY state transition the verification queue produces —
  * non-terminal (`partial`, `awaiting_question`, `awaiting_answer`,
  * `pending_confirmation_matched`, `pending_confirmation_unmatched`,
- * `processing`) AND terminal (`matched`, `unmatched`, `contradicted`).
+ * `processing`) AND terminal (`matched`, `unmatched`).
  *
  * Subscribe with:
  *   sdk.on("FACT_VERIFIED", (payload: FactVerifiedPayload) => {...});
@@ -264,6 +273,7 @@ declare abstract class IAiqaSdk {
     abstract getFacts(): Promise<ApplicationFact[]>;
     abstract setConversationProduct(product: string): Promise<SetConversationProductResult>;
     abstract setConversationLanguage(language: ConversationLanguage): Promise<SetConversationLanguageResult>;
+    abstract updateConversation(input: UpdateConversationInput): Promise<UpdateConversationResult>;
 }
 
 declare class AiQaSdk implements IAiqaSdk {
@@ -275,6 +285,13 @@ declare class AiQaSdk implements IAiqaSdk {
     internalListeners: Map<SdkEvent, Set<(...args: any[]) => void>>;
     internalEvents: Set<SdkEvent>;
     private wrappersByEvent;
+    /**
+     * Trailing-debounce window (ms) applied per fact in {@link addFact}. Defaults
+     * to {@link ADD_FACT_DEBOUNCE_MS}; set to 0 to disable debouncing and send
+     * every call immediately.
+     */
+    addFactDebounceMs: number;
+    private pendingAddFacts;
     constructor(applicationId: string, applicationSecret: string, url?: string);
     on(name: SdkEvent, callback: (...args: any[]) => any): void;
     off(name: SdkEvent, callback?: (...args: any[]) => any): void;
@@ -284,9 +301,12 @@ declare class AiQaSdk implements IAiqaSdk {
     getApplication(): Promise<Application>;
     getFacts(): Promise<ApplicationFact[]>;
     addFact(fact: ApplicationFactInput): Promise<AddFactResult>;
+    private flushAddFact;
+    private sendAddFact;
     flagFact(factId: string): Promise<FlagFactResult>;
     setConversationProduct(product: string): Promise<SetConversationProductResult>;
     setConversationLanguage(language: ConversationLanguage): Promise<SetConversationLanguageResult>;
+    updateConversation(input: UpdateConversationInput): Promise<UpdateConversationResult>;
     authenticate(): Promise<void>;
     startRecording(): Promise<boolean>;
     stopRecording(): Promise<boolean>;
@@ -296,4 +316,4 @@ declare class AiQaSdk implements IAiqaSdk {
     private isManagerEvent;
 }
 
-export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, type DialogAct, type DialogActConfidence, FactAnswerFormatType, type FactVerifiedPayload, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type TranscriptionUpdate, type Utterance, type VerificationStatus };
+export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, type DialogAct, type DialogActConfidence, 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

@@ -3348,6 +3348,7 @@ var Methods = /* @__PURE__ */ ((Methods2) => {
   Methods2["FLAG_FACT"] = "FLAG_FACT";
   Methods2["SET_CONVERSATION_PRODUCT"] = "SET_CONVERSATION_PRODUCT";
   Methods2["SET_CONVERSATION_LANGUAGE"] = "SET_CONVERSATION_LANGUAGE";
+  Methods2["UPDATE_CONVERSATION"] = "UPDATE_CONVERSATION";
   return Methods2;
 })(Methods || {});
 var ConversationLanguage = /* @__PURE__ */ ((ConversationLanguage3) => {
@@ -3396,7 +3397,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "1.6.0-develop.1",
+  version: "2.0.0-develop.2",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3478,6 +3479,7 @@ var package_default = {
 var SDK_VERSION = package_default.version ?? "0.0.1";
 var DEFAULT_URL = "ws://localhost:3025/ws";
 var DEFAULT_TIMEOUT_MS = 6e4;
+var ADD_FACT_DEBOUNCE_MS = 500;
 var RUNTIME = typeof window !== "undefined" && typeof window.document !== "undefined" ? "browser" : "node";
 var USER_AGENT = RUNTIME === "browser" ? typeof navigator !== "undefined" ? navigator.userAgent : "browser/unknown" : typeof process !== "undefined" ? `node ${process.version} ${process.platform}` : "node/unknown";
 function isThenable(value2) {
@@ -3523,6 +3525,15 @@ var AiQaSdk = class {
     // same fn twice registers two wrappers and two off() calls clear
     // both.
     this.wrappersByEvent = /* @__PURE__ */ new Map();
+    /**
+     * Trailing-debounce window (ms) applied per fact in {@link addFact}. Defaults
+     * to {@link ADD_FACT_DEBOUNCE_MS}; set to 0 to disable debouncing and send
+     * every call immediately.
+     */
+    this.addFactDebounceMs = ADD_FACT_DEBOUNCE_MS;
+    // In-flight debounce state keyed by fact id: the pending timer, the latest
+    // payload to send when it fires, and every caller awaiting that send.
+    this.pendingAddFacts = /* @__PURE__ */ new Map();
     this.url = url2 ?? DEFAULT_URL;
     this.internalListeners = /* @__PURE__ */ new Map();
     this.internalEvents = /* @__PURE__ */ new Set(["authenticated"]);
@@ -3642,6 +3653,13 @@ var AiQaSdk = class {
       this.socket.disconnect();
     }
     this.wrappersByEvent.clear();
+    for (const entry of this.pendingAddFacts.values()) {
+      clearTimeout(entry.timer);
+      entry.waiters.forEach(
+        (w) => w.reject(new Error("Socket disconnected before addFact was sent"))
+      );
+    }
+    this.pendingAddFacts.clear();
   }
   sendMessage(method, data) {
     return new Promise((resolve, reject) => {
@@ -3691,7 +3709,40 @@ var AiQaSdk = class {
     const result = await this.sendMessage("GET_FACTS" /* GET_FACTS */);
     return result && result.data !== void 0 ? result.data : result;
   }
-  async addFact(fact) {
+  addFact(fact) {
+    if (this.addFactDebounceMs <= 0) {
+      return this.sendAddFact(fact);
+    }
+    const key = fact.questionId ?? fact.id;
+    return new Promise((resolve, reject) => {
+      const existing = this.pendingAddFacts.get(key);
+      if (existing) {
+        clearTimeout(existing.timer);
+        existing.latest = fact;
+        existing.waiters.push({ resolve, reject });
+        existing.timer = setTimeout(
+          () => this.flushAddFact(key),
+          this.addFactDebounceMs
+        );
+        return;
+      }
+      this.pendingAddFacts.set(key, {
+        latest: fact,
+        waiters: [{ resolve, reject }],
+        timer: setTimeout(() => this.flushAddFact(key), this.addFactDebounceMs)
+      });
+    });
+  }
+  flushAddFact(key) {
+    const entry = this.pendingAddFacts.get(key);
+    if (!entry) return;
+    this.pendingAddFacts.delete(key);
+    this.sendAddFact(entry.latest).then(
+      (result) => entry.waiters.forEach((w) => w.resolve(result)),
+      (error) => entry.waiters.forEach((w) => w.reject(error))
+    );
+  }
+  async sendAddFact(fact) {
     const payload = {
       ...fact,
       critical: fact.critical ?? false,
@@ -3734,6 +3785,10 @@ 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);
+    return result && result.data !== void 0 ? result.data : result;
+  }
   async authenticate() {
     try {
       const result = await this.sendMessage("AUTHENTICATE" /* AUTHENTICATE */, {