subscription

type Access interface {
	// SubscriptionByToken returns the subscription holding the token. An
	// unknown token reports gorm.ErrRecordNotFound.
	SubscriptionByToken(ctx context.Context, token string) (*usersubEntity.Subscribe, error)
	// SubscriptionByID returns the subscription. An unknown id reports
	// gorm.ErrRecordNotFound.
	SubscriptionByID(ctx context.Context, id int64) (*usersubEntity.Subscribe, error)
	// SubscriptionsByIDs returns the subscriptions among the ids that exist.
	SubscriptionsByIDs(ctx context.Context, ids []int64) ([]*usersubEntity.Subscribe, error)
	// SubscriptionDetailsByIDs returns the subscriptions among the ids that
	// exist, each with its plan.
	SubscriptionDetailsByIDs(ctx context.Context, ids []int64) ([]*usersubEntity.SubscribeDetails, error)
	// PlanByID returns the plan.
	PlanByID(ctx context.Context, id int64) (*subscribe.Subscribe, error)
	// ServableSubscriptionsByNodeScope returns the subscriptions the nodes
	// of a scope may serve now: the servable subscriptions of the plans
	// selecting any of the node ids or tags, by plan and id, each with its
	// plan.
	ServableSubscriptionsByNodeScope(ctx context.Context, nodeIDs []int64, tags []string) ([]ServedSubscription, error)
	// ClearUserSubscriptionCaches drops the cached entries of every
	// subscription the users hold, so the tokens of a deleted or disabled
	// account stop resolving from the cache, and returns the node scope of
	// their plans: the node user lists that still carry the subscriptions.
	// A failed cache deletion is logged; the scope is returned all the same.
	ClearUserSubscriptionCaches(ctx context.Context, userIDs []int64) (nodeIDs []int64, tags []string, err error)
	// ClientApplications lists the client applications in their stored
	// order.
	ClientApplications(ctx context.Context) ([]*client.SubscribeApplication, error)
}

type Accounts interface {
	// FindOne returns the account with its devices and auth methods,
	// soft-deleted ones included.
	FindOne(ctx context.Context, id int64) (*user.User, error)
	// FindAccountState returns the account gate (enabled, deleted),
	// soft-deleted accounts included.
	FindAccountState(ctx context.Context, id int64) (*user.AccountState, error)
	// FindUsersByIds returns the live accounts among ids.
	FindUsersByIds(ctx context.Context, ids []int64) ([]*user.User, error)
	// FindUserAuthMethodsByUserIds returns the method bindings of the
	// accounts; soft-deleted accounts resolve to none.
	FindUserAuthMethodsByUserIds(ctx context.Context, method string, userIds []int64) ([]*user.AuthMethods, error)
	// QueryDevicePageList pages the account's devices, optionally only those
	// of one subscription.
	QueryDevicePageList(ctx context.Context, userid, subscribeId int64, page, size int) ([]*user.Device, int64, error)
	// ClearUserCache drops the id-keyed cached projections of the accounts;
	// ClearUserCacheOf every projection the loaded accounts derive.
	ClearUserCache(ctx context.Context, userIDs ...int64) error
	ClearUserCacheOf(ctx context.Context, users ...*user.User) error
}

type DeliveryConfig = delivery.Config

type DeliveryLimiter = delivery.FetchLimiter

