@to11ai/sdk 0.0.2

package/dist/gateway.d.ts

@@ -0,0 +1,22 @@
+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 declare function gatewayAuthHeaders(options: GatewayAuthOptions): Record<string, string>;
+/**
+ * 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 declare function gatewayPromptHeaders(prompt: ResolvedPrompt): Record<string, string>;

package/dist/gateway.js

@@ -0,0 +1,27 @@
+// src/gateway.ts
+function gatewayAuthHeaders(options) {
+  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
+  };
+}
+function gatewayPromptHeaders(prompt) {
+  const headers = {
+    "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;
+}
+export {
+  gatewayPromptHeaders,
+  gatewayAuthHeaders
+};

package/dist/prompts/cache.d.ts

@@ -0,0 +1,38 @@
+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;
+}
+/**
+ * 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 declare function buildCacheKey(projectId: string, slug: string, labels: string[], variables?: Record<string, unknown>): string;
+/**
+ * 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 declare class PromptCache {
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly store;
+    constructor(config?: CacheConfig);
+    get(key: string): ResolvedPrompt | undefined;
+    set(key: string, value: ResolvedPrompt): void;
+    delete(key: string): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/prompts/resource.cjs

@@ -0,0 +1,160 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/prompts/resource.ts
+var exports_resource = {};
+__export(exports_resource, {
+  PromptResource: () => PromptResource
+});
+module.exports = __toCommonJS(exports_resource);
+var import_errors = require("../errors");
+var import_cache = require("./cache");
+function unwrap(envelope) {
+  if (envelope.data === null || envelope.data === undefined) {
+    throw new Error("API returned success but data is null");
+  }
+  return envelope.data;
+}
+function getProjectPromptsPath(projectId) {
+  return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
+}
+function getProjectPromptPath(projectId, promptId) {
+  return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
+}
+
+class PromptResource {
+  transport;
+  cache;
+  constructor(transport, cacheConfig) {
+    this.transport = transport;
+    this.cache = new import_cache.PromptCache(cacheConfig);
+  }
+  async create(input) {
+    const { projectId, ...body } = input;
+    const envelope = await this.transport.request("POST", getProjectPromptsPath(projectId), { body });
+    return unwrap(envelope);
+  }
+  async list(input) {
+    const { projectId, ...queryRest } = input;
+    const envelope = await this.transport.request("GET", getProjectPromptsPath(projectId), {
+      query: {
+        ...queryRest
+      }
+    });
+    const raw = unwrap(envelope);
+    const items = Array.isArray(raw) ? raw : 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 };
+  }
+  async get(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("GET", getProjectPromptPath(projectId, promptId));
+    return unwrap(envelope);
+  }
+  async update(input) {
+    const { projectId, promptId, ...body } = input;
+    const envelope = await this.transport.request("PATCH", getProjectPromptPath(projectId, promptId), { body });
+    return unwrap(envelope);
+  }
+  async archive(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("DELETE", getProjectPromptPath(projectId, promptId));
+    return unwrap(envelope);
+  }
+  async createVersion(input) {
+    const { projectId, promptId, ...body } = input;
+    const envelope = await this.transport.request("POST", `${getProjectPromptPath(projectId, promptId)}/versions`, { body });
+    return unwrap(envelope);
+  }
+  async listVersions(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/versions`);
+    return unwrap(envelope);
+  }
+  async getVersion(input) {
+    const { projectId, promptId, versionNumber } = input;
+    const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/versions/${encodeURIComponent(String(versionNumber))}`);
+    return unwrap(envelope);
+  }
+  async moveLabel(input) {
+    const { projectId, promptId, label, ...body } = input;
+    const envelope = await this.transport.request("PUT", `${getProjectPromptPath(projectId, promptId)}/labels/${encodeURIComponent(label)}`, { body });
+    return unwrap(envelope);
+  }
+  async listLabels(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
+    return unwrap(envelope);
+  }
+  async resolve(input) {
+    const {
+      projectId,
+      slug,
+      labels,
+      variables,
+      cache: useCache = true,
+      fallback
+    } = input;
+    const cacheKey = import_cache.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("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 (err instanceof import_errors.To11aiNetworkError && fallback !== undefined) {
+        return fallback;
+      }
+      throw err;
+    }
+  }
+}

package/dist/prompts/resource.d.ts

@@ -0,0 +1,21 @@
+import type { Transport } from "../transport";
+import type { CacheConfig } 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";
+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";
+export declare class PromptResource {
+    private readonly transport;
+    private readonly cache;
+    constructor(transport: Transport, cacheConfig?: CacheConfig);
+    create(input: CreatePromptInput): Promise<CreatePromptResult>;
+    list(input: ListPromptsInput): Promise<PaginatedResult<ListPromptsResult>>;
+    get(input: GetPromptInput): Promise<GetPromptResult>;
+    update(input: UpdatePromptInput): Promise<UpdatePromptResult>;
+    archive(input: ArchivePromptInput): Promise<ArchivePromptResult>;
+    createVersion(input: CreatePromptVersionInput): Promise<CreatePromptVersionResult>;
+    listVersions(input: ListPromptVersionsInput): Promise<ListPromptVersionsResult>;
+    getVersion(input: GetPromptVersionInput): Promise<GetPromptVersionResult>;
+    moveLabel(input: MovePromptLabelInput): Promise<MovePromptLabelResult>;
+    listLabels(input: ListPromptLabelsInput): Promise<ListPromptLabelsResult>;
+    resolve(input: ResolvePromptInput): Promise<ResolvePromptResult>;
+}

package/dist/prompts/resource.js

@@ -0,0 +1,120 @@
+// src/prompts/resource.ts
+import { To11aiNetworkError } from "../errors";
+import { buildCacheKey, PromptCache } from "./cache";
+function unwrap(envelope) {
+  if (envelope.data === null || envelope.data === undefined) {
+    throw new Error("API returned success but data is null");
+  }
+  return envelope.data;
+}
+function getProjectPromptsPath(projectId) {
+  return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
+}
+function getProjectPromptPath(projectId, promptId) {
+  return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
+}
+
+class PromptResource {
+  transport;
+  cache;
+  constructor(transport, cacheConfig) {
+    this.transport = transport;
+    this.cache = new PromptCache(cacheConfig);
+  }
+  async create(input) {
+    const { projectId, ...body } = input;
+    const envelope = await this.transport.request("POST", getProjectPromptsPath(projectId), { body });
+    return unwrap(envelope);
+  }
+  async list(input) {
+    const { projectId, ...queryRest } = input;
+    const envelope = await this.transport.request("GET", getProjectPromptsPath(projectId), {
+      query: {
+        ...queryRest
+      }
+    });
+    const raw = unwrap(envelope);
+    const items = Array.isArray(raw) ? raw : 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 };
+  }
+  async get(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("GET", getProjectPromptPath(projectId, promptId));
+    return unwrap(envelope);
+  }
+  async update(input) {
+    const { projectId, promptId, ...body } = input;
+    const envelope = await this.transport.request("PATCH", getProjectPromptPath(projectId, promptId), { body });
+    return unwrap(envelope);
+  }
+  async archive(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("DELETE", getProjectPromptPath(projectId, promptId));
+    return unwrap(envelope);
+  }
+  async createVersion(input) {
+    const { projectId, promptId, ...body } = input;
+    const envelope = await this.transport.request("POST", `${getProjectPromptPath(projectId, promptId)}/versions`, { body });
+    return unwrap(envelope);
+  }
+  async listVersions(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/versions`);
+    return unwrap(envelope);
+  }
+  async getVersion(input) {
+    const { projectId, promptId, versionNumber } = input;
+    const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/versions/${encodeURIComponent(String(versionNumber))}`);
+    return unwrap(envelope);
+  }
+  async moveLabel(input) {
+    const { projectId, promptId, label, ...body } = input;
+    const envelope = await this.transport.request("PUT", `${getProjectPromptPath(projectId, promptId)}/labels/${encodeURIComponent(label)}`, { body });
+    return unwrap(envelope);
+  }
+  async listLabels(input) {
+    const { projectId, promptId } = input;
+    const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
+    return unwrap(envelope);
+  }
+  async resolve(input) {
+    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("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 (err instanceof To11aiNetworkError && fallback !== undefined) {
+        return fallback;
+      }
+      throw err;
+    }
+  }
+}
+export {
+  PromptResource
+};

package/dist/prompts/types.d.ts

@@ -0,0 +1,142 @@
+export type PromptStatus = "active" | "archived";
+export type PromptFormat = "text" | "chat";
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+}
+export interface Prompt {
+    id: string;
+    projectId: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    tags: string[];
+    status: PromptStatus;
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PromptVersion {
+    id: string;
+    promptId: string;
+    version: number;
+    format: PromptFormat;
+    templateJson: unknown;
+    variablesSchema: unknown;
+    modelConfig: unknown;
+    changelog: string | null;
+    createdByUserId: string;
+    createdAt: string;
+}
+export interface PromptLabelPointer {
+    promptId: string;
+    label: string;
+    versionId: string;
+    updatedByUserId: string;
+    updatedAt: string;
+}
+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;
+}
+export interface PaginationInfo {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+export interface PaginatedResult<T> {
+    items: T[];
+    pagination: PaginationInfo;
+}
+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/dist/transport.d.ts

@@ -0,0 +1,44 @@
+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;
+}
+export declare class Transport {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(config: TransportConfig);
+    private buildHeaders;
+    request<T>(method: string, path: string, options?: {
+        query?: Record<string, string | number | boolean | undefined>;
+        body?: unknown;
+    }): Promise<ApiEnvelope<T>>;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "@to11ai/sdk",
+	"version": "0.0.2",
+	"type": "module",
+	"main": "./dist/client.cjs",
+	"module": "./dist/client.js",
+	"types": "./src/client.ts",
+	"files": [
+		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.fixture.ts",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./src/client.ts",
+			"bun": "./src/client.ts",
+			"deno": "./src/client.ts",
+			"import": "./dist/client.js",
+			"require": "./dist/client.cjs",
+			"default": "./dist/client.js"
+		},
+		"./prompts": {
+			"types": "./src/prompts/resource.ts",
+			"bun": "./src/prompts/resource.ts",
+			"deno": "./src/prompts/resource.ts",
+			"import": "./dist/prompts/resource.js",
+			"require": "./dist/prompts/resource.cjs",
+			"default": "./dist/prompts/resource.js"
+		},
+		"./errors": {
+			"types": "./src/errors.ts",
+			"bun": "./src/errors.ts",
+			"deno": "./src/errors.ts",
+			"import": "./dist/errors.js",
+			"require": "./dist/errors.cjs",
+			"default": "./dist/errors.js"
+		},
+		"./gateway": {
+			"types": "./src/gateway.ts",
+			"bun": "./src/gateway.ts",
+			"deno": "./src/gateway.ts",
+			"import": "./dist/gateway.js",
+			"require": "./dist/gateway.cjs",
+			"default": "./dist/gateway.js"
+		}
+	},
+	"publishConfig": {
+		"access": "restricted"
+	},
+	"scripts": {
+		"build": "bun run build:clean && bun run build:esm && bun run build:cjs && bun run build:types",
+		"build:clean": "rm -rf dist",
+		"build:esm": "bun build src/client.ts src/prompts/resource.ts src/errors.ts src/gateway.ts --outdir dist --target node --format esm --external '*'",
+		"build:cjs": "bun build src/client.ts src/prompts/resource.ts src/errors.ts src/gateway.ts --outdir dist --target node --format cjs --external '*' --entry-naming '[dir]/[name].cjs'",
+		"build:types": "tsc -p tsconfig.build.json",
+		"prepack": "bun run build",
+		"test": "bun test",
+		"typecheck": "bun x tsc --noEmit",
+		"lint": "biome check .",
+		"lint:check": "biome check --error-on-warnings .",
+		"lint:fix": "biome check --fix .",
+		"format": "biome format --write ."
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.15",
+		"@types/bun": "^1.3.13",
+		"typescript": "^5.9.3"
+	}
+}