@searcly/sdk/README.md

Searcly Visual Search SDK for JavaScript

# Searcly SDK

The official JavaScript SDK for Searcly's Visual Search API. This SDK provides a simple and intuitive way to integrate visual search capabilities into your applications.

## Installation

```bash
npm install @searcly/sdk
# or
yarn add @searcly/sdk
```

## Quick Start

```javascript
import SearclyClient from '@searcly/sdk';

// Initialize the client
const client = new SearclyClient({
  apiKey: 'your_api_key_here'
});

// Search by image URL
const searchByUrl = async () => {
  try {
    const results = await client.searchByImage('https://example.com/image.jpg', {
      limit: 10
    });
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
};

// Search by image upload
const searchByUpload = async (imageFile) => {
  try {
    const results = await client.searchByImageUpload(imageFile, {
      limit: 10
    });
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
};

// Search similar products by ID
const searchSimilar = async () => {
  try {
    const results = await client.searchById('product_id_123', {
      limit: 10
    });
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
};
```

## Features

- Search by image URL
- Search by image upload (supports various image formats)
- Find similar products by ID
- Customizable search options (filters, limits, etc.)
- TypeScript support
- Comprehensive error handling

## API Reference

### Configuration

```typescript
interface SearclyConfig {
  apiKey: string;
  baseUrl?: string; // Optional, defaults to https://api.searcly.com/v1
}
```

### Search Options

```typescript
interface SearchOptions {
  limit?: number;     // Number of results to return
  offset?: number;    // Pagination offset
  filters?: Record<string, any>; // Additional search filters
}
```

### Methods

#### searchByImage(imageUrl: string, options?: SearchOptions)
Search for similar products using an image URL.

#### searchByImageUpload(imageFile: Buffer | Blob, options?: SearchOptions)
Search for similar products by uploading an image file.

#### searchById(productId: string, options?: SearchOptions)
Find products similar to a given product ID.

## Error Handling

The SDK throws descriptive errors that you can catch and handle in your application:

```javascript
try {
  const results = await client.searchByImage(imageUrl);
} catch (error) {
  if (error.response) {
    // API error response
    console.error('API Error:', error.response.data);
  } else if (error.request) {
    // Network error
    console.error('Network Error:', error.message);
  } else {
    // Other errors
    console.error('Error:', error.message);
  }
}
```

## Development

To contribute to the SDK:

1. Clone the repository
2. Install dependencies: `npm install`
3. Make your changes
4. Run tests: `npm test`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For support, email support@searcly.com or visit our [documentation](https://docs.searcly.com).