@kloddy/kloddy-js 0.1.0 → 0.1.1

package/dist/index-BaQw1DKg.d.ts

@@ -0,0 +1,178 @@
+import { K as KloddyOptions, U as User, O as Organization, F as Feature, P as PromptListOptions, e as PromptTemplate, d as PromptOptions, b as ExecuteOptions, c as ExecuteResult, E as EvaluationOptions, a as EvaluationResult } from './types-BrCFkSyd.js';
+import React from 'react';
+
+/**
+ * Low-level client for interacting with the Kloddy API.
+ * Handles authentication, token management, and raw requests.
+ */
+declare class KloddyClient {
+    private apiKey;
+    private apiSecret;
+    private host;
+    defaultOrgId: string | null;
+    defaultFeatureId: string | null;
+    private token;
+    private tokenExpires;
+    /**
+     * Initialize a new KloddyClient.
+     * If no credentials are provided, it will look for:
+     * - KLODDY_API_KEY / KLODDY_APP_ID
+     * - KLODDY_API_SECRET / KLODDY_SECRET_KEY
+     * in process.env.
+     */
+    constructor(apiKeyOrOptions?: string | KloddyOptions, options?: KloddyOptions);
+    /**
+     * Authenticate with the Kloddy API and retrieve a session token.
+     */
+    login(): Promise<string>;
+    /**
+     * Get the current active token, refreshing it if necessary.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Make an authenticated request to the Kloddy API.
+     */
+    request<T>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Get current user information.
+     */
+    whoAmI(): Promise<User>;
+    /**
+     * List organizations for the current user.
+     */
+    listOrganizations(): Promise<Organization[]>;
+    /**
+     * List features, optionally filtered by organization.
+     */
+    listFeatures(orgId?: string): Promise<Feature[]>;
+}
+
+/**
+ * Manager for Kloddy prompts.
+ *
+ * @template TPromptNames Union of strings representing available prompt names for type safety.
+ */
+declare class Prompts<TPromptNames extends string = string> {
+    private client;
+    constructor(options: {
+        client?: KloddyClient;
+    } | KloddyOptions);
+    /**
+     * List prompts with filters.
+     */
+    list(options?: PromptListOptions): Promise<PromptTemplate[]>;
+    /**
+     * Fetch a prompt template.
+     *
+     * @param name The unique name of the prompt.
+     * @param options Fetching options (version, fallback, etc.)
+     */
+    get(name: TPromptNames, options?: PromptOptions): Promise<PromptTemplate>;
+    /**
+     * Execute a prompt via the Kloddy API.
+     *
+     * @param name The unique name of the prompt.
+     * @param options Execution variables and model overrides.
+     */
+    execute(name: TPromptNames, options?: ExecuteOptions): Promise<ExecuteResult>;
+    /**
+     * Play: Direct execution for a single model/version.
+     * Same as execute but follows specific naming/body requirements.
+     *
+     * @param name The unique name of the prompt.
+     * @param options Execution variables and model overrides.
+     */
+    play(name: TPromptNames, options?: Omit<ExecuteOptions, 'judge' | 'evaluate_id'>): Promise<ExecuteResult>;
+    /**
+     * Update: Download all prompts for the user/organization.
+     */
+    update(options?: PromptListOptions): Promise<PromptTemplate[]>;
+    /**
+     * Local compilation of a template string with variables.
+     *
+     * @param template The template string or PromptTemplate object.
+     * @param variables Dictionary of variables to inject (e.g., {{variable}}).
+     */
+    compile(template: string | PromptTemplate, variables: Record<string, any>): string;
+}
+
+/**
+ * Manager for Kloddy evaluations.
+ * Allows running and retrieving model comparisons.
+ */
+declare class Evaluations {
+    private client;
+    constructor(options: {
+        client?: KloddyClient;
+    } | KloddyOptions);
+    /**
+     * Run or retrieve an evaluation.
+     *
+     * @param options Evaluation criteria including models, judge, and variables.
+     */
+    run(options: EvaluationOptions): Promise<EvaluationResult>;
+    /**
+     * Alias for run().
+     *
+     * @param options Evaluation criteria.
+     */
+    evaluate(options: EvaluationOptions): Promise<EvaluationResult>;
+    /**
+     * Simple one-step evaluation call.
+     *
+     * @param name The name of the evaluation to run.
+     * @param variables Variables to inject into the evaluation.
+     */
+    get(name: string, variables?: Record<string, any>): Promise<EvaluationResult>;
+}
+
+interface KloddyProviderProps {
+    children: React.ReactNode;
+    client?: KloddyClient;
+    options?: KloddyOptions;
+    apiKey?: string;
+    token?: string;
+    authEndpoint?: string;
+}
+/**
+ * KloddyProvider manages the Kloddy SDK state for React applications.
+ * It handles client initialization and optional automatic token fetching.
+ */
+declare const KloddyProvider: React.FC<KloddyProviderProps>;
+/**
+ * Hook to access Kloddy prompts and general SDK features.
+ *
+ * @template TPromptNames Union of strings for type-safe prompt names.
+ */
+declare const usePrompt: <TPromptNames extends string = string>() => {
+    prompts: Prompts<TPromptNames>;
+    isLoading: boolean;
+    error: Error | null;
+    getPrompt: (id: TPromptNames, options?: PromptOptions) => Promise<PromptTemplate>;
+    getAwnser: (id: TPromptNames, options?: ExecuteOptions) => Promise<ExecuteResult>;
+    /** @deprecated Use useEvaluations instead */
+    getEvaluation: (id: string, variables?: {}) => Promise<EvaluationResult>;
+    compile: (template: any, variables: any) => string;
+};
+/**
+ * Hook to access Kloddy evaluations.
+ */
+declare const useEvaluations: () => {
+    evaluations: Evaluations;
+    isLoading: boolean;
+    error: Error | null;
+    run: (options: EvaluationOptions) => Promise<EvaluationResult>;
+    evaluate: (options: EvaluationOptions) => Promise<EvaluationResult>;
+    get: (name: string, variables?: {}) => Promise<EvaluationResult>;
+};
+/**
+ * Hook for streaming prompt responses.
+ * (Placeholder implementation - requires backend streaming support)
+ */
+declare const usePromptStream: <TPromptNames extends string = string>() => {
+    stream: string;
+    isStreaming: boolean;
+    executeStream: (name: TPromptNames, options?: ExecuteOptions) => Promise<ExecuteResult>;
+};
+
+export { Evaluations as E, KloddyClient as K, Prompts as P, KloddyProvider as a, type KloddyProviderProps as b, usePrompt as c, usePromptStream as d, useEvaluations as u };

