@crvouga/mockingbird-service-formbricks

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of open-source Formbricks (6.x) for test suites: the client environment state the JS SDK loads surveys from, response creation with upstream'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 response pipeline's responseCreated / responseFinished webhooks. Every namespace is seeded with a small synthetic survey corpus (src/corpus/surveys.json: NPS, Onboarding, Product Feedback, a link survey and a paused survey; invented content).

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from upstream Formbricks 6.0.0's route handlers and the docs.

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 the SDK's appUrl (and your management API base URL) at the emulator, use the workspace id cworkspace000000000000001 (or its legacy environment id cenvironment0000000000001, as older SDKs send), and any management API key.

npx mockingbird-formbricks serve --port 8813 \
  --webhook-url http://127.0.0.1:3000/webhooks/formbricks \
  --webhook-secret "whsec_…"

Boot it with your own settings and surveys, without a wrapper process or a PUT after boot:

npx mockingbird-formbricks serve \
  --settings '{"workspaces": ["cworkspace000000000000002"], "legacyEnvironmentIds": {"cenvironment0000000000002": "cworkspace000000000000002"}}' \
  --surveys ./surveys.json

--settings <json|file> (or MOCKINGBIRD_SETTINGS, or a fleet entry's settings) takes the fields of GET|PUT /__admin/settings, checked with their types (a misspelled key is an error). They are every namespace's defaults, a reset returns to them, and a field you give replaces the built-in value whole (give legacyEnvironmentIds and the default environment alias is gone). --workspace-id adds to the booted workspaces. --surveys <file> (a list, or {surveys: [...]}) adds your surveys after the corpus ones for every namespace, and they survive a reset. A survey whose id the corpus (or an earlier row) already has is skipped, a survey with no workspaceId is served by every configured workspace, and type, status and a legacy environmentId are handled as PUT /__admin/surveys handles them. --surveys-mode replace uses the file as the whole corpus. In a fleet, set options: {"surveys": "surveys.json"}.

import { WORKSPACE_ID } from "@crvouga/mockingbird-service-formbricks"
import { createServer } from "@crvouga/mockingbird-service-formbricks/server"

// Test setup: the emulator, posting response webhooks to the app's handler.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/webhooks/formbricks", secret: "whsec_…" },
})

// Application code: appUrl is server.url. Submit a response to the seeded NPS survey.
const appUrl = server.url
const created = await fetch(`${appUrl}/api/v2/client/${WORKSPACE_ID}/responses`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    surveyId: "csurveynps000000000000001",
    finished: true,
    data: { nps_score: 9 },
  }),
})
// → {data: {id, quotaFull: false}}. The emulator validates it, stores it, and posts
// responseFinished to the webhook.

// Test control: read what was stored.
const stored = await fetch(`${appUrl}/__admin/responses`)
await server.close()

Routes

Client routes take a workspace id or a legacy (pre-Formbricks-5) environment id in the path; both resolve to the same workspace.

Management surveys carry questions derived from blocks (block button labels on the block's last element), workspaceId, the legacy environmentId, and projectOverwrites. 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> 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). Only events an endpoint subscribes to are sent: responseFinished by default (events: ["responseCreated", "responseFinished"] for both). --webhook-token appends a ?token= for receivers that check one. 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), 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), webhook_drop, webhook_reorder.

Namespaces

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

Deliberately not modelled

• Displays, contacts / identify, user and storage routes of the client API (the widget script is a no-op, so the SDK never calls them); response updates (PUT …/responses/{id}).
• Quotas (always quotaFull: false), single-use links, PIN protection, reCAPTCHA, email verification, file-upload checks, custom validation.rules, survey logic, and the full survey schema on create (only the shapes above are checked).
• The Embedded Data ingest contract beyond its allow-list (locked fields, coercion, size limits), userAgent parsing (always {device: "desktop"}), and language canonicalization beyond common bare codes.
• Organizations, API-key permissions (unauthorized), and the rest of the management API; the Formbricks UI.

API

Part of mockingbird.