@to11ai/sdk 0.0.2

package/src/client.ts

@@ -0,0 +1,120 @@
+import type { CacheConfig } from "./prompts/cache";
+import { PromptResource } from "./prompts/resource";
+import { Transport } from "./transport";
+
+// Re-export all error types for convenience
+export {
+	To11aiApiError,
+	To11aiAuthError,
+	To11aiError,
+	To11aiNetworkError,
+	To11aiRateLimitError,
+	To11aiValidationError,
+} from "./errors";
+export type { GatewayAuthOptions } from "./gateway";
+export { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
+export type { CacheConfig } from "./prompts/cache";
+export { PromptResource } from "./prompts/resource";
+export type { Transport } from "./transport";
+
+// ─── Auth option shapes ────────────────────────────────────────────────────
+
+interface ServerAuthOptions {
+	/** API key for server-side use. Must not be used in browser contexts. */
+	apiKey: string;
+	getAccessToken?: never;
+}
+
+interface BrowserAuthOptions {
+	/** Token callback for browser / edge contexts — avoids static secrets. */
+	getAccessToken: () => Promise<string>;
+	apiKey?: never;
+}
+
+type AuthOptions = ServerAuthOptions | BrowserAuthOptions;
+
+// ─── Client options ────────────────────────────────────────────────────────
+
+export type ClientOptions = AuthOptions & {
+	baseUrl: string;
+	/** LRU cache configuration for resolve(). Defaults: ttlSeconds=300, maxEntries=100 */
+	cache?: CacheConfig;
+	/** Request timeout in milliseconds. Default: 30_000 */
+	timeoutMs?: number;
+	/** Max retry attempts for network errors / 5xx. Default: 3 */
+	maxRetries?: number;
+};
+
+// ─── Client interface ──────────────────────────────────────────────────────
+
+export interface To11aiClient {
+	readonly prompts: PromptResource;
+}
+
+// ─── Factory ───────────────────────────────────────────────────────────────
+
+/**
+ * Create a to11ai SDK client.
+ *
+ * Auth mode is inferred from options:
+ *  - `apiKey`          → server-side; rejected in browser contexts.
+ *  - `getAccessToken`  → browser-safe; token fetched per request.
+ */
+export function createClient(options: ClientOptions): To11aiClient {
+	const isDomBrowser =
+		typeof globalThis === "object" &&
+		typeof (globalThis as { document?: unknown }).document !== "undefined";
+	const workerLikeGlobal = globalThis as {
+		Bun?: {
+			isMainThread?: boolean;
+		};
+		importScripts?: unknown;
+		postMessage?: unknown;
+		onmessage?: unknown;
+	};
+	const isBunMainThread = workerLikeGlobal.Bun?.isMainThread === true;
+	const isWorkerBrowser =
+		typeof globalThis === "object" &&
+		(typeof workerLikeGlobal.importScripts === "function" ||
+			(!isBunMainThread &&
+				typeof workerLikeGlobal.postMessage === "function" &&
+				typeof workerLikeGlobal.onmessage !== "undefined"));
+
+	if ((isDomBrowser || isWorkerBrowser) && options.apiKey !== undefined) {
+		throw new Error(
+			"[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.",
+		);
+	}
+
+	if (options.apiKey !== undefined && options.apiKey.trim() === "") {
+		throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
+	}
+
+	// TypeScript's union type prevents callers from providing both, but JS consumers can.
+	// Perform an explicit XOR check at runtime to catch the case where both are supplied.
+	const hasApiKey = options.apiKey !== undefined;
+	const hasGetAccessToken = options.getAccessToken !== undefined;
+	const getAccessToken = options.getAccessToken;
+
+	if (hasApiKey === hasGetAccessToken) {
+		throw new Error(
+			"[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).",
+		);
+	}
+
+	const auth =
+		options.apiKey !== undefined
+			? ({ apiKey: options.apiKey } as const)
+			: ({ getAccessToken: getAccessToken as () => Promise<string> } as const);
+
+	const transport = new Transport({
+		baseUrl: options.baseUrl,
+		auth,
+		timeoutMs: options.timeoutMs,
+		maxRetries: options.maxRetries,
+	});
+
+	const prompts = new PromptResource(transport, options.cache);
+
+	return { prompts };
+}

package/src/errors.ts

@@ -0,0 +1,91 @@
+/**
+ * Base class for all @to11ai/sdk errors.
+ */
+export class To11aiError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "To11aiError";
+		// Maintain proper prototype chain in environments that transpile class syntax
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}
+
+/**
+ * Thrown when the API returns a non-2xx response with an error envelope.
+ */
+export class To11aiApiError extends To11aiError {
+	readonly statusCode: number;
+	readonly errorCode: string | undefined;
+	readonly details: unknown;
+
+	constructor(
+		message: string,
+		statusCode: number,
+		errorCode?: string,
+		details?: unknown,
+	) {
+		super(message);
+		this.name = "To11aiApiError";
+		this.statusCode = statusCode;
+		this.errorCode = errorCode;
+		this.details = details;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}
+
+/**
+ * Thrown on 400 / schema validation failures.
+ */
+export class To11aiValidationError extends To11aiApiError {
+	constructor(message: string, errorCode?: string, details?: unknown) {
+		super(message, 400, errorCode, details);
+		this.name = "To11aiValidationError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}
+
+/**
+ * Thrown on 401 or 403 responses.
+ */
+export class To11aiAuthError extends To11aiApiError {
+	constructor(
+		message: string,
+		statusCode: 401 | 403,
+		errorCode?: string,
+		details?: unknown,
+	) {
+		super(message, statusCode, errorCode, details);
+		this.name = "To11aiAuthError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}
+
+/**
+ * Thrown on 429 rate limit responses.
+ */
+export class To11aiRateLimitError extends To11aiApiError {
+	readonly retryAfterSeconds: number | undefined;
+
+	constructor(
+		message: string,
+		retryAfterSeconds?: number,
+		errorCode?: string,
+		details?: unknown,
+	) {
+		super(message, 429, errorCode, details);
+		this.name = "To11aiRateLimitError";
+		this.retryAfterSeconds = retryAfterSeconds;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}
+
+/**
+ * Thrown on network failure or request timeout.
+ */
+export class To11aiNetworkError extends To11aiError {
+	constructor(message: string, cause?: unknown) {
+		super(message, { cause });
+		this.name = "To11aiNetworkError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}

package/src/gateway.ts

@@ -0,0 +1,49 @@
+import type { ResolvedPrompt } from "./prompts/types";
+
+export interface GatewayAuthOptions {
+	apiKey: string;
+	projectId: string;
+}
+
+/**
+ * Build the auth headers required for every request through the to11 gateway.
+ *
+ * @example
+ * const headers = gatewayAuthHeaders({ apiKey, projectId });
+ */
+export function gatewayAuthHeaders(
+	options: GatewayAuthOptions,
+): Record<string, string> {
+	if (options.apiKey.trim().length === 0) {
+		throw new Error("[to11ai/sdk] `apiKey` must not be empty.");
+	}
+	if (options.projectId.trim().length === 0) {
+		throw new Error("[to11ai/sdk] `projectId` must not be empty.");
+	}
+	return {
+		"x-to11-authorization": `Bearer ${options.apiKey}`,
+		"x-to11-project-id": options.projectId,
+	};
+}
+
+/**
+ * Build prompt provenance headers from a resolved prompt.
+ * Omits `x-to11-prompt-labels` when the prompt has no labels,
+ * since the gateway rejects empty header values.
+ *
+ * @example
+ * const prompt = await client.prompts.resolve({ slug, labels });
+ * const headers = gatewayPromptHeaders(prompt);
+ */
+export function gatewayPromptHeaders(
+	prompt: ResolvedPrompt,
+): Record<string, string> {
+	const headers: Record<string, string> = {
+		"x-to11-prompt-id": prompt.promptId,
+		"x-to11-prompt-version": String(prompt.version),
+	};
+	if (prompt.labels.length > 0) {
+		headers["x-to11-prompt-labels"] = prompt.labels.join(",");
+	}
+	return headers;
+}

package/src/prompts/cache.ts

@@ -0,0 +1,122 @@
+import type { ResolvedPrompt } from "./types";
+
+export interface CacheConfig {
+	/** Time-to-live in seconds. Default: 300 (5 minutes) */
+	ttlSeconds?: number;
+	/** Maximum number of entries. Default: 100 */
+	maxEntries?: number;
+}
+
+interface CacheEntry {
+	value: ResolvedPrompt;
+	expiresAt: number;
+}
+
+/**
+ * Build a canonical cache key for a resolve() call.
+ *
+ * - projectId is included to prevent cross-project cache collisions: a single
+ *   PromptResource can serve multiple projects, so the same slug+labels must
+ *   not share a cache entry across different projects.
+ * - Labels are sorted alphabetically so ["production", "en"] and ["en", "production"]
+ *   map to the same key.
+ * - Variables are canonicalized with deterministic sorted-keys JSON before hashing.
+ * - Each segment is JSON-encoded so that separator characters in slug or label
+ *   values cannot cause key collisions (e.g. a slug containing "|" or ",").
+ */
+export function buildCacheKey(
+	projectId: string,
+	slug: string,
+	labels: string[],
+	variables?: Record<string, unknown>,
+): string {
+	const sortedLabels = [...labels].sort();
+	const varsPart =
+		variables !== undefined ? JSON.stringify(sortObjectKeys(variables)) : null;
+	// JSON.stringify each segment to prevent separator-character collisions
+	return `${JSON.stringify(projectId)}|${JSON.stringify(slug)}|${JSON.stringify(sortedLabels)}|${JSON.stringify(varsPart)}`;
+}
+
+function sortObjectKeys(obj: unknown): unknown {
+	if (obj === null || typeof obj !== "object") return obj;
+	if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+	const sorted: Record<string, unknown> = {};
+	for (const key of Object.keys(obj as Record<string, unknown>).sort()) {
+		sorted[key] = sortObjectKeys((obj as Record<string, unknown>)[key]);
+	}
+	return sorted;
+}
+
+/**
+ * In-memory LRU cache for ResolvedPrompt objects.
+ *
+ * Uses a Map (insertion-ordered) as the backing store. On every access, the
+ * entry is deleted and re-inserted to maintain LRU order — oldest entries sit
+ * at the front of the Map.
+ */
+export class PromptCache {
+	private readonly ttlMs: number;
+	private readonly maxEntries: number;
+	private readonly store: Map<string, CacheEntry>;
+
+	constructor(config?: CacheConfig) {
+		this.ttlMs = (config?.ttlSeconds ?? 300) * 1000;
+		this.maxEntries = config?.maxEntries ?? 100;
+		this.store = new Map();
+	}
+
+	get(key: string): ResolvedPrompt | undefined {
+		const entry = this.store.get(key);
+		if (!entry) return undefined;
+
+		if (Date.now() > entry.expiresAt) {
+			this.store.delete(key);
+			return undefined;
+		}
+
+		// Refresh LRU order — move to end
+		this.store.delete(key);
+		this.store.set(key, entry);
+
+		return entry.value;
+	}
+
+	set(key: string, value: ResolvedPrompt): void {
+		// maxEntries: 0 (or negative) means caching is disabled — drop the entry.
+		if (this.maxEntries <= 0) {
+			return;
+		}
+
+		// Remove existing entry so re-insertion moves it to the end
+		if (this.store.has(key)) {
+			this.store.delete(key);
+		}
+
+		// Evict least-recently-used entry if at capacity
+		while (this.store.size >= this.maxEntries) {
+			const lruKey = this.store.keys().next().value;
+			if (lruKey !== undefined) {
+				this.store.delete(lruKey);
+			} else {
+				break;
+			}
+		}
+
+		this.store.set(key, {
+			value,
+			expiresAt: Date.now() + this.ttlMs,
+		});
+	}
+
+	delete(key: string): void {
+		this.store.delete(key);
+	}
+
+	clear(): void {
+		this.store.clear();
+	}
+
+	get size(): number {
+		return this.store.size;
+	}
+}

package/src/prompts/resource.ts

@@ -0,0 +1,279 @@
+import { To11aiNetworkError } from "../errors";
+import type { ApiEnvelope, Transport } from "../transport";
+import type { CacheConfig } from "./cache";
+import { buildCacheKey, PromptCache } from "./cache";
+import type {
+	ArchivePromptInput,
+	ArchivePromptResult,
+	CreatePromptInput,
+	CreatePromptResult,
+	CreatePromptVersionInput,
+	CreatePromptVersionResult,
+	GetPromptInput,
+	GetPromptResult,
+	GetPromptVersionInput,
+	GetPromptVersionResult,
+	ListPromptLabelsInput,
+	ListPromptLabelsResult,
+	ListPromptsInput,
+	ListPromptsResult,
+	ListPromptVersionsInput,
+	ListPromptVersionsResult,
+	MovePromptLabelInput,
+	MovePromptLabelResult,
+	PaginatedResult,
+	ResolvePromptInput,
+	ResolvePromptResult,
+	UpdatePromptInput,
+	UpdatePromptResult,
+} from "./types";
+
+// Re-export CacheConfig so callers can import from this module
+export type { CacheConfig } from "./cache";
+export type {
+	ArchivePromptInput,
+	ArchivePromptResult,
+	ChatMessage,
+	CreatePromptInput,
+	CreatePromptResult,
+	CreatePromptVersionInput,
+	CreatePromptVersionResult,
+	GetPromptInput,
+	GetPromptResult,
+	GetPromptVersionInput,
+	GetPromptVersionResult,
+	ListPromptLabelsInput,
+	ListPromptLabelsResult,
+	ListPromptsInput,
+	ListPromptsResult,
+	ListPromptVersionsInput,
+	ListPromptVersionsResult,
+	MovePromptLabelInput,
+	MovePromptLabelResult,
+	PaginatedResult,
+	PaginationInfo,
+	Prompt,
+	PromptFormat,
+	PromptLabelPointer,
+	PromptStatus,
+	PromptVersion,
+	RenderedPrompt,
+	ResolvedPrompt,
+	ResolvePromptInput,
+	ResolvePromptResult,
+	UpdatePromptInput,
+	UpdatePromptResult,
+} from "./types";
+
+function unwrap<T>(envelope: ApiEnvelope<T>): T {
+	if (envelope.data === null || envelope.data === undefined) {
+		throw new Error("API returned success but data is null");
+	}
+	return envelope.data;
+}
+
+function getProjectPromptsPath(projectId: string): string {
+	return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
+}
+
+function getProjectPromptPath(projectId: string, promptId: string): string {
+	return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
+}
+
+export class PromptResource {
+	private readonly transport: Transport;
+	private readonly cache: PromptCache;
+
+	constructor(transport: Transport, cacheConfig?: CacheConfig) {
+		this.transport = transport;
+		this.cache = new PromptCache(cacheConfig);
+	}
+
+	// ─── Create ──────────────────────────────────────────────────────────────
+
+	async create(input: CreatePromptInput): Promise<CreatePromptResult> {
+		const { projectId, ...body } = input;
+		const envelope = await this.transport.request<CreatePromptResult>(
+			"POST",
+			getProjectPromptsPath(projectId),
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── List ─────────────────────────────────────────────────────────────────
+
+	async list(
+		input: ListPromptsInput,
+	): Promise<PaginatedResult<ListPromptsResult>> {
+		const { projectId, ...queryRest } = input;
+		const envelope = await this.transport.request<
+			| ListPromptsResult[]
+			| {
+					items?: ListPromptsResult[];
+					pagination?: PaginatedResult<ListPromptsResult>["pagination"];
+			  }
+		>("GET", getProjectPromptsPath(projectId), {
+			query: {
+				...(queryRest as Record<string, string | number | boolean | undefined>),
+			},
+		});
+
+		const raw = unwrap(envelope);
+		// The server may return a top-level array or a { items, pagination } shape
+		const items = Array.isArray(raw)
+			? (raw as ListPromptsResult[])
+			: (raw.items ?? []);
+		const pagination = envelope.pagination ??
+			(Array.isArray(raw) ? undefined : raw.pagination) ?? {
+				page: 1,
+				limit: items.length,
+				total: items.length,
+				totalPages: 1,
+			};
+
+		return { items, pagination };
+	}
+
+	// ─── Get ──────────────────────────────────────────────────────────────────
+
+	async get(input: GetPromptInput): Promise<GetPromptResult> {
+		const { projectId, promptId } = input;
+		const envelope = await this.transport.request<GetPromptResult>(
+			"GET",
+			getProjectPromptPath(projectId, promptId),
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Update ───────────────────────────────────────────────────────────────
+
+	async update(input: UpdatePromptInput): Promise<UpdatePromptResult> {
+		const { projectId, promptId, ...body } = input;
+		const envelope = await this.transport.request<UpdatePromptResult>(
+			"PATCH",
+			getProjectPromptPath(projectId, promptId),
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Archive ──────────────────────────────────────────────────────────────
+
+	async archive(input: ArchivePromptInput): Promise<ArchivePromptResult> {
+		const { projectId, promptId } = input;
+		const envelope = await this.transport.request<ArchivePromptResult>(
+			"DELETE",
+			getProjectPromptPath(projectId, promptId),
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Create Version ───────────────────────────────────────────────────────
+
+	async createVersion(
+		input: CreatePromptVersionInput,
+	): Promise<CreatePromptVersionResult> {
+		const { projectId, promptId, ...body } = input;
+		const envelope = await this.transport.request<CreatePromptVersionResult>(
+			"POST",
+			`${getProjectPromptPath(projectId, promptId)}/versions`,
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── List Versions ────────────────────────────────────────────────────────
+
+	async listVersions(
+		input: ListPromptVersionsInput,
+	): Promise<ListPromptVersionsResult> {
+		const { projectId, promptId } = input;
+		const envelope = await this.transport.request<ListPromptVersionsResult>(
+			"GET",
+			`${getProjectPromptPath(projectId, promptId)}/versions`,
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Get Version ──────────────────────────────────────────────────────────
+
+	async getVersion(
+		input: GetPromptVersionInput,
+	): Promise<GetPromptVersionResult> {
+		const { projectId, promptId, versionNumber } = input;
+		const envelope = await this.transport.request<GetPromptVersionResult>(
+			"GET",
+			`${getProjectPromptPath(projectId, promptId)}/versions/${encodeURIComponent(String(versionNumber))}`,
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Move Label ───────────────────────────────────────────────────────────
+
+	async moveLabel(input: MovePromptLabelInput): Promise<MovePromptLabelResult> {
+		const { projectId, promptId, label, ...body } = input;
+		const envelope = await this.transport.request<MovePromptLabelResult>(
+			"PUT",
+			`${getProjectPromptPath(projectId, promptId)}/labels/${encodeURIComponent(label)}`,
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── List Labels ──────────────────────────────────────────────────────────
+
+	async listLabels(
+		input: ListPromptLabelsInput,
+	): Promise<ListPromptLabelsResult> {
+		const { projectId, promptId } = input;
+		const envelope = await this.transport.request<ListPromptLabelsResult>(
+			"GET",
+			`${getProjectPromptPath(projectId, promptId)}/labels`,
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Resolve ──────────────────────────────────────────────────────────────
+
+	async resolve(input: ResolvePromptInput): Promise<ResolvePromptResult> {
+		const {
+			projectId,
+			slug,
+			labels,
+			variables,
+			cache: useCache = true,
+			fallback,
+		} = input;
+
+		const cacheKey = buildCacheKey(projectId, slug, labels, variables);
+
+		if (useCache) {
+			const cached = this.cache.get(cacheKey);
+			if (cached) return structuredClone(cached);
+		}
+
+		try {
+			const envelope = await this.transport.request<ResolvePromptResult>(
+				"POST",
+				`${getProjectPromptsPath(projectId)}:resolve`,
+				{
+					body: { slug, labels, variables },
+				},
+			);
+			const result = unwrap(envelope);
+
+			if (useCache) {
+				this.cache.set(cacheKey, structuredClone(result));
+			}
+
+			return result;
+		} catch (err) {
+			// If network error and we have a fallback, serve it
+			if (err instanceof To11aiNetworkError && fallback !== undefined) {
+				return fallback;
+			}
+			throw err;
+		}
+	}
+}