@chat-ads/chatads-sdk 0.1.12 → 0.1.14

package/README.md

@@ -44,6 +44,15 @@ const result = await client.analyzeMessage("Need scheduling ideas", {
 });
 ```
 
+### Image search
+
+```ts
+const result = await client.analyze({
+  message: "https://example.com/product-image.jpg",
+  input_type: "image_url",
+});
+```
+
 - Reserved payload keys (like `message`, `country`, etc.) cannot be overwritten inside `extraFields`; the client throws if it detects a collision.
 - Pass `raiseOnFailure: true` to throw `ChatAdsAPIError` when the API returns an error with HTTP 200 responses.
 - Retries honor `Retry-After` headers and exponential backoff (`maxRetries` + `retryBackoffFactorMs`).

package/dist/client.js

@@ -4,14 +4,6 @@ const DEFAULT_ENDPOINT = "/v1/chatads/messages";
 const DEFAULT_TIMEOUT_MS = 10000;
 const DEFAULT_BACKOFF_FACTOR = 500; // ms
 const DEFAULT_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
-/**
- * Field aliases for normalizing optional field names.
- * Only includes the 3 optional fields from the OpenAPI spec.
- */
-const FIELD_ALIASES = {
-    fillpriority: "quality",
-    quality: "quality",
-};
 export class ChatAdsClient {
     constructor(options) {
         if (!options?.apiKey) {
@@ -167,8 +159,7 @@ function normalizeOptionalFields(data) {
         if (key === "extraFields") {
             continue;
         }
-        const aliasKey = FIELD_ALIASES[key.toLowerCase()] ?? key;
-        normalized[aliasKey] = value;
+        normalized[key] = value;
     }
     return normalized;
 }
@@ -179,14 +170,17 @@ async function parseResponse(response) {
         // Normalize null/undefined to empty defaults so devs don't need null checks
         const data = raw.data ?? { offers: [], requested: 0, returned: 0 };
         return {
+            ...raw,
             data: {
                 status: data.status,
                 offers: data.offers ?? [],
                 requested: data.requested ?? 0,
                 returned: data.returned ?? 0,
+                billed: data.billed ?? false,
                 extraction_source: data.extraction_source,
                 extraction_debug: data.extraction_debug,
                 resolution_debug: data.resolution_debug,
+                input_type: data.input_type,
             },
             error: raw.error,
             meta: raw.meta ?? { request_id: "unknown" },

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, Quality, ResponseStatus, } from "./models.js";
+export type { ChatAdsResponseEnvelope, Offer, Product, AnalyzeData, ChatAdsError, ChatAdsMeta, UsageInfo, FunctionItemPayload, FunctionItemOptionalFields, ResponseStatus, } from "./models.js";

package/dist/models.d.ts

@@ -1,17 +1,23 @@
-export type Quality = "fast" | "standard" | "best";
+export type ExtractionMode = "none" | "fast" | "standard";
+export type ResolutionMode = "none" | "fast" | "standard";
 /** Top-level response status indicating the outcome of the request */
-export type ResponseStatus = "filled" | "partial_fill" | "no_offers_found" | "internal_error";
+export type ResponseStatus = "filled" | "partial_fill" | "no_offer" | "message_too_short" | "message_too_long" | "country_not_allowed" | "blocked_keyword" | "language_not_allowed" | "ip_country_not_allowed";
 /**
  * Optional fields for ChatAds API requests.
- * 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;
-    /** Resolution quality level. Default: "standard" */
-    quality?: Quality;
+    /** Content type of the input message. Default: "text" */
+    input_type?: "text" | "image_url" | "image_file";
+    /** Extraction control: "none" (bring your own product), "fast" (NLP only), "standard" (default). Default: "standard" */
+    extraction_mode?: ExtractionMode;
+    /** Resolution control: "none" (extraction only), "fast" (vector only), "standard" (default). Default: "standard" */
+    resolution_mode?: ResolutionMode;
+    /** Filter image search results by title keyword (image input_type only) */
+    image_title_filter?: string;
 };
 export type FunctionItemPayload = {
     message: string;
@@ -29,10 +35,12 @@ export interface Product {
     stars?: number;
     /** Number of product reviews */
     reviews?: number;
+    /** Product image URL (image input_type only) */
+    image?: string;
 }
 /**
  * Single affiliate offer returned by the API.
- * If an offer is in the array, it is guaranteed to have a URL.
+ * URL is populated for resolved offers but may be empty in extraction-only mode (resolution_mode=none).
  */
 export interface Offer {
     /** Text to use for the affiliate link */
@@ -43,12 +51,14 @@ export interface Offer {
     confidence_score?: number | null;
     /** Confidence level classification (verbose mode only) */
     confidence_level?: string;
-    /** Affiliate URL (always populated) */
-    url: string;
+    /** Affiliate URL — empty when resolution_mode=none */
+    url?: string;
     /** Source of the URL resolution (e.g., amazon, serper, vector) (verbose mode only) */
     resolution_source?: string;
     /** Product metadata from resolution */
     product?: Product;
+    /** Source retailer name (image input_type only) */
+    offer_source?: string;
 }
 /**
  * Response data containing affiliate offers.
@@ -56,18 +66,22 @@ export interface Offer {
 export interface AnalyzeData {
     /** Status of the request - single source of truth for outcome */
     status: ResponseStatus;
-    /** Array of affiliate offers (only contains filled offers with URLs, never null) */
+    /** Array of affiliate offers (URL may be absent in extraction-only mode, never null) */
     offers: Offer[];
     /** Number of offers requested */
     requested: number;
     /** Number of offers returned (equals len(Offers)) */
     returned: number;
+    /** Whether this request was billed */
+    billed: boolean;
     /** Extraction source ("nlp", "groq_vector", "groq_resolved") (verbose mode only) */
     extraction_source?: string;
     /** Extraction debug information (verbose mode only) */
     extraction_debug?: unknown[];
     /** Resolution debug information (verbose mode only) */
     resolution_debug?: unknown[];
+    /** Request input type (verbose mode only) */
+    input_type?: string;
 }
 export interface ChatAdsError {
     code: string;
@@ -99,6 +113,6 @@ export interface ChatAdsResponseEnvelope {
 }
 /**
  * Reserved payload keys that cannot be used in extraFields.
- * These are the 4 allowed request fields per the OpenAPI spec.
+ * These are the allowed request fields per the OpenAPI spec.
  */
 export declare const RESERVED_PAYLOAD_KEYS: ReadonlySet<string>;

package/dist/models.js

@@ -1,10 +1,13 @@
 /**
  * Reserved payload keys that cannot be used in extraFields.
- * These are the 4 allowed request fields per the OpenAPI spec.
+ * These are the allowed request fields per the OpenAPI spec.
  */
 export const RESERVED_PAYLOAD_KEYS = new Set([
     "message",
     "ip",
     "country",
-    "quality",
+    "input_type",
+    "extraction_mode",
+    "resolution_mode",
+    "image_title_filter",
 ]);

package/package.json

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