Skip to main content

JavaScript SDK Overview

The JavaScript SDK is the primary integration layer for JavaScript applications using Actra.

It provides a clean three-layer architecture:

Actra         -> load & compile policies
Policy        -> compiled policy artifact
ActraRuntime  -> runtime enforcement

This gives JavaScript teams a deterministic path from YAML policy files to protected function execution.

Installation​

npm install @getactra/actra

Fastest Happy Path​

The fastest way to get started, is loading a policy directory.

import { Actra, ActraRuntime } from "@getactra/actra"

const policy = await Actra.fromDirectory("./policy")
const runtime = new ActraRuntime(policy)

This flow:

  1. loads schema, policy, and optional governance files
  2. compiles them into a native policy artifact
  3. creates a reusable runtime instance

SDK Architecture​

1) Compiler Layer​

The compiler layer converts YAML into a reusable Policy artifact.

From YAML Strings​

const policy = await Actra.fromStrings(
  schemaYaml,
  policyYaml,
  governanceYaml,
)

From Individual Files​

const policy = await Actra.fromFiles(
  "./policy/schema.yaml",
  "./policy/policy.yaml",
  "./policy/governance.yaml",
)

From Policy Directory​

const policy = await Actra.fromDirectory("./policy")

This is the recommended production setup for:

  • monorepos
  • governed policy repos
  • CI validation
  • multi-team ownership

2) Policy Artifact Layer​

The compiled Policy is a reusable runtime-safe artifact.

const decision = policy.evaluate({
  action: { type: "refund", amount: 1000 },
  actor: { role: "support" },
  snapshot: { is_locked: false },
})

The policy layer supports:

  • deterministic evaluation
  • policy hashing
  • explain debugging
  • assertion helpers
  • schema access

3) Runtime Enforcement Layer​

The runtime protects functions before execution.

async function refund(paymentId: string) {
  return "ok"
}

const protectedRefund = runtime.admit("refund", refund)

When called, the runtime:

  1. builds action payload
  2. resolves actor context
  3. resolves snapshot state
  4. evaluates matching rules
  5. executes or blocks

Resolver Model​

Actor Resolver​

runtime.setActorResolver((ctx) => ({
  role: ctx.user.role,
}))

Use actor resolvers for:

  • JWT claims
  • service identity
  • workflow caller
  • AI agent identity

Snapshot Resolver​

runtime.setSnapshotResolver((ctx) => ({
  is_locked: ctx.account.locked,
}))

Use snapshot resolvers for:

  • database state
  • Redis flags
  • fraud checks
  • deployment safety
  • workflow approvals

Runtime Decision Helpers​

For lightweight checks:

runtime.allow("refund", { amount: 100 })
runtime.block("refund", { amount: 100 })
runtime.requiresApproval("refund", { amount: 100000 })

For full decision access:

const decision = runtime.check("refund", { amount: 1000 })

Protecting Functions​

The most common production pattern is function protection.

const guardedRefund = runtime.admit("refund", async function refund(orderId: string) {
  return { ok: true }
})

If blocked, the runtime throws ActraPolicyError.

If approval is required, the same error contains the decision payload.

Non-Blocking Audit Mode​

For observability-only workflows:

const auditedRefund = runtime.audit("refund", refund)

This always executes the function while still producing policy decisions.

Ideal for:

  • shadow rollout
  • dry runs
  • migration safety
  • policy tuning

Explain & Debugging​

Use explain APIs for debugging live decisions.

runtime.explain({
  type: "refund",
  amount: 5000,
})

Or explain an upcoming function call:

runtime.explainCall(refund, {
  args: ["order_123"],
  actionName: "refund",
})

Production Mental Model​

YAML files -> Actra -> Policy -> Runtime -> admit()

This is the core JavaScript integration pipeline.

Common Use Cases​

  • API route protection
  • background workers
  • queue consumers
  • cron jobs
  • deployment automation
  • AI tool execution
  • workflow steps

Next Steps​

  • Learn Compiler API
  • Explore Policy Artifact API
  • Deep dive into Runtime API
  • Build Actor Resolvers
  • Add Snapshot Resolvers
  • Use Explain & Debugging