@crvouga/mockingbird-service-firstpromoter

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the FirstPromoter v2 affiliate API for test suites: promoter create (adopt before create by cust_id), lookups by id / cust_id / ref_token / email, list, update, archive, the dashboard iframe login, signup tracking by click tid, promoter_id or ref token, and the Basic-auth lead_becomes_referral webhook our backend receives. Every request is recorded in the journal, so a checkout suite can assert what the post-checkout job sent instead of producing a failed job.

• Operation coverage: SUPPORT.md
• FirstPromoter publishes no machine-readable spec: the contract (openapi.yaml) is hand-authored from our consumer's requests and the zod schemas it validates responses with.

Install

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

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

Usage

Point FIRST_PROMOTER_API_URL at the emulator (our Joi schema requires https, so either front it with TLS or relax that rule in the stack), set any FIRST_PROMOTER_API_KEY and FIRST_PROMOTER_ACCOUNT_ID, and pass the webhook Basic-auth pair as --webhook-secret.

npx mockingbird-firstpromoter serve --port 8812 \
  --webhook-url http://127.0.0.1:3000/users/webhooks/first-promoter \
  --webhook-secret "$FIRST_PROMOTER_WEBHOOK_AUTH_USERNAME:$FIRST_PROMOTER_WEBHOOK_AUTH_PASSWORD"

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

