JavaScript and TypeScript - Archal

Install and create a client

npm install archal@0.11.0

import { ArchalEnvironmentClient } from 'archal';

const archal = new ArchalEnvironmentClient({
  apiKey: process.env.ARCHAL_API_KEY!,
});

The API key controls sandbox lifecycle. Keep it out of the process being tested.

Create from explicit state

const sandbox = await archal.createSession(
  {
    environments: ['github'],
    ttlSeconds: 1800,
    initialState: {
      github: {
        format: 'json',
        value: githubState,
      },
    },
  },
  { idempotencyKey: `github-${process.env.CI_RUN_ID}` },
);

createSession waits until every environment is ready. If readiness fails, it attempts to destroy the new sandbox before returning the original error. Use startSession when you need the sandbox ID immediately, then call waitUntilReady.

Call a provider-shaped endpoint

try {
  const response = await archal.callEnvironment(sandbox.sessionId, 'github', {
    method: 'POST',
    path: '/user/repos',
    body: { name: 'checkout-test', private: true },
  });

  console.log(response.status, response.data);
} finally {
  await archal.destroySession(sandbox.sessionId);
}

callEnvironment reads the connection from the sandbox, removes any caller provider authorization, and applies the returned scoped credential headers. It rejects paths that leave the environment base URL.

State

const before = await archal.getState(sandbox.sessionId, 'github');

const diff = await archal.diffState(sandbox.sessionId, 'github', {
  source: 'explicit',
  before: before.state,
});

await archal.resetEnvironment(sandbox.sessionId, 'github');

A diff always requires the explicit prior JSON state. It does not infer the reset baseline.

Longer work

renewSession refreshes expiry and scoped connections. manageSessionLease can renew before the nearest lease boundary and refresh credentials. Stopping a managed lease stops its renewal timer, but does not destroy the sandbox. Read the returned hardExpiresAt instead of assuming one plan-wide maximum.

Common client methods

listEnvironments and describeEnvironment
listSessions, startSession, createSession, and getSession
waitUntilReady, its awaitSessionReady alias, and waitUntilDestroyed
validateState, getState, loadState, and diffState
callEnvironment and getEvidence
resetEnvironment, resetSession, and renewSession
manageSessionLease and destroySession

⌘I