@arker-ai/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,120 +1,533 @@
+interface components {
+    schemas: {
+        /** @description Standard API error. Backends use code "unsupported_operation" when the request is valid but names an operation or option this backend cannot support. */
+        ErrorResponse: {
+            /**
+             * @description Stable machine-readable error code. "unsupported_operation" means the backend does not implement the requested optional feature.
+             * @example unsupported_operation
+             */
+            code: string;
+            /** @description Human-readable error message. */
+            message: string;
+        };
+        NetworkPolicy: components["schemas"]["NetworkPolicyOpen"] | components["schemas"]["NetworkPolicyBlocked"] | components["schemas"]["NetworkPolicyAllow"] | components["schemas"]["NetworkPolicyBlock"];
+        NetworkPolicyOpen: {
+            /** @constant */
+            type: "open";
+        };
+        NetworkPolicyBlocked: {
+            /** @constant */
+            type: "blocked";
+        };
+        NetworkPolicyAllow: {
+            /** @constant */
+            type: "allow";
+            allow: string[];
+        };
+        NetworkPolicyBlock: {
+            /** @constant */
+            type: "block";
+            block: string[];
+        };
+        NetworkPolicyInput: boolean | string | components["schemas"]["NetworkPolicy"];
+        ForkRequest: {
+            name?: string | null;
+            image?: string | null;
+            network?: components["schemas"]["NetworkPolicyInput"] | null;
+            /** @default true */
+            disk?: boolean;
+            vcpu_count?: number | null;
+            memory_mib?: number | null;
+            max_memory_mib?: number | null;
+            disk_mib?: number | null;
+            /**
+             * @description Request a durable VM. If the underlying host fails mid-run, the run resumes on a healthy host with the VM's filesystem state preserved. Use for long-running or non-idempotent work. Forked children default to non-durable. Backends without durability support return ErrorResponse code "unsupported_operation".
+             * @default false
+             */
+            durable?: boolean | null;
+        };
+        SessionInfo: {
+            session_id: string;
+            state: string;
+            cwd: string;
+        };
+        ListSessionsResponse: components["schemas"]["SessionInfo"][];
+        GoldenInfo: {
+            vm_id: string;
+            name: string;
+            source_golden: string;
+            memory_mib?: number | null;
+            vcpu_count?: number | null;
+            disk_mib?: number | null;
+        };
+        ListGoldensResponse: {
+            goldens: components["schemas"]["GoldenInfo"][];
+        };
+        VmInfo: {
+            vm_id: string;
+            owner_id: string;
+            created_at: string;
+            name?: string | null;
+            source_golden?: string | null;
+            state: string;
+            last_activity?: string | null;
+            vcpu_count?: number | null;
+            memory_mib?: number | null;
+            disk_mib?: number | null;
+            sessions: components["schemas"]["SessionInfo"][];
+        };
+        ListVmsResponse: {
+            vms: components["schemas"]["VmInfo"][];
+        };
+        ForkVmResponse: {
+            vm_id: string;
+            owner_id: string;
+            created_at: string;
+            sessions: components["schemas"]["SessionInfo"][];
+            ssh_private_key?: string | null;
+            tunnels?: components["schemas"]["RunTunnelStatus"][];
+            network?: components["schemas"]["RunNetworkStatus"] | null;
+        };
+        DeleteVmResponse: {
+            deleted: boolean;
+        };
+        DeleteSessionResponse: {
+            deleted: boolean;
+        };
+        MountRequest: {
+            uri: string;
+            mount_point: string;
+            /** @default dir */
+            format?: string;
+        };
+        /** @description Foreground command execution is the portable baseline. Optional session, background, mount, resource, network, signal, release, and runtime fields may return ErrorResponse code "unsupported_operation" on backends that do not support them. */
+        RunRequest: {
+            /** @description Optional persistent session id. Backends without persistent sessions return unsupported_operation when this is requested. */
+            session_id?: string | null;
+            command: string;
+            /**
+             * @description Run asynchronously. Backends without background execution return unsupported_operation and must not silently run the command synchronously.
+             * @default false
+             */
+            background?: boolean;
+            timeout?: number | null;
+            /** @default auto */
+            end_symbol?: string | null;
+            /**
+             * @description Optional external mounts. Backends without mount support return unsupported_operation when this is non-empty.
+             * @default []
+             */
+            mounts?: components["schemas"]["MountRequest"][];
+            /** @description Optional per-run resource override. Backends without resource override support return unsupported_operation when this is requested. */
+            vcpu_count?: number | null;
+            /** @description Optional per-run resource override. Backends without resource override support return unsupported_operation when this is requested. */
+            memory_mib?: number | null;
+            /** @description Optional per-run resource override. Backends without resource override support return unsupported_operation when this is requested. */
+            disk_mib?: number | null;
+            /** @description Optional network/tunnel request. Backends without networking support return unsupported_operation when this is requested. */
+            network?: components["schemas"]["RunNetworkRequest"] | null;
+            /** @description Optional release selection. Backends without release selection support return unsupported_operation when this is requested. */
+            release?: string | null;
+            /** @description Optional session signal. Backends without signal support return unsupported_operation when this is requested. */
+            signal?: string | null;
+            /** @description Optional runtime selection. Backends without runtime selection support return unsupported_operation when this is requested. */
+            runtime?: string | null;
+            /** @description Optional runtime override. Backends without runtime overrides return unsupported_operation when this is requested. */
+            runtime_override?: string | null;
+        };
+        RunNetworkRequest: {
+            inbound?: components["schemas"]["RunInboundRequest"] | null;
+        };
+        RunInboundRequest: {
+            /** @default {} */
+            ports?: {
+                [key: string]: components["schemas"]["RunInboundPortRequest"];
+            };
+        };
+        RunInboundPortRequest: {
+            /** @default private */
+            visibility?: string;
+            /** @default http */
+            protocol?: string;
+        };
+        /** @description Successful run result. BackgroundRunResponse and PtyRunResponse are returned only by backends that support those modes; unsupported modes return ErrorResponse code "unsupported_operation". */
+        RunResponse: components["schemas"]["CompletedRunResponse"] | components["schemas"]["BackgroundRunResponse"] | components["schemas"]["PtyRunResponse"];
+        CompletedRunResponse: {
+            stdout: string;
+            stdout_encoding: string;
+            stderr: string;
+            stderr_encoding: string;
+            exit_code: number;
+            completed: boolean;
+        };
+        BackgroundRunResponse: {
+            run_id: string;
+            completed: boolean;
+            /** @default [] */
+            tunnels?: components["schemas"]["RunTunnelStatus"][];
+            network?: components["schemas"]["RunNetworkStatus"] | null;
+        };
+        PtyRunResponse: {
+            /** @constant */
+            pty: true;
+            session_id: string;
+            ws_url: string;
+        };
+        RunStatusResponse: {
+            run_id: string;
+            stdout: string;
+            stdout_encoding: string;
+            stderr: string;
+            stderr_encoding: string;
+            exit_code: number | null;
+            completed: boolean;
+            tunnels: components["schemas"]["RunTunnelStatus"][];
+            network?: components["schemas"]["RunNetworkStatus"] | null;
+            /**
+             * @description Number of times this run has been automatically retried after an infrastructure failure. 0 for runs that completed without interruption. Backends without durability support omit this field; clients should treat it as 0 when absent.
+             * @default 0
+             */
+            retry_count?: number;
+        };
+        RunNetworkStatus: {
+            inbound: components["schemas"]["RunInboundStatus"];
+        };
+        RunInboundStatus: {
+            ports: {
+                [key: string]: components["schemas"]["RunInboundPortStatus"];
+            };
+        };
+        RunInboundPortStatus: {
+            requested: string;
+            observed: string;
+            effective: string;
+            protocol: string;
+            url?: string | null;
+        };
+        RunTunnelStatus: {
+            /** @default  */
+            run_id?: string;
+            port: number;
+            visibility: string;
+            protocol: string;
+            url?: string | null;
+            status: string;
+            message?: string | null;
+        };
+        CancelRunResponse: {
+            cancelled: boolean;
+        };
+        /** @description Create a persistent session. Backends without persistent sessions return unsupported_operation. */
+        CreateSessionRequest: {
+            env?: {
+                [key: string]: string;
+            } | null;
+            cwd?: string | null;
+        };
+        /** @description Resize a PTY session. Backends without PTY sessions return unsupported_operation. */
+        ResizePtyRequest: {
+            cols: number;
+            rows: number;
+        };
+        ResizePtyResponse: {
+            resized: boolean;
+        };
+        /** @description Resize VM resources. Backends without VM resize support return unsupported_operation. */
+        ResizeRequest: {
+            vcpu_count?: number | null;
+            memory_mib?: number | null;
+            disk_mib?: number | null;
+        };
+        ResizeResponse: {
+            ok: boolean;
+        };
+        SyncRequest: components["schemas"]["SyncReadRequest"] | components["schemas"]["SyncWriteRequest"];
+        SyncReadRequest: {
+            /** @constant */
+            op: "read";
+            path: string;
+        };
+        SyncWriteRequest: {
+            /** @constant */
+            op: "write";
+            writes: components["schemas"]["SyncWriteEntry"][];
+        };
+        SyncWriteEntry: components["schemas"]["SyncChunkWrite"] | components["schemas"]["SyncPresignedWriteRequest"] | components["schemas"]["SyncPresignedWriteCommit"];
+        SyncChunkWrite: {
+            path: string;
+            size: number;
+            upload_id: string;
+            content: string;
+            start: number;
+            end: number;
+            sha256?: string | null;
+            /** @default false */
+            is_secret?: boolean;
+        };
+        SyncPresignedWriteRequest: {
+            path: string;
+            size: number;
+            presigned: boolean;
+            /** @default false */
+            is_secret?: boolean;
+        };
+        SyncPresignedWriteCommit: {
+            path: string;
+            size: number;
+            upload_id: string;
+            sha256?: string | null;
+        };
+        SyncResponse: components["schemas"]["SyncReadResponse"] | components["schemas"]["SyncWriteResponse"];
+        SyncReadResponse: components["schemas"]["SyncReadInlineResponse"] | components["schemas"]["SyncReadPresignedResponse"];
+        SyncReadInlineResponse: {
+            ok: boolean;
+            /** @constant */
+            op: "read";
+            path: string;
+            size: number;
+            content: string;
+            encoding: string;
+        };
+        SyncReadPresignedResponse: {
+            ok: boolean;
+            /** @constant */
+            op: "read";
+            path: string;
+            size: number;
+            presigned_url: string;
+            expires_in: number;
+            method: string;
+        };
+        SyncWriteResponse: {
+            ok: boolean;
+            /** @constant */
+            op: "write";
+            results: components["schemas"]["SyncWriteResult"][];
+        };
+        SyncWriteResult: components["schemas"]["SyncChunkWriteResult"] | components["schemas"]["SyncPresignedWriteRequestResult"] | components["schemas"]["SyncCommitWriteResult"];
+        SyncChunkWriteResult: {
+            path: string;
+            size: number;
+            received_bytes: number;
+            ranges: components["schemas"]["SyncByteRange"][];
+            complete: boolean;
+            written: boolean;
+            error?: components["schemas"]["SyncEntryError"] | null;
+        };
+        SyncPresignedWriteRequestResult: {
+            path: string;
+            size: number;
+            presigned_url: string;
+            upload_id: string;
+            expires_in: number;
+            method: string;
+            complete: boolean;
+            written: boolean;
+            error?: components["schemas"]["SyncEntryError"] | null;
+        };
+        SyncCommitWriteResult: {
+            path: string;
+            size: number;
+            complete: boolean;
+            written: boolean;
+            error?: components["schemas"]["SyncEntryError"] | null;
+        };
+        SyncByteRange: {
+            start: number;
+            end: number;
+        };
+        SyncEntryError: {
+            code: string;
+            message: string;
+        };
+    };
+    responses: {
+        /** @description API error. */
+        Error: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The request is valid, but this backend does not support the requested operation or option. The response body uses ErrorResponse with code "unsupported_operation". */
+        UnsupportedOperation: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+    };
+    parameters: {
+        VmId: string;
+        RunId: string;
+        SessionId: string;
+        /** @description Optional idempotency key for safe retries of POST /v1/vms/{id}/run. A retry with the same key and the same request returns the original run. A different request under the same key returns ErrorResponse code "conflict" with the original run_id. Keys expire 24h after the run completes. */
+        IdempotencyKey: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
 /**
- * Arker SDK — TypeScript client.
- *
- * Quickstart:
- *
- *   import { Arker } from "@arker-ai/sdk";
- *   const arker = new Arker({ apiKey: "ark_live_..." });
- *   const vm    = await arker.vm("arkuntu").fork({ name: "hello" });
- *
- *   const result = await vm.run("echo hi");
- *   console.log(new TextDecoder().decode(result.stdout)); // → "hi\n"
- *
- *   await vm.sync.writeFile("/home/user/data.bin", new Uint8Array([1, 2, 3]));
- *   const blob = await vm.sync.readFile("/home/user/data.bin");
+ * Arker TypeScript SDK.
  *
- *   const child = await vm.fork({ name: "branch" });
- *   await child.delete();
- *   await vm.delete();
- *
- *   // List your VMs (paginated):
- *   const page = await arker.list({ limit: 10 });
- *   for (const summary of page.items) {
- *     console.log(summary.vm_id, summary.name, summary.created_at);
- *   }
- *
- * Errors are thrown as `ArkerError(code, message, status)`.
+ * A small wrapper around the VM API. Configure a region for the standard
+ * Arker endpoints, or pass baseUrl directly for internal/dev targets.
  */
-declare const DEFAULT_BASE_URL = "https://aws-us-west-2.burst.arker.ai";
-/** `list` is served from a different host than the rest; used regardless of the client's baseUrl. */
-declare const LIST_BASE_URL = "https://arker.ai";
-/** 1000 pre-forked public VMs (snapshots of `arkuntu`). The SDK picks one
- * at random per `vm("arkuntu").fork()` call so concurrent fork bursts
- * fan out across distinct source state.log keys, avoiding per-key
- * throttling under load. */
-declare const ARKUNTU_POOL: readonly string[];
-/** Source-VM aliases. `arkuntu` resolves to the 1000-VM pool above. */
-declare const SOURCE_ALIASES: Record<string, readonly string[] | string>;
-/** Files above this size go through a direct upload path. */
+
+type ApiSchema<Name extends keyof components["schemas"]> = components["schemas"][Name];
 declare const CHUNK_SIZE: number;
+type FetchLike = typeof fetch;
+type HttpMethod = "GET" | "POST" | "DELETE";
+interface RetryOptions {
+    attempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterMs?: number;
+}
 interface ArkerOptions {
-    apiKey: string;
+    apiKey?: string;
     baseUrl?: string;
-}
-interface ForkOptions {
-    name?: string;
-    isPublic?: boolean;
+    burstBaseUrl?: string;
+    fetch?: FetchLike;
     region?: string;
+    retry?: RetryOptions | false;
 }
-interface RunOptions {
-    sessionId?: string | number;
-    timeout?: number;
-}
-interface RunResult {
+type NetworkPolicy = ApiSchema<"NetworkPolicy">;
+type NetworkPolicyInput = ApiSchema<"NetworkPolicyInput">;
+type ForkRequest = ApiSchema<"ForkRequest">;
+type ForkOptions = ForkRequest;
+type SessionInfo = ApiSchema<"SessionInfo">;
+type GoldenInfo = ApiSchema<"GoldenInfo">;
+type ListGoldensResponse = ApiSchema<"ListGoldensResponse">;
+type VmInfo = ApiSchema<"VmInfo">;
+type ListVmsResponse = ApiSchema<"ListVmsResponse">;
+type ListSessionsResponse = ApiSchema<"ListSessionsResponse">;
+type VmSummary = VmInfo;
+type VmList = ListVmsResponse;
+type ForkVmResponse = ApiSchema<"ForkVmResponse">;
+type DeleteVmResponse = ApiSchema<"DeleteVmResponse">;
+type DeleteSessionResponse = ApiSchema<"DeleteSessionResponse">;
+type MountRequest = ApiSchema<"MountRequest">;
+type RunRequest = ApiSchema<"RunRequest">;
+type RunOptions = Omit<RunRequest, "command"> & {
+    /**
+     * Optional idempotency key for retrying POST /v1/vms/{id}/run.
+     * Sent as the `Idempotency-Key` HTTP header. Retries with the same
+     * key and the same semantic request return the original run; a
+     * different semantic request under the same key returns
+     * ArkerError code "conflict" with the original run_id.
+     */
+    idempotencyKey?: string;
+};
+type RunInboundPortRequest = ApiSchema<"RunInboundPortRequest">;
+type RunNetworkRequest = ApiSchema<"RunNetworkRequest">;
+type RunTunnelStatus = ApiSchema<"RunTunnelStatus">;
+type RunNetworkStatus = ApiSchema<"RunNetworkStatus">;
+type RunResponse = ApiSchema<"RunResponse">;
+type CompletedRunResponse = ApiSchema<"CompletedRunResponse">;
+type BackgroundRunResponse = ApiSchema<"BackgroundRunResponse">;
+type PtyRunResponse = ApiSchema<"PtyRunResponse">;
+type RawRunResponse = RunResponse;
+interface CompletedRunResult {
+    type: "completed";
+    completed: true;
     stdout: Uint8Array;
+    stdoutEncoding: string;
     stderr: Uint8Array;
+    stderrEncoding: string;
     exitCode: number;
-    durationMs: number;
-    sessionId: string;
-    cwd: string;
-}
-interface VmSummary {
-    vm_id: string;
-    name: string | null;
-    base_image: string;
-    region: string;
-    /** ISO 8601 UTC. */
-    created_at: string;
 }
-interface VmList {
-    items: VmSummary[];
-    /** Total matching the query, ignoring limit/offset. */
-    total: number;
+interface BackgroundRunResult {
+    type: "background";
+    completed: boolean;
+    runId: string;
+    tunnels: RunTunnelStatus[];
+    network?: RunNetworkStatus | null;
 }
-interface ListOptions {
-    limit?: number;
-    offset?: number;
-    q?: string;
-    /** `created_at` | `-created_at` | `region` | `-region`. Default `-created_at`. */
-    sort?: string;
+interface PtyRunResult {
+    type: "pty";
+    pty: true;
+    sessionId: string;
+    wsUrl: string;
 }
+type RunResult = CompletedRunResult | BackgroundRunResult | PtyRunResult;
+type RunStatusResponse = ApiSchema<"RunStatusResponse">;
+type CancelRunResponse = ApiSchema<"CancelRunResponse">;
+type CreateSessionRequest = ApiSchema<"CreateSessionRequest">;
+type ResizePtyRequest = ApiSchema<"ResizePtyRequest">;
+type ResizePtyResponse = ApiSchema<"ResizePtyResponse">;
+type ResizeRequest = ApiSchema<"ResizeRequest">;
+type ResizeResponse = ApiSchema<"ResizeResponse">;
+type SyncRequest = ApiSchema<"SyncRequest">;
+type SyncResponse = ApiSchema<"SyncResponse">;
+type SyncReadResponse = ApiSchema<"SyncReadResponse">;
+type SyncReadInlineResponse = ApiSchema<"SyncReadInlineResponse">;
+type SyncReadPresignedResponse = ApiSchema<"SyncReadPresignedResponse">;
+type SyncByteRange = ApiSchema<"SyncByteRange">;
+type ErrorResponse = ApiSchema<"ErrorResponse">;
+type SyncChunkWriteResult = ApiSchema<"SyncChunkWriteResult">;
+type SyncPresignedWriteRequestResult = ApiSchema<"SyncPresignedWriteRequestResult">;
+type SyncCommitWriteResult = ApiSchema<"SyncCommitWriteResult">;
+type SyncWriteResult = ApiSchema<"SyncWriteResult">;
+type SyncWriteResponse = ApiSchema<"SyncWriteResponse">;
 declare class ArkerError extends Error {
     readonly code: string;
     readonly status: number;
     constructor(code: string, message: string, status: number);
 }
 declare class Arker {
+    readonly baseUrl: string;
+    readonly burstBaseUrl?: string;
+    readonly region?: string;
     private readonly apiKey;
-    private readonly baseUrl;
-    constructor(opts: ArkerOptions);
-    /** @internal */
-    _request<T = any>(method: string, path: string, body?: unknown, overrideBaseUrl?: string): Promise<T>;
-    /** Open a handle to a VM by ULID *or* template name. No network call. */
+    private readonly fetchImpl;
+    private readonly retry;
+    constructor(opts?: ArkerOptions);
     vm(vmId: string): Computer;
-    /** List VMs in the caller's organization. Always hits `https://arker.ai`. */
-    list(opts?: ListOptions): Promise<VmList>;
+    goldens(): Promise<ListGoldensResponse>;
+    list(): Promise<ListVmsResponse>;
+    get(vmId: string): Promise<VmInfo>;
+    /** @internal */
+    _request<T>(method: HttpMethod, path: string, body?: unknown, baseUrl?: string, extraHeaders?: Record<string, string | undefined>): Promise<T>;
+    /** @internal */
+    _fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /** @internal */
+    _retryAttempts(): number;
+    /** @internal */
+    _retryDelay(attempt: number): number;
+    /** @internal */
+    _baseUrlFor(ref: string): string;
 }
 declare class Computer {
     readonly id: string;
+    readonly baseUrl: string;
     readonly sync: Sync;
     /** @internal */
     readonly _client: Arker;
-    constructor(client: Arker, vmId: string);
-    delete(): Promise<void>;
-    /** Fork this VM. Aliases like `"arkuntu"` resolve client-side. */
-    fork(opts?: ForkOptions): Promise<Computer>;
-    run(command: string, opts?: RunOptions): Promise<RunResult>;
+    constructor(client: Arker, vmId: string, baseUrl?: string);
+    fork(request?: ForkOptions): Promise<Computer>;
+    run(command: string, options?: RunOptions): Promise<RunResult>;
+    runStatus(runId: string): Promise<RunStatusResponse>;
+    cancelRun(runId: string): Promise<CancelRunResponse>;
+    delete(): Promise<DeleteVmResponse>;
 }
 declare class Sync {
     /** @internal */
     readonly _vm: Computer;
     constructor(vm: Computer);
-    private path;
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array | string): Promise<void>;
-    private fastPath;
-    private presignedPath;
+    private path;
+    private writeInline;
+    private writePresigned;
+    private putPresigned;
     private sendOneWrite;
 }
 
-export { ARKUNTU_POOL, Arker, ArkerError, type ArkerOptions, CHUNK_SIZE, Computer, DEFAULT_BASE_URL, type ForkOptions, LIST_BASE_URL, type ListOptions, type RunOptions, type RunResult, SOURCE_ALIASES, Sync, type VmList, type VmSummary };
+export { Arker, ArkerError, type ArkerOptions, type BackgroundRunResponse, type BackgroundRunResult, CHUNK_SIZE, type CancelRunResponse, type CompletedRunResponse, type CompletedRunResult, Computer, type CreateSessionRequest, type DeleteSessionResponse, type DeleteVmResponse, type ErrorResponse, type ForkOptions, type ForkRequest, type ForkVmResponse, type GoldenInfo, type ListGoldensResponse, type ListSessionsResponse, type ListVmsResponse, type MountRequest, type NetworkPolicy, type NetworkPolicyInput, type PtyRunResponse, type PtyRunResult, type RawRunResponse, type ResizePtyRequest, type ResizePtyResponse, type ResizeRequest, type ResizeResponse, type RetryOptions, type RunInboundPortRequest, type RunNetworkRequest, type RunNetworkStatus, type RunOptions, type RunRequest, type RunResponse, type RunResult, type RunStatusResponse, type RunTunnelStatus, type SessionInfo, Sync, type SyncByteRange, type SyncChunkWriteResult, type SyncCommitWriteResult, type SyncPresignedWriteRequestResult, type SyncReadInlineResponse, type SyncReadPresignedResponse, type SyncReadResponse, type SyncRequest, type SyncResponse, type SyncWriteResponse, type SyncWriteResult, type VmInfo, type VmList, type VmSummary };