# SDKs & Libraries

Official SDKs for integrating with the AIDP API in your preferred language.

## Available SDKs

### [TypeScript/JavaScript](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/typescript)

For Node.js, browser, and TypeScript applications.

```bash
npm install @aidp/sdk
```

**Features**:

* Full TypeScript support with type definitions
* Promise-based async/await API
* Automatic retry and error handling
* Works in Node.js and browsers
* Tree-shakeable for optimal bundle size

***

### [Python](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/python)

For Python 3.8+ applications.

```bash
pip install aidp-sdk
```

**Features**:

* Type hints for better IDE support
* Async/await support with asyncio
* Automatic pagination
* Built-in retry logic
* Django and Flask integrations

***

### [JavaScript (Vanilla)](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/javascript)

For browser-only applications without build tools.

```html
<script src="https://cdn.aidp.dev/sdk/v1/aidp.min.js"></script>
```

**Features**:

* No build tools required
* Works in all modern browsers
* Lightweight (\~15KB gzipped)
* Promise-based API
* CDN-hosted for fast loading

***

## Quick Comparison

| Feature          | TypeScript/JS    | Python       | Vanilla JS     |
| ---------------- | ---------------- | ------------ | -------------- |
| **Environment**  | Node.js, Browser | Python 3.8+  | Browser only   |
| **Installation** | npm/yarn         | pip          | CDN script tag |
| **Type Safety**  | ✅ Full           | ✅ Type hints | ❌ No           |
| **Async/Await**  | ✅ Yes            | ✅ Yes        | ✅ Yes          |
| **Bundle Size**  | \~25KB           | N/A          | \~15KB         |
| **Tree Shaking** | ✅ Yes            | N/A          | ❌ No           |

***

## Common Features

All SDKs include:

### Authentication

* API key authentication
* JWT token support
* Automatic token refresh

### Error Handling

* Typed error responses
* Automatic retry for transient errors
* Rate limit handling

### Request Features

* Automatic pagination
* Request cancellation
* Timeout configuration
* Custom headers

### Response Features

* Automatic JSON parsing
* Type-safe responses
* Error normalization

***

## Getting Started

### 1. Get an API Key

1. Sign up at [platform.aidp.dev](https://platform.aidp.dev)
2. Navigate to Settings → API Keys
3. Create a new API key
4. Copy and store securely

### 2. Install SDK

Choose your preferred language and follow the installation guide:

* [TypeScript/JavaScript →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/typescript)
* [Python →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/python)
* [Vanilla JavaScript →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/javascript)

### 3. Make Your First Request

**TypeScript/JavaScript**:

```typescript
import { AIDPClient } from '@aidp/sdk';

const client = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
});

const results = await client.search({
  query: 'coffee shops',
  location: { lat: 45.5231, lon: -122.6765, distance: '5km' },
});
```

**Python**:

```python
from aidp import AIDPClient

client = AIDPClient(api_key=os.environ['AIDP_API_KEY'])

results = client.search(
    query='coffee shops',
    location={'lat': 45.5231, 'lon': -122.6765, 'distance': '5km'}
)
```

**Vanilla JavaScript**:

```javascript
const client = new AIDP.Client({
  apiKey: 'your-api-key',
});

const results = await client.search({
  query: 'coffee shops',
  location: { lat: 45.5231, lon: -122.6765, distance: '5km' },
});
```

***

## SDK Architecture

### Client Initialization

All SDKs follow a similar initialization pattern:

```typescript
const client = new AIDPClient({
  apiKey: 'your-api-key', // Required
  environment: 'production', // 'production' or 'sandbox'
  timeout: 30000, // Request timeout in ms
  retries: 3, // Number of retries
  baseURL: 'https://api.aidp.dev/v1', // Custom base URL (optional)
});
```

### Resource Organization

SDKs organize API endpoints into logical resources:

* **`client.search()`** - Business search
* **`client.businesses`** - Business management
* **`client.analytics`** - Analytics data
* **`client.auth`** - Authentication

***

## Best Practices

### 1. Store API Keys Securely

❌ **Don't**:

```typescript
const client = new AIDPClient({
  apiKey: 'sk_live_abc123...', // Hardcoded!
});
```

✅ **Do**:

```typescript
const client = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
});
```

### 2. Handle Errors Properly

```typescript
try {
  const results = await client.search({ query: 'coffee' });
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Wait and retry
    await sleep(error.retryAfter * 1000);
  } else {
    // Log and handle
    console.error('Search failed:', error.message);
  }
}
```

### 3. Use TypeScript for Type Safety

```typescript
import { AIDPClient, SearchParams, SearchResponse } from '@aidp/sdk';

const params: SearchParams = {
  query: 'coffee shops',
  location: { lat: 45.5231, lon: -122.6765, distance: '5km' },
};

const response: SearchResponse = await client.search(params);
```

***

## Support

### Documentation

* [TypeScript/JavaScript SDK →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/typescript)
* [Python SDK →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/python)
* [Vanilla JavaScript SDK →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks/javascript)
* [API Reference →](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference)

### Help

* 📧 Email: <sdk@aidp.dev>
* 💬 GitHub Discussions: [github.com/aidp/platform/discussions](https://github.com/aidp/platform/discussions)
* 🐛 Issues: [github.com/aidp/sdk/issues](https://github.com/aidp/sdk/issues)

***

## Contributing

We welcome contributions to our SDKs!

* [TypeScript/JS SDK Repository](https://github.com/aidp/sdk-js)
* [Python SDK Repository](https://github.com/aidp/sdk-python)
* [Contribution Guidelines](https://amistan.gitbook.io/aidp-docs/resources/contributing)