type Deps struct {
	Plans    repository.SubscribeRepo
	UserSubs repository.UserSubscriptionRepo
	Nodes    NodeReader
	Store    SubscriptionTransactor
	// NotifyPlanChanged broadcasts a plan update to connected devices.
	NotifyPlanChanged func()
	// IsTrialPlan reports whether the plan is the configured trial plan.
	IsTrialPlan func(planID int64) bool

	// Delivery dependencies.
	Clients repository.ClientRepo
	Logs    repository.LogRepo
	// DeliveryConfig reads the runtime-mutable delivery configuration.
	DeliveryConfig func() DeliveryConfig
	// DeliveryLimiter bounds the subscription fetches per client address
	// (NewDeliveryLimiter); nil admits every fetch.
	DeliveryLimiter DeliveryLimiter

	// Accounts is the identity port of delivery, administration, lifecycle
	// and quota use cases: owners, their devices and email bindings, and
	// their cached projections.
	Accounts Accounts

	// User-subscription administration dependencies.
	Traffic TrafficLogReader
	// Operations composes only the persistence capabilities of this module's
	// administration, lifecycle and fulfillment use cases.
	Operations Store
	// Orders, Refunds and QuotaGifts are the billing module's side of
	// fulfillment, cancellation and quota tasks: the orders they read, the
	// cancellation's refund stage and the quota task's gift stage.
	Orders     OrderReader
	Refunds    RefundSettler
	QuotaGifts QuotaGiftLedger
	Inbox      repository.InboxRepo
	// SingleModel forbids holding more than one blocking subscription;
	// runtime-mutable, read per request.
	SingleModel func() bool
	// TrialPolicy snapshots the runtime-mutable registration-trial settings
	// per call.
	TrialPolicy func() TrialPolicy

	// LifecycleNotify is the lifecycle sweep's owner notification channel.
	LifecycleNotify sweep.Notifier
}

type FulfillmentOutcome = fulfillment.Outcome

type Inventory interface {
	Reserve(ctx context.Context, orderNo string, subscribeID int64) error
	Restore(ctx context.Context, orderNo string, subscribeID int64) error
}

type InventoryStore = inventory.Store

type NodeReader interface {
	delivery.NodeLister
	storefront.NodeLister
	application.NodeLister
}

type OrderReader interface {
	fulfillment.OrderReader
	selfsub.OrderReader
}

type QuotaGiftLedger = quotatask.GiftLedger

type Reads interface {
	// FilterPlans pages the plans the filter selects.
	FilterPlans(ctx context.Context, params *subscribe.FilterParams) (int64, []*subscribe.Subscribe, error)
	// SubscriptionDetailsByID returns the subscription with its plan.
	SubscriptionDetailsByID(ctx context.Context, id int64) (*usersubEntity.SubscribeDetails, error)
	// UserSubscriptions lists the user's subscriptions with their plans;
	// given statuses, only those in one of them.
	UserSubscriptions(ctx context.Context, userID int64, statuses ...int64) ([]*usersubEntity.SubscribeDetails, error)
	// HasBlockingSubscription reports whether the user holds a subscription
	// that forbids buying another while only one may be held.
	HasBlockingSubscription(ctx context.Context, userID int64) (bool, error)
	// CountQuotaConsumingSubscriptions counts the user's subscriptions of the
	// plan that count against its per-user purchase quota.
	CountQuotaConsumingSubscriptions(ctx context.Context, userID, planID int64) (int64, error)
	// SelectSubscriptionIDs returns the ids of the subscriptions the filter
	// selects; CountSelectedSubscriptions counts them.
	SelectSubscriptionIDs(ctx context.Context, filter *usersubEntity.SubscribeFilter) ([]int64, error)
	CountSelectedSubscriptions(ctx context.Context, filter *usersubEntity.SubscribeFilter) (int64, error)
}

type RefundSettler = selfsub.RefundSettler

type RequestMeta = delivery.RequestMeta

type ServedSubscription = nodeaccess.Served

