Skip to content

Release v1.1.0 - Major Feature Updates & Production Hardening - #42

Merged
kemboi22 merged 14 commits into
mainfrom
dev
Jul 13, 2026
Merged

Release v1.1.0 - Major Feature Updates & Production Hardening#42
kemboi22 merged 14 commits into
mainfrom
dev

Conversation

@compgeniuses

@compgeniuses compgeniuses commented Jul 12, 2026

Copy link
Copy Markdown
Contributor

Description

Release v1.1.0 - Major Feature Updates & Production Hardening

🎯 Overview

This PR merges 10 major commits from dev to main, bringing FinaFlow to version 1.1.0. This release includes significant new features, production-ready database optimizations, integration capabilities, and comprehensive testing coverage.

Statistics:

  • 125 files changed
  • 35,108 insertions, 781 deletions
  • 10 new database migrations
  • 18 new test files with comprehensive coverage
  • 3 new API routers
  • 7 new React components
  • Multiple security & performance enhancements

🚀 Major Features

1. FinaBill Integration System

Commit: 9a86293 - feat(integrations): add FinaBill integration and tooling

New Capabilities:

  • Full FinaBill integration adapter with registry pattern
  • API key authentication system with secure hashing (bcrypt)
  • Outgoing webhook dispatch framework with event triggers
  • Frontend integration card with pairing workflow
  • Business connection tracking and multi-business support

