channel3-sdk

Channel3 TypeScript/JavaScript SDK

The official TypeScript/JavaScript SDK for the Channel3 AI Shopping API. Search for products using text, images, and advanced filters with AI-powered semantic search.

🚀 Features

• 🔍 Text Search: Natural language product search
• 🖼️ Visual Search: Search by image URL or base64 data
• 🎯 Advanced Filters: Filter by brand, price, gender, availability
• ⚙️ Search Configuration: Control query enrichment and semantic search
• 🔧 TypeScript First: Full type safety with auto-generated types from OpenAPI
• 🛡️ Robust Error Handling: Detailed error types for different scenarios

📦 Installation

npm install channel3-sdk
# or
yarn add channel3-sdk
# or
pnpm add channel3-sdk

🏃‍♂️ Quick Start

Basic Usage

import { Channel3Client } from 'channel3-sdk';

const client = new Channel3Client({
  apiKey: process.env.CHANNEL3_API_KEY!,
});

// Search for products
const products = await client.search({
  query: 'blue denim jacket',
});

console.log(`Found ${products.length} products`);
products.forEach((product) => {
  console.log(`${product.title} - $${product.price.price} ${product.price.currency}`);
});

Advanced Search with Configuration

// Search with custom configuration and context
const results = await client.search({
  query: 'running shoes',
  config: {
    enrich_query: true, // Enable query enrichment
    semantic_search: true, // Enable semantic search
  },
  context: 'Looking for athletic footwear for marathon training',
  filters: {
    price: { min_price: 50, max_price: 200 },
    gender: 'male',
    brand_ids: ['nike-id', 'adidas-id'],
  },
  limit: 10,
});

Visual Search

// Search by image URL
const imageResults = await client.search({
  image_url: 'https://example.com/product-image.jpg',
});

// Search by base64 image
const base64Results = await client.search({
  base64_image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
});

📚 API Reference

Client Configuration

interface Channel3ClientConfig {
  apiKey: string; // Your Channel3 API key
}

Methods

search(options: SearchRequest): Promise<Product[]>

Search for products with various options.

Parameters:

• query?: string - Text search query
• image_url?: string - URL of image for visual search
• base64_image?: string - Base64-encoded image for visual search
• config?: SearchConfig - Search configuration options
• context?: string - Additional context for the search
• filters?: SearchFilters - Advanced filtering options
• limit?: number - Maximum results to return (default: 20)

getProduct(productId: string): Promise<ProductDetail>

Get detailed information about a specific product.

getBrands(options?: GetBrandsV0BrandsGetRequest): Promise<PaginatedResponseBrand>

Get list of available brands with pagination.

getBrand(brandId: string): Promise<Brand>

Get detailed information about a specific brand.

🔧 Configuration Options

Search Configuration

interface SearchConfig {
  enrich_query?: boolean; // Enable AI query enrichment (default: true)
  semantic_search?: boolean; // Enable semantic search (default: true)
}

Search Filters

interface SearchFilters {
  brand_ids?: string[]; // Filter by specific brand IDs
  gender?: 'male' | 'female' | 'unisex'; // Gender filter
  price?: {
    // Price range filter
    min_price?: number;
    max_price?: number;
  };
  availability?: AvailabilityStatus[]; // Availability filter
}

🌍 Environment Variables

• CHANNEL3_API_KEY - Your Channel3 API key (required)

🚨 Error Handling

The SDK provides specific error types for different scenarios:

import {
  Channel3AuthenticationError, // 401 - Invalid API key
  Channel3ValidationError, // 422 - Invalid request data
  Channel3NotFoundError, // 404 - Resource not found
  Channel3ServerError, // 500 - Server error
  Channel3ConnectionError, // Network/timeout errors
} from 'channel3-sdk';

try {
  const products = await client.search({ query: 'shoes' });
} catch (error) {
  if (error instanceof Channel3AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof Channel3ValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof Channel3ConnectionError) {
    console.error('Network error:', error.message);
  }
}

📝 License

MIT License - see LICENSE file for details.

🤝 Support

• 📧 Email: [e-mail]
• 🌐 Website: https://trychannel3.com

Made with ❤️ by Channel3