repository

type AddOnFilter struct {
	AppID    *xid.ID
	IsActive *bool
	IsPublic *bool
	Page     int
	PageSize int
}

type AddOnRepository interface {
	// Create creates a new add-on
	Create(ctx context.Context, addon *schema.SubscriptionAddOn) error

	// Update updates an existing add-on
	Update(ctx context.Context, addon *schema.SubscriptionAddOn) error

	// Delete soft-deletes an add-on
	Delete(ctx context.Context, id xid.ID) error

	// FindByID retrieves an add-on by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionAddOn, error)

	// FindBySlug retrieves an add-on by slug within an app
	FindBySlug(ctx context.Context, appID xid.ID, slug string) (*schema.SubscriptionAddOn, error)

	// List retrieves add-ons with optional filters
	List(ctx context.Context, filter *AddOnFilter) ([]*schema.SubscriptionAddOn, int, error)

	// CreateFeature creates an add-on feature
	CreateFeature(ctx context.Context, feature *schema.SubscriptionAddOnFeature) error

	// DeleteFeatures deletes all features for an add-on
	DeleteFeatures(ctx context.Context, addOnID xid.ID) error

	// CreateTier creates a pricing tier
	CreateTier(ctx context.Context, tier *schema.SubscriptionAddOnTier) error

	// DeleteTiers deletes all tiers for an add-on
	DeleteTiers(ctx context.Context, addOnID xid.ID) error
}

type AlertRepository interface {
	// Alert config operations
	CreateAlertConfig(ctx context.Context, config *core.AlertConfig) error
	GetAlertConfig(ctx context.Context, id xid.ID) (*core.AlertConfig, error)
	GetAlertConfigByType(ctx context.Context, orgID xid.ID, alertType core.AlertType) (*core.AlertConfig, error)
	ListAlertConfigs(ctx context.Context, orgID xid.ID) ([]*core.AlertConfig, error)
	UpdateAlertConfig(ctx context.Context, config *core.AlertConfig) error
	DeleteAlertConfig(ctx context.Context, id xid.ID) error

	// Alert operations
	CreateAlert(ctx context.Context, alert *core.Alert) error
	GetAlert(ctx context.Context, id xid.ID) (*core.Alert, error)
	ListAlerts(ctx context.Context, orgID xid.ID, status *core.AlertStatus, page, pageSize int) ([]*core.Alert, int, error)
	ListPendingAlerts(ctx context.Context) ([]*core.Alert, error)
	UpdateAlert(ctx context.Context, alert *core.Alert) error
	DeleteAlert(ctx context.Context, id xid.ID) error
	CountAlertsByConfigToday(ctx context.Context, configID xid.ID) (int, error)
	GetLastAlertByConfig(ctx context.Context, configID xid.ID) (*core.Alert, error)

	// Alert template operations
	CreateAlertTemplate(ctx context.Context, template *core.AlertTemplate) error
	GetAlertTemplate(ctx context.Context, appID xid.ID, alertType core.AlertType, channel core.AlertChannel) (*core.AlertTemplate, error)
	ListAlertTemplates(ctx context.Context, appID xid.ID) ([]*core.AlertTemplate, error)
	UpdateAlertTemplate(ctx context.Context, template *core.AlertTemplate) error
	DeleteAlertTemplate(ctx context.Context, id xid.ID) error
}

type AnalyticsRepository interface {
	// Billing metric operations
	CreateMetric(ctx context.Context, metric *core.BillingMetric) error
	GetMetric(ctx context.Context, appID xid.ID, metricType core.MetricType, date time.Time, period core.MetricPeriod) (*core.BillingMetric, error)
	ListMetrics(ctx context.Context, appID xid.ID, metricTypes []core.MetricType, period core.MetricPeriod, startDate, endDate time.Time) ([]*core.BillingMetric, error)
	UpsertMetric(ctx context.Context, metric *core.BillingMetric) error

	// Subscription movement operations
	CreateMovement(ctx context.Context, movement *core.SubscriptionMovement) error
	ListMovements(ctx context.Context, appID xid.ID, startDate, endDate time.Time, movementType string, page, pageSize int) ([]*core.SubscriptionMovement, int, error)
	GetMovementSummary(ctx context.Context, appID xid.ID, startDate, endDate time.Time, currency string) (*MovementSummary, error)

	// Cohort operations
	CreateCohort(ctx context.Context, cohort *core.CohortAnalysis) error
	GetCohort(ctx context.Context, appID xid.ID, cohortMonth time.Time) (*core.CohortAnalysis, error)
	ListCohorts(ctx context.Context, appID xid.ID, startMonth time.Time, numMonths int) ([]*core.CohortAnalysis, error)
	UpsertCohort(ctx context.Context, appID xid.ID, cohortMonth time.Time, monthNumber int, activeCustomers int, revenue int64, currency string) error

	// Dashboard metrics
	GetDashboardMetrics(ctx context.Context, appID xid.ID, currency string) (*core.DashboardMetrics, error)
	GetMRRHistory(ctx context.Context, appID xid.ID, startDate, endDate time.Time, currency string) ([]*core.MRRBreakdown, error)
}

