PromptCompose SDK

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

Installation

npm install @promptcompose/sdk

Quick Start

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',
  {
    config: {
      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

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

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

// Manual variant selection
const result = await promptCompose.resolvePrompt('prompt-id', {
  config: {
    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

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 = {
  config: {
    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

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