feat(ledger): implement FeatureFilters for balance

Author: GAlexIHU

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -2415,6 +2415,7 @@ export const listCreditGrantsParamsFilter = z
 export const getCreditBalanceParamsFilter = z
   .object({
     currency: stringFieldFilterExact.optional(),
+    feature_key: stringFieldFilter.optional(),
   })
   .describe('Filter options for getting a credit balance.')
 

api/spec/packages/aip-client-javascript/src/models/types.ts

@@ -1259,6 +1259,21 @@ export interface ListCreditGrantsParamsFilter {
 export interface GetCreditBalanceParamsFilter {
   /** Filter credit balance by currency. */
   currency?: string | { eq?: string; oeq?: string[]; neq?: string }
+  /** Filter credit balance by feature key. Omit to return the total portfolio value. Use `exists=false` to return only unrestricted balance. */
+  feature_key?:
+    | string
+    | {
+        eq?: string
+        neq?: string
+        contains?: string
+        ocontains?: string[]
+        oeq?: string[]
+        gt?: string
+        gte?: string
+        lt?: string
+        lte?: string
+        exists?: boolean
+      }
 }
 
 /** Filter options for listing charges. */

api/spec/packages/aip/src/customers/credits/operations.tsp

@@ -151,6 +151,12 @@ model GetCreditBalanceParamsFilter {
    * Filter credit balance by currency.
    */
   currency?: Common.StringFieldFilterExact;
+
+  /**
+   * Filter credit balance by feature key. Omit to return the total portfolio value.
+   * Use `exists=false` to return only unrestricted balance.
+   */
+  feature_key?: Common.StringFieldFilter;
 }
 
 namespace Credits.Balance {

api/v3/api.gen.go

@@ -325,9 +325,17 @@ func parseFilterString(qs url.Values, field string) (FilterString, error) {
 			}
 			f.Ocontains = items
 		case OpExists:
-			f.Exists = lo.ToPtr(true)
+			exists, err := parseOptionalBool(field, OpExists, p.value)
+			if err != nil {
+				return err
+			}
+			f.Exists = &exists
 		case OpNexists:
-			f.Exists = lo.ToPtr(false)
+			nexists, err := parseOptionalBool(field, OpNexists, p.value)
+			if err != nil {
+				return err
+			}
+			f.Exists = lo.ToPtr(!nexists)
 		default:
 			return fieldError(field, p.op, ErrUnsupportedOperator)
 		}
@@ -337,6 +345,19 @@ func parseFilterString(qs url.Values, field string) (FilterString, error) {
 	return f, err
 }
 
+func parseOptionalBool(field, op, value string) (bool, error) {
+	if value == "" {
+		return true, nil
+	}
+
+	valueBool, err := strconv.ParseBool(value)
+	if err != nil {
+		return false, fieldError(field, op, fmt.Errorf("invalid boolean %q", value))
+	}
+
+	return valueBool, nil
+}
+
 // parseFilterStringExact extracts a FilterStringExact supporting eq, neq, and oeq.
 func parseFilterStringExact(qs url.Values, field string) (FilterStringExact, error) {
 	var f FilterStringExact

api/v3/filters/parse.go

@@ -113,19 +113,61 @@ func TestParse_FilterString(t *testing.T) {
 	})
 
 	t.Run("exists", func(t *testing.T) {
+		var f testFilter
+		require.NoError(t, Parse(url.Values{"filter[field][exists]": {"true"}}, &f))
+		require.NotNil(t, f.Field)
+		assert.Equal(t, lo.ToPtr(true), f.Field.Exists)
+	})
+
+	t.Run("exists false", func(t *testing.T) {
+		var f testFilter
+		require.NoError(t, Parse(url.Values{"filter[field][exists]": {"false"}}, &f))
+		require.NotNil(t, f.Field)
+		assert.Equal(t, lo.ToPtr(false), f.Field.Exists)
+	})
+
+	t.Run("exists without value", func(t *testing.T) {
 		var f testFilter
 		require.NoError(t, Parse(url.Values{"filter[field][exists]": {""}}, &f))
 		require.NotNil(t, f.Field)
 		assert.Equal(t, lo.ToPtr(true), f.Field.Exists)
 	})
 
+	t.Run("exists invalid boolean", func(t *testing.T) {
+		var f testFilter
+		err := Parse(url.Values{"filter[field][exists]": {"anything"}}, &f)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), `invalid boolean "anything"`)
+	})
+
 	t.Run("nexists", func(t *testing.T) {
+		var f testFilter
+		require.NoError(t, Parse(url.Values{"filter[field][nexists]": {"true"}}, &f))
+		require.NotNil(t, f.Field)
+		assert.Equal(t, lo.ToPtr(false), f.Field.Exists)
+	})
+
+	t.Run("nexists false", func(t *testing.T) {
+		var f testFilter
+		require.NoError(t, Parse(url.Values{"filter[field][nexists]": {"false"}}, &f))
+		require.NotNil(t, f.Field)
+		assert.Equal(t, lo.ToPtr(true), f.Field.Exists)
+	})
+
+	t.Run("nexists without value", func(t *testing.T) {
 		var f testFilter
 		require.NoError(t, Parse(url.Values{"filter[field][nexists]": {""}}, &f))
 		require.NotNil(t, f.Field)
 		assert.Equal(t, lo.ToPtr(false), f.Field.Exists)
 	})
 
