@promptev/client 0.0.3 → 0.1.0

package/dist/cjs/index.cjs

@@ -1,58 +1,293 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+// ── Types ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromptevClient = void 0;
-const axios_1 = __importDefault(require("axios"));
+exports.PromptevClient = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.PromptevError = void 0;
+// ── Errors ──────────────────────────────────────────────
+class PromptevError extends Error {
+    constructor(message, statusCode, responseText) {
+        super(message);
+        this.name = "PromptevError";
+        this.statusCode = statusCode;
+        this.responseText = responseText;
+    }
+}
+exports.PromptevError = PromptevError;
+class ValidationError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+class AuthenticationError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class NotFoundError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class RateLimitError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
+class ServerError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "ServerError";
+    }
+}
+exports.ServerError = ServerError;
+class NetworkError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "NetworkError";
+    }
+}
+exports.NetworkError = NetworkError;
+// ── Client ──────────────────────────────────────────────
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BACKOFF = 500; // ms
 class PromptevClient {
     constructor(config) {
-        this.baseUrl = config.baseUrl ?? "https://api.promptev.ai";
         this.projectKey = config.projectKey;
-        this.client = axios_1.default.create({
-            baseURL: this.baseUrl,
-            headers: {
-                "Content-Type": "application/json",
-                ...(config.headers ?? {}),
-            },
+        this.baseUrl = (config.baseUrl ?? "https://api.promptev.ai").replace(/\/+$/, "");
+        this.headers = {
+            "Content-Type": "application/json",
+            ...(config.headers ?? {}),
+        };
+        this.timeout = config.timeout ?? 30000;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    // ── Error handling ──────────────────────────────────
+    static raiseForStatus(status, text) {
+        if (status < 400)
+            return;
+        let detail;
+        try {
+            const body = JSON.parse(text);
+            detail =
+                typeof body.detail === "string" ? body.detail : text || "Unknown error";
+        }
+        catch {
+            detail = text || "Unknown error";
+        }
+        if (status === 400)
+            throw new ValidationError(detail, status, text);
+        if (status === 401)
+            throw new AuthenticationError(detail, status, text);
+        if (status === 403)
+            throw new AuthenticationError(detail, status, text);
+        if (status === 404)
+            throw new NotFoundError(detail, status, text);
+        if (status === 429)
+            throw new RateLimitError(detail, status, text);
+        if (status >= 500)
+            throw new ServerError(detail, status, text);
+        throw new PromptevError(detail, status, text);
+    }
+    // ── Retry helper ────────────────────────────────────
+    async fetchWithRetry(url, init) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const resp = await fetch(url, {
+                    ...init,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!RETRYABLE_STATUS.has(resp.status) || attempt === this.maxRetries) {
+                    return resp;
+                }
+                lastError = new ServerError(`Server error (${resp.status})`, resp.status);
+            }
+            catch (err) {
+                if (err.name === "AbortError") {
+                    lastError = new NetworkError("Request timed out");
+                }
+                else {
+                    lastError = new NetworkError(`Network error: ${err.message}`);
+                }
+                if (attempt === this.maxRetries)
+                    throw lastError;
+            }
+            const delay = DEFAULT_BACKOFF * Math.pow(2, attempt);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        throw lastError;
+    }
+    // ── SSE parser ──────────────────────────────────────
+    async *parseSSE(response) {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (!line.startsWith("data: "))
+                        continue;
+                    try {
+                        const data = JSON.parse(line.slice(6));
+                        const event = {
+                            type: data.type || "unknown",
+                            output: data.output || "",
+                            raw: data,
+                        };
+                        yield event;
+                        if (event.type === "done" || event.type === "error")
+                            return;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    // ── Prompt API ──────────────────────────────────────
+    /**
+     * Compile and execute a prompt.
+     *
+     * If the prompt has a model configured, it compiles the template,
+     * sends it to the LLM, and returns the AI response. If no model
+     * is configured, it returns the compiled template string.
+     */
+    async runPrompt(promptKey, query, variables) {
+        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
+        const merged = { query, ...(variables ?? {}) };
+        const resp = await this.fetchWithRetry(url, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify({ variables: merged }),
         });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text);
+        const data = JSON.parse(text);
+        if (typeof data.prompt !== "string") {
+            throw new PromptevError("Unexpected response: missing 'prompt' field");
+        }
+        return data.prompt;
     }
     /**
-     * Compile a prompt by POSTing variables.
-     * Body shape (exact):
-     * {
-     *   "variables": {
-     *     "additionalProp1": "string",
-     *     "additionalProp2": "string",
-     *     "additionalProp3": "string"
-     *   }
-     * }
+     * Compile and execute a prompt with streaming.
+     *
+     * Use this when the prompt has tools attached or you want real-time
+     * output. Returns the same event types as agent streaming.
      */
-    async getPrompt(promptKey, variables = {}, opts) {
-        const url = `/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
+    async *streamPrompt(promptKey, query, variables) {
+        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}?stream=true`;
+        const merged = { query, ...(variables ?? {}) };
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let resp;
         try {
-            const resp = await this.client.post(url, { variables }, // <-- exact body
-            { signal: opts?.signal });
-            // Success shape: { prompt: string }
-            const compiled = resp.data?.prompt;
-            if (typeof compiled !== "string") {
-                throw new Error("Unexpected response: missing 'prompt' field");
-            }
-            return compiled;
+            resp = await fetch(url, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify({ variables: merged }),
+                signal: controller.signal,
+            });
         }
         catch (err) {
-            const ax = err;
-            const status = ax.response?.status;
-            const body = ax.response?.data;
-            const detail = body?.detail ?? body;
-            // Your API returns detail as a plain string on 400
-            if (typeof detail === "string") {
-                throw new Error(detail);
-            }
-            // Fallback error
-            const msg = `Request failed${status ? ` (${status})` : ""}`;
-            throw new Error(msg);
+            clearTimeout(timeoutId);
+            if (err.name === "AbortError")
+                throw new NetworkError("Request timed out");
+            throw new NetworkError(`Network error: ${err.message}`);
+        }
+        clearTimeout(timeoutId);
+        if (resp.status >= 400) {
+            const text = await resp.text();
+            PromptevClient.raiseForStatus(resp.status, text);
+        }
+        const contentType = resp.headers.get("content-type") || "";
+        // Non-streaming fallback: prompt has no model, backend returns JSON
+        if (!contentType.includes("text/event-stream")) {
+            const data = await resp.json();
+            yield {
+                type: "done",
+                output: data.prompt || "",
+                raw: data,
+            };
+            return;
+        }
+        yield* this.parseSSE(resp);
+    }
+    // ── Agent API ───────────────────────────────────────
+    /**
+     * Start a new agent chat session.
+     */
+    async startAgent(chatbotId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/start`;
+        const payload = {};
+        if (options?.visitor != null)
+            payload.visitor = options.visitor;
+        if (options?.platform && options.platform !== "sdk")
+            payload.platform = options.platform;
+        const resp = await this.fetchWithRetry(url, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(payload),
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text);
+        const data = JSON.parse(text);
+        return {
+            sessionToken: data.session_token,
+            chatbotId: data.chatbot_id,
+            name: data.name,
+            memoryEnabled: data.memory_enabled ?? false,
+            messages: data.messages ?? [],
+        };
+    }
+    /**
+     * Stream an agent response as SSE events.
+     */
+    async *streamAgent(chatbotId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify({ query: options.query }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err.name === "AbortError")
+                throw new NetworkError("Request timed out");
+            throw new NetworkError(`Network error: ${err.message}`);
+        }
+        clearTimeout(timeoutId);
+        if (resp.status >= 400) {
+            const text = await resp.text();
+            PromptevClient.raiseForStatus(resp.status, text);
         }
+        yield* this.parseSSE(resp);
     }
 }
 exports.PromptevClient = PromptevClient;

package/dist/esm/index.d.ts

@@ -1,26 +1,83 @@
 export interface PromptevClientConfig {
-    baseUrl?: string;
     projectKey: string;
+    baseUrl?: string;
     headers?: Record<string, string>;
+    timeout?: number;
+    maxRetries?: number;
+}
+export interface AgentSession {
+    sessionToken: string;
+    chatbotId: string;
+    name: string;
+    memoryEnabled: boolean;
+    messages: Record<string, any>[];
+}
+export interface AgentEvent {
+    type: string;
+    output: string;
+    raw: Record<string, any>;
+}
+export declare class PromptevError extends Error {
+    statusCode?: number;
+    responseText?: string;
+    constructor(message: string, statusCode?: number, responseText?: string);
+}
+export declare class ValidationError extends PromptevError {
+    constructor(message: string, statusCode?: number, responseText?: string);
+}
+export declare class AuthenticationError extends PromptevError {
+    constructor(message: string, statusCode?: number, responseText?: string);
+}
+export declare class NotFoundError extends PromptevError {
+    constructor(message: string, statusCode?: number, responseText?: string);
+}
+export declare class RateLimitError extends PromptevError {
+    constructor(message: string, statusCode?: number, responseText?: string);
+}
+export declare class ServerError extends PromptevError {
+    constructor(message: string, statusCode?: number, responseText?: string);
+}
+export declare class NetworkError extends PromptevError {
+    constructor(message: string, statusCode?: number, responseText?: string);
 }
 export declare class PromptevClient {
-    private client;
-    private baseUrl;
     private projectKey;
+    private baseUrl;
+    private headers;
+    private timeout;
+    private maxRetries;
     constructor(config: PromptevClientConfig);
+    private static raiseForStatus;
+    private fetchWithRetry;
+    private parseSSE;
+    /**
+     * Compile and execute a prompt.
+     *
+     * If the prompt has a model configured, it compiles the template,
+     * sends it to the LLM, and returns the AI response. If no model
+     * is configured, it returns the compiled template string.
+     */
+    runPrompt(promptKey: string, query: string, variables?: Record<string, string>): Promise<string>;
+    /**
+     * Compile and execute a prompt with streaming.
+     *
+     * Use this when the prompt has tools attached or you want real-time
+     * output. Returns the same event types as agent streaming.
+     */
+    streamPrompt(promptKey: string, query: string, variables?: Record<string, string>): AsyncGenerator<AgentEvent>;
+    /**
+     * Start a new agent chat session.
+     */
+    startAgent(chatbotId: string, options?: {
+        visitor?: string;
+        platform?: string;
+    }): Promise<AgentSession>;
     /**
-     * Compile a prompt by POSTing variables.
-     * Body shape (exact):
-     * {
-     *   "variables": {
-     *     "additionalProp1": "string",
-     *     "additionalProp2": "string",
-     *     "additionalProp3": "string"
-     *   }
-     * }
+     * Stream an agent response as SSE events.
      */
-    getPrompt(promptKey: string, variables?: Record<string, string>, opts?: {
-        signal?: AbortSignal;
-    }): Promise<string>;
+    streamAgent(chatbotId: string, options: {
+        sessionToken: string;
+        query: string;
+    }): AsyncGenerator<AgentEvent>;
 }
 export default PromptevClient;

package/dist/esm/index.js

@@ -1,52 +1,283 @@
-import axios from "axios";
+// ── Types ───────────────────────────────────────────────
+// ── Errors ──────────────────────────────────────────────
+export class PromptevError extends Error {
+    constructor(message, statusCode, responseText) {
+        super(message);
+        this.name = "PromptevError";
+        this.statusCode = statusCode;
+        this.responseText = responseText;
+    }
+}
+export class ValidationError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "ValidationError";
+    }
+}
+export class AuthenticationError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "AuthenticationError";
+    }
+}
+export class NotFoundError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "NotFoundError";
+    }
+}
+export class RateLimitError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "RateLimitError";
+    }
+}
+export class ServerError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "ServerError";
+    }
+}
+export class NetworkError extends PromptevError {
+    constructor(message, statusCode, responseText) {
+        super(message, statusCode, responseText);
+        this.name = "NetworkError";
+    }
+}
+// ── Client ──────────────────────────────────────────────
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BACKOFF = 500; // ms
 export class PromptevClient {
     constructor(config) {
-        this.baseUrl = config.baseUrl ?? "https://api.promptev.ai";
         this.projectKey = config.projectKey;
-        this.client = axios.create({
-            baseURL: this.baseUrl,
-            headers: {
-                "Content-Type": "application/json",
-                ...(config.headers ?? {}),
-            },
+        this.baseUrl = (config.baseUrl ?? "https://api.promptev.ai").replace(/\/+$/, "");
+        this.headers = {
+            "Content-Type": "application/json",
+            ...(config.headers ?? {}),
+        };
+        this.timeout = config.timeout ?? 30000;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    // ── Error handling ──────────────────────────────────
+    static raiseForStatus(status, text) {
+        if (status < 400)
+            return;
+        let detail;
+        try {
+            const body = JSON.parse(text);
+            detail =
+                typeof body.detail === "string" ? body.detail : text || "Unknown error";
+        }
+        catch {
+            detail = text || "Unknown error";
+        }
+        if (status === 400)
+            throw new ValidationError(detail, status, text);
+        if (status === 401)
+            throw new AuthenticationError(detail, status, text);
+        if (status === 403)
+            throw new AuthenticationError(detail, status, text);
+        if (status === 404)
+            throw new NotFoundError(detail, status, text);
+        if (status === 429)
+            throw new RateLimitError(detail, status, text);
+        if (status >= 500)
+            throw new ServerError(detail, status, text);
+        throw new PromptevError(detail, status, text);
+    }
+    // ── Retry helper ────────────────────────────────────
+    async fetchWithRetry(url, init) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const resp = await fetch(url, {
+                    ...init,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!RETRYABLE_STATUS.has(resp.status) || attempt === this.maxRetries) {
+                    return resp;
+                }
+                lastError = new ServerError(`Server error (${resp.status})`, resp.status);
+            }
+            catch (err) {
+                if (err.name === "AbortError") {
+                    lastError = new NetworkError("Request timed out");
+                }
+                else {
+                    lastError = new NetworkError(`Network error: ${err.message}`);
+                }
+                if (attempt === this.maxRetries)
+                    throw lastError;
+            }
+            const delay = DEFAULT_BACKOFF * Math.pow(2, attempt);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        throw lastError;
+    }
+    // ── SSE parser ──────────────────────────────────────
+    async *parseSSE(response) {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (!line.startsWith("data: "))
+                        continue;
+                    try {
+                        const data = JSON.parse(line.slice(6));
+                        const event = {
+                            type: data.type || "unknown",
+                            output: data.output || "",
+                            raw: data,
+                        };
+                        yield event;
+                        if (event.type === "done" || event.type === "error")
+                            return;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    // ── Prompt API ──────────────────────────────────────
+    /**
+     * Compile and execute a prompt.
+     *
+     * If the prompt has a model configured, it compiles the template,
+     * sends it to the LLM, and returns the AI response. If no model
+     * is configured, it returns the compiled template string.
+     */
+    async runPrompt(promptKey, query, variables) {
+        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
+        const merged = { query, ...(variables ?? {}) };
+        const resp = await this.fetchWithRetry(url, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify({ variables: merged }),
         });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text);
+        const data = JSON.parse(text);
+        if (typeof data.prompt !== "string") {
+            throw new PromptevError("Unexpected response: missing 'prompt' field");
+        }
+        return data.prompt;
     }
     /**
-     * Compile a prompt by POSTing variables.
-     * Body shape (exact):
-     * {
-     *   "variables": {
-     *     "additionalProp1": "string",
-     *     "additionalProp2": "string",
-     *     "additionalProp3": "string"
-     *   }
-     * }
+     * Compile and execute a prompt with streaming.
+     *
+     * Use this when the prompt has tools attached or you want real-time
+     * output. Returns the same event types as agent streaming.
      */
-    async getPrompt(promptKey, variables = {}, opts) {
-        const url = `/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
+    async *streamPrompt(promptKey, query, variables) {
+        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}?stream=true`;
+        const merged = { query, ...(variables ?? {}) };
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let resp;
         try {
-            const resp = await this.client.post(url, { variables }, // <-- exact body
-            { signal: opts?.signal });
-            // Success shape: { prompt: string }
-            const compiled = resp.data?.prompt;
-            if (typeof compiled !== "string") {
-                throw new Error("Unexpected response: missing 'prompt' field");
-            }
-            return compiled;
+            resp = await fetch(url, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify({ variables: merged }),
+                signal: controller.signal,
+            });
         }
         catch (err) {
-            const ax = err;
-            const status = ax.response?.status;
-            const body = ax.response?.data;
-            const detail = body?.detail ?? body;
-            // Your API returns detail as a plain string on 400
-            if (typeof detail === "string") {
-                throw new Error(detail);
-            }
-            // Fallback error
-            const msg = `Request failed${status ? ` (${status})` : ""}`;
-            throw new Error(msg);
+            clearTimeout(timeoutId);
+            if (err.name === "AbortError")
+                throw new NetworkError("Request timed out");
+            throw new NetworkError(`Network error: ${err.message}`);
+        }
+        clearTimeout(timeoutId);
+        if (resp.status >= 400) {
+            const text = await resp.text();
+            PromptevClient.raiseForStatus(resp.status, text);
+        }
+        const contentType = resp.headers.get("content-type") || "";
+        // Non-streaming fallback: prompt has no model, backend returns JSON
+        if (!contentType.includes("text/event-stream")) {
+            const data = await resp.json();
+            yield {
+                type: "done",
+                output: data.prompt || "",
+                raw: data,
+            };
+            return;
+        }
+        yield* this.parseSSE(resp);
+    }
+    // ── Agent API ───────────────────────────────────────
+    /**
+     * Start a new agent chat session.
+     */
+    async startAgent(chatbotId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/start`;
+        const payload = {};
+        if (options?.visitor != null)
+            payload.visitor = options.visitor;
+        if (options?.platform && options.platform !== "sdk")
+            payload.platform = options.platform;
+        const resp = await this.fetchWithRetry(url, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(payload),
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text);
+        const data = JSON.parse(text);
+        return {
+            sessionToken: data.session_token,
+            chatbotId: data.chatbot_id,
+            name: data.name,
+            memoryEnabled: data.memory_enabled ?? false,
+            messages: data.messages ?? [],
+        };
+    }
+    /**
+     * Stream an agent response as SSE events.
+     */
+    async *streamAgent(chatbotId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify({ query: options.query }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err.name === "AbortError")
+                throw new NetworkError("Request timed out");
+            throw new NetworkError(`Network error: ${err.message}`);
+        }
+        clearTimeout(timeoutId);
+        if (resp.status >= 400) {
+            const text = await resp.text();
+            PromptevClient.raiseForStatus(resp.status, text);
         }
+        yield* this.parseSSE(resp);
     }
 }
 export default PromptevClient;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@promptev/client",
