@computesdk/platform 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 computesdk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @computesdk/platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ComputeSDK provider for [ComputeSDK Platform](https://platform.computesdk.com) hosted sandboxes — the same `compute` / `sandbox` interface as every other provider, backed by the platform's own sandbox API. Market placement, provider fallback, the secrets vault, warm pools and cost tracking all live server-side; your code gets one sandbox ID space and one API.
+
+```bash
+npm install computesdk @computesdk/platform
+```
+
+```typescript
+import { compute } from 'computesdk';
+import { platform } from '@computesdk/platform';
+
+const sdk = compute({
+  provider: platform({ apiKey: process.env.COMPUTE_API_KEY }),
+});
+
+const sandbox = await sdk.sandbox.create({ size: 'small' });
+const result = await sandbox.runCommand('echo hello');
+console.log(result.stdout);
+await sandbox.destroy();
+```
+
+## Authentication
+
+Credentials resolve once per provider instance, with the same precedence as the `compute` CLI:
+
+1. `apiKey` in config
+2. `COMPUTE_API_KEY` env var
+3. `BENCHMARKS_PLATFORM_API_KEY` env var (legacy alias)
+4. A `compute login` session (requires `@benchsdk/cli` installed — it's an optional peer dependency; the session store is read and refreshed but a login is never started)
+
+Base URL resolves similarly: `baseUrl` in config, then `COMPUTE_PLATFORM_URL`, then `BENCHMARKS_PLATFORM_URL`, then `https://platform.computesdk.com`.
+
+Credentials are only sent to `computesdk.com`, its subdomains, or loopback — pass `allowUntrustedHost: true` to send them elsewhere (HTTPS still required off-loopback). With no key configured you get a `no_credentials` error telling you to set `COMPUTE_API_KEY`, pass `apiKey`, or run `compute login`.
+
+`org` in config (or `COMPUTE_ORG`) sends `X-Org-Slug` on every request, for API keys that span orgs. A stored login's saved org is never sent — the platform already knows the active org.
+
+## Sizes and pricing
+
+Creates accept either a platform `size` or raw resources — never both:
+
+```typescript
+// Sizes: 'small' | 'medium' | 'large' | 'xlarge'
+await sdk.sandbox.create({ size: 'medium' });
+
+// Or raw resources (aliases: cpus|vcpus, memoryMb|memoryMiB|memMiB|memory, diskMb|diskMiB)
+await sdk.sandbox.create({ cpus: 4, memoryMb: 8192, diskMb: 20000 });
+```
+
+Market pricing options — `maxPrice: { usd, per: 'hour' }` and `orderType: 'market' | 'limit'` — can be passed per call or set once as `defaults` on the provider. `providerOrder` ranks where the platform tries to place the sandbox: your own provider keys by name, or `'market'` for the compute market.
+
+```typescript
+const provider = platform({
+  apiKey: process.env.COMPUTE_API_KEY,
+  defaults: {
+    size: 'small',
+    maxPrice: { usd: 0.5, per: 'hour' },
+    providerOrder: ['e2b', 'market'], // own E2B key first, market on failure
+  },
+});
+```
+
+## Own-keys (no market)
+
+A `providerOrder` with no `'market'` entry never touches the market — no buyer-lane approval, no credits, no cap; `maxPrice` and `orderType` are ignored (an own-key placement has no order semantics) and your provider bills you directly. The keys live in the org's vault, not in your code.
+
+```typescript
+const provider = platform({
+  apiKey: process.env.COMPUTE_API_KEY,
+  defaults: { providerOrder: ['e2b'] }, // own-keys only
+});
+```
+
+Provider order resolution: the call's `providerOrder`, then `defaults.providerOrder`, then the org's sandbox provider order (dashboard), then its Actions provider order. An org with none of these defaults to `['market']` — so own-keys users must set a provider order somewhere.
+
+## Errors
+
+API failures throw `PlatformApiError` with three derived fields:
+
+- `code` — the body's `details.code`, then top-level `code`, then a code derived from the HTTP status (`bad_request`, `unauthenticated`, `forbidden`, `not_found`, `conflict`, `payload_too_large`, `rate_limited`, `server_error`, `http_error`)
+- `details` — the body's `details` object (e.g. `details.attempts` on a placement failure)
+- `retryable` — true for 429/502/503/504, except market codes, which don't change on retry
+
+The market codes: `market_cap_required`, `market_access_required`, `limit_not_met`, `above_protection_limit`, `insufficient_credits`, `no_market_capacity`, `no_provider_configured`, `market_lane_not_approved`. Plus `sandbox_booting`, `idempotency_key_reused`, and the client's own `PlatformClientError` codes (`no_credentials`, `untrusted_host`, `untrusted_host_stored_auth`, `insecure_transport`, `invalid_argument`, `stream_ended`, `create_outcome_unknown`). Both code unions are exported and intentionally open.
+
+```typescript
+try {
+  await sdk.sandbox.create();
+} catch (err) {
+  if (err instanceof Error && 'code' in err) {
+    switch ((err as { code: string }).code) {
+      case 'insufficient_credits': /* top up */ break;
+      case 'no_market_capacity': /* retry later */ break;
+    }
+  }
+}
+```
+
+In multi-provider mode, `switch (err.code)` only sees the final error — the originals are on `err.errors`:
+
+```typescript
+import { e2b } from '@computesdk/e2b';
+
+const sdk = compute({ providers: [platform({ apiKey: k }), e2b({ apiKey: ek })] });
+try {
+  await sdk.sandbox.create();
+} catch (err) {
+  const codes = ((err as { errors?: { code?: string }[] }).errors ?? []).map((e) => e.code);
+  // e.g. ['no_market_capacity', 'unauthenticated']
+}
+```
+
+One exception: an error marked `fallback: false` (only `create_outcome_unknown` today) rethrows immediately — a box may exist and be billing, so trying another provider could boot a second one.
+
+Retries the SDK runs itself (the CLI does none of these): `sandbox_booting` exponential backoff up to ~60s (matched on the code — `no_market_capacity` is also a 503 and is never retried), `429` honoring `Retry-After`, and network errors on GET/DELETE only. No other POST is retried.
+
+## Limits
+
+- **Files**: ~4 MB per `readFile`/`writeFile` (UTF-8 bytes). The platform sits behind a 4.5 MB body cap; larger files need the upload/download URL route (not yet implemented).
+- **Commands**: `timeout` caps at 290s — the platform clamps it silently, so the SDK rejects higher values with `invalid_argument`. Longer work goes to `runCommand(cmd, { background: true })` (the processes route).
+- **Command length**: 64 KB.
+- **Secrets**: up to 100 vault secret names per sandbox.
+
+## Idempotent create
+
+Every `create` mints an `sdk-create:<uuid>` idempotency key, so a network blip or the 310s request timeout replays the same request instead of placing a second sandbox. Pass your own `idempotencyKey` to make the create safe across process restarts:
+
+```typescript
+await sdk.sandbox.create({ size: 'small', idempotencyKey: 'deploy-2026-10-27-a' } as any);
+```
+
+Same key + same request → the existing sandbox back, whatever its status. Same key + different request → `idempotency_key_reused` (409). A failed placement frees the key.
+
+If the outcome can't be determined within ~6 minutes, create throws `create_outcome_unknown` — check the org dashboard before retrying; the sandbox may still be creating.
+
+## Other create options
+
+`label` (≤200 chars, falls back to `name`), `secrets` (org vault names), `disk` (`{ diskId: '<orgSlug>/<diskId>', path, readonly?, branch? }`), `snapshotId`, `image`/`templateId`, `timeout` (→ `timeoutMs`), `envs` (merged under every command's `env`, request env wins).
+
+## What maps where
+
+| SDK call | Platform route |
+|---|---|
+| `sandbox.create` | `POST /api/v1/sandboxes` |
+| `sandbox.getById` | `GET /api/v1/sandboxes/:id` (404 → `null`) |
+| `sandbox.list` | `GET /api/v1/sandboxes?status=running` (follows `nextCursor`) |
+| `sandbox.destroy` | `DELETE /api/v1/sandboxes/:id` (404 = gone) |
+| `runCommand` | `POST /api/v1/sandboxes/:id/commands` (`cwd`, `env`, `timeoutMs`) |
+| `runCommand` + callbacks | same, `Accept: text/event-stream` (`stdout`/`stderr`/`exit`/`error`) |
+| `runCommand` + `background` | `POST /api/v1/sandboxes/:id/processes` |
+| `getUrl` | `GET /api/v1/sandboxes/:id/urls?port=&protocol=` |
+| `filesystem.*` | `GET/POST/DELETE /api/v1/sandboxes/:id/files` |
+
+Templates are not supported by this provider.

package/dist/index.d.mts

@@ -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 };