# KPI Digest Publish

Assemble a KPI (key performance indicator) digest from API metrics and email it to stakeholders on a recurring or ad hoc basis.

## When to use

- A stakeholder or schedule requests a periodic marketing/analytics KPI summary.
- Metrics need to be pulled from one or more analytics or SaaS (software-as-a-service) APIs and consolidated into a single report.
- A digest needs to be computed, formatted, and delivered by email without manual copy-paste.

## Tools

- `http-get` — read metrics from analytics/reporting APIs (e.g. GA4 (Google Analytics 4), CRM (customer relationship management) dashboards, ad platforms).
- `shell-execute` — run a small script to merge, dedupe, and compute metric math (rates, deltas, totals) across pulled datasets.
- `write-file` — save the assembled digest (Markdown or HTML (HyperText Markup Language)) as an artifact before sending.
- `send-email` — deliver the finished digest to stakeholder recipients.

## Playbook

1. Confirm the KPI list, date range, and recipient list for the digest before pulling any data.
2. For each metrics source, call the REST (representational state transfer) API with `http-get` (e.g. GET https://api.example.com/v1/metrics). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
3. If multiple pulls are needed, repeat step 2 for each source's `http-get` calls until all raw metric data is collected.
4. Use `shell-execute` to merge the pulled JSON/CSV (comma-separated values) responses, dedupe overlapping rows, and compute derived metrics (week-over-week change, conversion rate, totals).
5. Format the computed results into a readable digest body (headline numbers, brief trend notes, a short table).
6. Save the digest with `write-file` so there is a durable artifact of what was sent.
7. Send the digest to stakeholders with `send-email`, using a clear subject line that names the reporting period.
8. If any source's data appears incomplete or clearly wrong, note the gap in the digest rather than silently omitting it.
9. If a stakeholder later requests a correction to source data (not the digest itself) that would require modifying records in the SaaS system, that needs PATCH/PUT/DELETE, which is not possible — hand off to a human via send-message instead of implying the correction was made.

## Failure modes

- 401/403 on any metrics API -> missing Integration; stop and escalate via send-message naming the service and scopes.
- Empty or zero-value result from a source -> verify the endpoint and query parameters before assuming the metric is truly zero.
- Rate limit (429) from a metrics API -> back off and retry later; note the limit in memory via update-memory so future runs pace requests.
- Source page/API structure has changed and normal calls fail -> fall back to browser-search to confirm the current endpoint or reporting UI.

## Done when

- The KPI digest file exists on disk via `write-file` with computed metrics for the requested period.
- `send-email` confirms delivery to the full stakeholder recipient list.
- Any data gaps or anomalies are explicitly noted in the digest rather than silently dropped.