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

package/README.md

@@ -165,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:**
@@ -212,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 /
@@ -366,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`.**
@@ -453,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.
    */
@@ -484,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

package/dist/browser/browser.d.ts

@@ -100,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;
@@ -143,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.
      */
@@ -164,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) => {...});
@@ -286,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;
@@ -295,6 +301,8 @@ 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>;

package/dist/browser/browser.js

@@ -3397,7 +3397,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "2.0.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",
@@ -3479,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) {
@@ -3524,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"]);
@@ -3643,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) => {
@@ -3692,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,