Channel3 TypeScript SDK

The official TypeScript SDK for the Channel3 API — a universal product database powering AI shopping apps and agents.

Documentation

Full API documentation and guides are available at channel3.docs.buildwithfern.com.

Runtime Compatibilities

Installation

npm install @channel3/sdk
# or
yarn add @channel3/sdk
# or
pnpm add @channel3/sdk

Authentication

The SDK authenticates via an x-api-key header. Pass your key when initializing the client:

import { Channel3Client } from "@channel3/sdk";

const client = new Channel3Client({ apiKey: "YOUR_API_KEY" });

You can also supply a function for dynamic key resolution (useful for key rotation):

const client = new Channel3Client({
    apiKey: async () => getKeyFromVault(),
});

Usage

Search products

const response = await client.products.search({
    query: "organic cotton t-shirt",
    limit: 10,
});

for (const product of response.products) {
    console.log(product.title, product.offers?.[0]?.price);
}

Paginate through results

Search responses include a nextPageToken for cursor-based pagination:

let pageToken: string | undefined;

do {
    const response = await client.products.search({
        query: "sneakers",
        pageToken,
    });

    for (const product of response.products) {
        console.log(product.title);
    }

    pageToken = response.nextPageToken ?? undefined;
} while (pageToken);

Visual search by image

const response = await client.products.imageSearch({
    imageUrl: "https://example.com/photo.jpg",
});

Find similar products

const response = await client.products.similar({
    productId: "prod-12345",
});

Look up a product by URL

const product = await client.products.lookup({
    url: "https://example.com/product/abc",
});

Browse brands and categories

Cursor-paginated listing for brands and categories:

const brands = await client.brands.list({ limit: 50 });
console.log(brands.items);       // Brand[]
console.log(brands.nextCursor);  // pass as `cursor` for the next page

const categories = await client.categories.list({ pageSize: 50 });

Track prices

// Start tracking
await client.priceTracking.start({ canonicalProductId: "prod-12345" });

// Get price history
const history = await client.priceTracking.getHistory({ canonicalProductId: "prod-12345" });

// List active subscriptions
const subs = await client.priceTracking.listSubscriptions();

// Stop tracking
await client.priceTracking.stop({ canonicalProductId: "prod-12345" });

Type Intellisense

All request and response types are exported under the Channel3 namespace for easy discovery:

import { Channel3 } from "@channel3/sdk";

// Full autocomplete on request fields
const request: Channel3.SearchRequest = {
    query: "wireless headphones",
    limit: 20,
    filters: { gender: "female" },
    config: { country: "US", currency: "USD" },
};

// Response types are also typed
const response: Channel3.SearchResponse = await client.products.search(request);

Resource clients are accessible via dot notation — type client. in your editor to discover:

Error Handling

The SDK throws typed errors per HTTP status code:

import { Channel3Error, Channel3TimeoutError } from "@channel3/sdk";

try {
    await client.products.search({ query: "test" });
} catch (err) {
    if (err instanceof Channel3Error) {
        console.log(err.statusCode); // 401, 402, 422, etc.
        console.log(err.message);
        console.log(err.body);
    }
}

Advanced

Retries

Automatic exponential backoff on 5xx and network errors (default: 2 retries):

const response = await client.products.search(
    { query: "shoes" },
    { maxRetries: 5 },
);

Timeouts

Default timeout is 60 seconds. Override per-client or per-request:

const client = new Channel3Client({
    apiKey: "YOUR_API_KEY",
    timeoutInSeconds: 30,
});

// Per-request
await client.products.search({ query: "shoes" }, { timeoutInSeconds: 10 });

Abort Requests

const controller = new AbortController();
await client.products.search({ query: "shoes" }, { abortSignal: controller.signal });

Raw Response Access

Access HTTP headers and status alongside parsed data:

const response = await client.products.search({ query: "shoes" });
console.log(response.rawResponse.status);
console.log(response.rawResponse.headers);

Reference

See the full API reference in reference.md.

Contributing

See CONTRIBUTING.md for development setup and guidelines.