roe-typescript 0.1.0

package/dist/src/models/job.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobBatch = exports.Job = void 0;
+const responses_1 = require("./responses");
+class Job {
+    constructor(opts) {
+        this.agentsApi = opts.agentsApi;
+        this.jobId = opts.jobId;
+        this.timeoutSeconds = opts.timeoutSeconds ?? 7200;
+        if (this.timeoutSeconds <= 0) {
+            throw new Error(`timeoutSeconds must be positive, got ${this.timeoutSeconds}`);
+        }
+    }
+    get id() {
+        return this.jobId;
+    }
+    async wait(params) {
+        const intervalSeconds = params?.intervalSeconds ?? 5;
+        const timeoutSeconds = params?.timeoutSeconds ?? this.timeoutSeconds;
+        if (timeoutSeconds <= 0)
+            throw new Error(`timeoutSeconds must be positive, got ${timeoutSeconds}`);
+        const start = Date.now();
+        while (true) {
+            const status = await this.retrieveStatus();
+            const code = status.status;
+            if (code === responses_1.JobStatus.SUCCESS || code === responses_1.JobStatus.CACHED) {
+                return this.retrieveResult();
+            }
+            if (code === responses_1.JobStatus.FAILURE || code === responses_1.JobStatus.CANCELLED) {
+                throw new Error(`Job ${this.jobId} failed with status ${code}${status.error_message ? `: ${status.error_message}` : ""}`);
+            }
+            if (Date.now() - start > timeoutSeconds * 1000) {
+                throw new Error(`Job ${this.jobId} did not complete within ${timeoutSeconds} seconds`);
+            }
+            await new Promise((r) => setTimeout(r, intervalSeconds * 1000));
+        }
+    }
+    retrieveStatus() {
+        return this.agentsApi.jobs.retrieveStatus(this.jobId);
+    }
+    retrieveResult() {
+        return this.agentsApi.jobs.retrieveResult(this.jobId);
+    }
+}
+exports.Job = Job;
+class JobBatch {
+    constructor(opts) {
+        this.completed = {};
+        this.statusCache = {};
+        this.agentsApi = opts.agentsApi;
+        this.jobIds = opts.jobIds;
+        this.timeoutSeconds = opts.timeoutSeconds ?? 7200;
+        if (this.timeoutSeconds <= 0) {
+            throw new Error(`timeoutSeconds must be positive, got ${this.timeoutSeconds}`);
+        }
+    }
+    get jobs() {
+        return this.jobIds.map((id) => new Job({ agentsApi: this.agentsApi, jobId: id, timeoutSeconds: this.timeoutSeconds }));
+    }
+    async wait(params) {
+        const intervalSeconds = params?.intervalSeconds ?? 5;
+        const timeoutSeconds = params?.timeoutSeconds ?? this.timeoutSeconds;
+        if (timeoutSeconds <= 0)
+            throw new Error(`timeoutSeconds must be positive, got ${timeoutSeconds}`);
+        const start = Date.now();
+        while (Object.keys(this.completed).length < this.jobIds.length) {
+            const pending = this.jobIds.filter((id) => !this.completed[id]);
+            if (!pending.length)
+                break;
+            const statusBatch = await this.agentsApi.jobs.retrieveStatusMany(pending);
+            const failures = statusBatch.filter((s) => s.status === responses_1.JobStatus.FAILURE || s.status === responses_1.JobStatus.CANCELLED);
+            if (failures.length) {
+                const detail = failures.map((f) => `${f.id}:${f.status ?? "unknown"}`).join(', ');
+                throw new Error(`Jobs failed or cancelled: ${detail}`);
+            }
+            const completedIds = [];
+            for (const status of statusBatch) {
+                const code = status.status;
+                if (code === responses_1.JobStatus.SUCCESS || code === responses_1.JobStatus.CACHED) {
+                    completedIds.push(status.id);
+                }
+                if (code !== undefined && code !== null) {
+                    this.statusCache[status.id] = code;
+                }
+            }
+            if (completedIds.length) {
+                const resultBatch = await this.agentsApi.jobs.retrieveResultMany(completedIds);
+                for (const res of resultBatch) {
+                    if (!res.agent_id || !res.agent_version_id) {
+                        const id = res.id ?? 'unknown';
+                        throw new Error(`Job ${id} missing agent identifiers`);
+                    }
+                    // Use corrected_outputs as fallback if result is null/undefined
+                    const outputs = res.result ?? res.corrected_outputs;
+                    if (outputs == null) {
+                        // Both result and corrected_outputs are null - this may indicate an error or incomplete job
+                        throw new Error(`Job ${res.id} returned null or undefined result`);
+                    }
+                    if (!Array.isArray(outputs)) {
+                        // Result exists but is not an array - unexpected format
+                        throw new Error(`Job ${res.id} returned unexpected result format: ${typeof outputs}`);
+                    }
+                    this.completed[res.id] = {
+                        agent_id: res.agent_id,
+                        agent_version_id: res.agent_version_id,
+                        inputs: res.inputs ?? [],
+                        input_tokens: res.input_tokens,
+                        output_tokens: res.output_tokens,
+                        outputs,
+                    };
+                }
+            }
+            if (Object.keys(this.completed).length < this.jobIds.length) {
+                if (Date.now() - start > timeoutSeconds * 1000) {
+                    const remaining = this.jobIds.filter((id) => !this.completed[id]);
+                    throw new Error(`Jobs ${remaining.join(", ")} did not complete within ${timeoutSeconds} seconds`);
+                }
+                await new Promise((r) => setTimeout(r, intervalSeconds * 1000));
+            }
+        }
+        return this.jobIds.map((id) => this.completed[id]);
+    }
+    async retrieveStatus() {
+        const statusMap = { ...this.statusCache };
+        const toQuery = this.jobIds.filter((id) => statusMap[id] === undefined);
+        if (toQuery.length) {
+            const statuses = await this.agentsApi.jobs.retrieveStatusMany(toQuery);
+            for (const s of statuses) {
+                if (s.status !== undefined && s.status !== null) {
+                    statusMap[s.id] = s.status;
+                    this.statusCache[s.id] = s.status;
+                }
+            }
+        }
+        return statusMap;
+    }
+}
+exports.JobBatch = JobBatch;

