Add Salesforce enrichment workflow (90-day cadence)

[nico-dot]

Summary

Builds a self-contained workflow that keeps Salesforce (SFDC) records enriched with firmographic data on a rolling 90-day cadence. The repo previously contained only a README, so this adds the full project from scratch.

Each record is re-enriched at most once per 90 days: the job finds records that were never enriched or whose Last_Enriched__c is older than 90 days, looks them up by company domain via an enrichment provider, writes the attributes back, and stamps Last_Enriched__c.

How the 90-day cadence is enforced

GitHub cron can't express a true "every 90 days" period, so it's done in two layers:

1. Schedule — runs quarterly (0 6 1 */3 *, ~every 90 days).
2. Per-record freshness window — every run only selects records whose Last_Enriched__c is null or older than ENRICH_INTERVAL_DAYS (default 90). So no record is re-enriched more often than every 90 days, even if the job runs more frequently. This is the robust interpretation and is safe on any schedule.

What's included

• src/sfdc_enrichment/ — env-driven config, a simple-salesforce client (SOQL query + Bulk API updates), a pluggable enrichment provider interface (mock offline provider + generic http provider), the orchestration/freshness logic, and a CLI (python -m sfdc_enrichment, with --dry-run and --show-query).
• .github/workflows/enrich-sfdc.yml — scheduled + workflow_dispatch (with dry_run / max_records inputs), wired to secrets/vars.
• tests/ — 28 pytest tests, all offline (no live org or API key needed).
• README.md, .env.example, requirements*.txt.

Setup notes for the user

• Add a custom datetime field Last_Enriched__c on the target object (default Account), or point at your own via SFDC_LAST_ENRICHED_FIELD.
• Configure Salesforce auth + provider via repository secrets and variables (documented in the README and workflow file). Defaults to the mock provider so it runs safely out of the box.

Testing

• python -m pytest → 28 passed.
• python -m sfdc_enrichment --show-query renders the expected SOQL with a 90-day cutoff.

Design decisions

• Defaults to the mock provider (deterministic, offline) so CI and dry runs need no credentials; swap in a real vendor by implementing EnrichmentProvider.
• Supports both username/password+token and pre-obtained access-token auth styles.
• Provider/network errors are handled per-record so one bad lookup doesn't fail the whole run.