roe-typescript 0.1.3 → 1.0.0

package/dist/utils/dynamicInputs.d.ts

@@ -0,0 +1,30 @@
+import type { RoeRawClient } from "../generated/client.js";
+import { FileUpload } from "../models/file.js";
+export type ClassifiedInputs = {
+    formData: Record<string, string>;
+    files: Record<string, FileUpload>;
+};
+/**
+ * Splits a free-form `inputs` dict into form fields + file uploads, mirroring
+ * the detection rules from the legacy `RoeHTTPClient.postWithDynamicInputs`:
+ *
+ *   - `FileUpload` instance -> file part
+ *   - object with a `pipe` function (Node Readable) -> wrapped in FileUpload
+ *   - string that's a valid UUID -> form field (treated as a Roe file ref)
+ *   - string that resolves to a real file path -> opened as a FileUpload
+ *   - other strings / numbers / booleans -> form field (stringified)
+ */
+export declare function classifyInputs(inputs: Record<string, unknown>): Promise<ClassifiedInputs>;
+/**
+ * Posts a multipart body built from a free-form `inputs` dict (with optional
+ * sibling `metadata`) to a generated raw-client path. Bypasses openapi-fetch's
+ * default JSON serialization via the `bodySerializer` escape hatch and runs
+ * its own retry loop because Node `Readable` bodies cannot be re-read.
+ *
+ * The path / pathParams are intentionally typed loosely (`string` /
+ * `Record<string, string>`) — multipart agent-run endpoints have dynamic
+ * input keys that aren't statically modeled in the OpenAPI spec, so the
+ * generated typed-body variant is unusable here. Callers pass the path
+ * literal that matches `paths` in schema.d.ts.
+ */
+export declare function postDynamicInputs<T = unknown>(raw: RoeRawClient, path: string, pathParams: Record<string, string>, queryParams: Record<string, string | undefined>, inputs: Record<string, unknown>, metadata: Record<string, unknown> | undefined, maxRetries: number): Promise<T>;

package/dist/utils/dynamicInputs.js