type CouponRepository interface {
	// Coupon operations
	CreateCoupon(ctx context.Context, coupon *core.Coupon) error
	GetCoupon(ctx context.Context, id xid.ID) (*core.Coupon, error)
	GetCouponByCode(ctx context.Context, appID xid.ID, code string) (*core.Coupon, error)
	ListCoupons(ctx context.Context, appID xid.ID, status *core.CouponStatus, page, pageSize int) ([]*core.Coupon, int, error)
	UpdateCoupon(ctx context.Context, coupon *core.Coupon) error
	DeleteCoupon(ctx context.Context, id xid.ID) error
	IncrementRedemptions(ctx context.Context, id xid.ID) error

	// Redemption operations
	CreateRedemption(ctx context.Context, redemption *core.CouponRedemption) error
	GetRedemption(ctx context.Context, id xid.ID) (*core.CouponRedemption, error)
	GetRedemptionByCouponAndOrg(ctx context.Context, couponID, orgID xid.ID) (*core.CouponRedemption, error)
	ListRedemptions(ctx context.Context, couponID xid.ID, page, pageSize int) ([]*core.CouponRedemption, int, error)
	ListRedemptionsByOrg(ctx context.Context, orgID xid.ID) ([]*core.CouponRedemption, error)
	CountRedemptionsByOrg(ctx context.Context, couponID, orgID xid.ID) (int, error)

	// Promotion code operations
	CreatePromotionCode(ctx context.Context, code *core.PromotionCode) error
	GetPromotionCode(ctx context.Context, id xid.ID) (*core.PromotionCode, error)
	GetPromotionCodeByCode(ctx context.Context, appID xid.ID, code string) (*core.PromotionCode, error)
	ListPromotionCodes(ctx context.Context, couponID xid.ID, page, pageSize int) ([]*core.PromotionCode, int, error)
	UpdatePromotionCode(ctx context.Context, code *core.PromotionCode) error
	DeletePromotionCode(ctx context.Context, id xid.ID) error
	IncrementPromoRedemptions(ctx context.Context, id xid.ID) error
}

type CurrencyRepository interface {
	// Currency operations
	ListCurrencies(ctx context.Context) ([]*core.SupportedCurrency, error)
	GetCurrency(ctx context.Context, code string) (*core.SupportedCurrency, error)
	CreateCurrency(ctx context.Context, currency *core.SupportedCurrency) error
	UpdateCurrency(ctx context.Context, currency *core.SupportedCurrency) error

	// Exchange rate operations
	CreateExchangeRate(ctx context.Context, rate *core.ExchangeRate) error
	GetExchangeRate(ctx context.Context, fromCurrency, toCurrency string) (*core.ExchangeRate, error)
	GetExchangeRateAt(ctx context.Context, fromCurrency, toCurrency string, at time.Time) (*core.ExchangeRate, error)
	ListExchangeRates(ctx context.Context, appID xid.ID) ([]*core.ExchangeRate, error)
	UpdateExchangeRate(ctx context.Context, rate *core.ExchangeRate) error
	DeleteExchangeRate(ctx context.Context, id xid.ID) error
}