+	t.Run("nexists invalid boolean", func(t *testing.T) {
+		var f testFilter
+		err := Parse(url.Values{"filter[field][nexists]": {"anything"}}, &f)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), `invalid boolean "anything"`)
+	})
+
 	t.Run("bare key existence", func(t *testing.T) {
 		var f testFilter
 		require.NoError(t, Parse(url.Values{"filter[field]": {""}}, &f))

api/v3/filters/parse_test.go

@@ -6,8 +6,11 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/samber/mo"
+
 	api "github.com/openmeterio/openmeter/api/v3"
 	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/billing/charges/creditpurchase"
 	"github.com/openmeterio/openmeter/openmeter/customer"
 	"github.com/openmeterio/openmeter/openmeter/ledger/customerbalance"
 	"github.com/openmeterio/openmeter/pkg/clock"
@@ -18,9 +21,10 @@ import (
 
 type (
 	GetCustomerCreditBalanceRequest struct {
-		CustomerID customer.CustomerID
-		Currencies customerbalance.CurrencyFilter
-		AsOf       time.Time
+		CustomerID    customer.CustomerID
+		Currencies    customerbalance.CurrencyFilter
+		FeatureFilter mo.Option[creditpurchase.FeatureFilters]
+		AsOf          time.Time
 	}
 	GetCustomerCreditBalanceResponse = api.BillingCreditBalances
 	GetCustomerCreditBalanceParams   struct {
@@ -76,6 +80,15 @@ func (h *handler) GetCustomerCreditBalance() GetCustomerCreditBalanceHandler {
 				}
 			}
 
+			if args.Params.Filter != nil {
+				featureFilter, err := fromAPICreditBalanceFeatureFilter(args.Params.Filter.FeatureKey)
+				if err != nil {
+					return GetCustomerCreditBalanceRequest{}, newFeatureKeyFilterBadRequest(ctx, err)
+				}
+
+				request.FeatureFilter = featureFilter
+			}
+
 			return request, nil
 		},
 		func(ctx context.Context, request GetCustomerCreditBalanceRequest) (GetCustomerCreditBalanceResponse, error) {
@@ -87,9 +100,10 @@ func (h *handler) GetCustomerCreditBalance() GetCustomerCreditBalanceHandler {
 			}
 
 			balancesByCurrency, err := h.balanceFacade.GetBalances(ctx, customerbalance.GetBalancesInput{
-				CustomerID: request.CustomerID,
-				Currencies: request.Currencies,
-				AsOf:       &request.AsOf,
+				CustomerID:    request.CustomerID,
+				Currencies:    request.Currencies,
+				FeatureFilter: request.FeatureFilter,
+				AsOf:          &request.AsOf,
 			})
 			if err != nil {
 				return GetCustomerCreditBalanceResponse{}, err

api/v3/handlers/customers/credits/get_balance.go

@@ -0,0 +1,82 @@
+package customerscredits
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/samber/mo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/billing/charges/creditpurchase"
+	"github.com/openmeterio/openmeter/openmeter/ledger/customerbalance"
+)
+
+func fromAPICreditBalanceFeatureFilter(f *api.StringFieldFilter) (mo.Option[creditpurchase.FeatureFilters], error) {
+	if f == nil {
+		return customerbalance.AllFeatureFilter(), nil
+	}
+
+	if f.Exists != nil {
+		if !*f.Exists {
+			return customerbalance.NewUnrestrictedFeatureFilter(), nil
+		}
+
+		return customerbalance.AllFeatureFilter(), errors.New("exists=true operator is not supported")
+	}
+
+	if op := unsupportedCreditBalanceFeatureKeyOperator(f); op != "" {
+		return customerbalance.AllFeatureFilter(), fmt.Errorf("%s operator is not supported", op)
+	}
+
+	features := make([]string, 0, 1+len(f.Oeq))
+	if f.Eq != nil {
+		features = append(features, *f.Eq)
+	}
+	features = append(features, f.Oeq...)
+
+	if len(features) == 0 {
+		return customerbalance.AllFeatureFilter(), nil
+	}
+
+	featureFilter := customerbalance.NewFeatureFilter(features)
+	if err := customerbalance.ValidateFeatureFilter(featureFilter); err != nil {
+		return customerbalance.AllFeatureFilter(), err
+	}
+
+	return featureFilter, nil
+}
+
+func unsupportedCreditBalanceFeatureKeyOperator(f *api.StringFieldFilter) string {
+	switch {
+	case f.Neq != nil:
+		return "neq"
+	case f.Contains != nil:
+		return "contains"
+	case len(f.Ocontains) > 0:
+		return "ocontains"
+	case f.Gt != nil:
+		return "gt"
+	case f.Gte != nil:
+		return "gte"
+	case f.Lt != nil:
+		return "lt"
+	case f.Lte != nil:
+		return "lte"
+	default:
+		return ""
+	}
+}
+
+func newFeatureKeyFilterBadRequest(ctx context.Context, err error) error {
+	return apierrors.NewBadRequestError(
+		ctx,
+		errors.New("invalid feature_key filter"),
+		apierrors.InvalidParameters{{
+			Field:  "filter[feature_key]",
+			Reason: err.Error(),
+			Source: apierrors.InvalidParamSourceQuery,
+		}},
+	)
+}

api/v3/handlers/customers/credits/get_balance_filter.go

@@ -0,0 +1,75 @@
+package customerscredits
+
+import (
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/samber/mo"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/openmeter/billing/charges/creditpurchase"
+	"github.com/openmeterio/openmeter/openmeter/ledger/customerbalance"
+)
+
+func TestParseCreditBalanceFeatureFilter(t *testing.T) {
+	tests := []struct {
+		name    string
+		filter  *api.StringFieldFilter
+		want    mo.Option[creditpurchase.FeatureFilters]
+		wantErr bool
+	}{
+		{
+			name: "omitted filter returns all",
+			want: customerbalance.AllFeatureFilter(),
+		},
+		{
+			name:   "eq returns feature filter",
+			filter: &api.StringFieldFilter{Eq: lo.ToPtr("feature-a")},
+			want:   customerbalance.NewFeatureFilter([]string{"feature-a"}),
+		},
+		{
+			name:   "single oeq returns feature filter",
+			filter: &api.StringFieldFilter{Oeq: []string{"feature-a"}},
+			want:   customerbalance.NewFeatureFilter([]string{"feature-a"}),
+		},
+		{
+			name:    "multiple features are rejected",
+			filter:  &api.StringFieldFilter{Oeq: []string{"feature-a", "feature-b"}},
+			wantErr: true,
+		},
+		{
+			name:   "exists false returns unrestricted",
+			filter: &api.StringFieldFilter{Exists: lo.ToPtr(false)},
+			want:   customerbalance.NewUnrestrictedFeatureFilter(),
+		},
+		{
+			name:    "exists true is rejected",
+			filter:  &api.StringFieldFilter{Exists: lo.ToPtr(true)},
+			wantErr: true,
+		},
+		{
+			name:    "contains is rejected",
+			filter:  &api.StringFieldFilter{Contains: lo.ToPtr("feature")},
+			wantErr: true,
+		},
+		{
+			name:    "empty feature is rejected",
+			filter:  &api.StringFieldFilter{Eq: lo.ToPtr("")},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := fromAPICreditBalanceFeatureFilter(tt.filter)
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}

api/v3/handlers/customers/credits/get_balance_test.go

@@ -8186,6 +8186,12 @@ components:
           allOf:
             - $ref: '#/components/schemas/StringFieldFilterExact'
           description: Filter credit balance by currency.
+        feature_key:
+          allOf:
+            - $ref: '#/components/schemas/StringFieldFilter'
+          description: |-
+            Filter credit balance by feature key. Omit to return the total portfolio
+            value. Use `exists=false` to return only unrestricted balance.
       additionalProperties: false
       description: Filter options for getting a credit balance.
     GovernanceFeatureAccess: