SDK Reference

new Raison(config)

Creates a new Raison client instance, validates the API key, initializes the in-memory database, and opens a WebSocket connection to the Raison backend.

Throws if:

• config.apiKey is empty or falsy → "API key is required"
• config.apiKey does not start with rsn_ → "Invalid API key format"

// Valid
const raison = new Raison({ apiKey: "rsn_development_abc123" });

// With custom base URL (self-hosted)
const raison = new Raison({
  apiKey: "rsn_production_xyz",
  baseUrl: "https://api.your-domain.com",
});

// Throws — missing key
new Raison({ apiKey: "" }); // Error: API key is required

// Throws — wrong format
new Raison({ apiKey: "sk-abc123" }); // Error: Invalid API key format

Instance Methods

render(promptId, variables?)

Renders a prompt template with the given variables.

Signature: render(promptId: string, variables?: Record<string, unknown>): Promise<string>

Behavior:

Notes:

• Awaits the initial sync before executing. Safe to call immediately after construction.
• Handlebars is compiled with noEscape: true — HTML characters are not escaped.
• Missing variables in the template render as empty strings, not errors.

// Render with variables
const result = await raison.render("prompt-id", { name: "Alice" });

// Render without variables — returns raw template
const raw = await raison.render("prompt-id");

// Non-existent prompt — returns ""
const empty = await raison.render("nonexistent-id", { name: "Alice" });
// → ""

find(params?)

Query the in-memory database for prompts matching the given parameters.

Signature: find(params?: Partial<Prompt>): Promise<Prompt[]>

Behavior:

• No params → returns all prompts deployed to this environment
• Always returns an array. Returns [] if nothing matches. Never returns null.
• Awaits the initial sync before executing.

// All prompts
const all = await raison.find();

// Filter by agentId
const agentPrompts = await raison.find({ agentId: "agent-id" });

// Filter by name
const named = await raison.find({ name: "system-prompt" });

// Filter by version
const v2 = await raison.find({ version: 2 });

// Combined filters
const specific = await raison.find({ agentId: "agent-id", version: 1 });

findOne(params)

Find a single prompt matching the given parameters.

Signature: findOne(params: Partial<Prompt>): Promise<Prompt | null>

Behavior:

• Returns the first matching prompt, or null if none found.
• The composite index on [agentId, name] makes { agentId, name } the most efficient query pattern.
• Awaits the initial sync before executing.

// By ID
const p = await raison.findOne({ id: "prompt-id" });

// By agent + name (uses composite index)
const p = await raison.findOne({ agentId: "agent-id", name: "system-prompt" });

// Returns null if not found
const missing = await raison.findOne({ name: "nonexistent" });
// → null

disconnect()

Closes the WebSocket connection.

Signature: disconnect(): void

Behavior:

• Disconnects the Socket.IO client. Automatic reconnection stops.
• The in-memory database is not cleared — existing data remains readable after disconnect.
• Real-time updates (prompt:deployed events) will not be received after disconnect.

raison.disconnect();

Static Methods

Raison.registerHelper(name, fn)

Register a global Handlebars helper. Available in all prompt templates across all Raison instances.

Signature: registerHelper(name: string, fn: Handlebars.HelperDelegate): void

Notes:

• Helpers are process-global — call this once at startup, not per-request.
• Must be registered before render is called with a template that uses the helper.
• See Templating for helper examples.

Raison.registerHelper("uppercase", (str: string) => str.toUpperCase());
Raison.registerHelper("json", (obj: unknown) => JSON.stringify(obj, null, 2));

Types

interface RaisonConfig {
  apiKey: string;
  baseUrl?: string;
}

interface Prompt {
  id: string;       // Stable unique identifier
  name: string;     // Human-readable name, unique within an agent
  agentId: string;  // ID of the parent agent
  version: number;  // Version number (1, 2, 3, ...)
  content: string;  // Handlebars template content
  variables: string[] // List of variable names available in this prompt
}

Exports

import { Raison } from "raison";            // Main class
import type { RaisonConfig } from "raison";  // Constructor config type
import type { Prompt } from "raison";        // Prompt data type

Error Behavior Summary