Zap Studio

https://github.com/zap-studio/monorepo
Admin
Type-safe, framework-agnostic, composable, and tree-shakeable TypeScript libraries for the web.
Tokens:53,528
Snippets:645
Trust Score:7.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Quick Start with @zap-studio/fetch

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/index.mdx

Demonstrates initializing a fetch client with a logger and performing a validated GET request using a Zod schema.

```ts
import { ConsoleLogger } from "@zap-studio/logger";
import { createFetch } from "@zap-studio/fetch";
import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.email(),
});

const logger = new ConsoleLogger({ minLevel: "debug" });
const { api } = createFetch({ logger });

const user = await api.get("https://api.example.com/users/1", UserSchema);

console.log(user.name); // typed as string, validated at runtime
```

--------------------------------

### Install @zap-studio/permit

Source: https://github.com/zap-studio/monorepo/blob/main/packages/permit/README.md

Install the package using npm.

```bash
npm install @zap-studio/permit
```

--------------------------------

### Install @zap-studio/fetch

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/getting-started.mdx

Install the package using your preferred package manager.

```bash
npm install @zap-studio/fetch
```

```bash
yarn add @zap-studio/fetch
```

```bash
pnpm add @zap-studio/fetch
```

```bash
bun add @zap-studio/fetch
```

```bash
deno add jsr:@zap-studio/fetch
```

--------------------------------

### Install @zap-studio/retry

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/retry/getting-started.mdx

Install the package using your preferred package manager.

```npm
npm install @zap-studio/retry
```

```yarn
yarn add @zap-studio/retry
```

```pnpm
pnpm add @zap-studio/retry
```

```bun
bun add @zap-studio/retry
```

```deno
deno add jsr:@zap-studio/retry
```

--------------------------------

### Install @zap-studio/logger

Source: https://github.com/zap-studio/monorepo/blob/main/packages/logger/README.md

Install the package using npm.

```bash
npm install @zap-studio/logger
```

--------------------------------

### Install @zap-studio/webhooks

Source: https://github.com/zap-studio/monorepo/blob/main/packages/webhooks/README.md

Use npm to install the package in your project.

```bash
npm install @zap-studio/webhooks
```

--------------------------------

### Install @zap-studio/webhooks and Zod

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/getting-started.mdx

Install the required packages using your preferred package manager.

```bash
npm install @zap-studio/webhooks zod
```

```bash
yarn add @zap-studio/webhooks zod
```

```bash
pnpm add @zap-studio/webhooks zod
```

```bash
bun add @zap-studio/webhooks zod
```

```bash
deno add jsr:@zap-studio/webhooks npm:zod
```

--------------------------------

### Install Permit package

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/getting-started.mdx

Install the permit library using your preferred package manager.

```bash
npm install @zap-studio/permit
```

```bash
yarn add @zap-studio/permit
```

```bash
pnpm add @zap-studio/permit
```

```bash
bun add @zap-studio/permit
```

```bash
deno add jsr:@zap-studio/permit
```

--------------------------------

### Initialize Webhook Router

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/opentelemetry.mdx

Example of setting up a webhook router which is automatically instrumented for tracing.

```ts
import { createWebhookRouter } from "@zap-studio/webhooks";

const router = createWebhookRouter({ prefix: "/webhooks" });
router.register("/stripe", { schema: stripeEventSchema, handler });

export default { fetch: (request: Request) => router.handle(request) };
```

--------------------------------

### Install @zap-studio/monads

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/monads/getting-started.mdx

Use the appropriate package manager command to add the library to your project.

```npm
npm install @zap-studio/monads
```

```yarn
yarn add @zap-studio/monads
```

```pnpm
pnpm add @zap-studio/monads
```

```bun
bun add @zap-studio/monads
```

```deno
deno add jsr:@zap-studio/monads
```

--------------------------------

### Install @zap-studio/logger

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/getting-started.mdx

Commands to install the logger package using various package managers.

```npm
npm install @zap-studio/logger
```

```yarn
yarn add @zap-studio/logger
```

```pnpm
pnpm add @zap-studio/logger
```

```bun
bun add @zap-studio/logger
```

```deno
deno add jsr:@zap-studio/logger
```

--------------------------------

### Install the package

Source: https://github.com/zap-studio/monorepo/blob/main/packages/validation/README.md

Use npm to add the validation package to your project.

```bash
npm install @zap-studio/validation
```

--------------------------------

### Setup Resources, Actions, and Context

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/conditions.mdx

Initializes the Zod schemas for resources, defines allowed actions, and sets up the application context type.

```ts
import { z } from "zod";
import type { Resources, Actions } from "@zap-studio/permit";

const resources = {
  post: z.object({
    id: z.string(),
    authorId: z.string(),
    status: z.enum(["draft", "published", "archived"]),
    reportedBy: z.array(z.string()),
  }),
  document: z.object({
    id: z.string(),
    ownerId: z.string(),
    status: z.enum(["active", "archived"]),
    isLocked: z.boolean(),
    sharedWith: z.array(z.string()),
  }),
} satisfies Resources;

const actions = {
  post: ["edit", "like", "comment", "report"],
  document: ["read", "edit"],
} as const satisfies Actions<typeof resources>;

type AppContext = {
  user: { id: string; role: "guest" | "user" | "admin" } | null;
};
```

--------------------------------

### Install @zap-studio/validation

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/validation/getting-started.mdx