@@ -0,0 +1,114 @@
+import { FileUpload } from "../models/file.js";
+import { isFilePath, isUuidString } from "./fileDetection.js";
+/**
+ * Sentinel header read by `retryMiddleware`. Multipart bodies aren't safely
+ * cloneable for retry by the middleware — the wrapper-side loop in
+ * `postDynamicInputs` rebuilds FormData per attempt instead.
+ */
+const RETRY_BYPASS_HEADER = "x-roe-retry-bypass";
+const isRetriable = (status) => status >= 500 || status === 429 || status === 408;
+/**
+ * Splits a free-form `inputs` dict into form fields + file uploads, mirroring
+ * the detection rules from the legacy `RoeHTTPClient.postWithDynamicInputs`:
+ *
+ *   - `FileUpload` instance -> file part
+ *   - object with a `pipe` function (Node Readable) -> wrapped in FileUpload
+ *   - string that's a valid UUID -> form field (treated as a Roe file ref)
+ *   - string that resolves to a real file path -> opened as a FileUpload
+ *   - other strings / numbers / booleans -> form field (stringified)
+ */
+export async function classifyInputs(inputs) {
+    const formData = {};
+    const files = {};
+    for (const [key, value] of Object.entries(inputs)) {
+        if (value === undefined || value === null)
+            continue;
+        if (value instanceof FileUpload) {
+            files[key] = value;
+            continue;
+        }
+        if (typeof value === "object" && typeof value.pipe === "function") {
+            files[key] = new FileUpload({ file: value });
+            continue;
+        }
+        if (typeof value === "string") {
+            if (isUuidString(value)) {
+                formData[key] = value;
+            }
+            else if (await isFilePath(value)) {
+                files[key] = new FileUpload({ path: value });
+            }
+            else {
+                formData[key] = value;
+            }
+            continue;
+        }
+        if (typeof value === "boolean" || typeof value === "number") {
+            formData[key] = String(value);
+            continue;
+        }
+        // Unknown shape — JSON-encode so e.g. nested objects survive the round-trip.
+        formData[key] = JSON.stringify(value);
+    }
+    return { formData, files };
+}
+async function buildFormData(formData, files, metadata) {
+    const fd = new FormData();
+    for (const [k, v] of Object.entries(formData))
+        fd.append(k, v);
+    if (metadata !== undefined)
+        fd.append("metadata", JSON.stringify(metadata));
+    for (const [k, fu] of Object.entries(files)) {
+        fd.append(k, await fu.toBlob(), fu.effectiveFilename);
+    }
+    return fd;
+}
+/**
+ * Posts a multipart body built from a free-form `inputs` dict (with optional
+ * sibling `metadata`) to a generated raw-client path. Bypasses openapi-fetch's
+ * default JSON serialization via the `bodySerializer` escape hatch and runs
+ * its own retry loop because Node `Readable` bodies cannot be re-read.
+ *
+ * The path / pathParams are intentionally typed loosely (`string` /
+ * `Record<string, string>`) — multipart agent-run endpoints have dynamic
+ * input keys that aren't statically modeled in the OpenAPI spec, so the
+ * generated typed-body variant is unusable here. Callers pass the path
+ * literal that matches `paths` in schema.d.ts.
+ */
+export async function postDynamicInputs(raw, path, pathParams, queryParams, inputs, metadata, maxRetries) {
+    const { formData, files } = await classifyInputs(inputs);
+    let attempt = 0;
+    let lastErr;
+    while (attempt <= maxRetries) {
+        const fd = await buildFormData(formData, files, metadata);
+        try {
+            // openapi-fetch's typed POST is keyed on `paths`; we deliberately escape
+            // the type system here for multipart agent-run endpoints.
+            // NOTE: openapi-fetch skips `bodySerializer` entirely when `body` is
+            // `undefined`, so we pass the FormData as the body itself and use
+            // bodySerializer as an identity to preserve the FormData type signal
+            // (openapi-fetch then refrains from forcing Content-Type: application/json).
+            const result = await raw.POST(path, {
+                params: { path: pathParams, query: queryParams },
+                body: fd,
+                bodySerializer: (b) => b,
+                headers: { [RETRY_BYPASS_HEADER]: "1" },
+            });
+            // errorMiddleware throws on non-2xx, so reaching here means success.
+            // `error` is therefore always undefined; surface `data` directly.
+            return result.data;
+        }
+        catch (err) {
+            lastErr = err;
+            const status = err?.statusCode;
+            if (status !== undefined && isRetriable(status) && attempt < maxRetries) {
+                const backoff = Math.min(1000 * 2 ** attempt, 10000);
+                await new Promise((r) => setTimeout(r, backoff));
+                attempt += 1;
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastErr ?? new Error("postDynamicInputs exhausted retries without producing an error");
+}

package/dist/utils/middleware.d.ts

@@ -0,0 +1,6 @@
+import type { Middleware } from "openapi-fetch";
+import { RoeAuth } from "../auth.js";
+export declare function shouldBypassRetry(request: Request): boolean;
+export declare function authMiddleware(auth: RoeAuth): Middleware;
+export declare function retryMiddleware(maxRetries: number): Middleware;
+export declare const errorMiddleware: Middleware;

package/dist/utils/middleware.js

@@ -0,0 +1,80 @@
+import { extractErrorMessage, getExceptionForStatusCode } from "../exceptions.js";
+const RETRY_BYPASS_HEADER = "x-roe-retry-bypass";
+export function shouldBypassRetry(request) {
+    if (request.headers.get(RETRY_BYPASS_HEADER))
+        return true;
+    const ct = request.headers.get("content-type");
+    return !!ct && ct.toLowerCase().startsWith("multipart/");
+}
+export function authMiddleware(auth) {
+    return {
+        onRequest({ request }) {
+            for (const [k, v] of Object.entries(auth.getHeaders())) {
+                request.headers.set(k, v);
+            }
+            return request;
+        },
+    };
+}
+// Per-request body cache populated in onRequest (where the body is still
+// fresh) and consumed in onResponse to rebuild Requests on retry. Cloning
+// the original request post-fetch fails in Node 18+ undici with
+// `TypeError: Cannot perform 'clone' on a Request with a disturbed body`,
+// because the body stream has already been consumed by the initial fetch.
+const bodyCache = new WeakMap();
+export function retryMiddleware(maxRetries) {
+    return {
+        async onRequest({ request }) {
+            if (!shouldBypassRetry(request) && request.body) {
+                // Clone-then-buffer here is safe — the original `request` is still
+                // un-disturbed and goes on to fetch unchanged. Only the clone is
+                // consumed.
+                bodyCache.set(request, await request.clone().arrayBuffer());
+            }
+            return request;
+        },
+        async onResponse({ request, response, options }) {
+            if (shouldBypassRetry(request))
+                return response;
+            const retriable = (status) => status >= 500 || status === 429 || status === 408;
+            let attempt = 0;
+            let res = response;
+            const doFetch = options.fetch;
+            const cachedBody = bodyCache.get(request);
+            while (attempt < maxRetries && retriable(res.status)) {
+                const backoffMs = Math.min(1000 * 2 ** attempt, 10000);
+                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+                // Build a fresh Request per attempt — the original's body stream
+                // was disturbed by the previous fetch.
+                const retryReq = new Request(request.url, {
+                    method: request.method,
+                    headers: request.headers,
+                    body: cachedBody ?? null,
+                });
+                res = await doFetch(retryReq);
+                attempt += 1;
+            }
+            bodyCache.delete(request);
+            return res;
+        },
+    };
+}
+export const errorMiddleware = {
+    async onResponse({ response }) {
+        if (response.ok)
+            return response;
+        let data = null;
+        try {
+            data = await response.clone().json();
+        }
+        catch {
+            data = null;
+        }
+        const ExceptionClass = getExceptionForStatusCode(response.status);
+        const message = extractErrorMessage(data, response.status);
+        const responseObj = data && typeof data === "object" && !Array.isArray(data)
+            ? data
+            : null;
+        throw new ExceptionClass(message, response.status, responseObj);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roe-typescript",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "TypeScript SDK for the Roe AI API (feature parity with roe-python).",
   "type": "module",
   "main": "dist/index.js",
@@ -13,24 +13,24 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "generate-sdk": "bash scripts/generate-sdk",
     "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",
+    "openapi-fetch": "^0.13.8",
+    "undici": "^6.25.0",
     "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",
+    "@types/uuid": "^10.0.0",
+    "openapi-typescript": "^7.6.1",
     "typescript": "^5.6.3",
     "vitest": "^1.6.0"
   }
 }
-

package/dist/models/agent.d.ts

@@ -1,78 +0,0 @@
-import { UserInfo } from "./user.js";
-import { AgentsAPI } from "../api/agents.js";
-import { Job } from "./job.js";
-export type AgentInputDefinition = {
-    key: string;
-    data_type: string;
-    description: string;
-    example?: string;
-    accepts_multiple_files?: boolean | null;
-};
-export type BaseAgent = {
-    id: string;
-    name: string;
-    creator?: UserInfo | null;
-    created_at: string;
-    disable_cache: boolean;
-    cache_failed_jobs: boolean;
-    organization_id: string;
-    engine_class_id: string;
-    current_version_id?: string | null;
-    job_count?: number;
-    most_recent_job?: string | null;
-    engine_name?: string;
-};
-export declare class BaseAgentWithApi implements BaseAgent {
-    id: string;
-    name: string;
-    creator?: UserInfo | null;
-    created_at: string;
-    disable_cache: boolean;
-    cache_failed_jobs: boolean;
-    organization_id: string;
-    engine_class_id: string;
-    current_version_id?: string | null;
-    job_count?: number;
-    most_recent_job?: string | null;
-    engine_name?: string;
-    private _agentsApi?;
-    constructor(data: BaseAgent);
-    setAgentsApi(api: AgentsAPI): void;
-    run(inputs: Record<string, unknown>): Promise<Job>;
-    listVersions(): Promise<AgentVersionWithApi[]>;
-    getCurrentVersion(): Promise<AgentVersionWithApi> | null;
-}
-export type AgentVersion = {
-    id: string;
-    name: string;
-    version_name: string;
-    creator?: UserInfo | null;
-    created_at: string;
-    description?: string | null;
-    engine_class_id: string;
-    engine_name: string;
-    input_definitions: AgentInputDefinition[];
-    engine_config: Record<string, unknown>;
-    organization_id: string;
-    readonly: boolean;
-    base_agent: BaseAgent;
-};
-export declare class AgentVersionWithApi implements AgentVersion {
-    id: string;
-    name: string;
-    version_name: string;
-    creator?: UserInfo | null;
-    created_at: string;
-    description?: string | null;
-    engine_class_id: string;
-    engine_name: string;
-    input_definitions: AgentInputDefinition[];
-    engine_config: Record<string, unknown>;
-    organization_id: string;
-    readonly: boolean;
-    base_agent: BaseAgent;
-    private _agentsApi?;
-    constructor(data: AgentVersion);
-    setAgentsApi(api: AgentsAPI): void;
-    run(inputs: Record<string, unknown>): Promise<Job>;
-}

package/dist/models/agent.js

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

package/dist/models/policy.d.ts

@@ -1,19 +0,0 @@
-export type Policy = {
-    id: string;
-    name: string;
-    description: string;
-    organization_id: string;
-    current_version_id: string | null;
-    created_at: string;
-    updated_at: string;
-};
-export type PolicyVersion = {
-    id: string;
-    version_name: string;
-    content: Record<string, unknown>;
-    created_at: string;
-    updated_at: string;
-    policy: Policy | null;
-    created_by: Record<string, unknown> | null;
-    base_version_id: string | null;
-};

package/dist/models/policy.js

@@ -1 +0,0 @@
-export {};

package/dist/models/responses.d.ts

@@ -1,81 +0,0 @@
-export declare enum JobStatus {
-    PENDING = 0,
-    STARTED = 1,
-    RETRY = 2,
-    SUCCESS = 3,
-    FAILURE = 4,
-    CANCELLED = 5,
-    CACHED = 6
-}
-export type ErrorResponse = {
-    detail: string;
-    status_code: number;
-};
-export type AgentDatum = {
-    key: string;
-    description: string;
-    data_type: string;
-    value: string;
-    cost?: number | null;
-};
-export type PaginatedResponse<T> = {
-    count: number;
-    next: string | null;
-    previous: string | null;
-    results: T[];
-};
-export type AgentJobStatus = {
-    status: number;
-    timestamp: number | null;
-    error_message?: string | null;
-};
-export type Reference = {
-    url: string;
-    resource_id: string;
-};
-export declare function referenceFromUrl(url: string): Reference;
-export declare function extractReferencesFromOutputs(outputs: AgentDatum[]): Reference[];
-export declare function getJobReferences(result: Pick<AgentJobResult, "outputs">): Reference[];
-export type AgentJobResult = {
-    agent_id: string;
-    agent_version_id: string;
-    inputs: unknown[];
-    input_tokens?: number | null;
-    output_tokens?: number | null;
-    outputs: AgentDatum[];
-    status?: number | null;
-    error_message?: string | null;
-};
-/** Returns true if the job status is SUCCESS or CACHED. */
-export declare function isJobSuccess(result: AgentJobResult): boolean;
-/** Returns true if the job status is FAILURE or CANCELLED (any non-success terminal state). */
-export declare function isJobFailure(result: AgentJobResult): boolean;
-/** Returns true if the job status is specifically CANCELLED. */
-export declare function isJobCancelled(result: AgentJobResult): boolean;
-export type AgentJobStatusBatch = {
-    id: string;
-    status?: number | null;
-    created_at?: unknown;
-    last_updated_at?: unknown;
-    timestamp?: number | null;
-    error_message?: string | null;
-};
-export type AgentJobResultBatch = {
-    id: string;
-    status?: number | null;
-    result?: AgentDatum[] | unknown | null;
-    corrected_outputs?: AgentDatum[] | null;
-    agent_id?: string | null;
-    agent_version_id?: string | null;
-    cost?: number | null;
-    inputs?: unknown[] | null;
-    input_tokens?: number | null;
-    output_tokens?: number | null;
-};
-export type JobDataDeleteResponse = {
-    status: string;
-    deleted_count: number;
-    failed_count: number;
-    outputs_sanitized: boolean;
-    errors?: string[] | null;
-};

package/dist/models/responses.js

@@ -1,48 +0,0 @@
-import { v4 as uuidv4 } from "uuid";
-export 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 || (JobStatus = {}));
-export function referenceFromUrl(url) {
-    const resource_id = url.split("/references/").at(-1)?.replace(/\/+$/, "") ?? uuidv4();
-    return { url, resource_id };
-}
-export 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;
-}
-export function getJobReferences(result) {
-    return extractReferencesFromOutputs(result.outputs ?? []);
-}
-/** Returns true if the job status is SUCCESS or CACHED. */
-export function isJobSuccess(result) {
-    return result.status === JobStatus.SUCCESS || result.status === JobStatus.CACHED;
-}
-/** Returns true if the job status is FAILURE or CANCELLED (any non-success terminal state). */
-export function isJobFailure(result) {
-    return result.status === JobStatus.FAILURE || result.status === JobStatus.CANCELLED;
-}
-/** Returns true if the job status is specifically CANCELLED. */
-export function isJobCancelled(result) {
-    return result.status === JobStatus.CANCELLED;
-}

package/dist/models/user.d.ts

@@ -1,6 +0,0 @@
-export type UserInfo = {
-    id: number;
-    email: string;
-    first_name?: string;
-    last_name?: string;
-};

package/dist/models/user.js

@@ -1 +0,0 @@
-export {};

package/dist/utils/httpClient.d.ts

@@ -1,30 +0,0 @@
-import { FileUpload } from "../models/file.js";
-import { RoeAuth } from "../auth.js";
-import { RoeConfig } from "../config.js";
-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>, metadata?: Record<string, unknown>): Promise<T>;
-}