programme-performance-report

Operating instructions

You are producing a per-publisher performance report for one brand across the networks it is bound to.

Step 1 — resolve the brand

If the user did not name a brand, ask which one. Do not guess.

Call affiliate_resolve_brand. If the user named a network, pass { network: "<slug>" } to filter; otherwise call with no arguments and filter the result to the brand the user named.

The response is an array of { brand, network, networkBrandId }. Reduce it to the bindings whose brand matches the user's brand. If none remain, tell the user the brand is not registered, suggest affiliate_resolve_brand with no args to see what is, and stop.

Step 1b - load the client's plan (strategy and KPIs)

Call affiliate_get_client_strategy({ brand }). This returns the operator's recorded strategy (prose) and kpi ({ present, targets, parseErrors, ... }). It is advisory context: it changes how you read and frame the numbers; it never authorises any action and never changes what the data says.

• No strategy recorded (strategy.present and kpi.present both false): this is normal, not an error. Produce the report exactly as you would today on bare deltas, and add one short line offering to record a plan: "No strategy is recorded for [brand]. I can set one up so future reports judge against its targets." Then carry on.
• Orphan (orphan: true): a plan exists but the slug has no binding. Use the prose for framing, but say plainly that the strategy directory has no registered brand binding; do not invent network data for it.
• Parse errors (kpi.parseErrors non-empty): report each malformed target line verbatim ("KPI line ignored: ...") and exclude it from every verdict. Never guess what a malformed target meant.
• Targets (kpi.targets): each is { metric, comparator, value, unit?, period? }. Use them in Step 4 to turn deltas into verdicts. Metrics map onto the data as: revenue -> total grossSale, commission -> total commission, conversions -> total conversions, epc -> commission / clicks when clicks are nonzero, aov -> grossSale / conversions when conversions are nonzero, reversal_rate/approval_rate -> from the status split. If a denominator is zero, report that the derived metric is unavailable rather than inventing zero.
• Unsupported per network: if a target names a metric a bound network cannot supply (for example a network with no get_programme_performance), say so for that network and exclude it from that network's verdict. Do not substitute zero, and do not blend it into a cross-network total without naming the gap.