@forprompt/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,308 @@
+/**
+ * ForPrompt SDK Types
+ */
+interface ForPromptConfig {
+    /** API key from ForPrompt dashboard (required) */
+    apiKey: string;
+    /** Custom base URL (optional, defaults to https://wooden-fox-811.convex.site) */
+    baseUrl?: string;
+}
+interface Prompt {
+    /** Unique key identifier for the prompt */
+    key: string;
+    /** Display name of the prompt */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Version number */
+    versionNumber: number;
+    /** The system prompt content */
+    systemPrompt: string;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Prompt information fields */
+    purpose?: string;
+    expectedBehavior?: string;
+    inputFormat?: string;
+    outputFormat?: string;
+    constraints?: string;
+    useCases?: string;
+    additionalNotes?: string;
+    toolsNotes?: string;
+}
+interface GetPromptOptions {
+    /** Specific version number to fetch (optional, defaults to active version) */
+    version?: number;
+}
+declare class ForPromptError extends Error {
+    statusCode: number;
+    code: string;
+    constructor(message: string, statusCode: number, code: string);
+}
+
+/**
+ * ForPrompt Client
+ *
+ * Simple usage with auto-configuration:
+ * @example
+ * ```typescript
+ * import { forprompt } from "@forprompt/sdk";
+ *
+ * // Auto-loads from FORPROMPT_API_KEY env variable
+ * const prompt = await forprompt.getPrompt("userContextPrompt");
+ * ```
+ */
+
+/**
+ * Extended client configuration with security options
+ */
+interface ForPromptClientConfig {
+    /** Project API key (required) */
+    apiKey: string;
+    /** Base URL for API (default: https://wooden-fox-811.convex.site) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    retries?: number;
+}
+declare class ForPrompt {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private retries;
+    constructor(config: ForPromptClientConfig | ForPromptConfig | {
+        apiKey: string;
+        baseUrl?: string;
+    });
+    /**
+     * Fetch with timeout support using AbortController
+     */
+    private fetchWithTimeout;
+    /**
+     * Fetch with retry and exponential backoff
+     */
+    private fetchWithRetry;
+    /**
+     * Get a prompt by its key
+     *
+     * @example
+     * ```typescript
+     * const prompt = await forprompt.getPrompt("userContextPrompt");
+     * console.log(prompt.systemPrompt);
+     * ```
+     *
+     * @example With specific version
+     * ```typescript
+     * const prompt = await forprompt.getPrompt("userContextPrompt", { version: 2 });
+     * ```
+     */
+    getPrompt(key: string, options?: GetPromptOptions): Promise<Prompt>;
+    /**
+     * Get multiple prompts by their keys
+     *
+     * Requests are made in parallel with concurrency limit to avoid overwhelming the server.
+     *
+     * @example
+     * ```typescript
+     * const prompts = await forprompt.getPrompts(["userContext", "chatDefault"]);
+     * ```
+     */
+    getPrompts(keys: string[], options?: GetPromptOptions): Promise<Map<string, Prompt>>;
+}
+/**
+ * Create a ForPrompt client instance
+ *
+ * @example With explicit config
+ * ```typescript
+ * import { createForPrompt } from "@forprompt/sdk";
+ *
+ * const client = createForPrompt({
+ *   apiKey: "fp_xxx",
+ * });
+ *
+ * const prompt = await client.getPrompt("userContextPrompt");
+ * ```
+ *
+ * @example With timeout and retry config
+ * ```typescript
+ * const client = createForPrompt({
+ *   apiKey: "fp_xxx",
+ *   timeout: 10000, // 10 seconds
+ *   retries: 5,
+ * });
+ * ```
+ *
+ * @example Auto-config from environment
+ * ```typescript
+ * import { forprompt } from "@forprompt/sdk";
+ *
+ * // Uses FORPROMPT_API_KEY from environment
+ * const prompt = await forprompt.getPrompt("userContextPrompt");
+ * ```
+ */
+declare function createForPrompt(config?: Partial<ForPromptClientConfig>): ForPrompt;
+/**
+ * Default ForPrompt client instance
+ *
+ * Auto-configured from environment variables:
+ * - FORPROMPT_API_KEY: Your project API key
+ * - FORPROMPT_BASE_URL: Custom base URL (optional)
+ *
+ * @example
+ * ```typescript
+ * import { forprompt } from "@forprompt/sdk";
+ *
+ * const prompt = await forprompt.getPrompt("userContextPrompt");
+ * console.log(prompt.systemPrompt);
+ * ```
+ */
+declare const forprompt: ForPrompt;
+
+/**
+ * ForPrompt Logger
+ *
+ * Implements trace/span model for logging AI conversations
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { logger } from "@forprompt/sdk";
+ *
+ * // Start a trace
+ * logger.startTrace("onboardingprompt");
+ *
+ * // Log user message
+ * await logger.log({ role: "user", content: "Hello" });
+ *
+ * // Log AI response
+ * await logger.log({
+ *   role: "assistant",
+ *   content: "Hi! How can I help?",
+ *   model: "gpt-4o",
+ *   tokens: { output: 120 }
+ * });
+ *
+ * // End trace (optional)
+ * logger.endTrace();
+ * ```
+ */
+interface LogOptions {
+    role: "user" | "assistant" | "system";
+    content: string;
+    model?: string;
+    tokens?: {
+        input?: number;
+        output?: number;
+    };
+    durationMs?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for logging a single AI request/response
+ * Use this for one-shot interactions without conversation tracking
+ */
+interface SingleRequestOptions {
+    /** The prompt identifier */
+    promptKey: string;
+    /** Prompt version number for analytics tracking */
+    versionNumber?: number;
+    /** Optional custom trace ID (auto-generated if not provided) */
+    traceId?: string;
+    /** The user's input/prompt */
+    input: string;
+    /** The AI's output/response */
+    output: string;
+    /** The model used (e.g., "gpt-4o", "claude-sonnet-4") */
+    model?: string;
+    /** Token counts */
+    tokens?: {
+        input?: number;
+        output?: number;
+    };
+    /** Total duration in milliseconds */
+    durationMs?: number;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+declare class ForPromptLogger {
+    private baseUrl;
+    private apiKey;
+    private traceId;
+    private promptKey;
+    private versionNumber;
+    private source;
+    constructor(config?: {
+        apiKey?: string;
+        baseUrl?: string;
+        source?: string;
+    });
+    /**
+     * Start a new trace (conversation)
+     * Returns the generated traceId
+     *
+     * @param promptKey - The prompt identifier
+     * @param options.traceId - Optional custom trace ID (auto-generated if not provided)
+     * @param options.versionNumber - Prompt version number for analytics tracking
+     */
+    startTrace(promptKey: string, options?: {
+        traceId?: string;
+        versionNumber?: number;
+    }): string;
+    /**
+     * Log a span (message, LLM call, etc.)
+     * Automatically creates a trace if none exists
+     */
+    log(options: LogOptions): Promise<void>;
+    /**
+     * End the current trace
+     * This is optional - traces can be left open
+     */
+    endTrace(): Promise<void>;
+    /**
+     * Get the current version number
+     */
+    getVersionNumber(): number | null;
+    /**
+     * Get the current trace ID
+     */
+    getTraceId(): string | null;
+    /**
+     * Check if a trace is active
+     */
+    isTracing(): boolean;
+    /**
+     * Log a single AI request/response without conversation tracking
+     * Creates a new trace with input and output spans automatically
+     *
+     * @example
+     * ```typescript
+     * const { traceId } = await logger.logRequest({
+     *   promptKey: "aicoaching",
+     *   versionNumber: 2,
+     *   input: "How do I learn Python?",
+     *   output: "Here are 5 steps...",
+     *   model: "gpt-4o",
+     *   tokens: { input: 10, output: 150 },
+     *   durationMs: 1200,
+     * });
+     * ```
+     */
+    logRequest(options: SingleRequestOptions): Promise<{
+        traceId: string;
+    }>;
+}
+/**
+ * Create a ForPrompt logger instance
+ */
+declare function createLogger(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+    source?: string;
+}): ForPromptLogger;
+/**
+ * Default logger instance
+ * Auto-configured from environment variables
+ */
+declare const logger: ForPromptLogger;
+
+export { ForPrompt, type ForPromptConfig, ForPromptError, ForPromptLogger, type GetPromptOptions, type LogOptions, type Prompt, type SingleRequestOptions, createForPrompt, createLogger, forprompt, logger };

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+/**
+ * ForPrompt SDK Types
+ */
+interface ForPromptConfig {
+    /** API key from ForPrompt dashboard (required) */
+    apiKey: string;
+    /** Custom base URL (optional, defaults to https://wooden-fox-811.convex.site) */
+    baseUrl?: string;
+}
+interface Prompt {
+    /** Unique key identifier for the prompt */
+    key: string;
+    /** Display name of the prompt */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Version number */
+    versionNumber: number;
+    /** The system prompt content */
+    systemPrompt: string;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Prompt information fields */
+    purpose?: string;
+    expectedBehavior?: string;
+    inputFormat?: string;
+    outputFormat?: string;
+    constraints?: string;
+    useCases?: string;
+    additionalNotes?: string;
+    toolsNotes?: string;
+}
+interface GetPromptOptions {
+    /** Specific version number to fetch (optional, defaults to active version) */
+    version?: number;
+}
+declare class ForPromptError extends Error {
+    statusCode: number;
+    code: string;
+    constructor(message: string, statusCode: number, code: string);
+}
+
+/**
+ * ForPrompt Client
+ *
+ * Simple usage with auto-configuration:
+ * @example
+ * ```typescript
+ * import { forprompt } from "@forprompt/sdk";
+ *
+ * // Auto-loads from FORPROMPT_API_KEY env variable
+ * const prompt = await forprompt.getPrompt("userContextPrompt");
+ * ```
+ */
+
+/**
+ * Extended client configuration with security options
+ */
+interface ForPromptClientConfig {
+    /** Project API key (required) */
+    apiKey: string;
+    /** Base URL for API (default: https://wooden-fox-811.convex.site) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    retries?: number;
+}
+declare class ForPrompt {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private retries;
+    constructor(config: ForPromptClientConfig | ForPromptConfig | {
+        apiKey: string;
+        baseUrl?: string;
+    });
+    /**
+     * Fetch with timeout support using AbortController
+     */
+    private fetchWithTimeout;
+    /**
+     * Fetch with retry and exponential backoff
+     */
+    private fetchWithRetry;
+    /**
+     * Get a prompt by its key
+     *
+     * @example
+     * ```typescript
+     * const prompt = await forprompt.getPrompt("userContextPrompt");
+     * console.log(prompt.systemPrompt);
+     * ```
+     *
+     * @example With specific version
+     * ```typescript
+     * const prompt = await forprompt.getPrompt("userContextPrompt", { version: 2 });
+     * ```
+     */
+    getPrompt(key: string, options?: GetPromptOptions): Promise<Prompt>;
+    /**
+     * Get multiple prompts by their keys
+     *
+     * Requests are made in parallel with concurrency limit to avoid overwhelming the server.
+     *
+     * @example
+     * ```typescript
+     * const prompts = await forprompt.getPrompts(["userContext", "chatDefault"]);
+     * ```
+     */
+    getPrompts(keys: string[], options?: GetPromptOptions): Promise<Map<string, Prompt>>;
+}
+/**
+ * Create a ForPrompt client instance
+ *
+ * @example With explicit config
+ * ```typescript
+ * import { createForPrompt } from "@forprompt/sdk";
+ *
+ * const client = createForPrompt({
+ *   apiKey: "fp_xxx",
+ * });
+ *
+ * const prompt = await client.getPrompt("userContextPrompt");
+ * ```
+ *
+ * @example With timeout and retry config
+ * ```typescript
+ * const client = createForPrompt({
+ *   apiKey: "fp_xxx",
+ *   timeout: 10000, // 10 seconds
+ *   retries: 5,
+ * });
+ * ```
+ *
+ * @example Auto-config from environment
+ * ```typescript
+ * import { forprompt } from "@forprompt/sdk";
+ *
+ * // Uses FORPROMPT_API_KEY from environment
+ * const prompt = await forprompt.getPrompt("userContextPrompt");
+ * ```
+ */
+declare function createForPrompt(config?: Partial<ForPromptClientConfig>): ForPrompt;
+/**
+ * Default ForPrompt client instance
+ *
+ * Auto-configured from environment variables:
+ * - FORPROMPT_API_KEY: Your project API key
+ * - FORPROMPT_BASE_URL: Custom base URL (optional)
+ *
+ * @example
+ * ```typescript
+ * import { forprompt } from "@forprompt/sdk";
+ *
+ * const prompt = await forprompt.getPrompt("userContextPrompt");
+ * console.log(prompt.systemPrompt);
+ * ```
+ */
+declare const forprompt: ForPrompt;
+
+/**
+ * ForPrompt Logger
+ *
+ * Implements trace/span model for logging AI conversations
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { logger } from "@forprompt/sdk";
+ *
+ * // Start a trace
+ * logger.startTrace("onboardingprompt");
+ *
+ * // Log user message
+ * await logger.log({ role: "user", content: "Hello" });
+ *
+ * // Log AI response
+ * await logger.log({
+ *   role: "assistant",
+ *   content: "Hi! How can I help?",
+ *   model: "gpt-4o",
+ *   tokens: { output: 120 }
+ * });
+ *
+ * // End trace (optional)
+ * logger.endTrace();
+ * ```
+ */
+interface LogOptions {
+    role: "user" | "assistant" | "system";
+    content: string;
+    model?: string;
+    tokens?: {
+        input?: number;
+        output?: number;
+    };
+    durationMs?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for logging a single AI request/response
+ * Use this for one-shot interactions without conversation tracking
+ */
+interface SingleRequestOptions {
+    /** The prompt identifier */
+    promptKey: string;
+    /** Prompt version number for analytics tracking */
+    versionNumber?: number;
+    /** Optional custom trace ID (auto-generated if not provided) */
+    traceId?: string;
+    /** The user's input/prompt */
+    input: string;
+    /** The AI's output/response */
+    output: string;
+    /** The model used (e.g., "gpt-4o", "claude-sonnet-4") */
+    model?: string;
+    /** Token counts */
+    tokens?: {
+        input?: number;
+        output?: number;
+    };
+    /** Total duration in milliseconds */
+    durationMs?: number;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+declare class ForPromptLogger {
+    private baseUrl;
+    private apiKey;
+    private traceId;
+    private promptKey;
+    private versionNumber;
+    private source;
+    constructor(config?: {
+        apiKey?: string;
+        baseUrl?: string;
+        source?: string;
+    });
+    /**
+     * Start a new trace (conversation)
+     * Returns the generated traceId
+     *
+     * @param promptKey - The prompt identifier
+     * @param options.traceId - Optional custom trace ID (auto-generated if not provided)
+     * @param options.versionNumber - Prompt version number for analytics tracking
+     */
+    startTrace(promptKey: string, options?: {
+        traceId?: string;
+        versionNumber?: number;
+    }): string;
+    /**
+     * Log a span (message, LLM call, etc.)
+     * Automatically creates a trace if none exists
+     */
+    log(options: LogOptions): Promise<void>;
+    /**
+     * End the current trace
+     * This is optional - traces can be left open
+     */
+    endTrace(): Promise<void>;
+    /**
+     * Get the current version number
+     */
+    getVersionNumber(): number | null;
+    /**
+     * Get the current trace ID
+     */
+    getTraceId(): string | null;
+    /**
+     * Check if a trace is active
+     */
+    isTracing(): boolean;
+    /**
+     * Log a single AI request/response without conversation tracking
+     * Creates a new trace with input and output spans automatically
+     *
+     * @example
+     * ```typescript
+     * const { traceId } = await logger.logRequest({
+     *   promptKey: "aicoaching",
+     *   versionNumber: 2,
+     *   input: "How do I learn Python?",
+     *   output: "Here are 5 steps...",
+     *   model: "gpt-4o",
+     *   tokens: { input: 10, output: 150 },
+     *   durationMs: 1200,
+     * });
+     * ```
+     */
+    logRequest(options: SingleRequestOptions): Promise<{
+        traceId: string;
+    }>;
+}
+/**
+ * Create a ForPrompt logger instance
+ */
+declare function createLogger(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+    source?: string;
+}): ForPromptLogger;
+/**
+ * Default logger instance
+ * Auto-configured from environment variables
+ */
+declare const logger: ForPromptLogger;
+
+export { ForPrompt, type ForPromptConfig, ForPromptError, ForPromptLogger, type GetPromptOptions, type LogOptions, type Prompt, type SingleRequestOptions, createForPrompt, createLogger, forprompt, logger };