Reuse a shared usageStore scan helper to collapse the seven near-identical rollup loops

[mikewheeleer]

Refactor the repeated usageStore iteration into shared prefix/suffix scan helpers

Description

At least seven handlers in src/index.ts hand-roll a for (const [key, ...] of usageStore.entries()) loop with bespoke startsWith/endsWith/split("::") parsing: /agents, /agents/:agent/total, /agents/:agent/usage, /services/:serviceId/usage, /services/:serviceId/agents, /services/:serviceId/agents/top, plus /billing/total, /stats, /metrics, and the CSV/JSON exporters. Each re-implements the ${agent}::${serviceId} key split slightly differently (some split, some slice), which is brittle and the root of subtle bugs (e.g. an agent id containing ::). This issue centralizes key parsing and scanning behind small helpers, distinct from the indexing/performance work tracked elsewhere.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add parseUsageKey(key): { agent, serviceId } and scanByAgent(agent) / scanByService(serviceId) helpers, and route the rollup/export/stats handlers through them.
• Keep response shapes and values identical (pure refactor); the goal is one correct key-parsing implementation, not new behaviour or new indexes.
• Use the helpers consistently so a future change to the key scheme touches one place.
• Ensure parsing is robust to the agreed identifier rules (coordinate with the identifier-sanitization direction) without changing current outputs for valid ids.

Suggested execution

• Fork the repo and create a branch
• git checkout -b refactor/usage-77-scan-helpers
• Implement changes
  • Write code in: the rollup/export/stats/metrics handlers and new helpers in src/index.ts.
  • Write comprehensive tests in: new src/usage-scan-helpers.test.ts — helper parsing correctness, parity of each refactored endpoint with prior output.
  • Add documentation: note the key-parsing helper in code comments.
  • Add TSDoc on each helper.
  • Validate security assumptions: consistent key parsing removes the ::-in-id ambiguity surface.
• Test and commit

Test and commit

• Run npm test and npm run lint.
• Cover edge cases: agent with many services, service with many agents, empty store, exports.
• Include the full npm test output in the PR description.

Example commit message

refactor: centralize usageStore key parsing and rollup scans

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.