Use your preferred package manager to add the validation library to your project.

```bash
npm install @zap-studio/validation
```

```bash
yarn add @zap-studio/validation
```

```bash
pnpm add @zap-studio/validation
```

```bash
bun add @zap-studio/validation
```

```bash
deno add jsr:@zap-studio/validation
```

--------------------------------

### Define Resources, Actions, and Context

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/declarative-policies.mdx

Setup the base types and schemas required for policy definitions.

```ts
import { z } from "zod";
import type { Resources, Actions } from "@zap-studio/permit";

const resources = {
  post: z.object({
    id: z.string(),
    authorId: z.string(),
    visibility: z.enum(["public", "private"]),
  }),
} satisfies Resources;

const actions = {
  post: ["read", "write", "delete"],
} as const satisfies Actions<typeof resources>;

type AppContext = {
  user: { id: string; role: "guest" | "user" | "admin" } | null;
};

```

--------------------------------

### Install OpenTelemetry API dependency

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/opentelemetry.mdx

Install the required peer dependency for OpenTelemetry support.

```npm
npm install @opentelemetry/api
```

```yarn
yarn add @opentelemetry/api
```

```pnpm
pnpm add @opentelemetry/api
```

```bun
bun add @opentelemetry/api
```

```deno
deno add npm:@opentelemetry/api
```

--------------------------------

### Quick Start with exponentialBackoff

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/retry/index.mdx

Demonstrates initializing an exponential backoff policy and executing it with a fetch request using the runRetryPolicy runner.

```ts
import { ConsoleLogger } from "@zap-studio/logger";
import { exponentialBackoff, runRetryPolicy } from "@zap-studio/retry";
import { $fetch } from "@zap-studio/fetch";

const logger = new ConsoleLogger({ minLevel: "debug" });

const policy = exponentialBackoff({
  maxAttempts: 5,
  baseDelayMs: 100,
  maxDelayMs: 2_000,
});

const data = await runRetryPolicy(
  policy,
  async () => {
    const response = await $fetch("https://api.example.com/users", {
      throwOnFetchError: true,
    });
    return await response.json();
  },
  { logger }
);
```

--------------------------------

### Usage

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/scaling-policies.mdx

Example of checking permissions using the composed policy.

```ts
import { policy } from "./policies/index.js";

await policy.can(ctx, "post:read", post);
await policy.can(ctx, "comment:write", comment);
```

--------------------------------

### Configuring Built-in Retry Policies

Source: https://github.com/zap-studio/monorepo/blob/main/packages/retry/README.md

Examples of initializing fixed delay, linear backoff, and exponential backoff policies.

```ts
import {
  exponentialBackoff,
  fixedDelay,
  linearBackoff,
} from "@zap-studio/retry";

const exponential = exponentialBackoff({
  maxAttempts: 5,
  baseDelayMs: 100,
  maxDelayMs: 2_000,
});
const linear = linearBackoff({
  maxAttempts: 5,
  baseDelayMs: 100,
  incrementMs: 100,
  maxDelayMs: 2_000,
});
const fixed = fixedDelay({ maxAttempts: 4, delayMs: 300 });
```

--------------------------------

### OpenTelemetry Integration

Source: https://github.com/zap-studio/monorepo/blob/main/packages/fetch/README.md

Install the required peer dependency and use the fetch client to automatically generate spans and inject trace context.

```bash
npm install @opentelemetry/api
```

```ts
import { createFetch } from "@zap-studio/fetch";

const { api } = createFetch({ baseURL: "https://api.example.com" });

// If your app has registered an OpenTelemetry SDK, this call now produces a
// CLIENT span and injects `traceparent` into the outgoing request headers.
// If not, it's a no-op — no wiring required either way.
await api.get("/users/1", UserSchema);
```

--------------------------------

### Integrate OpenTelemetry

Source: https://github.com/zap-studio/monorepo/blob/main/packages/webhooks/README.md

Install the required peer dependency and register routes to enable automatic span generation for webhook deliveries.

```bash
npm install @opentelemetry/api
```

```ts
import { createWebhookRouter } from "@zap-studio/webhooks";

const router = createWebhookRouter({ prefix: "/webhooks" });
router.register("/stripe", { schema: stripeEventSchema, handler });

// If your app has registered an OpenTelemetry SDK, router.handle(request)
// now produces a SERVER span per delivery (continuing the sender's trace
// when a traceparent header is present) and an INTERNAL span per handler
// dispatch. If not, it's a no-op — no wiring required either way.
export default { fetch: (request: Request) => router.handle(request) };
```

--------------------------------

### Log output with trace context

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/opentelemetry.mdx

Example of the JSON structure when trace_id and span_id are automatically injected.

```json
{
  "userId": "u1",
  "trace_id": "4bf92f...",
  "span_id": "00f067...",
  "level": "info",
  "msg": "checkpoint"
}
```

--------------------------------

### Define schemas for supported validators

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/validation.mdx

Examples of defining schemas using Zod, Valibot, and ArkType.

```ts
import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});
```

```ts
import * as v from "valibot";

const UserSchema = v.object({
  id: v.number(),
  name: v.string(),
});
```

```ts
import { type } from "arktype";

const UserSchema = type({
  id: "number",
  name: "string",
});
```

--------------------------------

### api.get(url, schema, options)

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/api-methods.mdx

Performs a GET request and validates the response body against the provided schema.

