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

# JavaScript SDK

> CodeGate JavaScript/TypeScript client - code listing, verify, reactivate

## Install

```bash theme={null}
npm install codegate-sdk
```

Or install from local build (e.g. for development):

```bash theme={null}
cd sdk/javascript
npm install
npm run build
npm pack
npm install ./codegate-sdk-*.tgz
```

## Requirements

* **Node.js** >= 18 (native `fetch`, `crypto`)
* **TypeScript** >= 4.5 (optional)

## Quick start

```typescript theme={null}
import { CodeGateClient } from 'codegate-sdk';

const client = new CodeGateClient({
  apiKey: '550e8400e29b41d4a716446655440000',
  secret: 'a1b2c3d4e5f6...',
  projectId: '550e8400e29b41d4a716446655440000',
  baseUrl: 'https://api.example.com',
});

// Get project info
const project = await client.getProject();
console.log(project.name, project.statistics.total_codes);

// Verify code
const result = await client.verifyCode({ code: 'ABC12345', verifiedBy: 'user123' });
if (result.success) console.log('Verified at:', result.verified_at);
```

## API overview

| Method                                              | Description                                 |
| --------------------------------------------------- | ------------------------------------------- |
| `getProject()`                                      | Get project info                            |
| `listCodes(options?)`                               | List codes (page, pageSize, status, search) |
| `getCode(codeId)`                                   | Get one code by ID                          |
| `getCodeByCode(code)`                               | Get one code by code string                 |
| `verifyCode({ code, verifiedBy? })`                 | Verify (redeem) a code                      |
| `reactivateCode({ code, reactivatedBy?, reason? })` | Reactivate a used code                      |
| `getStatistics()`                                   | Project statistics                          |

Options use camelCase (e.g. `pageSize`, `verifiedBy`); the client converts to API snake\_case.

## Usage details

### Pagination and filters

```typescript theme={null}
// Unused only, search by keyword
const { items, total, totalPages } = await client.listCodes({
  page: 1,
  pageSize: 50,
  status: 'unused',
  search: 'PROMO2024',
});

// Iterate all unused codes
for (let p = 1; p <= totalPages; p++) {
  const { items } = await client.listCodes({ page: p, pageSize: 100, status: 'unused' });
  for (const c of items) console.log(c.code);
}
```

### Verify result and error\_code

Aside from 4xx/5xx (which throw `CodeGateApiError`), verify uses `success` and `error_code`:

```typescript theme={null}
const result = await client.verifyCode({ code: 'ABC12345', verifiedBy: 'user123' });
if (result.success) {
  console.log('Verified', result.verified_at);
} else {
  // e.g. CODE_ALREADY_USED, CODE_NOT_FOUND, CODE_DISABLED, CODE_EXPIRED
  console.log(result.error_code, result.message);
}
```

### Error handling

`4xx`/`5xx` throw `CodeGateApiError` with `status` and `detail`:

```typescript theme={null}
import { CodeGateClient, CodeGateApiError } from 'codegate-sdk';

try {
  await client.verifyCode({ code: 'X' });
} catch (e) {
  if (e instanceof CodeGateApiError) {
    if (e.status === 401) console.log('Auth failed');
    else if (e.status === 429) console.log('Rate limited');
  }
}
```

### Retry and resilience

Retry a limited number of times on 5xx or network errors:

```typescript theme={null}
async function withRetry<T>(fn: () => Promise<T>, max = 3): Promise<T> {
  for (let i = 0; i < max; i++) {
    try {
      return await fn();
    } catch (e: any) {
      const ok = e?.status >= 500 || e?.code === 'ECONNRESET';
      if (i === max - 1 || !ok) throw e;
      await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
    }
  }
  throw new Error('Unreachable');
}

const result = await withRetry(() => client.verifyCode({ code: 'ABC12345' }));
```

### Custom requests and generateSignature

For your own HTTP client, use `generateSignature`:

```typescript theme={null}
import { generateSignature } from 'codegate-sdk';

const method = 'GET';
const path = `/api/v1/projects/${projectId}/codes`;
const queryParams = { page: '1', page_size: '20', status: 'unused' };
const timestamp = Math.floor(Date.now() / 1000);
const sig = generateSignature(method, path, queryParams, undefined, timestamp, secret);
// Set X-Signature, X-API-Key, X-Timestamp in headers
```

## Environment variables

Use env vars for credentials in different environments:

```typescript theme={null}
const client = new CodeGateClient({
  apiKey: process.env.CODEGATE_API_KEY!,
  secret: process.env.CODEGATE_SECRET!,
  projectId: process.env.CODEGATE_PROJECT_ID!,
  baseUrl: process.env.CODEGATE_BASE_URL || 'https://api.example.com',
});
```

## Development

### Build

```bash theme={null}
cd sdk/javascript
npm install
npm run build
```

Output in `dist/`: `index.js` (ESM), `index.cjs`, `index.d.ts`.

### Tests

```bash theme={null}
npm run test
```

### Examples

```bash theme={null}
npx tsx examples/basic_usage.ts
npx tsx examples/error_handling.ts
```

Set `CODEGATE_API_KEY`, `CODEGATE_SECRET`, `CODEGATE_PROJECT_ID`, `CODEGATE_BASE_URL` (optional).