TypeScript SDK

Install and configure

The TypeScript SDK is a typed transport for the Rulebook API. It carries decisions, evidence, obligations and receipts from the runtime without reimplementing policy logic in application code.

Create one client for each trust boundary. The credential determines what the caller may access. The evidenceScope option narrows the response type so a decision-only client cannot reach verbatim policy quotes.

npm install @avery-rulebook/sdk

import { AveryClient } from "@avery-rulebook/sdk";

const avery = new AveryClient({
  baseUrl: process.env.AVERY_URL ?? "http://localhost:7171",
  apiKey: process.env.AVERY_TOKEN,
  evidenceScope: "evidence",
});

Make a governed decision

Use decide when the application knows the action it proposes and the facts available at that point. Handle every outcome explicitly. A missing fact or an unresolved conflict is a review state, not permission to continue.

const decision = await avery.decide({
  rulebook: "data-handling",
  action: "customer_record.share",
  facts: {
    region: "EU",
    purpose: "support",
    partnerApproved: true,
  },
});

switch (decision.outcome) {
  case "yes":
    console.log("Allowed", decision.receiptId);
    break;
  case "no":
    throw new Error("Policy denied this action");
  case "needs-review":
    throw new Error(
      "Review required: " + decision.needsReview.missingFacts.join(", "),
    );
  case "no-rule-applies":
    throw new Error("No confirmed rule governs this action");
}

Gate a side effect

The gateway hook is the shortest path to an enforced integration. It checks the proposed tool call, returns the original or policy-transformed arguments when permitted, and throws on denial or required approval. Keep the protected operation behind this function so there is no alternate route around the gate.

const guard = avery.gateway.hook({
  caller: { agent: "agt_support_01" },
  context: { environment: process.env.NODE_ENV ?? "development" },
});

async function shareCustomerRecord(input: Record<string, unknown>) {
  const checked = await guard("crm.share_customer_record", input);

  // Only checked.args may cross the action boundary.
  const result = await crm.shareCustomerRecord(checked.args);
  return { result, receiptId: checked.receiptId };
}

Declare the answer ceiling

The caller can limit how high Rulebook may climb on the answer ladder. strict accepts T0 only. fast, balanced and best admit progressively higher tiers. The SDK also rejects a response above the declared ceiling on the client side.

• strict: T0 only
• fast: up to T1 bounded judgment
• balanced: up to T2 validated plans
• best: up to T3 labelled explanation

const deterministic = avery.strict();
const balanced = avery.at("balanced");

const decision = await deterministic.decide({
  rulebook: "access-control",
  action: "repository.write",
  facts: { actorRole: "contractor", repository: "production" },
});