1272: wire up form to pardot - explore using form handler

[DNR500]

issue: 1272

Form Handler for Subscription form

Overview

This PR explores using a Pardot Form Handler on the backend to send subscription data via editor-api.

---

Key Considerations (Form Handler)

• Non-standard handling required for Form Handler integration
  Because Pardot Form Handlers do not provide a standard, structured API response contract, editor-api has had to use heuristic response handling (status/body pattern checks). This means outcomes are inferred rather than definitively confirmed on every request, and frontend error detail is necessarily less precise than a typical JSON API integration.

---

How to Test (Postman)

Request

• Method: POST
• URL: http://localhost:3009/api/subscriptions

Headers:

• Content-Type: application/json
• Accept: application/json

Body (raw JSON):

{
  "subscription": {
    "email": "teacher@example.com",
    "test_opt_in": true,
    "privacy_policy": true
  }
}

Expected Responses

• 200 OK → valid request, provider accepted
• 422 Unprocessable Content → validation error
• 503 Service Unavailable → provider unavailable / not configured
• 502 Bad Gateway → provider response rejected or ambiguous

Invalid Example

{
  "subscription": {
    "email": "bad-email",
    "test_opt_in": true,
    "privacy_policy": false
  }
}

[github-actions]

Test coverage

89.57% line coverage reported by SimpleCov.
Run: https://github.com/RaspberryPiFoundation/editor-api/actions/runs/25122661264

[Copilot]

Pull request overview

Introduces a new /api/subscriptions endpoint in editor-api that forwards subscription form submissions to a Pardot Form Handler, using heuristic response classification due to the lack of a structured provider API response.

Changes:

• Added Api::SubscriptionsController#create to validate subscription payloads and return standardized success/error responses.
• Implemented Subscriptions::PardotFormHandlerSubmitter to POST URL-encoded payloads to a configured Pardot Form Handler endpoint and classify outcomes.
• Wired up routing, CORS localhost subdomain support (dev/test), env/config, and added request/service specs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
app/controllers/api/subscriptions_controller.rb	Adds POST handler to validate and forward subscription requests via submitter.
app/services/subscriptions/pardot_form_handler_submitter.rb	Adds Faraday-based submitter with heuristic success/rejection/ambiguous classification.
config/routes.rb	Exposes POST /api/subscriptions route.
config/initializers/cors.rb	Broadens dev/test localhost CORS origin matching to allow one subdomain level.
config/application.rb	Adds PARDOT_SUBSCRIPTION_URL config entry for the submitter endpoint.
.env.example	Documents PARDOT_SUBSCRIPTION_URL.
spec/requests/api/subscriptions_spec.rb	Adds request specs covering validation and provider error propagation.
spec/services/subscriptions/pardot_form_handler_submitter_spec.rb	Adds submitter unit specs covering response classification and error handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

provider_payload uses .compact, which won’t remove false. If test_opt_in is false, this will still send Tester=false to the Pardot form handler, which many form handlers treat as “field present” and may incorrectly record the checkbox as selected. Consider only including the Tester field when test_opt_in is true (omit it entirely otherwise), or explicitly map to the exact value Pardot expects for an unchecked checkbox.

Suggested change

	{
	'email' => form_payload['email'],
	'Tester' => form_payload['test_opt_in']
	}.compact
	payload = {
	'email' => form_payload['email']
	}.compact
	payload['Tester'] = true if form_payload['test_opt_in'] == true
	payload