@crvouga/mockingbird-service-firstpromoter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-firstpromoter
+
+## 0.1.0 (2026-09-22)
+
+Initial release.

package/README.md

@@ -0,0 +1,127 @@
+# @crvouga/mockingbird-service-firstpromoter
+
+Stateful mock 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](https://github.com/crvouga/mockingbird/blob/main/packages/service/firstpromoter/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
+
+```bash
+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 mock (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`.
+
+```bash
+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"
+```
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-firstpromoter"
+
+const fp = createRuntime({
+  webhooks: { url: "http://127.0.0.1:3000/users/webhooks/first-promoter", secret: "user:pass" },
+})
+const admin = (path: string, body: unknown) =>
+  fp.fetch(
+    new Request(`http://fp.test/__admin${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    }),
+  )
+
+// An existing affiliate, and a click on their link: the tid checkout stores as fp_tid.
+await admin("/promoters", { email: "nate@example.com", ref_token: "nate91" })
+const { tid } = (await (await admin("/clicks", { ref_token: "nate91" })).json()) as { tid: string }
+// …the app's invoice handler posts POST /v2/track/signup {email, tid}; the mock converts the
+// referral and posts lead_becomes_referral to the backend with Authorization: Basic…
+```
+
+### Routes
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /v2/company/promoters` | `{email, cust_id?, profile?: {first_name, last_name}, drip_emails?, initial_campaign_id?}` → the promoter (`FirstPromoterV2ResponseSchema`), enrolled in the default campaign with a `ref_token` (first name + digits) and `ref_link` `https://gogeviti.com/referrals?fpr=<token>`. A live promoter with the same email or `cust_id` is 422 `{message, errors: {email: ["has already been taken"]}}`. |
+| `GET /v2/company/promoters?page=&per_page=` | `{data: [promoter], meta: {pending_count}}`; archived promoters are left out. |
+| `GET /v2/company/promoters/{value}?find_by=id\|cust_id\|ref_token\|email` | One promoter (archived ones too, with `archived_at`), or 404 `{message: "Promoter not found"}`. |
+| `PUT /v2/company/promoters/{id}` | `{cust_id?, email?, note?, profile?}` → the promoter; 404 / 422 as above. |
+| `POST /v2/company/promoters/archive` | `{ids: [..]}` → a completed batch `{id, status, total, selected_total, processed_count, failed_count, action_label, progress, processing_errors, …}`. |
+| `POST /v2/promoters/iframe_login?promoter_id=` | `{access_token, expires_in}`, or 404. |
+| `POST /v2/track/signup` | `{email, tid? \| promoter_id? \| ref_id?, uid?, skip_email_notification?}` → the referral. An unknown `tid`, promoter or ref token is 404; none of them is 400; an email already tracked is 422. With `autoConvert` (default on) the referral becomes a customer at once and `lead_becomes_referral` is posted. |
+
+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)
+
+| Route | Effect |
+| --- | --- |
+| `POST /__admin/promoters` | Seed a promoter `{email, cust_id?, first_name?, last_name?, ref_token?, campaign_id?}`. |
+| `GET /__admin/promoters` | The namespace's promoters (stored form). |
+| `POST /__admin/clicks` | `{ref_token}` → `{tid, promoterId}`: a click on the promoter's link. |
+| `GET /__admin/referrals` | Tracked signups. |
+| `POST /__admin/referrals/:id/convert` | `{saleAmount?}`: the lead paid; credits the promoter (percent reward × amount) and posts the webhook. |
+| `GET\|PUT /__admin/settings` | `{website?, defaultCampaignId?, autoConvert?, campaigns?}` (campaigns carry `referralRewards` / `promoterRewards` with `coupon`, `amount`, `unit`, `per_of_sale`). The default campaign's referral coupon is `GEVITI50`. |
+
+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`.
+
+### Namespaces
+
+`x-mockingbird-namespace`, a `/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 mock gets right.
+- The v1 API our EMR backend still calls (`/v1/promoters/*`, `/v1/track/signup`,
+  `/v1/reports/campaigns`); the catalog scopes this mock to v2.
+- Sales, refunds, commissions and payouts beyond the single `convert` step; fraud checks;
+  promo codes; the hosted affiliate portal behind the iframe token.
+- Promoter ids are sequential from 4800001 per namespace.
+
+## API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `FirstPromoterAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `render(promoter)`, `click(refToken)`, `convert(referralId, saleAmount?)`, `seedPromoter(input)`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`. |
+| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `FIRSTPROMOTER_PRESETS` | object | Every named fault preset. |
+| `FIRSTPROMOTER_NAMESPACE` | string | The service name, `"firstpromoter"`. |
+| `WEBHOOK_PATH` | string | Our receiver's path, `/users/webhooks/first-promoter`. |
+| `DEFAULT_CAMPAIGNS`, `DEFAULT_SETTINGS` | values | The seeded campaigns and settings. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8812. |
+
+Part of [mockingbird](https://github.com/crvouga/mockingbird).