```APIDOC
## GET [url]

### Description
Performs a GET request to the specified URL and validates the response body against the provided Zod schema.

### Method
GET

### Parameters
- **url** (string) - Required - The target URL.
- **schema** (ZodSchema) - Optional - The schema to validate the response body against.
- **options** (object) - Optional - Configuration options including searchParams, throwOnFetchError, and throwOnValidationError.
```

--------------------------------

### Define a Zod schema

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/validation/create-validators.mdx

The base schema used for all validation examples.

```ts
import { z } from "zod";

const userSchema = z.object({
  name: z.string(),
  age: z.number(),
});
```

--------------------------------

### Initialize a policy with @zap-studio/permit

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/index.mdx

Defines resources, actions, and a policy object to evaluate permissions based on user context and resource ownership.

```ts
import { z } from "zod";
import { ConsoleLogger } from "@zap-studio/logger";
import { createPolicy, allow, deny, when } from "@zap-studio/permit";
import type { Resources, Actions } from "@zap-studio/permit";

const resources = {
  post: z.object({ id: z.string(), authorId: z.string() }),
} satisfies Resources;

const actions = {
  post: ["read", "write", "delete"],
} as const satisfies Actions<typeof resources>;

type AppContext = { user: { id: string } };

const logger = new ConsoleLogger({ minLevel: "debug" });

const policy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    post: {
      read: allow(),
      write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
      delete: deny(),
    },
  },
  logger,
});

const ctx: AppContext = { user: { id: "user-1" } };
const post = { id: "1", authorId: "user-1" };

await policy.can(ctx, "post:write", post); // true, inferred as boolean
```

--------------------------------

### createFetch(options)

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/create-fetch.mdx

Initializes a new fetch client instance with shared configuration defaults.

```APIDOC
## createFetch(options)

### Description
Creates a fetch client with shared `baseURL`, headers, query params, and error defaults. It returns an independent `$fetch` function and `api` method set bound to those defaults.

### Parameters
- **baseURL** (string) - Optional - Base URL that relative request URLs are resolved against.
- **headers** (HeadersInit) - Optional - Default headers merged into every request.
- **searchParams** (URLSearchParams init) - Optional - Default query params applied to every request.
- **throwOnFetchError** (boolean) - Optional - Default for throwing `FetchError` on non-2xx responses.
- **throwOnValidationError** (boolean) - Optional - Default for throwing `ValidationError` on validation issues.

### Usage Example
```ts
import { createFetch } from "@zap-studio/fetch";

const { api, $fetch } = createFetch({
  baseURL: "https://api.example.com",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const user = await api.get("/users/1", UserSchema);
```
```

--------------------------------

### Initialize fetch with OpenTelemetry

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/opentelemetry.mdx

Tracing is enabled by default upon initialization and requires no additional configuration.

```ts
import { createFetch } from "@zap-studio/fetch";

const { api } = createFetch({ baseURL: "https://api.example.com" });

await api.get("/users/1", UserSchema);
```

--------------------------------

### Read Data with api.get

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/api-methods.mdx

Perform a GET request and validate the response body against a Zod schema.

```ts
import { api } from "@zap-studio/fetch";
import { z } from "zod";

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
});

const user = await api.get("https://api.example.com/users/1", UserSchema);
```

--------------------------------

### createWebhookRouter(options)

Source: https://github.com/zap-studio/monorepo/blob/main/packages/webhooks/README.md

Initializes a new webhook router instance with optional configuration for signature verification and error handling.

```APIDOC
## createWebhookRouter(options)

### Description
Creates a router instance. You can provide a custom verification function or use the built-in HMAC verifier.

### Parameters
- **options** (object) - Optional
  - **verify** (function) - Optional - A function to verify the request signature.
  - **onError** (function) - Optional - A callback to handle errors, such as VerificationError.
```

--------------------------------

### Basic Usage of createFetch

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/create-fetch.mdx

Initialize a client with a base URL and default headers, then perform requests using the returned api and $fetch instances.

```ts
import { createFetch } from "@zap-studio/fetch";
import { z } from "zod";

const UserSchema = z.object({ id: z.number(), name: z.string() });

const { api, $fetch } = createFetch({
  baseURL: "https://api.example.com",
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
  },
});

const user = await api.get("/users/1", UserSchema);
const health = await $fetch("/health");
```

--------------------------------

### Initialize Webhook Router

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/standard-schema.mdx

Create a new webhook router instance using the @zap-studio/webhooks package.

```ts
import { createWebhookRouter } from "@zap-studio/webhooks";

const router = createWebhookRouter();
```

--------------------------------

### Configured Clients

Source: https://github.com/zap-studio/monorepo/blob/main/packages/fetch/README.md

Creates a reusable client instance with shared base URLs, headers, and configuration.

```ts
import { createFetch } from "@zap-studio/fetch";

const { api } = createFetch({
  baseURL: "https://api.example.com",
  headers: { Authorization: `Bearer ${token}` },
});

const user = await api.get("/users/1", UserSchema);
```

--------------------------------

### Initialize and Register a Webhook Router

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/index.mdx

Demonstrates creating a router instance with a logger and registering a route with a Zod schema for payload validation.

```ts
import { ConsoleLogger } from "@zap-studio/logger";
import { createWebhookRouter } from "@zap-studio/webhooks";
import { z } from "zod";

const logger = new ConsoleLogger({ minLevel: "debug" });
const router = createWebhookRouter({ prefix: "/webhooks", logger });

router.register("/payments/succeeded", {
  schema: z.object({ id: z.string(), amount: z.number().positive() }),
  handler: ({ payload }) => {
    // payload is inferred from schema
    return Response.json({ processed: payload.id });
  },
});

export default {
  fetch: (request: Request) => router.handle(request),
};
```

--------------------------------

### pipe(value, ...fns)

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/monads/pipe.mdx

Composes multiple functions by passing the result of each function to the next, starting with the initial value.

```APIDOC
## pipe(value, ...fns)

### Description
Performs left-to-right function composition. Each function in the chain receives the previous function's return value, effectively executing `h(g(f(value)))` for `pipe(value, f, g, h)`.

### Signature
`pipe<T>(value: T, ...fns: Array<(arg: any) => any>): any`

### Parameters
- **value** (any) - The initial value to be passed through the chain.
- **...fns** (Array<(arg: any) => any>) - A sequence of functions to apply to the value.

### Example
```ts
import { pipe } from "@zap-studio/monads";

pipe(
  5,
  (n) => n + 1,
  (n) => n * 2
); // 12
```
```

--------------------------------

### Initialize the Webhook Router

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/getting-started.mdx

Configure the router with a path prefix to handle incoming requests.

```typescript
import { createWebhookRouter } from "@zap-studio/webhooks";

const router = createWebhookRouter({
  prefix: "/webhooks", // default
});
```

--------------------------------

### createWebhookRouter

Source: https://github.com/zap-studio/monorepo/blob/main/packages/webhooks/README.md

Initializes a new webhook router instance with optional lifecycle hooks, logging, and route prefixes.

```APIDOC
## createWebhookRouter(options)

### Description
Creates a router instance to handle incoming webhook requests. Supports lifecycle hooks for request processing and integration with logging utilities.

### Parameters
- **before** (function) - Optional - Hook executed before the handler.
- **after** (function) - Optional - Hook executed after the handler.
- **onError** (function) - Optional - Hook executed when an error occurs.
- **logger** (Logger) - Optional - Logger instance for observing delivery attempts and failures.
- **prefix** (string) - Optional - URL prefix for webhook routes.

### Example
```ts
const router = createWebhookRouter({
  prefix: "/webhooks",
  before: (ctx) => console.log("incoming", ctx.path),
  after: (_ctx, response) => console.log("status", response.status),
  onError: (error) => Response.json({ error: error.message }, { status: 500 }),
  logger
});
```
```

--------------------------------

### ConsoleLogger Initialization

Source: https://github.com/zap-studio/monorepo/blob/main/packages/logger/README.md

Instantiate the ConsoleLogger with optional configuration for minimum log level and output formatting.

```APIDOC
## ConsoleLogger Constructor

### Description
Initializes a new instance of the ConsoleLogger to handle application logging.

### Parameters
- **options** (object) - Optional
  - **minLevel** (string) - Optional - The minimum log level to capture (e.g., "debug").
  - **format** (LogFormatter) - Optional - The formatting function to apply to log records. Defaults to `classicFormat`.

### Usage Example
```ts
import { ConsoleLogger, jsonFormat } from "@zap-studio/logger";

const logger = new ConsoleLogger({ minLevel: "debug", format: jsonFormat });
```
```

--------------------------------

### $fetch(input, options)

Source: https://github.com/zap-studio/monorepo/blob/main/packages/fetch/README.md

Performs a raw fetch request that behaves like the native fetch API and returns a Response object.

```APIDOC
## $fetch(input, options)

### Description
Executes a standard HTTP request using the native fetch interface.

### Parameters
- **input** (RequestInfo | URL) - Required - The resource URL or Request object.
- **options** (RequestInit) - Optional - Standard fetch options.

### Returns
- **Response** - The native fetch Response object.
```

--------------------------------

### Create a Policy

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/retry/getting-started.mdx

Configure an exponential backoff policy with specific attempt limits and delay constraints.

```ts
import { exponentialBackoff } from "@zap-studio/retry";

const policy = exponentialBackoff({
  maxAttempts: 5, // total attempts, including the first
  baseDelayMs: 100, // first retry waits 100 ms
  maxDelayMs: 2_000, // later retries never wait longer than 2 s
});
```

--------------------------------

### Implement multiple requirements with and()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/conditions.mdx

Demonstrates combining multiple context-based checks to restrict access to a post.

```ts
import { createPolicy, when, and } from "@zap-studio/permit";

// User must be authenticated AND be the owner AND post must be published
const canEditPublishedPost = and(
  (ctx) => ctx.user !== null,
  (ctx, _, post) => ctx.user?.id === post.authorId,
  (_, __, post) => post.status === "published"
);

const policy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    post: {
      edit: when(canEditPublishedPost),
    },
  },
});
```

--------------------------------

### Configure built-in log formatters

Source: https://github.com/zap-studio/monorepo/blob/main/packages/logger/README.md

Demonstrates how to apply different built-in formatters like jsonFormat, compactFormat, and prettyFormat to the ConsoleLogger.

```ts
import {
  ConsoleLogger,
  jsonFormat,
  compactFormat,
  prettyFormat,
} from "@zap-studio/logger";

new ConsoleLogger({ format: jsonFormat });
// {"port":3000,"time":1704067200000,"level":"info","msg":"server started"}

new ConsoleLogger({ format: compactFormat });
// port=3000 time=2024-01-01T00:00:00.000Z level=info msg="server started"

new ConsoleLogger({ format: prettyFormat });
// 12:34:56.789 INFO  server started   (colored, context inspected as a second arg)
```

--------------------------------

### Initialize and use ConsoleLogger

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/index.mdx

Instantiate the logger with a minimum level and emit logs with optional context objects.

```ts
import { ConsoleLogger } from "@zap-studio/logger";

const logger = new ConsoleLogger({ minLevel: "debug" });

logger.debug("cache miss", { key: "user:42" });
logger.warn("retrying after failure", { attempt: 2 });
```

--------------------------------

### Initialize Runtime-Agnostic Verifier

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/verification.mdx

Uses the Web Crypto API to verify signatures without relying on Node-specific modules.

```ts
// No Node `crypto` import — works wherever globalThis.crypto.subtle exists
const verify = createHmacVerifier({
  headerName: "x-hub-signature-256",
  secret: process.env.WEBHOOK_SECRET!,
});
```

--------------------------------

### Implement multiple access paths with or()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/conditions.mdx

Demonstrates allowing access if any one of several conditions is met.

```ts
import { createPolicy, when, or } from "@zap-studio/permit";

// User can access if they're the owner OR an admin OR explicitly shared
const canAccess = or(
  (ctx, _, doc) => ctx.user?.id === doc.ownerId,
  (ctx) => ctx.user?.role === "admin",
  (ctx, _, doc) => doc.sharedWith.includes(ctx.user?.id ?? "")
);

const policy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    document: {
      read: when(canAccess),
    },
  },
});
```

--------------------------------

### Initialize Fetch with ConsoleLogger

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/logging.mdx

Pass a ConsoleLogger instance to the createFetch configuration to enable request and response logging.

```ts
import { ConsoleLogger } from "@zap-studio/logger";
import { createFetch } from "@zap-studio/fetch";

const logger = new ConsoleLogger({ minLevel: "debug" });
const { api } = createFetch({ baseURL: "https://api.example.com", logger });
```

--------------------------------

### Configuring Search Params

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/create-fetch.mdx

Illustrates the merging order of search parameters between client defaults and per-request options.

```ts
import { createFetch } from "@zap-studio/fetch";
import { z } from "zod";

const UserListSchema = z.array(z.object({ id: z.number(), name: z.string() }));

const { api } = createFetch({
  baseURL: "https://api.example.com",
  searchParams: {
    locale: "en",
    page: "1",
  },
});

await api.get("/users?page=2", UserListSchema, {
  searchParams: {
    q: "ada",
  },
});
// Final URL: https://api.example.com/users?locale=en&page=2&q=ada
```

--------------------------------

### Configure ConsoleLogger with jsonFormat

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/formats.mdx

Initialize the logger with a specific format by passing it to the constructor options.

```ts
import { ConsoleLogger, jsonFormat } from "@zap-studio/logger";

const logger = new ConsoleLogger({ format: jsonFormat });
```

--------------------------------

### Importing deny()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/declarative-policies.mdx

Import the deny function from the @zap-studio/permit package.

```ts
import { deny } from "@zap-studio/permit";
```

--------------------------------

### Log with classicFormat

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/formats.mdx

The default format passes context as a second argument to the console for native inspection.

```ts
logger.info("server started", { port: 3000 });
// console.info("server started", { port: 3000 })
```

--------------------------------

### Basic Usage of $fetch with Zod

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/validated-fetch-mode.mdx

Demonstrates how to use $fetch to automatically parse and validate a JSON response against a Zod schema.

```ts
import { $fetch } from "@zap-studio/fetch";
import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

const user = await $fetch("https://api.example.com/users/1", UserSchema);
```

--------------------------------

### Implement Policy with Multiple Roles

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/roles.mdx

Demonstrates a policy using role hierarchies and multiple roles to control access to resources.

```typescript
import { z } from "zod";
import { createPolicy, when, hasRole, or } from "@zap-studio/permit";
import type { Resources, Actions, RoleHierarchy } from "@zap-studio/permit";

const resources = {
  betaFeature: z.object({
    id: z.string(),
    name: z.string(),
  }),
  supportTicket: z.object({
    id: z.string(),
    userId: z.string(),
    priority: z.enum(["low", "normal", "high", "urgent"]),
  }),
} satisfies Resources;

const actions = {
  betaFeature: ["access"],
  supportTicket: ["create", "escalate"],
} as const satisfies Actions<typeof resources>;

type Role = "user" | "beta-tester" | "premium" | "support-agent" | "admin";

const roleHierarchy: RoleHierarchy<Role> = {
  user: [],
  "beta-tester": ["user"],
  premium: ["user"],
  "support-agent": ["user"],
  admin: ["premium", "support-agent"], // Admin inherits from multiple roles
};

type MultiRoleContext = {
  user: { id: string } | null;
  role: Role[];
};

const multiRolePolicy = createPolicy<MultiRoleContext>({
  resources,
  actions,
  rules: {
    betaFeature: {
      // Only beta testers can access beta features
      access: when(hasRole("beta-tester", roleHierarchy)),
    },
    supportTicket: {
      // Any authenticated user can create tickets
      create: when(hasRole("user", roleHierarchy)),

      // Only premium users or support agents can escalate
      escalate: when(
        or(
          hasRole("premium", roleHierarchy),
          hasRole("support-agent", roleHierarchy)
        )
      ),
    },
  },
});

// User with multiple roles
const betaPremiumUser: MultiRoleContext = {
  user: { id: "u1" },
  role: ["user", "beta-tester", "premium"],
};

const ticket = { id: "t1", userId: "u1", priority: "normal" as const };
const feature = { id: "f1", name: "New Dashboard" };

console.log(
  await multiRolePolicy.can(betaPremiumUser, "betaFeature:access", feature)
); // true (has beta-tester)
console.log(
  await multiRolePolicy.can(betaPremiumUser, "supportTicket:escalate", ticket)
); // true (has premium)
```

--------------------------------

### Apply Condition with when()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/conditions.mdx

Demonstrates the syntax for applying a condition logic within a policy rule.

```ts
when((ctx, action, resource) => /* condition logic */)
```

--------------------------------

### Implement exclusion rules with not()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/conditions.mdx

Shows how to negate conditions to create exclusion-based access rules.

```ts
import { createPolicy, when, not, and } from "@zap-studio/permit";

// Cannot interact with your own content
const isNotOwner = not(
  (ctx, _, resource) => ctx.user?.id === resource.authorId
);

// Content is not archived
const isNotArchived = not((_, __, resource) => resource.status === "archived");

const policy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    post: {
      // Can like any post except your own
      like: when(isNotOwner),

      // Can comment on posts that aren't archived
      comment: when(isNotArchived),

      // Can report posts that: you don't own AND aren't already reported by you
      report: when(
        and(
          isNotOwner,
          (ctx, _, post) => !post.reportedBy.includes(ctx.user?.id ?? "")
        )
      ),
    },
  },
});
```

--------------------------------

### Create Result instances

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/monads/result.mdx

Use ok and err constructors to create Result objects.

```typescript
import { err, ok } from "@zap-studio/monads";

ok(42); // { ok: true, value: 42 }
err("not found"); // { ok: false, error: "not found" }
```

--------------------------------

### Import linearBackoff

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/retry/linear-backoff.mdx

Import the linearBackoff function from the @zap-studio/retry package.

```ts
import { linearBackoff } from "@zap-studio/retry";
```

--------------------------------

### Handle Incoming Requests

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/getting-started.mdx

Integrate the router with various fetch-compatible runtimes and frameworks.

```typescript
// Bun / Deno / Cloudflare Workers
export default {
  fetch: (request: Request) => router.handle(request),
};

// Next.js route handler (app/webhooks/[...path]/route.ts)
export const POST = (request: Request) => router.handle(request);

// Hono
app.all("/webhooks/*", (c) => router.handle(c.req.raw));
```

--------------------------------

### Log with prettyFormat

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/formats.mdx

Provides colorized, human-friendly single-line output.

```ts
logger.info("server started", { port: 3000 });
// 12:34:56.789 INFO  server started   { port: 3000 }   (colored)
```

--------------------------------

### Integrate with Web API Runtimes

Source: https://github.com/zap-studio/monorepo/blob/main/packages/webhooks/README.md

Connect the router to fetch-compatible runtimes like Bun, Deno, Cloudflare Workers, or Next.js.

```ts
// Bun / Deno / Cloudflare Workers
export default { fetch: (request: Request) => router.handle(request) };

// Next.js route handler (app/webhooks/[...path]/route.ts)
export const POST = (request: Request) => router.handle(request);

// Hono
app.all("/webhooks/*", (c) => router.handle(c.req.raw));
```

--------------------------------

### Handling Empty Policy Lists

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/merging-policies.mdx

Merging zero policies results in a policy that always denies access, regardless of the strategy used.

```ts
const emptyAnd = mergePoliciesAnd(); // can() always resolves to false
const emptyOr = mergePoliciesOr(); // can() always resolves to false
```

--------------------------------

### Import allow function

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/declarative-policies.mdx

Import the allow helper from the permit package.

```ts
import { allow } from "@zap-studio/permit";
```

--------------------------------

### Import fixedDelay

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/retry/fixed-delay.mdx

Import the fixedDelay function from the @zap-studio/retry package.

```ts
import { fixedDelay } from "@zap-studio/retry";
```

--------------------------------

### Log with compactFormat

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/formats.mdx

Outputs logs in a machine-parseable logfmt style with key=value pairs.

```ts
logger.info("server started", { port: 3000 });
// port=3000 time=2024-01-01T00:00:00.000Z level=info msg="server started"
```

--------------------------------

### Create a policy

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/getting-started.mdx

Use createPolicy to combine resources, actions, and rules. Rules for individual actions are optional, and actions without defined rules are denied by default.

```ts
import { createPolicy, allow, deny, when } from "@zap-studio/permit";

const policy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    post: {
      read: allow(),
      write: when((ctx, _action, post) => ctx.user?.id === post.authorId),
      delete: deny(),
      publish: when((ctx) => ctx.user?.role === "admin"),
    },
    comment: {
      read: allow(),
      write: when((ctx) => ctx.user !== null),
      delete: when(
        (ctx, _action, comment) => ctx.user?.id === comment.authorId
      ),
    },
  },
});
```

--------------------------------

### Implement Base and Restrictive Policies with AND Merge

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/merging-policies.mdx

Demonstrates combining a base access policy with a security clearance policy using mergePoliciesAnd to enforce strict authorization requirements.

```ts
import { z } from "zod";
import { createPolicy, when, mergePoliciesAnd } from "@zap-studio/permit";
import type { Resources, Actions } from "@zap-studio/permit";

const resources = {
  document: z.object({
    id: z.string(),
    ownerId: z.string(),
    classification: z.enum(["public", "internal", "confidential"]),
  }),
} satisfies Resources;

const actions = {
  document: ["read", "write", "delete"],
} as const satisfies Actions<typeof resources>;

type AppContext = {
  user: { id: string; clearanceLevel: number } | null;
};

// Base policy: standard access rules
const basePolicy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    document: {
      read: when(
        (ctx, _, doc) =>
          doc.classification === "public" || ctx.user?.id === doc.ownerId
      ),
      write: when((ctx, _, doc) => ctx.user?.id === doc.ownerId),
      delete: when((ctx, _, doc) => ctx.user?.id === doc.ownerId),
    },
  },
});

// Security policy: additional clearance requirements
const securityPolicy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    document: {
      read: when((ctx, _, doc) => {
        if (doc.classification === "confidential") {
          return (ctx.user?.clearanceLevel ?? 0) >= 3;
        }
        if (doc.classification === "internal") {
          return (ctx.user?.clearanceLevel ?? 0) >= 1;
        }
        return true;
      }),
      write: when((ctx, _, doc) => {
        if (doc.classification === "confidential") {
          return (ctx.user?.clearanceLevel ?? 0) >= 3;
        }
        return true;
      }),
      delete: when((ctx, _, doc) => {
        if (doc.classification === "confidential") {
          return (ctx.user?.clearanceLevel ?? 0) >= 4;
        }
        return true;
      }),
    },
  },
});

// Merge: both policies must allow
const policy = mergePoliciesAnd(basePolicy, securityPolicy);

// Usage
const confidentialDoc = {
  id: "doc-1",
  ownerId: "user-123",
  classification: "confidential" as const,
};

// Owner with low clearance: base allows, security denies → DENIED
const lowClearanceOwner: AppContext = {
  user: { id: "user-123", clearanceLevel: 1 },
};
console.log(
  await policy.can(lowClearanceOwner, "document:read", confidentialDoc)
); // false

// Owner with high clearance: both allow → ALLOWED
const highClearanceOwner: AppContext = {
  user: { id: "user-123", clearanceLevel: 3 },
};
console.log(
  await policy.can(highClearanceOwner, "document:read", confidentialDoc)
); // true
```

--------------------------------

### Inspecting role inheritance

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/roles.mdx

Demonstrates how to define a RoleHierarchy and resolve inherited roles for various user configurations.

```ts
import { collectInheritedRoles } from "@zap-studio/permit";
import type { RoleHierarchy } from "@zap-studio/permit";

type Role = "guest" | "user" | "moderator" | "admin" | "beta-tester";

const hierarchy: RoleHierarchy<Role> = {
  guest: [],
  user: ["guest"],
  moderator: ["user"],
  admin: ["moderator"],
  "beta-tester": [],
};

// Get all roles for an admin
const adminRoles = collectInheritedRoles(["admin"], hierarchy);
console.log(adminRoles); // Set { "admin", "moderator", "user", "guest" }

// Get all roles for a moderator
const modRoles = collectInheritedRoles(["moderator"], hierarchy);
console.log(modRoles); // Set { "moderator", "user", "guest" }

// Multiple input roles
const mixedRoles = collectInheritedRoles(["user", "beta-tester"], hierarchy);
console.log(mixedRoles); // Set { "user", "guest", "beta-tester" }
```

--------------------------------

### createWebhookRouter

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/lifecycle-hooks.mdx

Configures a webhook router with global lifecycle hooks for request interception and error handling.

```APIDOC
## createWebhookRouter

### Description
Initializes a new webhook router instance with optional global lifecycle hooks. These hooks apply to every route registered with the router.

### Parameters
- **before** (BeforeHook | BeforeHook[]) - Optional - Hook executed before route processing.
- **after** (AfterHook | AfterHook[]) - Optional - Hook executed after successful route processing.
- **onError** (ErrorHook) - Optional - Hook executed when an error occurs during the request lifecycle.

### Request Example
```ts
const router = createWebhookRouter({
  before: (ctx) => { console.log("incoming", ctx.path); },
  after: (_ctx, response) => { console.log("status", response.status); },
  onError: (error) => Response.json({ error: error.message }, { status: 500 }),
});
```
```

--------------------------------

### Initialize ConsoleLogger

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/logger/getting-started.mdx

Basic usage of ConsoleLogger with default settings.

```ts
import { ConsoleLogger } from "@zap-studio/logger";

const logger = new ConsoleLogger(); // minLevel defaults to "info"

logger.debug("this is filtered out by default");
logger.info("server started", { port: 3000 });
logger.error("request failed", { status: 500 });
```

--------------------------------

### Importing and Defining when()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/declarative-policies.mdx

Import the when function and define the signature for the condition callback.

```ts
import { when } from "@zap-studio/permit";

when((context, action, resource) => boolean);
```

--------------------------------

### Import exponentialBackoff

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/retry/exponential-backoff.mdx

Import the exponentialBackoff function from the @zap-studio/retry package.

```ts
import { exponentialBackoff } from "@zap-studio/retry";
```

--------------------------------

### Integrate with Node http Servers

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/webhooks/web-api-native.mdx

Use a fetch-to-Node bridge to enable the router in environments that do not natively support the fetch API.

```ts
import { serve } from "srvx";
import { router } from "./webhooks";

serve({
  fetch: (request) => router.handle(request),
  port: 3000,
});
```

--------------------------------

### policy.can(context, permission, resource)

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/getting-started.mdx

Evaluates whether a specific action is allowed on a resource based on the provided context and defined policy rules.

```APIDOC
## policy.can(context, permission, resource)

### Description
Checks if the current context has permission to perform a specific action on a given resource. This method never throws an error and returns false if the check fails or if an error occurs during evaluation.

### Parameters
- **context** (TContext) - Required - The current user or request context.
- **permission** (string) - Required - The permission string in "resource:action" format (e.g., "product:read").
- **resource** (object) - Required - The resource object to be validated against the policy.

### Returns
- **Promise<boolean>** - Resolves to true if the action is permitted, otherwise false.
```

--------------------------------

### Import type definitions

Source: https://github.com/zap-studio/monorepo/blob/main/packages/validation/README.md

Access StandardSchemaV1 and StandardTypedV1 types directly from the package.

```ts
import type { StandardSchemaV1, StandardTypedV1 } from "@zap-studio/validation";
```

--------------------------------

### Resolving Base URLs

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/create-fetch.mdx

Demonstrates how relative URLs resolve against the baseURL while absolute URLs remain unchanged.

```ts
import { createFetch } from "@zap-studio/fetch";
import { z } from "zod";

const UserSchema = z.object({ id: z.number(), name: z.string() });
const StatusSchema = z.object({ ok: z.boolean() });

const { api } = createFetch({
  baseURL: "https://api.example.com",
});

await api.get("/users/1", UserSchema);
await api.get("https://status.example.com/health", StatusSchema);
```

--------------------------------

### $fetch(input, schema, options)

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/validated-fetch-mode.mdx

Performs a fetch request and validates the response body against a provided schema. The return type is automatically inferred from the schema.

```APIDOC
## $fetch(input, schema, options)

### Description
Performs an HTTP request and validates the JSON response body against a provided schema. The function supports both throwing validation errors and returning result objects.

### Signature
- **input** (FetchInput) - Required - The URL or Request object to fetch.
- **schema** (StandardSchemaV1) - Required - A schema object (e.g., Zod, Valibot) to validate the response body.
- **options** (ExtendedRequestInit) - Optional - Configuration for the fetch request and validation behavior.

### Options
- **searchParams** (URLSearchParams init) - Optional - Query parameters merged into the request URL.
- **throwOnValidationError** (boolean) - Optional - Default: true. If true, throws a ValidationError on failure. If false, returns a Standard Schema result object.
- **throwOnFetchError** (boolean) - Optional - Default: true. If true, throws a FetchError on non-2xx responses.

### Usage Example
```ts
import { $fetch } from "@zap-studio/fetch";
import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

const user = await $fetch("https://api.example.com/users/1", UserSchema);
```
```

--------------------------------

### Perform simple property checks with has()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/conditions.mdx

Demonstrates using has() to validate context properties like roles or plan types.

```ts
import { z } from "zod";
import { createPolicy, when, has, or } from "@zap-studio/permit";
import type { Resources, Actions } from "@zap-studio/permit";

const resources = {
  settings: z.object({ id: z.string() }),
  billing: z.object({ id: z.string() }),
  export: z.object({ id: z.string() }),
} satisfies Resources;

const actions = {
  settings: ["read"],
  billing: ["read"],
  export: ["use"],
} as const satisfies Actions<typeof resources>;

type AppContext = {
  role: "guest" | "user" | "admin";
  isVerified: boolean;
  plan: "free" | "pro" | "enterprise";
};

const policy = createPolicy<AppContext>({
  resources,
  actions,
  rules: {
    settings: {
      // Only admins can access settings
      read: when(has("role", "admin")),
    },
    billing: {
      // Only verified users can access billing
      read: when(has("isVerified", true)),
    },
    export: {
      // Pro or Enterprise users can export
      use: when(or(has("plan", "pro"), has("plan", "enterprise"))),
    },
  },
});
```

--------------------------------

### Construct Option values

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/monads/option.mdx

Create Option instances using some or none constructors.

```ts
import { none, some } from "@zap-studio/monads";

some(42); // { some: true, value: 42 }
none(); // { some: false }
```

--------------------------------

### Initialize Policy with ConsoleLogger

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/logging.mdx

Pass a ConsoleLogger instance to the createPolicy function to enable logging of policy evaluation events.

```ts
import { ConsoleLogger } from "@zap-studio/logger";
import { createPolicy } from "@zap-studio/permit";

const logger = new ConsoleLogger({ minLevel: "debug" });
const policy = createPolicy({ resources, actions, rules, logger });
```

--------------------------------

### Import API Helpers

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/fetch/api-methods.mdx

Import the api object to access the HTTP method helpers.

```ts
import { api } from "@zap-studio/fetch";
```

--------------------------------

### Check permissions with can()

Source: https://github.com/zap-studio/monorepo/blob/main/apps/docs/src/pages/permit/getting-started.mdx

The can() method evaluates a permission string against a context and resource, returning a promise that resolves to a boolean.

```ts
policy.can(context, permission, resource): Promise<boolean>
```
Tokens:
Raw