npm package: @montage-sh/sdk
Description: Official SDK for Montage - Remote configuration for AI prompts
Latest version: 0.1.0

# @montage-sh/sdk

Official SDK for Montage - Remote configuration for AI prompts.

## Installation

```bash
npm install @montage-sh/sdk
```

## Quick Start

```typescript
import { Montage } from '@montage-sh/sdk';
import OpenAI from 'openai';

// Initialize Montage
const montage = new Montage({
  apiKey: process.env.MONTAGE_API_KEY // mt_live_xxx
});

// Initialize OpenAI
const openai = new OpenAI();

// Fetch your prompt
const prompt = await montage.get('customer-support');

// Use directly with OpenAI — messages are already in the right format
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  temperature: prompt.temperature ?? 0.7,
  messages: prompt.messages
});
```

### With variables

```typescript
const prompt = await montage.get('customer-support');

// Replace {{variable}} placeholders with actual values
const compiled = prompt.compile({
  user_name: 'Sarah',
  company: 'Acme Corp'
});

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  temperature: compiled.temperature ?? 0.7,
  messages: compiled.messages
});
```

## API

### `new Montage(config)`

Create a new Montage client.

```typescript
const montage = new Montage({
  apiKey: 'mt_live_xxx',     // Required
  baseUrl: 'https://...',    // Optional, for self-hosted
  cacheTtl: 60               // Optional, cache TTL in seconds
});
```

### `montage.get(slug, options?)`

Fetch a prompt by its slug.

```typescript
const prompt = await montage.get('my-prompt');

// Skip cache
const fresh = await montage.get('my-prompt', { skipCache: true });

// Custom cache TTL
const prompt = await montage.get('my-prompt', { cacheTtl: 300 });
```

Returns a `Prompt` object:
```typescript
{
  id: string;
  slug: string;
  name: string;
  messages: PromptMessage[];     // Array of { role, content } messages
  variables: string[];           // Extracted variable names from {{variable}} syntax
  temperature: number | null;    // e.g., 0.7
  max_tokens: number | null;
  version: number;               // Current published version
  variable_metadata?: Record<string, VariableMetadata>;

  compile(values?: Record<string, string | number | boolean>): CompiledPrompt;
}
```

### `prompt.compile(values?)`

Replace `{{variable}}` placeholders in messages with actual values.

```typescript
const compiled = prompt.compile({ name: 'Sarah' });
// compiled.messages  — messages with variables replaced
// compiled.temperature
// compiled.max_tokens
```

### `montage.clearCache()`

Clear all cached prompts.

### `montage.invalidate(slug)`

Invalidate a specific prompt from cache.

## Error Handling

```typescript
import { MontageError } from '@montage-sh/sdk';

try {
  const prompt = await montage.get('my-prompt');
} catch (error) {
  if (error instanceof MontageError) {
    console.error(`Error ${error.code}: ${error.message}`);
    // error.status - HTTP status code
    // error.code - Error code (e.g., 'not_found', 'unauthorized')
  }
}
```

## Environment Variables

We recommend storing your API key in an environment variable:

```bash
MONTAGE_API_KEY=mt_live_xxxxx
```

```typescript
const montage = new Montage({
  apiKey: process.env.MONTAGE_API_KEY!
});
```

## Requirements

- Node.js 18 or later
- A Montage API key (`mt_live_*` or `mt_test_*`)

## License

MIT