Filament Crm Sync Laravel Package

Product Decisions This Supports

• Build vs. buy for CRM sync: this package covers the unglamorous 80% of a HubSpot integration — model-to-object mapping, upsert/dedupe by external ID or email, associations, queued jobs with 429 Retry-After backoff, and an in-panel sync log with retry. That is a concrete alternative to a multi-sprint custom build, so the decision becomes "adopt + validate" versus "build bespoke," not "integrate vs. don't."
• Roadmap sequencing for the admin panel: CRM sync is usually a mid-priority roadmap item that blocks sales/ops workflows. A package that ships the UI (status column, activity timeline, "Open in HubSpot," connection test, mapping check) lets you pull the visible value forward without pulling a backend engineer off core work.
• Where the source of truth lives: mapping is defined in code — on the model via SyncsToCrm or centrally via CrmSync::map() in a service provider. That is a deliberate architectural stance: schema/mapping ownership stays with engineering, changes go through review and deploy. Decide now whether that is acceptable or whether ops needs self-serve mapping (it doesn't provide that).
• CRM vendor commitment: HubSpot is the only driver; Pipedrive and Salesforce exist as a contract, not as working integrations. Adopting this is a soft vote for HubSpot, and the driver contract is the escape hatch to argue for if CRM strategy is still open.
• Scope of sync semantics: contacts upsert by email, companies/deals match on a chosen property, unchanged records are skipped, related records sync first. This is outbound lead sync — not a two-way sync engine. Product decisions about bidirectional updates, deletes, and conflict resolution are explicitly not solved here and must be scoped separately.
• Pilot gating: the release has never run against a live HubSpot account. That makes "run a timeboxed pilot against a real portal" a decision this package forces onto the plan rather than one it answers.

When to Consider This Package

Consider it when most of these hold:

• Your admin surface is Filament 4 or 5 on Laravel 12/13, PHP 8.2–8.5, and your CRM data originates in Eloquent models you control.
• HubSpot is your CRM (or is the decided near-term direction), and you need contacts/companies/deals pushed with associations.
• You want manual, bulk-queued, and on-save sync behavior plus an operator-visible log and retry path, rather than fire-and-forget API calls.
• You have engineering capacity to own the mapping code and a HubSpot private-app token lifecycle, but not capacity to build and maintain the whole integration.
• You can tolerate a single-maintainer, independent, free package and can pin a version and wrap the mapping in one place for later replacement.

Look elsewhere — or budget for a real spike first — when:

• Sync feeds revenue-critical pipelines and you need evidence against a live HubSpot portal before committing. This release rests on fixtures, a local mock, and HTTP::fake; that is a reasonable engineering bar but not production proof.
• You need two-way sync, deletes, field-level conflict resolution, or historical backfill beyond per-record push.
• You need multiple CRMs live now (Pipedrive/Salesforce are planned, not shipped).
• You need no-code mapping owned by RevOps, or enterprise support/SLA/compliance attestations — none are offered, and there's no affiliation with HubSpot.
• You have high API volume where HubSpot rate budgets are a first-class constraint and you need proven throughput numbers rather than per-job rate limiting and backoff.
• You need a guarantee on security review artifacts; the token handling claims (never logged, errors masked) are credible but unverified by a third party.

How to Pitch It (Stakeholders)

For executives (one paragraph): There's a free, open-source Laravel/Filament package that implements the HubSpot lead sync we've been scoping — mapping, dedupe, associations, queued jobs that respect HubSpot's rate limits, and an in-panel sync status, activity view, and retry log. It could remove a meaningful chunk of custom integration work from the roadmap at zero licence cost. The caveats are material and should be stated up front: it is maintained by an independent developer with no vendor backing, and it has not yet been run against a real HubSpot account — the release is validated by unit tests, a mock API, and browser checks on two stack combinations. My recommendation is a timeboxed pilot against a real HubSpot sandbox portal with a pinned version, not a broad rollout.

For engineering: the architecture is the right shape — mapping declared on the model or in a service provider, per-record HubSpot ID storage for idempotency, upsert-by-email for contacts and property-matching for companies/deals, unchanged-record skipping, and associations that sync parents first. Queued jobs are rate-limited and honour Retry-After on 429. Quality signals are reasonable for v1.0.0: Pint, PHPStan level 5, 54 Pest tests, 59 browser checks on each of two stack combinations, and a verified clean Packagist install. Gaps to plan around: no live-HubSpot validation, a driver contract with only one implementation, and the usual single-maintainer abandonment and CVE-response risk. Mitigations: pin the version, keep all mapping in one service provider so the swap surface is a single file, and add integration tests of our own against a sandbox portal before enabling sync-on-save.