TypeScript client reference

VerdictClient connects your TypeScript or JavaScript application to a Verdict instance to check authorization decisions, query policy rules, mutate facts, and manage active policies.

This reference covers the public root exports of @marcporciuncula/verdict-client. Generated protobuf transport definitions under ./proto are internal to the package and outside this reference.

import { VerdictClient, identity } from "@marcporciuncula/verdict-client";

const client = new VerdictClient({
  instanceUrl: "https://your-instance.example.com",
  apiKey: "your-instance-key",
});

const allowed = await client.authorize(
  identity("User", "alice"),
  "read",
  identity("Document", "handbook"),
);

Configure VerdictClient with the URL and bearer credential issued for your instance. Your active .vd policy determines which (actor, action, resource) checks resolve to true.

Core operations

• VerdictClient documents the client constructor, read and mutation methods (authorize, query, insertFact, deleteFact, batchFacts, listFacts, setPolicy, getPolicy), observed revision, routing sessionId, and session().
• VerdictClientOptions documents connection settings, consistency defaults, wire format ("proto" or "json"), HTTP 503 backoff, and mutation timeout bounds.
• FactInput, PatternInput, and ListFilterInput define the tuple and object shapes used to supply facts, evaluate or delete patterns, and filter stored facts.
• IntegerMode, ResultTerm, and IntegerRepresentationError define how 64-bit integers are decoded in responses.
• Client sessions, consistency, and retries explains observed revisions, read consistency modes (session, eventual, authoritative), request scoping with client.session(), and automatic mutation retries and timeouts.

Queries, fact filters, and wildcards

VerdictClient provides two ways to inspect state:

• query evaluates your policy rules and returns derived rows for each unbound position in a PatternInput.
• listFacts inspects only stored facts matching an optional ListFilterInput and does not evaluate derived rules.

In patterns passed to query, deleteFact, and listFacts, pass a concrete term to match an exact value, null for an anonymous wildcard matching any term, or a { wildcard: { type?, name? } } object to restrict the match by type or bind repeated variable names to equal values.

Handling 64-bit integers

Verdict represents integers as signed 64-bit values (int64):

• Inputs: JavaScript number arguments must be safe integers (Number.isSafeInteger). Pass a bigint when supplying values across the full signed 64-bit integer range.
• Outputs: By default (integerMode: "number"), decoded integers in ResultTerm are returned as number, and any response integer outside the safe integer range throws IntegerRepresentationError. Configure integerMode as "bigint" (always return bigint) or "adaptive" (return number when safe and bigint otherwise) when query or fact results can exceed Number.MAX_SAFE_INTEGER.

Related guides

Each generated reference page links directly to the TypeScript source comments that define the contract.

For end-to-end backend integration patterns, see Integrate with your app, Managing Facts, and Enforcing Decisions & Querying. For .vd policy syntax and modeling, see Policy Fundamentals and Designing Policies.