type Service interface {
	// CheckSubscriptions runs the lifecycle sweeps (traffic exceeded,
	// expired), committing status flips in subscription transactions with
	// notification and cache invalidation as post-commit side effects.
	CheckSubscriptions(ctx context.Context) error
	// RemindExpiringSubscriptions warns owners whose subscription expires
	// soon. It is a daily pass, not part of the minute-by-minute sweep: the
	// notice is once per expiry and reaching users at a civil hour matters.
	RemindExpiringSubscriptions(ctx context.Context) error
	// ResetCalendarTraffic clears the traffic of the subscriptions owed their
	// plan's calendar reset (1st of the month, monthly, yearly): those whose
	// reset falls on today and those a missed run left unreset since their
	// last reset day, each at most once per day however often a failed run
	// is repeated.
	ResetCalendarTraffic(ctx context.Context) error
	// ProcessQuotaTask executes an admin-scheduled quota grant (time
	// extension / gift credit) for the task's subscription scope.
	ProcessQuotaTask(ctx context.Context, taskID int64) error
	// FulfillPaidOrder applies a paid order's business effect (new
	// subscription, renewal or traffic reset) exactly once and returns the
	// notification context.
	FulfillPaidOrder(ctx context.Context, orderNo string) (*FulfillmentOutcome, error)
	ReconcileEntitlement(ctx context.Context, cmd dto.ReconcileEntitlementCommand) (*dto.EntitlementResult, error)
	// GrantTrial consumes the identity.user_registered event: applies the
	// registration trial exactly once (a disabled policy still consumes the
	// event).
	GrantTrial(ctx context.Context, userID int64) error

	// The client-application management for subscription delivery.
	CreateSubscribeApplication(ctx context.Context, req *dto.CreateSubscribeApplicationRequest) (*dto.SubscribeApplication, error)
	UpdateSubscribeApplication(ctx context.Context, req *dto.UpdateSubscribeApplicationRequest) (*dto.SubscribeApplication, error)
	DeleteSubscribeApplication(ctx context.Context, req *dto.DeleteSubscribeApplicationRequest) error
	GetSubscribeApplicationList(ctx context.Context, req *dto.GetSubscribeApplicationListRequest) (*dto.GetSubscribeApplicationListResponse, error)
	PreviewSubscribeTemplate(ctx context.Context, req *dto.PreviewSubscribeTemplateRequest) (*dto.PreviewSubscribeTemplateResponse, error)

	CreateSubscribe(ctx context.Context, req *dto.CreateSubscribeRequest) error
	UpdateSubscribe(ctx context.Context, req *dto.UpdateSubscribeRequest) error
	DeleteSubscribe(ctx context.Context, req *dto.DeleteSubscribeRequest) error
	BatchDeleteSubscribe(ctx context.Context, req *dto.BatchDeleteSubscribeRequest) error
	GetSubscribeList(ctx context.Context, req *dto.GetSubscribeListRequest) (*dto.GetSubscribeListResponse, error)
	GetSubscribeDetails(ctx context.Context, req *dto.GetSubscribeDetailsRequest) (*dto.Subscribe, error)
	SubscribeSort(ctx context.Context, req *dto.SubscribeSortRequest) error
	ResetAllSubscribeToken(ctx context.Context) (*dto.ResetAllSubscribeTokenResponse, error)
	CreateSubscribeGroup(ctx context.Context, req *dto.CreateSubscribeGroupRequest) error
	UpdateSubscribeGroup(ctx context.Context, req *dto.UpdateSubscribeGroupRequest) error
	DeleteSubscribeGroup(ctx context.Context, req *dto.DeleteSubscribeGroupRequest) error
	BatchDeleteSubscribeGroup(ctx context.Context, req *dto.BatchDeleteSubscribeGroupRequest) error
	GetSubscribeGroupList(ctx context.Context) (*dto.GetSubscribeGroupListResponse, error)

	QuerySubscribeList(ctx context.Context, req *dto.QuerySubscribeListRequest) (*dto.QuerySubscribeListResponse, error)
	QuerySubscribeGroupList(ctx context.Context) (*dto.QuerySubscribeGroupListResponse, error)
	QueryUserSubscribeNodeList(ctx context.Context) (*dto.QueryUserSubscribeNodeListResponse, error)

	// Deliver renders the client configuration for a subscription token.
	Deliver(ctx context.Context, meta RequestMeta, req *dto.SubscribeRequest) (*dto.SubscribeResponse, error)
	// IsUserAgentAllowed gates delivery by the configured user-agent allowlist.
	IsUserAgentAllowed(ctx context.Context, userAgent string) bool

	// User self-service subscription management.
	QueryUserSubscribe(ctx context.Context) (*dto.QueryUserSubscribeListResponse, error)
	// ResetOwnSubscribeToken is the self-service variant; ownership of the
	// subscription is enforced against the request context.
	ResetOwnSubscribeToken(ctx context.Context, req *dto.ResetUserSubscribeTokenRequest) error
	GetSubscribeLog(ctx context.Context, req *dto.GetSubscribeLogRequest) (*dto.GetSubscribeLogResponse, error)
	UpdateUserSubscribeNote(ctx context.Context, req *dto.UpdateUserSubscribeNoteRequest) error
	PreUnsubscribe(ctx context.Context, req *dto.PreUnsubscribeRequest) (*dto.PreUnsubscribeResponse, error)
	// Unsubscribe cancels in a subscription transaction and settles the
	// refund in a billing transaction, resumable via the idempotent inbox.
	Unsubscribe(ctx context.Context, req *dto.UnsubscribeRequest) error

	// Admin-side user subscription management.
	CreateUserSubscribe(ctx context.Context, req *dto.CreateUserSubscribeRequest) error
	DeleteUserSubscribe(ctx context.Context, req *dto.DeleteUserSubscribeRequest) error
	UpdateUserSubscribe(ctx context.Context, req *dto.UpdateUserSubscribeRequest) error
	GetUserSubscribe(ctx context.Context, req *dto.GetUserSubscribeListRequest) (*dto.GetUserSubscribeListResponse, error)
	GetUserSubscribeById(ctx context.Context, req *dto.GetUserSubscribeByIdRequest) (*dto.UserSubscribeDetail, error)
	GetUserSubscribeDevices(ctx context.Context, req *dto.GetUserSubscribeDevicesRequest) (*dto.GetUserSubscribeDevicesResponse, error)
	GetUserSubscribeLogs(ctx context.Context, req *dto.GetUserSubscribeLogsRequest) (*dto.GetUserSubscribeLogsResponse, error)
	GetUserSubscribeResetTrafficLogs(ctx context.Context, req *dto.GetUserSubscribeResetTrafficLogsRequest) (*dto.GetUserSubscribeResetTrafficLogsResponse, error)
	GetUserSubscribeTrafficLogs(ctx context.Context, req *dto.GetUserSubscribeTrafficLogsRequest) (*dto.GetUserSubscribeTrafficLogsResponse, error)
	ResetUserSubscribeToken(ctx context.Context, req *dto.ResetUserSubscribeTokenRequest) error
	ResetUserSubscribeTraffic(ctx context.Context, req *dto.ResetUserSubscribeTrafficRequest) error
	ToggleUserSubscribeStatus(ctx context.Context, req *dto.ToggleUserSubscribeStatusRequest) error
	// ChangeUserSubscribeStatus stops or resumes a subscription the caller
	// saw in status from, refusing when the status changed meanwhile.
	ChangeUserSubscribeStatus(ctx context.Context, id int64, from, to uint8) error

	// Access and Reads serve the other modules' reads and cache
	// invalidation (see access.go and reads.go).
	Access
	Reads
}

type Store interface {
	usersub.Store
	selfsub.Store
	sweep.Store
	trial.Store
	fulfillment.Store
	quotatask.Store
	trafficreset.Store
}

type SubscriptionTransactor = plan.SubscriptionTransactor

type TrafficLogReader = usersub.TrafficLogReader

type TrafficUsage interface {
	ApplyBucketOnce(ctx context.Context, bucket string, deltas []traffic.SubscribeTrafficDelta) error
}

type TrafficUsageStore = trafficusage.Store

type TrialPolicy = trial.Policy