@zapier/policy-context

Shared request-context types, builders, and policy condition generators — the canonical encoding of a request (HTTP, action, connection) into the shape the policy engine expects. This is the TypeScript port; the same contract is (or will be) implemented in Python and Go in this repo and kept byte-identical via the shared fixtures/.

Install

npm install @zapier/policy-context zod

zod (v4+) is a peer dependency.

What it provides

Four layers, each building on the previous:

1. Types — Zod schemas for HttpRequestContext, ActionRunContext, and the RequestContext discriminated union. The canonical shapes stored in approvalsapi and sent by sdkapi.
2. Builders — Normalize raw request parts (URL parsing, header filtering, body coercion) into validated contexts.
3. Conditions / Policies — Convert stored contexts into @zapier/policy-schema Condition[] and full v3 Policy documents with one statement tier and randomly generated UUID statement IDs prefixed with s_.
4. Zapier policy validation — ZapierPolicySchema composes the generic PolicySchema with Zapier resource grammar and permission/resource rules.

Usage

Build a request context

import { buildHttpRequestContext } from "@zapier/policy-context";

const context = buildHttpRequestContext({
  method: "POST",
  url: "https://api.example.com/v1/messages",
  headers: { "content-type": "application/json", authorization: "Bearer …" },
  body: '{"text":"hello"}',
});

buildHttpRequestContext normalizes the URL, filters headers through IGNORED_HEADERS (auth, cookies, etc.), and validates the result with Zod.

Generate policy conditions

import {
  buildExactHttpConditions,
  buildDomainHttpConditions,
} from "@zapier/policy-context";

const exact = buildExactHttpConditions(context); // matches this exact request
const domain = buildDomainHttpConditions(context); // matches any request to the same host

Build a complete "allow this exact request" policy

import { toExactPolicy } from "@zapier/policy-context";

const policy = toExactPolicy(context);

Policy builders emit version 3 policies with a single statement tier.

Connection-scoped policies

import { buildConnectionPolicy } from "@zapier/policy-context";

const policy = buildConnectionPolicy({
  connectionId: "conn_123",
  accessLevel: "read_only",
});

Validate a Zapier policy

import { ZapierPolicySchema } from "@zapier/policy-context";

const policy = ZapierPolicySchema.parse(input);

This accepts http, connection/{id|*}, canonical action/{selected_api}/{action_type|*}/{action_key} patterns, and the lone * god-mode resource. It validates structure only; app, API version, and action-key existence remain the caller's responsibility. It also rejects a statement when one higher-precedence statement (deny > ask > allow) fully subsumes it. For v3 policies, validation traverses each ordered tier and masking is checked only within that tier. Same-effect redundancy and coverage assembled from multiple statements remain valid.

License

Published as part of Zapier's services. Use is governed by the Zapier Terms of Service — see LICENSE.