# Pardot form handler

External component: fetches field definitions from the Pardot API v5 and renders a fully native, styled form on the site. Includes invisible reCAPTCHA v3, honeypot, and timing-based bot protection. Submissions are proxied through `/api/pardot/submit`.

> **API keys required.** The component returns nothing until all environment variables are configured. See [Required environment variables](#required-environment-variables) below.

## Fields & Schema

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `externalComponentType` | Symbol | Yes | Must be `"Pardot form handler"` |
| `data.formHandlerId` | string | Yes | Numeric Pardot Form Handler ID (e.g. `"123456"`). |
| `data.captchaEnabled` | boolean | No | Enable invisible reCAPTCHA v3. Default: `true`. |
| `extraCopy` | Rich Text | No | Content shown in-place after successful submission. |
| `data.errorMessage` | string | No | Message shown if submission fails. Default: `"Something went wrong. Please try again."` |
| `data.submitButtonText` | string | No | Submit button label. Default: `"Submit"`. |

## Finding your Form Handler ID

1. In Pardot, go to **Marketing → Forms → Form Handlers**.
2. Click the form handler name — the numeric ID is in the URL: `/form-handlers/123456/edit`.

## Usage

```bash
cms-edit add "Pardot form handler" --content-type externalComponent --target content

cms-edit set @ref data --json '{
  "formHandlerId": "123456",
  "submitButtonText": "Get in touch"
}'

# Set the success message via the extraCopy rich text field
cms-edit set @ref extraCopy --rich-text "Thank you! We will be in touch shortly."

cms-edit save
```

## Required environment variables

Set these in Vercel for every environment where the form is used:

```bash
vercel env add PARDOT_CONSUMER_KEY        # Salesforce Connected App client ID
vercel env add PARDOT_CONSUMER_SECRET     # Salesforce Connected App client secret
vercel env add PARDOT_BUSINESS_UNIT_ID    # Pardot Business Unit ID (starts with "0Uv")
vercel env add NEXT_PUBLIC_RECAPTCHA_SITE_KEY  # reCAPTCHA v3 site key (public)
vercel env add RECAPTCHA_SECRET_KEY            # reCAPTCHA v3 secret key (server only)
```

### Where to find each value

| Variable | Where to find it |
|----------|-----------------|
| `PARDOT_CONSUMER_KEY` | Salesforce Setup → App Manager → your connected app → Manage Consumer Details |
| `PARDOT_CONSUMER_SECRET` | Same location as above |
| `PARDOT_BUSINESS_UNIT_ID` | Pardot Settings → Business Unit Setup. Starts with `0Uv`. |
| `NEXT_PUBLIC_RECAPTCHA_SITE_KEY` | [Google reCAPTCHA Admin](https://www.google.com/recaptcha/admin) → your v3 site |
| `RECAPTCHA_SECRET_KEY` | Same location as above |

### Salesforce Connected App setup

The Pardot API uses Salesforce OAuth 2.0 client_credentials flow. Your Connected App must have:

- OAuth scope: `pardot_api` and `offline_access`
- Client Credentials Flow enabled (Setup → App Manager → your app → OAuth policies)
- IP relaxation set to "Relax IP restrictions" (or Vercel egress IPs whitelisted)

## Bot protection layers

| Layer | Description |
|-------|-------------|
| **reCAPTCHA v3** | Silent background score (0–1). Submissions scoring below 0.5 are rejected server-side. |
| **Honeypot field** | Off-screen hidden input. Bots that fill it are silently dropped without an error response. |
| **Timing check** | Submissions arriving less than 3 seconds after page render are rejected as bot-speed. |
| **Field allowlist** | Only field names defined in the Pardot form handler are forwarded. Extra fields are stripped. |

## How submission works

1. User submits the form.
2. reCAPTCHA v3 fires silently (if enabled) and returns a token.
3. Browser POSTs to `/api/pardot/submit` on the OM1 server.
4. Server checks honeypot → timing → reCAPTCHA score → field allowlist.
5. Server fetches the Pardot Form Handler endpoint URL from the Pardot API (cached 1 hour).
6. Server POSTs sanitised fields to the Pardot Form Handler endpoint.
7. Pardot returns HTTP 302 on success.
8. Browser replaces the form with the success message.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Component renders nothing | One or more environment variables are missing. Check Vercel env vars. |
| Wrong fields or no fields | Verify `formHandlerId` in Contentful. Cache revalidates every hour — redeploy to force a refresh. |
| "CAPTCHA score too low" errors | Check the [reCAPTCHA Admin Console](https://www.google.com/recaptcha/admin) for score distributions. Set `captchaEnabled: false` as a temporary workaround. |
| Pardot API 401 Unauthorized | `PARDOT_CONSUMER_KEY` or `PARDOT_CONSUMER_SECRET` is wrong. Check Salesforce App Manager. |
| Pardot API 403 Forbidden | Connected App missing `pardot_api` scope, or Vercel IPs are blocked. Set IP relaxation to "Relax IP restrictions". |