1package repository
2
3import (
4 "context"
5 "time"
6
7 "github.com/bnema/dumber/internal/domain/entity"
8)
9
10// HistoryRepository defines operations for browsing history persistence.
11type HistoryRepository interface {
12 // Save creates or updates a history entry (upsert).
13 Save(ctx context.Context, entry *entity.HistoryEntry) error
14
15 // FindByURL retrieves a history entry by its URL.
16 FindByURL(ctx context.Context, url string) (*entity.HistoryEntry, error)
17
18 // Search performs a fuzzy search on history entries.
19 Search(ctx context.Context, query string, limit int) ([]entity.HistoryMatch, error)
20
21 // GetRecent retrieves recent history entries with pagination. A zero limit means all entries.
22 GetRecent(ctx context.Context, limit, offset int) ([]*entity.HistoryEntry, error)
23
24 // GetRecentByDomain retrieves recent history entries for a domain with pagination. A zero limit means all matching entries.
25 GetRecentByDomain(ctx context.Context, domain string, limit, offset int) ([]*entity.HistoryEntry, error)
26
27 // GetRecentWindow retrieves entries older than the stable (last_visited, id) cursor, sorted by recency.
28 GetRecentWindow(ctx context.Context, before time.Time, beforeID int64, limit int) ([]*entity.HistoryEntry, error)
29
30 // GetRecentWindowByDomain retrieves domain entries older than the stable (last_visited, id) cursor, sorted by recency.
31 GetRecentWindowByDomain(ctx context.Context, domain string, before time.Time, beforeID int64, limit int) ([]*entity.HistoryEntry, error)
32
33 // GetRecentSince retrieves history entries visited within the last N days.
34 // days must be > 0.
35 GetRecentSince(ctx context.Context, days int) ([]*entity.HistoryEntry, error)
36
37 // GetMostVisited retrieves history entries sorted by visit count within the last N days.
38 // days must be > 0.
39 GetMostVisited(ctx context.Context, days int) ([]*entity.HistoryEntry, error)
40
41 // GetAllRecentHistory retrieves all history entries sorted by recency.
42 GetAllRecentHistory(ctx context.Context) ([]*entity.HistoryEntry, error)
43
44 // GetAllMostVisited retrieves all history entries sorted by visit count.
45 GetAllMostVisited(ctx context.Context) ([]*entity.HistoryEntry, error)
46
47 // IncrementVisitCount increments the visit count for a URL.
48 IncrementVisitCount(ctx context.Context, url string) error
49
50 // Delete removes a single history entry by ID.
51 Delete(ctx context.Context, id int64) error
52
53 // DeleteOlderThan removes entries older than the given time.
54 DeleteOlderThan(ctx context.Context, before time.Time) error
55
56 // DeleteSince removes entries visited at or after the given time.
57 DeleteSince(ctx context.Context, since time.Time) error
58
59 // DeleteAll removes all history entries.
60 DeleteAll(ctx context.Context) error
61
62 // DeleteByDomain removes all history entries for a domain.
63 DeleteByDomain(ctx context.Context, domain string) error
64
65 // GetStats retrieves overall history statistics.
66 GetStats(ctx context.Context) (*entity.HistoryStats, error)
67
68 // GetDomainStats retrieves per-domain statistics.
69 GetDomainStats(ctx context.Context, limit int) ([]*entity.DomainStat, error)
70
71 // GetHourlyDistribution retrieves hourly visit distribution.
72 GetHourlyDistribution(ctx context.Context) ([]*entity.HourlyDistribution, error)
73
74 // GetDailyVisitCount retrieves daily visit counts for the given period.
75 GetDailyVisitCount(ctx context.Context, daysAgo string) ([]*entity.DailyVisitCount, error)
76}