-  "version": "0.0.3",
-  "description": "Client library for accessing Promptev API",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript SDK for Promptev — run AI prompts and agents programmatically",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -32,9 +32,9 @@
     "client",
     "sdk",
     "ai",
-    "promptDev",
-    "promptdev",
-    "promptops",
+    "agents",
+    "agent-sdk",
+    "context-engineering",
     "typescript",
     "javascript"
   ],
@@ -44,10 +44,7 @@
     "build:cjs": "tsc -p tsconfig.cjs.json && node scripts/rename-cjs.cjs",
     "build": "npm run build:esm && npm run build:cjs"
   },
-  "dependencies": {
-    "axios": "^1.10.0",
-    "node-cache": "^5.1.2"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/node": "^20.10.0",
     "ts-node": "^10.9.2",

package/readme.md

@@ -1,116 +1,450 @@
-# promptev-client (JavaScript / TypeScript)
+# Promptev JavaScript SDK
 
-A lightweight JS SDK to fetch compiled prompts from [Promptev.ai](https://promptev.ai).
-
----
+The official JavaScript/TypeScript SDK for [Promptev.ai](https://promptev.ai) — run AI prompts and agents programmatically using your project API key.
 
 ## Installation
 
 ```bash
 npm install @promptev/client
 # or
-yarn install @promptev/client
-#or
+yarn add @promptev/client
+# or
 pnpm add @promptev/client
 ```
 
----
+Requires Node.js 18+ or any modern browser. Zero dependencies.
 
-## What is Promptev?
+## Platform Support
 
-[Promptev](https://promptev.ai) helps teams manage, version, and collaborate on AI prompts at scale — with variables, live context packs, histories, cost estimation, and SDK access.
----
+Works everywhere — backend, frontend, and edge runtimes. Built entirely on [Web Platform APIs](https://wintercg.org/) (`fetch`, `ReadableStream`, `AbortController`, `TextDecoder`) with no Node.js-specific modules.
 
-## Usage
+| Environment | Supported | Notes |
+|---|---|---|
+| **Node.js 18+** | ✅ | ESM and CommonJS |
+| **Bun** | ✅ | Native Web API support |
+| **Deno** | ✅ | Native Web API support |
+| **React / Next.js** | ✅ | Works with any bundler |
+| **Angular** | ✅ | Full TypeScript types included |
+| **Vue / Nuxt** | ✅ | Standard ESM import |
+| **Svelte / SvelteKit** | ✅ | Standard ESM import |
+| **Vanilla JS** | ✅ | No framework required |
+| **Cloudflare Workers** | ✅ | Edge runtime compatible |
+| **Vercel Edge Functions** | ✅ | Edge runtime compatible |
 
-### 1. Initialize the client
+```js
+// ESM (Node 18+, React, Next.js, Vue, Angular, Svelte, etc.)
+import { PromptevClient } from "@promptev/client";
+
+// CommonJS (legacy Node.js projects)
+const { PromptevClient } = require("@promptev/client");
+```
+
+## Quick Start
 
 ```ts
 import { PromptevClient } from "@promptev/client";
 
-const client = new PromptevClient({
-  projectKey: "pv_sk_abc123yourkey"
-});
+const client = new PromptevClient({ projectKey: "pv_sk_your_key_here" });
+
+// Run a prompt
+const result = await client.runPrompt("support-agent",
+  "What is the refund policy?",
+  { company: "Acme Corp" }
+);
+console.log(result);
+
+// Chat with an AI agent
+const session = await client.startAgent("your-agent-id");
+
+for await (const event of client.streamAgent(session.chatbotId, {
+  sessionToken: session.sessionToken,
+  query: "Summarize our Q4 sales report",
+})) {
+  if (event.type === "done") console.log(event.output);
+}
 ```
 
----
+## Prompts
+
+Promptev prompts are versioned, server-managed templates. `runPrompt` compiles the template with your variables — and if the prompt has a model configured in Promptev, it also executes it against the LLM and returns the AI response directly.
 
-### 2. Fetch a prompt with variables
+### Run a prompt with variables
 
 ```ts
-const prompt = await client.getPrompt("onboarding-email", {
-  name: "Ava",
-  product: "Promptev"
-});
+const result = await client.runPrompt("support-agent",
+  "How do I reset my password?",
+  { company: "Acme Corp", tone: "professional" }
+);
+```
 
-console.log(prompt);
-// "Subject: Welcome, Ava! Hey Ava, Thanks for joining Promptev..."
+### Run a prompt without variables
+
+```ts
+const result = await client.runPrompt("knowledge-base",
+  "What is the refund policy?"
+);
 ```
 
----
+### With a model configured (auto-execute)
 
-### 3. Fetch a prompt without variables
+If your prompt has a model and/or context packs attached in Promptev, `runPrompt` compiles the template, retrieves relevant context via RAG, sends it to the LLM, and returns the AI response:
 
 ```ts
-const staticPrompt = await client.getPrompt("system-intro");
-console.log(staticPrompt);
-// "You are a helpful AI assistant..."
+const answer = await client.runPrompt("support-agent",
+  "What is the refund policy?",
+  { company: "Acme Corp" }
+);
+console.log(answer); // "Our refund policy allows returns within 30 days..."
 ```
 
-> ⚠️ No variables? You can omit the second argument.
+### Without a model (use with your own LLM)
 
----
-
-### 4. Use with LLM APIs (OpenAI, Claude, Gemini, etc.)
+If no model is configured, `runPrompt` returns the compiled template — use it with any LLM:
 
 ```ts
 import OpenAI from "openai";
 
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
 const openai = new OpenAI({ apiKey: "sk-..." });
 
-const promptText = await client.getPrompt("clarify-topic", {
-  topic: "prompt engineering"
-});
+const systemPrompt = await client.runPrompt("support-agent",
+  "How do I reset my password?",
+  { company: "Acme Corp", tone: "professional" }
+);
 
 const response = await openai.chat.completions.create({
   model: "gpt-4",
-  messages: [{ role: "user", content: promptText }]
+  messages: [
+    { role: "system", content: systemPrompt },
+    { role: "user", content: "How do I reset my password?" },
+  ],
 });
-
 console.log(response.choices[0].message.content);
 ```
 
----
+### Stream a prompt (with tools or real-time output)
+
+When a prompt has tools attached (Jira, Slack, GitHub, etc.) or you want real-time output, use `streamPrompt`. It returns SSE events — same format as agent streaming:
+
+```ts
+for await (const event of client.streamPrompt("research-assistant",
+  "Find all P1 bugs assigned to me",
+  { project: "ACME" }
+)) {
+  if (event.type === "thoughts") console.log(`Thinking: ${event.output}`);
+  else if (event.type === "processing") console.log(`Running: ${event.output}`);
+  else if (event.type === "done") console.log(event.output);
+}
+```
+
+> **When to use which:**
+> - `runPrompt()` — simple prompt execution, no tools, returns a string
+> - `streamPrompt()` — prompts with tools, RAG-heavy queries, or when you want real-time output
+
+## Agents
+
+Promptev agents are deployed AI assistants with built-in memory, tools (Jira, Slack, GitHub, etc.), and RAG context packs. The SDK lets you start sessions and stream responses in real time.
+
+### Start a session
+
+```ts
+const session = await client.startAgent("your-agent-id", { visitor: "John" });
+
+console.log(session.sessionToken);  // Use this for all subsequent messages
+console.log(session.name);          // Agent display name
+console.log(session.memoryEnabled); // Whether agent retains conversation context
+```
+
+### Stream a response
 
-## Features
+The agent responds via Server-Sent Events (SSE). Each event has a `type` and `output`:
 
-- ✅ Works with or without prompt variables
-- 🔐 Safe for frontend & server use
-- 🔌 Works with any LLM provider
+| Event Type | Description |
+|---|---|
+| `thoughts` | Agent's internal reasoning |
+| `processing` | Tool execution status (e.g., "Searching Jira...") |
+| `approval_required` | Agent needs permission to run a tool |
+| `done` | Final response text |
+| `error` | Something went wrong |
 
----
+```ts
+for await (const event of client.streamAgent(session.chatbotId, {
+  sessionToken: session.sessionToken,
+  query: "What are the open P1 bugs in our backlog?",
+})) {
+  if (event.type === "thoughts") console.log(`Thinking: ${event.output}`);
+  else if (event.type === "processing") console.log(`Running: ${event.output}`);
+  else if (event.type === "done") console.log(`\n${event.output}`);
+  else if (event.type === "error") console.log(`Error: ${event.output}`);
+}
+```
 
-## Options
+### Multi-turn conversation
+
+The session token maintains conversation context across messages:
 
 ```ts
-new PromptevClient({
-  projectKey: "pv_sk_abc...",
-  baseUrl: "https://api.promptev.ai",   // optional
-  headers: { "X-PTV-API-Key": "..." }   // optional: extra headers
+const session = await client.startAgent("your-agent-id", { visitor: "Sarah" });
+
+// First message
+for await (const event of client.streamAgent(session.chatbotId, {
+  sessionToken: session.sessionToken,
+  query: "Summarize our Q4 sales report",
+})) {
+  if (event.type === "done") console.log(event.output);
+}
+
+// Follow-up — agent remembers the previous context
+for await (const event of client.streamAgent(session.chatbotId, {
+  sessionToken: session.sessionToken,
+  query: "Compare that with Q3",
+})) {
+  if (event.type === "done") console.log(event.output);
+}
+```
+
+### Collect the final response only
+
+```ts
+async function askAgent(client, session, query) {
+  for await (const event of client.streamAgent(session.chatbotId, {
+    sessionToken: session.sessionToken,
+    query,
+  })) {
+    if (event.type === "done") return event.output;
+    if (event.type === "error") throw new Error(event.output);
+  }
+}
+
+const answer = await askAgent(client, session, "What's our monthly churn rate?");
+```
+
+## Error Handling
+
+The SDK raises typed errors for each failure scenario:
+
+```ts
+import {
+  PromptevClient,
+  ValidationError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+} from "@promptev/client";
+
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+try {
+  const result = await client.runPrompt("my-prompt", "Hello", { name: "Ava" });
+} catch (err) {
+  if (err instanceof ValidationError) {
+    // 400 — missing variables, bad input
+    console.log(`Invalid request: ${err.message}`);
+  } else if (err instanceof NotFoundError) {
+    // 404 — prompt or project not found
+    console.log(`Not found: ${err.message}`);
+  } else if (err instanceof AuthenticationError) {
+    // 401/403 — invalid API key or agent not active
+    console.log(`Auth error: ${err.message}`);
+  } else if (err instanceof RateLimitError) {
+    // 429 — API usage quota exceeded
+    console.log(`Rate limited: ${err.message}`);
+  } else if (err instanceof ServerError) {
+    // 5xx — server error (after retries exhausted)
+    console.log(`Server error: ${err.message}`);
+  } else if (err instanceof NetworkError) {
+    // Connection failed, timeout, DNS error
+    console.log(`Network error: ${err.message}`);
+  }
+}
+```
+
+All errors extend `PromptevError` and include:
+- `err.statusCode` — HTTP status code (if applicable)
+- `err.responseText` — Raw response body (for debugging)
+
+## Configuration
+
+```ts
+const client = new PromptevClient({
+  projectKey: "pv_sk_...",              // Required — your project API key
+  baseUrl: "https://api.promptev.ai",   // Default — override for self-hosted
+  timeout: 30000,                        // Default — request timeout in ms
+  maxRetries: 2,                         // Default — retries for 502/503/504
+  headers: { "X-Custom": "value" },      // Optional — extra HTTP headers
 });
 ```
 
----
+| Parameter | Default | Description |
+|---|---|---|
+| `projectKey` | *required* | Your Promptev project API key |
+| `baseUrl` | `https://api.promptev.ai` | API base URL |
+| `timeout` | `30000` | Request timeout in milliseconds |
+| `maxRetries` | `2` | Automatic retries for transient server errors (502, 503, 504) |
+| `headers` | `{}` | Additional HTTP headers |
+
+## API Reference
+
+### `PromptevClient`
+
+| Method | Description | Returns |
+|---|---|---|
+| `runPrompt(promptKey, query, variables?)` | Compile and execute a prompt | `Promise<string>` |
+| `streamPrompt(promptKey, query, variables?)` | Stream prompt execution with tools | `AsyncGenerator<AgentEvent>` |
+| `startAgent(chatbotId, options?)` | Start agent session | `Promise<AgentSession>` |
+| `streamAgent(chatbotId, options)` | Stream agent response | `AsyncGenerator<AgentEvent>` |
+
+### `AgentSession`
+
+| Field | Type | Description |
+|---|---|---|
+| `sessionToken` | `string` | Token for subsequent stream calls |
+| `chatbotId` | `string` | Agent identifier |
+| `name` | `string` | Agent display name |
+| `memoryEnabled` | `boolean` | Whether agent retains conversation context |
+| `messages` | `array` | Previous messages (populated when resuming a session) |
+
+### `AgentEvent`
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `string` | Event type: `thoughts`, `processing`, `done`, `error`, `approval_required` |
+| `output` | `string` | Event content text |
+| `raw` | `object` | Full parsed SSE event data |
+
+### Exceptions
+
+| Error | HTTP Status | When |
+|---|---|---|
+| `ValidationError` | 400 | Missing required variables, bad input |
+| `AuthenticationError` | 401, 403 | Invalid API key, agent not active |
+| `NotFoundError` | 404 | Project, prompt, or agent not found |
+| `RateLimitError` | 429 | API usage quota exceeded |
+| `ServerError` | 5xx | Server error (after retries exhausted) |
+| `NetworkError` | — | Connection failed, timeout, DNS error |
+| `PromptevError` | any | Base class for all above errors |
+
+## Framework Examples
+
+### React
+
+```tsx
+import { useState } from "react";
+import { PromptevClient } from "@promptev/client";
+
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+export function AskAI() {
+  const [answer, setAnswer] = useState("");
+  const [loading, setLoading] = useState(false);
+
+  async function handleAsk() {
+    setLoading(true);
+    try {
+      const result = await client.runPrompt("support-agent", "What is your refund policy?");
+      setAnswer(result);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleAsk} disabled={loading}>Ask AI</button>
+      {answer && <p>{answer}</p>}
+    </div>
+  );
+}
+```
+
+### React — Streaming Agent Chat
+
+```tsx
+import { useState, useRef } from "react";
+import { PromptevClient } from "@promptev/client";
+
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+export function AgentChat() {
+  const [messages, setMessages] = useState<string[]>([]);
+  const [input, setInput] = useState("");
+  const sessionRef = useRef(null);
+
+  async function startChat() {
+    sessionRef.current = await client.startAgent("your-agent-id", { visitor: "user" });
+  }
+
+  async function sendMessage() {
+    if (!sessionRef.current) await startChat();
+
+    setMessages((prev) => [...prev, `You: ${input}`]);
+    const query = input;
+    setInput("");
+
+    for await (const event of client.streamAgent(sessionRef.current.chatbotId, {
+      sessionToken: sessionRef.current.sessionToken,
+      query,
+    })) {
+      if (event.type === "done") {
+        setMessages((prev) => [...prev, `Agent: ${event.output}`]);
+      }
+    }
+  }
+
+  return (
+    <div>
+      {messages.map((msg, i) => <p key={i}>{msg}</p>)}
+      <input value={input} onChange={(e) => setInput(e.target.value)} />
+      <button onClick={sendMessage}>Send</button>
+    </div>
+  );
+}
+```
+
+### Node.js / Express API
+
+```js
+import express from "express";
+import { PromptevClient } from "@promptev/client";
+
+const app = express();
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+app.post("/api/ask", express.json(), async (req, res) => {
+  const answer = await client.runPrompt("support-agent", req.body.question);
+  res.json({ answer });
+});
+
+app.listen(3000);
+```
+
+### Vanilla HTML
+
+```html
+<script type="module">
+  import { PromptevClient } from "https://cdn.jsdelivr.net/npm/@promptev/client/dist/esm/index.js";
+
+  const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+  document.getElementById("ask-btn").addEventListener("click", async () => {
+    const answer = await client.runPrompt("support-agent", "What is the refund policy?");
+    document.getElementById("output").textContent = answer;
+  });
+</script>
+```
 
 ## License
 
-This SDK is **commercial software** by Promptev Inc.
+This SDK is commercial software by [Promptev Inc](https://promptev.ai).
 
-By using this package, you agree to the terms in [`LICENSE.txt`](./LICENSE.txt).
+- Free tier use allowed
+- Production use requires an active subscription
 
----
+See [LICENSE](./LICENSE.txt) for full terms.
 
-## Contact
+## Support
 
-- 🌐 https://promptev.ai
-- 📧 support@promptev.ai
+- Website: [promptev.ai](https://promptev.ai)
+- Email: support@promptev.ai

package/dist/cjs/index.d.ts

@@ -1,30 +0,0 @@
-export interface PromptliyClientConfig {
-    baseUrl?: string;
-    projectKey: string;
-}
-export interface Prompt {
-    prompt: string;
-    variables: string[] | string | null;
-    format(values?: Record<string, string>): string;
-}
-export declare class PromptliyClient {
-    private client;
-    private baseUrl;
-    private projectKey;
-    private promptCache;
-    private refreshInterval;
-    private cacheRefreshIntervalMs;
-    private isReady;
-    constructor(config: PromptliyClientConfig);
-    private ensureReady;
-    private startCacheRefresh;
-    private refreshCachedPrompt;
-    private createPromptObject;
-    getPrompt(promptKey: string): Promise<Prompt> & {
-        format: (values: Record<string, string>) => Promise<string>;
-    };
-    private fetchPrompt;
-    private fetchPromptFromServer;
-    dispose(): Promise<void>;
-}
-export default PromptliyClient;