@aiqa/sdk 1.3.0 → 1.4.0-develop.2

package/README.md

@@ -138,6 +138,16 @@ Adds a fact to the active application (Promise-based).
   ```typescript
   {
     id: string;
+    /**
+     * Optional. Stable identifier for the underlying question, shared across
+     * applications and conversations. When provided it is used to look up (or
+     * create) the matching question row in the database instead of `id`. When
+     * omitted, `id` is used (legacy behavior).
+     *
+     * Keep this consistent across calls for the "same" question — see
+     * "Question identity and questionId" below.
+     */
+    questionId?: string;
     question: string;
     expected_answer: any;
     answer_format: { type: "STRING" }
@@ -158,6 +168,7 @@ Adds a fact to the active application (Promise-based).
 ```typescript
 const isMatched = await sdk.addFact({
   id: "fact-123",
+  questionId: "agreement-q",
   question: "Do you agree?",
   expected_answer: "Yes",
   answer_format: { type: "STRING" },
@@ -165,6 +176,37 @@ const isMatched = await sdk.addFact({
 });
 ```
 
+##### Question identity and `questionId`
+
+`id` identifies an instance of a fact within a single conversation. `questionId`
+is an optional field that identifies the underlying question across every
+application and conversation that asks it. They're separated so you can give
+each fact instance its own `id` (e.g. a per-call uuid) while still pointing at a
+stable question identity.
+
+Two server-side features are scoped per question identity:
+
+- **Accuracy improvements.** Per-question signals (flags, model tweaks, fuzzy
+  matches) accumulate against the question row. Splitting the same logical
+  question across multiple identities splits these signals and resets the
+  accuracy gains you've already earned.
+- **Remaps from the management dashboard.** When an operator remaps a question
+  in the dashboard, the remap is stored on the question row. A subsequent call
+  with a different identity won't pick up the remap.
+
+The "question identity" the server uses is `questionId` if you sent one,
+otherwise `id`. So:
+
+- If your `id` is already stable across calls for the same logical question,
+  omitting `questionId` is fine — both features above still work, just keyed off
+  `id`.
+- If your `id` varies per call (per-call uuid, ephemeral instance id, etc.),
+  send a stable `questionId`. Otherwise each call looks like a new question and
+  you lose the features above.
+- Once you've picked an identity for a question, don't change it. If you must
+  rename, coordinate with the team owning the dashboard so remaps and
+  historical signals can be migrated.
+
 #### `getFacts()`
 
 Retrieves all facts for the application (Promise-based). Each fact includes a `metadata` field containing whatever was passed to `addFact()`. Facts added without `metadata` return `{}`.
@@ -289,6 +331,16 @@ type ApplicationFact = ApplicationFactInput & {
 ```typescript
 type ApplicationFactInput = {
   id: string;
+  /**
+   * Optional. Stable identifier for the underlying question, shared across
+   * applications and conversations. Used to look up (or create) the matching
+   * question row in the database when provided. When omitted, `id` is used.
+   *
+   * Keep this consistent across calls — accuracy improvements and remaps
+   * configured in the management dashboard are scoped per `questionId`. See
+   * "Question identity and questionId" under `addFact()`.
+   */
+  questionId?: string;
   question: string;
   expected_answer: any;
   answer_format: {

package/dist/browser/browser.d.ts

@@ -32,7 +32,7 @@ declare enum ConversationLanguage {
     ES = "es",
     FR = "fr"
 }
-type SdkEvent = Methods | "connect" | "disconnect" | "close" | "error" | "reconnect_attempt" | "reconnect_error" | "reconnect_failed" | "authenticated" | "app_version";
+type SdkEvent = Methods | "connect" | "disconnect" | "close" | "error" | "reconnect_attempt" | "reconnect_error" | "reconnect_failed" | "authenticated" | "app_version" | "fact_verified";
 declare enum FactAnswerFormatType {
     string = "STRING",
     number = "NUMBER",
@@ -54,6 +54,14 @@ type ApplicationFactAnswerFormat = {
 };
 type ApplicationFactInput = {
     id: string;
+    /**
+     * Stable identifier for the underlying question, shared across applications and
+     * conversations. When provided it is used to look up (or create) the matching
+     * question row in the database instead of `id`. Keep this consistent across
+     * calls — accuracy improvements and remaps configured in the management
+     * dashboard are scoped per `questionId`.
+     */
+    questionId?: string;
     question: string;
     expected_answer: any;
     answer_format: ApplicationFactAnswerFormat;
@@ -65,7 +73,25 @@ type ApplicationFactInput = {
     metadata?: Record<string, string>;
 };
 type QuestionStatus = "searching" | "asked" | "not_asked";
-type VerificationStatus = "processing" | "matched" | "unmatched";
+/**
+ * Per-fact verification state.
+ *
+ * Extended from the original three-state shape to carry progress signals
+ * the backend already detects but previously could not express. Consumers
+ * that switch on this value MUST treat unknown strings as "processing"
+ * (default fall-through) so older SDK builds keep working after the
+ * backend starts emitting the additive states.
+ *
+ * Semantics:
+ *  - `processing`        generic, just queued or transcription not ready
+ *  - `awaiting_question` agent hasn't asked the question yet
+ *  - `awaiting_answer`   question asked, customer hasn't answered yet
+ *  - `partial`           partial evidence; backend still working on it
+ *  - `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" | "matched" | "unmatched" | "contradicted";
 type ApplicationFact = ApplicationFactInput & {
     ai_answer?: any;
     question_status: QuestionStatus;
@@ -76,7 +102,65 @@ interface AddFactResult {
     ai_answer?: string;
     is_valid_answer: boolean;
     question_asked?: boolean;
+    /**
+     * 0–1 (or 0–100 — scale matches the configured similarity method).
+     * Similarity between the agent's utterance and the expected question.
+     * Renamed from `match_score` to disambiguate from the answer-side score.
+     */
+    question_match_score?: number;
+    /**
+     * 0–1 score derived from how well the customer's answer matched expected.
+     * Populated by the verification queue from partial-match heuristics
+     * (numeric-prefix ratio, matched-components ratio). Undefined when no
+     * partial signal exists or for terminal results before this rolls out.
+     */
+    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
+     * resolves on terminals. Optional during the rollout window for
+     * backwards compatibility with older backends.
+     */
+    verification_status?: VerificationStatus;
+    /**
+     * Per-fact partial-match breakdown carried through from the
+     * verification queue's component-wise comparators. For numeric-prefix
+     * facts these are `["prefix"]` / `["suffix"]`; future work will
+     * generalise to addresses, names, dates, etc.
+     */
+    matched_components?: string[];
+    missing_components?: string[];
+}
+/**
+ * Payload of the `fact_verified` broadcast event.
+ *
+ * Fires on EVERY state transition the verification queue produces —
+ * partial (`partial`, `awaiting_question`, `awaiting_answer`,
+ * `processing`) AND terminal (`matched`, `unmatched`, `contradicted`).
+ *
+ * Subscribe with:
+ *   sdk.on("fact_verified", (payload: FactVerifiedPayload) => {...});
+ *
+ * `addFact()`'s Promise resolves only on terminals; this event stream
+ * is the channel for rendering live progress in the agent UI.
+ */
+interface FactVerifiedPayload {
+    factId: string;
+    success: boolean;
+    verification_status?: VerificationStatus;
+    question_match_score?: number;
+    answer_match_score?: number;
+    matched_components?: string[];
+    missing_components?: string[];
+    /**
+     * Inner data payload. Shape matches `AddFactResult` (minus the
+     * top-level envelope fields) so consumers can reuse the same
+     * rendering code for the terminal addFact() resolution and the
+     * broadcast event.
+     */
+    data?: AddFactResult;
+    error?: string;
 }
 type FlagFactResult = {
     success: boolean;
@@ -128,4 +212,4 @@ declare class AiQaSdk implements IAiqaSdk {
     private isManagerEvent;
 }
 
-export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, FactAnswerFormatType, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type VerificationStatus };
+export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, FactAnswerFormatType, type FactVerifiedPayload, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type VerificationStatus };

package/dist/browser/browser.js

@@ -3396,7 +3396,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "1.2.0",
+  version: "1.4.0-develop.1",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3599,7 +3599,7 @@ var AiQaSdk = class {
           reject(parsed.error);
           return;
         }
-        resolve(parsed && parsed.data !== void 0 ? parsed.data : parsed);
+        resolve(parsed);
       };
       this.socket.on(requestId, handler);
       const payload = data && typeof data === "object" ? { ...data, requestId } : { requestId, data };
@@ -3629,7 +3629,23 @@ var AiQaSdk = class {
       is_skipped: fact.is_skipped ?? false
     };
     const result = await this.sendMessage("ADD_FACT" /* ADD_FACT */, payload);
-    return result && result.data !== void 0 ? result.data : result;
+    if (!result) return result;
+    const inner = result.data !== void 0 ? result.data : result;
+    const hasEnvelope = result.verification_status !== void 0 || result.matched_components !== void 0 || result.missing_components !== void 0;
+    if (!hasEnvelope || typeof inner !== "object" || inner === null) {
+      return inner;
+    }
+    const merged = { ...inner };
+    if (result.verification_status !== void 0) {
+      merged.verification_status = result.verification_status;
+    }
+    if (result.matched_components !== void 0) {
+      merged.matched_components = result.matched_components;
+    }
+    if (result.missing_components !== void 0) {
+      merged.missing_components = result.missing_components;
+    }
+    return merged;
   }
   async flagFact(factId) {
     const result = await this.sendMessage("FLAG_FACT" /* FLAG_FACT */, {