package/dist/src/models/responses.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobStatus = void 0;
+exports.referenceFromUrl = referenceFromUrl;
+exports.extractReferencesFromOutputs = extractReferencesFromOutputs;
+exports.getJobReferences = getJobReferences;
+const uuid_1 = require("uuid");
+var JobStatus;
+(function (JobStatus) {
+    JobStatus[JobStatus["PENDING"] = 0] = "PENDING";
+    JobStatus[JobStatus["STARTED"] = 1] = "STARTED";
+    JobStatus[JobStatus["RETRY"] = 2] = "RETRY";
+    JobStatus[JobStatus["SUCCESS"] = 3] = "SUCCESS";
+    JobStatus[JobStatus["FAILURE"] = 4] = "FAILURE";
+    JobStatus[JobStatus["CANCELLED"] = 5] = "CANCELLED";
+    JobStatus[JobStatus["CACHED"] = 6] = "CACHED";
+})(JobStatus || (exports.JobStatus = JobStatus = {}));
+function referenceFromUrl(url) {
+    const resource_id = url.split("/references/").at(-1)?.replace(/\/+$/, "") ?? (0, uuid_1.v4)();
+    return { url, resource_id };
+}
+function extractReferencesFromOutputs(outputs) {
+    const references = [];
+    for (const output of outputs) {
+        try {
+            const parsed = JSON.parse(output.value);
+            const refs = Array.isArray(parsed?.references) ? parsed.references : [];
+            for (const ref of refs) {
+                if (typeof ref === "string" && ref.includes("/references/")) {
+                    references.push(referenceFromUrl(ref));
+                }
+            }
+        }
+        catch {
+            // ignore unparsable outputs
+        }
+    }
+    return references;
+}
+function getJobReferences(result) {
+    return extractReferencesFromOutputs(result.outputs ?? []);
+}

