1package repository
2
3import (
4 "context"
5 "time"
6
7 "github.com/bnema/dumber/internal/domain/entity"
8)
9
10// HistoryScope constrains a history query to an optional age window. Cutoff is
11// the inclusive lower bound for an entry's last_visited timestamp. The zero
12// time disables age filtering, so all stored history is eligible.
13type HistoryScope struct {
14 Cutoff time.Time
15}
16
17// HistoryRepository defines operations for browsing history persistence.
18type HistoryRepository interface {
19 // Save creates or updates a history entry (upsert).
20 Save(ctx context.Context, entry *entity.HistoryEntry) error
21
22 // FindByURL retrieves a history entry by its URL.
23 FindByURL(ctx context.Context, url string) (*entity.HistoryEntry, error)
24
25 // Search performs a fuzzy search on history entries. Results older than
26 // scope.Cutoff are excluded in SQL before the result limit is applied. A
27 // non-positive limit returns no matches.
28 Search(ctx context.Context, query string, limit int, scope HistoryScope) ([]entity.HistoryMatch, error)
29
30 // GetRecent retrieves recent history entries with pagination. A non-positive
31 // limit means all entries. Results older than scope.Cutoff are excluded in
32 // SQL before the limit is applied.
33 GetRecent(ctx context.Context, limit, offset int, scope HistoryScope) ([]*entity.HistoryEntry, error)
34
35 // GetRecentByDomain retrieves recent history entries for a domain with pagination. A zero limit means all matching entries.
36 GetRecentByDomain(ctx context.Context, domain string, limit, offset int) ([]*entity.HistoryEntry, error)
37
38 // GetRecentWindow retrieves entries older than the stable (last_visited, id) cursor, sorted by recency.
39 GetRecentWindow(ctx context.Context, before time.Time, beforeID int64, limit int) ([]*entity.HistoryEntry, error)
40
41 // GetRecentWindowByDomain retrieves domain entries older than the stable (last_visited, id) cursor, sorted by recency.
42 GetRecentWindowByDomain(ctx context.Context, domain string, before time.Time, beforeID int64, limit int) ([]*entity.HistoryEntry, error)
43
44 // GetRecentSince retrieves history entries visited within the last N days.
45 // days must be > 0.
46 GetRecentSince(ctx context.Context, days int) ([]*entity.HistoryEntry, error)
47
48 // GetMostVisited retrieves history entries sorted by visit count within the last N days.
49 // days must be > 0.
50 GetMostVisited(ctx context.Context, days int) ([]*entity.HistoryEntry, error)
51
52 // GetMostVisitedWithin retrieves history entries ordered by visit count,
53 // optionally restricted to scope.Cutoff and capped by limit in SQL. A
54 // non-positive limit returns an empty slice.
55 GetMostVisitedWithin(ctx context.Context, limit int, scope HistoryScope) ([]*entity.HistoryEntry, error)
56
57 // GetAllRecentHistory retrieves all history entries sorted by recency.
58 GetAllRecentHistory(ctx context.Context) ([]*entity.HistoryEntry, error)
59
60 // GetAllMostVisited retrieves all history entries sorted by visit count.
61 GetAllMostVisited(ctx context.Context) ([]*entity.HistoryEntry, error)
62
63 // IncrementVisitCount increments the visit count for a URL.
64 IncrementVisitCount(ctx context.Context, url string) error
65
66 // Delete removes a single history entry by ID.
67 Delete(ctx context.Context, id int64) error
68
69 // DeleteOlderThan removes entries older than the given time.
70 DeleteOlderThan(ctx context.Context, before time.Time) error
71
72 // DeleteSince removes entries visited at or after the given time.
73 DeleteSince(ctx context.Context, since time.Time) error
74
75 // DeleteAll removes all history entries.
76 DeleteAll(ctx context.Context) error
77
78 // DeleteByDomain removes all history entries for a domain.
79 DeleteByDomain(ctx context.Context, domain string) error
80
81 // GetStats retrieves overall history statistics.
82 GetStats(ctx context.Context) (*entity.HistoryStats, error)
83
84 // GetDomainStats retrieves per-domain statistics.
85 GetDomainStats(ctx context.Context, limit int) ([]*entity.DomainStat, error)
86
87 // GetHourlyDistribution retrieves hourly visit distribution.
88 GetHourlyDistribution(ctx context.Context) ([]*entity.HourlyDistribution, error)
89
90 // GetDailyVisitCount retrieves daily visit counts for the given period.
91 GetDailyVisitCount(ctx context.Context, daysAgo string) ([]*entity.DailyVisitCount, error)
92}