From 003fbc9570c4df6eb5ea641041bf4557fd35ecfa Mon Sep 17 00:00:00 2001
From: topphh <email.cristopher@gmail.com>
Date: Tue, 15 Sep 2026 13:06:36 +0800
Subject: [PATCH] feat(billing): add ListTagValues RPC and Tags cardinality
 fields

Adds Tags.totalValueCount/truncated and a paginated ListTagValues RPC
(following ListBillingGroupsPaginated's offset-pagination convention) so
GetTags callers can cap per-key value lists and drill into a high-
cardinality key on demand.

Part of the tags-improvement Spanner migration (ripple-openspec
optimize-tags-customer-index, task 4.1).
---
 billing/v1/billing.proto | 46 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/billing/v1/billing.proto b/billing/v1/billing.proto
index 0408f64b..e51b697f 100644
--- a/billing/v1/billing.proto
+++ b/billing/v1/billing.proto
@@ -698,7 +698,7 @@ service Billing {
     };
   }
 
-  // Returns the customer details and its tags. 
+  // Returns the customer details and its tags.
   // Port for: m/ripple/tags/vendor/{vendor}?type={type}
   rpc GetTags(GetTagsRequest) returns (stream TagData) {
     option (google.api.http) = {
@@ -706,6 +706,14 @@ service Billing {
     };
   }
 
+  // Returns one page of the distinct values for a single customer's tag key, for
+  // drilling down into a key beyond GetTags' per-key cap (see Tags.truncated).
+  rpc ListTagValues(ListTagValuesRequest) returns (ListTagValuesResponse) {
+    option (google.api.http) = {
+      get: "/v1/tags:values"
+    };
+  }
+
   // Creates new customfield
   rpc CreateCustomField(CreateCustomFieldRequest) returns (CustomField) {
     option (google.api.http) = {
@@ -2806,6 +2814,15 @@ message TagData {
 message Tags {
   string key = 1;
   repeated string values = 2;
+
+  // Total number of distinct values recorded for this key, regardless of how
+  // many are present in `values` above.
+  int32 totalValueCount = 3;
+
+  // True if `values` does not contain all of this key's distinct values (its
+  // count exceeds the server-side per-key cap). Use ListTagValues to page
+  // through the full list.
+  bool truncated = 4;
 }
 
 message GetTagsRequest {
@@ -2813,6 +2830,33 @@ message GetTagsRequest {
   string type = 2;
 }
 
+// Request message for the Billing.ListTagValues rpc.
+message ListTagValuesRequest {
+  string vendor = 1;
+  string customerId = 2;
+  string tagKey = 3;
+
+  // Optional. Page number for pagination. Starts from 1. Default is 1.
+  int32 pageNumber = 4;
+
+  // Optional. Page size for pagination. Default is 50, maximum is 1000.
+  int32 pageSize = 5;
+}
+
+// Response message for the Billing.ListTagValues rpc.
+message ListTagValuesResponse {
+  // This page's distinct values.
+  repeated string values = 1;
+
+  // Total distinct-value count for this (customerId, tagKey), consistent
+  // with Tags.totalValueCount.
+  int32 totalValueCount = 2;
+
+  int32 pageNumber = 3;
+  int32 pageSize = 4;
+  int32 totalPages = 5;
+}
+
 message CustomField {
   // Unique identifier for the custom field, automatically generated and immutable.
   string id = 1;