AI Prompt Bucket — TypeScript SDK

TypeScript SDK for AI Prompt Bucket, a managed prompt registry for teams.

Installation

npm install aipromptbucket

Configuration

Set environment variables or pass directly to the client:

export AIPROMPTBUCKET_API_KEY="sk-api01-your-key-here"
export AIPROMPTBUCKET_URL="https://aipromptbucket.com"  # optional, this is the default

Quick Start — getPrompt()

The simplest way to use AI Prompt Bucket. One function, no boilerplate:

import { getPrompt } from "aipromptbucket";

// Fetch a rendered prompt
const text = await getPrompt("my-prompt");

// With variables
const text = await getPrompt("my-prompt", { variables: { name: "Alice" } });

// With a specific label
const text = await getPrompt("my-prompt", { label: "staging" });

// With a fallback if the service is unreachable
const text = await getPrompt("my-prompt", { fallback: "You are a helpful assistant." });

// With TTL caching (seconds)
const text = await getPrompt("my-prompt", { ttl: 300 });

Set global defaults so you don't repeat yourself:

import { configure } from "aipromptbucket";

configure({
  apiKey: "sk-api01-...",
  baseUrl: "https://aipromptbucket.com",
  defaultLabel: "production",
  defaultTtl: 300,
});

Using the Full Client

For advanced use cases (creating prompts, managing versions, labels, etc.):

import { Client } from "aipromptbucket";

const client = new Client();

// List all prompts
const result = await client.listPrompts();
if (result.ok) {
  for (const prompt of result.data!) {
    console.log(`${prompt.slug}: ${prompt.name}`);
  }
}

// Get a specific prompt
const prompt = await client.getPrompt("my-prompt");
if (prompt.ok) {
  console.log(prompt.data!.name);
}

// Render a prompt with variables
const rendered = await client.render("my-prompt", {
  variables: { name: "World" },
});
if (rendered.ok) {
  console.log(rendered.data!.rendered_text);
}

// Create a new prompt
const created = await client.createPrompt({
  name: "Greeting Prompt",
  slug: "greeting-prompt",
  templateText: "Hello, {{ name }}! You are a {{ role }}.",
  templateFormat: "jinja2",
  tags: ["greetings"],
});

// Promote a version to a label
await client.promote("greeting-prompt", {
  version: 2,
  label: "production",
});

API Reference

All methods return Promise<APIResponse<T>> with fields:

• ok: boolean — whether the request succeeded
• statusCode: number — HTTP status code
• data?: T — response data (when ok is true)
• error?: string — error message (when ok is false)

Prompts

| Method | Description | |---|---| | listPrompts({ tag?, search? }) | List all prompts | | getPrompt(slug) | Get prompt details | | createPrompt(options) | Create a new prompt | | updatePrompt(slug, options) | Update prompt metadata | | deletePrompt(slug) | Delete a prompt |

Versions

| Method | Description | |---|---| | listVersions(slug) | List all versions | | getVersion(slug, versionNumber) | Get specific version | | createVersion(slug, options) | Create a new version |

Rendering

| Method | Description | |---|---| | render(slug, options?) | Render a prompt template |

Labels

| Method | Description | |---|---| | listLabels() | List team labels | | createLabel(options) | Create a team label | | deleteLabel(name) | Delete a team label | | listPromptLabels(slug) | List labels for a prompt | | assignLabel(slug, options) | Assign label to version | | labelImpact(slug) | Analyze change impact |

Promote / Rollback

| Method | Description | |---|---| | promote(slug, { version, label }) | Assign label to a version | | rollback(slug, { label }) | Rollback label to previous version |

Snapshots

| Method | Description | |---|---| | listSnapshots() | List snapshots | | createSnapshot(options) | Create a snapshot | | restoreSnapshot(snapshotId) | Restore a snapshot |

Health & Analysis

| Method | Description | |---|---| | getHealth(slug) | Get prompt health score | | refreshHealth(slug) | Recompute health score | | listAnalysis({ limit? }) | List analysis results | | runAnalysis() | Run new analysis |

System

| Method | Description | |---|---| | healthCheck() | Check API health |

Requirements

• Node.js 18+ (uses native fetch)
• Zero runtime dependencies

License

MIT — Bright Wing Solutions LLC