@promptev/client 0.0.3 → 0.2.0

package/dist/cjs/index.cjs

@@ -1,58 +1,276 @@
 "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();
+        }
+    }
+    // ── Agent API ───────────────────────────────────────
+    /**
+     * Trigger an agent in a single blocking call — the primary way to use the SDK.
+     *
+     * Creates (or resumes) a session AND runs the agent, returning the final
+     * response as JSON. Any tools the agent has attached run server-side.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     * @param message - The user message to send to the agent.
+     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
+     *   conversation memory. Omit it for a fresh, stateless run.
+     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
+     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
+     *   to continue the same conversation.
+     *
+     * @example
+     * const { response, sessionId } = await client.triggerAgent(
+     *   "your-agent-id",
+     *   "What is the refund policy?",
+     *   { variables: { company: "Acme Corp" } }
+     * );
+     * // Follow-up keeps memory:
+     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
+     */
+    async triggerAgent(agentId, message, opts) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/trigger`;
+        const payload = { message };
+        if (opts?.sessionId != null)
+            payload.session_id = opts.sessionId;
+        if (opts?.variables != null)
+            payload.variables = opts.variables;
+        // Optional caller/end-user id stored on the chat session; defaults server-side
+        // to a generated webhook_<id> when omitted.
+        if (opts?.visitor != null)
+            payload.visitor = opts.visitor;
+        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 {
+            response: typeof data.response === "string" ? data.response : "",
+            sessionId: data.session_id,
+        };
     }
     /**
-     * Compile a prompt by POSTing variables.
-     * Body shape (exact):
-     * {
-     *   "variables": {
-     *     "additionalProp1": "string",
-     *     "additionalProp2": "string",
-     *     "additionalProp3": "string"
-     *   }
-     * }
+     * Start a new agent chat session (streaming flow).
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    async getPrompt(promptKey, variables = {}, opts) {
-        const url = `/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
+    async startAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/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,
+            agentId: data.chatbot_id,
+            name: data.name,
+            memoryEnabled: data.memory_enabled ?? false,
+            messages: data.messages ?? [],
+        };
+    }
+    /**
+     * Stream an agent response as SSE events.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     */
+    async *streamAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
+        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({ query: options.query }),
+                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);
         }
+        yield* this.parseSSE(resp);
     }
 }
 exports.PromptevClient = PromptevClient;

package/dist/esm/index.d.ts

@@ -1,26 +1,104 @@
 export interface PromptevClientConfig {
-    baseUrl?: string;
     projectKey: string;
+    baseUrl?: string;
     headers?: Record<string, string>;
+    timeout?: number;
+    maxRetries?: number;
+}
+export interface AgentSession {
+    sessionToken: string;
+    agentId: string;
+    name: string;
+    memoryEnabled: boolean;
+    messages: Record<string, any>[];
+}
+export interface TriggerResult {
+    response: string;
+    sessionId: string;
+}
+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;
+    /**
+     * Trigger an agent in a single blocking call — the primary way to use the SDK.
+     *
+     * Creates (or resumes) a session AND runs the agent, returning the final
+     * response as JSON. Any tools the agent has attached run server-side.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     * @param message - The user message to send to the agent.
+     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
+     *   conversation memory. Omit it for a fresh, stateless run.
+     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
+     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
+     *   to continue the same conversation.
+     *
+     * @example
+     * const { response, sessionId } = await client.triggerAgent(
+     *   "your-agent-id",
+     *   "What is the refund policy?",
+     *   { variables: { company: "Acme Corp" } }
+     * );
+     * // Follow-up keeps memory:
+     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
+     */
+    triggerAgent(agentId: string, message: string, opts?: {
+        sessionId?: string;
+        variables?: Record<string, any>;
+        visitor?: string;
+    }): Promise<TriggerResult>;
+    /**
+     * Start a new agent chat session (streaming flow).
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     */
+    startAgent(agentId: 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.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    getPrompt(promptKey: string, variables?: Record<string, string>, opts?: {
-        signal?: AbortSignal;
-    }): Promise<string>;
+    streamAgent(agentId: string, options: {
+        sessionToken: string;
+        query: string;
+    }): AsyncGenerator<AgentEvent>;
 }
 export default PromptevClient;

