roe-typescript 0.1.0

package/dist/api/agents.js

@@ -0,0 +1,263 @@
+import { PaginationHelper } from "../utils/pagination";
+import { isUuidString } from "../utils/fileDetection";
+import { BadRequestError, RoeAPIException } from "../exceptions";
+import { AgentVersionWithApi, BaseAgentWithApi, } from "../models/agent";
+import { Job, JobBatch } from "../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 (!isUuidString(value)) {
+        throw new BadRequestError(`Invalid ${fieldName}: "${value}" is not a valid UUID`, 400);
+    }
+}
+export 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 AgentVersionWithApi(data);
+        obj.setAgentsApi(this.agentsApi);
+        return obj;
+    }
+}
+export 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);
+        }
+    }
+}
+AgentJobsAPI.MAX_BATCH_SIZE = 1000;
+export 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 BaseAgentWithApi(data);
+        obj.setAgentsApi(this);
+        return obj;
+    }
+    async list(params) {
+        const query = 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 RoeAPIException(`Invalid job ID returned from API: ${JSON.stringify(response)}`);
+        }
+        if (!isUuidString(jobId)) {
+            throw new RoeAPIException(`Invalid job ID format returned from API: ${jobId}`);
+        }
+        return new 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 RoeAPIException(`Invalid job ID returned from batch API: ${JSON.stringify(jobId)}`);
+                }
+                if (!isUuidString(jobId)) {
+                    throw new RoeAPIException(`Invalid job ID format returned from batch API: ${jobId}`);
+                }
+                allJobIds.push(jobId);
+            }
+        }
+        return new 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 RoeAPIException(`Invalid job ID returned from API: ${JSON.stringify(response)}`);
+        }
+        if (!isUuidString(jobId)) {
+            throw new RoeAPIException(`Invalid job ID format returned from API: ${jobId}`);
+        }
+        return new 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);
+        }
+    }
+}
+AgentsAPI.MAX_BATCH_SIZE = 1000;

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import { RoeConfig } from "./config";
+export declare class RoeAuth {
+    private readonly config;
+    constructor(config: RoeConfig);
+    getHeaders(): Record<string, string>;
+}

package/dist/auth.js

@@ -0,0 +1,11 @@
+export class RoeAuth {
+    constructor(config) {
+        this.config = config;
+    }
+    getHeaders() {
+        return {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "User-Agent": "roe-typescript/0.1.0",
+        };
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+import { AgentsAPI } from "./api/agents";
+import { RoeAuth } from "./auth";
+import { RoeConfig, RoeConfigInput } from "./config";
+import { RoeHTTPClient } from "./utils/httpClient";
+export declare class RoeClient {
+    readonly config: RoeConfig;
+    readonly auth: RoeAuth;
+    readonly httpClient: RoeHTTPClient;
+    private readonly _agents;
+    constructor(input?: RoeConfigInput);
+    get agents(): AgentsAPI;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,18 @@
+import { AgentsAPI } from "./api/agents";
+import { RoeAuth } from "./auth";
+import { RoeConfig } from "./config";
+import { RoeHTTPClient } from "./utils/httpClient";
+export class RoeClient {
+    constructor(input = {}) {
+        this.config = RoeConfig.fromEnv(input);
+        this.auth = new RoeAuth(this.config);
+        this.httpClient = new RoeHTTPClient(this.config, this.auth);
+        this._agents = new AgentsAPI(this.config, this.httpClient);
+    }
+    get agents() {
+        return this._agents;
+    }
+    close() {
+        this.httpClient.close();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export type RoeConfigInput = {
+    apiKey?: string;
+    organizationId?: string;
+    baseUrl?: string;
+    timeoutSeconds?: number;
+    timeoutMs?: number;
+    maxRetries?: number;
+};
+export declare class RoeConfig {
+    readonly apiKey: string;
+    readonly organizationId: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    private constructor();
+    static fromEnv(input?: RoeConfigInput): RoeConfig;
+}

package/dist/config.js

@@ -0,0 +1,43 @@
+export 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,
+        });
+    }
+}

package/dist/exceptions.d.ts

@@ -0,0 +1,25 @@
+export declare class RoeAPIException extends Error {
+    readonly statusCode?: number;
+    readonly response?: Record<string, unknown> | null;
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown> | null);
+}
+export declare class BadRequestError extends RoeAPIException {
+}
+export declare class AuthenticationError extends RoeAPIException {
+}
+export declare class InsufficientCreditsError extends RoeAPIException {
+}
+export declare class ForbiddenError extends RoeAPIException {
+}
+export declare class NotFoundError extends RoeAPIException {
+}
+export declare class RateLimitError extends RoeAPIException {
+}
+export declare class ServerError extends RoeAPIException {
+}
+export declare function getExceptionForStatusCode(status: number): typeof RoeAPIException;
+/**
+ * Extracts error message from various API response formats.
+ * Handles: { detail: string }, { error: string }, { message: string }, or raw string.
+ */
+export declare function extractErrorMessage(data: unknown, statusCode: number): string;

package/dist/exceptions.js

@@ -0,0 +1,73 @@
+export class RoeAPIException extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.name = this.constructor.name;
+        this.statusCode = statusCode;
+        this.response = response;
+    }
+}
+export class BadRequestError extends RoeAPIException {
+}
+export class AuthenticationError extends RoeAPIException {
+}
+export class InsufficientCreditsError extends RoeAPIException {
+}
+export class ForbiddenError extends RoeAPIException {
+}
+export class NotFoundError extends RoeAPIException {
+}
+export class RateLimitError extends RoeAPIException {
+}
+export class ServerError extends RoeAPIException {
+}
+export 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.
+ */
+export 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/index.d.ts

@@ -0,0 +1,10 @@
+export { RoeClient } from "./client";
+export { RoeConfig } from "./config";
+export type { RoeConfigInput } from "./config";
+export { RoeAuth } from "./auth";
+export * from "./exceptions";
+export * from "./api/agents";
+export * from "./models/agent";
+export * from "./models/job";
+export * from "./models/responses";
+export * from "./models/file";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { RoeClient } from "./client";
+export { RoeConfig } from "./config";
+export { RoeAuth } from "./auth";
+export * from "./exceptions";
+export * from "./api/agents";
+export * from "./models/agent";
+export * from "./models/job";
+export * from "./models/responses";
+export * from "./models/file";