package/dist/src/models/user.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/utils/fileDetection.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUuidString = isUuidString;
+exports.isFilePath = isFilePath;
+exports.isFilePathSync = isFilePathSync;
+const fs_1 = __importDefault(require("fs"));
+const uuidRegex = /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i;
+function isUuidString(value) {
+    return typeof value === "string" && uuidRegex.test(value);
+}
+/**
+ * Asynchronously checks if a value is a valid file path.
+ * Uses async fs operations to avoid blocking the event loop.
+ */
+async function isFilePath(value) {
+    if (typeof value !== "string")
+        return false;
+    if (isUuidString(value))
+        return false;
+    try {
+        const stat = await fs_1.default.promises.stat(value);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Synchronous version of isFilePath for backward compatibility.
+ * @deprecated Use isFilePath (async) instead to avoid blocking the event loop.
+ */
+function isFilePathSync(value) {
+    if (typeof value !== "string")
+        return false;
+    if (isUuidString(value))
+        return false;
+    try {
+        return fs_1.default.existsSync(value) && fs_1.default.statSync(value).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/utils/httpClient.js

@@ -0,0 +1,236 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoeHTTPClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const form_data_1 = __importDefault(require("form-data"));
+const fs_1 = __importDefault(require("fs"));
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const file_1 = require("../models/file");
+const exceptions_1 = require("../exceptions");
+const fileDetection_1 = require("./fileDetection");
+// Keep-alive agents for connection reuse (improves performance under load)
+const httpAgent = new http_1.default.Agent({ keepAlive: true });
+const httpsAgent = new https_1.default.Agent({ keepAlive: true });
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class RoeHTTPClient {
+    constructor(config, auth) {
+        this.config = config;
+        this.auth = auth;
+        this.maxRetries = config.maxRetries;
+        this.client = axios_1.default.create({
+            baseURL: config.baseUrl,
+            timeout: config.timeoutMs,
+            headers: auth.getHeaders(),
+            httpAgent,
+            httpsAgent,
+        });
+    }
+    close() {
+        // no-op; included for parity
+    }
+    async execute(fn) {
+        let attempt = 0;
+        let lastError;
+        while (attempt <= this.maxRetries) {
+            try {
+                const res = await fn();
+                return this.handleResponse(res);
+            }
+            catch (err) {
+                lastError = err;
+                const status = axios_1.default.isAxiosError(err) ? err.response?.status : undefined;
+                const isNetworkError = axios_1.default.isAxiosError(err) && !err.response;
+                const retriableStatus = status !== undefined &&
+                    (status >= 500 || status === 429 || status === 408);
+                const shouldRetry = (isNetworkError || retriableStatus) && attempt < this.maxRetries;
+                if (!shouldRetry) {
+                    if (axios_1.default.isAxiosError(err) && err.response) {
+                        const ExceptionClass = (0, exceptions_1.getExceptionForStatusCode)(err.response.status);
+                        const data = err.response.data;
+                        // Use improved error message extraction that handles multiple formats
+                        const message = (0, exceptions_1.extractErrorMessage)(data, err.response.status);
+                        throw new ExceptionClass(message, err.response.status, data ?? null);
+                    }
+                    throw err;
+                }
+                const backoffMs = Math.min(1000 * 2 ** attempt, 10000);
+                await sleep(backoffMs);
+            }
+            attempt += 1;
+        }
+        if (lastError)
+            throw lastError;
+        throw new Error("Request failed");
+    }
+    handleResponse(response) {
+        if (response.status >= 200 && response.status < 300) {
+            return response.data;
+        }
+        const ExceptionClass = (0, exceptions_1.getExceptionForStatusCode)(response.status);
+        const data = response.data;
+        // Use improved error message extraction that handles multiple formats
+        const message = (0, exceptions_1.extractErrorMessage)(data, response.status);
+        throw new ExceptionClass(message, response.status, data ?? null);
+    }
+    get(url, params) {
+        return this.execute(() => this.client.get(url, { params }));
+    }
+    async getBytes(url, params) {
+        const data = await this.execute(() => this.client.get(url, { params, responseType: "arraybuffer" }));
+        // Normalize ArrayBuffer/Buffer to Buffer (axios returns ArrayBuffer in browsers)
+        return Buffer.isBuffer(data) ? data : Buffer.from(data);
+    }
+    async post(options) {
+        const { url, json, formData, files, params } = options;
+        const config = { params };
+        if (json !== undefined) {
+            return this.execute(() => this.client.post(url, json, config));
+        }
+        // Check if we have files that need retry-safe handling
+        const hasFiles = files && Object.keys(files).length > 0;
+        if (!hasFiles) {
+            // No files - build FormData once (safe for retries)
+            const fd = new form_data_1.default();
+            if (formData) {
+                for (const [k, v] of Object.entries(formData)) {
+                    if (v === undefined || v === null)
+                        continue;
+                    fd.append(k, String(v));
+                }
+            }
+            config.headers = { ...(config.headers || {}), ...fd.getHeaders() };
+            return this.execute(() => this.client.post(url, fd, config));
+        }
+        // With files - need to rebuild FormData on each retry attempt
+        // because file streams can only be read once
+        return this.executeWithFormData(url, formData ?? {}, files, config);
+    }
+    /**
+     * Execute a POST request with FormData that contains files.
+     * Rebuilds FormData on each retry attempt to handle stream consumption.
+     */
+    async executeWithFormData(url, formData, files, config) {
+        // Pre-resolve file paths to avoid async in retry loop
+        const resolvedFiles = [];
+        for (const [k, v] of Object.entries(files)) {
+            if (v instanceof file_1.FileUpload) {
+                resolvedFiles.push({ key: k, type: "fileUpload", value: v });
+            }
+            else if (typeof v === "string" && await (0, fileDetection_1.isFilePath)(v)) {
+                resolvedFiles.push({ key: k, type: "path", value: v });
+            }
+            else if (typeof v === "string") {
+                resolvedFiles.push({ key: k, type: "string", value: v });
+            }
+            else {
+                // Raw streams cannot be safely retried - warn but allow first attempt
+                resolvedFiles.push({ key: k, type: "stream", value: v });
+            }
+        }
+        let attempt = 0;
+        let lastError;
+        while (attempt <= this.maxRetries) {
+            try {
+                // Build fresh FormData for each attempt
+                const fd = new form_data_1.default();
+                for (const [k, v] of Object.entries(formData)) {
+                    if (v === undefined || v === null)
+                        continue;
+                    fd.append(k, String(v));
+                }
+                for (const file of resolvedFiles) {
+                    if (file.type === "fileUpload") {
+                        const fu = file.value;
+                        fd.append(file.key, fu.open(), {
+                            filename: fu.effectiveFilename,
+                            contentType: fu.effectiveMimeType,
+                        });
+                    }
+                    else if (file.type === "path") {
+                        fd.append(file.key, fs_1.default.createReadStream(file.value));
+                    }
+                    else if (file.type === "string") {
+                        fd.append(file.key, file.value);
+                    }
+                    else {
+                        // Stream - can only be used on first attempt
+                        if (attempt > 0) {
+                            throw new Error(`Cannot retry request with consumed stream for field "${file.key}". ` +
+                                `Use FileUpload or file path instead for retry-safe uploads.`);
+                        }
+                        fd.append(file.key, file.value);
+                    }
+                }
+                const reqConfig = { ...config, headers: { ...(config.headers || {}), ...fd.getHeaders() } };
+                const res = await this.client.post(url, fd, reqConfig);
+                return this.handleResponse(res);
+            }
+            catch (err) {
+                lastError = err;
+                const status = axios_1.default.isAxiosError(err) ? err.response?.status : undefined;
+                const isNetworkError = axios_1.default.isAxiosError(err) && !err.response;
+                const retriableStatus = status !== undefined &&
+                    (status >= 500 || status === 429 || status === 408);
+                const shouldRetry = (isNetworkError || retriableStatus) && attempt < this.maxRetries;
+                if (!shouldRetry) {
+                    if (axios_1.default.isAxiosError(err) && err.response) {
+                        const ExceptionClass = (0, exceptions_1.getExceptionForStatusCode)(err.response.status);
+                        const data = err.response.data;
+                        const message = (0, exceptions_1.extractErrorMessage)(data, err.response.status);
+                        throw new ExceptionClass(message, err.response.status, data ?? null);
+                    }
+                    throw err;
+                }
+                const backoffMs = Math.min(1000 * 2 ** attempt, 10000);
+                await sleep(backoffMs);
+            }
+            attempt += 1;
+        }
+        if (lastError)
+            throw lastError;
+        throw new Error("Request failed");
+    }
+    put(url, json, params) {
+        return this.execute(() => this.client.put(url, json ?? {}, { params }));
+    }
+    delete(url, params) {
+        return this.execute(() => this.client.delete(url, { params }));
+    }
+    async postWithDynamicInputs(url, inputs, params) {
+        const formData = {};
+        const files = {};
+        // Process inputs and detect file paths asynchronously
+        for (const [key, value] of Object.entries(inputs)) {
+            if (value instanceof file_1.FileUpload) {
+                files[key] = value;
+            }
+            else if (value && typeof value === "object" && typeof value.pipe === "function") {
+                // More robust stream detection: check if it's an object with a pipe function
+                files[key] = value;
+            }
+            else if (typeof value === "string") {
+                if ((0, fileDetection_1.isUuidString)(value)) {
+                    formData[key] = value;
+                }
+                else if (await (0, fileDetection_1.isFilePath)(value)) {
+                    // Use async file detection to avoid blocking the event loop
+                    files[key] = value;
+                }
+                else {
+                    formData[key] = value;
+                }
+            }
+            else if (value !== undefined && value !== null) {
+                formData[key] = value;
+            }
+        }
+        return this.post({ url, formData, files, params });
+    }
+}
+exports.RoeHTTPClient = RoeHTTPClient;

package/dist/src/utils/pagination.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationHelper = void 0;
+class PaginationHelper {
+    static buildQueryParams(organizationId, page, pageSize, extra = {}) {
+        const params = { organization_id: organizationId };
+        if (page !== undefined)
+            params.page = String(page);
+        if (pageSize !== undefined)
+            params.page_size = String(pageSize);
+        for (const [k, v] of Object.entries(extra)) {
+            if (v !== undefined && v !== null)
+                params[k] = String(v);
+        }
+        return params;
+    }
+}
+exports.PaginationHelper = PaginationHelper;

package/dist/utils/fileDetection.d.ts

@@ -0,0 +1,11 @@
+export declare function isUuidString(value: unknown): value is string;
+/**
+ * Asynchronously checks if a value is a valid file path.
+ * Uses async fs operations to avoid blocking the event loop.
+ */
+export declare function isFilePath(value: unknown): Promise<boolean>;
+/**
+ * Synchronous version of isFilePath for backward compatibility.
+ * @deprecated Use isFilePath (async) instead to avoid blocking the event loop.
+ */
+export declare function isFilePathSync(value: unknown): value is string;

package/dist/utils/fileDetection.js

@@ -0,0 +1,38 @@
+import fs from "fs";
+const uuidRegex = /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i;
+export function isUuidString(value) {
+    return typeof value === "string" && uuidRegex.test(value);
+}
+/**
+ * Asynchronously checks if a value is a valid file path.
+ * Uses async fs operations to avoid blocking the event loop.
+ */
+export async function isFilePath(value) {
+    if (typeof value !== "string")
+        return false;
+    if (isUuidString(value))
+        return false;
+    try {
+        const stat = await fs.promises.stat(value);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Synchronous version of isFilePath for backward compatibility.
+ * @deprecated Use isFilePath (async) instead to avoid blocking the event loop.
+ */
+export function isFilePathSync(value) {
+    if (typeof value !== "string")
+        return false;
+    if (isUuidString(value))
+        return false;
+    try {
+        return fs.existsSync(value) && fs.statSync(value).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/httpClient.d.ts

@@ -0,0 +1,30 @@
+import { FileUpload } from "../models/file";
+import { RoeAuth } from "../auth";
+import { RoeConfig } from "../config";
+export declare class RoeHTTPClient {
+    private readonly config;
+    private readonly auth;
+    private readonly client;
+    private readonly maxRetries;
+    constructor(config: RoeConfig, auth: RoeAuth);
+    close(): void;
+    private execute;
+    private handleResponse;
+    get<T>(url: string, params?: Record<string, unknown>): Promise<T>;
+    getBytes(url: string, params?: Record<string, unknown>): Promise<Buffer>;
+    post<T>(options: {
+        url: string;
+        json?: Record<string, unknown> | unknown[];
+        formData?: Record<string, unknown>;
+        files?: Record<string, FileUpload | NodeJS.ReadableStream | string>;
+        params?: Record<string, unknown>;
+    }): Promise<T>;
+    /**
+     * Execute a POST request with FormData that contains files.
+     * Rebuilds FormData on each retry attempt to handle stream consumption.
+     */
+    private executeWithFormData;
+    put<T>(url: string, json?: Record<string, unknown>, params?: Record<string, unknown>): Promise<T>;
+    delete(url: string, params?: Record<string, unknown>): Promise<void>;
+    postWithDynamicInputs<T>(url: string, inputs: Record<string, unknown>, params?: Record<string, unknown>): Promise<T>;
+}