type CustomerRepository interface {
	// Create creates a new customer
	Create(ctx context.Context, customer *schema.SubscriptionCustomer) error

	// Update updates an existing customer
	Update(ctx context.Context, customer *schema.SubscriptionCustomer) error

	// Delete deletes a customer
	Delete(ctx context.Context, id xid.ID) error

	// FindByID retrieves a customer by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionCustomer, error)

	// FindByOrganizationID retrieves a customer by organization ID
	FindByOrganizationID(ctx context.Context, orgID xid.ID) (*schema.SubscriptionCustomer, error)

	// FindByProviderID retrieves a customer by provider customer ID
	FindByProviderID(ctx context.Context, providerCustomerID string) (*schema.SubscriptionCustomer, error)
}

type EventFilter struct {
	SubscriptionID *xid.ID
	OrganizationID *xid.ID
	EventType      string
	Page           int
	PageSize       int
}

type EventRepository interface {
	// Create creates a new event
	Create(ctx context.Context, event *schema.SubscriptionEvent) error

	// FindByID retrieves an event by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionEvent, error)

	// List retrieves events with optional filters
	List(ctx context.Context, filter *EventFilter) ([]*schema.SubscriptionEvent, int, error)
}

type FeatureFilter struct {
	AppID    *xid.ID
	Type     string
	IsPublic *bool
	Page     int
	PageSize int
}

type FeatureRepository interface {
	// Create creates a new feature
	Create(ctx context.Context, feature *schema.Feature) error

	// Update updates an existing feature
	Update(ctx context.Context, feature *schema.Feature) error

	// Delete deletes a feature
	Delete(ctx context.Context, id xid.ID) error

	// FindByID retrieves a feature by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.Feature, error)

	// FindByKey retrieves a feature by key within an app
	FindByKey(ctx context.Context, appID xid.ID, key string) (*schema.Feature, error)

	// List retrieves features with optional filters
	List(ctx context.Context, filter *FeatureFilter) ([]*schema.Feature, int, error)

	// CreateTier creates a feature tier
	CreateTier(ctx context.Context, tier *schema.FeatureTier) error

	// DeleteTiers deletes all tiers for a feature
	DeleteTiers(ctx context.Context, featureID xid.ID) error

	// GetTiers retrieves all tiers for a feature
	GetTiers(ctx context.Context, featureID xid.ID) ([]*schema.FeatureTier, error)

	// LinkToPlan links a feature to a plan
	LinkToPlan(ctx context.Context, link *schema.PlanFeatureLink) error

	// UpdatePlanLink updates a feature-plan link
	UpdatePlanLink(ctx context.Context, link *schema.PlanFeatureLink) error

	// UnlinkFromPlan removes a feature from a plan
	UnlinkFromPlan(ctx context.Context, planID, featureID xid.ID) error

	// GetPlanLinks retrieves all feature links for a plan
	GetPlanLinks(ctx context.Context, planID xid.ID) ([]*schema.PlanFeatureLink, error)

	// GetPlanLink retrieves a specific feature link
	GetPlanLink(ctx context.Context, planID, featureID xid.ID) (*schema.PlanFeatureLink, error)

	// GetFeaturePlans retrieves all plans that have a feature
	GetFeaturePlans(ctx context.Context, featureID xid.ID) ([]*schema.PlanFeatureLink, error)
}

type FeatureUsageLogFilter struct {
	OrganizationID *xid.ID
	FeatureID      *xid.ID
	Action         string
	Page           int
	PageSize       int
}

