@zvk/contracts

Dependency-free result, error, action, and validation contracts for ZVK applications and app-layer packages.

import { actionError, actionOk, createContractError, err, ok } from "@zvk/contracts";
import { normalizeZodError } from "@zvk/contracts/zod";

The root package and all subpaths are framework-agnostic and SSR-safe. They do not depend on React, Next.js, Supabase, browser APIs, Node-only APIs, Drizzle, Stripe, or DOM globals.

Use this package for JSON-safe boundaries:

• Result<T, E>, ok, err, isOk, and isErr
• ContractError, stable contract error codes, and unknown error normalization
• ActionResult<TData, E> with nested-error server-action envelopes
• SchemaAdapter and schema parsing helpers
• validation issue normalization and validation-error construction
• ZodLikeSchema and structural Zod-like issue normalization through @zvk/contracts/zod

Canonical ownership stays here. Use @zvk/contracts/schema-adapter for the shared SchemaAdapter; @zvk/contracts/validation for validation issues; @zvk/contracts/actions for nested-error ActionResult envelopes; and @zvk/contracts/zod for ZodLikeSchema and structural Zod-like issue normalization. @zvk/feature-kit/schema-adapter is only a compatibility and ergonomics import that re-exports the contracts adapter.

Application-specific policy stays in applications or later packages. Do not add Stripe, billing, organization membership, entitlements, RBAC, storage policy, or route-guard decisions to this package.

Repo Skill

This repository keeps the Codex usage and maintenance skill at:

.codex/skills/use-zvk-contracts/SKILL.md

Use that skill before maintaining this package or replacing local app helpers such as server/result.ts, server/errors.ts, server/actions/result.ts, or lib/validation/zod-issues.ts. The skill includes migration, action-result, contract-error, validation, and testing references.

Migration Notes

Migrate in small slices. Replace generic result and action envelopes with @zvk/contracts, then adapt app-specific AppError copy, redirects, auth policy, and route behavior at the app boundary. ContractError is intentionally a stable shared transport shape, not a full domain error hierarchy.

The @zvk/contracts/zod subpath is structural. It exposes ZodLikeSchema and normalizes Zod-like issue objects without importing Zod at runtime, so application schemas and schema-library dependencies remain app-owned.