PromptOS TypeScript SDK

Official TypeScript SDK for interacting with the PromptOS.dev API prompts endpoints.

Installation

npm install @promptos.dev/sdk
# or
yarn add @promptos.dev/sdk
# or
pnpm add @promptos.dev/sdk
# or
bun add @promptos.dev/sdk

Quick Start

import { PromptOSClient } from '@promptos.dev/sdk';

// Initialize the client with your API key
const client = new PromptOSClient({
  apiKey: 'mpa_live_your_api_key_here'
});

// List all prompts
const prompts = await client.prompts.list();
for (const prompt of prompts.data) {
  console.log(`${prompt.title} - ${prompt.id}`);
}

// Render a prompt
const result = await client.prompts.render('your_prompt_id', {
  inputs: { name: 'John', topic: 'TypeScript' }
});
console.log(result.prompt);

Authentication

The SDK requires an API key for authentication. You can obtain an API key from your PromptOS dashboard.

API keys come in two types:

• Live keys (mpa_live_...): For production use
• Test keys (mpa_test_...): For development and testing

// Production client
const client = new PromptOSClient({
  apiKey: 'mpa_live_...'
});

// Development client  
const client = new PromptOSClient({
  apiKey: 'mpa_test_...'
});

Client Configuration

You can customize the client behavior:

const client = new PromptOSClient({
  apiKey: 'mpa_live_...',
  baseUrl: 'http://localhost:3001',  // Custom API endpoint
  timeout: 60000,                    // Request timeout in milliseconds
  maxRetries: 5                      // Number of retries for failed requests
});

API Reference

Prompts

List Prompts

List all prompts in your organization with pagination support.

// Basic usage
const prompts = await client.prompts.list();

// With pagination
const prompts = await client.prompts.list({ page: 2, limit: 50 });

// Access results
for (const prompt of prompts.data) {
  console.log(`ID: ${prompt.id}`);
  console.log(`Title: ${prompt.title}`);
  console.log(`Tags: ${prompt.tags}`);
  if (prompt.latestVersion) {
    console.log(`Latest version: v${prompt.latestVersion.version}`);
  }
}

Get Prompt Details

Retrieve detailed information about a specific prompt, including all versions.

const prompt = await client.prompts.get('prompt_id_here');

console.log(`Prompt: ${prompt.title}`);
console.log(`Description: ${prompt.description}`);
console.log(`Alias: ${prompt.alias}`);
console.log(`Number of versions: ${prompt.versions.length}`);

// Access version history
for (const version of prompt.versions) {
  console.log(`Version ${version.version}: ${version.status}`);
  console.log(`Content: ${version.content}`);
  if (version.variables) {
    console.log(`Variables:`, version.variables);
  }
}

Render Prompt

Render a prompt with the latest published version.

// Render by ID
const result = await client.prompts.render('prompt_id_here', {
  inputs: {
    name: 'Alice',
    product: 'PromptOS',
    feature: 'SDK'
  }
});

console.log(result.prompt);  // The rendered prompt text
console.log(`Version used: ${result.metadata.version}`);
console.log(`Variables used: ${result.metadata.variables}`);

// Render by alias
const result = await client.prompts.renderByAlias('welcome-email', {
  inputs: { name: 'Bob' }
});

Error Handling

The SDK provides specific exception types for different error scenarios:

import {
  PromptOSError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ServerError
} from '@promptos.dev/sdk';

try {
  const result = await client.prompts.render('invalid_id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error(`Authentication failed: ${error.message}`);
    console.error(`Status code: ${error.statusCode}`);
  } else if (error instanceof NotFoundError) {
    console.error(`Prompt not found: ${error.message}`);
  } else if (error instanceof ValidationError) {
    console.error(`Invalid request: ${error.message}`);
    console.error(`Details:`, error.response);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limit exceeded: ${error.message}`);
  } else if (error instanceof ServerError) {
    console.error(`Server error: ${error.message}`);
  } else if (error instanceof PromptOSError) {
    console.error(`General error: ${error.message}`);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type safety:

import type {
  Prompt,
  PromptDetail,
  PromptVersion,
  PromptListResponse,
  PromptRenderResponse,
  PromptRenderRequest
} from '@promptos.dev/sdk';

// All responses are fully typed
const prompts: PromptListResponse = await client.prompts.list();
const prompt: PromptDetail = await client.prompts.get('id');
const result: PromptRenderResponse = await client.prompts.render('id', {
  inputs: { /* typed inputs */ }
});

Examples

See the examples/ directory for more detailed examples:

• basic-usage.ts: Basic operations
• prompt-rendering.ts: Advanced rendering examples
• error-handling.ts: Comprehensive error handling

Development

Running Tests

# Install dependencies
npm install

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Building

npm run build

Type Checking

npm run typecheck

Linting

npm run lint
npm run lint:fix

Browser Support

This SDK uses the Fetch API and is compatible with:

• Node.js 18+
• Modern browsers (Chrome, Firefox, Safari, Edge)
• Any environment with Fetch API support

For older environments, you may need to provide a Fetch polyfill.

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://docs.promptos.dev
• API Reference: https://api.promptos.dev
• Issues: https://github.com/promptos/typescript-sdk/issues