feat(api): add v3 customer and subscription list filters (#4336)

Author: tothandras

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

@@ -19,20 +19,18 @@ namespace Customers;
  */
 @friendlyName("ListCustomersParamsFilter")
 model ListCustomersParamsFilter {
-  /**
-   * Filter customers by key.
-   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
   key?: Common.StringFieldFilter;
-
-  /**
-   * Filter customers by name.
-   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
   name?: Common.StringFieldFilter;
-
-  /**
-   * Filter customers by primary email.
-   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
   primary_email?: Common.StringFieldFilter;
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  usage_attribution_subject_key?: Common.StringFieldFilter;
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  plan_key?: Common.StringFieldFilter;
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  billing_profile_id?: Common.ULIDFieldFilter;
 }
 
 interface CustomersOperations {

api/spec/packages/aip/src/subscriptions/operations.tsp

@@ -53,6 +53,17 @@ model SubscriptionChangeResponse {
   next: Subscription;
 }
 
+/**
+ * Filter options for listing subscriptions.
+ */
+@friendlyName("ListSubscriptionsParamsFilter")
+model ListSubscriptionsParamsFilter {
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  customer_id?: Common.ULIDFieldFilter;
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  plan_key?: Common.StringFieldFilter;
+}
+
 interface SubscriptionsOperations {
   @post
   @operationId("create-subscription")
@@ -73,12 +84,7 @@ interface SubscriptionsOperations {
      * Filter subscriptions.
      */
     @query(#{ style: "deepObject", explode: true })
-    filter?: {
-      /**
-       * Filter subscriptions by customer ID.
-       */
-      customer_id?: Shared.ULID;
-    },
+    filter?: ListSubscriptionsParamsFilter,
   ): Shared.PagePaginatedResponse<Subscription> | Common.NotFound | Common.ErrorResponses;
 
   @get

api/v3/api.gen.go

@@ -98,6 +98,27 @@ func (h *handler) ListCustomers() ListCustomersHandler {
 					})
 				}
 				req.PrimaryEmail = primaryEmail
+				usageAttributionSubjectKey, err := filters.FromAPIFilterString(params.Filter.UsageAttributionSubjectKey)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[usage_attribution_subject_key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.UsageAttributionSubjectKey = usageAttributionSubjectKey
+				planKey, err := filters.FromAPIFilterString(params.Filter.PlanKey)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[plan_key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.PlanKey = planKey
+				billingProfileID, err := filters.FromAPIFilterULID(params.Filter.BillingProfileId)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[billing_profile_id]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.BillingProfileID = billingProfileID
 			}
 
 			return req, nil

api/v3/handlers/customers/list.go

@@ -8,6 +8,7 @@ import (
 
 	api "github.com/openmeterio/openmeter/api/v3"
 	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
 	"github.com/openmeterio/openmeter/api/v3/response"
 	"github.com/openmeterio/openmeter/openmeter/subscription"
 	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
@@ -58,11 +59,20 @@ func (h *handler) ListSubscriptions() ListSubscriptionsHandler {
 
 			// Filters
 			if params.Filter != nil {
-				// Filter by customer ID
-				if params.Filter.CustomerId != nil {
-					// Add the customer ID filter to the request
-					req.CustomerIDs = []string{*params.Filter.CustomerId}
+				customerID, err := filters.FromAPIFilterULID(params.Filter.CustomerId)
+				if err != nil {
+					return ListSubscriptionsRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[customer_id]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
 				}
+				req.CustomerID = customerID
+				planKey, err := filters.FromAPIFilterString(params.Filter.PlanKey)
+				if err != nil {
+					return ListSubscriptionsRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[plan_key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.PlanKey = planKey
 			}
 
 			return req, nil

api/v3/handlers/subscriptions/list.go

@@ -2488,13 +2488,7 @@ paths:
           required: false
           description: Filter subscriptions.
           schema:
-            type: object
-            properties:
-              customer_id:
-                allOf:
-                  - $ref: '#/components/schemas/ULID'
-                description: Filter subscriptions by customer ID.
-            additionalProperties: false
+            $ref: '#/components/schemas/ListSubscriptionsParamsFilter'
           style: deepObject
       responses:
         '200':
@@ -7833,17 +7827,17 @@ components:
       type: object
       properties:
         key:
-          allOf:
-            - $ref: '#/components/schemas/StringFieldFilter'
-          description: Filter customers by key.
+          $ref: '#/components/schemas/StringFieldFilter'
         name:
-          allOf:
-            - $ref: '#/components/schemas/StringFieldFilter'
-          description: Filter customers by name.
+          $ref: '#/components/schemas/StringFieldFilter'
         primary_email:
-          allOf:
-            - $ref: '#/components/schemas/StringFieldFilter'
-          description: Filter customers by primary email.
+          $ref: '#/components/schemas/StringFieldFilter'
+        usage_attribution_subject_key:
+          $ref: '#/components/schemas/StringFieldFilter'
+        plan_key:
+          $ref: '#/components/schemas/StringFieldFilter'
+        billing_profile_id:
+          $ref: '#/components/schemas/ULIDFieldFilter'
       additionalProperties: false
       description: Filter options for listing customers.
     ListEventsParamsFilter:
@@ -7945,6 +7939,15 @@ components:
           $ref: '#/components/schemas/StringFieldFilterExact'
       additionalProperties: false
       description: Filter options for listing plans.
+    ListSubscriptionsParamsFilter:
+      type: object
+      properties:
+        customer_id:
+          $ref: '#/components/schemas/ULIDFieldFilter'
+        plan_key:
+          $ref: '#/components/schemas/StringFieldFilter'
+      additionalProperties: false
+      description: Filter options for listing subscriptions.
     Meter:
       type: object
       required:

api/v3/openapi.yaml

@@ -10,6 +10,7 @@ import (
 	"github.com/openmeterio/openmeter/openmeter/billing/worker/subscriptionsync"
 	"github.com/openmeterio/openmeter/openmeter/customer"
 	"github.com/openmeterio/openmeter/openmeter/subscription"
+	"github.com/openmeterio/openmeter/pkg/filter"
 )
 
 var _ customer.RequestValidator = (*Validator)(nil)
@@ -46,8 +47,8 @@ func (v *Validator) ValidateDeleteCustomer(ctx context.Context, input customer.D
 
 	// Let's sync any subscriptions pending for this customer
 	subs, err := v.subscriptionService.List(ctx, subscription.ListSubscriptionsInput{
-		Namespaces:  []string{input.Namespace},
-		CustomerIDs: []string{input.ID},
+		Namespaces: []string{input.Namespace},
+		CustomerID: &filter.FilterULID{FilterString: filter.FilterString{Eq: &input.ID}},
 	})
 	if err != nil {
 		return err

openmeter/billing/validators/customer/customer.go

@@ -13,6 +13,7 @@ import (
 	"github.com/openmeterio/openmeter/openmeter/customer"
 	"github.com/openmeterio/openmeter/openmeter/subscription"
 	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/filter"
 	"github.com/openmeterio/openmeter/pkg/models"
 	"github.com/openmeterio/openmeter/pkg/pagination"
 	"github.com/openmeterio/openmeter/pkg/timeutil"
@@ -102,8 +103,8 @@ func (r *Reconciler) ListSubscriptions(ctx context.Context, in ReconcilerListSub
 
 	for {
 		subscriptions, err := r.subscriptionService.List(ctx, subscription.ListSubscriptionsInput{
-			Namespaces:  in.Namespaces,
-			CustomerIDs: in.Customers,
+			Namespaces: in.Namespaces,
+			CustomerID: &filter.FilterULID{FilterString: filter.FilterString{In: &in.Customers}},
 			ActiveInPeriod: &timeutil.StartBoundedPeriod{
 				From: clock.Now().Add(-in.Lookback),
 				To:   lo.ToPtr(clock.Now()),

openmeter/billing/worker/subscriptionsync/reconciler/reconciler.go

@@ -13,6 +13,7 @@ import (
 	entdb "github.com/openmeterio/openmeter/openmeter/ent/db"
 	appcustomerdb "github.com/openmeterio/openmeter/openmeter/ent/db/appcustomer"
 	appstripecustomerdb "github.com/openmeterio/openmeter/openmeter/ent/db/appstripecustomer"
+	billingcustomeroverridedb "github.com/openmeterio/openmeter/openmeter/ent/db/billingcustomeroverride"
 	customerdb "github.com/openmeterio/openmeter/openmeter/ent/db/customer"
 	customersubjectsdb "github.com/openmeterio/openmeter/openmeter/ent/db/customersubjects"
 	plandb "github.com/openmeterio/openmeter/openmeter/ent/db/plan"
@@ -56,18 +57,35 @@ func (a *adapter) ListCustomers(ctx context.Context, input customer.ListCustomer
 		query = filter.ApplyToQuery(query, input.Name, customerdb.FieldName)
 		query = filter.ApplyToQuery(query, input.PrimaryEmail, customerdb.FieldPrimaryEmail)
 
-		if input.Subject != nil {
-			query = query.Where(customerdb.HasSubjectsWith(
-				customersubjectsdb.SubjectKeyContainsFold(*input.Subject),
-				customersubjectsdb.Or(
-					customersubjectsdb.DeletedAtIsNil(),
-					customersubjectsdb.DeletedAtGTE(now),
-				),
-			))
+		if input.PlanKey != nil {
+			applyActiveSubscriptionFilterWithPlanKey(query, now, input.PlanKey)
+		}
+
+		if input.UsageAttributionSubjectKey != nil {
+			if p := filter.SelectPredicate[predicate.CustomerSubjects](
+				filter.Filter(*input.UsageAttributionSubjectKey),
+				customersubjectsdb.FieldSubjectKey,
+			); p != nil {
+				query = query.Where(customerdb.HasSubjectsWith(
+					*p,
+					customersubjectsdb.Or(
+						customersubjectsdb.DeletedAtIsNil(),
+						customersubjectsdb.DeletedAtGTE(now),
+					),
+				))
+			}
 		}
 
-		if input.PlanKey != nil {
-			applyActiveSubscriptionFilterWithPlanKey(query, now, *input.PlanKey)
+		if input.BillingProfileID != nil {
+			if p := filter.SelectPredicate[predicate.BillingCustomerOverride](
+				filter.Filter(*input.BillingProfileID),
+				billingcustomeroverridedb.FieldBillingProfileID,
+			); p != nil {
+				query = query.Where(customerdb.HasBillingCustomerOverrideWith(
+					*p,
+					billingcustomeroverridedb.DeletedAtIsNil(),
+				))
+			}
 		}
 
 		if len(input.CustomerIDs) > 0 {
@@ -751,12 +769,14 @@ func applyActiveSubscriptionFilter(query *entdb.SubscriptionQuery, at time.Time)
 	query.Where(activeSubscriptionFilter(at)...)
 }
 
-func applyActiveSubscriptionFilterWithPlanKey(query *entdb.CustomerQuery, at time.Time, planKey string) {
-	predicates := activeSubscriptionFilter(at)
+func applyActiveSubscriptionFilterWithPlanKey(query *entdb.CustomerQuery, at time.Time, planKey *filter.FilterString) {
+	p := filter.SelectPredicate[predicate.Plan](filter.Filter(*planKey), plandb.FieldKey)
+	if p == nil {
+		return
+	}
 
-	predicates = append(predicates, subscriptiondb.HasPlanWith(
-		plandb.Key(planKey),
-	))
+	predicates := activeSubscriptionFilter(at)
+	predicates = append(predicates, subscriptiondb.HasPlanWith(*p))
 
 	query.Where(
 		customerdb.HasSubscriptionWith(predicates...),

openmeter/customer/adapter/customer.go

@@ -304,12 +304,13 @@ type ListCustomersInput struct {
 	Order   sortx.Order
 
 	// Filters
-	Key          *filter.FilterString
-	Name         *filter.FilterString
-	PrimaryEmail *filter.FilterString
-	Subject      *string
-	PlanKey      *string
-	CustomerIDs  []string
+	Key                        *filter.FilterString
+	Name                       *filter.FilterString
+	PrimaryEmail               *filter.FilterString
+	UsageAttributionSubjectKey *filter.FilterString
+	PlanKey                    *filter.FilterString
+	CustomerIDs                []string
+	BillingProfileID           *filter.FilterULID
 
 	// Expand
 	Expands Expands
@@ -344,6 +345,24 @@ func (i ListCustomersInput) Validate() error {
 		}
 	}
 
+	if i.UsageAttributionSubjectKey != nil {
+		if err := i.UsageAttributionSubjectKey.Validate(); err != nil {
+			errs = append(errs, models.NewGenericValidationError(fmt.Errorf("invalid usage attribution subject key filter: %w", err)))
+		}
+	}
+
+	if i.PlanKey != nil {
+		if err := i.PlanKey.Validate(); err != nil {
+			errs = append(errs, models.NewGenericValidationError(fmt.Errorf("invalid plan key filter: %w", err)))
+		}
+	}
+
+	if i.BillingProfileID != nil {
+		if err := i.BillingProfileID.Validate(); err != nil {
+			errs = append(errs, models.NewGenericValidationError(fmt.Errorf("invalid billing profile id filter: %w", err)))
+		}
+	}
+
 	return models.NewNillableGenericValidationError(errors.Join(errs...))
 }