@mainbrella/sdk 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,298 @@
+const keyPattern = /^mb_[a-f0-9]{64}$/i;
+const terminal = new Set(['succeeded', 'failed', 'canceled', 'timed_out', 'output_limit', 'interrupted']);
+
+export class MainbrellaError extends Error {
+  constructor(code, status = 0, details = {}) {
+    super(code);
+    this.name = 'MainbrellaError';
+    this.code = code;
+    this.status = status;
+    Object.assign(this, details);
+  }
+}
+
+function apiOrigin(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/'
+    || (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
+    throw new MainbrellaError('invalid_api_url');
+  }
+  return url.origin;
+}
+
+function identity(value) {
+  if (!value || !/^(small|c[1-9]\d{0,2})$/.test(value.id) || !value.createdAt
+    || !Number.isFinite(Date.parse(value.createdAt)) || new Date(value.createdAt).toISOString() !== value.createdAt) {
+    throw new MainbrellaError('invalid_container_identity');
+  }
+  return { id: value.id, createdAt: value.createdAt };
+}
+
+function fileBoolean(value) {
+  if (typeof value !== 'boolean') throw new MainbrellaError('invalid_file_options');
+  return String(value);
+}
+
+export class Mainbrella {
+  #apiKey;
+  #fetch;
+  constructor({ apiKey, baseUrl = 'https://api.mainbrella.com', fetch: fetcher = globalThis.fetch, timeoutMs = 90_000 } = {}) {
+    if (!keyPattern.test(apiKey ?? '')) throw new MainbrellaError('invalid_api_key');
+    if (typeof fetcher !== 'function' || !Number.isInteger(timeoutMs) || timeoutMs < 1) throw new MainbrellaError('invalid_client_options');
+    this.#apiKey = apiKey;
+    this.#fetch = fetcher;
+    this.baseUrl = apiOrigin(baseUrl);
+    this.timeoutMs = timeoutMs;
+    const workspacePath = id => {
+      if(!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(id??''))throw new MainbrellaError('invalid_workspace_identity');
+      return `/workspaces/${id}`;
+    };
+    this.workspaces = {
+      list:()=>this.request('/workspaces'), get:id=>this.request(workspacePath(id)),
+      update:(id,options)=>this.request(workspacePath(id),{method:'PATCH',body:options}),
+      delete:id=>this.request(workspacePath(id),{method:'DELETE'}),
+      restore:(id,options={})=>{workspacePath(id);return this.create({...options,workspaceId:id});},
+    };
+  }
+  async request(path, { method = 'GET', body, headers = {}, binary = false, stream = false, signal } = {}) {
+    if (!path.startsWith('/') || path.startsWith('//')) throw new MainbrellaError('invalid_api_path');
+    const url = new URL(path, this.baseUrl);
+    if (url.origin !== this.baseUrl) throw new MainbrellaError('invalid_api_path');
+    let response;
+    try {
+      response = await this.#fetch(url, { method, redirect: 'error', credentials: 'omit',
+        headers: { ...headers, Authorization: `Bearer ${this.#apiKey}`,
+          ...(body !== undefined ? { 'Content-Type': body instanceof Uint8Array ? 'application/octet-stream' : 'application/json' } : {}) },
+        body: body instanceof Uint8Array ? body : body !== undefined ? JSON.stringify(body) : undefined,
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(this.timeoutMs)]) : AbortSignal.timeout(this.timeoutMs) });
+    } catch { throw new MainbrellaError('transport_unavailable'); }
+    if (!response.ok) {
+      let data;
+      try { data = await response.json(); } catch {}
+      const code = typeof data?.error === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(data.error) ? data.error : 'request_failed';
+      const details = code === 'preview_reconciliation_required' && /^[a-f0-9]{32}$/.test(data?.previewId ?? '')
+        ? { previewId: data.previewId } : {};
+      throw new MainbrellaError(code, response.status, details);
+    }
+    if (stream) return response;
+    try { return binary ? new Uint8Array(await response.arrayBuffer()) : await response.json(); }
+    catch { throw new MainbrellaError('invalid_response', response.status); }
+  }
+  capabilities() { return this.request('/capabilities'); }
+  list() { return this.request('/containers'); }
+  connect(value) { return new Sandbox(this, value); }
+  async create({ catalogId, imageId, size, internet, workspaceId, idempotencyKey = crypto.randomUUID(), waitTimeoutMs = 120_000, pollIntervalMs = 1000 } = {}) {
+    if (catalogId && imageId || workspaceId && (catalogId || imageId || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(workspaceId)) || !/^[A-Za-z0-9_-]{1,128}$/.test(idempotencyKey)
+      || !Number.isInteger(waitTimeoutMs) || waitTimeoutMs < 1 || !Number.isInteger(pollIntervalMs) || pollIntervalMs < 1) {
+      throw new MainbrellaError('invalid_creation_options');
+    }
+    const deadline = Date.now() + waitTimeoutMs;
+    if(workspaceId && (await this.capabilities())?.persistence?.snapshots!==true)throw new MainbrellaError('persistence_unavailable',503,{idempotencyKey});
+    if (size !== undefined && !['lite', 'small', 'medium', 'large', 'xl'].includes(size)) throw new MainbrellaError('invalid_creation_options');
+    if (internet !== undefined && typeof internet !== 'boolean') throw new MainbrellaError('invalid_creation_options');
+    if (internet === false && (await this.capabilities())?.networking?.internetControl !== true) throw new MainbrellaError('network_policy_unavailable', 503, { idempotencyKey });
+    const body = { ...(workspaceId?{workspaceId}:imageId ? { imageId } : catalogId ? { catalogId } : {}), ...(size !== undefined ? { size } : {}), ...(internet !== undefined ? { internet } : {}) };
+    while (Date.now() < deadline) {
+      try {
+        const data = await this.request('/containers', { method: 'POST', body,
+          headers: { 'Idempotency-Key': idempotencyKey }, signal: AbortSignal.timeout(Math.max(1, deadline - Date.now())) });
+        const creation = data.creation;
+        if (!creation?.id || !['starting', 'running'].includes(creation.status)) throw new MainbrellaError('invalid_creation_response');
+        if (creation.status === 'running') {
+          const selected = data.containers?.find(c => c.id === creation.containerId && c.createdAt === creation.createdAt && c.status === 'running');
+          if (!selected) throw new MainbrellaError('invalid_creation_response');
+          if (internet === false && selected.internet !== false) throw new MainbrellaError('network_policy_unconfirmed', 409);
+          if(workspaceId && selected.workspaceId!==workspaceId)throw new MainbrellaError('workspace_restore_unconfirmed',409);
+          const sandbox = this.connect(selected);
+          sandbox.creationId = creation.id;
+          return sandbox;
+        }
+      } catch (error) {
+        if (!(error instanceof MainbrellaError) || ['network_policy_unavailable','persistence_unavailable'].includes(error.code) || error.status && error.status !== 503 || error.status === 0 && error.code !== 'transport_unavailable') {
+          error.idempotencyKey = idempotencyKey;
+          throw error;
+        }
+      }
+      const remaining = deadline - Date.now();
+      if (remaining > 0) await new Promise(resolve => setTimeout(resolve, Math.min(pollIntervalMs, remaining)));
+    }
+    throw new MainbrellaError('creation_ambiguous', 0, { idempotencyKey });
+  }
+}
+
+export class Sandbox {
+  constructor(client, value) {
+    this.client = client;
+    Object.assign(this, identity(value));
+    if (typeof value.internet === 'boolean') this.internet = value.internet;
+    for (const name of ['imageDigest', 'catalogId', 'imageId', 'instance','workspaceId']) if (typeof value[name] === 'string') this[name] = value[name];
+    this.files = {
+      read: path => this.client.request(this.path('/containers/files', { path }), { binary: true }),
+      write: (path, bytes) => {
+        if (!(bytes instanceof Uint8Array)) throw new MainbrellaError('file_bytes_required');
+        return this.client.request(this.path('/containers/files', { path }), { method: 'PUT', body: bytes });
+      },
+      list: (path, { limit, offset } = {}) => this.client.request(this.path('/containers/files/list', {
+        path, ...(limit !== undefined ? { limit: String(limit) } : {}), ...(offset !== undefined ? { offset: String(offset) } : {}),
+      })),
+      stat: (path, { followSymlinks = false } = {}) => this.client.request(this.path('/containers/files/stat', { path, followSymlinks: fileBoolean(followSymlinks) })),
+      mkdir: (path, { recursive = false, mode } = {}) => this.client.request(this.path('/containers/files/mkdir'), {
+        method: 'POST', body: { path, recursive, ...(mode !== undefined ? { mode } : {}) },
+      }),
+      remove: (path, { recursive = false } = {}) => this.client.request(this.path('/containers/files/remove', { path, recursive: fileBoolean(recursive) }), { method: 'DELETE' }),
+      move: (path, destination) => this.client.request(this.path('/containers/files/move'), { method: 'POST', body: { path, destination } }),
+      chmod: (path, mode) => this.client.request(this.path('/containers/files/chmod', { path }), { method: 'PATCH', body: { mode } }),
+    };
+    this.previews = {
+      create: (port, { ttlSeconds } = {}) => {
+        if (!Number.isInteger(port) || port < 1024 || port > 65535
+          || ttlSeconds !== undefined && (!Number.isInteger(ttlSeconds) || ttlSeconds < 60 || ttlSeconds > 3600)) {
+          throw new MainbrellaError('invalid_preview_options');
+        }
+        return this.client.request(this.path('/containers/previews'), { method: 'POST',
+          body: { port, ...(ttlSeconds !== undefined ? { ttlSeconds } : {}) } });
+      },
+      list: () => this.client.request(this.path('/containers/previews')),
+      revoke: previewId => {
+        if (!/^[a-f0-9]{32}$/.test(previewId ?? '')) throw new MainbrellaError('invalid_preview_identity');
+        return this.client.request(this.path('/containers/previews', { previewId }), { method: 'DELETE' });
+      },
+    };
+    this.webhook = {
+      get: () => this.client.request(this.path('/containers/webhook')),
+      configure: (url, { replayFromCursor } = {}) => this.client.request(this.path('/containers/webhook'), {
+        method: 'PUT', body: { url, ...(replayFromCursor !== undefined ? { replayFromCursor } : {}) },
+      }),
+      remove: () => this.client.request(this.path('/containers/webhook'), { method: 'DELETE' }),
+      deliveries: () => this.client.request(this.path('/containers/webhook/deliveries')),
+      retry: eventId => {
+        if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(eventId ?? '')) throw new MainbrellaError('invalid_event_identity');
+        return this.client.request(this.path('/containers/webhook/retry'), { method: 'POST', body: { eventId } });
+      },
+    };
+    this.commands = {
+      list: () => this.client.request(this.path('/containers/executions')),
+      attach: id => new Execution(this, id),
+      run: (command, { timeoutMs, signal } = {}) => this.client.request(this.path('/containers/exec'),
+        { method: 'POST', body: { command, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }, signal }),
+      start: async (command, { timeoutMs, stdin, cwd, env, pty, idempotencyKey = crypto.randomUUID() } = {}) => {
+        try {
+          const record = await this.client.request(this.path('/containers/executions'), { method: 'POST',
+            body: { ...(Array.isArray(command) ? { argv: command } : { command }), ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+              ...(pty !== undefined ? { pty } : {}), ...(stdin !== undefined ? { stdin } : {}), ...(cwd !== undefined ? { cwd } : {}), ...(env !== undefined ? { env } : {}) }, headers: { 'Idempotency-Key': idempotencyKey } });
+          return new Execution(this, record.id);
+        } catch (error) { error.idempotencyKey = idempotencyKey; throw error; }
+      },
+    };
+  }
+  path(path, extra = {}) { return `${path}?${new URLSearchParams({ ...extra, id: this.id, createdAt: this.createdAt })}`; }
+  async saveWorkspace(name,{stop=false,idempotencyKey=crypto.randomUUID()}={}) {
+    if(typeof name!=='string'||!name.length||name.length>80||typeof stop!=='boolean'||!/^[A-Za-z0-9_-]{1,128}$/.test(idempotencyKey))throw new MainbrellaError('invalid_workspace_options');
+    try{return await this.client.request('/workspaces',{method:'POST',body:{id:this.id,createdAt:this.createdAt,name,stop},headers:{'Idempotency-Key':idempotencyKey}});}
+    catch(error){error.idempotencyKey=idempotencyKey;throw error;}
+  }
+  exportWorkspace(){return this.client.request(this.path('/containers/export'),{binary:true});}
+  events({ cursor, limit } = {}) {
+    return this.client.request(this.path('/containers/events', { ...(cursor !== undefined ? { cursor: String(cursor) } : {}), ...(limit !== undefined ? { limit: String(limit) } : {}) }));
+  }
+  metrics({ from, to } = {}) {
+    return this.client.request(this.path('/containers/metrics', { ...(from !== undefined ? { from } : {}), ...(to !== undefined ? { to } : {}) }));
+  }
+  async kill() {
+    const data = await this.client.request(this.path('/containers'), { method: 'DELETE' });
+    if (!Array.isArray(data.containers) || data.containers.some(c => c.id === this.id && c.createdAt === this.createdAt)) {
+      throw new MainbrellaError('cleanup_unconfirmed');
+    }
+    return data;
+  }
+}
+
+export async function verifyWebhookSignature(bytes, signature, signingSecret, { nowMs = Date.now(), toleranceSeconds = 300 } = {}) {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength > 16 * 1024 || typeof signature !== 'string'
+    || typeof signingSecret !== 'string' || !/^mbwh_[a-f0-9]{64}$/.test(signingSecret) || !Number.isFinite(nowMs) || nowMs < 0
+    || !Number.isInteger(toleranceSeconds) || toleranceSeconds < 1 || toleranceSeconds > 900) return false;
+  const match = /^t=(\d{1,13}),v1=([a-f0-9]{64})$/.exec(signature);
+  if (!match || Math.abs(Math.floor(nowMs / 1000) - Number(match[1])) > toleranceSeconds) return false;
+  const prefix = new TextEncoder().encode(`${match[1]}.`), message = new Uint8Array(prefix.length + bytes.byteLength);
+  message.set(prefix); message.set(bytes, prefix.length);
+  const expected = Uint8Array.from(match[2].match(/.{2}/g), pair => Number.parseInt(pair, 16));
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(signingSecret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+  return crypto.subtle.verify('HMAC', key, expected, message);
+}
+
+export class Execution {
+  constructor(sandbox, id) {
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id ?? '')) throw new MainbrellaError('invalid_execution_identity');
+    this.sandbox = sandbox;
+    this.id = id;
+    this.cursor = 0;
+    this.stdin = {
+      write: bytes => {
+        if (!(bytes instanceof Uint8Array)) throw new MainbrellaError('stdin_bytes_required');
+        return this.sandbox.client.request(this.path('/stdin'), { method: 'POST', body: bytes });
+      },
+      close: () => this.sandbox.client.request(this.path('/stdin'), { method: 'DELETE' }),
+    };
+  }
+  path(suffix = '', extra = {}) { return this.sandbox.path(`/containers/executions/${this.id}${suffix}`, extra); }
+  get() { return this.sandbox.client.request(this.path()); }
+  cancel() { return this.sandbox.client.request(this.path(), { method: 'DELETE' }); }
+  signal(signal) {
+    if (!['SIGINT', 'SIGTERM', 'SIGKILL'].includes(signal)) throw new MainbrellaError('invalid_execution_signal');
+    return this.sandbox.client.request(this.path('/signal'), { method: 'POST', body: { signal } });
+  }
+  resize(cols, rows) {
+    if (![cols, rows].every(value => Number.isInteger(value) && value >= 1 && value <= 1000)) throw new MainbrellaError('invalid_terminal_size');
+    return this.sandbox.client.request(this.path('/resize'), { method: 'POST', body: { cols, rows } });
+  }
+  async wait({ timeoutMs = 15 * 60_000, pollIntervalMs = 1000 } = {}) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || !Number.isInteger(pollIntervalMs) || pollIntervalMs < 1) throw new MainbrellaError('invalid_wait_options');
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.get();
+      if (terminal.has(result.status)) return result;
+      await new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(pollIntervalMs, deadline - Date.now()))));
+    }
+    throw new MainbrellaError('execution_wait_timeout');
+  }
+  async *events({ cursor = this.cursor, signal } = {}) {
+    if (!Number.isSafeInteger(cursor) || cursor < 0) throw new MainbrellaError('invalid_cursor');
+    while (!signal?.aborted) {
+      const response = await this.sandbox.client.request(this.path('/events', { cursor: String(cursor) }), { stream: true, signal });
+      const reader = response.body?.getReader();
+      if (!reader) throw new MainbrellaError('invalid_stream_response');
+      const decoder = new TextDecoder();
+      let buffer = '', completed = false, sawStatus = false;
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+          let boundary;
+          while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+            if (boundary > 64 * 1024) throw new Error();
+            const frame = buffer.slice(0, boundary); buffer = buffer.slice(boundary + 2);
+            const type = frame.split('\n').find(line => line.startsWith('event: '))?.slice(7);
+            const data = frame.split('\n').find(line => line.startsWith('data: '))?.slice(6);
+            if (!data) continue;
+            const item = JSON.parse(data);
+            if (type === 'status') {
+              sawStatus = true;
+              completed = terminal.has(item.status);
+              yield { type: 'status', execution: item };
+            } else if (['stdout', 'stderr'].includes(type)) {
+              if (!Number.isSafeInteger(item.sequence) || typeof item.data !== 'string') throw new Error();
+              if (item.sequence > cursor) { this.cursor = cursor = item.sequence; yield item; }
+            }
+          }
+          if (buffer.length > 64 * 1024) throw new Error();
+          if (done && (buffer.trim() || !sawStatus)) throw new Error();
+          if (done || completed) break;
+        }
+      } catch { throw new MainbrellaError('execution_stream_unavailable', 0, { cursor }); }
+      finally { await reader.cancel().catch(() => {}); }
+      if (completed) return;
+    }
+  }
+}
+
+export { terminal as terminalExecutionStates };

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@mainbrella/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Mainbrella container automation client",
+  "license": "GPL-3.0-only",
+  "homepage": "https://mainbrella.com/docs/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mainbrella/backend.git",
+    "directory": "sdk/javascript"
+  },
+  "bugs": "https://github.com/mainbrella/backend/issues",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE",
+    "cli.mjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test *.test.mjs"
+  },
+  "bin": {
+    "mainbrella": "cli.mjs"
+  }
+}