# Overview 📦

CardScan provides pre-built API clients for multiple programming languages to simplify integration with our platform. These clients are generated from our [OpenAPI specification](https://github.com/CardScan-ai/api-clients/blob/main/openapi.yaml) and provide type-safe interfaces for all API operations.

## Available Clients

| Language              | Package                        | Repository                                                        |
| --------------------- | ------------------------------ | ----------------------------------------------------------------- |
| TypeScript/JavaScript | `@cardscan.ai/cardscan-client` | [npm](https://www.npmjs.com/package/@cardscan.ai/cardscan-client) |
| Python                | `cardscan-client`              | [PyPI](https://pypi.org/project/cardscan-client/)                 |
| Swift                 | `CardScanClient`               | [Swift Package](https://github.com/CardScan-ai/api-clients)       |
| Kotlin                | `com.cardscan.api`             | [Maven](https://search.maven.org/artifact/com.cardscan/api)       |
| Dart                  | `cardscan_client`              | [pub.dev](https://pub.dev/packages/cardscan_client)               |

## Installation

### TypeScript/JavaScript

```bash
npm install @cardscan.ai/cardscan-client
# or
yarn add @cardscan.ai/cardscan-client
```

### Python

```bash
pip install cardscan-client
```

### Swift

```swift
// Package.swift
dependencies: [
    .package(url: "https://github.com/CardScan-ai/api-clients.git", from: "1.0.0")
]
```

### Kotlin

```kotlin
// build.gradle
implementation 'com.cardscan:api:1.0.0'
```

### Dart

```yaml
# pubspec.yaml
dependencies:
  cardscan_client: ^1.0.0
```

## Quick Start

All clients follow a similar pattern:

1. Initialize the client with your API key
2. Generate a session token for your user
3. Use the client to create cards, upload images, and retrieve results

```typescript
// TypeScript example
import { CardScanApi } from '@cardscan.ai/cardscan-client';

const client = new CardScanApi({ 
  apiKey: 'sk_test_cardscan_ai_...' 
});

// Generate session token
const { Token, IdentityId, session_id } = await client.getAccessToken({ 
  user_id: 'unique-user-id' 
});

// Create a card
const card = await client.createCard({
  sessionToken: Token,
  enable_backside_scan: false
});
```

## Features

All API clients provide:

* **Type Safety**: Strongly typed request and response objects
* **Authentication**: Built-in handling of API keys and session tokens
* **Error Handling**: Consistent error types and messages
* **Async Support**: Modern async/await patterns (where applicable)
* **Auto-retry**: Configurable retry logic for transient failures
* **Documentation**: Inline documentation and code completion

## Source Code

The API clients are open source and available at: <https://github.com/CardScan-ai/api-clients>

## Custom Clients

If you need to generate a client for a language not listed above, you can use our OpenAPI specification with any OpenAPI code generator:

```bash
# Example using OpenAPI Generator
openapi-generator generate \
  -i https://raw.githubusercontent.com/CardScan-ai/api-clients/main/openapi.yaml \
  -g <language> \
  -o ./generated-client
```