type FeatureUsageRepository interface {
	// CreateUsage creates or updates feature usage for an organization
	CreateUsage(ctx context.Context, usage *schema.OrganizationFeatureUsage) error

	// UpdateUsage updates feature usage
	UpdateUsage(ctx context.Context, usage *schema.OrganizationFeatureUsage) error

	// FindUsage retrieves feature usage for an organization and feature
	FindUsage(ctx context.Context, orgID, featureID xid.ID) (*schema.OrganizationFeatureUsage, error)

	// FindUsageByKey retrieves feature usage by feature key
	FindUsageByKey(ctx context.Context, orgID, appID xid.ID, featureKey string) (*schema.OrganizationFeatureUsage, error)

	// ListUsage retrieves all feature usage for an organization
	ListUsage(ctx context.Context, orgID xid.ID) ([]*schema.OrganizationFeatureUsage, error)

	// IncrementUsage atomically increments usage by a quantity
	IncrementUsage(ctx context.Context, orgID, featureID xid.ID, quantity int64) (*schema.OrganizationFeatureUsage, error)

	// DecrementUsage atomically decrements usage by a quantity
	DecrementUsage(ctx context.Context, orgID, featureID xid.ID, quantity int64) (*schema.OrganizationFeatureUsage, error)

	// ResetUsage resets usage to zero
	ResetUsage(ctx context.Context, orgID, featureID xid.ID) error

	// CreateLog creates a usage log entry
	CreateLog(ctx context.Context, log *schema.FeatureUsageLog) error

	// ListLogs retrieves usage logs with filters
	ListLogs(ctx context.Context, filter *FeatureUsageLogFilter) ([]*schema.FeatureUsageLog, int, error)

	// FindLogByIdempotencyKey finds a log by idempotency key
	FindLogByIdempotencyKey(ctx context.Context, key string) (*schema.FeatureUsageLog, error)

	// CreateGrant creates a feature grant
	CreateGrant(ctx context.Context, grant *schema.FeatureGrant) error

	// UpdateGrant updates a feature grant
	UpdateGrant(ctx context.Context, grant *schema.FeatureGrant) error

	// DeleteGrant deletes a feature grant
	DeleteGrant(ctx context.Context, id xid.ID) error

	// FindGrantByID retrieves a grant by ID
	FindGrantByID(ctx context.Context, id xid.ID) (*schema.FeatureGrant, error)

	// ListGrants retrieves all active grants for an organization and feature
	ListGrants(ctx context.Context, orgID, featureID xid.ID) ([]*schema.FeatureGrant, error)

	// ListAllOrgGrants retrieves all active grants for an organization
	ListAllOrgGrants(ctx context.Context, orgID xid.ID) ([]*schema.FeatureGrant, error)

	// Dashboard queries
	// GetCurrentUsageSnapshot retrieves all current usage across all organizations for an app
	GetCurrentUsageSnapshot(ctx context.Context, appID xid.ID) ([]*core.CurrentUsage, error)

	// GetUsageByOrg retrieves usage statistics by organization
	GetUsageByOrg(ctx context.Context, appID xid.ID, startDate, endDate time.Time) ([]*core.OrgUsageStats, error)

	// GetUsageTrends retrieves usage trends over time for a feature
	GetUsageTrends(ctx context.Context, appID xid.ID, featureID *xid.ID, startDate, endDate time.Time) ([]*core.UsageTrend, error)

	// GetTopConsumers retrieves top consuming organizations
	GetTopConsumers(ctx context.Context, appID xid.ID, featureID *xid.ID, startDate, endDate time.Time, limit int) ([]*core.OrgUsageStats, error)

	// GetUsageByFeatureType retrieves usage aggregated by feature type
	GetUsageByFeatureType(ctx context.Context, appID xid.ID, startDate, endDate time.Time) (map[core.FeatureType]*core.UsageStats, error)

	// GetTotalGrantedValue calculates total granted quota for an organization and feature
	GetTotalGrantedValue(ctx context.Context, orgID, featureID xid.ID) (int64, error)

	// ExpireGrants marks expired grants as inactive
	ExpireGrants(ctx context.Context) error

	// GetUsageNeedingReset retrieves usage records that need to be reset
	GetUsageNeedingReset(ctx context.Context, resetPeriod string) ([]*schema.OrganizationFeatureUsage, error)
}

type InvoiceFilter struct {
	OrganizationID *xid.ID
	SubscriptionID *xid.ID
	Status         string
	Page           int
	PageSize       int
}

type InvoiceRepository interface {
	// Create creates a new invoice
	Create(ctx context.Context, invoice *schema.SubscriptionInvoice) error

	// Update updates an existing invoice
	Update(ctx context.Context, invoice *schema.SubscriptionInvoice) error

	// FindByID retrieves an invoice by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionInvoice, error)

	// FindByNumber retrieves an invoice by number
	FindByNumber(ctx context.Context, number string) (*schema.SubscriptionInvoice, error)

	// FindByProviderID retrieves an invoice by provider invoice ID
	FindByProviderID(ctx context.Context, providerInvoiceID string) (*schema.SubscriptionInvoice, error)

	// List retrieves invoices with optional filters
	List(ctx context.Context, filter *InvoiceFilter) ([]*schema.SubscriptionInvoice, int, error)

	// CreateItem creates an invoice line item
	CreateItem(ctx context.Context, item *schema.SubscriptionInvoiceItem) error

	// GetItems retrieves all items for an invoice
	GetItems(ctx context.Context, invoiceID xid.ID) ([]*schema.SubscriptionInvoiceItem, error)

	// GetNextInvoiceNumber generates the next invoice number
	GetNextInvoiceNumber(ctx context.Context, appID xid.ID) (string, error)
}

