@crvouga/mockingbird-service-firstpromoter 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog — @crvouga/mockingbird-service-firstpromoter
 
-## 3.6.0 (2026-10-17)
+## 3.8.0 (2026-10-21)
+
+### Features
+
+- raise the serve and fleet body limit to the S3 maximum ([86b9e2b](https://github.com/crvouga/mockingbird/commit/86b9e2b80bcaaaef57f52edbac50b27da0b42f33))
+- validate block limits, filter nutrients, list block children ([2acb823](https://github.com/crvouga/mockingbird/commit/2acb823ba66b30f3d03221996e015c127b0f72c6))
+
+## 3.7.0 (2026-10-18)
+
+### Features
+
+- resolve the agent-reported issue queue in one batch ([25c52b6](https://github.com/crvouga/mockingbird/commit/25c52b668a53ddb80b968419601a20abf33f956b))
+
+## 3.6.0 (2026-10-16)
 
 ### Features
 

package/README.md

@@ -74,11 +74,12 @@ await server.close()
 | --- | --- |
 | `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://acme.example/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"}`. |
+| `GET /v2/company/promoters/{value}?find_by=id\|cust_id\|auth_token\|ref_token\|promo_code\|email` | One promoter (archived ones too, with `archived_at`), or 404 `{message: "Promoter not found"}`. `promo_code` resolves codes seeded through `POST /__admin/promo-codes` to the promoter owning that campaign enrolment. `auth_token` is a deterministic per-promoter token that `POST` / `GET /__admin/promoters` report as `auth_token` (the vendor's promoter schema has no such field, so the promoter body does not carry it). Any other `find_by` is 400. |
 | `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. |
+| `PUT /v2/company/commissions/{id}` | `{internal_note?, external_note?}` (the vendor's `CommissionUpdate`) → the updated commission, reflected in `GET /v2/company/commissions`; other fields are not writable. An unknown id is 404 `{message: "Commission not found", code: "not_found"}`. |
 | `GET /v2/company/referrals` | A bare array of stored referrals and live promoter/campaign metadata. `q` searches email/uid; `ids[]`, `filters[type]=lead\|customer`, `filters[state]`, `filters[promoter_id]`, and inclusive `filters[created_at\|customer_since][from\|to]` filter before paging. `page` starts at 1; `per_page` defaults to 20 (max 100). Exhausted pages and unmatched searches return `[]`. |
 | `GET /v2/company/referrals/{id}` | The same referral projection as listing. A numeric ID or `find_by=email\|uid` selects it; missing records are 404. |
 
@@ -109,7 +110,7 @@ is `user:pass`. Non-2xx answers are retried; `GET /__admin/webhooks`, `…/event
 | `POST /__admin/referrals/:id/convert` | `{saleAmount?}`: the lead paid; credits the promoter (percent reward × amount) and posts the webhook. |
 | `POST /__admin/commissions` | Seed a commission against an existing `{promoter_campaign_id, amount, unit?, status?, fulfilled?, is_paid?, referral_id?, sale_amount?, event_id?}`. Defaults: approved, points, unfulfilled/unpaid. A referral must belong to that promoter and campaign. |
 | `POST /__admin/promo-codes` | Seed `{promo_code, promoter_campaign_id}` against an existing promoter campaign for sale attribution tests. |
-| `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 `ACME50`. |
+| `GET\|PUT /__admin/settings` | `{website?, defaultCampaignId?, autoConvert?, promoCodeCreatesReferral?, campaigns?}` (campaigns carry `referralRewards` / `promoterRewards` with `coupon`, `amount`, `unit`, `per_of_sale`). The default campaign's referral coupon is `ACME50`. |
 
 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`
@@ -146,6 +147,24 @@ Codes must be seeded through the admin control; tokens must belong to the referr
 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](https://github.com/firstpromoter/docs/blob/d4e9e6f16bf4801c524508d2809a425ea6419d7d/api-reference-v2/api-admin/tracking-api/openapi-v2-tracking.json)
+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:
@@ -161,8 +180,8 @@ deduplication. A successful sale preserves the existing conversion webhook behav
 - 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
+- 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.

package/SUPPORT.md

@@ -2,9 +2,9 @@
 
 Generated from `openapi.yaml`; do not edit by hand.
 
-- operations in spec: **16**
-- supported by the emulator: **16**
-- parity enabled: **16**
+- operations in spec: **17**
+- supported by the emulator: **17**
+- parity enabled: **17**
 
 | operationId | route | emulator | parity | notes |
 | --- | --- | --- | --- | --- |
@@ -20,6 +20,7 @@ Generated from `openapi.yaml`; do not edit by hand.
 | `ListCommissions` | `GET /v2/company/commissions` | ✅ supported | ✅ |  |
 | `FulfillCommissions` | `POST /v2/company/commissions/mark_fulfilled` | ✅ supported | ⚠️ unsafe (opt-in) |  |
 | `DestroyCommissions` | `DELETE /v2/company/commissions/destroy` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `UpdateCommission` | `PUT /v2/company/commissions/{id}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
 | `ListBatchProcesses` | `GET /v2/company/batch_processes` | ✅ supported | ✅ |  |
 | `BatchProcessProgress` | `GET /v2/company/batch_processes/progress` | ✅ supported | ✅ |  |
 | `GetBatchProcess` | `GET /v2/company/batch_processes/{id}` | ✅ supported | ✅ |  |

package/dist/{chunk-QTSDT26U.js → chunk-C6B3TYF4.js}

@@ -3,17 +3,31 @@ import {
   createRuntime,
   normalizeBootControls,
   normalizeControls,
+  normalizeIdBase,
   ownedTransport,
   parseDuration,
   parseFaultHeader,
   resolveAdminPrefix,
   restoreClock
-} from "./chunk-OHWRVHV3.js";
+} from "./chunk-G6BNGSL2.js";
 
 // ../../adapters/node/dist/cli.js
 import { readFile as readFile5 } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
+// ../../adapters/node/dist/boot-settings.js
+var checkSettings = (target, settings, label) => {
+  if (!target.parseSettings)
+    throw new Error(`${label}: ${target.name} takes no boot settings`);
+  try {
+    return target.parseSettings(settings);
+  } catch (error) {
+    throw new Error(`${label}: ${error instanceof Error ? error.message : String(error)}`, {
+      cause: error
+    });
+  }
+};
+
 // ../../adapters/node/dist/fleet.js
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 import { createHash as createHash4, randomUUID as randomUUID4 } from "node:crypto";
@@ -2663,6 +2677,9 @@ var fleet_config_schema_default = {
     adminControls: {
       $ref: "#/$defs/controls"
     },
+    idBase: {
+      $ref: "#/$defs/idBase"
+    },
     namespace: {
       type: "string",
       pattern: "^[A-Za-z0-9_.-]{1,64}$"
@@ -2752,6 +2769,12 @@ var fleet_config_schema_default = {
         adminControls: {
           $ref: "#/$defs/controls"
         },
+        idBase: {
+          $ref: "#/$defs/idBase"
+        },
+        settings: {
+          type: "object"
+        },
         fixtures: {
           type: "object"
         },
@@ -2798,6 +2821,18 @@ var fleet_config_schema_default = {
         }
       }
     },
+    idBase: {
+      anyOf: [
+        {
+          type: "integer",
+          minimum: 0
+        },
+        {
+          type: "string",
+          pattern: "^(boot|[0-9]+)$"
+        }
+      ]
+    },
     controls: {
       type: "object",
       additionalProperties: false,
@@ -2947,6 +2982,8 @@ async function preflightFleet(config, options) {
     throw new Error("protected archive policy requires a protected repository; configure its protector before startup");
   resolveAdminPrefix(config.adminPrefix);
   normalizeBootControls(config.adminControls);
+  if (config.idBase !== void 0)
+    normalizeIdBase(config.idBase, "idBase");
   const targets = /* @__PURE__ */ new Map();
   const ports = /* @__PURE__ */ new Set();
   for (const [name, entry] of Object.entries(config.services)) {
@@ -2978,6 +3015,13 @@ async function preflightFleet(config, options) {
             throw new Error("invalid protocol namespace selector");
         }
       }
+      if (entry.idBase !== void 0)
+        normalizeIdBase(entry.idBase, "idBase");
+      if (entry.settings !== void 0) {
+        if (protocol !== "http" || !("create" in target))
+          throw new Error("settings: only HTTP services take boot settings");
+        checkSettings(target, entry.settings, "settings");
+      }
       const port = entry.port ?? target.defaultPort;
       if (port !== 0) {
         const key = `${entry.host ?? "127.0.0.1"}:${port}`;
@@ -3013,7 +3057,7 @@ async function preflightFleet(config, options) {
             break;
         }
       }
-      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.6.0" });
+      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.8.0" });
     } catch (error) {
       throw new Error(`service ${name}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
@@ -3239,7 +3283,11 @@ var serve = async (api, options = {}) => {
 // ../../adapters/node/dist/listen.js
 var listen = async (api, options = {}) => {
   const host = options.host ?? "127.0.0.1";
-  const server = await serve(api, { port: options.port ?? 0, host });
+  const server = await serve(api, {
+    port: options.port ?? 0,
+    host,
+    ...options.maxBodyBytes !== void 0 ? { maxBodyBytes: options.maxBodyBytes } : {}
+  });
   const address = server.address();
   const port = typeof address === "object" && address !== null ? address.port : options.port ?? 0;
   const shown = host.includes(":") ? `[${host}]` : host;
@@ -3333,6 +3381,7 @@ var httpChild = async (target, entry, options, admission, generation, privateAcc
       options.onLog?.(entry2);
     },
     ...entry.adminControls !== void 0 ? { adminControls: entry.adminControls } : {},
+    ...entry.settings !== void 0 ? { settings: checkSettings(target, entry.settings, "settings") } : {},
     ...entry.fixtures !== void 0 ? { fixtures: entry.fixtures } : {},
     ...(advertisedHttpBase(entry) ?? entry.baseUrl) !== void 0 ? { baseUrl: advertisedHttpBase(entry) ?? entry.baseUrl } : {}
   });
@@ -3351,6 +3400,8 @@ var httpChild = async (target, entry, options, admission, generation, privateAcc
   ].some((method) => typeof created[method] !== "function"))
     throw new Error("HTTP target does not implement the fleet runtime protocol; build/install matching supported service versions");
   const runtime = created;
+  if (entry.idBase !== void 0)
+    runtime.setIdBase?.(entry.idBase);
   const unobserve = runtime.webhooks?.observeDeliveries(observer.delivery);
   if (options.outbound && runtime.webhooks)
     runtime.webhooks.setTransportPolicy(ownedTransport(options.outbound));
@@ -3435,7 +3486,8 @@ var httpChild = async (target, entry, options, admission, generation, privateAcc
   try {
     server = await listen(api, {
       port: entry.port ?? target.defaultPort,
-      host: entry.host ?? "127.0.0.1"
+      host: entry.host ?? "127.0.0.1",
+      ...target.maxBodyBytes !== void 0 ? { maxBodyBytes: target.maxBodyBytes } : {}
     });
     target.listening?.(server);
   } catch (error) {
@@ -3949,6 +4001,7 @@ async function startFleet(config, options) {
           ...entry,
           adminPrefix: resolveAdminPrefix(entry.adminPrefix ?? adminPrefix),
           ...adminKey !== void 0 ? { adminKey } : {},
+          ...(entry.idBase ?? config.idBase) !== void 0 ? { idBase: entry.idBase ?? config.idBase } : {},
           // Fleet-wide controls, with the service's own keys replacing them.
           ...config.adminControls !== void 0 || entry.adminControls !== void 0 ? { adminControls: { ...config.adminControls, ...entry.adminControls } } : {}
         }, options, (namespace, request) => management?.admit(namespace, request), (namespace) => management?.generation(namespace), (namespace, request) => management?.privateRequest(namespace, request) ?? false, {
@@ -4633,6 +4686,16 @@ var COMMON_SERVE_OPTIONS = {
     value: "<seed>",
     description: "Seed for every random choice (env MOCKINGBIRD_SEED)"
   },
+  "id-base": {
+    type: "string",
+    value: "<n|boot>",
+    description: "Start generated ids at this base so a restart does not reissue the last boot's ids; boot derives one from the clock (env MOCKINGBIRD_ID_BASE; default 0, the same ids every boot)"
+  },
+  settings: {
+    type: "string",
+    value: "<json|file>",
+    description: "Service settings to boot with, as JSON or a JSON file; every namespace starts from them (env MOCKINGBIRD_SETTINGS; only for services that declare settings)"
+  },
   "admin-controls": {
     type: "string",
     value: "<json|file>",
@@ -4727,19 +4790,40 @@ var readJsonFile = async (path, label) => {
   }
 };
 var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readJsonOption = async (source, label) => {
+  const trimmed = source.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      throw new Error(`${label}: not valid JSON`);
+    }
+  }
+  return readJsonFile(source, label);
+};
+var resolveServeIdBase = (values, env = process.env) => {
+  const source = asString(values["id-base"]) ?? env.MOCKINGBIRD_ID_BASE;
+  if (source === void 0 || source.trim() === "")
+    return void 0;
+  normalizeIdBase(source.trim(), "--id-base");
+  return source.trim();
+};
+var resolveServeSettings = async (target, values, env = process.env) => {
+  const flag = asString(values.settings);
+  const source = flag ?? env.MOCKINGBIRD_SETTINGS;
+  if (source === void 0 || source.trim() === "")
+    return void 0;
+  const label = flag !== void 0 ? "--settings" : "MOCKINGBIRD_SETTINGS";
+  const parsed = await readJsonOption(source, label);
+  if (!isObject2(parsed))
+    throw new Error(`${label}: expected a JSON object`);
+  return checkSettings(target, parsed, label);
+};
 var resolveServeControls = async (values, env = process.env, base) => {
   const source = asString(values["admin-controls"]) ?? env.MOCKINGBIRD_ADMIN_CONTROLS;
   let document = isObject2(base) ? { ...base } : {};
   if (source !== void 0 && source.trim() !== "") {
-    let parsed;
-    if (source.trim().startsWith("{")) {
-      try {
-        parsed = JSON.parse(source);
-      } catch {
-        throw new Error("--admin-controls: not valid JSON");
-      }
-    } else
-      parsed = await readJsonFile(source, "--admin-controls");
+    const parsed = source.trim().startsWith("{") ? await readJsonOption(source, "--admin-controls") : await readJsonFile(source, "--admin-controls");
     if (!isObject2(parsed))
       throw new Error("--admin-controls: expected a JSON object");
     document = { ...document, ...parsed };
@@ -4789,9 +4873,16 @@ var start = async (target, values, config) => {
     adminKey: config.adminKey,
     seed: config.seed,
     onLog: formatLog(config.log),
+    ...config.settings !== void 0 ? { settings: config.settings } : {},
     ...config.adminControls !== void 0 ? { adminControls: config.adminControls } : {}
   });
-  const listening = await listen(runtime, { port: config.port, host: config.host });
+  if (config.idBase !== void 0)
+    runtime.setIdBase?.(config.idBase);
+  const listening = await listen(runtime, {
+    port: config.port,
+    host: config.host,
+    ...target.maxBodyBytes !== void 0 ? { maxBodyBytes: target.maxBodyBytes } : {}
+  });
   target.listening?.(listening);
   console.log(`${target.name} emulator listening on ${listening.url}`);
   console.log(`${target.name} health: GET ${listening.url}${adminPrefix}/health`);
@@ -4836,6 +4927,11 @@ var serveCommand = (target) => ({
         const adminControls = await resolveServeControls(values, process.env, config.adminControls);
         if (adminControls !== void 0)
           config.adminControls = adminControls;
+        if (values.settings !== void 0)
+          throw new Error("--settings serves a single service; give each service its own `settings` in the config");
+        const idBase = config.idBase ?? resolveServeIdBase(values);
+        if (idBase !== void 0)
+          config.idBase = idBase;
         const fleet = await startFleet(config, {
           load: (name) => loadTarget(name, target),
           onLog: formatLog(config.log ?? log),
@@ -4865,8 +4961,12 @@ var serveCommand = (target) => ({
     let listening;
     try {
       const adminControls = await resolveServeControls(values);
+      const idBase = resolveServeIdBase(values);
+      const settings = await resolveServeSettings(target, values);
       listening = await start(target, values, {
         ...adminControls !== void 0 ? { adminControls } : {},
+        ...idBase !== void 0 ? { idBase } : {},
+        ...settings !== void 0 ? { settings } : {},
         adminPrefix: resolveAdminPrefix(asString(values["admin-prefix"]) ?? process.env.MOCKINGBIRD_ADMIN_PREFIX),
         port: port === void 0 ? target.defaultPort : Number.parseInt(port, 10),
         host: asString(values.host) ?? "127.0.0.1",
@@ -4934,4 +5034,4 @@ export {
   createServer2 as createServer,
   serveTarget
 };
-//# sourceMappingURL=chunk-QTSDT26U.js.map
+//# sourceMappingURL=chunk-C6B3TYF4.js.map