@crvouga/mockingbird-service-firstpromoter 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog — @crvouga/mockingbird-service-firstpromoter
 
+## 3.1.0 (2026-10-08)
+
+### Features
+
+- redesign emulator experience ([d6038c2](https://github.com/crvouga/mockingbird/commit/d6038c27eebbaa1751f02bc9305002a5b1304779))
+
+### Dependencies
+
+- `@crvouga/mockingbird-service-sqlite`
+
 ## 3.0.0 (2026-10-07)
 
 ### ⚠️ Breaking changes
@@ -14,10 +24,6 @@
 - typecheck the brand gate before builds ([fc36095](https://github.com/crvouga/mockingbird/commit/fc3609514de70ffe3170a5d216fb8a49f9ce7cbb))
 - format the emulates records query ([8698872](https://github.com/crvouga/mockingbird/commit/8698872509d06002be5a8fcdc85d79f8462320c3))
 
-### Dependencies
-
-- `@crvouga/mockingbird-service-sqlite`
-
 ## 2.3.0 (2026-10-04)
 
 ### Features

package/DISCOVERY.md

@@ -1,7 +1,7 @@
 # @crvouga/mockingbird-service-firstpromoter discovery
 
 This is the installed-package index for coding agents and tooling. All relative links resolve
-inside `node_modules/@crvouga/mockingbird-service-firstpromoter/`; no repository checkout is needed to discover the mock's
+inside `node_modules/@crvouga/mockingbird-service-firstpromoter/`; no repository checkout is needed to discover the emulator's
 supported surface or documented behavior.
 
 ## Capability and behavior sources
@@ -48,7 +48,7 @@ designed for assertions and diagnosis by consuming test suites.
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
-operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
 documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
 customer data, prompts, PHI, card data, or unredacted recordings.
 

package/README.md

@@ -1,8 +1,8 @@
 # @crvouga/mockingbird-service-firstpromoter
 
-> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
 
-Stateful mock of the **FirstPromoter v2** affiliate API for test suites: promoter create (adopt
+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
@@ -25,7 +25,7 @@ with any Fetch server.
 
 ## Usage
 
-Point `FIRST_PROMOTER_API_URL` at the mock (our Joi schema requires `https`, so either front it
+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`.
 
@@ -53,7 +53,7 @@ const admin = (path: string, body: unknown) =>
 // 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
+// …the app's invoice handler posts POST /v2/track/signup {email, tid}; the emulator converts the
 // referral and posts lead_becomes_referral to the backend with Authorization: Basic…
 ```
 
@@ -113,7 +113,7 @@ Commission reconciliation follows FirstPromoter's [published contract](https://g
 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
-mock they move to in_progress after the clock advances and complete at 1,000 ms, on the next
+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
@@ -144,16 +144,16 @@ deduplication. A successful sale preserves the existing conversion webhook behav
 
 - 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.
+  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 mock to v2.
+  `/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.
 - Sale tracking requires an existing referral (the vendor's one-step signup bypass is unmodelled).
   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 mock policies, not live-verified
+  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.
@@ -162,8 +162,8 @@ deduplication. A successful sale preserves the existing conversion webhook behav
 
 | 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`. |
+| `FirstPromoterAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `render(promoter)`, `click(refToken)`, `convert(referralId, saleAmount?)`, `seedPromoter(input)`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`. |
+| `createRuntime` | function | The emulator 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`. |

package/SUPPORT.md

@@ -3,10 +3,10 @@
 Generated from `openapi.yaml`; do not edit by hand.
 
 - operations in spec: **16**
-- supported by the mock: **16**
+- supported by the emulator: **16**
 - parity enabled: **16**
 
-| operationId | route | mock | parity | notes |
+| operationId | route | emulator | parity | notes |
 | --- | --- | --- | --- | --- |
 | `TrackSignup` | `POST /v2/track/signup` | ✅ supported | ⚠️ unsafe (opt-in) |  |
 | `ListPromoters` | `GET /v2/company/promoters` | ✅ supported | ✅ |  |