Teleprompter SDK

Teleprompter SDK is a TypeScript/JavaScript client library that enables developers to work with prompt management APIs and infrastructure provided by the Teleprompter platform. The SDK offers utilities to interact with Teleprompter APIs either over HTTP or by fetching and rendering prompt templates stored directly in a Cloudflare KV namespace, making it suitable for backend as well as edge/serverless environments.

Concepts

Immutable updates

• Prompts are versioned and append-only. Each write creates a new version; existing versions never change.
• You can list a prompt’s history with getPromptVersions(id) and target a prior version with rollbackPrompt(id, version).
• This model preserves auditability and makes rollbacks predictable.

Versioning system

• Each prompt version is the UNIX timestamp (UTC) at the moment the version is created.
• Versions increase over time for a given prompt.
• Versions are assigned automatically by the service; clients do not choose version numbers.

Update messaging

• For queue-based workflows, publish updates with Teleprompter.UpdateMessage({ id, prompt, version }) and deletions with Teleprompter.DeleteMessage(id).
• A queue consumer applies changes by calling Teleprompter.HandleUpdates(batch, env, ctx), which writes updates to the PROMPTS KV namespace or deletes keys.
• Running applications that read from KV see the latest prompt on their next fetch; no restart is required.

// Publish an update
const msg = Teleprompter.UpdateMessage({
  id: 'welcome-email',
  prompt: 'Welcome, {{name}}!',
  version: 1731166505 // UNIX timestamp (UTC)
})
await queue.send(msg)

// Apply updates in a Worker queue consumer
export default {
  async queue(batch, env, ctx) {
    await Teleprompter.HandleUpdates(batch, env, ctx)
  }
}
Copy

Caching

• The KV client reads prompt data by ID and renders with Mustache at the edge for low latency.
• Cloudflare KV is eventually consistent; updates propagate quickly but are not instantaneous. Design caches to tolerate brief propagation delays.
• If you add an application cache, key entries by id and version. Evict or refresh when a newer version is written. The SDK does not add an extra in-memory cache.

Clients

The library exposes two primary client types, targeting different use cases and environments:

1. HTTP Client

The HTTP client is designed to interact with a Teleprompter REST API server. It provides methods to list, read, update, and version prompt templates managed by your service. The API is intended for situations where you have a remote prompt registry or require centralized management (for example, enterprise APIs or development/CI/CD environments).

When should you use the HTTP client?

• When you want to remotely manage, version, and audit your LLM prompt templates.
• If you are consuming prompts from an API that tracks prompt history and provides workflow integrations.
• In backend services, CI pipelines, or anywhere you want programmatic access to Teleprompter's HTTP API.

2. KV Client

The KV client wraps access to a Cloudflare KV namespace that stores prompt templates. It is focused on scenarios where you want fast, serverless environment interpolation and rendering. The client seamlessly integrates with Mustache to interpolate variables directly on the edge, returning the generated prompt text.

When should you use the KV client?

• When deploying prompt templates for use in Cloudflare Workers, edge runtimes, or similar environments.
• For ultra-low latency, low-overhead rendering of prompts with runtime data.
• As a companion to the HTTP registry: prompts may be published from HTTP to KV for global, performant access.

This dual-client approach gives you flexibility to manage, distribute, and consume LLM prompts in a way that matches your architecture and runtime needs.

---

Installation

bun add teleprompter-sdk
# or
npm install teleprompter-sdk
Copy

---

Documentation

Full API documentation is available at https://britt.github.io/teleprompter-sdk/

---

Usage Examples

HTTP Client Example

Create an HTTP instance with either a base URL or a Fetcher binding. The client implements methods for listing, retrieving, updating, and managing prompt templates remotely.

import Teleprompter from 'teleprompter-sdk';

const client = new Teleprompter.HTTP('https://api.example.com');

// List all prompts
const prompts = await client.listPrompts();

// Retrieve a prompt's latest version
const prompt = await client.getPrompt('welcome-email');

// Update or create a prompt
await client.writePrompt({ id: 'welcome-email', prompt: 'Welcome, {{name}}!' });

// Roll back a prompt to a previous version
await client.rollbackPrompt('welcome-email', 1731166505); // UNIX timestamp (UTC)
Copy

Advanced: Using a Fetcher Binding

If you're running in an environment like Cloudflare Workers, you can pass a custom Fetcher (usually a service binding or mock object) to abstract the request layer:

const client = new Teleprompter.HTTP(env.API);
Copy

---

Rendering Prompts from KV

The KV client allows you to fetch templates from a Cloudflare KV namespace and render them directly with runtime context using Mustache.

const kv = new Teleprompter.KV(env);
const output = await kv.render('welcome-email', { name: 'Ada' });
Copy

This looks up the welcome-email prompt template in the PROMPTS namespace and renders it with the supplied context, returning the final text. This is ideal for edge/serverless workloads.

---

Scripts

• bun run build – Compile TypeScript source
• bun test – Run unit tests
• bun test --coverage – Run tests with coverage report
• bun run docs – Generate TypeDoc documentation to the docs/ folder

Continuous integration automatically runs tests on every pull request.

---

Development

This project uses Bun as its runtime and package manager.

Install dependencies:

bun install
Copy

Run tests:

bun test
Copy

Generate documentation:

bun run docs
Copy

Documentation is automatically published to GitHub Pages from the docs/ directory.

---

Co-authors

• doc.holiday

---

License

This project is licensed under the MIT License.