@brimble/sandbox 0.1.0

package/dist/src/transport/http.js

@@ -0,0 +1,354 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransport = void 0;
+const constants_1 = require("../constants");
+const errors_1 = require("../errors");
+const auth_1 = require("./auth");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function hasMessage(value) {
+    return isRecord(value) && typeof value.message === 'string';
+}
+function isEnvelope(value) {
+    return hasMessage(value);
+}
+function maybeJoinSignal(signal, timeoutMs) {
+    if (!signal) {
+        return { signal: AbortSignal.timeout(timeoutMs), cleanup: () => { } };
+    }
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => {
+        timeoutController.abort(new DOMException('The operation timed out.', 'AbortError'));
+    }, timeoutMs);
+    const mergedController = new AbortController();
+    const onCallerAbort = () => {
+        mergedController.abort(signal.reason);
+    };
+    const onTimeoutAbort = () => {
+        mergedController.abort(timeoutController.signal.reason);
+    };
+    if (signal.aborted) {
+        mergedController.abort(signal.reason);
+    }
+    else {
+        signal.addEventListener('abort', onCallerAbort, { once: true });
+    }
+    timeoutController.signal.addEventListener('abort', onTimeoutAbort, { once: true });
+    const cleanup = () => {
+        clearTimeout(timeoutId);
+        signal.removeEventListener('abort', onCallerAbort);
+        timeoutController.signal.removeEventListener('abort', onTimeoutAbort);
+    };
+    return { signal: mergedController.signal, cleanup };
+}
+async function parseResponseBody(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+        return response.json();
+    }
+    const text = await response.text();
+    return text.length > 0 ? text : null;
+}
+function buildUrl(baseUrl, endpoint, query) {
+    const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    const normalizedPath = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    const url = new URL(`${normalizedBaseUrl}${normalizedPath}`);
+    if (query) {
+        url.search = query.toString();
+    }
+    return url.toString();
+}
+function normalizeRetryConfig(retry) {
+    return {
+        maxAttempts: Math.max(1, retry?.maxAttempts ?? constants_1.DEFAULT_RETRY_MAX_ATTEMPTS),
+        baseDelayMs: Math.max(0, retry?.baseDelayMs ?? constants_1.DEFAULT_RETRY_BASE_DELAY_MS),
+        maxDelayMs: Math.max(0, retry?.maxDelayMs ?? constants_1.DEFAULT_RETRY_MAX_DELAY_MS),
+        retryStatuses: retry?.retryStatuses ?? [...constants_1.DEFAULT_RETRY_STATUSES],
+        retryMethods: retry?.retryMethods ?? ['GET', 'DELETE', 'PUT'],
+    };
+}
+function mergeRetryConfig(base, override) {
+    if (override === false) {
+        return {
+            ...base,
+            maxAttempts: 1,
+        };
+    }
+    if (!override) {
+        return base;
+    }
+    return normalizeRetryConfig({
+        maxAttempts: override.maxAttempts ?? base.maxAttempts,
+        baseDelayMs: override.baseDelayMs ?? base.baseDelayMs,
+        maxDelayMs: override.maxDelayMs ?? base.maxDelayMs,
+        retryStatuses: override.retryStatuses ?? base.retryStatuses,
+        retryMethods: override.retryMethods ?? base.retryMethods,
+    });
+}
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === 'AbortError';
+}
+function canRetryByMethod(method, retryMethods, idempotencyKey) {
+    if (retryMethods.includes(method)) {
+        return true;
+    }
+    if (method === 'POST' && idempotencyKey) {
+        return true;
+    }
+    return false;
+}
+function canRetryBody(body) {
+    if (!body) {
+        return true;
+    }
+    if (typeof body === 'string') {
+        return true;
+    }
+    if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+        return true;
+    }
+    return false;
+}
+function computeRetryDelayMs(attempt, baseDelayMs, maxDelayMs) {
+    const exponent = Math.max(0, attempt - 1);
+    const delayMs = baseDelayMs * (2 ** exponent);
+    return Math.min(maxDelayMs, delayMs);
+}
+async function sleep(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function parseRetryAfterSeconds(value) {
+    if (!value) {
+        return null;
+    }
+    const asNumber = Number(value);
+    if (Number.isFinite(asNumber)) {
+        return asNumber;
+    }
+    return null;
+}
+function getRequestId(response) {
+    return response.headers.get('x-request-id') ?? response.headers.get('x-correlation-id') ?? null;
+}
+class HttpTransport {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    fetchImpl;
+    retry;
+    /** Create a transport used by all SDK resources. */
+    constructor(config) {
+        this.baseUrl = config.baseUrl;
+        this.apiKey = config.apiKey;
+        this.timeoutMs = config.timeoutMs ?? constants_1.DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
+        this.retry = normalizeRetryConfig(config.retry);
+    }
+    /**
+     * Send a JSON request and return the unwrapped `data` payload.
+     * If the endpoint returns 204, this resolves to `undefined`.
+     */
+    async requestJson(args) {
+        const headers = args.body !== undefined ? { 'content-type': 'application/json', ...(args.headers ?? {}) } : args.headers;
+        const response = await this.executeRequest({
+            endpoint: args.endpoint,
+            method: args.method,
+            query: args.query,
+            body: args.body !== undefined ? JSON.stringify(args.body) : undefined,
+            headers,
+            signal: args.signal,
+            timeoutMs: args.timeoutMs,
+            idempotencyKey: args.idempotencyKey,
+            retry: args.retry,
+        });
+        if (response.status === 204) {
+            return undefined;
+        }
+        const payload = await parseResponseBody(response);
+        if (!response.ok) {
+            throw this.toApiError(response, args.method, args.endpoint, payload);
+        }
+        if (isEnvelope(payload)) {
+            if ('data' in payload) {
+                return payload.data;
+            }
+            return payload;
+        }
+        return payload;
+    }
+    /**
+     * Send a binary upload request (for file writes).
+     * Returns when the API acknowledges success.
+     */
+    async requestBinary(args) {
+        const response = await this.executeRequest({
+            endpoint: args.endpoint,
+            method: args.method,
+            query: args.query,
+            body: args.body,
+            headers: args.headers,
+            signal: args.signal,
+            timeoutMs: args.timeoutMs,
+            idempotencyKey: args.idempotencyKey,
+            retry: args.retry,
+        });
+        if (response.ok || response.status === 204) {
+            return;
+        }
+        const payload = await parseResponseBody(response);
+        throw this.toApiError(response, args.method, args.endpoint, payload);
+    }
+    /**
+     * Send a JSON request and return the raw response stream.
+     * Used for endpoints that stream SSE frames (`text/event-stream`).
+     */
+    async requestJsonStream(args) {
+        const headers = args.body !== undefined ? { 'content-type': 'application/json', ...(args.headers ?? {}) } : args.headers;
+        const response = await this.executeRequest({
+            endpoint: args.endpoint,
+            method: args.method,
+            query: args.query,
+            body: args.body !== undefined ? JSON.stringify(args.body) : undefined,
+            headers,
+            signal: args.signal,
+            timeoutMs: args.timeoutMs,
+            idempotencyKey: args.idempotencyKey,
+            retry: args.retry,
+        });
+        if (!response.ok) {
+            const payload = await parseResponseBody(response);
+            throw this.toApiError(response, args.method, args.endpoint, payload);
+        }
+        if (!response.body) {
+            throw new errors_1.SandboxApiError({
+                status: response.status,
+                message: 'Expected a response stream but received an empty body',
+                endpoint: `${args.method} ${args.endpoint}`,
+                responseBody: null,
+                requestId: getRequestId(response),
+            });
+        }
+        return response.body;
+    }
+    /**
+     * Request a binary response stream (for file downloads).
+     * Throws if the API returns an error status.
+     */
+    async requestStream(args) {
+        const response = await this.executeRequest({
+            endpoint: args.endpoint,
+            method: args.method,
+            query: args.query,
+            signal: args.signal,
+            timeoutMs: args.timeoutMs,
+            idempotencyKey: args.idempotencyKey,
+            retry: args.retry,
+        });
+        if (!response.ok) {
+            const payload = await parseResponseBody(response);
+            throw this.toApiError(response, args.method, args.endpoint, payload);
+        }
+        if (!response.body) {
+            throw new errors_1.SandboxApiError({
+                status: response.status,
+                message: 'Expected a response stream but received an empty body',
+                endpoint: `${args.method} ${args.endpoint}`,
+                responseBody: null,
+                requestId: getRequestId(response),
+            });
+        }
+        return response.body;
+    }
+    async executeRequest(args) {
+        const timeoutMs = args.timeoutMs ?? this.timeoutMs;
+        const retryConfig = mergeRetryConfig(this.retry, args.retry);
+        const canRetryMethod = canRetryByMethod(args.method, retryConfig.retryMethods, args.idempotencyKey);
+        const replayableBody = canRetryBody(args.body);
+        let lastError;
+        for (let attempt = 1; attempt <= retryConfig.maxAttempts; attempt += 1) {
+            const { signal, cleanup } = maybeJoinSignal(args.signal, timeoutMs);
+            try {
+                const response = await this.fetchImpl(buildUrl(this.baseUrl, args.endpoint, args.query), {
+                    method: args.method,
+                    headers: {
+                        'x-brimble-key': (0, auth_1.buildApiKeyHeader)(this.apiKey),
+                        source: 'sdk-package',
+                        'source-version': constants_1.SDK_PACKAGE_VERSION,
+                        ...(args.idempotencyKey ? { 'idempotency-key': args.idempotencyKey } : {}),
+                        ...(args.headers ?? {}),
+                    },
+                    body: args.body,
+                    signal,
+                });
+                const shouldRetry = attempt < retryConfig.maxAttempts &&
+                    canRetryMethod &&
+                    replayableBody &&
+                    retryConfig.retryStatuses.includes(response.status) &&
+                    !signal.aborted;
+                if (shouldRetry) {
+                    await sleep(computeRetryDelayMs(attempt, retryConfig.baseDelayMs, retryConfig.maxDelayMs));
+                    continue;
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                const shouldRetry = attempt < retryConfig.maxAttempts &&
+                    canRetryMethod &&
+                    replayableBody &&
+                    !isAbortError(error) &&
+                    !(args.signal?.aborted ?? false);
+                if (!shouldRetry) {
+                    throw error;
+                }
+                await sleep(computeRetryDelayMs(attempt, retryConfig.baseDelayMs, retryConfig.maxDelayMs));
+            }
+            finally {
+                cleanup();
+            }
+        }
+        if (lastError) {
+            throw lastError;
+        }
+        throw new Error('HTTP request failed before receiving a response.');
+    }
+    toApiError(response, method, endpoint, responseBody) {
+        let message = response.statusText || 'Sandbox API request failed';
+        if (hasMessage(responseBody)) {
+            message = responseBody.message;
+        }
+        else if (typeof responseBody === 'string' && responseBody.trim().length > 0) {
+            message = responseBody;
+        }
+        const baseArgs = {
+            status: response.status,
+            message,
+            endpoint: `${method} ${endpoint}`,
+            responseBody,
+            requestId: getRequestId(response),
+        };
+        if (response.status === 401 || response.status === 403) {
+            return new errors_1.AuthError(baseArgs);
+        }
+        if (response.status === 400 || response.status === 422) {
+            return new errors_1.ValidationError(baseArgs);
+        }
+        if (response.status === 404) {
+            return new errors_1.NotFoundError(baseArgs);
+        }
+        if (response.status === 429) {
+            return new errors_1.RateLimitError({
+                ...baseArgs,
+                retryAfterSeconds: parseRetryAfterSeconds(response.headers.get('retry-after')),
+            });
+        }
+        return new errors_1.SandboxApiError(baseArgs);
+    }
+}
+exports.HttpTransport = HttpTransport;

package/dist/src/transport/pagination.d.ts

@@ -0,0 +1,3 @@
+import type { Pagination } from '../types';
+/** Convert pagination inputs into query params with sensible defaults. */
+export declare function toPaginationQuery(pagination?: Pagination): URLSearchParams;

package/dist/src/transport/pagination.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPaginationQuery = toPaginationQuery;
+const constants_1 = require("../constants");
+/** Convert pagination inputs into query params with sensible defaults. */
+function toPaginationQuery(pagination = {}) {
+    const params = new URLSearchParams();
+    params.set('page', String(pagination.page ?? constants_1.DEFAULT_PAGE));
+    params.set('limit', String(pagination.limit ?? constants_1.DEFAULT_PAGE_LIMIT));
+    return params;
+}

package/dist/src/types/exec.d.ts

@@ -0,0 +1,34 @@
+import { CodeLanguage } from '../enums';
+export type ExecInput = {
+    cmd: string;
+    timeout_seconds?: number;
+    cwd?: string;
+    stream?: boolean;
+};
+export type CodeInput = {
+    language: CodeLanguage;
+    code: string;
+    timeout_seconds?: number;
+    cwd?: string;
+    stream?: boolean;
+};
+export type ExecResult = {
+    stdout: string;
+    stderr: string;
+    exit_code: number;
+    duration_ms: number;
+};
+export type ExecStreamFrame = {
+    type: 'stdout';
+    data: string;
+} | {
+    type: 'stderr';
+    data: string;
+} | {
+    type: 'done';
+    exit_code: number;
+    duration_ms: number;
+} | {
+    type: 'error';
+    message: string;
+};

package/dist/src/types/exec.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/files.d.ts

@@ -0,0 +1 @@
+export type FileUploadBody = ReadableStream<Uint8Array> | Buffer | Uint8Array;

package/dist/src/types/files.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/index.d.ts

@@ -0,0 +1,9 @@
+export type { CodeInput, ExecInput, ExecResult, ExecStreamFrame } from './exec';
+export type { FileUploadBody } from './files';
+export type { Paginated, Pagination, TeamScopedPagination } from './pagination';
+export type { RegionSummary, SandboxRegion, SandboxRegionsResult } from './region';
+export type { AckMessage, CreateSandboxInput, CreateSandboxRequest, CreateSandboxResult, CreateSandboxWithVolumeInput, CreateSandboxWithVolumeResult, Sandbox, SandboxReadyRequestOptions, SandboxRegionInput, SandboxRuntimeOptions, SandboxSpecs, WaitPreference, WaitUntilReadyOptions, } from './sandbox';
+export type { CreateSnapshotInput, Snapshot } from './snapshot';
+export type { Stats, StatsAverageNetwork, StatsAverageNumeric, StatsQuery, StatsTimelinePoint } from './stats';
+export type { SandboxTemplate } from './template';
+export type { CreateVolumeInput, Volume } from './volume';

package/dist/src/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/pagination.d.ts

@@ -0,0 +1,14 @@
+export type Pagination = {
+    page?: number;
+    limit?: number;
+};
+export type TeamScopedPagination = Pagination & {
+    teamId?: string;
+};
+export type Paginated<T> = {
+    data: T[];
+    totalCount: number;
+    currentPage: number;
+    totalPages: number;
+    limit: number;
+};

package/dist/src/types/pagination.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/region.d.ts

@@ -0,0 +1,17 @@
+export type RegionSummary = {
+    id: string;
+    name: string;
+    country: string;
+    continent: string | null;
+    provider: string;
+    is_paid: boolean;
+};
+export type SandboxRegion = {
+    id: string;
+    name: string;
+    country: string;
+    continent: string | null;
+};
+export type SandboxRegionsResult = {
+    regions: SandboxRegion[];
+};

package/dist/src/types/region.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/sandbox.d.ts

@@ -0,0 +1,90 @@
+import { DestroyReason, DestroyTimeout, SandboxStatus, SnapshotMode } from '../enums';
+import type { RequestOptions } from '../transport/http';
+import type { RegionSummary } from './region';
+import type { CreateVolumeInput, Volume } from './volume';
+export type SandboxSpecs = {
+    cpu?: number;
+    memory?: number;
+    disk?: number;
+};
+export type SandboxRegionInput = string | 'auto';
+export type CreateSandboxInput = {
+    name?: string;
+    template?: string;
+    teamId?: string;
+    environmentId?: string;
+    region?: string;
+    specs?: SandboxSpecs;
+    autoDestroy?: boolean;
+    destroyTimeout?: DestroyTimeout;
+    oneShot?: boolean;
+    blockOutbound?: boolean;
+    persistent?: boolean;
+    persistentDiskGB?: number;
+    volumeId?: string;
+    fromSnapshot?: string;
+    snapshotMode?: SnapshotMode;
+    snapshotFrequency?: string;
+};
+export type CreateSandboxRequest = Omit<CreateSandboxInput, 'region'> & {
+    region?: SandboxRegionInput;
+};
+export type CreateSandboxResult = {
+    id: string;
+    name: string;
+    template: string;
+    status: SandboxStatus;
+    created_at: string;
+    expires_at: string;
+};
+export type Sandbox = {
+    id: string;
+    name: string;
+    template: string;
+    status: SandboxStatus;
+    region: RegionSummary | string;
+    specs: SandboxSpecs;
+    team: string | null;
+    project_environment: string | null;
+    auto_destroy: boolean;
+    destroy_timeout: DestroyTimeout | null;
+    one_shot: boolean;
+    block_outbound: boolean;
+    persistent: boolean;
+    persistent_disk_gb: number | null;
+    paused_at: string | null;
+    from_snapshot: string | null;
+    snapshot_mode: SnapshotMode;
+    snapshot_frequency: string | null;
+    created_at: string;
+    last_activity_at: string;
+    expires_at: string;
+    destroyed_at: string | null;
+    destroy_reason: DestroyReason | null;
+};
+export type AckMessage = {
+    message: string;
+};
+export type WaitUntilReadyOptions = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+};
+export type WaitPreference = boolean | WaitUntilReadyOptions;
+export type SandboxRuntimeOptions = RequestOptions & {
+    waitUntilReady?: WaitPreference;
+};
+export type SandboxReadyRequestOptions = {
+    request?: RequestOptions;
+    wait?: WaitUntilReadyOptions;
+};
+export type CreateSandboxWithVolumeInput = {
+    sandbox: Omit<CreateSandboxRequest, 'volumeId' | 'persistent' | 'persistentDiskGB'>;
+    volume: Omit<CreateVolumeInput, 'region'> & {
+        region?: string;
+    };
+};
+export type CreateSandboxWithVolumeResult = {
+    sandbox: CreateSandboxResult;
+    volume: Volume;
+};

package/dist/src/types/sandbox.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/snapshot.d.ts

@@ -0,0 +1,15 @@
+import { SnapshotStatus } from '../enums';
+export type CreateSnapshotInput = {
+    name: string;
+};
+export type Snapshot = {
+    id: string;
+    sandbox_id: string;
+    name: string;
+    image_tag: string;
+    source_template: string;
+    status: SnapshotStatus;
+    failure_reason: string | null;
+    size_bytes: number | null;
+    created_at: string;
+};

package/dist/src/types/snapshot.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/stats.d.ts

@@ -0,0 +1,31 @@
+export type StatsAverageNumeric = {
+    totalInPercentage: number;
+    size: number;
+};
+export type StatsAverageNetwork = {
+    value?: number | null;
+    total?: number | null;
+    totalInPercentage?: number | null;
+    bytesPerSecond?: number | null;
+};
+export type StatsTimelinePoint = {
+    date: string;
+    memory: number;
+    cpu: number;
+    network: {
+        bytesPerSecond: number | null;
+    };
+};
+export type Stats = {
+    average: {
+        memory: StatsAverageNumeric;
+        cpu: StatsAverageNumeric;
+        network: StatsAverageNetwork;
+    };
+    replicaCount: number;
+    results: StatsTimelinePoint[];
+    responseTime: unknown;
+};
+export type StatsQuery = {
+    hoursAgo?: number;
+};

package/dist/src/types/stats.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/template.d.ts

@@ -0,0 +1,5 @@
+export type SandboxTemplate = {
+    name: string;
+    display_name: string;
+    description: string;
+};

package/dist/src/types/template.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/types/volume.d.ts

@@ -0,0 +1,24 @@
+import { VolumeType } from '../enums';
+import type { RegionSummary } from './region';
+export type CreateVolumeInput = {
+    name: string;
+    sizeGB: number;
+    region: string;
+    type?: VolumeType;
+    teamId?: string;
+};
+export type Volume = {
+    id: string;
+    name: string;
+    type: VolumeType;
+    team: string | null;
+    csi_volume_id: string | null;
+    size: number;
+    region: RegionSummary | null;
+    mount_path: string | null;
+    attached_sandbox_id: string | null;
+    attached_project_id: string | null;
+    last_attached_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+};

package/dist/src/types/volume.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });