Minctrl Docs
SDKs

TypeScript SDK

A typed, fetch-based TypeScript client for the Minctrl API — run the governed start → park → resume loop from Node or the browser.

The TypeScript SDK (@minctrl/sdk) is a thin, typed client over the global fetch. Each method is one API route, grouped as auth, templates, connectors, and runs, and its request-body types are generated from the OpenAPI schema. It covers part of the API reference; the gaps are listed below.

Install

npm install @minctrl/sdk

Requires Node 20+ or any runtime with a global fetch. ESM and CommonJS builds and full type declarations are shipped — no runtime dependencies.

Not wrapped yet: your own processes

The SDK was written when Minctrl shipped built-in processes. It does not yet wrap importing or saving a process (POST /process-templates/import, POST /process-templates/, GET /process-templates/drafts), and its generated StartRun type has no draft field. mc.templates reads only the bundled example graphs by name. Import over HTTP (see the Quickstart), then start the run with draft: true as below — the client sends the body as given.

Quickstart

Create a client, authenticate, and run the governed cycle on a process already saved in your company (here the imported aml example): a run proceeds on its own until governance parks it on a gate, then you resume it on that gate.

import { createMinctrl, type StartRun } from "@minctrl/sdk";

const mc = createMinctrl({ baseUrl: "https://app.minctrl.com" });

// Authenticate — attach the returned token to the client.
const { token } = await mc.auth.login({
  email: "[email protected]",
  password: "<your-password>",
});
mc.setToken(token!);

// Start a run of your saved process. `draft: true` is not in the generated type yet.
const run = await mc.runs.start({
  vertical: "aml",
  draft: true,
  inputs: { customer_name: "Jane Q. Public", risk: "high" },
} as StartRun);

// The run parks when governance needs a person. trace.parked_step is the step-id to sign.
const trace = run.trace as { parked_step?: string } | undefined;
if (run.status === "awaiting_human" && trace?.parked_step) {
  await mc.runs.resume(run.id!, { gate: trace.parked_step, decision: "onboarding approved" });
}

Which gate to name

runs.resume(...) takes the step-id the run parked on (trace.parked_step) or its parked_at label. The run id is run.id; the run_id and parked_gate fields of the SDK's ProcessRun type are not returned by the API. Check status after a resume: a gate or decision that matches nothing leaves the run parked where it was.

Irreversible tools stay shadowed

Even with auto_resolve: true (the default), a connector bound to an irreversible tool-id runs in shadow — no real call is made — unless its config sets reversible: true. The autopilot never fires a live irreversible action on your behalf.

Client surface

Every group maps onto these routes:

GroupMethodsRoutes
mc.authregister, login, me/auth/register, /auth/login, /auth/me
mc.templateslist, canvas, bpmn (bundled example graphs, by name)/process-templates/, /process-templates/{vertical}/canvas, /process-templates/{vertical}/bpmn
mc.connectorslist, upsert, test, delete/connectors/, /connectors/{tool_id} (+ /test)
mc.runsstart, get, resume, list/process-runs/, /process-runs/{run_id} (+ /resume)

The client always sends and expects JSON, sets Authorization: Bearer <token> when a token is present, follows redirects, and throws a typed MinctrlError (with .status and .body) on any non-2xx response.

Binding a connector

Bind a process tool-id to one of your own HTTP endpoints. Keep reversible: false so an irreversible screen stays shadowed until you explicitly opt in.

await mc.connectors.upsert("sanctions-screen", {
  base_url: "https://screening.vendor.com",
  method: "POST",
  path: "/v1/screen",
  auth_type: "bearer",
  auth_token: "<your-token>",
  body_map: { full_name: "customer_name" },
  signal_rule: { path: "match_score", op: "lt", value: 0.85, pass: "clear", fail: "hit" },
  reversible: false,
});

Authentication

Every method except auth.register and auth.login requires a bearer token. Set it at construction or after logging in — the SDK sends it as Authorization: Bearer <token> on each request:

// At construction:
const mc = createMinctrl({ baseUrl: "https://app.minctrl.com", token: "<token>" });

// Or after login/register:
const { token } = await mc.auth.login({ email: "[email protected]", password: "<your-password>" });
mc.setToken(token!);

With an API key

A script or an integration uses a company API key instead of a person's session — createMinctrl({ baseUrl, apiKey: "mk_live_…" }). A key never signs a gate. See API keys and service accounts.

Triggers

mc.triggers lists, creates, updates, rotates and deletes webhook and schedule triggers — with an owner's session or a key that has triggers:manage. A webhook's url and a generated secret are in the create response only. See Triggers.

Test suites

mc.tests.run(slug, version) runs a process's test suite against a version (a key needs processes:test); suitePassed(run) is true only for a passed run. runs, result and cases read (processes:read); compare(slug, a, b) lines up two versions. See Testing processes.

See also

On this page