package/dist/esm/index.js

@@ -1,52 +1,266 @@
-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();
+        }
+    }
+    // ── Agent API ───────────────────────────────────────
+    /**
+     * Trigger an agent in a single blocking call — the primary way to use the SDK.
+     *
+     * Creates (or resumes) a session AND runs the agent, returning the final
+     * response as JSON. Any tools the agent has attached run server-side.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     * @param message - The user message to send to the agent.
+     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
+     *   conversation memory. Omit it for a fresh, stateless run.
+     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
+     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
+     *   to continue the same conversation.
+     *
+     * @example
+     * const { response, sessionId } = await client.triggerAgent(
+     *   "your-agent-id",
+     *   "What is the refund policy?",
+     *   { variables: { company: "Acme Corp" } }
+     * );
+     * // Follow-up keeps memory:
+     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
+     */
+    async triggerAgent(agentId, message, opts) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/trigger`;
+        const payload = { message };
+        if (opts?.sessionId != null)
+            payload.session_id = opts.sessionId;
+        if (opts?.variables != null)
+            payload.variables = opts.variables;
+        // Optional caller/end-user id stored on the chat session; defaults server-side
+        // to a generated webhook_<id> when omitted.
+        if (opts?.visitor != null)
+            payload.visitor = opts.visitor;
+        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 {
+            response: typeof data.response === "string" ? data.response : "",
+            sessionId: data.session_id,
+        };
     }
     /**
-     * Compile a prompt by POSTing variables.
-     * Body shape (exact):
-     * {
-     *   "variables": {
-     *     "additionalProp1": "string",
-     *     "additionalProp2": "string",
-     *     "additionalProp3": "string"
-     *   }
-     * }
+     * Start a new agent chat session (streaming flow).
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    async getPrompt(promptKey, variables = {}, opts) {
-        const url = `/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
+    async startAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/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,
+            agentId: data.chatbot_id,
+            name: data.name,
+            memoryEnabled: data.memory_enabled ?? false,
+            messages: data.messages ?? [],
+        };
+    }
+    /**
+     * Stream an agent response as SSE events.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     */
+    async *streamAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
+        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({ query: options.query }),
+                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);
         }
+        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.2.0",
+  "description": "JavaScript/TypeScript SDK for Promptev — trigger and stream your AI agents programmatically",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -13,7 +13,7 @@
       "types": "./dist/esm/index.d.ts"
     }
   },
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Promptev Inc. <support@promptev.ai>",
   "private": false,
   "publishConfig": {
@@ -27,14 +27,13 @@
   ],
   "keywords": [
     "promptev",
-    "prompts",
+    "agents",
+    "agent-sdk",
+    "ai",
     "api",
     "client",
     "sdk",
-    "ai",
-    "promptDev",
-    "promptdev",
-    "promptops",
+    "context-engineering",
     "typescript",
     "javascript"
   ],
@@ -44,10 +43,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,463 @@
-# 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) — trigger and stream your AI **agents** programmatically using your project API key.
 
----
+> In Promptev, an **agent** is your deployed AI assistant: instructions + model + tools (Jira, Slack, GitHub, …) + context packs, all configured in the dashboard. This SDK runs those agents. Tools execute server-side, memory is built in.
 
 ## 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.
+
+## Platform Support
+
+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.
 
-## What is Promptev?
+| 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 |
 
