npm package: @semantikmatch/sdk
Description: JavaScript SDK for the Semantik Client API
Latest version: 0.1.4

# Semantik JavaScript SDK

TypeScript/JavaScript SDK for the Semantik Client API. Designed for Node.js and serverless environments.

📖 **[Full Documentation](./DOCUMENTATION.md)** - Complete API reference with all endpoints, types, and examples.

## Installation

```bash
npm install @semantikmatch/sdk
# or
yarn add @semantikmatch/sdk
# or
pnpm add @semantikmatch/sdk
```

## Quick Start

```typescript
import { Semantik } from '@semantikmatch/sdk';
import fs from 'fs';

// Automatically reads from SEMANTIK_API_KEY environment variable (recommended)
// Set SEMANTIK_API_KEY in your .env file or environment
const semantik = new Semantik();

// Or override with explicit API key
const semantik = new Semantik({
  apiKey: 'sk_your_api_key_here',
});

// List programs
const { programs } = await semantik.programs.list();
console.log(`Found ${programs.length} programs`);

// Get a specific program
const program = await semantik.programs.get(programs[0].id);

// Submit a candidate application
const cvBuffer = fs.readFileSync('resume.pdf');
const cvBase64 = cvBuffer.toString('base64');

const result = await semantik.candidates.submitApplication({
  candidate: {
    firstName: 'John',
    lastName: 'Doe',
    email: 'john.doe@example.com',
  },
  programId: program.id,
  stepId: program.steps[0].id,
  documents: [
    {
      fieldName: 'CV',
      content: cvBase64,
      fileName: 'john-doe-cv.pdf',
      mimeType: 'application/pdf',
      encoding: 'base64',
    },
  ],
});

console.log(`Application submitted: ${result.applicationId}`);
console.log(`Candidate ID: ${result.candidateId}`);

// Get candidate status
const status = await semantik.candidates.getStatus(result.candidateId, {
  include: 'applications,scores',
});

// Move candidate to next step
await semantik.programs.moveCandidate(program.id, {
  candidateId: result.candidateId,
  direction: 'next',
});
```

## Configuration

### API Key

Set your API key as an environment variable (recommended):

```bash
export SEMANTIK_API_KEY=sk_your_api_key_here
```

Or pass it directly to the client:

```typescript
const semantik = new Semantik({
  apiKey: 'sk_your_api_key_here',
});
```

### Base URL

The SDK defaults to production (`https://gateway.semantikmatch.com`). For local development:

```typescript
const semantik = new Semantik({
  apiKey: 'sk_...',
  baseUrl: 'http://localhost:9000',
});
```

Or set `SEMANTIK_BASE_URL` environment variable.

## API Reference

### Programs

- `semantik.programs.list()` - List all programs
- `semantik.programs.get(programId)` - Get a specific program
- `semantik.programs.listCandidates(programId, options?)` - List candidates in a program
- `semantik.programs.moveCandidate(programId, request)` - Move a candidate between steps

### Candidates

- `semantik.candidates.submitApplication(request)` - Submit a new application
- `semantik.candidates.getStatus(candidateId, options?)` - Get candidate status across all programs
- `semantik.candidates.getApplications(candidateId, options?)` - Get all applications for a candidate
- `semantik.candidates.getScores(candidateId, options?)` - Get candidate scores
- `semantik.candidates.enroll(candidateId, request)` - Enroll candidate in a program

## Error Handling

```typescript
import { Semantik, ApiError } from '@semantikmatch/sdk';

try {
  await semantik.programs.get(999);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error ${error.status}: ${error.message}`);
    console.error(error.response);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All request and response types are exported for use in your code.

## Support

For issues or questions, please contact support or visit the [documentation](https://docs.semantikmatch.com).