@arker-ai/sdk 0.5.2 → 0.6.3

package/dist/index.d.cts

@@ -7,6 +7,7 @@ interface components {
         ErrorCode: "unsupported_operation" | "bad_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "payload_too_large" | "not_implemented" | "resource_pressure" | "internal" | "unavailable" | "network_error";
         ErrorResponse: {
             code: components["schemas"]["ErrorCode"];
+            /** @description Human-readable, client-safe error message. For `code: "internal"`, this is intentionally generic; server logs retain the underlying cause. */
             message: string;
         };
         /**
@@ -26,34 +27,26 @@ interface components {
          * @enum {string}
          */
         RunState: "running" | "completed" | "failed" | "cancelled";
-        /**
-         * @description `starting` = backend is allocating the tunnel; `open` = accepting
-         *     connections; `closed` = torn down or never came up.
-         * @enum {string}
-         */
-        TunnelState: "starting" | "open" | "closed";
         /** @enum {string} */
         ResourceKind: "cpu" | "memory" | "disk";
-        NetworkPolicy: components["schemas"]["NetworkPolicyOpen"] | components["schemas"]["NetworkPolicyBlocked"] | components["schemas"]["NetworkPolicyAllow"] | components["schemas"]["NetworkPolicyBlock"];
-        NetworkPolicyOpen: {
+        /** @description Outbound egress policy stored on the VM. */
+        NetworkPolicy: {
             /** @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"];
+        /** @description Outbound egress policy input. `true`/`open` means unrestricted; `false`/`blocked`/`none` means deny all. */
+        NetworkPolicyInput: boolean | ("open" | "blocked" | "true" | "false" | "none") | components["schemas"]["NetworkPolicy"];
         ForkRequest: {
             /** @description Global VM identifier. Org is inferred from the row. */
             source_vm_id?: string | null;
@@ -65,16 +58,14 @@ interface components {
             name?: string | null;
             /** @description Make the new VM publicly forkable from other orgs. */
             public?: boolean | 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 Inbound reachability and SSH authorized keys for the new VM. */
+            network?: components["schemas"]["NetworkInput"] | null;
+            /** @description Outbound egress policy for the new VM. Omit to inherit from the source VM, or default to open for image-created VMs with no source. */
+            egress?: components["schemas"]["NetworkPolicyInput"] | null;
+            disk?: boolean | null;
             durable?: boolean | null;
-            /** @description Optional VM-scoped tunnel customization. Omitting it allocates an open any-port tunnel where supported. */
-            tunnel?: components["schemas"]["TunnelRequest"] | null;
+            /** @description Resource shape for the new VM. */
+            resources?: components["schemas"]["VmResources"] | null;
         };
         Session: {
             session_id: string;
@@ -116,21 +107,25 @@ interface components {
             /** @enum {string|null} */
             provider?: "aws" | "aws-burst" | null;
             started_at?: string | null;
-            vcpu_count?: number | null;
-            memory_mib?: number | null;
-            disk_mib?: number | null;
-            /** @description Effective VM fork-time egress policy. */
-            network?: components["schemas"]["NetworkPolicy"];
+            /** @description Inbound reachability settings for this VM. */
+            network: components["schemas"]["VmNetwork"];
+            /** @description Outbound egress policy for this VM. */
+            egress?: components["schemas"]["NetworkPolicy"] | null;
             /** @description Hard vCPU ceiling for a fork of this VM (KVM slot count). Requesting more fails the run. */
             max_vcpus?: number | null;
+            /** @description Smallest vCPU count accepted for this VM. */
+            min_vcpus?: number | null;
             /** @description Hard memory ceiling (MiB) a fork can hotplug up to. */
             max_memory_mib?: number | null;
             /** @description Non-hotpluggable base memory (MiB). */
             min_memory_mib?: number | null;
-            /** @description Worker host that owns this VM. Used by routers to populate caches without a fresh PlanetScale lookup. */
-            worker_id?: string | null;
+            /** @description Smallest disk size (MiB) accepted for this VM. `0` means nodisk. */
+            min_disk_mib?: number | null;
+            /** @description Largest disk size (MiB) accepted for this VM. `0` means nodisk. */
+            max_disk_mib?: number | null;
             sessions: components["schemas"]["Session"][];
-            tunnels?: components["schemas"]["Tunnel"][];
+            /** @description Current VM resource allocation. */
+            resources: components["schemas"]["VmResources"];
         };
         ListVmsResponse: {
             vms: components["schemas"]["Vm"][];
@@ -203,6 +198,12 @@ interface components {
             stderr_encoding: string;
             exit_code: number;
             dispatch?: string | null;
+            /** @description ARK-107: requested total memory (MiB) when this run carried an explicit memory override. Absent when the run had no memory override. */
+            memory_requested_mib?: number | null;
+            /** @description ARK-107: achieved total memory (MiB) after the run's resize. Memory shrink is best-effort, so this can exceed memory_requested_mib when guest pages are pinned. Absent when the run had no memory override. */
+            memory_achieved_mib?: number | null;
+            /** @description ARK-107: true when the run's memory shrink was partial (achieved differs from requested beyond the virtio-mem block granularity). The command still ran at the achieved footprint (best-effort); this flags the gap instead of a silent success. Defaults false. */
+            memory_partial?: boolean;
         };
         BackgroundRunResponse: {
             run_id: string;
@@ -310,41 +311,6 @@ interface components {
             protocol: string;
             url?: string | null;
         };
-        Tunnel: {
-            /** @description The VM this tunnel belongs to. Always populated so flat tunnel listings work without restructuring. */
-            vm_id: string;
-            /** @description Unique-per-VM identifier. */
-            port: number;
-            /** @description The Run that opened this tunnel, if any. VM-scoped tunnels created at fork time or via `POST /vms/{id}/tunnels` have `run_id: null`. */
-            run_id?: string | null;
-            visibility: string;
-            protocol: string;
-            url?: string | null;
-            state: components["schemas"]["TunnelState"];
-            message?: string | null;
-            started_at?: string | null;
-            vm_name?: string | null;
-            source_org_id?: string | null;
-            region?: string | null;
-            /** @enum {string|null} */
-            provider?: "aws" | "aws-burst" | null;
-            /** @description Recoverable tunnel identity embedded in URLs (`p{port}-{key}`). Not a secret. Present on VM-scoped tunnel responses. */
-            tunnel_key?: string | null;
-            /**
-             * @description `open` or `authenticated` for VM-scoped tunnels.
-             * @enum {string|null}
-             */
-            auth_mode?: "open" | "authenticated" | null;
-            /** @description One-time bearer secret returned only when allocating an authenticated tunnel; never echoed on listings. */
-            auth_token?: string | null;
-        };
-        ListTunnelsResponse: {
-            tunnels: components["schemas"]["Tunnel"][];
-            next_cursor?: string | null;
-        };
-        DeleteTunnelResponse: {
-            deleted: boolean;
-        };
         CancelRunResponse: {
             cancelled: boolean;
         };
@@ -354,14 +320,6 @@ interface components {
             } | null;
             cwd?: string | null;
         };
-        ResizeRequest: {
-            vcpu_count?: number | null;
-            memory_mib?: number | null;
-            disk_mib?: number | null;
-        };
-        ResizeResponse: {
-            resized: boolean;
-        };
         Sync: {
             sync_id: string;
             vm_id: string;
@@ -489,18 +447,31 @@ interface components {
         FilesystemCreateRequest: {
             name: string;
         };
-        TunnelRequest: {
-            /**
-             * @description Allowed VM ports for this tunnel. Omitted, null, or empty means any port.
-             * @default []
-             */
-            ports?: number[] | null;
-            /**
-             * @description `open` allows unauthenticated tunnel requests. `authenticated` returns a one-time bearer `auth_token` and requires it on tunnel requests.
-             * @default open
-             * @enum {string|null}
-             */
-            auth_mode?: "open" | "authenticated" | null;
+        VmResources: {
+            vcpu?: number | null;
+            memory_mib?: number | null;
+            disk_mib?: number | null;
+        };
+        NetworkInput: {
+            /** @description Enable inbound reachability for this VM. Defaults to false. */
+            reachable?: boolean | null;
+            /** @description OpenSSH public keys authorized for terminator auth and in-VM sshd injection. */
+            ssh_public_keys?: string[];
+        };
+        SshPublicKeyInfo: {
+            public_key: string;
+            fingerprint: string;
+        };
+        VmNetwork: {
+            reachable: boolean;
+            /** @description Stable per-VM hostname, present when reachable is true. */
+            hostname?: string | null;
+            /** @description Authorized SSH keys with fingerprints. Returned by GET /v1/vms/{id}; omitted from list responses when empty. */
+            ssh_public_keys?: components["schemas"]["SshPublicKeyInfo"][];
+        };
+        PatchVmRequest: {
+            resources?: components["schemas"]["VmResources"] | null;
+            network?: components["schemas"]["NetworkInput"] | null;
         };
     };
     responses: {
@@ -533,8 +504,6 @@ interface components {
         Cursor: string | null;
         /** @description Max items per page. Backend caps may apply. */
         Limit: number;
-        /** @description Recoverable tunnel identity returned as `Tunnel.tunnel_key` and embedded in tunnel URLs. */
-        TunnelKey: string;
     };
     requestBodies: never;
     headers: never;
@@ -559,7 +528,7 @@ declare const CHUNK_SIZE: number;
  */
 declare const ARKER_ORG_ID = "ArkerHQ";
 type FetchLike = typeof fetch;
-type HttpMethod = "GET" | "POST" | "DELETE";
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
 interface RetryOptions {
     attempts?: number;
     baseDelayMs?: number;
@@ -592,13 +561,15 @@ interface ArkerOptions {
 type VmState = ApiSchema<"VmState">;
 type SessionState = ApiSchema<"SessionState">;
 type RunState = ApiSchema<"RunState">;
-type TunnelState = ApiSchema<"TunnelState">;
 type ResourceKind = ApiSchema<"ResourceKind">;
 type ErrorCode = ApiSchema<"ErrorCode">;
 type NetworkPolicy = ApiSchema<"NetworkPolicy">;
 type NetworkPolicyInput = ApiSchema<"NetworkPolicyInput">;
 type ForkRequest = ApiSchema<"ForkRequest">;
 type ForkOptions = ForkRequest;
+type VmResources = ApiSchema<"VmResources">;
+type VmNetwork = ApiSchema<"VmNetwork">;
+type NetworkInput = ApiSchema<"NetworkInput">;
 type Session = ApiSchema<"Session">;
 type Vm = ApiSchema<"Vm">;
 type ListVmsResponse = ApiSchema<"ListVmsResponse">;
@@ -634,10 +605,6 @@ type RunOptions = Partial<Omit<RunRequest, "command">> & {
 };
 type InboundPortRequest = ApiSchema<"InboundPortRequest">;
 type NetworkRequest = ApiSchema<"NetworkRequest">;
-type TunnelRequest = ApiSchema<"TunnelRequest">;
-type Tunnel = ApiSchema<"Tunnel">;
-type ListTunnelsResponse = ApiSchema<"ListTunnelsResponse">;
-type DeleteTunnelResponse = ApiSchema<"DeleteTunnelResponse">;
 type NetworkStatus = ApiSchema<"NetworkStatus">;
 type RunResponse = ApiSchema<"RunResponse">;
 type CompletedRunResponse = ApiSchema<"CompletedRunResponse">;
@@ -650,8 +617,7 @@ type ListOrgRunsResponse = ApiSchema<"ListOrgRunsResponse">;
 type RunListRow = OrgRunListRow;
 type CancelRunResponse = ApiSchema<"CancelRunResponse">;
 type CreateSessionRequest = ApiSchema<"CreateSessionRequest">;
-type ResizeRequest = ApiSchema<"ResizeRequest">;
-type ResizeResponse = ApiSchema<"ResizeResponse">;
+type PatchVmRequest = ApiSchema<"PatchVmRequest">;
 type ErrorResponse = ApiSchema<"ErrorResponse">;
 /** @deprecated Use `Session`. */
 type SessionInfo = Session;
@@ -663,8 +629,6 @@ type RunNetworkRequest = NetworkRequest;
 type RunNetworkStatus = NetworkStatus;
 /** @deprecated Use `InboundPortRequest`. */
 type RunInboundPortRequest = InboundPortRequest;
-/** @deprecated Use `Tunnel`. */
-type RunTunnelStatus = Tunnel;
 interface CompletedRunResult {
     type: "completed";
     /** The run's own id. Present for executed runs; absent for operation acks. */
@@ -679,6 +643,12 @@ interface CompletedRunResult {
     /** System failure explanation when `state` is "failed". Distinct from
      * `stderr` (the program's own error output); null otherwise. */
     failReason?: string | null;
+    /** Requested total memory (MiB), present when the run carried a memory override. */
+    memoryRequestedMib?: number | null;
+    /** Achieved total memory (MiB) after the run's resize. */
+    memoryAchievedMib?: number | null;
+    /** True when the runtime could not reach the requested memory target exactly. */
+    memoryPartial?: boolean;
 }
 interface BackgroundRunResult {
     type: "background";
@@ -708,6 +678,56 @@ interface ListOrgRunsOptions {
     sort?: "when" | "status" | "path" | "total" | "queue" | "your_code" | "runtime";
     dir?: "asc" | "desc";
 }
+type PtyInput = string | Uint8Array | ArrayBuffer;
+interface PtyConnectOptions {
+    /** Existing session to attach. Omit to create a new session first. */
+    sessionId?: string;
+    cols?: number;
+    rows?: number;
+    command?: string;
+    /** Defaults to the backend's persistent detach semantics. */
+    persist?: boolean;
+    /**
+     * Auto-cancel the PTY run after this many seconds with no terminal I/O. When
+     * the window elapses the server completes the underlying run and DESTROYS the
+     * shell (not just a detach) — a reconnect to the same `sessionId` starts
+     * fresh. Unset (default) means no auto-cancel.
+     */
+    cancelTtlSecs?: number;
+    /** @internal Test/runtime override for browser-ticket vs Node-header auth. */
+    useTicket?: boolean;
+    /** @internal Test/runtime override for WebSocket construction. */
+    webSocketFactory?: PtyWebSocketFactory;
+}
+interface PtyCloseEvent {
+    code?: number;
+    reason?: string;
+}
+interface PtyConnection {
+    readonly sessionId: string;
+    readonly ready: Promise<void>;
+    onData(listener: (data: Uint8Array) => void): () => void;
+    onClose(listener: (event: PtyCloseEvent) => void): () => void;
+    onError(listener: (error: unknown) => void): () => void;
+    send(data: PtyInput): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    close(code?: number, reason?: string): void;
+}
+interface PtyWebSocketFactoryInit {
+    headers?: Record<string, string>;
+}
+type PtyWebSocketFactory = (url: string, init: PtyWebSocketFactoryInit) => PtyWebSocketLike | Promise<PtyWebSocketLike>;
+interface PtyWebSocketLike {
+    binaryType?: string;
+    readyState?: number;
+    send(data: string | Uint8Array | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?: (type: string, listener: (event: unknown) => void) => void;
+    removeEventListener?: (type: string, listener: (event: unknown) => void) => void;
+    on?: (type: string, listener: (...args: unknown[]) => void) => void;
+    off?: (type: string, listener: (...args: unknown[]) => void) => void;
+}
 declare class ArkerError extends Error {
     readonly code: string;
     readonly status: number;
@@ -806,6 +826,8 @@ declare class Arker {
     /** @internal */
     _retryDelay(attempt: number): number;
     /** @internal */
+    _authHeaders(): Record<string, string>;
+    /** @internal */
     _baseUrlFor(ref: string): string;
 }
 interface ListOpts {
@@ -837,7 +859,6 @@ declare class VM {
     readonly root_source_vm_name?: string | null;
     readonly worker_id?: string | null;
     readonly sessions?: Session[];
-    readonly tunnels?: Tunnel[];
     constructor(client: Arker, vmId: string, baseUrl?: string, data?: Vm);
     /** Re-fetch this VM and return a fresh, fully-populated handle. */
     refresh(): Promise<VM>;
@@ -866,7 +887,15 @@ declare class VM {
     private syncWritePresigned;
     private putPresigned;
     private sendOneWrite;
-    resize(request: ResizeRequest): Promise<ResizeResponse>;
+    /**
+     * Update this VM's resource allocation and/or network settings via
+     * `PATCH /v1/vms/{id}`. Returns the updated `Vm`.
+     *
+     * Accepts either a `PatchVmRequest` (`{ resources, network }`) or, for
+     * convenience, flat resource fields (`{ vcpu, memory_mib, disk_mib }`)
+     * which are folded into `resources`.
+     */
+    resize(request: PatchVmRequest | (VmResources & Pick<PatchVmRequest, "network">)): Promise<Vm>;
     delete(): Promise<DeleteVmResponse>;
     listSyncs(opts?: ListOpts & {
         filesystemId?: string;
@@ -890,12 +919,7 @@ declare class VM {
     createSession(request?: CreateSessionRequest): Promise<Session>;
     getSession(sessionId: string): Promise<Session>;
     deleteSession(sessionId: string): Promise<DeleteSessionResponse>;
-    listTunnels(opts?: ListOpts & {
-        state?: TunnelState;
-    }): Promise<ListTunnelsResponse>;
-    createTunnel(request?: TunnelRequest): Promise<Tunnel>;
-    getTunnel(key: string): Promise<Tunnel>;
-    deleteTunnel(key: string): Promise<DeleteTunnelResponse>;
+    connectPty(options?: PtyConnectOptions): Promise<PtyConnection>;
 }
 
-export { ARKER_ORG_ID, Arker, ArkerError, type ArkerOptions, type BackgroundRunResponse, type BackgroundRunResult, CHUNK_SIZE, type CancelRunResponse, type CompletedRunResponse, type CompletedRunResult, type CreateSessionRequest, type DeleteFilesystemResponse, type DeleteSessionResponse, type DeleteSyncResponse, type DeleteTunnelResponse, type DeleteVmResponse, type ErrorCode, type ErrorResponse, type Filesystem, type FilesystemCreateRequest, type ForkOptions, type ForkRequest, type ForkSource, type InboundPortRequest, type ListFilesystemsResponse, type ListOpts, type ListOrgRunsOptions, type ListOrgRunsResponse, type ListRunsResponse, type ListSessionsResponse, type ListSyncsResponse, type ListTunnelsResponse, type ListVmsResponse, type NetworkPolicy, type NetworkPolicyInput, type NetworkRequest, type NetworkStatus, type OrgRunListRow, type ResizeRequest, type ResizeResponse, type ResourceKind, type RetryOptions, type Run, type RunInboundPortRequest, type RunListRow, type RunNetworkRequest, type RunNetworkStatus, type RunOptions, type RunRequest, type RunResponse, type RunResult, type RunState, type RunStatusResponse, type RunSummary, type RunTunnelStatus, type Session, type SessionInfo, type SessionState, type Sync, type SyncByteRange, type SyncChunkWriteResult, type SyncCommitWriteResult, type SyncCreateRequest, type SyncPresignedWriteRequestResult, type SyncReadInlineResponse, type SyncReadPresignedResponse, type SyncReadRequest, type SyncReadResponse, type SyncWriteRequest, type SyncWriteResponse, type SyncWriteResult, type Tunnel, type TunnelRequest, type TunnelState, VM, type Vm, type VmState };
+export { ARKER_ORG_ID, Arker, ArkerError, type ArkerOptions, type BackgroundRunResponse, type BackgroundRunResult, CHUNK_SIZE, type CancelRunResponse, type CompletedRunResponse, type CompletedRunResult, type CreateSessionRequest, type DeleteFilesystemResponse, type DeleteSessionResponse, type DeleteSyncResponse, type DeleteVmResponse, type ErrorCode, type ErrorResponse, type Filesystem, type FilesystemCreateRequest, type ForkOptions, type ForkRequest, type ForkSource, type InboundPortRequest, type ListFilesystemsResponse, type ListOpts, type ListOrgRunsOptions, type ListOrgRunsResponse, type ListRunsResponse, type ListSessionsResponse, type ListSyncsResponse, type ListVmsResponse, type NetworkInput, type NetworkPolicy, type NetworkPolicyInput, type NetworkRequest, type NetworkStatus, type OrgRunListRow, type PatchVmRequest, type PtyCloseEvent, type PtyConnectOptions, type PtyConnection, type PtyInput, type PtyWebSocketFactory, type ResourceKind, type RetryOptions, type Run, type RunInboundPortRequest, type RunListRow, type RunNetworkRequest, type RunNetworkStatus, type RunOptions, type RunRequest, type RunResponse, type RunResult, type RunState, type RunStatusResponse, type RunSummary, type Session, type SessionInfo, type SessionState, type Sync, type SyncByteRange, type SyncChunkWriteResult, type SyncCommitWriteResult, type SyncCreateRequest, type SyncPresignedWriteRequestResult, type SyncReadInlineResponse, type SyncReadPresignedResponse, type SyncReadRequest, type SyncReadResponse, type SyncWriteRequest, type SyncWriteResponse, type SyncWriteResult, VM, type Vm, type VmNetwork, type VmResources, type VmState };