@kloddy/kloddy-js 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,8 @@
 # @kloddy/kloddy-js
 
-Kloddy is the ultimate platform for Prompt Engineering and LLM Analytics. This SDK allows you to fetch, compile, and execute prompts directly from your Node.js or React applications.
+Kloddy is the ultimate platform for Prompt Engineering and LLM Analytics. This SDK allows you to fetch, compile, and execute prompts directly from your Node.js or React applications with full type safety and zero-config support.
 
-## installation
+## Installation
 
 ```bash
 # via npm
@@ -14,140 +14,109 @@ yarn add @kloddy/kloddy-js
 
 ## Quick Start
 
-### Basic Usage (Node.js)
+### Zero-Config Initialization (Node.js)
 
-```javascript
-import { Kloddy } from 'kloddy-js';
+Kloddy automatically looks for `KLODDY_API_KEY` and `KLODDY_API_SECRET` in your environment variables.
 
-const kloddy = new Kloddy({
-  apiKey: '<your_project_api_key>',
-  apiSecret: '<your_personal_api_key>',
-  host: 'https://api.kloddy.com' // Optional
-});
+```typescript
+import { Kloddy } from '@kloddy/kloddy-js';
 
-// Fetch a prompt template
-const template = await kloddy.prompts.get('customer-support-agent', {
-  fallback: 'You are a helpful assistant.'
-});
+// Zero-config! Uses process.env.KLODDY_API_KEY and process.env.KLODDY_API_SECRET
+const kloddy = new Kloddy();
 
-// Compile with variables
-const systemPrompt = kloddy.prompts.compile(template, {
-  userName: 'Alice',
-  company: 'Acme Corp'
+// Type-safe prompts (Optional but recommended)
+type MyPrompts = 'exam-generator' | 'customer-support' | 'welcome-email';
+const kloddyTyped = new Kloddy<MyPrompts>();
+
+// One-step execution (Play)
+const { result } = await kloddyTyped.prompts.play('exam-generator', {
+  variables: { locale: 'en-US', topic: 'Physics' }
 });
 
-console.log(systemPrompt);
+console.log(result);
 ```
 
-### React Usage
+### Next.js Integration (App Router)
 
-Wrap your app with `KloddyProvider`. For security, it is highly recommended to generate an **accessToken** on your server and pass it to the frontend instead of using your `apiSecret` in the browser.
+Securely generate tokens on the server without exposing secrets to the client.
 
-```tsx
-import { KloddyProvider, usePrompt } from '@kloddy/kloddy-js';
+```typescript
+// app/api/kloddy/token/route.ts
+import { createKloddyAdapter } from '@kloddy/kloddy-js/next';
 
