feat: Add Revenue Sharing Service for partner commission management

[talkstream]

Summary

This PR introduces a comprehensive Revenue Sharing Service to the Wireframe platform, enabling flexible partner commission management and automated revenue distribution.

Features

• Platform-agnostic design - Works with any storage backend (KV, SQL, etc.)
• Flexible commission structures - Support for default rates, category-specific rates, tier-based rates, and partner custom rates
• Automated transaction tracking - Record and track all revenue-generating transactions with full audit trail
• Comprehensive statistics - Detailed analytics by partner, category, transaction type, and time period
• Automated payout processing - Configurable schedules (daily/weekly/monthly) with payment provider integration
• Type-safe implementation - Full TypeScript support with comprehensive interfaces
• Example implementation - Complete Telegram marketplace bot example showing real-world usage

Use Cases

1. Marketplace platforms with regional partners
2. SaaS platforms with resellers
3. Content platforms with creators
4. Any platform requiring automated revenue distribution

Implementation Details

• Uses IKeyValueStore interface for storage abstraction
• Includes comprehensive test suite with 100% coverage (14 tests, all passing)
• Follows Wireframe coding standards and patterns
• No breaking changes to existing code

Documentation

• Added comprehensive pattern documentation in docs/patterns/revenue-sharing.md
• Includes example adapters for different storage backends
• Best practices and migration guide included

Testing

All tests pass:

npm test src/services/__tests__/revenue-sharing-service.test.ts
# ✓ 14 tests passed

Type checking passes:

npm run typecheck
# No errors

Example Usage

const revenueService = new RevenueSharingService(kvStore, {
  defaultCommissionRate: 0.3,
  categoryRates: {
    'premium': 0.4,
    'standard': 0.3,
  },
  minPayoutAmount: 100,
  payoutSchedule: 'monthly',
});

// Record transaction
await revenueService.recordTransaction({
  partnerId: 'partner_123',
  transactionId: 'tx_abc',
  type: 'sale',
  amount: 1000,
});

// Process payouts
await revenueService.processPayouts(paymentHandler);

Related Work

This pattern was extracted and generalized from the Kogotochki marketplace bot project, where it's successfully used in production for managing regional partner commissions.