@runnee/sdk 0.0.0-stage → 0.1.0

package/lib/esm/errors.d.ts

@@ -0,0 +1,34 @@
+/** Errors never retain request headers, request bodies or raw response bodies. */
+export declare class RunneeError extends Error {
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly code?: string;
+    constructor(message: string, details?: {
+        status?: number;
+        requestId?: string;
+        code?: string;
+    });
+}
+export declare class RunneeAuthenticationError extends RunneeError {
+}
+export declare class RunneePermissionError extends RunneeError {
+}
+export declare class RunneeValidationError extends RunneeError {
+}
+export declare class RunneeRateLimitError extends RunneeError {
+    retryAfter?: number;
+}
+export declare class RunneeTimeoutError extends RunneeError {
+}
+export declare class RunneeNetworkError extends RunneeError {
+}
+export declare class RunneeServerError extends RunneeError {
+}
+export declare class RunneeConflictError extends RunneeError {
+}
+export declare class RunneeNotFoundError extends RunneeError {
+}
+export declare class RunneeResponseError extends RunneeError {
+}
+export declare class RunneeCancelledError extends RunneeError {
+}

package/lib/esm/errors.js

@@ -0,0 +1,34 @@
+/** Errors never retain request headers, request bodies or raw response bodies. */
+export class RunneeError extends Error {
+    status;
+    requestId;
+    code;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = new.target.name;
+        Object.assign(this, details);
+    }
+}
+export class RunneeAuthenticationError extends RunneeError {
+}
+export class RunneePermissionError extends RunneeError {
+}
+export class RunneeValidationError extends RunneeError {
+}
+export class RunneeRateLimitError extends RunneeError {
+    retryAfter;
+}
+export class RunneeTimeoutError extends RunneeError {
+}
+export class RunneeNetworkError extends RunneeError {
+}
+export class RunneeServerError extends RunneeError {
+}
+export class RunneeConflictError extends RunneeError {
+}
+export class RunneeNotFoundError extends RunneeError {
+}
+export class RunneeResponseError extends RunneeError {
+}
+export class RunneeCancelledError extends RunneeError {
+}

package/lib/esm/http.d.ts

@@ -0,0 +1,25 @@
+export interface ResponseMetadata {
+    status: number;
+    requestId?: string;
+    rateLimitRemaining?: number;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+    idempotencyKey?: string;
+    onResponse?: (metadata: ResponseMetadata) => void;
+}
+export interface RunneeOptions {
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+    allowInsecureHTTP?: boolean;
+}
+export declare class HTTPClient {
+    #private;
+    constructor(options?: RunneeOptions);
+    request<T>(id: string, params?: Record<string, string | number | undefined>, body?: unknown, options?: RequestOptions): Promise<T>;
+}

package/lib/esm/http.js