-function MyComponent() {
-  const { getPrompt, getAwnser } = usePrompt();
+export const GET = createKloddyAdapter({
+  // Credentials picked up from env vars automatically
+});
+```
 
-  const handleWelcome = async () => {
-    const prompt = await getPrompt('welcome-message');
-    const response = await getAwnser('welcome-message', {
-      variables: { name: 'Alice' }
-    });
-    console.log(response.result);
-  };
+### React Hooks
 
-  return <button onClick={handleWelcome}>Say Hello</button>;
-}
+Wrap your application with `KloddyProvider` and use the simplified hooks.
 
-function App() {
-  // The token should be fetched from your own API
-  const [token, setToken] = useState('');
+```tsx
+// app/layout.tsx
+import { KloddyProvider } from '@kloddy/kloddy-js';
 
+export default function RootLayout({ children }) {
   return (
-    <KloddyProvider apiKey="YOUR_PROJECT_ID" token={token}>
-      <MyComponent />
+    <KloddyProvider authEndpoint="/api/kloddy/token">
+      {children}
     </KloddyProvider>
   );
 }
-```
-
-## Advanced Usage
 
-### Organization & Feature Context
-You can set a default organization or feature ID during initialization to simplify your calls.
+// components/PromptExecutor.tsx
+'use client';
+import { usePrompt } from '@kloddy/kloddy-js';
 
-```javascript
-const kloddy = new Kloddy({
-  apiKey: '...',
-  defaultOrgId: 'org_123',
-  defaultFeatureId: 'feat_456'
-});
+export function PromptExecutor() {
+  const { getAwnser, isLoading } = usePrompt<'exam-generator'>();
 
-// These will now use the defaults automatically
-const prompts = await kloddy.prompts.list();
-const features = await kloddy.listFeatures();
-```
+  const handleRun = async () => {
+    const { result } = await getAwnser('exam-generator', {
+      variables: { topic: 'Math' }
+    });
+    alert(result);
+  };
 
-### Account Information
-```javascript
-const user = await kloddy.whoAmI();
-const orgs = await kloddy.listOrganizations();
-const features = await kloddy.listFeatures(orgs[0].id);
+  return (
+    <button onClick={handleRun} disabled={isLoading}>
+      {isLoading ? 'Running...' : 'Generate Exam'}
+    </button>
+  );
+}
 ```
 
-### Prompts Management
-```javascript
-// List all prompts
-const allPrompts = await kloddy.prompts.list({ pageSize: 50 });
+## Features
 
-// Update/Sync (alias for list)
-const synced = await kloddy.prompts.update();
-
-// Play (Direct Execution)
-const result = await kloddy.prompts.play('my-prompt', {
-  variables: { user: 'Alice' },
-  model: 'gpt-4'
-});
-```
-
-### Evaluations
-```javascript
-const evalResult = await kloddy.evaluations.evaluate({
-  name: 'model-comparison',
-  models: ['gpt-4', 'claude-3'],
-  judge: 'gpt-4-judge',
-  variables: { input: '...' },
-  temperature: 0.7
-});
-```
+- **Zero-Config**: Works out of the box with `process.env`.
+- **Type Safety**: Use Generics to get autocomplete for your prompt names.
+- **Next.js Ready**: Built-in adapter for secure token handling.
+- **Graceful Degradation**: Built-in fallback support for offline mode or API issues.
+- **Professional Error Handling**: Custom error classes like `KloddyAuthError` and `KloddyNotFoundError`.
+- **Tree-Shakable**: Optimized for small bundle sizes.
 
 ## API Reference
 
-### `Kloddy` Client
-- `whoAmI()`: Get current user details.
-- `listOrganizations()`: List organizations.
-- `listFeatures(orgId?)`: List features.
-- `prompts.list(filters)`: List prompts with pagination and filters.
-- `prompts.get(name, options)`: Fetch a template.
-- `prompts.play(name, options)`: Execute a prompt directly.
-- `prompts.update()`: Sync all prompts.
-- `evaluations.evaluate(options)`: Run model evaluations.
+### `Kloddy<TPromptNames>`
+The main entry point for the SDK.
+- `prompts.get(name, options)`: Fetch a template with optional version and fallback.
+- `prompts.play(name, options)`: Execute a prompt directly in one step.
+- `prompts.compile(template, variables)`: Locally compile a template string.
+- `evaluations.run(options)`: Run model evaluations.
 
 ### React Hooks
-- `usePrompt()`: Returns `getPrompt`, `getAwnser`, `getEvaluation`, `compile`.
-
-## Integration with Vercel AI Gateway
+- `usePrompt<TPromptNames>()`: Manage prompts and execution state.
+- `useEvaluations()`: Manage model evaluations and comparisons.
+- `usePromptStream<TPromptNames>()`: Support for streaming responses.
 
-You can use Kloddy to manage your prompts and Vercel AI Gateway to route your LLM calls.
+## Advanced Fallback Strategy
 
-```javascript
-const template = await kloddy.prompts.get('support-agent');
-const systemPrompt = kloddy.prompts.compile(template, { user: 'Alice' });
+Prevent outages by providing a local fallback for critical prompts.
 
-// Use with OpenAI via Vercel AI Gateway
-const openai = new OpenAI({
-  baseURL: 'https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/YOUR_GATEWAY_ID/openai'
+```typescript
+const template = await kloddy.prompts.get('critical-prompt', {
+  fallback: 'You are a helpful assistant. (Offline Fallback)'
 });
 ```
 

package/dist/chunk-WSN7MLKR.mjs

@@ -0,0 +1,166 @@
+// src/errors.ts
+var KloddyError = class _KloddyError extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "KloddyError";
+    Object.setPrototypeOf(this, _KloddyError.prototype);
+  }
+};
+var KloddyAuthError = class _KloddyAuthError extends KloddyError {
+  constructor(message) {
+    super(message, 401, "AUTH_FAILED");
+    this.name = "KloddyAuthError";
+    Object.setPrototypeOf(this, _KloddyAuthError.prototype);
+  }
+};
+var KloddyNotFoundError = class _KloddyNotFoundError extends KloddyError {
+  constructor(message) {
+    super(message, 404, "NOT_FOUND");
+    this.name = "KloddyNotFoundError";
+    Object.setPrototypeOf(this, _KloddyNotFoundError.prototype);
+  }
+};
+var KloddyRateLimitError = class _KloddyRateLimitError extends KloddyError {
+  constructor(message) {
+    super(message, 429, "RATE_LIMIT_EXCEEDED");
+    this.name = "KloddyRateLimitError";
+    Object.setPrototypeOf(this, _KloddyRateLimitError.prototype);
+  }
+};
+
+// src/client.ts
+import fetch from "cross-fetch";
+var KloddyClient = class {
+  apiKey;
+  apiSecret;
+  host;
+  defaultOrgId = null;
+  defaultFeatureId = null;
+  token = null;
+  tokenExpires = null;
+  /**
+   * 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, options) {
+    const envApiKey = typeof process !== "undefined" ? process.env?.KLODDY_API_KEY || process.env?.KLODDY_APP_ID || "" : "";
+    const envApiSecret = typeof process !== "undefined" ? process.env?.KLODDY_API_SECRET || process.env?.KLODDY_SECRET_KEY || "" : "";
+    if (!apiKeyOrOptions || apiKeyOrOptions === "") {
+      this.apiKey = envApiKey;
+      this.apiSecret = envApiSecret;
+      this.host = "https://api.kloddy.com";
+    } else if (typeof apiKeyOrOptions === "string") {
+      this.apiKey = apiKeyOrOptions;
+      this.apiSecret = options?.apiSecret || options?.personalApiKey || options?.secretKey || envApiSecret || "";
+      this.token = options?.token || null;
+      this.host = options?.host || "https://api.kloddy.com";
+      this.defaultOrgId = options?.defaultOrgId || null;
+      this.defaultFeatureId = options?.defaultFeatureId || null;
+    } else {
+      this.apiKey = apiKeyOrOptions.apiKey || apiKeyOrOptions.projectApiKey || apiKeyOrOptions.applicationId || envApiKey || "";
+      this.apiSecret = apiKeyOrOptions.apiSecret || apiKeyOrOptions.personalApiKey || apiKeyOrOptions.secretKey || envApiSecret || "";
+      this.token = apiKeyOrOptions.token || null;
+      this.host = apiKeyOrOptions.host || "https://api.kloddy.com";
+      this.defaultOrgId = apiKeyOrOptions.defaultOrgId || null;
+      this.defaultFeatureId = apiKeyOrOptions.defaultFeatureId || null;
+    }
+    if (!this.token && (!this.apiKey || !this.apiSecret)) {
+      if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+        console.warn("Kloddy SDK: API Key or Secret missing. Set KLODDY_API_KEY and KLODDY_API_SECRET env vars or pass them to the constructor.");
+      }
+    }
+  }
+  /**
+   * Authenticate with the Kloddy API and retrieve a session token.
+   */
+  async login() {
+    if (!this.apiKey || !this.apiSecret) {
+      throw new KloddyAuthError("KloddyClient: Cannot login without apiKey and apiSecret.");
+    }
+    const response = await fetch(`${this.host}/api/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        applicationId: this.apiKey,
+        secretKey: this.apiSecret
+      })
+    });
+    if (!response.ok) {
+      const errorContent = await response.text();
+      if (response.status === 401) throw new KloddyAuthError(`Authentication failed: ${errorContent}`);
+      if (response.status === 429) throw new KloddyRateLimitError(`Rate limit exceeded: ${errorContent}`);
+      throw new KloddyError(`Kloddy Auth failed: ${response.status} ${errorContent}`, response.status);
+    }
+    const data = await response.json();
+    this.token = data.token;
+    this.tokenExpires = Date.now() + (data.expiresAt ? new Date(data.expiresAt).getTime() - Date.now() : 36e5);
+    return this.token;
+  }
+  /**
+   * Get the current active token, refreshing it if necessary.
+   */
+  async getToken() {
+    if (this.token && !this.apiSecret) {
+      return this.token;
+    }
+    if (!this.token || this.tokenExpires && Date.now() >= this.tokenExpires - 6e4) {
+      return this.login();
+    }
+    return this.token;
+  }
+  /**
+   * Make an authenticated request to the Kloddy API.
+   */
+  async request(path, options = {}) {
+    const token = await this.getToken();
+    const url = path.startsWith("http") ? path : `${this.host}${path}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...options.headers,
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (!response.ok) {
+      const errorContent = await response.text();
+      if (response.status === 404) throw new KloddyNotFoundError(`Resource not found: ${path}`);
+      if (response.status === 401) throw new KloddyAuthError(`Unauthorized: ${errorContent}`);
+      if (response.status === 429) throw new KloddyRateLimitError(`Rate limit exceeded: ${errorContent}`);
+      throw new KloddyError(`Kloddy API error: ${response.status} ${errorContent}`, response.status);
+    }
+    return await response.json();
+  }
+  /**
+   * Get current user information.
+   */
+  async whoAmI() {
+    return this.request("/api/whoiam");
+  }
+  /**
+   * List organizations for the current user.
+   */
+  async listOrganizations() {
+    return this.request("/api/organizations");
+  }
+  /**
+   * List features, optionally filtered by organization.
+   */
+  async listFeatures(orgId) {
+    const path = orgId ? `/api/features?org_id=${orgId}` : "/api/features";
+    return this.request(path);
+  }
+};
+
+export {
+  KloddyError,
+  KloddyAuthError,
+  KloddyNotFoundError,
+  KloddyRateLimitError,
+  KloddyClient
+};

package/dist/chunk-WWAXYTZO.mjs

@@ -0,0 +1,265 @@
+import {
+  KloddyClient
+} from "./chunk-WSN7MLKR.mjs";
+
+// src/libs/react/index.tsx
+import { createContext, useContext, useMemo, useState, useEffect } from "react";
+
+// src/prompts.ts
+var Prompts = class {
+  client;
+  constructor(options) {
+    if ("client" in options && options.client) {
+      this.client = options.client;
+    } else if ("posthog" in options && options.posthog) {
+      this.client = options.posthog;
+    } else {
+      this.client = new KloddyClient(options);
+    }
+  }
+  /**
+   * List prompts with filters.
+   */
+  async list(options = {}) {
+    const params = new URLSearchParams();
+    if (options.page) params.append("page", options.page.toString());
+    if (options.pageSize) params.append("pageSize", options.pageSize.toString());
+    if (options.name) params.append("name", options.name);
+    const orgId = options.org_id || this.client.defaultOrgId;
+    if (orgId) params.append("org_id", orgId);
+    const featureId = options.feature_id || this.client.defaultFeatureId;
+    if (featureId) params.append("feature_id", featureId);
+    const queryString = params.toString() ? `?${params.toString()}` : "";
+    return this.client.request(`/api/prompts${queryString}`);
+  }
+  /**
+   * Fetch a prompt template.
+   * 
+   * @param name The unique name of the prompt.
+   * @param options Fetching options (version, fallback, etc.)
+   */
+  async get(name, options) {
+    const params = new URLSearchParams();
+    if (options?.version) params.append("version", options.version.toString());
+    const resolve = options?.resolve !== void 0 ? options.resolve : true;
+    params.append("resolve", resolve.toString());
+    const queryString = params.toString() ? `?${params.toString()}` : "";
+    try {
+      const template = await this.client.request(`/api/prompt/${name}${queryString}`, {
+        method: "GET"
+      });
+      return template;
+    } catch (error) {
+      if (options?.fallback) {
+        if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+          console.warn(`Kloddy SDK: Prompt '${name}' not found, using provided fallback.`);
+        }
+        return {
+          id: "fallback",
+          name,
+          content: options.fallback,
+          version: 0
+        };
+      }
+      throw error;
+    }
+  }
+  /**
+   * Execute a prompt via the Kloddy API.
+   * 
+   * @param name The unique name of the prompt.
+   * @param options Execution variables and model overrides.
+   */
+  async execute(name, options = {}) {
+    return this.client.request(`/api/prompt/${name}`, {
+      method: "POST",
+      body: JSON.stringify({
+        ...options,
+        resolve: options.resolve !== void 0 ? options.resolve : true
+      })
+    });
+  }
+  /**
+   * 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.
+   */
+  async play(name, options = {}) {
+    return this.client.request("/api/play", {
+      method: "POST",
+      body: JSON.stringify({
+        name,
+        ...options,
+        resolve: options.resolve !== void 0 ? options.resolve : true
+      })
+    });
+  }
+  /**
+   * Update: Download all prompts for the user/organization.
+   */
+  async update(options = {}) {
+    return this.list(options);
+  }
+  /**
+   * 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, variables) {
+    let content = typeof template === "string" ? template : template.content;
+    for (const [key, value] of Object.entries(variables)) {
+      const regex = new RegExp(`{{${key}}}|{${key}}`, "g");
+      content = content.replace(regex, String(value));
+    }
+    return content;
+  }
+};
+
+// src/evaluations.ts
+var Evaluations = class {
+  client;
+  constructor(options) {
+    if ("client" in options && options.client) {
+      this.client = options.client;
+    } else if ("posthog" in options && options.posthog) {
+      this.client = options.posthog;
+    } else {
+      this.client = new KloddyClient(options);
+    }
+  }
+  /**
+   * Run or retrieve an evaluation.
+   * 
+   * @param options Evaluation criteria including models, judge, and variables.
+   */
+  async run(options) {
+    return this.client.request("/api/evaluate", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Alias for run().
+   * 
+   * @param options Evaluation criteria.
+   */
+  async evaluate(options) {
+    return this.run(options);
+  }
+  /**
+   * Simple one-step evaluation call.
+   * 
+   * @param name The name of the evaluation to run.
+   * @param variables Variables to inject into the evaluation.
+   */
+  async get(name, variables = {}) {
+    return this.run({ name, variables });
+  }
+};
+
+// src/libs/react/index.tsx
+import { jsx } from "react/jsx-runtime";
+var KloddyContext = createContext(null);
+var KloddyProvider = ({
+  children,
+  client,
+  options,
+  apiKey,
+  token: initialToken,
+  authEndpoint
+}) => {
+  const [token, setToken] = useState(initialToken);
+  const [isLoading, setIsLoading] = useState(!!authEndpoint && !initialToken);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (authEndpoint && !token) {
+      setIsLoading(true);
+      fetch(authEndpoint).then((res) => res.json()).then((data) => {
+        if (data.token) {
+          setToken(data.token);
+        } else {
+          throw new Error("No token returned from authEndpoint");
+        }
+      }).catch((err) => {
+        console.error("KloddyProvider: Failed to fetch token:", err);
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }).finally(() => {
+        setIsLoading(false);
+      });
+    }
+  }, [authEndpoint, token]);
+  const value = useMemo(() => {
+    const activeClient = client || new KloddyClient({ ...options, apiKey, token });
+    return {
+      prompts: new Prompts({ client: activeClient }),
+      evaluations: new Evaluations({ client: activeClient }),
+      isLoading,
+      error
+    };
+  }, [client, options, apiKey, token, isLoading, error]);
+  return /* @__PURE__ */ jsx(KloddyContext.Provider, { value, children });
+};
+var usePrompt = () => {
+  const context = useContext(KloddyContext);
+  if (!context) {
+    throw new Error("usePrompt must be used within a KloddyProvider");
+  }
+  const { prompts, evaluations, isLoading, error } = context;
+  const typedPrompts = prompts;
+  return {
+    prompts: typedPrompts,
+    isLoading,
+    error,
+    getPrompt: (id, options = {}) => typedPrompts.get(id, options),
+    getAwnser: (id, options = {}) => typedPrompts.execute(id, options),
+    /** @deprecated Use useEvaluations instead */
+    getEvaluation: (id, variables = {}) => evaluations.get(id, variables),
+    compile: (template, variables) => typedPrompts.compile(template, variables)
+  };
+};
+var useEvaluations = () => {
+  const context = useContext(KloddyContext);
+  if (!context) {
+    throw new Error("useEvaluations must be used within a KloddyProvider");
+  }
+  const { evaluations, isLoading, error } = context;
+  return {
+    evaluations,
+    isLoading,
+    error,
+    run: (options) => evaluations.run(options),
+    evaluate: (options) => evaluations.evaluate(options),
+    get: (name, variables = {}) => evaluations.get(name, variables)
+  };
+};
+var usePromptStream = () => {
+  const { prompts } = usePrompt();
+  const [stream, setStream] = useState("");
+  const [isStreaming, setIsStreaming] = useState(false);
+  const executeStream = async (name, options = {}) => {
+    setIsStreaming(true);
+    setStream("");
+    console.warn("usePromptStream: Streaming is currently a placeholder.");
+    const result = await prompts.execute(name, options);
+    setStream(result.result);
+    setIsStreaming(false);
+    return result;
+  };
+  return {
+    stream,
+    isStreaming,
+    executeStream
+  };
+};
+
+export {
+  Prompts,
+  Evaluations,
+  KloddyProvider,
+  usePrompt,
+  useEvaluations,
+  usePromptStream
+};