> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinrefine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> The complete TypeScript SDK for Refine search, recommendations, and analytics

## Introduction

The `@refine-ai/sdk` package is the official TypeScript SDK for integrating Refine into your application. It provides:

* **Search** — Text and image search with visual AI
* **Recommendations** — Similar items, visitor, and user-based personalization
* **Product Listing Pages** — Curated collections with pinned products
* **Event Tracking** — Comprehensive analytics with automatic batching
* **Identity Management** — Visitor, session, and user tracking
* **Plugins** — Extensible architecture for consent, debugging, and auto-tracking

## Quick Example

```typescript theme={null}
import { Refine } from '@refine-ai/sdk';

// Initialize
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789'
});

// Search
const results = await refine.search.text({
  query: 'summer dress',
  topK: 24,
  visualWeight: 0.5
});

// Track events
const context = refine.events.trackSearch('summer dress', results.results, {
  surface: 'search_results',
  totalResults: results.totalResults
});

// Handle user interaction
context.trackClick('sku_001', 0);

// Get recommendations
const recs = await refine.recs.similarItems({
  anchorId: 'sku_001',
  topK: 8
});

// Identify logged-in users
refine.identify('user_12345');
```

## SDK Structure

The SDK is organized into namespaces:

| Namespace           | Purpose                                        |
| ------------------- | ---------------------------------------------- |
| `refine.search`     | Text and image search                          |
| `refine.recs`       | Recommendations (similar items, visitor, user) |
| `refine.plp`        | Product listing pages                          |
| `refine.events`     | Event tracking and queue management            |
| `refine.identify()` | User identification                            |
| `refine.use()`      | Plugin registration                            |

## Requirements

* **Runtime**: Browser or Node.js 18+
* **TypeScript**: 4.7+ (optional but recommended)
* **Bundle size**: \~12KB gzipped

## Documentation

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Install and set up the SDK
  </Card>

  <Card title="Configuration" icon="gear" href="/sdk/configuration">
    All configuration options
  </Card>

  <Card title="Text Search" icon="magnifying-glass" href="/sdk/search/text-search">
    Natural language search
  </Card>

  <Card title="Recommendations" icon="wand-magic-sparkles" href="/sdk/recommendations/overview">
    AI-powered product recommendations
  </Card>

  <Card title="Event Tracking" icon="chart-line" href="/sdk/events/overview">
    Analytics and conversion tracking
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/sdk/error-handling">
    Error types and handling patterns
  </Card>
</CardGroup>