npm package: @promptcompose/sdk
Description: SDK for integrating with PromptCompose API to resolve and manage AI prompts.
Author: Mahmoud Bassam
Latest version: 0.1.2

# PromptCompose SDK

Official JavaScript/TypeScript SDK for integrating with the PromptCompose API to resolve and manage AI prompts with A/B testing capabilities.

## Installation

```bash
npm install @promptcompose/sdk
```

## Quick Start

```typescript
import { PromptCompose } from '@promptcompose/sdk';

// Initialize the SDK
const promptCompose = new PromptCompose(
  'your-api-key',
  'your-project-id',
  { debug: true }
);

// Initialize connection
await promptCompose.init();

// Resolve a prompt with variables
const result = await promptCompose.resolvePrompt(
  'prompt-id',
  {
    versionId: 'v1',
    abTesting: { enabled: false }
  },
  {
    userName: 'John',
    productName: 'Widget'
  }
);

console.log(result.content);
```

## Features

- **Prompt Resolution**: Resolve prompts with dynamic variable interpolation
- **A/B Testing**: Built-in support for A/B testing with multiple rollout strategies
- **Version Management**: Handle multiple prompt versions seamlessly
- **TypeScript Support**: Full TypeScript definitions included with JSDoc comments
- **IntelliSense**: Complete IntelliSense support for both TypeScript and JavaScript users
- **Error Handling**: Comprehensive error handling with detailed messages

## API Reference

### Constructor

```typescript
new PromptCompose(apiKey: string, projectId: string, options?: { debug: boolean })
```

### Methods

#### `init()`
Performs initial handshake with the API to verify credentials.

#### `listPrompts()`
Retrieves all prompts for the project.

#### `getPrompt(promptId: string)`
Retrieves a specific prompt by ID.

#### `resolvePrompt(promptId: string, config: PromptConfig, variables?: Record<string, string | number>)`
Resolves a prompt with optional A/B testing and variable interpolation.

#### `listABTests()`
Retrieves all A/B tests for the project.

#### `getABTest(abTestId: string)`
Retrieves a specific A/B test by ID.

#### `reportABResult(abTestId: string, result: ReportABResult)`
Reports A/B test results for analytics.

## A/B Testing

The SDK supports three A/B testing strategies:

- **Sequential**: Tests variants in order
- **Weighted**: Random selection with specified weights
- **Manual**: Explicit variant selection

```typescript
// Sequential A/B testing
const result = await promptCompose.resolvePrompt('prompt-id', {
  abTesting: {
    sessionId: 'user-session-123'
  }
});

// Manual variant selection
const result = await promptCompose.resolvePrompt('prompt-id', {
  abTesting: {
    variantId: 'variant-abc'
  }
});
```

## Error Handling

The SDK provides detailed error messages for various scenarios:

- `ValidationError`: Missing required variables or invalid configuration
- `APIError`: Network or server errors
- `SDKError`: General SDK errors

## IntelliSense Support

The SDK provides comprehensive IntelliSense support for both TypeScript and JavaScript users:

### TypeScript Users
- Full type definitions with JSDoc comments
- Autocomplete for all methods and properties
- Type checking for parameters and return values
- Import suggestions for all exported types

```typescript
import { PromptCompose, PromptConfig, ResolvedPrompt } from '@promptcompose/sdk';

// Full IntelliSense support with JSDoc comments
const sdk = new PromptCompose('api-key', 'project-id');

// IntelliSense will show autocomplete for config.abTesting properties
const config: PromptConfig = {
  versionId: 'v1',
  abTesting: {
    enabled: false,
    variantId: 'variant-123',
    sessionId: 'session-456'
  }
};

const result: ResolvedPrompt = await sdk.resolvePrompt('prompt-id', config);
```

### JavaScript Users
- JSDoc comments preserved in compiled output
- Autocomplete for methods and properties
- Parameter hints and documentation
- Type information available through JSDoc

```javascript
import { PromptCompose } from '@promptcompose/sdk';

// JSDoc comments provide IntelliSense even in JavaScript
const sdk = new PromptCompose('api-key', 'project-id');
const result = await sdk.resolvePrompt('prompt-id', config);
```

## License

MIT