Skip to main content

Installation

npm install @chat-ads/chatads-sdk

Quick Start

import { ChatAdsClient } from '@chat-ads/chatads-sdk';

const client = new ChatAdsClient({
  apiKey: process.env.CHATADS_API_KEY!,
  baseUrl: 'https://api.getchatads.com'
});

// Using analyzeMessage (string + options)
const response = await client.analyzeMessage(
  "The Bose QuietComfort Ultra earbuds are great for commuting. They have solid noise cancellation and a comfortable fit. Battery life is around six hours, which is enough for most people.",
  { country: "US" }
);

if (response.error === null && response.data?.returned > 0) {
  // Access first offer
  const offer = response.data.offers[0];
  console.log(`link_text: ${offer.link_text}`);
  console.log(`url: ${offer.url}`);

  // Or iterate all offers
  response.data.offers.forEach((offer, i) => {
    console.log(`Offer ${i + 1}: ${offer.link_text} - ${offer.url}`);
  });
}

Configuration Options

import { ChatAdsClient } from '@chat-ads/chatads-sdk';

const client = new ChatAdsClient({
  apiKey: 'cak_your_api_key',                    // Required
  baseUrl: 'https://api.getchatads.com',         // Required: API base URL
  timeoutMs: 10000,                              // Optional: request timeout (default: 10000)
  maxRetries: 2,                                 // Optional: retry attempts (default: 0)
  retryBackoffFactorMs: 500,                     // Optional: backoff between retries
  raiseOnFailure: true,                          // Optional: throw on API errors
  fetchImplementation: customFetch,              // Optional: custom fetch for Node 16
  logger: console,                               // Optional: debug logging
});

Methods

analyze

Analyze a message using a payload object.
const response = await client.analyze({
  message: "Looking for a good yoga mat",
  country: "US",
});

analyzeMessage

Convenience method that takes a message string directly.
// Simple usage
const response = await client.analyzeMessage("Looking for a good yoga mat");

// With options
const response = await client.analyzeMessage(
  "Looking for a good yoga mat",
  {
    country: "US",
    extraction_mode: "fast",    // "none" | "fast" | "standard" (default)
    resolution_mode: "standard", // "none" | "standard" (default)
  }
);
Analyze images for product recommendations by passing input_type:
// Analyze a product image by URL
const response = await client.analyze({
  message: "https://example.com/product-image.jpg",
  input_type: "image_url",
  image_title_filter: "desk", // Filter results to only desk products
});

Response

See the API Reference for the full response structure. The SDK is fully typed — explore ChatAdsResponseEnvelope, Offer, Product, and other types via your editor’s autocomplete.