@computesdk/platform 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import * as _computesdk_provider from '@computesdk/provider';
+import { CreateInstanceOptions } from '@computesdk/provider';
+
+/**
+ * Thin client for the hosted ComputeSDK platform API.
+ *
+ * This is the single platform transport: `@computesdk/platform` (the SDK
+ * provider) and `@computesdk/cli` both use it. Wire types for Actions and
+ * sandboxes live in `types.ts` (sandboxes) and in the CLI (Actions); the API
+ * is the contract.
+ */
+declare const DEFAULT_BASE_URL = "https://platform.computesdk.com";
+/**
+ * Market order codes the platform returns. Retrying never changes the
+ * outcome, so errors carrying them are `retryable: false`.
+ */
+declare const MARKET_CODES: ReadonlySet<string>;
+/**
+ * Codes a `PlatformApiError` can carry — the market order codes, the sandbox
+ * lifecycle codes, and `codeForStatus`'s status-table codes. Kept open for
+ * codes added later; callers can `switch (err.code)`.
+ */
+type PlatformApiErrorCode = 'market_cap_required' | 'market_access_required' | 'limit_not_met' | 'above_protection_limit' | 'insufficient_credits' | 'no_market_capacity' | 'no_provider_configured' | 'market_lane_not_approved' | 'sandbox_booting' | 'idempotency_key_reused' | 'bad_request' | 'unauthenticated' | 'forbidden' | 'not_found' | 'conflict' | 'payload_too_large' | 'rate_limited' | 'server_error' | 'http_error' | (string & {});
+interface PlatformAuth {
+    apiKey: string;
+    baseUrl: string;
+    /** Sent as `X-Org-Slug` when set (--org / COMPUTE_ORG / stored login org). */
+    orgSlug?: string;
+}
+declare class PlatformApiError extends Error {
+    status: number;
+    body?: unknown | undefined;
+    /** details.code ?? body.code ?? codeForStatus(status) */
+    readonly code: PlatformApiErrorCode;
+    /** The body's `details` object, when the error response carried one. */
+    readonly details?: Record<string, unknown>;
+    /** 429/502/503/504 — except market codes, which don't change on retry. */
+    readonly retryable: boolean;
+    /** Parsed `Retry-After` in ms, when the response carried the header. */
+    retryAfterMs?: number;
+    constructor(status: number, message: string, body?: unknown | undefined);
+}
+/** Stable machine-readable codes for errors raised by the client itself. */
+type PlatformClientErrorCode = 'no_credentials' | 'untrusted_host' | 'untrusted_host_stored_auth' | 'insecure_transport' | 'invalid_argument' | 'stream_ended' | 'create_outcome_unknown' | 'workflow_not_found' | (string & {});
+/** An error the client raised before or instead of an API call. */
+declare class PlatformClientError extends Error {
+    code: PlatformClientErrorCode;
+    /**
+     * `false` means falling back to another provider is unsafe — e.g.
+     * create_outcome_unknown, where a box may exist and be billing.
+     */
+    fallback?: boolean;
+    constructor(code: PlatformClientErrorCode, message: string);
+}
+/** The `--json` error envelope; `code` is stable, `message` is for humans. */
+interface PlatformErrorEnvelope {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        /** Present when the platform answered; absent for local/transport failures. */
+        httpStatus?: number;
+        retryable: boolean;
+        /** The platform's `details` object, when its error response carried one. */
+        details?: Record<string, unknown>;
+    };
+}
+declare function codeForStatus(status: number): string;
+declare function errorDetails(body: unknown): Record<string, unknown> | undefined;
+/**
+ * Classify any error thrown by an Actions command. API errors carry the HTTP
+ * status; CLI errors carry their own code; a fetch rejection (DNS, refused
+ * connection, TLS) is `network`; anything else is `unknown`.
+ */
+declare function toErrorEnvelope(error: unknown): PlatformErrorEnvelope;
+declare class PlatformClient {
+    private readonly auth;
+    private readonly fetchImpl;
+    constructor(auth: PlatformAuth, fetchImpl?: typeof fetch);
+    get baseUrl(): string;
+    get<T>(path: string, params?: Record<string, string | string[] | undefined>, opts?: RequestOpts): Promise<T>;
+    post<T>(path: string, body?: Record<string, unknown>, opts?: RequestOpts): Promise<T>;
+    /**
+     * POST JSON and return the raw response body for SSE reading
+     * (Accept: text/event-stream). Callers feed it to `readSseNamedEvents`.
+     */
+    postStream(path: string, body?: Record<string, unknown>, opts?: RequestOpts): Promise<ReadableStream<Uint8Array>>;
+    /** POST a raw text body (e.g. a unified diff to `/api/v1/actions/patches`). */
+    postText<T>(path: string, body: string, contentType: string, opts?: RequestOpts): Promise<T>;
+    put<T>(path: string, body?: Record<string, unknown>, opts?: RequestOpts): Promise<T>;
+    patch<T>(path: string, body?: Record<string, unknown>, opts?: RequestOpts): Promise<T>;
+    del<T>(path: string, opts?: RequestOpts): Promise<T>;
+    /**
+     * One `data:` JSON payload per SSE event. `next()` resolves to the payload,
+     * or null when the stream ends. Call `close()` to abort.
+     */
+    sse(path: string, params?: Record<string, string | string[] | undefined>, opts?: RequestOpts): AsyncGenerator<unknown>;
+    /**
+     * `sse()` with the frame's `event:` name preserved — for streams whose
+     * events are distinguished by name rather than payload shape (process
+     * follow: stdout/stderr share a `{chunk}` payload).
+     */
+    sseNamed(path: string, params?: Record<string, string | string[] | undefined>, opts?: RequestOpts): AsyncGenerator<{
+        event: string;
+        data: unknown;
+    }>;
+    /** Download bytes following redirects (artifact URLs 302 to storage). */
+    download(path: string, opts?: RequestOpts): Promise<Uint8Array>;
+    private headers;
+    private parse;
+}
+interface RequestOpts {
+    signal?: AbortSignal;
+}
+/** Minimal SSE reader: yields the JSON payload of each `data:` event. */
+declare function readSseEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<unknown>;
+/** `readSseEvents` with the `event:` name preserved alongside the JSON payload. */
+declare function readSseNamedEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<{
+    event: string;
+    data: unknown;
+}>;
+/** The subset of `@benchsdk/cli`'s `resolveAuth` result Actions needs. */
+type StoredPlatformAuth = {
+    apiKey?: string;
+    token?: string;
+    orgSlug?: string;
+    orgId?: string;
+};
+type StoredPlatformAuthResolver = (opts: {
+    baseUrl: string;
+}) => Promise<StoredPlatformAuth>;
+/**
+ * Precedence: `--api-key` > `COMPUTE_API_KEY` > `BENCHMARKS_PLATFORM_API_KEY`
+ * (legacy) > platform OAuth credentials stored by `compute login`
+ * (`~/.benchsdk/credentials.json`, via `@benchsdk/cli`'s `resolveAuth`, which
+ * refreshes an expired access token but never opens a browser). `compute
+ * login` writes the same store, so a platform login covers these commands.
+ */
+declare function resolvePlatformAuth(opts: {
+    apiKey?: string;
+    baseUrl?: string;
+    allowUntrustedHost?: boolean;
+    /** One-off org override: sent as X-Org-Slug (also settable via COMPUTE_ORG). */
+    org?: string;
+}, resolveStored?: StoredPlatformAuthResolver, 
+/** Overrides the no-credentials message's credential hint (the CLI passes `--api-key`). */
+credentialsHint?: string): Promise<PlatformAuth>;
+/** https://, or http:// to a loopback host only. */
+declare function isSecurePlatformTransport(baseUrl: string): boolean;
+/** computesdk.com (and subdomains) or localhost — safe to receive the API key. */
+declare function isTrustedPlatformHost(baseUrl: string): boolean;
+
+/**
+ * Sandbox wire types — mirror the response shapes of
+ * benchmarks-platform `lib/sandboxes` (the `/api/v1/sandboxes` routes).
+ * The API is the contract; keep in sync by hand.
+ */
+interface SandboxCost {
+    rate: {
+        usd: number;
+        unit: string;
+    } | null;
+    runtimeSeconds: number;
+    costUsd: number | null;
+    settled: boolean;
+}
+/** `toSummary` — one row of GET /api/v1/sandboxes. */
+interface SandboxSummary {
+    id: string;
+    label: string | null;
+    provider: string | null;
+    providerSandboxId: string | null;
+    status: 'creating' | 'running' | 'destroyed' | string;
+    placementAttempts: unknown[];
+    commandCount: number;
+    secrets: string[];
+    /** The `boot.image` asked for, and what the provider actually booted. */
+    requestedImage: string | null;
+    image: string | null;
+    createdAt: string;
+    lastCommandAt: string | null;
+    destroyedAt: string | null;
+    destroyError: string | null;
+    /** The sandbox's configured timeout, when one was set at create. */
+    timeoutMs: number | null;
+    /** How the sandbox was placed — source, order type, rate, max price, the
+     * requested platform `size` and the seller's `box` on a market fill. */
+    placement: {
+        source: 'market' | 'own-key';
+        size?: string | null;
+        box?: {
+            provider: string;
+            sizeName: string | null;
+            resources?: {
+                cpus: number | null;
+                memoryMb: number | null;
+                ephemeralDiskMb: number | null;
+            };
+        };
+        orderType?: 'market' | 'limit';
+        rate: {
+            usd: number;
+            per: string;
+        };
+        maxPrice?: {
+            usd: number;
+            per: string;
+        };
+    } | null;
+    cost: SandboxCost;
+}
+/** `toDetail` — POST /sandboxes and GET /sandboxes/{id}. */
+interface SandboxDetail extends SandboxSummary {
+    /** BYOK direct-attach descriptor — null on market fills and ambient providers. */
+    attach: {
+        provider: string;
+        providerSandboxId: string;
+        region: string | null;
+    } | null;
+}
+interface SandboxProcess {
+    id: string;
+    jobId: string;
+    pid: number | null;
+    command: string;
+    cwd: string | null;
+    envNames: string[];
+    /** Whether the job's stdin pipe is open (spawn `--stdin`). */
+    stdin: boolean;
+    status: string;
+    exitCode: number | null;
+    signal: string | null;
+    startedAt: string;
+    exitedAt: string | null;
+}
+interface SandboxProcessStatus extends SandboxProcess {
+    stdout: string;
+    stderr: string;
+}
+/** The commands route's JSON (non-SSE) result. */
+interface CommandResult {
+    commandId: string;
+    exitCode: number;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+}
+interface FileEntry {
+    name: string;
+    type: 'file' | 'directory';
+    size?: number;
+    modified?: string;
+}
+type PathView = {
+    path: string;
+    type: 'file';
+    content: string;
+} | {
+    path: string;
+    type: 'directory';
+    entries: FileEntry[];
+};
+/** `snapshotView` — one row of GET /sandboxes/{id}/snapshots. */
+interface SandboxSnapshot {
+    id: string;
+    sandboxId: string;
+    provider: string;
+    region: string | null;
+    providerSnapshotId: string;
+    label: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    deletedAt: string | null;
+}
+
+type PlatformSize = 'small' | 'medium' | 'large' | 'xlarge';
+interface PlatformConfig {
+    /** An org API key or an OAuth access token; both are sent as Bearer. */
+    apiKey?: string;
+    /** baseUrl > COMPUTE_PLATFORM_URL > BENCHMARKS_PLATFORM_URL > the default host. */
+    baseUrl?: string;
+    /** Org slug, sent as X-Org-Slug (also COMPUTE_ORG); ignored for org API keys. */
+    org?: string;
+    /** Send credentials to a host outside computesdk.com/loopback. */
+    allowUntrustedHost?: boolean;
+    /** Applied to every create unless the call overrides it. */
+    defaults?: {
+        size?: PlatformSize;
+        maxPrice?: {
+            usd: number;
+            per: 'second' | 'minute' | 'hour';
+        };
+        orderType?: 'market' | 'limit';
+        providerOrder?: string[];
+    };
+    /** fetch override, for tests and proxies. */
+    fetch?: typeof fetch;
+}
+/** Platform-specific create options, alongside the universal ones. */
+interface PlatformCreateOptions extends CreateInstanceOptions {
+    size?: PlatformSize;
+    maxPrice?: {
+        usd: number;
+        per: 'second' | 'minute' | 'hour';
+    };
+    orderType?: 'market' | 'limit';
+    providerOrder?: string[];
+    /** Org vault secret names to inject, up to 100. */
+    secrets?: string[];
+    /** Disk v1: `{ diskId, path, readonly?, branch? }`; diskId must be under `<orgSlug>/`. */
+    disk?: {
+        diskId: string;
+        path: string;
+        readonly?: boolean;
+        branch?: string;
+    };
+    /** Sandbox label (falls back to universal `name`); max 200 characters. */
+    label?: string;
+    /** Makes the create safe to replay across process restarts. */
+    idempotencyKey?: string;
+}
+/** What the SDK's instance handle carries through to every method call. */
+interface PlatformInstance {
+    id: string;
+    detail: SandboxDetail;
+    client: PlatformClient;
+    /** envs passed at create — merged under each command's env. */
+    envs: Record<string, string>;
+    /** The create's `timeout` — getInfo fallback when `summary.timeoutMs` is null. */
+    createTimeout?: number;
+}
+declare const platform: (config: PlatformConfig) => _computesdk_provider.Provider<PlatformInstance, any, any, _computesdk_provider.Volume>;
+
+export { type CommandResult, DEFAULT_BASE_URL, type FileEntry, MARKET_CODES, type PathView, PlatformApiError, type PlatformApiErrorCode, type PlatformAuth, PlatformClient, PlatformClientError, type PlatformClientErrorCode, type PlatformConfig, type PlatformCreateOptions, type PlatformErrorEnvelope, type PlatformSize, type RequestOpts, type SandboxCost, type SandboxDetail, type SandboxProcess, type SandboxProcessStatus, type SandboxSnapshot, type SandboxSummary, type StoredPlatformAuth, type StoredPlatformAuthResolver, codeForStatus, errorDetails, isSecurePlatformTransport, isTrustedPlatformHost, platform, readSseEvents, readSseNamedEvents, resolvePlatformAuth, toErrorEnvelope };