@@ -0,0 +1,256 @@
+import { contracts } from './contracts.js';
+import { validate, encodeRequest } from './validation.js';
+import { RunneeError, RunneeAuthenticationError, RunneePermissionError, RunneeValidationError, RunneeRateLimitError, RunneeTimeoutError, RunneeNetworkError, RunneeServerError, RunneeConflictError, RunneeNotFoundError, RunneeResponseError, RunneeCancelledError, } from './errors.js';
+const operations = contracts.operations;
+function integer(n, min, max, name) {
+    if (!Number.isSafeInteger(n) || n < min || n > max)
+        throw new RunneeValidationError(name + ' is outside the supported range.');
+    return n;
+}
+function retryAfter(raw) {
+    if (!raw)
+        return;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0)
+        return n * 1000;
+    const date = Date.parse(raw);
+    if (Number.isFinite(date))
+        return Math.max(0, date - Date.now());
+}
+async function pause(ms, signal) {
+    if (signal.aborted)
+        throw new RunneeCancelledError('Request cancelled.');
+    return new Promise((resolve, reject) => {
+        const done = () => {
+            signal.removeEventListener('abort', abort);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            reject(new RunneeCancelledError('Request cancelled.'));
+        };
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}
+async function readJSON(response) {
+    if (!/\bapplication\/(?:[\w.+-]*\+)?json\b/i.test(response.headers.get('content-type') ?? ''))
+        throw new RunneeResponseError('Runnee returned a non-JSON response.');
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new RunneeResponseError('Runnee returned an empty response.');
+    const decoder = new TextDecoder(), parts = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > 5 * 1024 * 1024)
+                throw new RunneeResponseError('Runnee response exceeds the SDK size limit.');
+            parts.push(decoder.decode(value, { stream: true }));
+        }
+        parts.push(decoder.decode());
+        try {
+            return JSON.parse(parts.join(''));
+        }
+        catch {
+            throw new RunneeResponseError('Runnee returned invalid JSON.');
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+export class HTTPClient {
+    #key;
+    #url;
+    #fetch;
+    #timeout;
+    #retries;
+    constructor(options = {}) {
+        if (typeof window !== 'undefined' && typeof document !== 'undefined')
+            throw new RunneeValidationError('Runnee API keys must be used on a trusted server, not in a public browser application.');
+        const env = globalThis.process?.env;
+        const key = options.apiKey ?? env?.RUNNEE_API_KEY;
+        if (typeof key !== 'string' || !/^[A-Za-z0-9_-]{8,512}$/.test(key))
+            throw new RunneeAuthenticationError('Set a valid RUNNEE_API_KEY or provide apiKey.');
+        let url;
+        try {
+            url = new URL(options.baseURL ?? env?.RUNNEE_BASE_URL ?? 'https://api.runnee.cloud');
+        }
+        catch {
+            throw new RunneeValidationError('baseURL must be an absolute HTTPS origin.');
+        }
+        if (url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== '/' ||
+            !['https:', 'http:'].includes(url.protocol) ||
+            (url.protocol === 'http:' &&
+                !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
+                !options.allowInsecureHTTP))
+            throw new RunneeValidationError('baseURL requires HTTPS; HTTP is allowed only for loopback or explicit development use.');
+        this.#url = url.origin;
+        this.#key = key;
+        this.#timeout = integer(options.timeout ?? 30000, 1, 300000, 'timeout');
+        this.#retries = integer(options.maxRetries ?? 2, 0, 5, 'maxRetries');
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        if (typeof this.#fetch !== 'function')
+            throw new RunneeValidationError('This runtime requires fetch or a fetch implementation.');
+    }
+    async request(id, params = {}, body, options = {}) {
+        if (options.signal && typeof options.signal.addEventListener !== 'function')
+            throw new RunneeValidationError('signal must be an AbortSignal.');
+        const op = operations.find((o) => o.id === id);
+        if (!op)
+            throw new RunneeValidationError('Unsupported SDK operation.');
+        let pathname = op.path;
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            const marker = '{' + key + '}';
+            if (pathname.includes(marker)) {
+                const encoded = String(value);
+                if (!encoded || encoded === '.' || encoded === '..' || /[\/\\\x00-\x1f]/.test(encoded))
+                    throw new RunneeValidationError('Invalid resource identifier.');
+                pathname = pathname.replace(marker, encodeURIComponent(encoded));
+            }
+            else
+                query.set(key, String(value));
+        }
+        if (pathname.includes('{'))
+            throw new RunneeValidationError('Missing resource identifier.');
+        const requestBody = body && typeof body === 'object' && !Array.isArray(body)
+            ? Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined))
+            : body;
+        if (op.request)
+            validate(requestBody, op.request, false);
+        const payload = requestBody === undefined ? undefined : encodeRequest(requestBody);
+        if (options.idempotencyKey !== undefined &&
+            (id !== 'execute' || !/^[A-Za-z0-9_.:-]{8,128}$/.test(options.idempotencyKey)))
+            throw new RunneeValidationError('Use an 8–128 character idempotencyKey only for execute.');
+        const safe = op.method === 'GET' || (id === 'execute' && !!options.idempotencyKey);
+        const retries = integer(options.maxRetries ?? (safe ? this.#retries : 0), 0, 5, 'maxRetries');
+        if (!safe && retries > 0)
+            throw new RunneeValidationError('Automatic retries require a read operation or idempotent execution.');
+        const controller = new AbortController(), abort = () => controller.abort();
+        let timedOut = false;
+        const timeout = integer(options.timeout ?? this.#timeout, 1, 300000, 'timeout');
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            controller.abort();
+        try {
+            for (let attempt = 0;; attempt++) {
+                if (controller.signal.aborted)
+                    throw new RunneeCancelledError('Request cancelled.');
+                let response;
+                try {
+                    response = await this.#fetch(this.#url + pathname + (query.size ? '?' + query : ''), {
+                        method: op.method,
+                        headers: {
+                            Authorization: 'Bearer ' + this.#key,
+                            Accept: 'application/json',
+                            'User-Agent': 'runnee-js/0.1.0',
+                            ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                            ...(options.idempotencyKey ? { 'Idempotency-Key': options.idempotencyKey } : {}),
+                        },
+                        body: payload,
+                        signal: controller.signal,
+                        redirect: 'error',
+                        credentials: 'omit',
+                        cache: 'no-store',
+                    });
+                }
+                catch {
+                    if (controller.signal.aborted)
+                        throw new RunneeCancelledError('Request cancelled.');
+                    if (attempt < retries) {
+                        await pause(Math.min(10000, 250 * 2 ** attempt) * (0.5 + Math.random() * 0.5), controller.signal);
+                        continue;
+                    }
+                    throw new RunneeNetworkError('Unable to reach Runnee. An interrupted execution may still have run; inspect history before submitting with a new key.');
+                }
+                const requestId = response.headers.get('x-request-id') ?? undefined;
+                const remaining = response.headers.get('x-ratelimit-remaining');
+                options.onResponse?.({
+                    status: response.status,
+                    requestId,
+                    rateLimitRemaining: remaining === null ? undefined : Number(remaining),
+                });
+                const after = retryAfter(response.headers.get('retry-after'));
+                if ([429, 500, 502, 503, 504].includes(response.status) &&
+                    attempt < retries &&
+                    (after === undefined || after <= 60000)) {
+                    await response.body?.cancel();
+                    await pause(after ?? Math.min(10000, 250 * 2 ** attempt) * (0.5 + Math.random() * 0.5), controller.signal);
+                    continue;
+                }
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    const E = response.status === 401
+                        ? RunneeAuthenticationError
+                        : response.status === 403
+                            ? RunneePermissionError
+                            : response.status === 404
+                                ? RunneeNotFoundError
+                                : response.status === 409
+                                    ? RunneeConflictError
+                                    : response.status === 429
+                                        ? RunneeRateLimitError
+                                        : response.status >= 500
+                                            ? RunneeServerError
+                                            : RunneeValidationError;
+                    const error = new E(response.status === 409
+                        ? 'The request conflicts with existing state. An execution may be admitted or its idempotency key reused; inspect history before submitting again.'
+                        : response.status === 401
+                            ? 'Invalid, expired or revoked Runnee API key.'
+                            : response.status === 403
+                                ? 'The API key scope or resource access policy does not permit this operation.'
+                                : 'Runnee API request failed (HTTP ' + response.status + ').', { status: response.status, requestId });
+                    if (error instanceof RunneeRateLimitError)
+                        error.retryAfter = after === undefined ? undefined : after / 1000;
+                    throw error;
+                }
+                let value;
+                try {
+                    value = await readJSON(response);
+                }
+                catch (e) {
+                    if (e instanceof RunneeResponseError)
+                        throw new RunneeResponseError(e.message, { status: response.status, requestId });
+                    if (controller.signal.aborted)
+                        throw e;
+                    if (attempt < retries) {
+                        await pause(Math.min(10000, 250 * 2 ** attempt) * (0.5 + Math.random() * 0.5), controller.signal);
+                        continue;
+                    }
+                    throw new RunneeNetworkError('Unable to read a complete Runnee response. Inspect history before resubmitting an uncertain execution.');
+                }
+                validate(value, op.response, true, requestId);
+                return value;
+            }
+        }
+        catch (error) {
+            if (timedOut)
+                throw new RunneeTimeoutError('Request timed out. Execution may still have completed; reuse its idempotency key or inspect history.');
+            if (options.signal?.aborted)
+                throw new RunneeCancelledError('Request cancelled. Remote execution cancellation is not guaranteed.');
+            if (error instanceof RunneeError)
+                throw error;
+            throw new RunneeNetworkError('Runnee request could not be completed.');
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+}

package/lib/esm/index.d.ts

@@ -0,0 +1,57 @@
+import { type RunneeOptions, type RequestOptions } from './http.js';
+import type * as T from './types.js';
+export * from './errors.js';
+export type * from './types.js';
+export type { RunneeOptions, RequestOptions, ResponseMetadata } from './http.js';
+export interface ExecutionFilters {
+    before?: string;
+    status?: 'success' | 'failed';
+    mode?: 'dry-run' | 'live';
+}
+export declare class Runnee {
+    #private;
+    constructor(apiKey: string, options?: Omit<RunneeOptions, 'apiKey'>);
+    constructor(options?: RunneeOptions);
+    execute(input: T.ExecuteRequest, options?: RequestOptions): Promise<T.ExecuteResponse>;
+    readonly executions: {
+        get: (id: string, options?: RequestOptions) => Promise<T.ExecutionDetail>;
+        list: (filters?: ExecutionFilters, options?: RequestOptions) => Promise<T.ExecutionPage>;
+        iterate: (filters?: ExecutionFilters, options?: RequestOptions) => AsyncGenerator<T.Execution>;
+    };
+    private iterateExecutions;
+    readonly scripts: {
+        list: (options?: RequestOptions) => Promise<T.ScriptList>;
+        create: (input: T.ScriptCreate, options?: RequestOptions) => Promise<T.Script>;
+        get: (id: string, options?: RequestOptions) => Promise<T.ScriptDetail>;
+        update: (id: string, input: T.ScriptUpdate, options?: RequestOptions) => Promise<T.Script>;
+        delete: (id: string, options?: RequestOptions) => Promise<T.Deleted>;
+        getVersion: (id: string, version: number, options?: RequestOptions) => Promise<T.ScriptVersion>;
+        restore: (id: string, input: T.ScriptRestore, options?: RequestOptions) => Promise<T.Script>;
+        storage: (options?: RequestOptions) => Promise<T.Storage>;
+    };
+    readonly secrets: {
+        list: (options?: RequestOptions) => Promise<T.SecretList>;
+        get: (name: string, options?: RequestOptions) => Promise<T.Secret>;
+        create: (input: T.SecretCreate, options?: RequestOptions) => Promise<T.Secret>;
+        update: (name: string, input: T.SecretUpdate, options?: RequestOptions) => Promise<T.Secret>;
+        delete: (name: string, options?: RequestOptions) => Promise<T.Deleted>;
+    };
+    readonly usage: {
+        get: (options?: RequestOptions) => Promise<T.BillingStatus>;
+        summary: (options?: RequestOptions) => Promise<T.UsageSummary>;
+        history: (days?: 7 | 30 | 90, options?: RequestOptions) => Promise<T.UsageHistory>;
+    };
+    readonly sandbox: {
+        get: (options?: RequestOptions) => Promise<T.Sandbox>;
+    };
+    readonly billing: {
+        plans: (options?: RequestOptions) => Promise<T.Plans>;
+    };
+    readonly health: {
+        get: (options?: RequestOptions) => Promise<T.Health>;
+    };
+    readonly telemetry: {
+        recordExecution: (input: T.TelemetryExecution, options?: RequestOptions) => Promise<T.TelemetryRecorded>;
+        recordEvent: (input: T.TelemetryEvent, options?: RequestOptions) => Promise<T.Accepted>;
+    };
+}

package/lib/esm/index.js

@@ -0,0 +1,68 @@
+import { HTTPClient } from './http.js';
+export * from './errors.js';
+export class Runnee {
+    #http;
+    constructor(apiKeyOrOptions = {}, options = {}) {
+        this.#http = new HTTPClient(typeof apiKeyOrOptions === 'string'
+            ? { ...options, apiKey: apiKeyOrOptions }
+            : apiKeyOrOptions);
+    }
+    execute(input, options) {
+        return this.#http.request('execute', {}, input, options);
+    }
+    executions = {
+        get: (id, options) => this.#http.request('executions.get', { id }, undefined, options),
+        list: (filters = {}, options) => this.#http.request('executions.list', { ...filters }, undefined, options),
+        iterate: (filters = {}, options) => this.iterateExecutions(filters, options),
+    };
+    async *iterateExecutions(filters, options) {
+        let before = filters.before;
+        const seen = new Set();
+        for (;;) {
+            const page = await this.executions.list({ ...filters, before }, options);
+            for (const item of page.items)
+                yield item;
+            if (!page.nextCursor)
+                break;
+            if (seen.has(page.nextCursor))
+                throw new Error('Runnee returned a repeated pagination cursor.');
+            seen.add(page.nextCursor);
+            before = page.nextCursor;
+        }
+    }
+    scripts = {
+        list: (options) => this.#http.request('scripts.list', {}, undefined, options),
+        create: (input, options) => this.#http.request('scripts.create', {}, input, options),
+        get: (id, options) => this.#http.request('scripts.get', { id }, undefined, options),
+        update: (id, input, options) => this.#http.request('scripts.update', { id }, input, options),
+        delete: (id, options) => this.#http.request('scripts.delete', { id }, undefined, options),
+        getVersion: (id, version, options) => this.#http.request('scripts.getVersion', { id, version }, undefined, options),
+        restore: (id, input, options) => this.#http.request('scripts.restore', { id }, input, options),
+        storage: (options) => this.#http.request('scripts.storage', {}, undefined, options),
+    };
+    secrets = {
+        list: (options) => this.#http.request('secrets.list', {}, undefined, options),
+        get: (name, options) => this.#http.request('secrets.get', { name }, undefined, options),
+        create: (input, options) => this.#http.request('secrets.create', {}, input, options),
+        update: (name, input, options) => this.#http.request('secrets.update', { name }, input, options),
+        delete: (name, options) => this.#http.request('secrets.delete', { name }, undefined, options),
+    };
+    usage = {
+        get: (options) => this.#http.request('usage.get', {}, undefined, options),
+        summary: (options) => this.#http.request('usage.summary', {}, undefined, options),
+        history: (days = 7, options) => this.#http.request('usage.history', { days }, undefined, options),
+    };
+    sandbox = {
+        get: (options) => this.#http.request('sandbox.get', {}, undefined, options),
+    };
+    billing = {
+        plans: (options) => this.#http.request('billing.plans', {}, undefined, options),
+    };
+    health = {
+        get: (options) => this.#http.request('health.get', {}, undefined, options),
+    };
+    telemetry = {
+        recordExecution: (input, options) => this.#http.request('telemetry.recordExecution', {}, input, options),
+        recordEvent: (input, options) => this.#http.request('telemetry.recordEvent', {}, input, options),
+    };
+}