@aiqa/sdk 1.2.0 → 1.4.0-develop.1

package/README.md

@@ -14,6 +14,7 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [Fact Management](#fact-management)
   - [Event Handling](#event-handling)
 - [Types](#types)
+  - [FlagFactResult](#flagfactresult)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
 - [Semantic Versioning](#semantic-versioning)
@@ -137,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" }
@@ -157,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" },
@@ -164,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 `{}`.
@@ -175,6 +218,23 @@ facts.forEach((fact) => {
 });
 ```
 
+#### `flagFact(factId)`
+
+Flags a fact for human review. Creates a signal that allow AIQA to improve review quality.
+
+**Parameters:**
+
+- `factId: string` - the `id` of the fact to flag (must match the `id` used in `addFact()`)
+
+**Returns:**
+
+- `Promise<FlagFactResult>` — `{ success: boolean }`
+
+```typescript
+const result = await sdk.flagFact("fact-123");
+console.log(result.success); // true
+```
+
 ### Recording Management
 
 #### `startRecording()`
@@ -271,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: {
@@ -309,6 +379,16 @@ type ApplicationFactInput = {
 };
 ```
 
+### FlagFactResult
+
+Returned by `flagFact()`.
+
+```typescript
+type FlagFactResult = {
+  success: boolean;
+};
+```
+
 ### ConversationLanguage
 
 ```typescript

package/dist/browser/browser.d.ts

@@ -15,6 +15,7 @@ declare enum Methods {
     STOP_RECORDING = "STOP_RECORDING",
     IS_RECORDING = "IS_RECORDING",
     ADD_FACT = "ADD_FACT",
+    FLAG_FACT = "FLAG_FACT",
     SET_CONVERSATION_PRODUCT = "SET_CONVERSATION_PRODUCT",
     SET_CONVERSATION_LANGUAGE = "SET_CONVERSATION_LANGUAGE"
 }
@@ -53,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;
@@ -75,7 +84,11 @@ interface AddFactResult {
     ai_answer?: string;
     is_valid_answer: boolean;
     question_asked?: boolean;
+    metadata?: Record<string, string>;
 }
+type FlagFactResult = {
+    success: boolean;
+};
 type SdkError = {
     code: "INVALID_CONFIG" | "CONNECTION_ERROR" | "TIMEOUT" | "SERVER_ERROR" | "UNEXPECTED_RESPONSE";
     message: string;
@@ -88,6 +101,7 @@ declare abstract class IAiqaSdk {
     abstract off(eventName: string): void;
     abstract getApplication(): Promise<Application>;
     abstract addFact(fact: ApplicationFactInput): Promise<AddFactResult>;
+    abstract flagFact(factId: string): Promise<FlagFactResult>;
     abstract getFacts(): Promise<ApplicationFact[]>;
     abstract setConversationProduct(product: string): Promise<SetConversationProductResult>;
     abstract setConversationLanguage(language: ConversationLanguage): Promise<SetConversationLanguageResult>;
@@ -110,6 +124,7 @@ declare class AiQaSdk implements IAiqaSdk {
     getApplication(): Promise<Application>;
     getFacts(): Promise<ApplicationFact[]>;
     addFact(fact: ApplicationFactInput): Promise<AddFactResult>;
+    flagFact(factId: string): Promise<FlagFactResult>;
     setConversationProduct(product: string): Promise<SetConversationProductResult>;
     setConversationLanguage(language: ConversationLanguage): Promise<SetConversationLanguageResult>;
     authenticate(): Promise<void>;
@@ -121,4 +136,4 @@ declare class AiQaSdk implements IAiqaSdk {
     private isManagerEvent;
 }
 
-export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, FactAnswerFormatType, 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 FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type VerificationStatus };

package/dist/browser/browser.js

@@ -3345,6 +3345,7 @@ var Methods = /* @__PURE__ */ ((Methods2) => {
   Methods2["STOP_RECORDING"] = "STOP_RECORDING";
   Methods2["IS_RECORDING"] = "IS_RECORDING";
   Methods2["ADD_FACT"] = "ADD_FACT";
+  Methods2["FLAG_FACT"] = "FLAG_FACT";
   Methods2["SET_CONVERSATION_PRODUCT"] = "SET_CONVERSATION_PRODUCT";
   Methods2["SET_CONVERSATION_LANGUAGE"] = "SET_CONVERSATION_LANGUAGE";
   return Methods2;
@@ -3395,7 +3396,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "1.1.0-develop.1",
+  version: "1.3.0",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3630,6 +3631,12 @@ var AiQaSdk = class {
     const result = await this.sendMessage("ADD_FACT" /* ADD_FACT */, payload);
     return result && result.data !== void 0 ? result.data : result;
   }
+  async flagFact(factId) {
+    const result = await this.sendMessage("FLAG_FACT" /* FLAG_FACT */, {
+      factId
+    });
+    return result && result.data !== void 0 ? result.data : result;
+  }
   async setConversationProduct(product) {
     const result = await this.sendMessage("SET_CONVERSATION_PRODUCT" /* SET_CONVERSATION_PRODUCT */, {
       product