run402-mcp/sdk/dist/namespaces/jobs.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

/**
 * `jobs` namespace — platform-managed job runs.
 * All methods require the project's service key.
 */
import type { Client } from "../kernel.js";
export type ManagedJobType = string;
export type ManagedJobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
export interface ManagedJobSubmitRequest {
    jobType: ManagedJobType;
    input: {
        inputJson: Record<string, unknown>;
    };
    maxCostUsdMicros: number;
    /**
     * Optional HTTPS URL pushed once when the job reaches a terminal state
     * (completed/failed/cancelled), so you need not poll. Delivery is durable
     * (at-least-once, retried) and unsigned: dedupe on the `Run402-Webhook-Id`
     * header and re-fetch authoritative state with `get()` before acting — the
     * callback is a trigger, not the source of truth.
     */
    callbackUrl?: string;
}
export interface ManagedJobSubmitRequestWireCompat {
    job_type: ManagedJobType;
    input: {
        input_json?: Record<string, unknown>;
        "input.json"?: Record<string, unknown>;
    };
    max_cost_usd_micros: number;
    callback_url?: string;
}
type ManagedJobSubmitRequestInput = ManagedJobSubmitRequest | ManagedJobSubmitRequestWireCompat;
export interface ManagedJobError {
    code: string;
    message: string;
}
export interface ManagedJobMetadata {
    wall_seconds?: number;
    cost_usd_micros?: number;
    raw_cost_usd_micros?: number;
    absorbed_overage_usd_micros?: number;
    image_digest?: string;
    spot_rate_usd_hr_micros?: number;
    on_demand_rate_usd_hr_micros?: number;
    instance_type?: string;
    az?: string;
    peak_rss_gb?: number;
    interrupt_count?: number;
    attempt_count?: number;
    billing_status?: string;
    [key: string]: unknown;
}
/**
 * A recorded output file from a completed job run.
 *
 * Returned as the values of the `artifacts` map on {@link ManagedJobResponse}
 * (and in the terminal-completion webhook). The legacy `run402://storage/...`
 * ref strings — which were never resolvable — have been retired: `url` is an
 * absolute HTTPS endpoint that streams the raw bytes under the project's
 * service key (the same auth as the rest of `/jobs/v1`). Fetch it with
 * {@link Jobs.downloadArtifact} (which resolves the service key for you) or
 * directly with an `Authorization: Bearer <service_key>` header.
 *
 * `content_type`, `sha256`, and `size_bytes` are absent for jobs created before
 * the artifact-ref change; `url` still serves in that case.
 */
export interface ManagedJobArtifact {
    /** Absolute HTTPS URL that streams the raw artifact bytes (service-key auth). */
    url: string;
    /** MIME type of the artifact bytes (e.g. `application/json`, `text/plain`). */
    content_type?: string;
    /** Lowercase-hex SHA-256 of the bytes. */
    sha256?: string;
    /** Size of the artifact in bytes. */
    size_bytes?: number;
}
export interface ManagedJobResponse {
    job_id: string;
    job_type: ManagedJobType;
    status: ManagedJobStatus;
    created_at: string;
    started_at?: string;
    completed_at?: string;
    /**
     * Recorded outputs for a completed run, keyed by filename. Each value is a
     * {@link ManagedJobArtifact} object (the pre-retirement `run402://` ref
     * strings are gone). Absent until the job reaches a terminal state with
     * recorded artifacts.
     */
    artifacts?: Record<string, ManagedJobArtifact>;
    metadata?: ManagedJobMetadata;
    error?: ManagedJobError;
}
export interface ManagedJobLogEntry {
    timestamp: string;
    message: string;
    log_stream_name: string;
    event_id: string;
    ingestion_time?: string;
}
export interface ManagedJobLogsOptions {
    /** Maximum number of log entries to return. Gateway default is 100. */
    tail?: number;
    /**
     * Only include events at or after this ISO-8601 timestamp. Legacy epoch
     * milliseconds are still accepted for older callers.
     */
    since?: string | number;
}
export interface ManagedJobLogsResponse {
    logs: ManagedJobLogEntry[];
}
export interface ManagedJobPurgeResponse {
    deleted_jobs: number;
    /** Queued/running jobs included in the purge. */
    cancelled_active_jobs: number;
    /** Known EC2 runner instances terminated before records were deleted. */
    terminated_instances: number;
}
export declare class Jobs {
    private readonly client;
    constructor(client: Client);
    /** Submit a platform-managed job run for a run402-configured job type. */
    submit(projectId: string, request: ManagedJobSubmitRequestInput): Promise<ManagedJobResponse>;
    /** Get a job run by id. */
    get(projectId: string, jobId: string): Promise<ManagedJobResponse>;
    /**
     * Download a completed job's artifact by filename. Returns the raw `Response`
     * so callers can stream to disk or buffer with `.bytes()` / `.text()` —
     * this avoids forcing large artifacts through a JS string.
     *
     * Discover the available filenames from the `artifacts` map on {@link get}.
     *
     * @throws {ProjectNotFound} if `projectId` is not in the provider.
     * @throws {ApiError} on non-2xx — notably `404` when the job has not
     *   completed or the filename was not recorded for the run.
     */
    downloadArtifact(projectId: string, jobId: string, filename: string): Promise<Response>;
    /** Read job runner logs. */
    logs(projectId: string, jobId: string, opts?: ManagedJobLogsOptions): Promise<ManagedJobLogsResponse>;
    /** Cancel a queued or running job. */
    cancel(projectId: string, jobId: string): Promise<ManagedJobResponse>;
    /** Purge all managed job runs for a project. Active runners are terminated when known. */
    purge(projectId: string): Promise<ManagedJobPurgeResponse>;
}
export {};
//# sourceMappingURL=jobs.d.ts.map