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/sdkRequires 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:
| Group | Methods | Routes |
|---|---|---|
mc.auth | register, login, me | /auth/register, /auth/login, /auth/me |
mc.templates | list, canvas, bpmn (bundled example graphs, by name) | /process-templates/, /process-templates/{vertical}/canvas, /process-templates/{vertical}/bpmn |
mc.connectors | list, upsert, test, delete | /connectors/, /connectors/{tool_id} (+ /test) |
mc.runs | start, 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
- API reference — every operation and model, generated from the OpenAPI schema.
- Run a governed process — the start → park → resume loop in depth.