// Test setup: the emulator, an existing affiliate, and a click on their link.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/users/webhooks/first-promoter", secret: "user:pass" },
})
const admin = (path: string, body: unknown) =>
  fetch(`${server.url}/__admin${path}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  })
await admin("/promoters", { email: "[email protected]", ref_token: "nate91" })
// The tid checkout stores as fp_tid.
const { tid } = (await (await admin("/clicks", { ref_token: "nate91" })).json()) as { tid: string }

// Application code: FIRST_PROMOTER_API_URL is server.url. The invoice handler tracks the signup.
const baseUrl = server.url
const tracked = await fetch(`${baseUrl}/v2/track/signup`, {
  method: "POST",
  headers: {
    authorization: "Bearer fp-api-key",
    "Account-ID": "acct_1",
    "content-type": "application/json",
  },
  body: JSON.stringify({ email: "[email protected]", tid }),
})
// The emulator converts the referral and posts lead_becomes_referral to the backend with
// Authorization: Basic…
await server.close()

Routes

The official referral reference specifies the bare array. Paging parameters and limits follow the official n8n client and input definitions.

Every call needs Authorization: Bearer <key> and an Account-ID header (else 401).

Webhooks

lead_becomes_referral bodies match our FirstPromoterNewCustomerWebhookSchema: {event: {id, type, created_at}, data: {id, state, email, customer_since, promotion: {id, promoter_id, ref_id, leads_count, customers_count, current_referral_reward}, promoter: {id, cust_id, email, earnings_balance: {cash}}}}, sent with Authorization: Basic base64(<secret>) where the secret is user:pass. Non-2xx answers are retried; GET /__admin/webhooks, …/events, …/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): created_but_500 (stored, then 500: the retry must adopt by cust_id), lookup_unavailable (lookups 503: neither create nor adopt), no_campaign (no promoter_campaigns: no ref link), unauthorized, rate_limited, server_error, connection_drop, webhook_duplicate, webhook_drop.

Commission reconciliation follows FirstPromoter's published contract: GET /v2/company/commissions returns a bare array, newest first, with q, repeated ids[], page / per_page (1 / 20 by default, maximum 100), and filters for status, nonmonetary fulfilled=yes|no, monetary paid=yes|no, promoter_id, campaign_id, amount / sale-amount ranges and creation-date ranges. POST …/commissions/mark_fulfilled fulfills nonmonetary commissions; DELETE …/commissions/destroy deletes selected commissions. Both take {ids}. Batches of at most five IDs return 200/completed; larger batches return 202/pending. In the emulator they move to in_progress after the clock advances and complete at 1,000 ms, on the next authenticated API call. The batch collections and pending work participate in reset and snapshots. GET …/batch_processes and …/batch_processes/progress list unfinished work by default (filters[status] selects another status); GET …/batch_processes/{id} returns counts and processing errors. batch_partial_failure fails the first selected item while processing the others. Timing, missing-ID/monetary-item error text, and this preset are synthetic controls; they are not claims about the vendor's worker timing or exact error messages. Fulfillment is stored separately from the vendor's is_paid monetary field.

POST /v2/track/sale follows the vendor's sale contract: {event_id, amount, email|uid, currency?, plan?, promo_code?, ref_id?, tid?, skip_email_notification?} records a positive integer amount in minor units against a tracked referral. The first configured campaign reward supplies an approved commission; percent rewards are rounded to the nearest minor unit, and flat rewards use their configured amount. Cash rewards also credit the existing promoter balance; nonmonetary rewards do not. The response includes the referral, amount and linked commissions, visible in the commission collection. Replaying an event ID returns the documented 409 without another credit, commission or webhook. Unknown referrals, archived promoters and unmatched supplied attribution tokens return the documented 404 not_found shape. Codes must be seeded through the admin control; tokens must belong to the referral's promoter campaign. All validation precedes sale/commission/balance writes; snapshots/reset include event deduplication. A successful sale preserves the existing conversion webhook behavior.

When no lead matches email / uid, the vendor's tracking contract lets tid or ref_id "bypass the signup tracking": the lead is created and the sale assigned in one request. The emulator does the same when the tid (a click from POST /__admin/clicks) or ref_id resolves to a live promoter and the request names the lead by email; the new lead counts toward the promoter's referrals, becomes a customer and posts lead_becomes_referral. This is docs-verified (the tracking OpenAPI above), not oracle-verified. uid alone cannot name a new lead, and an email that is already a lead under another uid is 422 (as in signup tracking).

promo_code alone: best guess, not oracle-verified. The vendor documents nothing further for promo_code ("For promo code tracking"), so whether a sale carrying only a promo code creates the lead is unobserved. Default (promoCodeCreatesReferral: false): a sale for an unknown buyer with only promo_code is the same 404 as any unattributed sale, and nothing is stored. Opt in with PUT /__admin/settings {"promoCodeCreatesReferral": true} to have a code seeded through POST /__admin/promo-codes create the lead (needs email), assign the sale to the promoter owning that campaign enrolment, and post lead_becomes_referral, exactly like tid / ref_id. An unseeded code is 404 in both modes. Treat a test that depends on this setting as depending on an emulator assumption until a live response is captured.

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix in FIRST_PROMOTER_API_URL, or by API key: PUT /__admin/credentials {"credentials": {"<FIRST_PROMOTER_API_KEY>": "<namespace>"}}.

Deliberately not modelled

• Error bodies and exact status codes of the real API are unverified (no sandbox credentials): errors use {message} and validation {message, errors: {field: [...]}}. Our consumer only branches on ok / 404, which the emulator gets right.
• The v1 API our EMR backend still calls (/v1/promoters/*, /v1/track/signup, /v1/reports/campaigns); the catalog scopes this emulator to v2.
• Refunds, standalone commission creation/editing/approval, cash payouts and commission filters beyond those listed above; fraud checks; public promo-code provisioning; the hosted affiliate portal behind the iframe token.
• Creating a lead from promo_code alone is off by default (promoCodeCreatesReferral): the vendor documents the one-step bypass only for tid and ref_id, so the opt-in behavior is a best guess, not oracle-verified.
• Currency is recorded without foreign-exchange conversion; plan-specific rewards, quantity/MRR calculations, multiple reward tiers, split commissions and notification emails are unmodelled. Commission rounding and immediate approval are deterministic emulator policies, not live-verified campaign policy. The default campaign reward remains 10 percent, as before.
• Referral editing/deletion, username/website profile provisioning, cancelled-date filters and split attribution.
• Promoter ids are sequential from 4800001 per namespace.

API

Part of mockingbird.