type MovementSummary struct {
	NewMRR          int64 `json:"newMrr"`
	ExpansionMRR    int64 `json:"expansionMrr"`
	ContractionMRR  int64 `json:"contractionMrr"`
	ChurnedMRR      int64 `json:"churnedMrr"`
	ReactivationMRR int64 `json:"reactivationMrr"`
	NewCount        int   `json:"newCount"`
	UpgradeCount    int   `json:"upgradeCount"`
	DowngradeCount  int   `json:"downgradeCount"`
	ChurnCount      int   `json:"churnCount"`
	ReactivateCount int   `json:"reactivateCount"`
}

type PaymentMethodRepository interface {
	// Create creates a new payment method
	Create(ctx context.Context, pm *schema.SubscriptionPaymentMethod) error

	// Update updates an existing payment method
	Update(ctx context.Context, pm *schema.SubscriptionPaymentMethod) error

	// Delete deletes a payment method
	Delete(ctx context.Context, id xid.ID) error

	// FindByID retrieves a payment method by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionPaymentMethod, error)

	// FindByProviderID retrieves a payment method by provider method ID
	FindByProviderID(ctx context.Context, providerMethodID string) (*schema.SubscriptionPaymentMethod, error)

	// ListByOrganization retrieves all payment methods for an organization
	ListByOrganization(ctx context.Context, orgID xid.ID) ([]*schema.SubscriptionPaymentMethod, error)

	// GetDefault retrieves the default payment method for an organization
	GetDefault(ctx context.Context, orgID xid.ID) (*schema.SubscriptionPaymentMethod, error)

	// SetDefault sets a payment method as the default
	SetDefault(ctx context.Context, orgID, paymentMethodID xid.ID) error

	// ClearDefault clears the default flag on all payment methods for an organization
	ClearDefault(ctx context.Context, orgID xid.ID) error
}

type PlanFilter struct {
	AppID    *xid.ID
	IsActive *bool
	IsPublic *bool
	Page     int
	PageSize int
}

type PlanRepository interface {
	// Create creates a new plan
	Create(ctx context.Context, plan *schema.SubscriptionPlan) error

	// Update updates an existing plan
	Update(ctx context.Context, plan *schema.SubscriptionPlan) error

	// Delete soft-deletes a plan
	Delete(ctx context.Context, id xid.ID) error

	// FindByID retrieves a plan by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionPlan, error)

	// FindBySlug retrieves a plan by slug within an app
	FindBySlug(ctx context.Context, appID xid.ID, slug string) (*schema.SubscriptionPlan, error)

	// FindByProviderID retrieves a plan by provider plan ID (e.g., Stripe product ID)
	FindByProviderID(ctx context.Context, providerPlanID string) (*schema.SubscriptionPlan, error)

	// List retrieves plans with optional filters
	List(ctx context.Context, filter *PlanFilter) ([]*schema.SubscriptionPlan, int, error)

	// CreateFeature creates a plan feature
	CreateFeature(ctx context.Context, feature *schema.SubscriptionPlanFeature) error

	// DeleteFeatures deletes all features for a plan
	DeleteFeatures(ctx context.Context, planID xid.ID) error

	// CreateTier creates a pricing tier
	CreateTier(ctx context.Context, tier *schema.SubscriptionPlanTier) error

	// DeleteTiers deletes all tiers for a plan
	DeleteTiers(ctx context.Context, planID xid.ID) error
}

type SubscriptionFilter struct {
	AppID          *xid.ID
	OrganizationID *xid.ID
	PlanID         *xid.ID
	Status         string
	Page           int
	PageSize       int
}

