Add payer metadata endpoint (#1013)

### TL;DR

Added a new API endpoint to retrieve payer usage information, including spend and message counts, with hourly or daily granularity.

## Requires
- xmtp/proto#287

### What changed?

- Added a new `GetPayerInfo` endpoint to the Metadata API service that allows querying payer usage data
- Created a `PayerInfoFetcher` to retrieve payer information from the database
- Added message count tracking to the `unsettled_usage` table via a new migration
- Modified the protocol buffer definitions to support the new API endpoint
- Updated the `dev/gen/protos` script to support configurable branch selection via `GEN_PROTO_BRANCH` environment variable

### How to test?

1. Run the database migrations to add the message count column
2. Use the new API endpoint with a payer address:
   ```
   curl -X POST http://localhost:8080/mls/v2/metadata/get-payer-info \
     -H "Content-Type: application/json" \
     -d '{"payer_addresses": ["0x..."], "granularity": "PAYER_INFO_GRANULARITY_DAY"}'
   ```
3. Run the comprehensive test suite in `payer_info_test.go` which covers various scenarios including:
   - Different time granularities (hourly/daily)
   - Time range filtering
   - Multiple originators
   - Edge cases and boundary conditions

### Why make this change?

This change enables monitoring and reporting of payer usage metrics, allowing both the service operator and payers themselves to track message volume and spending over time. The granular data can be used for billing, analytics, and capacity planning purposes.

Author: neekolas

dev/gen/protos

@@ -5,8 +5,10 @@ script_dir=$(dirname "$(realpath "$0")")
 repo_root=$(realpath "${script_dir}/../../")
 cd "${repo_root}"
 
+GEN_PROTO_BRANCH="${GEN_PROTO_BRANCH:-main}"
+
 rm -rf pkg/proto/**/*.pb.go pkg/proto/**/*.pb.gw.go pkg/proto/**/*.swagger.json
-if ! go tool -modfile=tools/go.mod buf generate https://github.com/xmtp/proto.git#subdir=proto,branch=main; then
+if ! go tool -modfile=tools/go.mod buf generate "https://github.com/xmtp/proto.git#subdir=proto,branch=${GEN_PROTO_BRANCH}"; then
     echo "Failed to generate protobuf definitions"
     exit 1
 fi

pkg/api/metadata/payer_info.go

@@ -0,0 +1,71 @@
+package metadata
+
+import (
+	"context"
+	"database/sql"
+
+	"github.com/xmtp/xmtpd/pkg/db/queries"
+	"github.com/xmtp/xmtpd/pkg/proto/xmtpv4/metadata_api"
+)
+
+type PayerInfoGroupBy string
+
+const (
+	PayerInfoGroupByHour PayerInfoGroupBy = "hour"
+	PayerInfoGroupByDay  PayerInfoGroupBy = "day"
+)
+
+type IPayerInfoFetcher interface {
+	GetPayerByAddress(ctx context.Context, address string) (int32, error)
+	GetPayerInfo(
+		ctx context.Context,
+		payerID int32,
+		groupBy PayerInfoGroupBy,
+	) (*metadata_api.GetPayerInfoResponse_PayerInfo, error)
+}
+
+type PayerInfoFetcher struct {
+	queries *queries.Queries
+}
+
+func NewPayerInfoFetcher(db *sql.DB) *PayerInfoFetcher {
+	return &PayerInfoFetcher{
+		queries: queries.New(db),
+	}
+}
+
+// Gets the total spend and message count for a payer between the two timestamps, grouped by the appropriate granularity.
+func (f *PayerInfoFetcher) GetPayerInfo(
+	ctx context.Context,
+	payerID int32,
+	groupBy PayerInfoGroupBy,
+) (*metadata_api.GetPayerInfoResponse_PayerInfo, error) {
+	result, err := f.queries.GetPayerInfoReport(ctx, queries.GetPayerInfoReportParams{
+		GroupBy: string(groupBy),
+		PayerID: payerID,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	payerInfo := &metadata_api.GetPayerInfoResponse_PayerInfo{
+		PeriodSummaries: make([]*metadata_api.GetPayerInfoResponse_PeriodSummary, 0),
+	}
+
+	for _, row := range result {
+		periodSummary := &metadata_api.GetPayerInfoResponse_PeriodSummary{
+			AmountSpentPicodollars: uint64(row.TotalSpendPicodollars),
+			NumMessages:            uint64(row.TotalMessageCount),
+			PeriodStartUnixSeconds: uint64(row.TimePeriod),
+		}
+
+		payerInfo.PeriodSummaries = append(payerInfo.PeriodSummaries, periodSummary)
+	}
+
+	return payerInfo, nil
+}
+
+// GetPayerByAddress looks up a payer ID by address
+func (f *PayerInfoFetcher) GetPayerByAddress(ctx context.Context, address string) (int32, error) {
+	return f.queries.GetPayerByAddress(ctx, address)
+}