Add a Salesforce NPSP Opportunity export reader

[shivamlalakiya]

Summary

Adds a Salesforce Nonprofit Success Pack (NPSP) Opportunity export reader alongside the existing CiviCRM and Raiser's Edge bridges, and wires it into the CLI as philanthropy features --source npsp.

• philanthropy.ingest.read_npsp_opportunities(path): reads an Opportunity export CSV, or a directory of them, delegating to the shared CiviCRM reader.
• philanthropy.ingest.npsp_opportunities_to_features(opportunities, *, reference_date=None, exclude_stages=DEFAULT_EXCLUDED_STAGES): rolls the export up into the donor-level feature table, dropping Pledged rows by default before handing the rest to civicrm_contributions_to_features.
• philanthropy.ingest.DEFAULT_EXCLUDED_STAGES = ("Pledged",).

Why the Pledged filter exists: NPSP's Recurring Donations feature creates one Opportunity per instalment. The upcoming instalment is created in the Pledged stage and only moves to a closed/won stage (Closed Won, or a site's own Posted) once the gift is actually received. Depending on an org's "Installment Opportunity Auto-Creation" setting, the Pledged row and the Closed Won row recording the same instalment's receipt can both exist with the same amount and close date, so summing every Opportunity's Amount naively counts that instalment twice - the same commitment-vs-payment trap the Raiser's Edge bridge already guards against, expressed through Opportunity stage instead of a separate gift record.

Header aliases accept a Salesforce report export's column labels (Account Name/Account ID, Close Date, Amount, Stage, Record Type), the raw Opportunity API field names (AccountId, CloseDate, StageName, RecordType.Name), and NPSP's own Data Import template headers (Donation Date, Donation Amount, Donation Stage, Donation Record Type Name), plus Primary Contact for the Contact-keyed donor case.

NPSP vocabulary was checked against Salesforce's own public documentation rather than assumed:

• Standard NPSP Data Import Fields (official field/header reference): https://help.salesforce.com/s/articleView?id=sfdo.npsp_standard_di_fields.htm
• NPSP Logic for Creating Opportunity Contact Roles (Primary Contact): https://help.salesforce.com/s/articleView?id=sfdo.NPSP_Logic_for_Creating_OCRs.htm
• Trailhead, "Managing Recurring Donations with Nonprofit Success Pack" (Pledged -> Closed Won/Posted instalment lifecycle): https://trailhead.salesforce.com/content/learn/modules/donation-management-basics-with-nonprofit-success-pack/create-recurring-donations
• Trailhead, "Customize Sales Processes and Paths for Nonprofit Success" (per-org stage lists): https://trailhead.salesforce.com/content/learn/modules/opportunity-settings-in-nonprofit-success-pack/understand-and-customize-sales-process-and-path-npsp
• Trailhead, "Managing Donations with Nonprofit Success Pack" (Posted/Closed Won = gift received): https://trailhead.salesforce.com/content/learn/modules/donation-management-basics-with-nonprofit-success-pack/create-or-edit-donations

I deliberately did not model the npe01__OppPayment__c Payment child object - this bridge reads an Opportunity-level export, matching the PR's scope, and I didn't want to assert Payment field names I couldn't verify against a primary source.

Files changed

• philanthropy/ingest/_npsp.py (new)
• philanthropy/ingest/__init__.py (export the three new names)
• philanthropy/cli.py (--source npsp)
• tests/test_npsp.py (new, same depth as tests/test_raisers_edge.py)
• tests/test_cli.py (two CLI integration tests for the new source)
• docs/how-to/use_the_cli.md, docs/reference/index.md (Tier 2/Beta row)
• CHANGELOG.md

Test plan

• python -c "from philanthropy.ingest import DEFAULT_EXCLUDED_STAGES, npsp_opportunities_to_features, read_npsp_opportunities" before writing tests, per CONTRIBUTING.md's order.
• make ci: 2117 passed, 8 skipped; coverage 98.52% (floor 92%); philanthropy/ingest/_npsp.py at 100%.
• make riskcov: risk-tier coverage 98% (floor 93%).

Required test coverage of 92.0% reached. Total coverage: 98.52%
2117 passed, 8 skipped, 195 warnings in 114.93s (0:01:54)
==> All CI checks passed locally.

==> Checking risk-tier coverage floor (93%)...
TOTAL   2163  22  548  26  98%