Add Trade Credit & Invoice Factoring Extensions (B2B analytics)

[Thorium]

Summary

This PR introduces the initial Business (B2B) analytical extensions under the namespace FSharp.Finance.B2B.*.

Purpose: provide optional analytics (NOT a full commercial / operational platform) for:

• Trade credit early-payment discount implied annual rates
• Basic invoice factoring parameter construction
• Lightweight product metadata classification
• Forward-looking generic cashflow scaffolding (not yet integrated)

---

Files Added (Current State)

• DomainExtensions.fs
  • BusinessProductType DU
  • ProductMetadata record + helper constructors (consumer, tradeCredit, invoiceFactoring)
• CashflowModel.fs
  • CashflowType DU + CashflowEvent record (future-facing abstraction; not yet wired in)
• TradeCredit.fs
  • DiscountTerms, createTerms
  • impliedAnnualRateSimple
  • impliedAnnualRateCompounded
• InvoiceFactoring.fs
  • Invoice, InvoiceAdvance (derive)
  • FactoringParameters.build -> Parameters
• Docs: docs/exampleTradeCreditAndFactoring.fsx
• README: B2B section added

---

Design Decisions

Aspect	Decision
Namespace boundary	All new code under FSharp.Finance.B2B.*
APR handling	Reuse Apr.CalculationMethod.UnitedKingdom 2 (placeholder)
Factoring modeling	Scheduled repayments are aggregated by due date before building the custom schedule
Product metadata	Non-regulatory, descriptive only
Cashflow model	Present but not integrated yet (reserved for future factoring / reserves modeling)

---

Trade Credit Rate Formulas

Let d = discountPercent, D = discount deadline day, N = net due day.

Simple annualized (no intra-year compounding):
rate_simple = (d / (1 - d)) * (365 / (N - D))

Naive compounded:
rate_compounded = (1 + d / (1 - d))^(365 / (N - D)) - 1

Comments in code document rationale and limitations.

---

Documentation Example

docs/exampleTradeCreditAndFactoring.fsx:

• Demonstrates 2/10 net 30 implied rates
• Builds factoring parameters for multiple invoices
• Prints schedule basics and economics
• Includes disclaimers

---

Tests

• TradeCreditTests.fs
  • Assert impliedAnnualRateSimple for 2/10 net 30 ~= 0.3724 (tolerance +/- 0.0001m)
  • Reject 100m discount input to avoid divide-by-zero paths
• InvoiceFactoringTests.fs
  • Assert same-day invoice due dates are aggregated into one scheduled payment instead of being overwritten

---

Checklist

• Add B2B source modules
• Update README
• Add documentation example
• Add trade credit unit test
• Add factoring structural integrity test
• Address PR review feedback

---

Open Questions

1. Should this be its own NuGet package, since the functionality is B2B-oriented even though it reuses the existing amortisation engine?
2. Introduce AprMethod.Disabled in a future minor version for zero-interest cases?
3. Explicit reserves as separate modeled cashflows later by integrating CashflowModel?
4. Future consolidation into a neutral FSharp.Finance.Analytics namespace?

---

Non-Goals (Current Iteration)

• Operational factoring workflows (collections, dilution)
• Risk / expected loss modeling
• Multi-currency support
• Regulatory classification

---

Disclaimer

Analytical utilities only. Independent validation required for production or compliance use.

[Copilot]

Pull request overview

Adds initial B2B analytical extensions (trade credit discount-rate analytics + invoice factoring parameter construction) alongside some supporting domain/cashflow scaffolding and documentation.

Changes:

• Introduces FSharp.Finance.B2B.TradeCredit utilities + unit tests for implied rates and validation.
• Adds FSharp.Finance.B2B.InvoiceFactoring types and a FactoringParameters.build helper to produce core Scheduling.Parameters.
• Adds product metadata/cashflow scaffolding plus a docs script + README section describing the new B2B analytics.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/TradeCreditTests.fs	Adds unit tests for trade credit calculations and validations.
tests/FSharp.Finance.Personal.Tests.fsproj	Includes the new trade credit test file in the test project.
src/TradeCredit.fs	Implements trade credit discount terms + implied annual rate calculators.
src/InvoiceFactoring.fs	Adds invoice factoring domain types + parameter/statistics builders.
src/FSharp.Finance.Personal.fsproj	Compiles the new modules into the main library and updates package description.
src/DomainExtensions.fs	Adds business product classification + metadata helpers.
src/CashflowModel.fs	Adds (currently unused) cashflow event/type scaffolding.
docs/exampleTradeCreditAndFactoring.fsx	Adds an example script demonstrating trade credit + factoring usage.
README.md	Documents the new B2B analytical extensions at a high level.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.