Formbricks

Stateful mock of Formbricks (as our fork, geviti-formbrick, serves it) for test suites: the client environment state our member app and backend load surveys from, response creation with the fork's validation and {code, message, details} errors, the v1 management API (responses and surveys, x-api-key), the widget script the web SDK loads, and the responseFinished webhook that nothing sends in non-prod today. Surveys are seeded from our committed production clone (packages/forms-fixtures/formbricks/prod-clone.json).

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from the fork's route handlers and our consumers.

#Install

npm install -D @crvouga/mockingbird-service-formbricks

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-formbricks serve, createServer from ./server (Node), or createRuntime with any Fetch server.

#Usage

Point FORMBRICKS_APP_URL at the mock (instead of the backend's compat shim), keep FORMBRICKS_ENVIRONMENT_ID (cmlhiza9j0009lj01my5c1g0q production or cmlhiza9c0004lj01jbuhp0nz development; both serve the clone), set any FORMBRICKS_API_KEY, and pass the backend's FORMBRICKS_WEBHOOK_SECRET as --webhook-token.

npx mockingbird-formbricks serve --port 8813 \
  --webhook-url http://127.0.0.1:3000/onboarding-tasks/formbricks-webhook \
  --webhook-token "$FORMBRICKS_WEBHOOK_SECRET"

import { createRuntime } from "@crvouga/mockingbird-service-formbricks"

const formbricks = createRuntime({
  webhooks: { url: "http://127.0.0.1:3000/onboarding-tasks/formbricks-webhook?token=s3cret" },
})
// …the member app POSTs /api/v2/client/<env>/responses {surveyId, finished: true, data, userId}…
// the mock validates it, stores it, and posts responseFinished to the backend.
const response = await formbricks.fetch(new Request("http://formbricks.test/__admin/responses"))

#Routes

Management routes need x-api-key (any non-empty key, unless apiKeys is set), else 401 {code: "not_authenticated", message: "Not authenticated", details: {"x-Api-Key": "…"}}.

#Webhooks

POST <webhook-url> (carrying our ?token=) with {webhookId, event, data: {...response, survey: {title, type, status, createdAt, updatedAt}}}, headers webhook-id, webhook-timestamp and, when the endpoint has a whsec_… secret, webhook-signature: v1,<base64 HMAC-SHA256> (Standard Webhooks; our receiver does not verify it). Only events an endpoint subscribes to are sent: responseFinished by default (events: ["responseCreated", "responseFinished"] for both). Retries, GET /__admin/webhooks, …/events, …/replay, …/flush and PUT /__admin/webhook-endpoints work as usual.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): rate_limited (429 too_many_requests; the member app retries ×3), server_error (500), missing_response_id (stored, but no id in the answer), environment_unavailable, data_as_string (management data as a JSON string), management_unauthorized, connection_drop, duplicate (the next webhook twice: our receiver does not dedupe), webhook_drop, webhook_reorder.

#Namespaces

x-mockingbird-namespace, a /ns/<name> prefix on FORMBRICKS_APP_URL, or by credential: the environment id in the client paths (the member app's fetch cannot add headers) or the management x-api-key, through PUT /__admin/credentials {"credentials": {"<env id or key>": "<namespace>"}}.

#Deliberately not modelled

• Formbricks' Postgres: backend eRx and the form sources also read it directly (FORMBRICKS_DATABASE_URL); an HTTP mock cannot cover that path.
• The rest of the JS SDK protocol (displays, contacts/identify, app/sync, storage): the widget script is a no-op, so the SDK never calls them.
• Quotas (always quotaFull: false), single-use links, reCAPTCHA, the "other" option length check, custom validation.rules on elements (only required and the implicit openText email / url / phone rules are applied), response updates (PUT …/responses/{id}).
• Survey editing beyond create; the Formbricks UI.

#API

Part of mockingbird.