roe-typescript 0.1.0

package/dist/utils/httpClient.js

@@ -0,0 +1,229 @@
+import axios from "axios";
+import FormData from "form-data";
+import fs from "fs";
+import http from "http";
+import https from "https";
+import { FileUpload } from "../models/file";
+import { getExceptionForStatusCode, extractErrorMessage } from "../exceptions";
+import { isFilePath, isUuidString } from "./fileDetection";
+// Keep-alive agents for connection reuse (improves performance under load)
+const httpAgent = new http.Agent({ keepAlive: true });
+const httpsAgent = new https.Agent({ keepAlive: true });
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class RoeHTTPClient {
+    constructor(config, auth) {
+        this.config = config;
+        this.auth = auth;
+        this.maxRetries = config.maxRetries;
+        this.client = axios.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.isAxiosError(err) ? err.response?.status : undefined;
+                const isNetworkError = axios.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.isAxiosError(err) && err.response) {
+                        const ExceptionClass = getExceptionForStatusCode(err.response.status);
+                        const data = err.response.data;
+                        // Use improved error message extraction that handles multiple formats
+                        const message = 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 = getExceptionForStatusCode(response.status);
+        const data = response.data;
+        // Use improved error message extraction that handles multiple formats
+        const message = 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 FormData();
+            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 FileUpload) {
+                resolvedFiles.push({ key: k, type: "fileUpload", value: v });
+            }
+            else if (typeof v === "string" && await 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 FormData();
+                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.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.isAxiosError(err) ? err.response?.status : undefined;
+                const isNetworkError = axios.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.isAxiosError(err) && err.response) {
+                        const ExceptionClass = getExceptionForStatusCode(err.response.status);
+                        const data = err.response.data;
+                        const message = 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 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 (isUuidString(value)) {
+                    formData[key] = value;
+                }
+                else if (await 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 });
+    }
+}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,3 @@
+export declare class PaginationHelper {
+    static buildQueryParams(organizationId: string, page?: number, pageSize?: number, extra?: Record<string, unknown>): Record<string, string>;
+}

package/dist/utils/pagination.js

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "roe-typescript",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Roe AI API (feature parity with roe-python).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc --noEmit",
+    "test": "vitest run tests/unit --passWithNoTests",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "form-data": "^4.0.0",
+    "mime-types": "^2.1.35",
+    "uuid": "^11.0.3"
+  },
+  "devDependencies": {
+    "@types/form-data": "^2.5.0",
+    "@types/mime-types": "^2.1.4",
+    "@types/uuid": "^10.0.0",
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3",
+    "vitest": "^1.6.0"
+  }
+}
+