@aiqa/sdk 2.4.0-develop.1 → 2.4.0-develop.2

package/README.md

@@ -20,6 +20,7 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [ApplicationVerificationStatus](#applicationverificationstatus)
   - [ApplicationFact](#applicationfact)
   - [AddFactResult](#addfactresult)
+  - [FactWarning](#factwarning)
   - [VerificationStatus](#verificationstatus)
   - [FactVerifiedPayload](#factverifiedpayload)
   - [ApplicationFactInput](#applicationfactinput)
@@ -305,6 +306,8 @@ a timeout, a rejected payload.
 
 - `Promise<`[`AddFactResult`](#addfactresult)`>` — resolves once the fact
   reaches a final `verification_status`.
+  - `warnings`: present only when part of this `addFact()` was not applied.
+    See [`FactWarning`](#factwarning).
 
 **Parameters:**
 
@@ -348,6 +351,10 @@ const result = await sdk.addFact({
   metadata: { uiFieldId: "policy-agreement", section: "consent" },
 });
 
+for (const warning of result.warnings ?? []) {
+  console.warn(warning.code, warning.message);
+}
+
 if (result.is_valid_answer) {
   // verification_status, when present, is "matched".
   console.log("matched:", result.ai_answer);
@@ -681,10 +688,36 @@ interface AddFactResult {
   matched_components?: string[];
   missing_components?: string[];
 
+  // Present only when part of this addFact() was not applied.
+  warnings?: FactWarning[];
+
   metadata?: Record<string, string>;
 }
 ```
 
+### FactWarning
+
+Listed in `warnings` on the [`AddFactResult`](#addfactresult) returned by the
+`addFact()` call that caused them. `FACT_VERIFIED` events never include
+warnings, so read them from the `addFact()` result.
+
+```typescript
+interface FactWarning {
+  code: FactWarningCode;
+  message: string;
+}
+
+type FactWarningCode = "category_not_found" | (string & {});
+```
+
+| `code`               | meaning                                              | question's category | what to do                                                                            |
+| -------------------- | ---------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
+| `category_not_found` | there is no category with the `category_id` you sent | unchanged           | check the `category_id` and send it again with the next `addFact()` for this question |
+| 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 `category_id` you sent, and may change.
+- The rest of the fact is saved, and `addFact()` resolves as usual with its result.
+
 ### VerificationStatus
 
 ```typescript
@@ -707,7 +740,8 @@ which states are final.
 ### FactVerifiedPayload
 
 Payload of the `FACT_VERIFIED` event: which fact the update is about, its
-current state, and the full [`AddFactResult`](#addfactresult) shape in `data`.
+current state, and the [`AddFactResult`](#addfactresult) shape in `data`,
+without `warnings`.
 
 ```typescript
 interface FactVerifiedPayload {
@@ -718,8 +752,8 @@ interface FactVerifiedPayload {
   answer_match_score?: number;
   matched_components?: string[];
   missing_components?: string[];
-  /** Inner payload, same shape as AddFactResult. */
-  data?: AddFactResult;
+  /** Inner payload, same shape as AddFactResult without warnings. */
+  data?: Omit<AddFactResult, "warnings">;
   error?: string;
 }
 ```

package/dist/browser/browser.d.ts

@@ -232,6 +232,17 @@ type ApplicationFact = ApplicationFactInput & {
     /** True once `flagFact(factId)` has been called for this fact. */
     flagged: boolean;
 };
+/**
+ * Why part of an `addFact()` was not applied. Use it to choose what to do; do
+ * not parse `message`. Later versions may add codes: log `message` and
+ * continue. See "FactWarning" in the README.
+ */
+type FactWarningCode = "category_not_found" | (string & {});
+/** Part of an `addFact()` that was not applied. The rest of the fact is saved. */
+interface FactWarning {
+    code: FactWarningCode;
+    message: string;
+}
 interface AddFactResult {
     /** Conversation the fact was attached to. */
     conversation_id?: string;
@@ -267,6 +278,8 @@ interface AddFactResult {
      */
     matched_components?: string[];
     missing_components?: string[];
+    /** Present only when part of this `addFact()` was not applied. */
+    warnings?: FactWarning[];
 }
 /**
  * Payload of the `FACT_VERIFIED` event, which fires on every state change —
@@ -281,8 +294,8 @@ interface FactVerifiedPayload {
     answer_match_score?: number;
     matched_components?: string[];
     missing_components?: string[];
-    /** Inner payload, shaped like `AddFactResult`. */
-    data?: AddFactResult;
+    /** Inner payload, shaped like `AddFactResult` without `warnings`. */
+    data?: Omit<AddFactResult, "warnings">;
     error?: string;
 }
 type FlagFactResult = {
@@ -380,4 +393,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 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 Utterance, type VerificationStatus };

package/dist/browser/browser.js

@@ -3406,7 +3406,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "2.3.0-develop.2",
+  version: "2.4.0-develop.1",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3732,7 +3732,7 @@ var AiQaSdk = class {
     const result = await this.sendMessage("ADD_FACT" /* ADD_FACT */, payload);
     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;
+    const hasEnvelope = result.verification_status !== void 0 || result.matched_components !== void 0 || result.missing_components !== void 0 || result.warnings !== void 0;
     if (!hasEnvelope || typeof inner !== "object" || inner === null) {
       return inner;
     }
@@ -3746,6 +3746,9 @@ var AiQaSdk = class {
     if (result.missing_components !== void 0) {
       merged.missing_components = result.missing_components;
     }
+    if (result.warnings !== void 0) {
+      merged.warnings = result.warnings;
+    }
     return merged;
   }
   async flagFact(factId) {