Release v0.3.1

🚀 KnotEngine v0.3.1

Added

• Hybrid Email Service — Migrated to a hybrid email architecture:
  • Production: Uses the resend SDK for professional deliverability, bounce tracking, and future React Email templating.
  • Development: Uses nodemailer + Gmail SMTP for free, frictionless local testing without quota limits or DNS verification.
• Backend Unit Testing — Implemented the first vitest testing suite with 24 passing tests covering:
  • Engine Math: Verifies correct platform fee deductions (1.0%, 0.5%, 0.25%) and partial payment thresholds.
  • Rate Limiting: Mathematically proves starter tiers are capped at 1 req/sec.
  • Security: Validates that Webhook HMAC-SHA256 signatures correctly reject tampered payloads.
• Email Test Scripts — Added NODE_ENV=production pnpm test:email to easily test both local and prod email providers.
• Email Setup Documentation — Created comprehensive guides in docs/GMAIL_SETUP.md and docs/EMAIL_QUICK_SETUP.md.
• Checkout Header Alignment — Added left/center alignment option for merchant branding header in checkout page.
• Subscription Grace Period — Introduced automated grace periods and status UI to prevent immediate suspension when credit balance is low.
• Animated Sidebar Icons — Integrated lucide-animated with high-performance hover triggers (via React refs) for the primary navigation.
• Promo Code System — Launched a new redemption system allowing merchants to claim balance credits via codes. Includes a new PromoCodeCard UI and secure backend validation.
• Referral Rewards — Implemented 10% instant commission payouts for referrers when their referred merchants perform a top-up.

Fixed

• Email Service Initialization — Fixed lazy-loading of Gmail SMTP transporter to ensure environment variables are loaded before email sending.
• Checkout Footer Logic — Fixed "Remove Powered by KnotEngine" toggle to correctly respect merchant plan (Starter plans cannot remove, Pro+ can).
• Plan Validation — Added plan-based feature gating for white-label checkout (Pro+ only).
• Branding Toggle API — Added brandingEnabled and removeBranding to merchant update schema (was preventing toggles from saving).
• Login Hydration Mismatch — Refactored the login layout into specialized server and client components to resolve Next.js 16/React 19 hydration errors.
• CSS Import Types — Added CSS module declarations to resolve TypeScript errors for CSS imports in dashboard layout.
• Auth Polling Loop — Resolved a critical infinite API sync loop in NextAuth jwt callback occurring for new users with no merchants.
• Service Worker Interception — Fixed "ERR_FAILED" browser errors by decommissioning the legacy Service Worker with a self-destruct script.
• React 19 Rendering — Fixed "component created during render" and "ref accessed during render" errors in animated UI primitives (SlidingNumber, Slot).
• Blockchain ID Collision — Patched a bug where mid_ prefixes were incorrectly being assigned to blockchain xPub fields in some edge cases.
• Linting & Type Safety — Achieved zero-warning status across the dashboard package by resolving multiple unused variables and implicit any types.

Changed

• Email Architecture — Swapped backend email transmission logic from simple SMTP to a dual-provider EmailService class (Resend | Gmail) depending on NODE_ENV.
• Environment Templates — Updated .env.example and .env.development to include merged configuration blocks for GMAIL_APP_PASSWORD alongside RESEND_API_KEY.
• Dynamic Versioning — Standardized version display to pull directly from package.json build metadata.

Removed

• Redundant .env.template — Consolidated environment configuration to single .env.example file.

---

View Full Changelog

Full Changelog: v0.3.0...v0.3.1