Technical Changes:

  • New API routes: /api/integration-finabill/* and /api/webhooks/*
  • New tables: apiKeys, integrationConnections, channelMappings, webhookDeliveries
  • New components: FinabillIntegrationCard.tsx
  • New libraries: api/lib/webhook-dispatcher.ts, api/lib/webhook-handlers.ts
  • Updated dev server port: 3000 → 3200 across all configs
  • Added EXPENSE_CATEGORIES_MANAGE permission role

Files Added/Modified:

api/integration-finabill-router.ts (531 lines)
api/lib/integrations/* (multiple adapter files)
api/lib/webhook-dispatcher.ts (156 lines)
api/lib/webhook-handlers.ts (162 lines)
api/lib/crypto.ts (59 lines)
api/lib/api-key-auth.ts (116 lines)
src/components/FinabillIntegrationCard.tsx (434 lines)
db/migrations/0017_steep_tarantula.sql
db/migrations/0018_bent_hellcat.sql

Testing:

  • api/__tests__/integration-finabill.test.ts (367 lines)
  • api/__tests__/webhook-dispatcher.test.ts (235 lines)
  • api/__tests__/webhook-triggers.test.ts (117 lines)

2. Integration Security & Production Hardening

Commit: 13ea530 - feat(integrations,auth,db): harden integration workflows and add scoped machine auth

Security Enhancements:

  • Scoped API key middleware with granular permission checks
  • Exempted /api/integration/* routes from CSRF for machine-to-machine auth
  • Required locationId and sourceBatchId for daily sales ingestion
  • Enforced tenant isolation for API key users creating journal entries
  • Updated webhook handlers to require externalId for safe master data updates
  • Role allowlists and location validation in Finabill upsertUser

Bug Fixes:

  • Fixed ledger reversal logic to filter by transaction type, avoiding cross-module soft delete collisions
  • Removed conflicting legacy migrations to prevent deployment failures

Database Changes:

  • Production-safe migration 0025_integration_connections_and_channel_maps.sql
  • Added API key expiry tracking
  • Added source batch tracking for daily sales

Files Modified:

api/lib/api-key-middleware.ts (43 lines)
api/lib/accounting-reversal.ts
api/lib/journal.ts
api/middleware.ts (60 lines)
api/boot.ts (updated CSRF exemptions)
db/migrations/0025_integration_connections_and_channel_maps.sql

3. Database Performance & Integrity

Commit: b9c73eb - feat(db): add production-safe database indexes, foreign keys, and tooling

Performance Improvements:

  • 40+ partial/composite concurrent indexes on high-volume financial tables
  • Optimized query performance for bills, expenses, transactions, accounts

Data Integrity:

  • 25+ NO ACTION foreign keys using NOT VALID + VALIDATE pattern
  • Avoids long table locks during migrations
  • Ensures referential integrity without downtime

New Tooling:

scripts/migration-safety-check.ts (276 lines)
docs/database-migrations.md (169 lines)

Key Features:

  • Pre-deployment orphan row validation
  • Missing index detection
  • Comprehensive migration runbook with best practices
  • Safe production deployment procedures

Files Modified:

db/schema.ts (updated with new indexes and FKs)
db/migrations/meta/_journal.json

4. Enhanced UX: Inline Form Enhancements

Commit: 7e47204 - feat: add inline add-new category and supplier options to forms

User Experience Improvements:

  • Inline "Add New" options in category and supplier selectors
  • No more context switching between forms
  • Controlled dialog state with custom triggers
  • Streamlined expense and bill creation workflow

Components Updated:

src/components/ExpenseCategorySelector.tsx (updated)
src/components/QuickCategoryDialog.tsx (190 lines)
src/components/QuickSupplierDialog.tsx (110 lines)
src/pages/Expenses.tsx (updated with inline flow)
src/pages/Bills.tsx (updated with inline flow)

Technical Changes:

  • Refactored dialogs to support controlled open state
  • Custom label and callback support in selectors
  • Removed redundant separate trigger buttons
  • Managed dialog state at page level for better control

5. Data Freshness & Cache Management

Commit: fb3536f - fix(auth, payments, users): keep user and payment data fresh, add tests

Cache Fixes:

  • Set staleTime: 0 on useAuth hook for continuous fresh user data
  • Added invalidation of localAuth.me query after location assignment updates
  • Fixed payment method refetch and invalidation on the Accounts page
  • Proper query invalidation on assignment mutations

Testing:

  • Added comprehensive test cases for freshness behaviors
  • Validated all invalidation patterns

Files Modified:

src/hooks/useAuth.ts
src/pages/Accounts.tsx
src/pages/Users.tsx
api/__tests__/frontend-regressions.test.ts

6. Business Connection Management

Commit: 5e783fc - feat(integrations): add business connection tracking and UI

New Features:

  • ltc1q0gq5ghan358l8y6unf2yz7s42efgnqcut0pvu6 API endpoint
  • Per-business integration connection status display
  • Direct business switching from integration cards
  • Duplicate connection prevention for same business + target system
  • Multi-business integration status overview

UI Enhancements:

  • Updated Finabill integration card with per-business status
  • Pairing workflow UI with pairing codes and direct approval links
  • Connection status badges and indicators

Files Modified:

api/integrations-router.ts (updated)
src/components/FinabillIntegrationCard.tsx (updated)
api/__tests__/integration-connections.test.ts (178 lines)

7. FinaBill Database Utilities

Commit: 628a784 - feat(scripts): add finabill database utility scripts

New Scripts:

scripts/fix-finabill-target-url.ts - Update connection URLs (localhost:3100 → 3101)
scripts/query-business-names.ts - Fetch business details by ID across databases
scripts/inspect-finabill-connections.ts - List all integration connections

Use Cases:

  • Integration debugging and troubleshooting
  • Connection URL management
  • Cross-database business lookups

8. Business Scope for Wallet Reconciliation

Commit: a9f8b44 - feat(wallet): add business scope to reconciliation records

Multi-Tenancy Improvements:

  • Added businessId and locationId to mobile_wallet_reconciliation table
  • Backfilled existing records with sentinel business ID
  • Created unique index on (businessId, provider, txnDate)
  • Enforced business and location authorization checks on all wallet endpoints
  • Fixed business reset script to only delete target business records

Testing:

  • Comprehensive scope isolation tests for wallet endpoints
  • Validated cross-tenant data access prevention

Files Modified:

db/migrations/0028_wallet_reconciliation_tenant_scope.sql
api/wallet-router.ts (88 lines modified)
scripts/business-reset.ts
api/__tests__/wallet-router.test.ts (148 lines)

9. Partner Leads & Referral System

Commit: db92ec2 - feat(partner): add partner leads, referrals, and allocation fixes

New Lead Management:

  • Full partner lead tracking and referral attribution workflow
  • Database migration 0029_partner_leads with new schema
  • Lead normalization and attribution helpers
  • Frontend dashboard components for lead management
  • Referral attribution during signup and account settings
  • Validation rules for referral codes

Authorization Fixes:

  • Business owners retain allocation management access
  • Partner/admin users get restricted allocation claim flows
  • Corrected allocation visibility permissions

Email Templates:

  • Added lead invitation communication templates

Files Added/Modified:

api/leads-router.ts (292 lines)
api/lib/leads.ts (255 lines)
api/lib/email-templates.ts (updated)
src/components/partner/LeadsTab.tsx (349 lines)
src/components/partner/LeadFormDialog.tsx (152 lines)
src/components/partner/LeadStatusBadge.tsx (41 lines)
db/migrations/0029_partner_leads.sql
api/__tests__/leads-router.test.ts (250 lines)
api/__tests__/account-subscription-referral.test.ts (221 lines)
api/__tests__/partner-allocation-authorization.test.ts (135 lines)

10. Dashboard Coherence Refactor

Commit: 5a4c0d2 - feat(dashboard): add dashboard coherence refactor

New Dashboard Architecture:

  • Reusable dashboard feature sub-component library with barrel exports
  • Components: CashPositionCard, CashflowTrendCard, MobileWalletSummaryCard, TrendKpiCard, BillsPipelineCard, TodayStrip

Dashboard Improvements:

  • Reordered layout top-down for better UX
  • Replaced in-page KpiCard helper with trend-enabled TrendKpiCard
  • Removed duplicate "Unpaid Sales" KPI
  • Gated components behind appropriate permissions
  • Fixed orphaned mobile wallet summary display

Backend Extensions:

  • Added cashflowTrend query
  • Added previousPeriodTotals for trend calculations
  • Aggregated cashPosition breakdown by account type

Testing:

  • Unit and regression tests for all new dashboard logic
  • src/pages/__tests__/dashboard-coherence.test.ts (68 lines)
  • api/__tests__/dashboard-summary-extensions.test.ts (59 lines)

Files Added:

src/features/dashboard/* (multiple card components)
src/features/dashboard/cash-position.ts (56 lines)
src/features/dashboard/cashflow-trend-data.ts (62 lines)
src/features/dashboard/__tests__/* (test files)

11. Version Bump & Release

Commit: ad543c0 - chore(release): bump version to 1.1.0

Release Preparation:

  • Updated package.json version: 1.0.6 → 1.1.0
  • Updated APP_VERSION constant in src/lib/version.ts
  • Added v1.1.0 release notes to CHANGELOG.md
  • Coordinated version updates for deployment

🗄️ Database Migrations

This release includes 10 new migrations:

  1. 0017_steep_tarantula.sql - Initial integration foundations
  2. 0018_bent_hellcat.sql - Extended integration schema
  3. 0025_integration_connections_and_channel_maps.sql - Production-ready integration tables
  4. 0026_fina_connect_sessions.sql - Connect protocol sessions
  5. 0027_fina_connect_target_business.sql - Target business tracking
  6. 0028_wallet_reconciliation_tenant_scope.sql - Multi-tenant wallet scope
  7. 0029_partner_leads.sql - Partner lead management

Migration Safety:

  • All migrations use production-safe patterns
  • Concurrent indexes (no table locks)
  • Foreign keys added with NOT VALID + VALIDATE
  • Pre-deployment safety check script included

🧪 Testing Coverage

New Test Files (18):

api/__tests__/account-subscription-referral.test.ts (221 lines)
api/__tests__/connect-protocol.test.ts (33 lines)
api/__tests__/dashboard-summary-extensions.test.ts (59 lines)
api/__tests__/frontend-regressions.test.ts (23 lines)
api/__tests__/integration-connections.test.ts (178 lines)
api/__tests__/integration-finabill.test.ts (367 lines)
api/__tests__/leads-router.test.ts (250 lines)
api/__tests__/partner-allocation-authorization.test.ts (135 lines)
api/__tests__/wallet-router.test.ts (148 lines)
api/__tests__/webhook-dispatcher.test.ts (235 lines)
api/__tests__/webhook-triggers.test.ts (117 lines)
api/lib/__tests__/api-key-auth.test.ts (117 lines)
api/lib/__tests__/leads.test.ts (44 lines)
src/features/dashboard/__tests__/cash-position.test.ts (58 lines)
src/features/dashboard/__tests__/cashflow-trend-data.test.ts (82 lines)
src/pages/__tests__/dashboard-coherence.test.ts (68 lines)
src/pages/__tests__/partner-dashboard-visibility.test.ts (47 lines)

Test Coverage Areas:

  • Integration workflows and security
  • Webhook dispatch and handling
  • Partner leads and referrals
  • Dashboard calculations and trends
  • Wallet scope isolation
  • API key authentication
  • Authorization and permissions
  • Data freshness and cache invalidation

🔒 Security Enhancements

  1. API Key Authentication System

    • Bcrypt hashing for API keys
    • Scoped permissions with middleware
    • Tenant isolation enforcement
  2. CSRF Protection Updates

    • Exempted machine-to-machine routes (/api/integration/*, /api/webhooks/*)
    • Maintained protection on all user-facing endpoints
  3. Authorization Improvements

    • Location-scoped queries and mutations
    • Business-scoped wallet reconciliation
    • Partner allocation permission fixes
  4. Data Integrity

    • Foreign key constraints on all critical tables
    • Unique indexes to prevent duplicates
    • Required fields for sensitive operations (locationId, sourceBatchId, externalId)

📚 Documentation Updates

New Documentation:

docs/database-migrations.md (169 lines)
.trae/documents/dashboard-coherence-cards-and-trend-chart.md (368 lines)
.trae/documents/partner_leads_engine_and_allocation_visibility_plan.md (210 lines)

Updated Files:

AGENTS.md (updated commands and structure)
README.md (updated version and features)
CHANGELOG.md (214 new lines)

⚙️ Configuration Changes

Environment Variables:

  • Updated .env.example with new integration-related variables
  • Dev server port: 3000 → 3200

Dependencies:

  • No new external dependencies added
  • Leveraged existing crypto and hashing libraries

🐛 Bug Fixes

  1. Ledger Reversal Logic - Fixed cross-module soft delete collisions by filtering transaction types
  2. Payment Method Refetch - Fixed invalidation on location assignment
  3. Business Reset Script - Now only deletes records for target business
  4. Duplicate Unpaid Sales KPI - Removed from dashboard
  5. Mobile Wallet Summary - Fixed orphaned display issue
  6. Logout Flow - Fixed async TRPC mutation and cross-environment cookie handling

🚨 Breaking Changes

None - This release is fully backward compatible with v1.0.6

Note: The dev server port change (3000 → 3200) may require local environment updates for developers.


📋 Deployment Checklist

  • Review and run scripts/migration-safety-check.ts before deployment
  • Apply all 10 database migrations in order
  • Update environment variables per .env.example
  • Verify Portless configuration if using HTTPS locally
  • Run npm test to validate all tests pass
  • Run npm run lint and npm run check for code quality
  • Deploy backend first, then frontend
  • Verify integration endpoints are accessible
  • Test FinaBill integration pairing workflow
  • Validate partner lead management flows

👥 Contributors


📊 Commit Summary

Commit Type Description
ad543c0 chore Bump version to 1.1.0
5a4c0d2 feat Dashboard coherence refactor
db92ec2 feat Partner leads, referrals, and allocation fixes
a9f8b44 feat Business scope for wallet reconciliation
628a784 feat FinaBill database utility scripts
5e783fc feat Business connection tracking and UI
fb3536f fix Auth, payments, users data freshness
7e47204 feat Inline add-new category and supplier options
b9c73eb feat Production-safe database indexes and FKs
13ea530 feat Hardened integration workflows and scoped auth
9a86293 feat FinaBill integration and tooling

🎉 Summary

This release represents a significant milestone for FinaFlow, bringing enterprise-grade integration capabilities, production-ready database optimizations, and enhanced partner management features. The codebase is now more secure, performant, and maintainable with comprehensive test coverage and documentation.

Ready for production deployment! 🚀

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactor (no functional changes)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

  • Unit tests
  • Integration tests
  • End-to-end tests
  • Manual testing

Test Configuration:

  • Node.js version:
  • PostgreSQL version:
  • OS:

Checklist:

  • My code follows the project's code style
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation (if applicable)
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

Screenshots (if appropriate):

Additional context:

Add any other context about the pull request here.

Add full FinaBill integration stack including adapter, registry, frontend card, and webhook routes
Update dev server port from 3000 to 3200 across vite config, env example, and backend env handling
Implement API key authentication system with middleware, hashing utilities, and DB schema
Add outgoing webhook dispatch framework and event triggers for core business events
Exclude /api/webhooks endpoints from CSRF protection
Add EXPENSE_CATEGORIES_MANAGE permission role
Fix logout flow to use async TRPC mutation and correct cross-environment cookie handling
Update partner client listing to include both partnered and referred businesses
Add mobile-responsive styling for partner allocations tab and account picker
Add QuickSupplierDialog component for fast supplier creation
Update database schema, add migrations, and add comprehensive tests for new systems
…ed machine auth

- Add production-safe 0025 migration for integration connections, channel mappings, API key expiry, and daily sales source batch tracking
- Remove conflicting legacy migrations to prevent deployment failures
- Update _journal.json to reflect current migration state
- Exempt /api/integration/ machine-to-machine routes from CSRF protection
- Implement scoped API key middleware with permission checks for protected endpoints
- Require valid locationId and sourceBatchId for daily sales ingestion
- Fix ledger reversal logic to filter by transaction type, avoiding cross-module soft delete collisions
- Enforce tenant isolation for API key users creating journal entries
- Update webhook handlers to require externalId for safe master data updates
- Harden Finabill integration upsertUser with role allowlists and location validation
- Update CHANGELOG with release notes for these changes
- Update all related tests and test configurations
…ling

Add production-safe database performance and integrity improvements:
- Add 40+ partial/composite concurrent indexes on high-volume financial tables to boost query speed
- Add 25+ NO ACTION foreign keys using NOT VALID + VALIDATE to avoid long table locks during migrations
- Create migration safety check script to validate orphan rows and missing indexes before deployment
- Write comprehensive database migration runbook documentation
- Update db/schema.ts to match new indexes and foreign key constraints
- Clean up redundant comment in AllocationManagement.tsx
- Update CHANGELOG and migration journal files
- update ExpenseCategorySelector to support add-new options with custom labels and callbacks
- refactor QuickCategoryDialog and QuickSupplierDialog to support controlled open state and custom triggers
- update Expenses and Bills pages to use updated selectors, replace separate trigger buttons with inline add flows, and manage dialog state at page level
- remove unused Lucide Plus icon imports from dialog components
- Set staleTime: 0 on the useAuth hook to keep authenticated user data fresh continuously
- Add invalidation of the localAuth.me query after updating user location assignments in the Users page
- In the Accounts page: add a refetch handler for location-specific payment methods, and fix the assignment mutation to properly invalidate and refetch the correct payment methods
- Add test cases to validate all freshness and invalidation behaviors
Add new `listBusinessConnectionStates` API endpoint and service function to fetch integration connection statuses across a user's active businesses.
Add validation to prevent duplicate connections for the same business and target system when creating a new integration session.
Update the Finabill integration card to display per-business connection status, enable direct business switching, and refine the pairing workflow UI to show pairing codes and direct approval links.
Show all connected businesses' integration statuses for multi-business users directly in the card.
add three new helper scripts for finabill integration management:
- update finabill connection URLs from localhost:3100 to 3101
- fetch business details by ID across configured databases
- list all existing finabill integration connections
- Add database migration to add `businessId` and `locationId` columns to `mobile_wallet_reconciliation` table, backfill existing records with a sentinel business ID, and create a unique index on (businessId, provider, txnDate)
- Update drizzle ORM schema to match the new table structure
- Update test database setup to include the new migration files
- Fix business reset script to only delete reconciliation records for the target business instead of all records
- Update Mpesa migration script to include default business ID for historical records and adjust conflict resolution target to include business ID
- Add comprehensive scope isolation tests for wallet and reconciliation endpoints
- Enforce business and location authorization checks on all wallet router procedures to prevent cross-tenant data access
Implemented full partner lead management and referral attribution workflow:
- Added database migration 0029_partner_leads, updated DB schema, and backend logic for lead tracking and commission eligibility
- Added leads API router, normalization/attribution helpers, and frontend dashboard components
- Added referral attribution during signup and account settings with validation rules
- Corrected allocation visibility permissions: business owners retain allocation management access in the Businesses page while partner/admin users get restricted partner allocation claim flows
- Added comprehensive test coverage for all new lead, referral, and authorization workflows
- Updated email templates for lead invitation communications
Introduce reusable dashboard feature sub-component library with barrel exports:
CashPositionCard, CashflowTrendCard, MobileWalletSummaryCard, TrendKpiCard,
BillsPipelineCard, and TodayStrip.

Refactor src/pages/Dashboard.tsx: reorder layout top-down, replace the in-page
KpiCard helper with trend-enabled TrendKpiCard, remove the duplicate Unpaid Sales
KPI, and gate components behind appropriate permissions.

Extend backend dashboard router: add cashflowTrend query, previousPeriodTotals
for trend calculations, and aggregated cashPosition breakdown by account type.

Add comprehensive unit and regression tests for all new dashboard logic, fix the
previously orphaned mobile wallet summary display, and update CHANGELOG.md with
full release notes for this overhaul.
- Update package.json version from 1.0.6 to 1.1.0
- Update APP_VERSION constant in src/lib/version.ts to 1.1.0
- Add version 1.1.0 release notes to CHANGELOG.md with deployment date
- Prepare application for deployment with coordinated version updates
- Replace KES/USD with XXX/YYY to test error handling without relying on specific currency pair availability
- Improve test isolation by using placeholder codes that guarantee missing exchange rates
fix(business-reset): handle empty location IDs array in account filtering
- Add conditional check before using inArray() to prevent invalid query generation when locationIds is empty
- Fall back to businessId equality check when no locations are present
- Prevents potential runtime errors in account reset queries with filtered location scopes
@kemboi22
kemboi22 merged commit 2bbd835 into main Jul 13, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants