1	<?php
2
3	namespace App\Http\Repositories\interfaces;
4
5	use App\Http\Models\Auth\User;
6	use App\Http\Models\Plans;
7	use App\Http\Models\Subscription;
8
9	/**
10	* Interface for subscription data access operations.
11	*
12	* This repository abstracts subscription-related database queries,
13	* providing methods to retrieve active subscriptions and plan information.
14	*/
15	interface ISubscriptionRepository
16	{
17	/**
18	* Get the active subscription for a user.
19	*
20	* This method finds the most recent valid subscription for the user,
21	* ordered by created_at DESC, returning the first one that is valid.
22	* This fixes the bug where the first() method could return a deactivated
23	* subscription instead of the newest active one.
24	*
25	* @param  User  $user  The user to get the subscription for
26	* @param  string  $name  The subscription name (default: 'main')
27	* @return Subscription|null The active subscription or null if none found
28	*/
29	public function getActiveSubscription(User $user, string $name = 'main'): ?Subscription;
30
31	/**
32	* Get the freemium plan.
33	*
34	* @return Plans The freemium plan
35	*/
36	public function getFreemiumPlan(): Plans;
37
38	/**
39	* Get a plan by its identifier.
40	*
41	* @param  string  $identifier  The plan identifier
42	* @return Plans|null The plan or null if not found
43	*/
44	public function getPlanByIdentifier(string $identifier): ?Plans;
45
46	/**
47	* Get counts of active subscriptions grouped by stripe_plan.
48	*
49	* Uses the same active subscription criteria as the Subscription::active() scope:
50	* - ends_at is null OR ends_at > now (grace period)
51	* - stripe_status NOT IN [incomplete, incomplete_expired, unpaid]
52	* - If Cashier::$deactivatePastDue is true: excludes past_due status
53	*
54	* @return array<string, int> Map of stripe_plan to active subscription count
55	*/
56	public function getActiveSubscriptionCountsByPlan(): array;
57	}