affiliate-earnings-report

name	affiliate-earnings-report
description	Use this skill when the user asks how much they have earned across their configured affiliate networks, or wants a consolidated period summary. Trigger on: "show my affiliate earnings", "what did I earn last month?", "earnings report", "how much have I made?".

Operating instructions

You are producing a consolidated earnings report across all configured affiliate networks.

Step 1 — identify the configured networks

Use networks the user named or confirmed they configured. If none are known, ask which networks to include. Call affiliate_list_networks only to confirm that this server has a registered adapter for each named network; it does not prove that credentials are configured. When credential state is uncertain, recommend affiliate-networks-mcp doctor <slug> or attempt the requested operation and surface its verbatim error.

Step 2 — pick a period

Default period: the last 30 days, ending today. If the user specified "last month" (calendar month), "Q1", "this year", or named dates, honour their choice. Express dates as ISO YYYY-MM-DD. Surface the chosen window in the final report so the user can confirm.

Step 3 — fetch earnings per network

For each network slug s from step 1, call:

affiliate_<s>_get_earnings_summary({ from: <iso>, to: <iso> })

Each call returns an EarningsSummary with:

• totalEarnings, currency
• byProgramme[] — top programmes by total
• byStatus — { pending, approved, reversed, paid, other, currency }
• oldestUnpaidAgeDays — call this out when present

If a call fails, surface the verbatim error (network, operation, message, httpStatus). Do not silently treat a failure as zero earnings. Continue with the remaining networks and flag the gap clearly at the top of the report.

Step 4 — present the consolidated view

Output in this order:

1. Window: from YYYY-MM-DD to YYYY-MM-DD (and number of days).
2. Total across networks. If currencies differ, list per-currency totals — do not invent FX conversion.
3. By network: one row per network — total, by-status split, oldest-unpaid age days. Flag any network with oldestUnpaidAgeDays > 90 as ATTENTION.
4. Top programmes overall: union of each network's byProgramme[], sorted by total, top 10.
5. Failures (if any): per-network verbatim error from the envelope.

Keep the table compact. Matter-of-fact tone, UK spelling.

Stretch — anomaly detection

If the user asks for "this month vs last month", or hints at "is anything weird?", call affiliate_<s>_get_earnings_summary twice per network (current window and prior comparable window) and compare:

• A network that produced > £0 in the prior window and £0 in the current window — flag as a potential outage and recommend affiliate-networks-mcp doctor <slug>.
• A programme that contributed > 25% of a network's total in the prior window and 0% in the current window — flag as a potential programme drop.

Be precise. Do not call something an anomaly without quoting the prior and current figures.

Large accounts

On accounts where a pull runs to tens of thousands of rows, keep every tool result within the client's size limit:

• Prefer summaries: affiliate_<slug>_get_earnings_summary answers totals and status splits without pulling transaction rows.
• When raw rows are needed, pull month-sized windows rather than the whole period in one call, and page with offset (using limit as the page size) when a window is still too big.
• If a result returns truncated: true or result_too_large, follow its hint: continue from the given nextOffset or narrow the window or filters. Never total a truncated pull as if it were complete.

Constraints

• Never invent earnings figures. If the response is missing, say "no data" — don't fill in zeros.
• Currency: respect the per-network currency from the envelope. Don't normalise unless the user explicitly asks.
• Pair this with affiliate_<slug>_list_transactions when the user drills into "what makes up this number?".