1	<?php
2
3	namespace App\Http\Repositories\interfaces;
4
5	use App\Http\Models\Auth\User;
6	use App\Http\Models\RolePlayConversations;
7	use Illuminate\Database\Eloquent\Collection;
8
9	/**
10	* Data access contract for RolePlayConversations.
11	*
12	* The monthly-window queries in this interface are duplicated across the
13	* subscription controller, dashboard controller, start/end session requests,
14	* and the reevaluation command. Centralising them here avoids per-site drift
15	* (and means a future SQL migration only has to touch one place).
16	*/
17	interface IRolePlayConversationsRepository
18	{
19	/**
20	* Number of sessions the user has started in the current calendar month.
21	* "Sessions" = all RolePlayConversations regardless of terminal status
22	* (matches the existing subscription-info semantics).
23	*/
24	public function countForUserThisMonth(User $user): int;
25
26	/**
27	* Total `duration` (seconds) of completed sessions in the current
28	* calendar month. Filters by `status = 'done'` so paused / failed
29	* sessions don't inflate the number.
30	*/
31	public function sumDoneDurationForUserThisMonth(User $user): int;
32
33	/**
34	* Number of sessions the user has *started* in the current calendar
35	* month counting every status. Used for authorize() quota guards that
36	* must count pending/processing/failed attempts too.
37	*/
38	public function countStartedForUserThisMonth(User $user): int;
39
40	/**
41	* Total `duration` (seconds) for sessions in the current calendar
42	* month regardless of status — companion to {@see countStartedForUserThisMonth()}.
43	*/
44	public function sumDurationForUserThisMonth(User $user): int;
45
46	/**
47	* Most-recent N done sessions for the user (with project relation eager
48	* loaded). Ordered newest first.
49	*
50	* @return Collection<int, RolePlayConversations>
51	*/
52	public function recentDoneForUser(User $user, int $limit = 5): Collection;
53	}