@mochabug/adapt-core

Headless client for Adapt automations. No UI — just the automation lifecycle.

npm install @mochabug/adapt-core

CDN (UMD — from @mochabug/adapt-web):

<script src="https://cdn.mochabug.com/adapt/web/__VERSION__/adapt-core.min.js"></script>

Quick start

Browser

import { createConnectClient } from "@mochabug/adapt-core/connect";
import { createAdaptClient } from "@mochabug/adapt-core";

const client = createAdaptClient(
  createConnectClient({ id: "my-automation" }),
  "my-automation",
);

const { sessionToken } = await client.run({
  onSession: (session) => console.log("Status:", session.status),
  onOutput: (output) => console.log("Output:", output.data),
  onUrl: (url) => console.log("URL:", url.url),
  onError: (error) => console.error("Error:", error),
});

Node.js

import { createGrpcClient } from "@mochabug/adapt-core/grpc";
import { createAdaptClient } from "@mochabug/adapt-core";

const client = createAdaptClient(
  createGrpcClient(),
  "my-automation",
);

Configuration

import { configure } from "@mochabug/adapt-core";

configure({
  webUrl: "https://adapt.mochabugapis.com/v1/automations", // default
  grpcUrl: "https://adapt-grpc.mochabugapis.com",          // default
});

Run an automation

run() starts a session and subscribes to real-time updates in a single RPC call.

const { sessionToken, expiresAt } = await client.run({
  challengeToken,       // proof-of-work token (if required)
  transmitter: "start", // optional starting transmitter
  signals: {            // optional input signals
    query: "hello",
    file: { mimeType: "application/pdf", data: pdfBytes, filename: "doc.pdf" },
  },
  authToken,            // for protected automations
  onSession: (s) => { /* { status, fork? } */ },
  onOutput: (o) => { /* { vertex, fork, data, created } */ },
  onUrl: (u) => { /* { url, vertex, done, stopped, created, token, fork } */ },
  onError: (e) => { /* non-retriable stream error */ },
});

Inherit a session

const { sessionToken } = await client.runInherit(parentToken, {
  onSession: (s) => {},
  onOutput: (o) => {},
});

Start without subscribing

const { sessionToken, expiresAt } = await client.start({
  challengeToken,
  transmitter: "start",
  signals: { input: "data" },
});

await client.subscribe(sessionToken, {
  onSession: (s) => {},
  onOutput: (o) => {},
});

await client.stop(sessionToken);
await client.unsubscribe();

Read data

const session = await client.getSession(sessionToken);

const { outputs, nextPageCursor } = await client.readOutput(sessionToken, {
  pageSize: 100,
  vertex: "output-vertex",
  newerThan: new Date("2025-01-01"),
});

const { urls } = await client.readUrls(sessionToken, {
  pageSize: 50,
});

Headless + Cap (UMD)

Load the headless client and Cap widget together for proof-of-work in non-UI scenarios:

<script src="https://cdn.mochabug.com/adapt/web/__VERSION__/adapt-core.min.js"></script>
<script src="https://cdn.mochabug.com/adapt/web/__VERSION__/adapt-web.cap.min.js"></script>
<script>
  // Both scripts merge into MbAdapt
  var client = MbAdapt.createAdaptClient(
    MbAdapt.createConnectClient({ id: "my-automation" }),
    "my-automation"
  );

  // Show Cap widget, then run with the token
  var cap = new MbAdapt.Cap({
    container: "cap-container",
    automationId: "my-automation",
    client: MbAdapt.createConnectClient({ id: "my-automation" }),
    onSolve: function (token) {
      client.run({ challengeToken: token });
    },
  });
</script>

Error handling

import { ConnectError, Code } from "@mochabug/adapt-core";

try {
  await client.run();
} catch (e) {
  if (e instanceof ConnectError) {
    console.error(e.code, e.message); // e.g. Code.NotFound
  }
}

Retriable errors (network failures, server overload) are retried automatically with exponential backoff. Non-retriable errors (NotFound, PermissionDenied, Unauthenticated, InvalidArgument, FailedPrecondition, ResourceExhausted) are thrown immediately.

Entry points

| Export | Description | |--------|-------------| | @mochabug/adapt-core | Client, types, configuration | | @mochabug/adapt-core/connect | createConnectClient — browser transport | | @mochabug/adapt-core/grpc | createGrpcClient — Node.js transport |

License

ISC © mochabug AB