@to11ai/sdk 0.0.2

package/src/prompts/types.ts

@@ -0,0 +1,202 @@
+// ─── Shared primitives ─────────────────────────────────────────────────────
+
+export type PromptStatus = "active" | "archived";
+export type PromptFormat = "text" | "chat";
+
+export interface ChatMessage {
+	role: "system" | "user" | "assistant" | "tool";
+	content: string;
+}
+
+// ─── Prompt ────────────────────────────────────────────────────────────────
+
+export interface Prompt {
+	id: string;
+	projectId: string;
+	name: string;
+	slug: string;
+	description: string | null;
+	tags: string[];
+	status: PromptStatus;
+	createdByUserId: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+// ─── PromptVersion ─────────────────────────────────────────────────────────
+
+export interface PromptVersion {
+	id: string;
+	promptId: string;
+	version: number;
+	format: PromptFormat;
+	templateJson: unknown;
+	variablesSchema: unknown;
+	modelConfig: unknown;
+	changelog: string | null;
+	createdByUserId: string;
+	createdAt: string;
+}
+
+// ─── PromptLabelPointer ────────────────────────────────────────────────────
+
+export interface PromptLabelPointer {
+	promptId: string;
+	label: string;
+	versionId: string;
+	updatedByUserId: string;
+	updatedAt: string;
+}
+
+// ─── ResolvedPrompt ────────────────────────────────────────────────────────
+
+export type RenderedPrompt =
+	| { format: "text"; text: string }
+	| { format: "chat"; messages: ChatMessage[] };
+
+export interface ResolvedPrompt {
+	promptId: string;
+	versionId: string;
+	version: number;
+	labels: string[];
+	contentHash: string;
+	rendered: RenderedPrompt;
+}
+
+// ─── Pagination ────────────────────────────────────────────────────────────
+
+export interface PaginationInfo {
+	page: number;
+	limit: number;
+	total: number;
+	totalPages: number;
+}
+
+export interface PaginatedResult<T> {
+	items: T[];
+	pagination: PaginationInfo;
+}
+
+// ─── Input types ──────────────────────────────────────────────────────────
+
+export interface CreatePromptInput {
+	projectId: string;
+	name: string;
+	slug: string;
+	description?: string;
+	tags?: string[];
+}
+
+export type CreatePromptResult = Prompt;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ListPromptsInput {
+	projectId: string;
+	status?: PromptStatus;
+	sortBy?: "createdAt" | "updatedAt" | "name";
+	tags?: string;
+	page?: number;
+	limit?: number;
+}
+
+export type ListPromptsResult = Prompt;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface GetPromptInput {
+	projectId: string;
+	promptId: string;
+}
+
+export type GetPromptResult = Prompt;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface UpdatePromptInput {
+	projectId: string;
+	promptId: string;
+	name?: string;
+	description?: string | null;
+	tags?: string[];
+}
+
+export type UpdatePromptResult = Prompt;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ArchivePromptInput {
+	projectId: string;
+	promptId: string;
+}
+
+export type ArchivePromptResult = Prompt;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CreatePromptVersionInput {
+	projectId: string;
+	promptId: string;
+	format: PromptFormat;
+	templateJson: unknown;
+	variablesSchema: unknown;
+	modelConfig?: unknown;
+	changelog?: string;
+}
+
+export type CreatePromptVersionResult = PromptVersion;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ListPromptVersionsInput {
+	projectId: string;
+	promptId: string;
+}
+
+export type ListPromptVersionsResult = PromptVersion[];
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface GetPromptVersionInput {
+	projectId: string;
+	promptId: string;
+	versionNumber: number;
+}
+
+export type GetPromptVersionResult = PromptVersion;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface MovePromptLabelInput {
+	projectId: string;
+	promptId: string;
+	label: string;
+	versionId: string;
+	reason?: string;
+}
+
+export type MovePromptLabelResult = PromptLabelPointer;
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ListPromptLabelsInput {
+	projectId: string;
+	promptId: string;
+}
+
+export type ListPromptLabelsResult = PromptLabelPointer[];
+
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ResolvePromptInput {
+	projectId: string;
+	slug: string;
+	labels: string[];
+	variables?: Record<string, unknown>;
+	/** Set false to bypass the LRU cache for this call. Default: true */
+	cache?: boolean;
+	/** Fallback prompt served if the API is unreachable and cache is empty. */
+	fallback?: ResolvedPrompt;
+}
+
+export type ResolvePromptResult = ResolvedPrompt;

package/src/transport.ts

@@ -0,0 +1,223 @@
+import {
+	To11aiApiError,
+	To11aiAuthError,
+	To11aiNetworkError,
+	To11aiRateLimitError,
+	To11aiValidationError,
+} from "./errors";
+
+export type AuthConfig =
+	| { readonly apiKey: string; readonly getAccessToken?: never }
+	| { readonly getAccessToken: () => Promise<string>; readonly apiKey?: never };
+
+export interface TransportConfig {
+	readonly baseUrl: string;
+	readonly auth: AuthConfig;
+	/** Request timeout in milliseconds. Default: 30_000 */
+	readonly timeoutMs?: number;
+	/** Max number of retries for network errors / 5xx (not counting the initial attempt). Default: 3 */
+	readonly maxRetries?: number;
+}
+
+/** Standard API envelope returned by the to11ai server. */
+export interface ApiEnvelope<T = unknown> {
+	readonly success: boolean;
+	readonly code: number;
+	readonly data: T | null;
+	readonly error: { code?: string; message: string; details?: unknown } | null;
+	readonly pagination: {
+		readonly page: number;
+		readonly limit: number;
+		readonly total: number;
+		readonly totalPages: number;
+	} | null;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+
+/** Exponential backoff with jitter: 100ms * 2^attempt + random(0,100ms) */
+const backoffMs = (attempt: number): number =>
+	100 * 2 ** attempt + Math.random() * 100;
+
+const sleep = (ms: number) =>
+	new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Map HTTP status codes and error envelopes to typed SDK errors.
+ */
+function mapHttpError(
+	status: number,
+	envelope: { code?: string; message?: string; details?: unknown } | null,
+	rawMessage: string,
+	headers?: Headers,
+): To11aiApiError {
+	const message = envelope?.message ?? rawMessage;
+	const errorCode = envelope?.code;
+	const details = envelope?.details;
+
+	if (status === 401 || status === 403) {
+		return new To11aiAuthError(
+			message,
+			status as 401 | 403,
+			errorCode,
+			details,
+		);
+	}
+	if (status === 429) {
+		const retryAfterHeader = headers?.get("retry-after");
+		const retryAfterSeconds = retryAfterHeader
+			? Number(retryAfterHeader)
+			: undefined;
+		return new To11aiRateLimitError(
+			message,
+			Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
+			errorCode,
+			details,
+		);
+	}
+	if (status === 400) {
+		return new To11aiValidationError(message, errorCode, details);
+	}
+	return new To11aiApiError(message, status, errorCode, details);
+}
+
+export class Transport {
+	private readonly baseUrl: string;
+	private readonly auth: AuthConfig;
+	private readonly timeoutMs: number;
+	private readonly maxRetries: number;
+
+	constructor(config: TransportConfig) {
+		this.baseUrl = config.baseUrl.replace(/\/$/, "");
+		this.auth = config.auth;
+		this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+	}
+
+	private async buildHeaders(): Promise<Record<string, string>> {
+		const headers: Record<string, string> = {
+			"content-type": "application/json",
+			accept: "application/json",
+		};
+
+		if (this.auth.apiKey !== undefined) {
+			headers.authorization = `Bearer ${this.auth.apiKey}`;
+		} else if (this.auth.getAccessToken) {
+			const token = await this.auth.getAccessToken();
+			headers.authorization = `Bearer ${token}`;
+		}
+
+		return headers;
+	}
+
+	async request<T>(
+		method: string,
+		path: string,
+		options?: {
+			query?: Record<string, string | number | boolean | undefined>;
+			body?: unknown;
+		},
+	): Promise<ApiEnvelope<T>> {
+		const url = new URL(this.baseUrl + path);
+
+		if (options?.query) {
+			for (const [key, value] of Object.entries(options.query)) {
+				if (value !== undefined) {
+					url.searchParams.set(key, String(value));
+				}
+			}
+		}
+
+		let attempt = 0;
+
+		while (true) {
+			const headers = await this.buildHeaders();
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+
+			try {
+				const response = await fetch(url.toString(), {
+					method,
+					headers,
+					body:
+						options?.body !== undefined
+							? JSON.stringify(options.body)
+							: undefined,
+					signal: controller.signal,
+				});
+
+				clearTimeout(timeoutId);
+
+				// 5xx — retry if we have retries left
+				if (response.status >= 500 && attempt < this.maxRetries) {
+					// Drain the body to free the underlying connection before sleeping
+					await response.body?.cancel().catch(() => undefined);
+					attempt++;
+					await sleep(backoffMs(attempt));
+					continue;
+				}
+
+				let json: ApiEnvelope<T> | undefined;
+				const text = await response.text();
+
+				try {
+					json = JSON.parse(text) as ApiEnvelope<T>;
+				} catch {
+					// Not a JSON body — treat as generic API error
+					throw mapHttpError(
+						response.status,
+						null,
+						text || response.statusText,
+						response.headers,
+					);
+				}
+
+				if (!response.ok) {
+					throw mapHttpError(
+						response.status,
+						json?.error ?? null,
+						json?.error?.message ?? response.statusText,
+						response.headers,
+					);
+				}
+
+				return json;
+			} catch (err) {
+				clearTimeout(timeoutId);
+
+				// Re-throw typed SDK errors immediately (no retry)
+				if (err instanceof To11aiApiError) {
+					throw err;
+				}
+
+				// Timeout / network errors — retry if retries remain
+				const isTimeout =
+					err instanceof DOMException && err.name === "AbortError";
+				// Only retry on genuine network failures (fetch throws TypeError) or timeouts.
+				// Unexpected errors (e.g. getAccessToken rejections) propagate immediately.
+				const isNetworkError = err instanceof TypeError;
+
+				if ((isTimeout || isNetworkError) && attempt < this.maxRetries) {
+					attempt++;
+					await sleep(backoffMs(attempt));
+					continue;
+				}
+
+				if (isTimeout) {
+					throw new To11aiNetworkError(
+						`Request timed out after ${this.timeoutMs}ms`,
+						err,
+					);
+				}
+
+				if (isNetworkError) {
+					throw new To11aiNetworkError(`Network error: ${err.message}`, err);
+				}
+
+				// Re-throw unexpected errors (e.g. auth callback failures) as-is
+				throw err;
+			}
+		}
+	}
+}