package/dist/index-CqX8s53x.d.mts

@@ -0,0 +1,178 @@
+import { K as KloddyOptions, U as User, O as Organization, F as Feature, P as PromptListOptions, e as PromptTemplate, d as PromptOptions, b as ExecuteOptions, c as ExecuteResult, E as EvaluationOptions, a as EvaluationResult } from './types-BrCFkSyd.mjs';
+import React from 'react';
+
+/**
+ * Low-level client for interacting with the Kloddy API.
+ * Handles authentication, token management, and raw requests.
+ */
+declare class KloddyClient {
+    private apiKey;
+    private apiSecret;
+    private host;
+    defaultOrgId: string | null;
+    defaultFeatureId: string | null;
+    private token;
+    private tokenExpires;
+    /**
+     * Initialize a new KloddyClient.
+     * If no credentials are provided, it will look for:
+     * - KLODDY_API_KEY / KLODDY_APP_ID
+     * - KLODDY_API_SECRET / KLODDY_SECRET_KEY
+     * in process.env.
+     */
+    constructor(apiKeyOrOptions?: string | KloddyOptions, options?: KloddyOptions);
+    /**
+     * Authenticate with the Kloddy API and retrieve a session token.
+     */
+    login(): Promise<string>;
+    /**
+     * Get the current active token, refreshing it if necessary.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Make an authenticated request to the Kloddy API.
+     */
+    request<T>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Get current user information.
+     */
+    whoAmI(): Promise<User>;
+    /**
+     * List organizations for the current user.
+     */
+    listOrganizations(): Promise<Organization[]>;
+    /**
+     * List features, optionally filtered by organization.
+     */
+    listFeatures(orgId?: string): Promise<Feature[]>;
+}
+
+/**
+ * Manager for Kloddy prompts.
+ *
+ * @template TPromptNames Union of strings representing available prompt names for type safety.
+ */
+declare class Prompts<TPromptNames extends string = string> {
+    private client;
+    constructor(options: {
+        client?: KloddyClient;
+    } | KloddyOptions);
+    /**
+     * List prompts with filters.
+     */
+    list(options?: PromptListOptions): Promise<PromptTemplate[]>;
+    /**
+     * Fetch a prompt template.
+     *
+     * @param name The unique name of the prompt.
+     * @param options Fetching options (version, fallback, etc.)
+     */
+    get(name: TPromptNames, options?: PromptOptions): Promise<PromptTemplate>;
+    /**
+     * Execute a prompt via the Kloddy API.
+     *
+     * @param name The unique name of the prompt.
+     * @param options Execution variables and model overrides.
+     */
+    execute(name: TPromptNames, options?: ExecuteOptions): Promise<ExecuteResult>;
+    /**
+     * Play: Direct execution for a single model/version.
+     * Same as execute but follows specific naming/body requirements.
+     *
+     * @param name The unique name of the prompt.
+     * @param options Execution variables and model overrides.
+     */
+    play(name: TPromptNames, options?: Omit<ExecuteOptions, 'judge' | 'evaluate_id'>): Promise<ExecuteResult>;
+    /**
+     * Update: Download all prompts for the user/organization.
+     */
+    update(options?: PromptListOptions): Promise<PromptTemplate[]>;
+    /**
+     * Local compilation of a template string with variables.
+     *
+     * @param template The template string or PromptTemplate object.
+     * @param variables Dictionary of variables to inject (e.g., {{variable}}).
+     */
+    compile(template: string | PromptTemplate, variables: Record<string, any>): string;
+}
+
+/**
+ * Manager for Kloddy evaluations.
+ * Allows running and retrieving model comparisons.
+ */
+declare class Evaluations {
+    private client;
+    constructor(options: {
+        client?: KloddyClient;
+    } | KloddyOptions);
+    /**
+     * Run or retrieve an evaluation.
+     *
+     * @param options Evaluation criteria including models, judge, and variables.
+     */
+    run(options: EvaluationOptions): Promise<EvaluationResult>;
+    /**
+     * Alias for run().
+     *
+     * @param options Evaluation criteria.
+     */
+    evaluate(options: EvaluationOptions): Promise<EvaluationResult>;
+    /**
+     * Simple one-step evaluation call.
+     *
+     * @param name The name of the evaluation to run.
+     * @param variables Variables to inject into the evaluation.
+     */
+    get(name: string, variables?: Record<string, any>): Promise<EvaluationResult>;
+}
+
+interface KloddyProviderProps {
+    children: React.ReactNode;
+    client?: KloddyClient;
+    options?: KloddyOptions;
+    apiKey?: string;
+    token?: string;
+    authEndpoint?: string;
+}
+/**
+ * KloddyProvider manages the Kloddy SDK state for React applications.
+ * It handles client initialization and optional automatic token fetching.
+ */
+declare const KloddyProvider: React.FC<KloddyProviderProps>;
+/**
+ * Hook to access Kloddy prompts and general SDK features.
+ *
+ * @template TPromptNames Union of strings for type-safe prompt names.
+ */
+declare const usePrompt: <TPromptNames extends string = string>() => {
+    prompts: Prompts<TPromptNames>;
+    isLoading: boolean;
+    error: Error | null;
+    getPrompt: (id: TPromptNames, options?: PromptOptions) => Promise<PromptTemplate>;
+    getAwnser: (id: TPromptNames, options?: ExecuteOptions) => Promise<ExecuteResult>;
+    /** @deprecated Use useEvaluations instead */
+    getEvaluation: (id: string, variables?: {}) => Promise<EvaluationResult>;
+    compile: (template: any, variables: any) => string;
+};
+/**
+ * Hook to access Kloddy evaluations.
+ */
+declare const useEvaluations: () => {
+    evaluations: Evaluations;
+    isLoading: boolean;
+    error: Error | null;
+    run: (options: EvaluationOptions) => Promise<EvaluationResult>;
+    evaluate: (options: EvaluationOptions) => Promise<EvaluationResult>;
+    get: (name: string, variables?: {}) => Promise<EvaluationResult>;
+};
+/**
+ * Hook for streaming prompt responses.
+ * (Placeholder implementation - requires backend streaming support)
+ */
+declare const usePromptStream: <TPromptNames extends string = string>() => {
+    stream: string;
+    isStreaming: boolean;
+    executeStream: (name: TPromptNames, options?: ExecuteOptions) => Promise<ExecuteResult>;
+};
+
+export { Evaluations as E, KloddyClient as K, Prompts as P, KloddyProvider as a, type KloddyProviderProps as b, usePrompt as c, usePromptStream as d, useEvaluations as u };