type SubscriptionRepository interface {
	// Create creates a new subscription
	Create(ctx context.Context, sub *schema.Subscription) error

	// Update updates an existing subscription
	Update(ctx context.Context, sub *schema.Subscription) error

	// Delete soft-deletes a subscription
	Delete(ctx context.Context, id xid.ID) error

	// FindByID retrieves a subscription by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.Subscription, error)

	// FindByOrganizationID retrieves the active subscription for an organization
	FindByOrganizationID(ctx context.Context, orgID xid.ID) (*schema.Subscription, error)

	// FindByProviderID retrieves a subscription by provider subscription ID
	FindByProviderID(ctx context.Context, providerSubID string) (*schema.Subscription, error)

	// List retrieves subscriptions with optional filters
	List(ctx context.Context, filter *SubscriptionFilter) ([]*schema.Subscription, int, error)

	// CreateAddOnItem attaches an add-on to a subscription
	CreateAddOnItem(ctx context.Context, item *schema.SubscriptionAddOnItem) error

	// DeleteAddOnItem removes an add-on from a subscription
	DeleteAddOnItem(ctx context.Context, subscriptionID, addOnID xid.ID) error

	// GetAddOnItems retrieves all add-ons for a subscription
	GetAddOnItems(ctx context.Context, subscriptionID xid.ID) ([]*schema.SubscriptionAddOnItem, error)
}

type TaxRepository interface {
	// Tax rate operations
	CreateTaxRate(ctx context.Context, rate *core.TaxRate) error
	GetTaxRate(ctx context.Context, id xid.ID) (*core.TaxRate, error)
	GetTaxRateByLocation(ctx context.Context, appID xid.ID, country, state string) (*core.TaxRate, error)
	ListTaxRates(ctx context.Context, appID xid.ID, activeOnly bool) ([]*core.TaxRate, error)
	UpdateTaxRate(ctx context.Context, rate *core.TaxRate) error
	DeleteTaxRate(ctx context.Context, id xid.ID) error

	// Tax exemption operations
	CreateTaxExemption(ctx context.Context, exemption *core.TaxExemption) error
	GetTaxExemption(ctx context.Context, id xid.ID) (*core.TaxExemption, error)
	GetTaxExemptionByOrg(ctx context.Context, orgID xid.ID, country string) (*core.TaxExemption, error)
	ListTaxExemptions(ctx context.Context, orgID xid.ID) ([]*core.TaxExemption, error)
	UpdateTaxExemption(ctx context.Context, exemption *core.TaxExemption) error
	DeleteTaxExemption(ctx context.Context, id xid.ID) error

	// Customer tax ID operations
	CreateCustomerTaxID(ctx context.Context, taxID *core.CustomerTaxID) error
	GetCustomerTaxID(ctx context.Context, id xid.ID) (*core.CustomerTaxID, error)
	ListCustomerTaxIDs(ctx context.Context, orgID xid.ID) ([]*core.CustomerTaxID, error)
	UpdateCustomerTaxID(ctx context.Context, taxID *core.CustomerTaxID) error
	DeleteCustomerTaxID(ctx context.Context, id xid.ID) error
}

type UsageFilter struct {
	SubscriptionID *xid.ID
	OrganizationID *xid.ID
	MetricKey      string
	Reported       *bool
	Page           int
	PageSize       int
}

type UsageRepository interface {
	// Create creates a new usage record
	Create(ctx context.Context, record *schema.SubscriptionUsageRecord) error

	// FindByID retrieves a usage record by ID
	FindByID(ctx context.Context, id xid.ID) (*schema.SubscriptionUsageRecord, error)

	// FindByIdempotencyKey retrieves a usage record by idempotency key
	FindByIdempotencyKey(ctx context.Context, key string) (*schema.SubscriptionUsageRecord, error)

	// List retrieves usage records with optional filters
	List(ctx context.Context, filter *UsageFilter) ([]*schema.SubscriptionUsageRecord, int, error)

	// GetSummary calculates usage summary for a subscription and metric
	GetSummary(ctx context.Context, subscriptionID xid.ID, metricKey string, periodStart, periodEnd interface{}) (*UsageSummary, error)

	// GetUnreported retrieves usage records not yet reported to provider
	GetUnreported(ctx context.Context, limit int) ([]*schema.SubscriptionUsageRecord, error)

	// MarkReported marks a usage record as reported
	MarkReported(ctx context.Context, id xid.ID, providerRecordID string) error
}

type UsageSummary struct {
	MetricKey     string
	TotalQuantity int64
	RecordCount   int64
}