Customer engagement reports

Overview

The internal Reports area brings together two different kinds of evidence:

• Engagement and Recorded activity use a completed customer-engagement capture. They describe recorded product activity for external customer organizations.
• Revenue keeps the existing finance report, based on billing and metric engine facts.

Use the view links under Reports in the admin sidebar to move between them. The reports share an entry point, but engagement captures and financial daily snapshots keep separate definitions and storage. Engagement captures are derived JSON files in Fondaro's existing private object storage; they do not add reporting tables. The service retains the latest five completed captures.

Choose a capture and period

Engagement reporting pins every chart, customer row, detail view, and export to one successful capture. The observation time shown in the toolbar tells you when that capture was completed. Its coverage notes explain which sources and dates can support the figures.

The default period is the last 30 complete UTC days. Changing the date range changes the product-activity period inside the selected capture. Dates use UTC and the end date is exclusive, so a range ending 15 September includes activity up to the start of that date.

If a required product source could not be captured, the engagement report is unavailable rather than showing an incomplete total. Optional Clerk access data can be unavailable while the recorded product report remains usable.

Read the engagement view

The summary shows weekly active organizations, monthly active organizations, attributable active members, and median active days. An organization is active only when the capture contains an allowlisted, human-initiated product action. Automated and integration activity is reported separately and does not make a person or organization active.

The weekly chart counts distinct active organizations. The feature chart shows organization counts. Historical coverage has not been verified, so this version does not show adoption percentages or previous-period comparisons.

The customer ledger shows each organization's active members and days, latest recorded product activity, features used, and weekly activity. Open a row for the contributing feature, member, and coverage detail, or follow the organization link to the existing admin console. An empty or unknown value is not a customer health score.

Product activity and Clerk access

Product activity comes from Fondaro records inside the capture's historical period. Counts are deduplicated so one logical action is counted once. Unknown actors stay unknown, bulk imports do not become thousands of human actions, and recorded automation stays outside human engagement.

Clerk recent access is a current recency snapshot observed when the capture was made. It can show that a member recently accessed Fondaro, but it cannot reconstruct historical daily, weekly, or monthly activity, time spent, or organization-switch history. It therefore appears with its own observation time in member detail and does not change when you change the historical product period. A Clerk lookup failure never means that a customer was inactive.

Retention and recorded coverage

The weekly activity chart shows distinct active organizations across the selected period. Hover a bar to see the UTC week and recorded count.

Activity after signup groups organizations by their signup week. Choose a Signup week to see that group's activity over time. Weeks begin on Monday at 00:00 UTC: W0 is the signup calendar week, and later labels show the number of weeks since signup. Older groups show the weeks that overlap your selected period. Hover a point to see its calendar date and active-organization count.

Only fully elapsed weeks inside the selected coverage show recorded counts. A measured quiet week plots as zero; unavailable and unfinished weeks remain gaps. A customer may be inactive in one week and return in a later week; each week stands on its own. Complete historical coverage has not been established, so these charts show recorded counts rather than retention percentages.

Search, filters, and customer status

Use organization search to narrow the captured report population. This version does not include a plan filter. Signed-up and paying organizations are separate concepts: the customer date uses the local organization record, while payment status and revenue require finance-backed evidence. Churned customers remain in historical populations when their records survive, so current subscription status does not rewrite an earlier denominator.

Export and print

Export CSV and Print use the same capture, date range, filters, metric definitions, and complete server-filtered population as the screen. They are not limited to the currently visible table page. The output includes the UTC period, capture and definition identifiers, observation time, exclusions, and coverage notes. Printing uses the fixed-white report treatment.

Use the Revenue view for financial reporting and Daily snapshots for financial metric-engine captures. Those snapshots do not contain customer engagement history, and engagement captures do not replace them.

Capture and API operations

Choose your UTC date range and click Generate report to create or refresh the report from existing records. Generation can take a few minutes; the action shows progress and reports failures. No tracking setup or database migration is needed. If a capture is missing, the page offers generation instead of leaving charts loading. Failed reads and exports offer a retry.

Operators can also audit source coverage with the CLI, then capture the same UTC bounds:

pnpm --filter @fondaro/api cli customer-analytics:capture --from=2026-08-01 --to=2026-09-15 --dry-run
pnpm --filter @fondaro/api cli customer-analytics:capture --from=2026-08-01 --to=2026-09-15

The equivalent authenticated admin action is:

curl --request POST "https://api.fondaro.com/admin/reports/engagement/capture" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"from":"2026-08-16","to":"2026-09-15"}'

This request returns only after a complete capture is published. A concurrent capture in the same API process returns ENGAGEMENT_CAPTURE_IN_PROGRESS (409). Ordinary report reads never scan the source databases or fan out to Clerk.

Internal-admin API clients should pin the successful capture ID and explicit date bounds so related reads cannot switch generations:

curl --get "https://api.fondaro.com/admin/reports/engagement/summary" \
  --header "Authorization: Bearer $TOKEN" \
  --data-urlencode "captureId=00000000-0000-4000-8000-000000000000" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "to=2026-09-15"