roe-typescript 0.1.0

package/dist/src/api/agents.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsAPI = exports.AgentJobsAPI = exports.AgentVersionsAPI = void 0;
+const pagination_1 = require("../utils/pagination");
+const fileDetection_1 = require("../utils/fileDetection");
+const exceptions_1 = require("../exceptions");
+const agent_1 = require("../models/agent");
+const job_1 = require("../models/job");
+/**
+ * Validates that a value is a valid UUID string.
+ * @throws BadRequestError if the value is not a valid UUID
+ */
+function validateUuid(value, fieldName) {
+    if (!(0, fileDetection_1.isUuidString)(value)) {
+        throw new exceptions_1.BadRequestError(`Invalid ${fieldName}: "${value}" is not a valid UUID`, 400);
+    }
+}
+class AgentVersionsAPI {
+    constructor(agentsApi) {
+        this.agentsApi = agentsApi;
+    }
+    get http() {
+        return this.agentsApi.httpClient;
+    }
+    async list(agentId) {
+        validateUuid(agentId, "agentId");
+        const data = await this.http.get(`/v1/agents/${agentId}/versions/`);
+        return data.map((v) => this.wrap(v));
+    }
+    async retrieve(agentId, versionId, getSupportsEval) {
+        validateUuid(agentId, "agentId");
+        validateUuid(versionId, "versionId");
+        const params = getSupportsEval === undefined ? undefined : { get_supports_eval: String(getSupportsEval).toLowerCase() };
+        const data = await this.http.get(`/v1/agents/${agentId}/versions/${versionId}/`, params);
+        return this.wrap(data);
+    }
+    async retrieveCurrent(agentId) {
+        validateUuid(agentId, "agentId");
+        const data = await this.http.get(`/v1/agents/${agentId}/versions/current/`);
+        return this.wrap(data);
+    }
+    async create(params) {
+        validateUuid(params.agentId, "agentId");
+        const payload = {
+            input_definitions: params.inputDefinitions ?? [],
+            engine_config: params.engineConfig ?? {},
+        };
+        if (params.versionName !== undefined)
+            payload.version_name = params.versionName;
+        if (params.description !== undefined)
+            payload.description = params.description;
+        const data = await this.http.post({
+            url: `/v1/agents/${params.agentId}/versions/`,
+            json: payload,
+        });
+        return this.retrieve(params.agentId, data.id);
+    }
+    async update(agentId, versionId, updates) {
+        validateUuid(agentId, "agentId");
+        validateUuid(versionId, "versionId");
+        const payload = {};
+        if (updates.versionName !== undefined)
+            payload.version_name = updates.versionName;
+        if (updates.description !== undefined)
+            payload.description = updates.description;
+        await this.http.put(`/v1/agents/${agentId}/versions/${versionId}/`, payload);
+    }
+    async delete(agentId, versionId) {
+        validateUuid(agentId, "agentId");
+        validateUuid(versionId, "versionId");
+        await this.http.delete(`/v1/agents/${agentId}/versions/${versionId}/`);
+    }
+    wrap(data) {
+        const obj = new agent_1.AgentVersionWithApi(data);
+        obj.setAgentsApi(this.agentsApi);
+        return obj;
+    }
+}
+exports.AgentVersionsAPI = AgentVersionsAPI;
+class AgentJobsAPI {
+    constructor(agentsApi) {
+        this.agentsApi = agentsApi;
+    }
+    get http() {
+        return this.agentsApi.httpClient;
+    }
+    async retrieveStatus(jobId) {
+        validateUuid(jobId, "jobId");
+        return this.http.get(`/v1/agents/jobs/${jobId}/status/`);
+    }
+    async retrieveResult(jobId) {
+        validateUuid(jobId, "jobId");
+        return this.http.get(`/v1/agents/jobs/${jobId}/result/`);
+    }
+    async retrieveStatusMany(jobIds) {
+        const results = [];
+        for (const chunk of this.iterChunks(jobIds, AgentJobsAPI.MAX_BATCH_SIZE)) {
+            if (!chunk.length)
+                continue;
+            const data = await this.http.post({
+                url: "/v1/agents/jobs/statuses/",
+                json: { job_ids: chunk },
+            });
+            results.push(...data);
+        }
+        return results;
+    }
+    async retrieveResultMany(jobIds) {
+        const results = [];
+        for (const chunk of this.iterChunks(jobIds, AgentJobsAPI.MAX_BATCH_SIZE)) {
+            if (!chunk.length)
+                continue;
+            const data = await this.http.post({
+                url: "/v1/agents/jobs/results/",
+                json: { job_ids: chunk },
+            });
+            results.push(...data);
+        }
+        return results;
+    }
+    async downloadReference(jobId, resourceId, asAttachment = false) {
+        validateUuid(jobId, "jobId");
+        validateUuid(resourceId, "resourceId");
+        const params = asAttachment ? { download: "true" } : undefined;
+        return this.http.getBytes(`/v1/agents/jobs/${jobId}/references/${resourceId}/`, params);
+    }
+    async deleteData(jobId) {
+        validateUuid(jobId, "jobId");
+        return this.http.post({
+            url: `/v1/agents/jobs/${jobId}/delete-data/`,
+        });
+    }
+    *iterChunks(items, size) {
+        for (let i = 0; i < items.length; i += size) {
+            yield items.slice(i, i + size);
+        }
+    }
+}
+exports.AgentJobsAPI = AgentJobsAPI;
+AgentJobsAPI.MAX_BATCH_SIZE = 1000;
+class AgentsAPI {
+    constructor(config, httpClient) {
+        this.config = config;
+        this.httpClient = httpClient;
+        this.versions = new AgentVersionsAPI(this);
+        this.jobs = new AgentJobsAPI(this);
+    }
+    wrapBase(data) {
+        const obj = new agent_1.BaseAgentWithApi(data);
+        obj.setAgentsApi(this);
+        return obj;
+    }
+    async list(params) {
+        const query = pagination_1.PaginationHelper.buildQueryParams(this.config.organizationId, params?.page, params?.pageSize);
+        const resp = await this.httpClient.get("/v1/agents/", query);
+        const wrapped = resp.results.map((a) => this.wrapBase(a));
+        return { ...resp, results: wrapped };
+    }
+    async retrieve(agentId) {
+        validateUuid(agentId, "agentId");
+        const data = await this.httpClient.get(`/v1/agents/${agentId}/`);
+        return this.wrapBase(data);
+    }
+    async create(params) {
+        const payload = {
+            name: params.name,
+            engine_class_id: params.engineClassId,
+            organization_id: this.config.organizationId,
+            input_definitions: params.inputDefinitions ?? [],
+            engine_config: params.engineConfig ?? {},
+        };
+        if (params.versionName !== undefined)
+            payload.version_name = params.versionName;
+        if (params.description !== undefined)
+            payload.description = params.description;
+        const data = await this.httpClient.post({ url: "/v1/agents/", json: payload });
+        return this.wrapBase(data);
+    }
+    async update(agentId, updates) {
+        validateUuid(agentId, "agentId");
+        const payload = {};
+        if (updates.name !== undefined)
+            payload.name = updates.name;
+        if (updates.disableCache !== undefined)
+            payload.disable_cache = updates.disableCache;
+        if (updates.cacheFailedJobs !== undefined)
+            payload.cache_failed_jobs = updates.cacheFailedJobs;
+        const data = await this.httpClient.put(`/v1/agents/${agentId}/`, payload);
+        return this.wrapBase(data);
+    }
+    async delete(agentId) {
+        validateUuid(agentId, "agentId");
+        await this.httpClient.delete(`/v1/agents/${agentId}/`);
+    }
+    async duplicate(agentId) {
+        validateUuid(agentId, "agentId");
+        const data = await this.httpClient.post({
+            url: `/v1/agents/${agentId}/duplicate/`,
+        });
+        return this.wrapBase(data.base_agent);
+    }
+    async run(params) {
+        validateUuid(params.agentId, "agentId");
+        const response = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${params.agentId}/async/`, params.inputs);
+        // Handle both string response and object response formats
+        const jobId = typeof response === "string" ? response : response?.job_id;
+        if (!jobId || typeof jobId !== "string") {
+            throw new exceptions_1.RoeAPIException(`Invalid job ID returned from API: ${JSON.stringify(response)}`);
+        }
+        if (!(0, fileDetection_1.isUuidString)(jobId)) {
+            throw new exceptions_1.RoeAPIException(`Invalid job ID format returned from API: ${jobId}`);
+        }
+        return new job_1.Job({ agentsApi: this, jobId, timeoutSeconds: params.timeoutSeconds });
+    }
+    async runMany(params) {
+        validateUuid(params.agentId, "agentId");
+        const allJobIds = [];
+        for (const chunk of this.iterChunks(params.batchInputs, AgentsAPI.MAX_BATCH_SIZE)) {
+            if (!chunk.length)
+                continue;
+            const resp = await this.httpClient.post({
+                url: `/v1/agents/run/${params.agentId}/async/many/`,
+                json: { inputs: chunk },
+            });
+            // Validate each returned job ID
+            for (const jobId of resp) {
+                if (!jobId || typeof jobId !== "string") {
+                    throw new exceptions_1.RoeAPIException(`Invalid job ID returned from batch API: ${JSON.stringify(jobId)}`);
+                }
+                if (!(0, fileDetection_1.isUuidString)(jobId)) {
+                    throw new exceptions_1.RoeAPIException(`Invalid job ID format returned from batch API: ${jobId}`);
+                }
+                allJobIds.push(jobId);
+            }
+        }
+        return new job_1.JobBatch({ agentsApi: this, jobIds: allJobIds, timeoutSeconds: params.timeoutSeconds });
+    }
+    async runSync(agentId, inputs) {
+        validateUuid(agentId, "agentId");
+        const resp = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${agentId}/`, inputs);
+        return resp;
+    }
+    async runVersion(params) {
+        validateUuid(params.agentId, "agentId");
+        validateUuid(params.versionId, "versionId");
+        const response = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${params.agentId}/versions/${params.versionId}/async/`, params.inputs);
+        // Handle both string response and object response formats
+        const jobId = typeof response === "string" ? response : response?.job_id;
+        if (!jobId || typeof jobId !== "string") {
+            throw new exceptions_1.RoeAPIException(`Invalid job ID returned from API: ${JSON.stringify(response)}`);
+        }
+        if (!(0, fileDetection_1.isUuidString)(jobId)) {
+            throw new exceptions_1.RoeAPIException(`Invalid job ID format returned from API: ${jobId}`);
+        }
+        return new job_1.Job({ agentsApi: this, jobId, timeoutSeconds: params.timeoutSeconds });
+    }
+    async runVersionSync(agentId, versionId, inputs) {
+        validateUuid(agentId, "agentId");
+        validateUuid(versionId, "versionId");
+        return this.httpClient.postWithDynamicInputs(`/v1/agents/run/${agentId}/versions/${versionId}/`, inputs);
+    }
+    *iterChunks(items, size) {
+        for (let i = 0; i < items.length; i += size) {
+            yield items.slice(i, i + size);
+        }
+    }
+}
+exports.AgentsAPI = AgentsAPI;
+AgentsAPI.MAX_BATCH_SIZE = 1000;

package/dist/src/auth.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoeAuth = void 0;
+class RoeAuth {
+    constructor(config) {
+        this.config = config;
+    }
+    getHeaders() {
+        return {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "User-Agent": "roe-typescript/0.1.0",
+        };
+    }
+}
+exports.RoeAuth = RoeAuth;

package/dist/src/client.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoeClient = void 0;
+const agents_1 = require("./api/agents");
+const auth_1 = require("./auth");
+const config_1 = require("./config");
+const httpClient_1 = require("./utils/httpClient");
+class RoeClient {
+    constructor(input = {}) {
+        this.config = config_1.RoeConfig.fromEnv(input);
+        this.auth = new auth_1.RoeAuth(this.config);
+        this.httpClient = new httpClient_1.RoeHTTPClient(this.config, this.auth);
+        this._agents = new agents_1.AgentsAPI(this.config, this.httpClient);
+    }
+    get agents() {
+        return this._agents;
+    }
+    close() {
+        this.httpClient.close();
+    }
+}
+exports.RoeClient = RoeClient;

package/dist/src/config.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoeConfig = void 0;
+class RoeConfig {
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.organizationId = opts.organizationId;
+        this.baseUrl = opts.baseUrl;
+        this.timeoutMs = opts.timeoutMs;
+        this.maxRetries = opts.maxRetries;
+    }
+    static fromEnv(input = {}) {
+        const apiKey = input.apiKey ?? process.env.ROE_API_KEY;
+        const organizationId = input.organizationId ?? process.env.ROE_ORGANIZATION_ID;
+        const baseUrl = input.baseUrl ?? process.env.ROE_BASE_URL ?? "https://api.roe-ai.com";
+        // Parse ROE_TIMEOUT with NaN check to avoid poisoning timeoutMs
+        const timeoutSecondsEnvRaw = process.env.ROE_TIMEOUT ? Number(process.env.ROE_TIMEOUT) : undefined;
+        const timeoutSecondsEnv = timeoutSecondsEnvRaw !== undefined && !Number.isNaN(timeoutSecondsEnvRaw)
+            ? timeoutSecondsEnvRaw
+            : undefined;
+        const timeoutMs = input.timeoutMs ??
+            (input.timeoutSeconds !== undefined
+                ? input.timeoutSeconds * 1000
+                : timeoutSecondsEnv !== undefined
+                    ? timeoutSecondsEnv * 1000
+                    : 60000);
+        const envMaxRetries = process.env.ROE_MAX_RETRIES;
+        const parsedEnvMaxRetries = envMaxRetries !== undefined && !Number.isNaN(Number(envMaxRetries))
+            ? Number(envMaxRetries)
+            : undefined;
+        const maxRetries = input.maxRetries ?? parsedEnvMaxRetries ?? 3;
+        if (!apiKey) {
+            throw new Error("API key is required. Provide it in constructor or set ROE_API_KEY.");
+        }
+        if (!organizationId) {
+            throw new Error("Organization ID is required. Provide it in constructor or set ROE_ORGANIZATION_ID.");
+        }
+        return new RoeConfig({
+            apiKey,
+            organizationId,
+            baseUrl,
+            timeoutMs,
+            maxRetries,
+        });
+    }
+}
+exports.RoeConfig = RoeConfig;

package/dist/src/exceptions.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerError = exports.RateLimitError = exports.NotFoundError = exports.ForbiddenError = exports.InsufficientCreditsError = exports.AuthenticationError = exports.BadRequestError = exports.RoeAPIException = void 0;
+exports.getExceptionForStatusCode = getExceptionForStatusCode;
+exports.extractErrorMessage = extractErrorMessage;
+class RoeAPIException extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.name = this.constructor.name;
+        this.statusCode = statusCode;
+        this.response = response;
+    }
+}
+exports.RoeAPIException = RoeAPIException;
+class BadRequestError extends RoeAPIException {
+}
+exports.BadRequestError = BadRequestError;
+class AuthenticationError extends RoeAPIException {
+}
+exports.AuthenticationError = AuthenticationError;
+class InsufficientCreditsError extends RoeAPIException {
+}
+exports.InsufficientCreditsError = InsufficientCreditsError;
+class ForbiddenError extends RoeAPIException {
+}
+exports.ForbiddenError = ForbiddenError;
+class NotFoundError extends RoeAPIException {
+}
+exports.NotFoundError = NotFoundError;
+class RateLimitError extends RoeAPIException {
+}
+exports.RateLimitError = RateLimitError;
+class ServerError extends RoeAPIException {
+}
+exports.ServerError = ServerError;
+function getExceptionForStatusCode(status) {
+    const map = {
+        400: BadRequestError,
+        401: AuthenticationError,
+        402: InsufficientCreditsError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        429: RateLimitError,
+    };
+    if (map[status])
+        return map[status];
+    if (status >= 500)
+        return ServerError;
+    return RoeAPIException;
+}
+/**
+ * Extracts error message from various API response formats.
+ * Handles: { detail: string }, { error: string }, { message: string }, or raw string.
+ */
+function extractErrorMessage(data, statusCode) {
+    if (typeof data === "string") {
+        return data;
+    }
+    if (typeof data === "object" && data !== null) {
+        // Try common error message field names
+        const obj = data;
+        if (typeof obj.detail === "string")
+            return obj.detail;
+        if (typeof obj.error === "string")
+            return obj.error;
+        if (typeof obj.message === "string")
+            return obj.message;
+        // Handle nested error object
+        if (typeof obj.error === "object" && obj.error !== null) {
+            const errObj = obj.error;
+            if (typeof errObj.message === "string")
+                return errObj.message;
+        }
+        // Handle array of errors
+        if (Array.isArray(obj.errors) && obj.errors.length > 0) {
+            const firstError = obj.errors[0];
+            if (typeof firstError === "string")
+                return firstError;
+            if (typeof firstError === "object" && firstError !== null && typeof firstError.message === "string") {
+                return firstError.message;
+            }
+        }
+    }
+    // Fallback to generic message
+    return `HTTP ${statusCode} error`;
+}

package/dist/src/models/agent.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentVersionWithApi = exports.BaseAgentWithApi = void 0;
+class BaseAgentWithApi {
+    constructor(data) {
+        Object.assign(this, data);
+    }
+    setAgentsApi(api) {
+        this._agentsApi = api;
+    }
+    run(inputs) {
+        if (!this._agentsApi)
+            throw new Error("Agents API not set");
+        return this._agentsApi.run({ agentId: this.id, inputs });
+    }
+    listVersions() {
+        if (!this._agentsApi)
+            throw new Error("Agents API not set");
+        return this._agentsApi.versions.list(this.id);
+    }
+    getCurrentVersion() {
+        if (!this._agentsApi)
+            throw new Error("Agents API not set");
+        if (!this.current_version_id)
+            return null;
+        return this._agentsApi.versions.retrieve(this.id, this.current_version_id);
+    }
+}
+exports.BaseAgentWithApi = BaseAgentWithApi;
+class AgentVersionWithApi {
+    constructor(data) {
+        Object.assign(this, data);
+    }
+    setAgentsApi(api) {
+        this._agentsApi = api;
+    }
+    run(inputs) {
+        if (!this._agentsApi)
+            throw new Error("Agents API not set");
+        if (!this.base_agent?.id)
+            throw new Error("AgentVersion missing base_agent id");
+        return this._agentsApi.runVersion({ agentId: this.base_agent.id, versionId: this.id, inputs });
+    }
+}
+exports.AgentVersionWithApi = AgentVersionWithApi;

package/dist/src/models/file.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileUpload = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const mime_types_1 = __importDefault(require("mime-types"));
+const exceptions_1 = require("../exceptions");
+/** Maximum file size: 2GB (aligned with main-roe backend) */
+const MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024;
+class FileUpload {
+    constructor(init) {
+        this._openedStream = null;
+        this.path = init.path;
+        this.file = init.file;
+        this.filename = init.filename;
+        this.mimeType = init.mimeType;
+        if (!this.path && !this.file) {
+            throw new Error("Either path or file must be provided");
+        }
+        if (this.path && this.file) {
+            throw new Error("Only one of path or file should be provided");
+        }
+        // Validate file size if path is provided
+        if (this.path) {
+            try {
+                const stat = fs_1.default.statSync(this.path);
+                if (stat.size > MAX_FILE_SIZE) {
+                    throw new exceptions_1.BadRequestError(`File exceeds maximum size of 2GB: ${this.path} (${(stat.size / (1024 * 1024 * 1024)).toFixed(2)}GB)`, 400);
+                }
+            }
+            catch (err) {
+                if (err instanceof exceptions_1.BadRequestError)
+                    throw err;
+                throw new Error(`Cannot access file: ${this.path}`);
+            }
+        }
+    }
+    get effectiveFilename() {
+        if (this.filename)
+            return this.filename;
+        if (this.path)
+            return path_1.default.basename(this.path);
+        return "upload";
+    }
+    get effectiveMimeType() {
+        if (this.mimeType)
+            return this.mimeType;
+        const guess = mime_types_1.default.lookup(this.effectiveFilename);
+        return (guess || "application/octet-stream");
+    }
+    /**
+     * Opens the file for reading. If a path was provided, creates a new ReadStream.
+     * Track opened streams so they can be closed later.
+     */
+    open() {
+        if (this.file)
+            return this.file;
+        if (this.path) {
+            this._openedStream = fs_1.default.createReadStream(this.path);
+            return this._openedStream;
+        }
+        throw new Error("No file source available");
+    }
+    /**
+     * Closes any opened file stream to prevent resource leaks.
+     * Should be called after the file upload is complete.
+     */
+    close() {
+        if (this._openedStream) {
+            this._openedStream.destroy();
+            this._openedStream = null;
+        }
+    }
+    /**
+     * Returns the file size in bytes, if available.
+     */
+    getSize() {
+        if (this.path) {
+            try {
+                return fs_1.default.statSync(this.path).size;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+}
+exports.FileUpload = FileUpload;