Releases: getpaykit/paykit
v0.0.3
PayKit v0.0.3 ships a provider adapter layer that decouples the core billing system from Stripe, opening the door to Polar, Paddle, and other providers down the line. We've also added plan drift detection to catch schema mismatches at runtime, optimized usage billing down to a single database query for common scenarios, and overhauled the init command to support 13+ frameworks out of the box. Plus fixes for customer portals, webhook reliability, and stacked entitlements. The foundation is now more modular, resilient, and ready for production scale.
Highlights
Pluggable payment provider adapter interface
The core PayKit logic no longer knows about Stripe. A new PaymentProvider interface lets you swap providers at init time, and we've moved the full Stripe implementation (~900 lines) into @paykitjs/stripe. This opens the door to Polar, Creem, and other providers without touching core billing logic.
Plan hash-based drift detection catches out-of-sync schemas at runtime
Subscribe requests now compute a SHA-256 hash of your plans and compare it against the database. If they mismatch (you pushed new code but haven't run migrations yet), you get a 500 error with clear guidance instead of silent failures downstream. The CLI check command validates this at deploy time too.
Single-query reportEntitlement for instant usage billing
The common-path metered billing scenario now uses one PostgreSQL CTE instead of five to seven separate calls. Stacked entitlements (multiple billing groups) are aggregated in the same query. We added concurrent request guards to prevent double-charges under load.
Fix for stacked entitlements with atomic transaction rollback
Multi-group deductions (e.g., core product + add-ons) now roll back atomically if concurrent conflicts occur. Previously a retry could re-deduct already-committed rows, causing false overages.
Init command now supports 13 frameworks with smart auto-detection
Point the CLI at your Next.js, Nuxt, Remix, SvelteKit, or any of 13 other frameworks and get type-safe route handlers, client imports, and env files auto-configured. The tool detects your setup, fills in missing environment variables only, and skips existing files on re-run.
More Updates
Bug Fixes
- Customer portal failures in production - upsertCustomer was gated behind testing mode, blocking free-only users from accessing the portal. Ncow always provisions the provider customer idempotently. (Author: @maxktz)
- Webhook events stuck in processing state - Events that crash after beginWebhookEvent but before finishing now auto-reset after 5 minutes instead of hanging forever. (Author: @maxktz)
- Stable JSONB key ordering for metadata syncs - PostgreSQL doesn't preserve key insertion order in JSONB, causing false-positive provider syncs. Keys now sort before serializing. (Author: @maxktz)
- Checkout metadata resolution for plan versioning - Product lookup now uses the persisted plan hash from checkout time instead of the current schema, preventing mismatches if plans change between checkout and webhook processing. (Author: @maxktz)
- Zod v4 compatibility in demo app - better-auth requires zod v4+ but demo was pinned to v3, causing z.email failures. Fixed. (Author: @maxktz)
Features & Enhancements
- Testing mode with Stripe test clocks - Full lifecycle tests now use real Stripe test clocks instead of faking events. Supports advancing time, triggering renewals, and validating webhook flows end-to-end. (Author: @maxktz)
- CLI status and push commands with parallel checks - Loading spinners, parallel DB and provider diagnostics, and context-aware exit messages. Removed the old check command (use status instead). (Author: @maxktz)
- Update notifications in CLI - The push and status commands now check npm in parallel and show an install prompt if a newer version is available. Uses your detected package manager. (Author: @maxktz)
- Version consistency checks across @paykitjs packages - Dev startup validates all @paykitjs/* packages are on the same version, preventing mismatched adapters. (Author: @maxktz)
- Stripe managedPayments and apiVersion options - Opt into Stripe's managed payments API and pin a specific API version so upstream changes don't break your integration. (Author: @aristotl-dylan)
- Database export from paykitjs/database - Schema is now exported so consumers can reference types without internal paths. Added drizzle studio command to the demo. (Author: @maxktz)
Performance Improvements
- Reduced database round-trips in subscription flows - Common path from 5-7 calls down to 1-3. Stacked fallback uses atomic updates instead of drain-then-refund patterns. (Author: @maxktz)
Infrastructure
- Database schema consolidation - Merged 17 tables into 10 using JSONB columns for provider and subscription data. Reduces complexity and query join overhead while keeping migration safety. (Author: @maxktz)
- Drizzle query builder throughout - Replaced all raw SQL with type-safe Drizzle queries across services, webhooks, and tests. Eliminated pg-mem and pglite test utilities in favor of real e2e PostgreSQL. (Author: @maxktz)
- Plugin system with @paykitjs/dash dashboard - Plugin interface lets you mount custom endpoints. Built a Vite React SPA dashboard with Tailwind and shadcn/ui as the first plugin. (Author: @maxktz)
- Structured logging with AsyncLocalStorage trace IDs - New trace context module auto-injects trace IDs into logs across the entire request. Webhook handler and subscribe service now emit 7+ structured log points per call. (Author: @maxktz)
- Package publishing pipeline with bumpp - GitHub Actions workflow for v* tags, manual dist-tag workflow for retroactive fixes, and synchronized versioning across all packages. (Author: @maxktz)
Documentation
- Complete docs rewrite with Get Started, Concepts, Flows, and Providers sections - 14 pages covering plans, customers, subscriptions, entitlements, webhooks, database, providers, plugins, CLI, and TypeScript inference. Installation, Quickstart, and Introduction pages with code examples. (Author: @maxktz)
- AI access endpoints for LLM documentation - /docs/*/.mdx routes serve raw markdown per page. /llms-full.txt endpoint streams the entire docs as a single markdown file for AI model context. (Author: @maxktz)
- CLI and contributing guides - AGENTS.md for e2e test development, contributing.md for community setup, and updated README with project overview and code snippets. (Author: @maxktz)
Testing
- Comprehensive e2e test suites - 14+ test scenarios covering subscribe, upgrade, downgrade, cancel, resume, renewal, entitlements (boolean and metered), stacked billing, and full webhook lifecycle. All tests use real Postgres, real Stripe API, and test clocks. (Author: @maxktz, Author: @t3duk)
- Test performance assertions - e2e tests now assert database call counts to enforce performance contracts. Catches regressions automatically. (Author: @maxktz)
Internal Changes
- Simplified telemetry to env-var-only gating - Removed .paykit config directory and telemetry subcommand. Opt-out via PAYKIT_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1. (Author: @maxktz)
- Unified error handling with typed error codes - New defineErrorCodes utility validates 20+ error codes at compile time. All errors now map automatically to HTTP responses. (Author: @maxktz)
- Lazy context initialization - PayKit context no longer runs at module load. Everything is lazy, and dev checks run on first request instead of blocking startup. (Author: @maxktz)
- Landing page overhaul - Redesigned hero terminal animation to match real CLI output, new features grid, enterprise contact form with Resend, testimonials section, mobile-responsive polish. (Author: @maxktz, Author: @aarmful, Author: @t3duk)
