Community Fund

Source: src/data/community-fund/

Per-tenant informal community pool. Members make voluntary contributions at checkout; community leaders disburse to members in need.

Integration status: Standalone module. Order-flow checkout, Discord celebration messages, and payment capture are deferred. See docs/specs/2026-04-26-community-fund.md.

---

Service

createCommunityFundService / CommunityFundService

Factory: createCommunityFundService(deps: CommunityFundServiceDeps) — returns CommunityFundService.

CommunityFundServiceDeps:

• contributions: CommunityFundContributionRepository
• disbursements: CommunityFundDisbursementRepository
• config: CommunityFundConfigRepository

Method	Parameters	Returns	Description
recordContribution	RecordContributionInput	Promise<CommunityFundContribution>	Creates a contribution. Throws CommunityFundDisabledError when fund is disabled.
recordDisbursement	RecordDisbursementInput	Promise<CommunityFundDisbursement>	Creates a disbursement. Throws CommunityFundInsufficientBalanceError if balance low.
getBalance	tenantId: string	Promise<FundBalance>	Computes balance from aggregation; never reads a cached field.
getRecentContributions	tenantId: string, limit?: number	Promise<CommunityFundContribution[]>	Last N contributions, ordered by date desc. Default limit 20.
getRecentDisbursements	tenantId: string, limit?: number	Promise<CommunityFundDisbursement[]>	Last N disbursements, ordered by date desc. Default limit 20.
getStats	tenantId: string, period: FundStatsPeriod	Promise<FundStats>	Contribution + disbursement counts and totals for a date range.
getOrCreateConfig	tenantId: string	Promise<CommunityFundConfig>	Returns existing config or creates with defaults. Idempotent.
updateConfig	tenantId: string, patch: CommunityFundConfigPatch	Promise<CommunityFundConfig>	Partial update to tenant config. Creates with defaults if not yet present.
listContributions	tenantId: string, { limit, offset }	Promise<{ items, total }>	Paginated contributions.
listDisbursements	tenantId: string, { limit, offset }	Promise<{ items, total }>	Paginated disbursements.

---

Errors

All errors are defined in src/data/community-fund/community-fund.errors.ts.

Error class	When thrown
CommunityFundDisabledError	recordContribution called when config.enabled === false
CommunityFundInsufficientBalanceError	recordDisbursement when balance < requested amount
CommunityFundConfigError	Invalid or unrecoverable config state (rare)

---

Repositories

Three separate repository interfaces, each with a Mongoose implementation:

• CommunityFundContributionRepository — create, findRecent, findPaginated, sumContributions, statsByPeriod
• CommunityFundDisbursementRepository — create, findRecent, findPaginated, sumDisbursements, statsByPeriod
• CommunityFundConfigRepository — findByTenant, upsert

Use makeCommunityFundRepositories({ ContributionModel, DisbursementModel, ConfigModel }) to build all three at once.

---

Deferred Integration Points

Integration	Target file	Notes
Order-flow checkout	src/data/order/order-flow.service.ts	Call recordContribution after payment confirms
Celebration message	Event bus → community-fund.events.ts (to create)	Emit COMMUNITY_FUND_CONTRIBUTION_RECORDED
Bot-config guild toggle	src/data/bot-config/bot-config.types.ts	Add communityFundEnabled field
Payment capture	src/data/payment/	Add donation as separate line item in charge