The definitive open library of npm package behavioral contracts.
This corpus encodes what npm packages promise to do — not just their types, but their behavioral contracts: what errors they throw, what conditions they expect, and what calling code must do to handle them correctly.
This is not a type library. This is not documentation.
This is a machine-readable, AI-writable, human-auditable specification of package behavior.
The difference:
- TypeScript types say: "this returns a
Promise<Response>" - Behavioral contracts say: "this throws on 429 and you must handle it"
When AI generates code, we need to verify it handles error states correctly. But "correct" is not defined anywhere except scattered documentation.
This corpus becomes the standard reference for what packages promise to do.
When someone asks "does this code handle axios errors correctly?", the answer is no longer opinion — it's a verifiable check against the contract.
corpus/
├── SCHEMA.md # Contract schema specification
├── CONTRIBUTING.md # How to contribute contracts
├── packages/
│ ├── axios/
│ │ ├── contract.yaml # Behavioral contract for axios
│ │ └── SOURCES.md # Documentation sources
│ ├── jsonwebtoken/
│ ├── prisma/
│ ├── stripe/
│ └── bullmq/
└── schema/
└── contract.schema.json # JSON Schema for validation
35 packages with behavioral contracts (as of 2026-02-26)
- ✅ stripe - Payment API errors, idempotency, webhooks
- ✅ openai - API errors, rate limiting, token handling
- ✅ @anthropic-ai/sdk - API errors, streaming, rate limits
- ✅ @aws-sdk/client-s3 - S3 operations, credential errors
- ✅ @sendgrid/mail - Email API errors, validation
- ✅ twilio - SMS/voice API errors, webhook validation
- ✅ cloudinary - Image upload errors, transformation failures
- ✅ square - Payment errors, idempotency
- ✅ @octokit/rest - GitHub API errors, rate limiting
- ✅ @prisma/client - Null returns, constraint violations
- ✅ mongodb - Connection errors, query failures
- ✅ mongoose - Schema validation, connection handling
- ✅ pg - PostgreSQL errors, connection pooling
- ✅ @vercel/postgres - Serverless connection pooling
- ✅ drizzle-orm - Type-safe SQL errors
- ✅ redis - Connection errors, data serialization
- ✅ ioredis - Cluster errors, pipeline failures
- ✅ bullmq - Job failures, worker errors, connection cleanup
- ✅ express - Middleware errors, route handler failures
- ✅ fastify - Async handler errors, schema validation
- ✅ next - API route errors, server-side errors
- ✅ socket.io - WebSocket errors, event handler failures
- ✅ @clerk/nextjs - Authentication errors, session handling
- ✅ axios - Network errors, timeouts, rate limiting (429)
- ✅ discord.js - Bot errors, rate limiting, permission errors
- ✅ @slack/web-api - API errors, rate limiting
- ✅ @supabase/supabase-js - Database errors, auth failures
- ✅ zod - Schema validation errors, parsing failures
- ✅ joi - Validation errors, schema mismatches
- ✅ react-hook-form - Form validation, submission errors
- ✅ ethers - Transaction errors, network failures, gas errors
- ✅ firebase-admin - Auth errors, Firestore operations
- ✅ @tanstack/react-query - Query errors, cache invalidation
- ✅ typescript - Compiler API errors, transformation failures
See CATALOG.md for complete package index and upcoming additions.
npx @behavioral-contracts/verify-cli --tsconfig ./tsconfig.jsonThe CLI analyzes your TypeScript code against contracts in this corpus.
import { loadCorpus } from '@behavioral-contracts/verify-cli';
const result = await loadCorpus('./corpus');
const axiosContract = result.contracts.get('axios');Cite contracts in:
- Code reviews: "This violates axios contract clause
rate-limited-429" - Documentation: "See behavioral-contracts/corpus for error handling requirements"
- Audit reports: "Verified against axios contract v1.0.0"
We need contracts for the top 100 npm packages.
How to contribute:
- Read SCHEMA.md to understand the contract format
- Choose a package from CONTRIBUTING.md
- Research the package's official documentation
- Encode the behavioral contract
- Test against real codebases
- Submit a pull request
Every contract must:
- ✅ Link to authoritative documentation
- ✅ Validate against the JSON Schema
- ✅ Produce zero false positives
- ✅ Catch real violations in the wild
Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
This corpus is open and free to use. Anyone can:
- ✅ Use contracts in their tools (commercial or non-commercial)
- ✅ Adapt contracts for their needs
- ✅ Share contracts with others
- ✅ Fork and modify the corpus
You must:
- 📝 Give credit to this corpus (attribution)
- 🔄 Share modifications under the same license (ShareAlike)
You cannot:
- ❌ Create proprietary forks (must stay open)
- ❌ Claim contracts are your own original work
The ShareAlike clause prevents vendor lock-in:
If Sentry (or any competitor) forks our corpus:
- ✅ They must keep it open source
- ✅ They must share improvements back
- ✅ They cannot build proprietary contract database
- ✅ The community benefits from all improvements
What this means:
- Individual developers: Use freely, forever ✅
- Companies: Use in CI/CD, tooling, products ✅
- SaaS providers: Use contracts in your service ✅
- Forks: Must stay open and share-alike ✅
Example:
✅ ALLOWED: Building a SaaS tool that uses these contracts
✅ ALLOWED: Forking to add your own contracts
✅ ALLOWED: Selling services based on these contracts
❌ NOT ALLOWED: Forking and making it proprietary
❌ NOT ALLOWED: Taking contracts and not crediting source
This is the same license Wikipedia uses. It ensures the standard stays open while allowing commercial use.
See LICENSE for full legal text.
10 perfect contracts beat 100 noisy ones. Every contract must be precise.
Contracts encode what the docs say, not what we wish they said.
No vendor lock-in. This is infrastructure, not a product.
The corpus is maintained separately from any analysis tool. This is what makes it a standard.
- Schema questions: Open an issue with label
schema-question - Package-specific: Open an issue with label
package:<name> - General discussion: Open an issue with label
discussion
This corpus is built by the community:
- Contributors are credited in contract
maintainerfields - Contributors are listed in quarterly recognition posts
- Citations in research and tools credit the corpus
Thank you for helping make TypeScript codebases more auditable.