@chat-ads/chatads-sdk 0.1.8 → 0.1.9

package/README.md

@@ -41,7 +41,6 @@ if (response.success && response.data?.Offers.length) {
 ```ts
 const result = await client.analyzeMessage("Need scheduling ideas", {
   country: "US",
-  message_analysis: "thorough",
 });
 ```
 
@@ -90,12 +89,12 @@ try {
 {
   "success": true,
   "data": {
+    "Status": "filled",
     "Offers": [
       {
         "LinkText": "CRM tools",
         "IntentLevel": "high",
         "URL": "https://amazon.com/dp/example?tag=chatads-20",
-        "Status": "filled",
         "Category": "Software"
       }
     ],

package/dist/client.js

@@ -6,19 +6,11 @@ const DEFAULT_BACKOFF_FACTOR = 500; // ms
 const DEFAULT_RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 /**
  * Field aliases for normalizing optional field names.
- * Only includes the 7 optional fields from the OpenAPI spec.
+ * Only includes the 3 optional fields from the OpenAPI spec.
  */
 const FIELD_ALIASES = {
-    messageanalysis: "message_analysis",
-    message_analysis: "message_analysis",
-    fillpriority: "fill_priority",
-    fill_priority: "fill_priority",
-    minintent: "min_intent",
-    min_intent: "min_intent",
-    skipmessageanalysis: "skip_message_analysis",
-    skip_message_analysis: "skip_message_analysis",
-    maxoffers: "max_offers",
-    max_offers: "max_offers",
+    fillpriority: "quality",
+    quality: "quality",
 };
 export class ChatAdsClient {
     constructor(options) {
@@ -76,7 +68,7 @@ export class ChatAdsClient {
                 });
                 const parsed = await parseResponse(response);
                 const httpError = !response.ok;
-                const logicalError = this.raiseOnFailure && parsed.success === false;
+                const logicalError = this.raiseOnFailure && parsed.error != null;
                 if (!httpError && !logicalError) {
                     clearTimeout(timer);
                     return parsed;
@@ -181,7 +173,21 @@ function normalizeOptionalFields(data) {
 async function parseResponse(response) {
     const text = await response.text();
     try {
-        return text ? JSON.parse(text) : { success: false, meta: { request_id: "unknown" } };
+        const raw = text ? JSON.parse(text) : {};
+        // Normalize null/undefined to empty defaults so devs don't need null checks
+        const data = raw.data ?? { offers: [], requested: 0, returned: 0 };
+        return {
+            data: {
+                status: data.status,
+                offers: data.offers ?? [],
+                requested: data.requested ?? 0,
+                returned: data.returned ?? 0,
+                extraction_source: data.extraction_source,
+                extraction_debug: data.extraction_debug,
+            },
+            error: raw.error,
+            meta: raw.meta ?? { request_id: "unknown" },
+        };
     }
     catch (error) {
         throw new ChatAdsSDKError("Failed to parse ChatAds response as JSON", error);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { ChatAdsClient } from "./client.js";
 export { ChatAdsAPIError, ChatAdsSDKError } from "./errors.js";
 export type { ChatAdsClientOptions, AnalyzeOptions, AnalyzeMessageOptions, } from "./client.js";
-export type { ChatAdsResponseEnvelope, Offer, Product, AnalyzeData, ChatAdsError, ChatAdsMeta, UsageInfo, FunctionItemPayload, FunctionItemOptionalFields, MessageAnalysis, FillPriority, MinIntent, IntentLevel, OfferStatus, UrlSource, } from "./models.js";
+export type { ChatAdsResponseEnvelope, Offer, Product, AnalyzeData, ChatAdsError, ChatAdsMeta, UsageInfo, FunctionItemPayload, FunctionItemOptionalFields, Quality, ConfidenceLevel, ResponseStatus, ResolutionSource, } from "./models.js";

package/dist/models.d.ts

@@ -1,28 +1,19 @@
-export type MessageAnalysis = "fast" | "thorough";
-export type FillPriority = "speed" | "coverage";
-export type MinIntent = "any" | "low" | "medium" | "high";
-export type IntentLevel = "high" | "medium" | "low" | "very_low";
-export type OfferStatus = "filled" | "scored" | "failed";
-export type UrlSource = "demo" | "serper" | "amazon_paapi" | "cache";
+export type Quality = "fast" | "standard" | "best";
+export type ConfidenceLevel = "high" | "medium" | "low" | "very_low";
+export type ResolutionSource = "demo" | "serper" | "amazon_paapi" | "cache" | "vector";
+/** Top-level response status indicating the outcome of the request */
+export type ResponseStatus = "filled" | "partial_fill" | "no_offers_found" | "internal_error";
 /**
  * Optional fields for ChatAds API requests.
- * Only these 7 optional fields are supported (plus required `message`).
+ * Only these 3 optional fields are supported (plus required `message`).
  */
 export type FunctionItemOptionalFields = {
     /** Client IP address for geo-detection (max 45 characters) */
     ip?: string;
     /** ISO 3166-1 alpha-2 country code for geo-targeting */
     country?: string;
-    /** Keyword extraction method. Default: "thorough" */
-    message_analysis?: MessageAnalysis;
-    /** URL resolution fallback behavior. Default: "coverage" */
-    fill_priority?: FillPriority;
-    /** Minimum purchase intent level. Default: "low" */
-    min_intent?: MinIntent;
-    /** Skip NLP/LLM extraction and use message directly as search query. Default: false */
-    skip_message_analysis?: boolean;
-    /** Maximum number of affiliate offers to return (1-2). Default: 1 */
-    max_offers?: number;
+    /** Resolution quality level. Default: "standard" */
+    quality?: Quality;
 };
 export type FunctionItemPayload = {
     message: string;
@@ -33,51 +24,52 @@ export type FunctionItemPayload = {
  */
 export interface Product {
     /** Product title from search result */
-    Title?: string;
+    title?: string;
     /** Product description/snippet from search result */
-    Description?: string;
+    description?: string;
+    /** Product rating (e.g., 4.5 out of 5) */
+    stars?: number;
+    /** Number of product reviews */
+    reviews?: number;
 }
 /**
  * Single affiliate offer returned by the API.
+ * If an offer is in the array, it is guaranteed to have a URL.
  */
 export interface Offer {
     /** Text to use for the affiliate link */
-    LinkText: string;
-    /** Product search term used */
-    SearchTerm?: string;
-    /** Intent score (0.0-1.0) */
-    IntentScore?: number | null;
-    /** Intent level classification */
-    IntentLevel: string;
-    /** Affiliate URL */
-    URL: string;
-    /** Source of the URL (e.g., amazon, serper) */
-    URLSource?: string;
-    /** Offer status */
-    Status: OfferStatus;
-    /** Reason for status (e.g., failure reason) */
-    Reason?: string;
+    link_text: string;
+    /** Product search term used (verbose mode only) */
+    search_term?: string;
+    /** Confidence score (0.0-1.0) (verbose mode only) */
+    confidence_score?: number | null;
+    /** Confidence level classification */
+    confidence_level: string;
+    /** Affiliate URL (always populated) */
+    url: string;
+    /** Source of the URL resolution (e.g., amazon, serper, vector) (verbose mode only) */
+    resolution_source?: string;
     /** Detected product category */
-    Category?: string;
+    category?: string;
     /** Product metadata from resolution */
-    Product?: Product;
+    product?: Product;
 }
 /**
  * Response data containing affiliate offers.
  */
 export interface AnalyzeData {
-    /** Array of affiliate offers */
-    Offers: Offer[];
+    /** Status of the request - single source of truth for outcome */
+    status: ResponseStatus;
+    /** Array of affiliate offers (only contains filled offers with URLs, never null) */
+    offers: Offer[];
     /** Number of offers requested */
-    Requested: number;
-    /** Number of offers returned */
-    Returned: number;
-    /** Total processing latency in milliseconds */
-    LatencyMs?: number;
-    /** LLM extraction step timing */
-    ExtractionMs?: number;
-    /** Affiliate URL lookup timing */
-    LookupMs?: number;
+    requested: number;
+    /** Number of offers returned (equals len(Offers)) */
+    returned: number;
+    /** Extraction source ("nlp", "groq_vector", "groq_resolved") (verbose mode only) */
+    extraction_source?: string;
+    /** Extraction debug information (verbose mode only) */
+    extraction_debug?: unknown[];
 }
 export interface ChatAdsError {
     code: string;
@@ -102,14 +94,13 @@ export interface ChatAdsMeta {
     [key: string]: unknown;
 }
 export interface ChatAdsResponseEnvelope {
-    success: boolean;
-    data?: AnalyzeData | null;
+    data: AnalyzeData;
     error?: ChatAdsError | null;
     meta: ChatAdsMeta;
     [key: string]: unknown;
 }
 /**
  * Reserved payload keys that cannot be used in extraFields.
- * These are the 8 allowed request fields per the OpenAPI spec.
+ * These are the 4 allowed request fields per the OpenAPI spec.
  */
 export declare const RESERVED_PAYLOAD_KEYS: ReadonlySet<string>;

package/dist/models.js

@@ -1,14 +1,10 @@
 /**
  * Reserved payload keys that cannot be used in extraFields.
- * These are the 8 allowed request fields per the OpenAPI spec.
+ * These are the 4 allowed request fields per the OpenAPI spec.
  */
 export const RESERVED_PAYLOAD_KEYS = new Set([
     "message",
     "ip",
     "country",
-    "message_analysis",
-    "fill_priority",
-    "min_intent",
-    "skip_message_analysis",
-    "max_offers",
+    "quality",
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chat-ads/chatads-sdk",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "TypeScript/JavaScript client for the ChatAds prospect scoring API",
   "license": "MIT",
   "type": "module",