@montage-sh/sdk

Official SDK for Montage - Remote configuration for AI prompts.

Installation

npm install @montage-sh/sdk

Quick Start

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

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.

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.

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:

{
  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.

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

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:

MONTAGE_API_KEY=mt_live_xxxxx

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