max / goingson

4.2 KB · 107 lines History Blame Raw

1	use super::{
2	ContactId, DateTime, Event, EventId, NaiveDate, NewEvent, ProjectId, Result, TaskId, UserId,
3	Utc, async_trait,
4	};
5
6	/// Repository for calendar event operations.
7	///
8	/// Events can be standalone or linked to tasks (for time-blocking).
9	///
10	/// # Ordering Contract
11	///
12	/// All methods returning `Vec<Event>` MUST return results sorted by
13	/// `start_time ASC`. This is enforced at the SQL level (`ORDER BY e.start_time ASC`)
14	/// and callers rely on this guarantee, no post-fetch sorting is needed.
15	#[async_trait]
16	pub trait EventRepository: Send + Sync {
17	/// Lists all events for a user, ordered by `start_time ASC`.
18	async fn list_all(&self, user_id: UserId) -> Result<Vec<Event>>;
19
20	/// Lists events belonging to a specific project, ordered by `start_time ASC`.
21	async fn list_by_project(&self, user_id: UserId, project_id: ProjectId) -> Result<Vec<Event>>;
22
23	/// Lists events linked to a specific contact, ordered by `start_time DESC`.
24	async fn list_by_contact(&self, user_id: UserId, contact_id: ContactId) -> Result<Vec<Event>>;
25
26	/// Retrieves an event by ID.
27	async fn get_by_id(&self, id: EventId, user_id: UserId) -> Result<Option<Event>>;
28
29	/// Creates a new event.
30	async fn create(&self, user_id: UserId, event: NewEvent) -> Result<Event>;
31
32	/// Restores an event verbatim from a backup, preserving its original ID and
33	/// all metadata the normal create path never sets, `block_type`,
34	/// `external_source`/`external_id`, `recurrence_parent_id`, `is_read_only`,
35	/// `snoozed_until`, and reminder offsets. Idempotent (`INSERT OR IGNORE`).
36	async fn restore(&self, user_id: UserId, event: &Event) -> Result<()>;
37
38	/// Updates an existing event.
39	async fn update(
40	&self,
41	id: EventId,
42	user_id: UserId,
43	event: crate::models::UpdateEvent,
44	) -> Result<Option<Event>>;
45
46	/// Deletes an event.
47	async fn delete(&self, id: EventId, user_id: UserId) -> Result<bool>;
48
49	/// Records the external source/id for an event (e.g. after an iCal import),
50	/// used to dedup on re-import.
51	async fn set_external_ref(
52	&self,
53	id: EventId,
54	user_id: UserId,
55	source: &str,
56	external_id: &str,
57	) -> Result<()>;
58
59	/// Deletes multiple events by ID, returning the number deleted.
60	async fn delete_many(&self, ids: &[EventId], user_id: UserId) -> Result<u64>;
61
62	/// Gets events starting within the next N days, ordered by `start_time ASC`.
63	async fn get_upcoming(&self, user_id: UserId, days: i64) -> Result<Vec<Event>>;
64
65	/// Finds the event linked to a specific task (for time-blocking).
66	async fn get_by_linked_task(&self, user_id: UserId, task_id: TaskId) -> Result<Option<Event>>;
67
68	/// Deletes the event linked to a task.
69	async fn delete_by_linked_task(&self, user_id: UserId, task_id: TaskId) -> Result<bool>;
70
71	/// Lists events occurring on a specific date, ordered by `start_time ASC`.
72	async fn list_for_date(&self, user_id: UserId, date: NaiveDate) -> Result<Vec<Event>>;
73
74	/// Lists events within a date range (for weekly review), ordered by `start_time ASC`.
75	async fn list_between(
76	&self,
77	user_id: UserId,
78	start: DateTime<Utc>,
79	end: DateTime<Utc>,
80	) -> Result<Vec<Event>>;
81
82	/// Lists all recurring events (recurrence != 'None' or recurrence_rule is set).
83	async fn list_recurring(&self, user_id: UserId) -> Result<Vec<Event>>;
84
85	/// Finds an event by external source and ID (for dedup during import).
86	async fn find_by_external_id(
87	&self,
88	source: &str,
89	ext_id: &str,
90	user_id: UserId,
91	) -> Result<Option<Event>>;
92
93	/// Snoozes an event until `until`. Returns the updated event, or `None` if not found.
94	async fn snooze(
95	&self,
96	id: EventId,
97	user_id: UserId,
98	until: DateTime<Utc>,
99	) -> Result<Option<Event>>;
100
101	/// Clears any snooze on an event. Returns the updated event, or `None` if not found.
102	async fn unsnooze(&self, id: EventId, user_id: UserId) -> Result<Option<Event>>;
103
104	/// Lists currently snoozed events (snoozed_until is in the future).
105	async fn list_snoozed(&self, user_id: UserId) -> Result<Vec<Event>>;
106	}
107