roe-typescript 0.1.0

package/dist/models/agent.d.ts

@@ -0,0 +1,78 @@
+import { UserInfo } from "./user";
+import { AgentsAPI } from "../api/agents";
+import { Job } from "./job";
+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

@@ -0,0 +1,40 @@
+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/file.d.ts

@@ -0,0 +1,30 @@
+export type FileUploadInit = {
+    path?: string;
+    file?: NodeJS.ReadableStream;
+    filename?: string;
+    mimeType?: string;
+};
+export declare class FileUpload {
+    readonly path?: string;
+    readonly file?: NodeJS.ReadableStream;
+    readonly filename?: string;
+    readonly mimeType?: string;
+    private _openedStream;
+    constructor(init: FileUploadInit);
+    get effectiveFilename(): string;
+    get effectiveMimeType(): string;
+    /**
+     * Opens the file for reading. If a path was provided, creates a new ReadStream.
+     * Track opened streams so they can be closed later.
+     */
+    open(): NodeJS.ReadableStream;
+    /**
+     * Closes any opened file stream to prevent resource leaks.
+     * Should be called after the file upload is complete.
+     */
+    close(): void;
+    /**
+     * Returns the file size in bytes, if available.
+     */
+    getSize(): number | undefined;
+}

package/dist/models/file.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+import path from "path";
+import mime from "mime-types";
+import { BadRequestError } from "../exceptions";
+/** Maximum file size: 2GB (aligned with main-roe backend) */
+const MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024;
+export 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.statSync(this.path);
+                if (stat.size > MAX_FILE_SIZE) {
+                    throw new BadRequestError(`File exceeds maximum size of 2GB: ${this.path} (${(stat.size / (1024 * 1024 * 1024)).toFixed(2)}GB)`, 400);
+                }
+            }
+            catch (err) {
+                if (err instanceof BadRequestError)
+                    throw err;
+                throw new Error(`Cannot access file: ${this.path}`);
+            }
+        }
+    }
+    get effectiveFilename() {
+        if (this.filename)
+            return this.filename;
+        if (this.path)
+            return path.basename(this.path);
+        return "upload";
+    }
+    get effectiveMimeType() {
+        if (this.mimeType)
+            return this.mimeType;
+        const guess = mime.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.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.statSync(this.path).size;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+}

package/dist/models/job.d.ts

@@ -0,0 +1,37 @@
+import { AgentsAPI } from "../api/agents";
+import { AgentJobResult, AgentJobStatus } from "./responses";
+export declare class Job {
+    private readonly agentsApi;
+    private readonly jobId;
+    private readonly timeoutSeconds;
+    constructor(opts: {
+        agentsApi: AgentsAPI;
+        jobId: string;
+        timeoutSeconds?: number;
+    });
+    get id(): string;
+    wait(params?: {
+        intervalSeconds?: number;
+        timeoutSeconds?: number;
+    }): Promise<AgentJobResult>;
+    retrieveStatus(): Promise<AgentJobStatus>;
+    retrieveResult(): Promise<AgentJobResult>;
+}
+export declare class JobBatch {
+    private readonly agentsApi;
+    private readonly jobIds;
+    private readonly timeoutSeconds;
+    private completed;
+    private statusCache;
+    constructor(opts: {
+        agentsApi: AgentsAPI;
+        jobIds: string[];
+        timeoutSeconds?: number;
+    });
+    get jobs(): Job[];
+    wait(params?: {
+        intervalSeconds?: number;
+        timeoutSeconds?: number;
+    }): Promise<AgentJobResult[]>;
+    retrieveStatus(): Promise<Record<string, number>>;
+}

package/dist/models/job.js

@@ -0,0 +1,133 @@
+import { JobStatus } from "./responses";
+export 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 === JobStatus.SUCCESS || code === JobStatus.CACHED) {
+                return this.retrieveResult();
+            }
+            if (code === JobStatus.FAILURE || code === 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);
+    }
+}
+export 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 === JobStatus.FAILURE || s.status === 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 === JobStatus.SUCCESS || code === 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;
+    }
+}

package/dist/models/responses.d.ts

@@ -0,0 +1,71 @@
+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;
+    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[];
+};
+export type AgentJobStatusBatch = {
+    id: string;
+    status?: number | null;
+    created_at?: unknown;
+    last_updated_at?: unknown;
+};
+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

@@ -0,0 +1,36 @@
+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 ?? []);
+}

package/dist/models/user.d.ts

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

package/dist/models/user.js

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