# Handoff - HubSpot client forms integration

Date: 2026-06-24
Branch: `tom/integration-hubspot-client`
Preview: https://covalba-next-wp-tom-integration-hubspot-client.paf-studio.dev
WP BO: https://covalba-admin.paf-studio.dev/wp-admin/edit.php?post_type=formulaire_hubspot

## Current state

The feature implementation is present in the working tree but is not committed yet, except this handoff file.

Goal: migrate the site forms from the test HubSpot account to the client HubSpot account by managing HubSpot portal/form configuration in WordPress instead of hard-coding it in the front.

Implemented locally:

- Added the `formulaire_hubspot` CPT in the mu-plugin.
- Added ACF fields for HubSpot form configuration:
  - `code`
  - `portal_id`
  - `form_guid`
  - `mode`
  - repeater `champs` with local key, label, HubSpot internal name, object type id, active, required.
- Added relationships from CTA and React component layouts to a `formulaire_hubspot`.
- Updated seed support for the new CPT and relationships.
- Added seed files for:
  - `hubspot-contact`
  - `hubspot-applicateur`
  - `hubspot-diagnostic`
  - `hubspot-estimation`
  - `hubspot-livre-blanc`
  - `hubspot-simulateur-roi`
- Updated page seeds so the relevant pages point to the matching `formulaire_hubspot`.
- Updated GraphQL fragments/types and view prop mapping on the Next side.
- Updated form submission code so fields can be mapped to HubSpot internal field names from WordPress.
- Kept legacy env/GUID fallbacks where needed.

Important: current seed values still use the known existing portal/test data where available. The client HubSpot portal id and final form GUIDs/internal field names must be checked in HubSpot or filled in WordPress before final validation.

## WordPress deployment already done

The mu-plugin and seed files have been deployed manually to the VPS because the standard `scripts/wp/deploy-mu-plugins.sh` refuses feature-branch mu-plugin diffs from `origin/main`.

Deployed to:

- `/srv/covalba-wp/wp-content/mu-plugins/`
- `/srv/covalba-wp/wp-content/seed/lib.php`
- selected affected files in `/srv/covalba-wp/wp-content/seed/content/`

Remote seed commands already run:

- `formulaire-hubspot--*`
- `page--contact*`
- `page--devenir-applicateur`
- `page--diagnostic*`
- `page--estimation*`
- `page--guide-cool-roof*`
- `page--simulateur-economie-energie*`

Remote WordPress now has 6 published `formulaire_hubspot` posts:

- `hubspot-applicateur` - ID `1387`
- `hubspot-contact` - ID `1389`
- `hubspot-diagnostic` - ID `1391`
- `hubspot-estimation` - ID `1393`
- `hubspot-livre-blanc` - ID `1395`
- `hubspot-simulateur-roi` - ID `1397`

GraphQL checks already passed:

- standard `scripts/wp/check-graphql-schema.sh`
- targeted `formulairesHubspot` query returned 6 nodes

Known non-blocking warning during seed:

- `Warning: champ inconnu 'badge' du layout cta` on `page--simulateur-economie-energie.es.json`

## Local verification already run

Passed:

- `php -l` on changed PHP files
- JSON parse of all seed content
- `git diff --check`
- `npm run lint` with existing warnings only
- `npm run build` TypeScript/compile phase passed

Known failures / limitations:

- `npm run test` fails on existing roof/industry tests because `LanguageSwitcher` / `usePathname()` is null. This looks unrelated to the HubSpot changes.
- `npm run build` later fails during page data collection when `WORDPRESS_GRAPHQL_URL` is missing in the local environment.
- `npx tsc --noEmit` fails on existing asset module declaration issues, while the Next build TypeScript phase passed.

## What the next agent should do

1. In the WordPress BO, open the CPT list:
   https://covalba-admin.paf-studio.dev/wp-admin/edit.php?post_type=formulaire_hubspot

2. For each form, confirm or replace:
   - HubSpot client portal id
   - HubSpot form GUID
   - internal field names
   - active/inactive fields
   - required flags

3. Test submissions from the front preview:
   - Contact
   - Devenir applicateur
   - Diagnostic
   - Estimation
   - Guide Cool Roof / livre blanc blocks
   - Simulateur economie energie

4. Check submissions in HubSpot. They may land in spam or a suspicious bucket because the domain is not connected to the final HubSpot domain yet.

5. After testing, commit the feature changes with a conventional commit, push the branch, create a PR to `main`, include the test plan, wait for review, then merge if approved.

## Files to pay attention to

Main WordPress files:

- `wordpress/mu-plugins/covalba-core/inc/post-types.php`
- `wordpress/mu-plugins/covalba-core/inc/field-groups/fiche-formulaire-hubspot.php`
- `wordpress/mu-plugins/covalba-core/inc/field-groups/layouts/composant-react.php`
- `wordpress/mu-plugins/covalba-core/inc/field-groups/layouts/cta.php`
- `wordpress/seed/lib.php`
- `wordpress/seed/content/formulaire-hubspot--*.json`
- affected `wordpress/seed/content/page--*.json`

Main front files:

- `src/lib/hubspot.ts`
- `src/lib/wp/viewProps/hubspot.ts`
- `src/lib/wp/fragments/shared.ts`
- `src/lib/wp/fragments/composantReact.ts`
- `src/lib/wp/fragments/cta.ts`
- `src/components/HubSpotForm.tsx`
- form components under `src/components/*/*Form.tsx`
- affected views under `src/views/`

## Notes

- Do not commit the untracked `AGENTS.md` unless specifically requested. It is environment context.
- Avoid hard-coding the preview host or port in committed config.
- If the dev server is needed, use port `3101` and host `0.0.0.0`.