-[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.
----
+```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");
+```
 
-## Usage
+## Quick Start
 
-### 1. Initialize the client
+The fastest way to use an agent is `triggerAgent` — one blocking call that runs the agent and returns its final answer. Pass your agent's id (from the **Deploy** tab) and a message:
 
 ```ts
 import { PromptevClient } from "@promptev/client";
 
-const client = new PromptevClient({
-  projectKey: "pv_sk_abc123yourkey"
-});
+const client = new PromptevClient({ projectKey: "pv_sk_your_key_here" });
+
+const { response, sessionId } = await client.triggerAgent(
+  "your-agent-id",
+  "What is the refund policy?",
+  { variables: { company: "Acme Corp" } }
+);
+console.log(response);
+
+// Keep conversation memory by passing the same sessionId back:
+const followUp = await client.triggerAgent(
+  "your-agent-id",
+  "And for digital goods?",
+  { sessionId }
+);
+console.log(followUp.response);
 ```
 
----
+That's it. The agent's tools, context packs, and model all run server-side — you just get the answer.
+
+## `triggerAgent` — run an agent in one call
 
-### 2. Fetch a prompt with variables
+`triggerAgent(agentId, message, opts?)` creates **or** resumes a session **and** runs the agent, returning the final response as JSON.
 
 ```ts
-const prompt = await client.getPrompt("onboarding-email", {
-  name: "Ava",
-  product: "Promptev"
-});
+const result = await client.triggerAgent("your-agent-id", "Summarize our Q4 sales report");
+console.log(result.response);   // the agent's answer
+console.log(result.sessionId);  // pass this back to continue the conversation
+```
 
-console.log(prompt);
-// "Subject: Welcome, Ava! Hey Ava, Thanks for joining Promptev..."
+| Parameter | Type | Description |
+|---|---|---|
+| `agentId` | `string` | Your agent's id (from the Deploy tab) |
+| `message` | `string` | The user message to send to the agent |
+| `opts.sessionId` | `string?` | Pass the `sessionId` from a previous call to keep memory. Omit for a fresh, stateless run. |
+| `opts.variables` | `object?` | Fills the agent's `{{...}}` prompt variables |
+| `opts.visitor` | `string?` | Attribute the run to an end-user id (stored on the chat session for analytics/audit). Defaults to a generated `webhook_<id>`. Set it on the first call of a conversation; a resumed session keeps its original visitor. |
+
+Returns `{ response: string; sessionId: string }`.
+
+```ts
+// Attribute the run to a specific end-user:
+const { response } = await client.triggerAgent(
+  "your-agent-id",
+  "How do I reset my password?",
+  { visitor: "user_12345" }
+);
 ```
 
----
+### Stateful (with memory)
 
-### 3. Fetch a prompt without variables
+Pass the returned `sessionId` back on each follow-up to keep context:
 
 ```ts
-const staticPrompt = await client.getPrompt("system-intro");
-console.log(staticPrompt);
-// "You are a helpful AI assistant..."
+let { response, sessionId } = await client.triggerAgent("your-agent-id", "Summarize Q4 sales");
+console.log(response);
+
+({ response } = await client.triggerAgent("your-agent-id", "Compare that with Q3", { sessionId }));
+console.log(response);
 ```
 
-> ⚠️ No variables? You can omit the second argument.
+### Stateless (no memory)
+
+Omit `sessionId` for an independent, one-shot run each time:
 
----
+```ts
+const { response } = await client.triggerAgent(
+  "your-agent-id",
+  "What is the refund policy?",
+  { variables: { company: "Acme Corp" } }
+);
+```
+
+### With prompt variables
 
-### 4. Use with LLM APIs (OpenAI, Claude, Gemini, etc.)
+If your agent's instructions contain `{{...}}` placeholders, fill them via `variables`:
 
 ```ts
-import OpenAI from "openai";
+const { response } = await client.triggerAgent(
+  "your-agent-id",
+  "How do I reset my password?",
+  { variables: { company: "Acme Corp", tone: "professional" } }
+);
+```
 
-const openai = new OpenAI({ apiKey: "sk-..." });
+## Streaming an agent
 
-const promptText = await client.getPrompt("clarify-topic", {
-  topic: "prompt engineering"
-});
+When you want real-time output — agent reasoning, tool-execution status, and the final answer as they happen — use the streaming flow: `startAgent` to open a session, then `streamAgent` to receive [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
 
-const response = await openai.chat.completions.create({
-  model: "gpt-4",
-  messages: [{ role: "user", content: promptText }]
-});
+### Start a session
+
+```ts
+const session = await client.startAgent("your-agent-id", { visitor: "John" });
+
+console.log(session.sessionToken);  // use this for all subsequent stream calls
+console.log(session.agentId);       // the agent id, echoed back
+console.log(session.name);          // agent display name
+console.log(session.memoryEnabled); // whether the agent retains conversation context
+```
+
+### Stream a response
+
+Each event has a `type` and `output`:
+
+| 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.agentId, {
+  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}`);
+}
+```
+
+### Multi-turn conversation
+
+The session token maintains conversation context across messages:
 
-console.log(response.choices[0].message.content);
+```ts
+const session = await client.startAgent("your-agent-id", { visitor: "Sarah" });
+
+// First message
+for await (const event of client.streamAgent(session.agentId, {
+  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.agentId, {
+  sessionToken: session.sessionToken,
+  query: "Compare that with Q3",
+})) {
+  if (event.type === "done") console.log(event.output);
+}
 ```
 
----
+### Collect the final response only
 
-## Features
+```ts
+async function askAgent(client, session, query) {
+  for await (const event of client.streamAgent(session.agentId, {
+    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?");
+```
 
-- ✅ Works with or without prompt variables
-- 🔐 Safe for frontend & server use
-- 🔌 Works with any LLM provider
+> **When to use which:**
+> - `triggerAgent()` — the default. One call, blocking, returns the final answer. Best for APIs, jobs, and server-to-server use.
+> - `startAgent()` + `streamAgent()` — when you want to render reasoning and tool progress live (e.g., a chat UI).
 
----
+## Error Handling
 
-## Options
+The SDK raises typed errors for each failure scenario:
 
 ```ts
-new PromptevClient({
-  projectKey: "pv_sk_abc...",
-  baseUrl: "https://api.promptev.ai",   // optional
-  headers: { "X-PTV-API-Key": "..." }   // optional: extra headers
+import {
+  PromptevClient,
+  ValidationError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+} from "@promptev/client";
+
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+try {
+  const { response } = await client.triggerAgent("your-agent-id", "Hello");
+  console.log(response);
+} catch (err) {
+  if (err instanceof ValidationError) {
+    // 400 — missing variables, bad input
+    console.log(`Invalid request: ${err.message}`);
+  } else if (err instanceof NotFoundError) {
+    // 404 — agent 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)
+
+| Error | HTTP Status | When |
+|---|---|---|
+| `ValidationError` | 400 | Missing required variables, bad input |
+| `AuthenticationError` | 401, 403 | Invalid API key, agent not active |
+| `NotFoundError` | 404 | Project 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 |
+
+## 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 (`pv_sk_...`) |
+| `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 |
+|---|---|---|
+| `triggerAgent(agentId, message, opts?)` | Run an agent in one blocking call | `Promise<TriggerResult>` |
+| `startAgent(agentId, options?)` | Start a streaming agent session | `Promise<AgentSession>` |
+| `streamAgent(agentId, options)` | Stream an agent response (SSE) | `AsyncGenerator<AgentEvent>` |
+
+### `TriggerResult`
+
+| Field | Type | Description |
+|---|---|---|
+| `response` | `string` | The agent's final answer |
+| `sessionId` | `string` | Pass back as `opts.sessionId` to continue the conversation |
+
+### `AgentSession`
+
+| Field | Type | Description |
+|---|---|---|
+| `sessionToken` | `string` | Token for subsequent stream calls |
+| `agentId` | `string` | Agent identifier |
+| `name` | `string` | Agent display name |
+| `memoryEnabled` | `boolean` | Whether the 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 |
+
+## Framework Examples
+
+### React
+
+```tsx
+import { useState } from "react";
+import { PromptevClient } from "@promptev/client";
+
+const client = new PromptevClient({ projectKey: "pv_sk_..." });
+
+export function AskAgent() {
+  const [answer, setAnswer] = useState("");
+  const [loading, setLoading] = useState(false);
+
+  async function handleAsk() {
+    setLoading(true);
+    try {
+      const { response } = await client.triggerAgent("your-agent-id", "What is your refund policy?");
+      setAnswer(response);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleAsk} disabled={loading}>Ask Agent</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.agentId, {
+      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 { response, sessionId } = await client.triggerAgent(
+    "your-agent-id",
+    req.body.question,
+    { sessionId: req.body.sessionId }   // pass back to keep memory across turns
+  );
+  res.json({ answer: response, sessionId });
 });
+
+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 { response } = await client.triggerAgent("your-agent-id", "What is the refund policy?");
+    document.getElementById("output").textContent = response;
+  });
+</script>
 ```
 
----
+## Building from source
+
+```bash
+npm install
+npm run build   # builds both ESM (dist/esm) and CommonJS (dist/cjs)
+```
 
 ## 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;