TypeScript SDK - Rotascale

npm install @rotascale/sdk

Configuration

import { Rotascale } from "@rotascale/sdk";

const rs = new Rotascale();                      // reads the environment
const rs2 = new Rotascale({ baseUrl: "...", apiKey: "..." });

The environment variable differs from the Python SDK, and one of them is going to trip you up. TypeScript reads ROTASCALE_API_URL. Python reads ROTASCALE_URL. Set both if you run both in the same deployment.

TypeScript also falls back to https://api.rotascale.com when neither is set, and there is no such deployment. RotaGrant runs single-tenant inside your environment, so a default hosted URL cannot be right for anybody. Set baseUrl or ROTASCALE_API_URL explicitly; the Python SDK raises instead, which is the better behaviour of the two.

Option	Default
`baseUrl`	`ROTASCALE_API_URL`, then a hosted URL that does not exist
`apiKey`	`ROTASCALE_API_KEY`
`enforcementTimeoutMs`	short: enforcement is on the hot path
`captureTimeoutMs`	longer: capture is off the critical path by construction
`failOpenEnforcement`	off, and it logs every time it is used

Authorising an action

Options object rather than positional arguments, which is the one deliberate divergence from the Python shape.

const decision = await rs.authorize({
  grantId: "grt_01KZXYD62VG0",
  scope: { tool: ["payments.settle"] },
  amountMinor: 25_000_00,
  currency: "EUR",
  trajectoryId: t.id,
});

if (decision.allowed) await settle();

throwOnRefusal is on by default, so the unsafe path is one you write deliberately rather than get by forgetting to check a return value.

Handling refusals

import { Blocked, Exhausted, Gated, ReviewRequired,
         EnforcementUnavailable, RequestRefused } from "@rotascale/sdk";

try {
  await rs.authorize({ grantId, scope: { tool: ["payments.settle"] },
                       amountMinor: 25_000_00, currency: "EUR" });
  await settle();
} catch (err) {
  if (err instanceof Exhausted) escalate("ceiling reached");
  else if (err instanceof Gated) escalate("context not clean");
  else if (err instanceof ReviewRequired) park(err.reviewId);
  else if (err instanceof Blocked) stop();
  else if (err instanceof EnforcementUnavailable) stop();
  else throw err;
}

Exhausted and Gated extend Blocked, so check them before Blocked. An instanceof Blocked branch placed first swallows all three and you lose the only field that tells you what to do next.

RequestRefused is TypeScript-only and covers a malformed request rather than a governance decision. It has no Python counterpart because the Python client raises the underlying HTTP error.

Trajectories and middleware

import { witness, watchOpenAI, watchAnthropic, watchMcp } from "@rotascale/sdk";

await witness(rs, { agent: "refund-assistant", ticket: "TICKET-98130" }, async (t) => {
  const openai = watchOpenAI(client, t);
  await openai.chat.completions.create({ /* ... */ });

  await t.authorize({ grantId, scope: { tool: ["billing.refund"] },
                      amountMinor: 1200, currency: "EUR" });
});

currentTrajectory() reaches the active trajectory without threading it through every function. As in Python, middleware records and does not authorise. Only your code knows which action is consequential. See Framework middleware.

What it deliberately does not do

No governance fact is derived client-side. enforcing and suppressed read fields the server sends; there is no second opinion about what a refusal means, because two SDKs disagreeing about that is worse than either being wrong alone.

​Configuration

​Authorising an action

​Handling refusals

​Trajectories and middleware

​What it deliberately does not do

Configuration

Authorising an action

Handling refusals

Trajectories and middleware

What it deliberately does not do