earnings-rollup

---
name: earnings-rollup
description: |
  Use this skill when a publisher wants a multi-period earnings trend across their configured networks, how concentrated their earnings are in one or two programmes, and how long money typically takes to move from converted to approved to paid so they can forecast the next payout. This is the premium extension of the free `affiliate-earnings-report` skill, not a replacement for it.
  Trigger on: "Show my earnings trend over the last six months", "How concentrated is my income in one programme?", "How long does [network] usually take to pay me?", "Forecast when my pending commissions will land".
---

# Premium scope note

The free `affiliate-earnings-report` skill already produces the single-period
consolidated view: total earnings, by-network and by-programme breakdown, the
status split, and an unpaid-age flag. Run that skill first for a single
period's numbers; this premium skill does not repeat it.

This premium skill adds three things the free report does not do:

1. **Multi-period trend** (typically the last six months), so the user sees
   the earnings shape over time rather than one window.
2. **Concentration/diversification analysis**: what share of total earnings
   comes from the top one, three, and five programmes, with a plain
   diversification-risk flag when concentration is high.
3. **Payment-timing analysis**: per network, the typical time from
   `dateConverted` to `dateApproved` and from `dateApproved` to `datePaid`,
   computed from the transaction rows, used to give a rough forecast for
   when currently-pending or currently-approved commission is likely to be
   paid. This is a pattern observed in past data, not a promise from the
   network.

## Assumptions and requirements

- Publisher-side networks only.
- Credentials for networks in scope are configured; recommend
  `affiliate-networks-mcp doctor <slug>` when credential state is uncertain.
- Payment-timing analysis needs enough paid history to be meaningful (a
  handful of paid transactions per network at minimum). Where a network has
  too little paid history, state that rather than forecasting from one or
  two data points.
- This skill never invents a payment date. A forecast is stated as a range
  derived from past typical timing, not a guarantee.

## Step 1 — identify networks

Use publisher networks the user named or confirmed configured. Call
`affiliate_list_networks` only to confirm a registered adapter exists per
named network. Recommend `affiliate-networks-mcp doctor <slug>` when
credential state is uncertain rather than assuming.

## Step 2 — pull the multi-period trend

For each network `s`, call the earnings summary once per of the last six
complete months:

```
affiliate_<s>_get_earnings_summary({ from: <month-start>, to: <month-end> })
```

for example `affiliate_awin_get_earnings_summary({ from, to })` or
`affiliate_cj_get_earnings_summary({ from, to })`. Record `totalEarnings` per
network per month per currency. If a call fails for a given month, say so
for that month and continue; do not treat it as zero.

## Step 3 — concentration analysis

For the most recent complete month (or the period the user asked about),
use each network's `byProgramme[]` from Step 2's summary calls. Rank
programmes by `total` across all networks (per currency; do not blend
currencies). Compute the share of total earnings held by the top 1, top 3,
and top 5 programmes.

Flag as a diversification risk when the top programme alone exceeds roughly
40% of total earnings, or the top 3 exceed roughly 70%, in that currency's
total. State the actual percentages; never just say "concentrated" without
the number.

## Step 4 — payment-timing analysis

For each network, call:

```
affiliate_<s>_list_transactions({ status: "paid", from: <iso>, to: <iso> })
```

for example `affiliate_cj_list_transactions({ status: "paid", from, to })`,
over a window wide enough to gather a reasonable sample of paid
transactions (six to twelve months back is usually enough). For each row
with both `dateApproved` and `datePaid`, compute days from approval to
payment. For rows also carrying `dateConverted`, compute days from
conversion to approval. Report the median and the range (not just an
average, which one outlier can distort) per network.

If a network has fewer than roughly five paid transactions with the needed
dates in the window, state that the sample is too small for a reliable
figure rather than reporting a median from one or two rows.

Using the median approval-to-payment time, give a rough forecast window for
currently-approved-but-unpaid commission: "typically paid within N to M days
of approval; the GBP X approved on [date] would be expected to land by
roughly [date range]". Label this explicitly as a pattern from past data,
not a commitment from the network.

## Step 5 — present the report

Output in this order:

1. **Trend**: compact table, one row per network, one column per month,
   `totalEarnings` per currency, plus a one-line description of the shape
   (growing, flat, seasonal, declining).
2. **Concentration**: top 1/3/5 programme shares with actual percentages and
   the diversification-risk flag where it applies.
3. **Payment timing**: per network, median and range for
   conversion-to-approval and approval-to-payment, sample size, and the
   forecast window for currently pending/approved amounts.
4. **Failures/gaps (if any)**: per-network verbatim error or "sample too
   small" notes.

Matter-of-fact tone, UK spelling. Keep tables compact.

## Large accounts

Follow the free skill's large-account guidance: prefer
`get_earnings_summary` over raw transaction pulls where the question is a
total or a split, and page month-by-month with `offset` when a raw pull is
needed and a single window is too large. Respect `truncated: true` or
`result_too_large` by following the hint rather than treating a partial pull
as complete.

## Constraints

- Never invent a figure, a month's total, or a payment date. A gap or a too-
  small sample is stated, not filled or forecast anyway.
- Currency: respect each network's currency; never blend currencies in a
  trend, concentration ranking, or payment-timing figure.
- A payment-timing forecast is explicitly a pattern from past data, phrased
  as a range, never presented as a network commitment or a guarantee.
- This is a read-only report. Pair with the free `chase-unpaid-commissions`
  or premium `unpaid-commission-chaser` skill when the user wants to act on
  what is overdue.