SDK Documentation¶

# Installation

## Package Managers

### npm
npm install @company/sdk

### yarn
yarn add @company/sdk

### pnpm
pnpm add @company/sdk

## Requirements

- Node.js 18 or higher
- TypeScript 5.0+ (for TypeScript users)

## Verify Installation

import { Client } from '@company/sdk';
console.log(Client.VERSION); // Should print version number

# Quick Start

This guide gets you from zero to working code in under 5 minutes.

## 1. Install the SDK

npm install @company/sdk

## 2. Get Your API Key

Create an account at [dashboard.example.com](https://dashboard.example.com)
and copy your API key.

## 3. Initialize the Client

const { Client } = require('@company/sdk');

const client = new Client({
  apiKey: process.env.API_KEY
});

## 4. Make Your First Request

const result = await client.analyze('Hello, world!');
console.log(result);
// { sentiment: 'positive', confidence: 0.95 }

## Next Steps

- [Configuration options](configuration.md)
- [Core concepts](concepts.md)
- [Full API reference](reference/index.md)

# Configuration

## Client Options

const client = new Client({
  apiKey: 'your-api-key',      // Required
  baseUrl: 'https://...',       // Optional: custom endpoint
  timeout: 30000,               // Optional: request timeout (ms)
  retries: 3,                   // Optional: retry attempts
  debug: false                  // Optional: enable logging
});

## Option Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| apiKey | string | — | Your API key (required) |
| baseUrl | string | Production URL | API endpoint |
| timeout | number | 30000 | Request timeout in ms |
| retries | number | 3 | Max retry attempts |
| debug | boolean | false | Enable debug logging |

## Environment Variables

The SDK reads these environment variables:

- `COMPANY_API_KEY`: API key (if not passed to constructor)
- `COMPANY_DEBUG`: Enable debug mode ("true" or "1")

# Client

The main entry point for the SDK.

## Constructor

new Client(options: ClientOptions)

Creates a new client instance.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| options | ClientOptions | Configuration options |

**Example:**

const client = new Client({ apiKey: 'your-key' });

## Methods

### analyze(text)

Analyzes text and returns results.

client.analyze(text: string, options?: AnalyzeOptions): Promise<AnalyzeResult>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| text | string | Yes | Text to analyze |
| options | AnalyzeOptions | No | Analysis options |

**Returns:** `Promise<AnalyzeResult>`

**Example:**

const result = await client.analyze('Great product!');
// { sentiment: 'positive', confidence: 0.92 }

**Throws:**

- `AuthenticationError`: Invalid API key
- `ValidationError`: Text is empty or too long
- `RateLimitError`: Rate limit exceeded

# Types

## ClientOptions

Configuration for the Client constructor.

interface ClientOptions {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
  retries?: number;
  debug?: boolean;
}

## AnalyzeResult

Result from the analyze method.

interface AnalyzeResult {
  sentiment: 'positive' | 'negative' | 'neutral';
  confidence: number;
  keywords: string[];
}

# Examples

## Basic Usage

### Simple Analysis

const result = await client.analyze('I love this product');

### Batch Processing

const texts = ['Great!', 'Terrible', 'Okay'];
const results = await Promise.all(
  texts.map(text => client.analyze(text))
);

## Error Handling

### Retry Logic

async function analyzeWithRetry(text, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.analyze(text);
    } catch (error) {
      if (error instanceof RateLimitError && i < maxRetries - 1) {
        await sleep(error.retryAfter * 1000);
        continue;
      }
      throw error;
    }
  }
}

## Integration Examples

### Express.js Middleware

const express = require('express');
const { Client } = require('@company/sdk');

const app = express();
const client = new Client({ apiKey: process.env.API_KEY });

app.post('/analyze', async (req, res) => {
  const result = await client.analyze(req.body.text);
  res.json(result);
});

# Migrating from v1 to v2

## Breaking Changes

### Client Initialization

**v1:**
const client = new Client('api-key');

**v2:**
const client = new Client({ apiKey: 'api-key' });

### Method Signatures

**v1:**
client.analyze(text, callback)

**v2:**
await client.analyze(text)

## New Features in v2

- Promise-based API (no more callbacks)
- TypeScript support
- Automatic retries
- Streaming responses

## Deprecated Features

The following are deprecated and will be removed in v3:

- `client.analyzeSync()` - Use `await client.analyze()`
- `options.apiVersion` - API version is now automatic

=== "Python"

    client = Client(api_key="your-key")
    result = client.analyze("Hello")

=== "JavaScript"

    const client = new Client({ apiKey: 'your-key' });
    const result = await client.analyze('Hello');

=== "Go"

    client := sdk.NewClient(sdk.WithAPIKey("your-key"))
    result, err := client.Analyze(ctx, "Hello")