package/dist/index.d.mts

@@ -1,113 +1,57 @@
-import React from 'react';
+import { K as KloddyOptions, U as User, O as Organization, F as Feature } from './types-BrCFkSyd.mjs';
+export { A as AuthResponse, E as EvaluationOptions, a as EvaluationResult, b as ExecuteOptions, c as ExecuteResult, P as PromptListOptions, d as PromptOptions, e as PromptTemplate } from './types-BrCFkSyd.mjs';
+import { K as KloddyClient, P as Prompts, E as Evaluations } from './index-CqX8s53x.mjs';
+export { a as KloddyProvider, b as KloddyProviderProps, u as useEvaluations, c as usePrompt, d as usePromptStream } from './index-CqX8s53x.mjs';
+import 'react';
 
-interface KloddyOptions {
-    apiKey?: string;
-    apiSecret?: string;
-    token?: string;
-    personalApiKey?: string;
-    projectApiKey?: string;
-    applicationId?: string;
-    secretKey?: string;
-    host?: string;
-    cacheTtlSeconds?: number;
-    defaultOrgId?: string;
-    defaultFeatureId?: string;
-}
-interface User {
-    id: string;
-    email: string;
-    name: string;
-    [key: string]: any;
-}
-interface Organization {
-    id: string;
-    name: string;
-    [key: string]: any;
-}
-interface Feature {
-    id: string;
-    name: string;
-    org_id: string;
-    [key: string]: any;
-}
-interface PromptListOptions {
-    page?: number;
-    pageSize?: number;
-    name?: string;
-    org_id?: string;
-    feature_id?: string;
-}
-interface PromptOptions {
-    version?: number | string;
-    fallback?: string;
-    cacheTtlSeconds?: number;
-    resolve?: boolean;
-}
-interface PromptTemplate {
-    id: string;
-    name: string;
-    content: string;
-    version: number;
-    variables?: string[];
-    [key: string]: any;
-}
-interface ExecuteOptions {
-    variables?: Record<string, any>;
-    model?: string;
-    version?: string | number;
-    resolve?: boolean;
-}
-interface ExecuteResult {
-    result: string;
-    model: string;
-    version: string | number;
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
-interface EvaluationOptions {
-    name: string;
-    models?: string[];
-    judge?: string;
-    version?: (string | number)[];
-    variables?: Record<string, any>;
-    evaluate_id?: string;
-    temperature?: number;
-}
-interface EvaluationResult {
-    result: string;
-    winner?: string;
-    answers: {
-        model: string;
-        answer: string;
-        score?: number;
-    }[];
-}
-interface AuthResponse {
-    token: string;
-    expiresAt?: string;
+/**
+ * Base class for all Kloddy-related errors.
+ */
+declare class KloddyError extends Error {
+    status?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+/**
+ * Thrown when authentication fails.
+ */
+declare class KloddyAuthError extends KloddyError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a resource (e.g., prompt, organization) is not found.
+ */
+declare class KloddyNotFoundError extends KloddyError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the API rate limit is exceeded.
+ */
+declare class KloddyRateLimitError extends KloddyError {
+    constructor(message: string);
 }
 
-declare class KloddyClient {
-    private apiKey;
-    private apiSecret;
-    private host;
-    defaultOrgId: string | null;
-    defaultFeatureId: string | null;
-    private token;
-    private tokenExpires;
-    constructor(apiKeyOrOptions: string | KloddyOptions, options?: KloddyOptions);
-    login(): Promise<string>;
-    getToken(): Promise<string>;
-    request<T>(path: string, options?: RequestInit): Promise<T>;
+/**
+ * The main Kloddy SDK class.
+ * Provides access to prompts, evaluations, and account management.
+ *
+ * @template TPromptNames Union of strings representing available prompt names for type safety.
+ */
+declare class Kloddy<TPromptNames extends string = string> {
+    client: KloddyClient;
+    prompts: Prompts<TPromptNames>;
+    evaluations: Evaluations;
+    /**
+     * Initialize the Kloddy SDK.
+     * If no arguments are provided, it will attempt to use KLODDY_API_KEY and KLODDY_API_SECRET from process.env.
+     */
+    constructor(apiKeyOrOptions?: string | KloddyOptions, options?: KloddyOptions);
     /**
-     * Get current user information.
+     * Get information about the current authenticated user/application.
      */
     whoAmI(): Promise<User>;
     /**
-     * List organizations for the current user.
+     * List organizations accessible by the current credentials.
      */
     listOrganizations(): Promise<Organization[]>;
     /**
@@ -116,80 +60,4 @@ declare class KloddyClient {
     listFeatures(orgId?: string): Promise<Feature[]>;
 }
 
-declare class Prompts {
-    private client;
-    constructor(options: {
-        posthog?: KloddyClient;
-    } | KloddyOptions);
-    /**
-     * List prompts with filters.
-     */
-    list(options?: PromptListOptions): Promise<PromptTemplate[]>;
-    /**
-     * Fetch a prompt template.
-     */
-    get(name: string, options?: PromptOptions): Promise<PromptTemplate>;
-    /**
-     * Execute a prompt via the Kloddy API.
-     */
-    execute(name: string, options?: ExecuteOptions): Promise<ExecuteResult>;
-    /**
-     * Play: Direct execution for a single model/version.
-     * Same as execute but follows specific naming/body requirements.
-     */
-    play(name: string, options?: Omit<ExecuteOptions, 'judge' | 'evaluate_id'>): Promise<ExecuteResult>;
-    /**
-     * Update: Download all prompts for the user/organization.
-     */
-    update(options?: PromptListOptions): Promise<PromptTemplate[]>;
-    /**
-     * Local compilation of a template string with variables.
-     */
-    compile(template: string | PromptTemplate, variables: Record<string, any>): string;
-}
-
-declare class Evaluations {
-    private client;
-    constructor(options: {
-        posthog?: KloddyClient;
-    } | KloddyOptions);
-    /**
-     * Run or retrieve an evaluation.
-     */
-    run(options: EvaluationOptions): Promise<EvaluationResult>;
-    /**
-     * Alias for run() as requested.
-     */
-    evaluate(options: EvaluationOptions): Promise<EvaluationResult>;
-    /**
-     * Legacy alias for run(name) as requested in the hook example.
-     */
-    get(name: string, variables?: Record<string, any>): Promise<EvaluationResult>;
-}
-
-interface KloddyProviderProps {
-    children: React.ReactNode;
-    client?: KloddyClient;
-    options?: KloddyOptions;
-    apiKey?: string;
-    token?: string;
-}
-declare const KloddyProvider: React.FC<KloddyProviderProps>;
-declare const usePrompt: () => {
-    getPrompt: (id: string, options?: {}) => Promise<PromptTemplate>;
-    getAwnser: (id: string, options?: {}) => Promise<ExecuteResult>;
-    getEvaluation: (id: string, variables?: {}) => Promise<EvaluationResult>;
-    compile: (template: any, variables: any) => string;
-};
-
-declare class Kloddy {
-    client: KloddyClient;
-    prompts: Prompts;
-    evaluations: Evaluations;
-    constructor(apiKeyOrOptions: string | KloddyOptions, options?: KloddyOptions);
-    whoAmI(): Promise<User>;
-    listOrganizations(): Promise<Organization[]>;
-    listFeatures(orgId?: string): Promise<Feature[]>;
-}
-
-export { type AuthResponse, type EvaluationOptions, type EvaluationResult, Evaluations, type ExecuteOptions, type ExecuteResult, type Feature, Kloddy, KloddyClient, type KloddyOptions, KloddyProvider, type KloddyProviderProps, type Organization, type PromptListOptions, type PromptOptions, type PromptTemplate, Prompts, type User, Kloddy as default, usePrompt };
+export { Evaluations, Feature, Kloddy, KloddyAuthError, KloddyClient, KloddyError, KloddyNotFoundError, KloddyOptions, KloddyRateLimitError, Organization, Prompts, User, Kloddy as default };