Documentation
¶
Index ¶
- Constants
- Variables
- func AttachReading(ctx context.Context, db bun.IDB, userID int, books []*models.Book) error
- func DetachBooks(ctx context.Context, db bun.IDB, bookIDs []int) error
- func DetachLibraryBooks(ctx context.Context, db bun.IDB, libraryID int) error
- func LastFinishedDayExpr(userID int, bookIDColumn string) string
- func LastReadExpr(userID int, bookIDColumn string) string
- func MergeBooks(ctx context.Context, db bun.IDB, sourceBookID, targetBookID int) error
- func RatingStars(units *int) *float64
- func RatingUnits(stars float64) (int, bool)
- func RatingUnitsExpr(userID int, bookIDColumn string) string
- func RegisterRoutes(g *echo.Group, db *bun.DB)
- func StatusExpr(userID int, bookIDColumn string) string
- func StatusRankExpr(userID int, bookIDColumn string) string
- func UnderwayFilterExpr(userID int, bookIDColumn string) string
- func UnderwayOrderExpr(userID int, bookIDColumn string) string
- type BookReading
- type BookReadingResponse
- type DayPayload
- type DeviceStatus
- type FilePositionResponse
- type Filter
- type HistoryOptions
- type ListReadingHistoryQuery
- type ListReadingHistoryResponse
- type ListReadingStatsFinishedQuery
- type ListReadingStatsFinishedResponse
- type PageRow
- type PositionUpdate
- type ReadThroughChangeResponse
- type ReadThroughEntry
- type ReadThroughSession
- type ReadThroughSessionsResponse
- type ReadingHistoryBook
- type ReadingHistoryEntry
- type ReadingStatsBookRef
- type ReadingStatsCalendarDay
- type ReadingStatsCalendarDayBook
- type ReadingStatsCalendarQuery
- type ReadingStatsCalendarResponse
- type ReadingStatsCount
- type ReadingStatsDay
- type ReadingStatsDayQuery
- type ReadingStatsDayResponse
- type ReadingStatsDaySession
- type ReadingStatsFinishedBook
- type ReadingStatsHeatmapQuery
- type ReadingStatsHeatmapResponse
- type ReadingStatsKindCount
- type ReadingStatsPeriod
- type ReadingStatsPlace
- type ReadingStatsQuery
- type ReadingStatsRatingCount
- type ReadingStatsResponse
- type ReadingStatsTotals
- type ReorderToReadPayload
- type ReportedStatus
- type Service
- func (svc *Service) AddToRead(ctx context.Context, userID, bookID int) error
- func (svc *Service) AppendToRead(ctx context.Context, userID int, bookIDs []int) (int, error)
- func (svc *Service) BookLibraryID(ctx context.Context, bookID int) (int, error)
- func (svc *Service) BuildHistoryEntries(ctx context.Context, user *models.User, readThroughs []*models.ReadThrough) ([]*ReadingHistoryEntry, error)
- func (svc *Service) ChangedSince(ctx context.Context, userID int, since time.Time) ([]int, error)
- func (svc *Service) DeleteReadThrough(ctx context.Context, rt *models.ReadThrough) error
- func (svc *Service) DeleteSession(ctx context.Context, userID, id int) (bool, error)
- func (svc *Service) DeviceUpdatedSince(ctx context.Context, deviceID string, since time.Time) (bool, error)
- func (svc *Service) End(ctx context.Context, userID, bookID int, outcome, today string) error
- func (svc *Service) EndReadThrough(ctx context.Context, rt *models.ReadThrough, outcome, today string) error
- func (svc *Service) FileLibraryID(ctx context.Context, fileID int) (int, error)
- func (svc *Service) FillRating(ctx context.Context, userID, bookID, units int) error
- func (svc *Service) GroupHeldRows(ctx context.Context, userID int, deviceID, document string, fileID int, ...) error
- func (svc *Service) KeepFinished(ctx context.Context, userID, fileID int) error
- func (svc *Service) ListHistory(ctx context.Context, userID int, opts HistoryOptions) ([]*models.ReadThrough, int, error)
- func (svc *Service) Location(ctx context.Context, userID int) (*time.Location, error)
- func (svc *Service) ReadThroughSessions(ctx context.Context, userID, readThroughID int) (*ReadThroughSessionsResponse, error)
- func (svc *Service) RecordEstimatedSession(ctx context.Context, userID, fileID int, source string, session SessionInput) (int, error)
- func (svc *Service) RecordHistoryStatus(ctx context.Context, s DeviceStatus) error
- func (svc *Service) RecordPageRows(ctx context.Context, userID int, deviceID string, fileID *int, rows []PageRow, ...) error
- func (svc *Service) RecordSession(ctx context.Context, userID, fileID int, source string, session SessionInput) (int, error)
- func (svc *Service) RemoveFromToRead(ctx context.Context, userID, bookID int) error
- func (svc *Service) ReorderToRead(ctx context.Context, userID int, bookIDs []int) error
- func (svc *Service) RetrieveBookReading(ctx context.Context, userID, bookID int) (*BookReading, error)
- func (svc *Service) RetrievePosition(ctx context.Context, userID, fileID int) (*models.ReadingPosition, error)
- func (svc *Service) RetrievePositions(ctx context.Context, userID int, fileIDs []int) (map[int]*models.ReadingPosition, error)
- func (svc *Service) RetrieveReadThrough(ctx context.Context, userID, id int) (*models.ReadThrough, error)
- func (svc *Service) RetrieveStatusSummaries(ctx context.Context, userID int, bookIDs []int) (map[int]*StatusSummary, error)
- func (svc *Service) RetrieveWebReaderPosition(ctx context.Context, userID, fileID int) (*models.ReadingPosition, error)
- func (svc *Service) SetDeviceStatus(ctx context.Context, s DeviceStatus) error
- func (svc *Service) SetEstimatedSessionEnd(ctx context.Context, userID, id int, endedAt time.Time, endPercentage float64) error
- func (svc *Service) SetPageFlow(ctx context.Context, userID, bookID int, flow *string) error
- func (svc *Service) SetPaused(ctx context.Context, userID, bookID int, paused bool) error
- func (svc *Service) SetRating(ctx context.Context, userID, bookID int, units *int) error
- func (svc *Service) Start(ctx context.Context, userID, bookID int, today string) error
- func (svc *Service) Stats(ctx context.Context, user *models.User, year *int) (*ReadingStatsResponse, error)
- func (svc *Service) StatsCalendar(ctx context.Context, user *models.User, year, month int) (*ReadingStatsCalendarResponse, error)
- func (svc *Service) StatsDay(ctx context.Context, user *models.User, day string) (*ReadingStatsDayResponse, error)
- func (svc *Service) StatsFinished(ctx context.Context, user *models.User, opts StatsFinishedOptions) (*ListReadingStatsFinishedResponse, error)
- func (svc *Service) StatsHeatmap(ctx context.Context, user *models.User, year *int) (*ReadingStatsHeatmapResponse, error)
- func (svc *Service) ToReadPlace(ctx context.Context, userID, bookID int, libraryIDs []int) (int, error)
- func (svc *Service) UndoAutoFinish(ctx context.Context, rt *models.ReadThrough) error
- func (svc *Service) UpdatePosition(ctx context.Context, u PositionUpdate) (*UpdatePositionResponse, error)
- func (svc *Service) UpdateReadThroughDays(ctx context.Context, rt *models.ReadThrough, beginDay, endDay *string) error
- type SessionInput
- type SessionPayload
- type SetPageFlowPayload
- type SetRatingPayload
- type StatsFinishedOptions
- type StatusSummary
- type UpdatePositionPayload
- type UpdatePositionResponse
- type UpdateReadThroughPayload
Constants ¶
const ( // AudioStartSeconds is how much of one sitting of listening counts as real // progress: a minute of it, not a few seconds of checking what it sounds // like or a seek to somewhere later. AudioStartSeconds = 60.0 // AudioEndSeconds is how close to an audiobook's end counts as reaching // it, so end credits don't stop it being marked read. AudioEndSeconds = 60.0 )
const ( //tygo:emit export type ReadingStatsKind = typeof ReadingStatsKindEbook | typeof ReadingStatsKindComic | typeof ReadingStatsKindAudiobook | typeof ReadingStatsKindUnknown; ReadingStatsKindEbook = "ebook" ReadingStatsKindComic = "comic" ReadingStatsKindAudiobook = "audiobook" ReadingStatsKindUnknown = "unknown" )
Kinds of reading a finished Book is counted under on Reading Stats, from the Files its Read-through was read in.
const RevertWindow = 15 * time.Minute
RevertWindow is how soon after an automatic finish the next update for the File, back before the end, undoes the finish: someone who jumped to the end to check the back matter and went back hasn't finished.
const SessionGap = 10 * time.Minute
SessionGap is the longest stretch without reading inside one measured Reading Session. A longer one starts the next session.
Variables ¶
var ( ErrAlreadyUnderway = errors.New("a read-through is already underway") ErrNothingUnderway = errors.New("no read-through is underway") ErrAlreadyPaused = errors.New("the read-through is already paused") ErrNotPaused = errors.New("the read-through is not paused") )
The transitions return these when the Book's current Read-throughs don't allow them, which the handlers render as 422 invalid_state.
var ( ErrEndDayWhileUnderway = errors.New("a read-through underway has no end day") ErrEndBeforeBegin = errors.New("the end day is before the begin day") )
UpdateReadThroughDays returns these for days it rejects, which the handlers render as 422 validation_error.
var ErrFileNotFound = errors.New("file not found")
ErrFileNotFound is returned for a position update on a File that doesn't exist.
var ErrNotAutoFinished = errors.New("the read-through was not finished automatically")
ErrNotAutoFinished is returned for undoing a finish that a position update didn't make, or that was already undone. A finish the user chose is never undone this way.
var ErrReadThroughEnded = errors.New("the read-through has already ended")
ErrReadThroughEnded is returned for ending a Read-through that already ended, which the handlers render as 422 invalid_state.
var ErrReadThroughNotFound = errors.New("read-through not found")
ErrReadThroughNotFound is returned for a Read-through that doesn't exist or belongs to another user.
Functions ¶
func AttachReading ¶
AttachReading sets ReadingStatus, Rating, ReadingProgress, and LastReadAt on each Book to userID's. Only a listing served to userID may call it, since all are private.
func DetachBooks ¶ added in v0.8.0
DetachBooks copies the title and author names of each of bookIDs onto every user's Read-throughs of it, for a delete about to remove those Books. The delete clears the Read-throughs' Book, and the copy is how their users still recognise them (ADR 0015). Book deletes call it first, in the same transaction, and a library delete calls DetachLibraryBooks. A merge needs neither: MergeBooks moves the Read-throughs to the Book kept.
func DetachLibraryBooks ¶ added in v0.8.0
DetachLibraryBooks is DetachBooks for every Book in libraryID, for a library delete about to cascade to them.
func LastFinishedDayExpr ¶
LastFinishedDayExpr is the SQL expression for the end day of userID's latest finished Read-through of the Book whose id is in bookIDColumn, or NULL when no finished Read-through has an end day. bookIDColumn is interpolated as in StatusExpr.
func LastReadExpr ¶ added in v0.7.0
LastReadExpr is the SQL expression for when userID last read the Book in bookIDColumn: the latest update logged on the Read-through underway, or NULL with none, so activity from an earlier read or a look back at a finished Book doesn't count. Neither does a place a link opened, or reading a supplement, which isn't reading the Book. A File since deleted leaves its update's File empty, and that reading still happened. bookIDColumn is interpolated as in StatusExpr.
func MergeBooks ¶
MergeBooks moves every user's reading data from sourceBookID to targetBookID, for a merge that is about to delete the source. Run it in the transaction that deletes the source, before the delete cascades the source's rows away.
- The target keeps its Rating, To Read position, and Page flow, taking the source's where it has none.
- The source's Read-throughs move to the target. When both have one underway, they collapse into the target's, which takes the earlier begin day, stays paused only if both were, and remembers a To Read place either left.
- A user with a Read-through underway on the target afterwards has it off To Read.
func RatingStars ¶
RatingStars converts quarter-star units to stars, keeping nil as nil.
func RatingUnits ¶
RatingUnits converts stars to quarter-star units, reporting false for a value that isn't a quarter step from 0.25 to 5.
func RatingUnitsExpr ¶
RatingUnitsExpr is the SQL expression for userID's Rating, in quarter-star units, of the Book whose id is in bookIDColumn, or NULL when unrated. bookIDColumn is interpolated as in StatusExpr.
func RegisterRoutes ¶
RegisterRoutes registers the reading routes on a group the server has already configured with authentication and Books Read. Reading data is the caller's own, so every route acts only on the signed-in user's records and needs no further permission; each that names a Book or File checks its library access, except that a user's own Read-throughs can be edited, ended, and deleted after their Book is gone or out of reach. Every write is a POST, PATCH, PUT, or DELETE, which Demo Mode rejects.
func StatusExpr ¶
StatusExpr is the SQL expression for userID's Reading Status of the Book whose id is in bookIDColumn, or NULL when there is none. bookIDColumn is interpolated into the SQL, so it must be a column name or an integer literal from code, never request input. It is the one place the status is derived (ADR 0013), so listings that show, filter, or sort on it use this expression:
- A Read-through underway: currently_reading, or paused.
- Otherwise, on To Read: to_read.
- Otherwise, the latest ended Read-through: read or did_not_finish. Latest means the latest end day; undated ones rank below dated ones, and ties go to the one recorded last.
func StatusRankExpr ¶
StatusRankExpr is the SQL expression ranking userID's Reading Status of the Book whose id is in bookIDColumn, for sorting: Currently Reading 1, Paused 2, To Read 3, Read 4, Did Not Finish 5, and no status 6. bookIDColumn is interpolated as in StatusExpr.
func UnderwayFilterExpr ¶
UnderwayFilterExpr is the SQL condition that userID has a Read-through underway on the Book whose id is in bookIDColumn, interpolated as in StatusExpr.
func UnderwayOrderExpr ¶
UnderwayOrderExpr is the SQL ORDER BY for userID's Books underway, the Book whose id is in bookIDColumn: the ones being read before the paused ones, each most recently begun first. bookIDColumn is interpolated as in StatusExpr.
Types ¶
type BookReading ¶
type BookReading struct {
Status *string
RatingUnits *int
OnToRead bool
PageFlow *string
ReadThroughs []*models.ReadThrough
// Positions holds the Reading Position of each of the Book's Files that has one.
Positions []*models.ReadingPosition
// Progress is the Book's: see progressExpr.
Progress *float64
// LastReadAt is the Book's: see LastReadExpr.
LastReadAt *time.Time
}
BookReading is one user's reading record for one Book.
type BookReadingResponse ¶
type BookReadingResponse struct {
BookID int `json:"book_id"`
Status *string `json:"status" tstype:"ReadingStatus | null"`
Rating *float64 `json:"rating" tstype:"number | null"` // Stars, in quarter steps from 0.25 to 5
OnToRead bool `json:"on_to_read"`
ToReadPlace *int `json:"to_read_place" tstype:"number | null"` // 1-based place on To Read as the To Read page shows it, among Books in libraries the user can reach
ReadThroughs []*models.ReadThrough `json:"read_throughs" tstype:"ReadThrough[]"`
// SessionCounts is how many Reading Sessions each Read-through has, by
// its id.
SessionCounts map[int]int `json:"session_counts"`
PageFlow *string `json:"page_flow" tstype:"PageFlow | null"` // The flow chosen for the Page-based reader; null lets the reader pick
// Progress is how far through the Book the user is, from 0 to 1: the
// furthest of its main Files' positions, while a Read-through is underway.
Progress *float64 `json:"progress" tstype:"number | null"`
// Positions is the Reading Position of each of the Book's Files that has
// one, whatever its status. Progress is what says the Book is in progress.
Positions []*models.ReadingPosition `json:"positions" tstype:"ReadingPosition[]"`
// LastReadAt is the latest reading in the Read-through underway, on any of
// the Book's main Files. Null with nothing underway or no reading yet.
LastReadAt *time.Time `json:"last_read_at" tstype:"string | null"`
}
BookReadingResponse is the signed-in user's reading record for one Book: the derived Reading Status, every Read-through, the Rating, and whether and where the Book is on To Read. Read-throughs come newest first: the one underway, then ended ones by end day, undated ones last.
type DayPayload ¶
type DayPayload struct {
Today string `json:"today" validate:"required,date"`
}
DayPayload carries the user's "today" for a transition that dates a Read-through. It is the browser's local date, since a day is in the user's time zone.
type DeviceStatus ¶ added in v0.8.0
type DeviceStatus struct {
UserID int
// FileID is the File the device holds a copy of.
FileID int
// Status is ReadingStatusRead, ReadingStatusPaused, or
// ReadingStatusCurrentlyReading.
Status string
// Day is when the device set it, in the user's time zone.
Day string
}
DeviceStatus is a Reading Status a device's own reader set on purpose, as KOReader's finished, On hold, and reading are (ADR 0016), dated by the day it was set.
type FilePositionResponse ¶ added in v0.7.0
type FilePositionResponse struct {
Position *models.ReadingPosition `json:"position" tstype:"ReadingPosition | null,required"`
}
FilePositionResponse is the signed-in user's Reading Position in a File, or null when they have none. The wrapper keeps "no position yet" a 200 the reader can open at the start from, rather than an error.
type Filter ¶
Filter keeps the Books whose reader's Reading Status is any of Statuses, where models.ReadingStatusFilterNone matches Books with none, and that the reader rated within RatingMin and RatingMax stars, both ends included. Empty fields don't filter.
func (Filter) Apply ¶
func (f Filter) Apply(q *bun.SelectQuery, readerID int, bookIDColumn string) *bun.SelectQuery
Apply adds f, read from readerID's reading data, to q, whose Book id is in bookIDColumn, interpolated as in StatusExpr.
type HistoryOptions ¶ added in v0.8.0
HistoryOptions filters and pages ListHistory.
type ListReadingHistoryQuery ¶ added in v0.8.0
type ListReadingHistoryQuery struct {
Limit int `query:"limit" json:"limit,omitempty" default:"50" validate:"min=1,max=100"`
Offset int `query:"offset" json:"offset,omitempty" validate:"min=0"`
Outcome *string `query:"outcome" json:"outcome,omitempty" validate:"omitempty,oneof=underway finished abandoned" tstype:"ReadThroughOutcome"`
Removed bool `query:"removed" json:"removed,omitempty"`
}
ListReadingHistoryQuery pages through the signed-in user's Read-throughs for all time. Outcome keeps only Read-throughs with that outcome, and Removed only those whose Book was deleted.
type ListReadingHistoryResponse ¶ added in v0.8.0
type ListReadingHistoryResponse struct {
Items []*ReadingHistoryEntry `json:"items" tstype:"ReadingHistoryEntry[]"`
Total int `json:"total"`
}
ListReadingHistoryResponse is a page of Reading History, newest first.
type ListReadingStatsFinishedQuery ¶ added in v0.8.0
type ListReadingStatsFinishedQuery struct {
Year *int `query:"year" json:"year,omitempty" validate:"omitempty,min=1,max=9999"`
Genre *string `query:"genre" json:"genre,omitempty" validate:"omitempty,max=500"`
Tag *string `query:"tag" json:"tag,omitempty" validate:"omitempty,max=500"`
Author *string `query:"author" json:"author,omitempty" validate:"omitempty,max=500"`
Kind *string `query:"kind" json:"kind,omitempty" validate:"omitempty,oneof=ebook comic audiobook unknown" tstype:"ReadingStatsKind"`
Rating *float64 `query:"rating" json:"rating,omitempty" validate:"omitempty,min=0.25,max=5"`
Limit int `query:"limit" json:"limit,omitempty" default:"50" validate:"min=1,max=100"`
Offset int `query:"offset" json:"offset,omitempty" validate:"min=0"`
}
ListReadingStatsFinishedQuery pages through the finished Read-throughs on Reading Stats: those that ended in Year, or for all time when it's omitted. The other filters narrow it to what one row of a breakdown counts, and combine: a Genre, Tag, or author name (in any case), a kind, or a current Rating in stars. A detached Read-through has no Book to match any of them.
type ListReadingStatsFinishedResponse ¶ added in v0.8.0
type ListReadingStatsFinishedResponse struct {
Items []ReadingStatsFinishedBook `json:"items"`
Total int `json:"total"`
}
ListReadingStatsFinishedResponse is a page of the finished Read-throughs on Reading Stats, latest first.
type PageRow ¶ added in v0.8.0
type PageRow struct {
Document string
// Page is 1-based, out of TotalPages in the layout it was read in.
Page int
TotalPages int
// StartTime is the device's own Unix time, part of the row's key, and
// StartedAt the instant after correcting the device's clock.
StartTime int64
StartedAt time.Time
Duration int
}
PageRow is one visit to one page that a device timed, as KOReader's statistics record it (ADR 0016).
type PositionUpdate ¶ added in v0.7.0
type PositionUpdate struct {
UserID int
FileID int
Source string
// DeviceID is the Device that reported the update, when a Device did.
DeviceID *string
// ReportedDevice and ReportedDeviceID are how the source named itself,
// kept with the position.
ReportedDevice *string
ReportedDeviceID *string
// Locator holds the position in the one form the source reads.
Locator models.ReadingLocator
// PercentageOnly is a position with no locator, only Percentage, from a
// copy whose locators may not line up with the File's, such as one a
// user linked to it (ADR 0017). Readers open it at its percentage.
PercentageOnly bool
// LocatorFileType is the File Type of the copy Locator points into, when
// it isn't the File's own.
LocatorFileType *string
// Percentage is how far through the File the position is, from 0 to 1.
Percentage float64
// ChapterPercentage is how far through its chapter the position is, from
// 0 to 1, when the source says.
ChapterPercentage *float64
// ReportedStatus is a status the source reports outright.
ReportedStatus ReportedStatus
// AtEnd is the source reporting the end of the File, such as a
// reflowable reader's final location or playback ending, which finishes
// the Read-through underway. The last page and an audiobook's last
// minute count as the end whether or not the source says so.
AtEnd bool
// ListenedSeconds is how long a source timing audio has played in this
// sitting, including any session sent with the update. It's only for
// deciding that this sitting starts or resumes a Read-through.
ListenedSeconds float64
// ListeningSince is when this sitting of listening or reading began, for
// a source that knows. A sitting that starts a Read-through belongs to it
// from here, first minute included, and dates its begin day.
ListeningSince *time.Time
// Opened is a reader opened at this place by a link, such as a page
// thumbnail or a shared URL, which saves it as the place but isn't
// reading: it starts, resumes, finishes, and undoes nothing.
Opened bool
// OccurredAt is when the source was at the position, for an update
// sent later. Nil is now, and an instant after now counts as now.
OccurredAt *time.Time
// Session is a Reading Session the source finished, recorded with the
// update.
Session *SessionInput
}
PositionUpdate is one source reporting where a user is in a File. It is the single input of the position update service for every source: the web readers now, devices later.
type ReadThroughChangeResponse ¶ added in v0.8.0
type ReadThroughChangeResponse struct {
ReadThrough *models.ReadThrough `json:"read_through" tstype:"ReadThrough,required"`
Reading *BookReadingResponse `json:"reading" tstype:"BookReadingResponse | null,required"`
}
ReadThroughChangeResponse answers a change to one of the user's Read-throughs: the Read-through as the change left it (as it was, for a delete), and its Book's reading record, which is null when the Book was deleted or is in a library the user can no longer reach.
type ReadThroughEntry ¶ added in v0.8.0
type ReadThroughEntry struct {
ReadThrough *models.ReadThrough `json:"read_through" tstype:"ReadThrough,required"`
// Title and Authors are the Book's, or the copy kept when it was deleted.
Title string `json:"title"`
Authors []string `json:"authors"`
// Removed is true when the Book was deleted.
Removed bool `json:"removed"`
// Book is the Book when the user can still reach it: null when it was
// deleted or sits in a library they no longer have access to.
Book *ReadingHistoryBook `json:"book" tstype:"ReadingHistoryBook | null,required"`
}
ReadThroughEntry is one of the user's Read-throughs with what it takes to show it, wherever Read-throughs are listed.
type ReadThroughSession ¶ added in v0.8.0
type ReadThroughSession struct {
ID int `json:"id"`
StartedAt time.Time `json:"started_at"`
EndedAt time.Time `json:"ended_at"`
Seconds int `json:"seconds"`
StartPercentage float64 `json:"start_percentage"`
EndPercentage float64 `json:"end_percentage"`
Kind string `json:"kind" tstype:"ReadingKind"`
Source string `json:"source" tstype:"ReadingSource"`
// Measured is false for a Session its source estimated.
Measured bool `json:"measured"`
// DeviceID and DeviceName are the user's Device it came from, null for
// the web reader or a Device since deleted.
DeviceID *string `json:"device_id" tstype:"string | null,required"`
DeviceName *string `json:"device_name" tstype:"string | null,required"`
}
ReadThroughSession is one Reading Session of a Read-through. Seconds is the time it recorded, which can be less than its span.
type ReadThroughSessionsResponse ¶ added in v0.8.0
type ReadThroughSessionsResponse struct {
// TimeZone is the IANA zone to show the Sessions in: the user's, or UTC
// when they set none.
TimeZone string `json:"time_zone"`
Items []ReadThroughSession `json:"items"`
}
ReadThroughSessionsResponse is every Reading Session of one of the user's Read-throughs, in the order they started. It's every one, so it isn't paged.
type ReadingHistoryBook ¶ added in v0.8.0
type ReadingHistoryBook struct {
ID int `json:"id"`
LibraryID int `json:"library_id"`
CoverCacheKey string `json:"cover_cache_key"`
}
ReadingHistoryBook is what a Reading History row needs to link to its Book and show its cover.
type ReadingHistoryEntry ¶ added in v0.8.0
type ReadingHistoryEntry struct {
ReadThroughEntry `tstype:",extends"`
// CanReread is whether "Start a reread" applies: the user can reach the
// Book and has no Read-through of it underway.
CanReread bool `json:"can_reread"`
// SessionCount is how many Reading Sessions the Read-through has.
SessionCount int `json:"session_count"`
}
ReadingHistoryEntry is one Read-through on Reading History, with what it takes to show it.
type ReadingStatsBookRef ¶ added in v0.8.0
type ReadingStatsBookRef struct {
// Key stays the same for a Book in every month, so it can pick the
// Book's colour: "book-<id>"; once the Book is deleted, which keeps no
// link to it, "read-through-<id>" for each Read-through of it, or
// "session-<id>" for a Session with no Read-through to name it.
Key string `json:"key"`
Title string `json:"title"`
// Removed is true when the Book was deleted.
Removed bool `json:"removed"`
// Book is the Book when the user can still reach it: null when it was
// deleted or sits in a library they no longer have access to.
Book *ReadingHistoryBook `json:"book" tstype:"ReadingHistoryBook | null,required"`
}
ReadingStatsBookRef names a Book on the calendar and in a day's detail.
type ReadingStatsCalendarDay ¶ added in v0.8.0
type ReadingStatsCalendarDay struct {
Day string `json:"day"`
Books []ReadingStatsCalendarDayBook `json:"books"`
}
ReadingStatsCalendarDay is one day of the calendar and the Books on it.
type ReadingStatsCalendarDayBook ¶ added in v0.8.0
type ReadingStatsCalendarDayBook struct {
Key string `json:"key"`
Seconds int `json:"seconds"`
Finished bool `json:"finished"`
}
ReadingStatsCalendarDayBook is one Book on one calendar day: the Session time spent on it that day, and whether a Read-through of it finished that day. A Read-through logged by hand finishes with no time.
type ReadingStatsCalendarQuery ¶ added in v0.8.0
type ReadingStatsCalendarQuery struct {
Year int `query:"year" json:"year" validate:"required,min=1,max=9999"`
Month int `query:"month" json:"month" validate:"required,min=1,max=12"`
}
ReadingStatsCalendarQuery picks the month the Reading Stats calendar shows.
type ReadingStatsCalendarResponse ¶ added in v0.8.0
type ReadingStatsCalendarResponse struct {
Year int `json:"year"`
Month int `json:"month"`
// Books are every Book read or finished in the month, by title.
Books []ReadingStatsBookRef `json:"books"`
// Days are the days with anything on them, in order.
Days []ReadingStatsCalendarDay `json:"days"`
}
ReadingStatsCalendarResponse is one month of the Reading Stats calendar: each day with reading or a finish, and the Books on them. Days are in the user's time zone, and a Session that ran past midnight is on both days.
type ReadingStatsCount ¶ added in v0.8.0
ReadingStatsCount is how many finished Books fall under one name.
type ReadingStatsDay ¶ added in v0.8.0
type ReadingStatsDay struct {
Day string `json:"day"`
ReadingSeconds int `json:"reading_seconds"`
ListeningSeconds int `json:"listening_seconds"`
}
ReadingStatsDay is the Session time that fell on one day, in the user's time zone, for the Reading Stats heatmap.
type ReadingStatsDayQuery ¶ added in v0.8.0
type ReadingStatsDayQuery struct {
Day string `query:"day" json:"day" validate:"required,date"`
}
ReadingStatsDayQuery picks the day whose Sessions Reading Stats lists.
type ReadingStatsDayResponse ¶ added in v0.8.0
type ReadingStatsDayResponse struct {
Day string `json:"day"`
// TimeZone is the IANA zone the day is in: the user's, or UTC when
// they set none.
TimeZone string `json:"time_zone"`
Sessions []ReadingStatsDaySession `json:"sessions"`
Finished []ReadingStatsBookRef `json:"finished"`
}
ReadingStatsDayResponse is one day's Reading Sessions, in the user's time zone, and the Read-throughs finished that day.
type ReadingStatsDaySession ¶ added in v0.8.0
type ReadingStatsDaySession struct {
ID int `json:"id"`
Book ReadingStatsBookRef `json:"book"`
StartedAt time.Time `json:"started_at"`
EndedAt time.Time `json:"ended_at"`
Seconds int `json:"seconds"`
StartPercentage float64 `json:"start_percentage"`
EndPercentage float64 `json:"end_percentage"`
Kind string `json:"kind" tstype:"ReadingKind"`
Source string `json:"source" tstype:"ReadingSource"`
// Measured is false for a Session its source estimated.
Measured bool `json:"measured"`
// DeviceID and DeviceName are the user's Device it came from, null for
// the web reader or a Device since deleted.
DeviceID *string `json:"device_id" tstype:"string | null,required"`
DeviceName *string `json:"device_name" tstype:"string | null,required"`
}
ReadingStatsDaySession is one Reading Session that touched the day, in the order they started. StartedAt and EndedAt are the whole Session, which may begin the day before or end the day after; Seconds is its time on this day.
type ReadingStatsFinishedBook ¶ added in v0.8.0
type ReadingStatsFinishedBook struct {
ReadThroughEntry `tstype:",extends"`
// DaysTaken counts begin day to end day inclusively; null without both.
DaysTaken *int `json:"days_taken" tstype:"number | null,required"`
// Seconds is the Read-through's Session time; null with no Sessions.
Seconds *int `json:"seconds" tstype:"number | null,required"`
// Rating is the Book's current Rating in stars; null when unrated or
// the Book was deleted.
Rating *float64 `json:"rating" tstype:"number | null,required"`
}
ReadingStatsFinishedBook is one finished Read-through on Reading Stats.
type ReadingStatsHeatmapQuery ¶ added in v0.8.0
type ReadingStatsHeatmapQuery struct {
Year *int `query:"year" json:"year,omitempty" validate:"omitempty,min=1,max=9999"`
}
ReadingStatsHeatmapQuery picks the heatmap's year, or the last 12 months when Year is omitted.
type ReadingStatsHeatmapResponse ¶ added in v0.8.0
type ReadingStatsHeatmapResponse struct {
// Today is the user's today.
Today string `json:"today"`
// From and To are the heatmap's first and last days: the last 12 months
// up to Today, or the whole year asked for, the current one included.
From string `json:"from"`
To string `json:"to"`
// FirstDay is the earliest day the user read or began or ended a
// Read-through, however long ago, which the calendar goes back to. Null
// with no reading at all.
FirstDay *string `json:"first_day" tstype:"string | null,required"`
// Days are the days from From to To with Session time, in order.
Days []ReadingStatsDay `json:"days"`
}
ReadingStatsHeatmapResponse is the signed-in user's reading for a year, a day at a time, for the heatmap on Reading Stats' Calendar tab. Days are in the user's time zone, a Session past midnight split between both.
type ReadingStatsKindCount ¶ added in v0.8.0
type ReadingStatsKindCount struct {
Kind string `json:"kind" tstype:"ReadingStatsKind"`
Books int `json:"books"`
}
ReadingStatsKindCount is how many distinct finished Books were read as one kind. A Book read as two kinds counts under each.
type ReadingStatsPeriod ¶ added in v0.8.0
type ReadingStatsPeriod struct {
Year int `json:"year"`
// Month is 1 to 12, or null when the period is the whole year.
Month *int `json:"month" tstype:"number | null,required"`
Finished int `json:"finished"`
ReadingSeconds int `json:"reading_seconds"`
ListeningSeconds int `json:"listening_seconds"`
}
ReadingStatsPeriod is one month, or one year under all time.
type ReadingStatsPlace ¶ added in v0.8.0
type ReadingStatsPlace struct {
Source string `json:"source" tstype:"ReadingSource"`
DeviceName *string `json:"device_name" tstype:"string | null,required"`
ReadingSeconds int `json:"reading_seconds"`
ListeningSeconds int `json:"listening_seconds"`
}
ReadingStatsPlace is the time spent reading in one place: the Shisho reader, one of the user's Devices, or a Kobo or KOReader that is no longer a Device (DeviceName null).
type ReadingStatsQuery ¶ added in v0.8.0
type ReadingStatsQuery struct {
Year *int `query:"year" json:"year,omitempty" validate:"omitempty,min=1,max=9999"`
}
ReadingStatsQuery picks the range Reading Stats covers: one calendar year, or all time when Year is omitted.
type ReadingStatsRatingCount ¶ added in v0.8.0
type ReadingStatsRatingCount struct {
Rating float64 `json:"rating"` // Stars, in quarter steps from 0.25 to 5
Books int `json:"books"`
}
ReadingStatsRatingCount is how many finished Books have one Rating.
type ReadingStatsResponse ¶ added in v0.8.0
type ReadingStatsResponse struct {
// Year is the year covered, or null for all time.
Year *int `json:"year" tstype:"number | null,required"`
// Years are the years with any reading activity, newest first.
Years []int `json:"years"`
Totals ReadingStatsTotals `json:"totals"`
// Periods are the months of Year, or for all time each year from the
// first with activity to the last.
Periods []ReadingStatsPeriod `json:"periods"`
// Genres, Tags, and Authors count the distinct finished Books under each
// name. A Book whose Read-through was detached from it isn't counted; one
// in a library the user can no longer reach is, as Reading History still
// shows its title and authors.
// Each lists every name, most Books first, then by name.
Genres []ReadingStatsCount `json:"genres"`
Tags []ReadingStatsCount `json:"tags"`
Authors []ReadingStatsCount `json:"authors"`
Kinds []ReadingStatsKindCount `json:"kinds"`
// Ratings counts the finished Books at each current Rating, lowest
// first, each Book once.
Ratings []ReadingStatsRatingCount `json:"ratings"`
// Places is reading and listening time by where it happened, most first.
// The finished Read-throughs themselves page separately, through
// ListReadingStatsFinishedQuery.
Places []ReadingStatsPlace `json:"places"`
}
ReadingStatsResponse is the signed-in user's Reading Stats for one range. Session time is grouped into days in the user's time zone; Read-throughs count by the day they ended, as stored.
type ReadingStatsTotals ¶ added in v0.8.0
type ReadingStatsTotals struct {
// Finished counts finished Read-throughs, every reread included, and
// Rereads how many of those were of a Book already finished before.
Finished int `json:"finished"`
Rereads int `json:"rereads"`
DidNotFinish int `json:"did_not_finish"`
// ReadingSeconds and ListeningSeconds are Session time, estimated
// Sessions included.
ReadingSeconds int `json:"reading_seconds"`
ListeningSeconds int `json:"listening_seconds"`
// MedianDaysToFinish counts begin day to end day inclusively, over
// finished Read-throughs with both. Null with none.
MedianDaysToFinish *float64 `json:"median_days_to_finish" tstype:"number | null,required"`
// AverageRating is the mean current Rating, in stars, of the finished
// Books the user rated. Null with none.
AverageRating *float64 `json:"average_rating" tstype:"number | null,required"`
}
ReadingStatsTotals are the summary figures for the range.
type ReorderToReadPayload ¶
type ReorderToReadPayload struct {
BookIDs []int `json:"book_ids" validate:"required,min=1,max=500,dive,min=1"`
}
ReorderToReadPayload puts the named Books, all on To Read, in this order. Books on To Read it leaves out keep their places, so a page showing only the Books in libraries the user can reach can reorder those.
type ReportedStatus ¶ added in v0.7.0
type ReportedStatus int
ReportedStatus is a status a source reports outright, as a Kobo does, rather than one Shisho infers from the position.
const ( // ReportedNothing leaves the status to the position. ReportedNothing ReportedStatus = iota // ReportedReading is reading, wherever the position is: it starts or // resumes the Read-through as real progress would. ReportedReading // ReportedFinished is the Book finished. It ends the Read-through // underway, or records a finished one for a Book reading would start, // and unlike reaching the end, it's never undone. ReportedFinished )
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func NewService ¶
func (*Service) AddToRead ¶
AddToRead puts bookID at the end of userID's To Read. A Book already on To Read keeps its place. A Book with a Read-through underway is refused with ErrAlreadyUnderway: starting takes a Book off To Read, and its status would stay Currently Reading or Paused.
func (*Service) AppendToRead ¶
AppendToRead puts bookIDs at the end of userID's To Read in their order, skipping Books already on it and Books with a Read-through underway, and returns how many it added. The caller checks the user can reach each Book.
func (*Service) BookLibraryID ¶
BookLibraryID returns the library of bookID, or sql.ErrNoRows when there is no such Book.
func (*Service) BuildHistoryEntries ¶ added in v0.8.0
func (svc *Service) BuildHistoryEntries(ctx context.Context, user *models.User, readThroughs []*models.ReadThrough) ([]*ReadingHistoryEntry, error)
BuildHistoryEntries describes each of user's readThroughs as Reading History shows it. A Book in a library user can't reach shows only its title and authors.
func (*Service) ChangedSince ¶ added in v0.8.0
ChangedSince returns userID's Books whose Read-throughs or Rating changed after since. A deleted Read-through leaves nothing to find.
func (*Service) DeleteReadThrough ¶
DeleteReadThrough deletes rt: the Read-through no longer counts. Its position updates and Reading Sessions go with it. Deleting the one underway takes the Book back to before it started: its Reading Positions reset, and a Book that left To Read to start it returns to its place. A detached Read-through has no Book to take back.
func (*Service) DeleteSession ¶ added in v0.7.0
DeleteSession deletes userID's Reading Session id for good, one that turned out not to be reading, and reports whether there was one: another user's is never deleted. It's a plain delete, which KOReader sync relies on to keep a deleted Session from coming back.
func (*Service) DeviceUpdatedSince ¶ added in v0.7.0
func (svc *Service) DeviceUpdatedSince(ctx context.Context, deviceID string, since time.Time) (bool, error)
DeviceUpdatedSince reports whether deviceID sent an update that arrived at or after since.
func (*Service) End ¶
End ends the Read-through underway with outcome, dated the day the user last read it, in their time zone, or today when it has no activity. Finishing with nothing underway records a finished Read-through with no begin day ending today, for a Book read before the user tracked it; abandoning needs one underway. Either way the Book leaves To Read, so a queued Book marked read shows Read; adding it again afterwards plans a reread.
func (*Service) EndReadThrough ¶ added in v0.8.0
func (svc *Service) EndReadThrough(ctx context.Context, rt *models.ReadThrough, outcome, today string) error
EndReadThrough ends rt, which must be underway, with outcome, by the rules End follows: dated the day it was last read, or today. A detached Read-through has no Book to take off To Read. It refuses with ErrReadThroughEnded a Read-through that already ended.
func (*Service) FileLibraryID ¶ added in v0.7.0
FileLibraryID returns the library of fileID, or sql.ErrNoRows when there is no such File.
func (*Service) FillRating ¶ added in v0.8.0
FillRating sets userID's Rating of bookID to units, in quarter stars, from a device's history, only when the Book has none.
func (*Service) GroupHeldRows ¶ added in v0.8.0
func (svc *Service) GroupHeldRows(ctx context.Context, userID int, deviceID, document string, fileID int, history bool) error
GroupHeldRows makes the rows deviceID sent for a document Shisho didn't recognize, held ungrouped (RecordPageRows), rows of fileID, now that the copy is linked to it (ADR 0017), and groups them as if they had just arrived: either the ones from history, or the rest, so the caller can apply history's statuses between the two.
func (*Service) KeepFinished ¶ added in v0.8.0
KeepFinished makes a finish of the Book fileID belongs to that a position update made automatically one the reader chose, as when a device reports it finished after reaching the end, so going back no longer undoes it.
func (*Service) ListHistory ¶ added in v0.8.0
func (svc *Service) ListHistory(ctx context.Context, userID int, opts HistoryOptions) ([]*models.ReadThrough, int, error)
ListHistory returns a page of userID's Read-throughs for all time and how many match, newest first: the ones underway, then by end day, then by begin day, undated days last, then the latest recorded.
func (*Service) Location ¶ added in v0.8.0
Location is userID's time zone, which their days are in, or UTC when they have none.
func (*Service) ReadThroughSessions ¶ added in v0.8.0
func (svc *Service) ReadThroughSessions(ctx context.Context, userID, readThroughID int) (*ReadThroughSessionsResponse, error)
ReadThroughSessions lists userID's Reading Sessions of readThroughID, in the order they started. The caller checks the Read-through is theirs.
func (*Service) RecordEstimatedSession ¶ added in v0.7.0
func (svc *Service) RecordEstimatedSession(ctx context.Context, userID, fileID int, source string, session SessionInput) (int, error)
RecordEstimatedSession records session, which source estimated, for userID in fileID, returning its id.
func (*Service) RecordHistoryStatus ¶ added in v0.8.0
func (svc *Service) RecordHistoryStatus(ctx context.Context, s DeviceStatus) error
RecordHistoryStatus makes the Read-through a status from a device's history stands for, s, when the Book has none, so it makes at most one per Book: the device keeps no record of rereads, only the status a Book has now. It begins on the day of the Book's first Reading Session, or on s.Day when that's earlier or there's none, and a Read Book's ends on s.Day:
- Read records a finished Read-through, leaving the Book on To Read when it's there, since it's no newer than a reread queued since
- Paused records one underway, paused
- Currently Reading records one underway
Reading Sessions on no Read-through are then placed again by their time. A Book with a Read-through already has a record of its own, which history can't improve on, and a supplement isn't the Book, so neither changes.
func (*Service) RecordPageRows ¶ added in v0.8.0
func (svc *Service) RecordPageRows(ctx context.Context, userID int, deviceID string, fileID *int, rows []PageRow, history bool) error
RecordPageRows takes in rows of one document from deviceID for userID. Rows already taken in are ignored, including ones behind a session or Read-through the user has since deleted. When the document is a File (fileID), the new rows are grouped into measured Reading Sessions: a gap of more than SessionGap starts a new one, and rows next to a session from an earlier upload extend it. A new session is placed by its time: on the Read-through underway when it started, or none. One that's real progress in a Book never read, or on To Read, starts a Read-through on its own day, except in history: rows the device recorded before it began syncing, whose Read-throughs come only from its statuses (RecordHistoryStatus). Estimated sessions deviceID recorded in the File are deleted where a measured one overlaps them, so the same time isn't counted twice. Rows of a document Shisho doesn't recognize (fileID nil) are stored ungrouped and count toward nothing until something groups them.
func (*Service) RecordSession ¶ added in v0.7.0
func (svc *Service) RecordSession(ctx context.Context, userID, fileID int, source string, session SessionInput) (int, error)
RecordSession records a Reading Session a source finished without moving, such as a reader opened and closed where it was. It changes no Reading Position and no Read-through. It returns the File's Book.
func (*Service) RemoveFromToRead ¶
RemoveFromToRead takes bookID off userID's To Read, if it's there.
func (*Service) ReorderToRead ¶
ReorderToRead puts bookIDs in this order on userID's To Read. The Books it names move among the places they held, so Books it leaves out (in a library the user can no longer reach) keep theirs; ids not on To Read are ignored. Positions are renumbered from 1.
func (*Service) RetrieveBookReading ¶
func (svc *Service) RetrieveBookReading(ctx context.Context, userID, bookID int) (*BookReading, error)
RetrieveBookReading loads userID's reading record for bookID.
func (*Service) RetrievePosition ¶ added in v0.7.0
func (svc *Service) RetrievePosition(ctx context.Context, userID, fileID int) (*models.ReadingPosition, error)
RetrievePosition loads userID's Reading Position in fileID, or nil when there is none, in the form and copy its source wrote: a reader given it gets it through reflowable.Translate, as RetrieveWebReaderPosition does.
func (*Service) RetrievePositions ¶ added in v0.7.0
func (svc *Service) RetrievePositions(ctx context.Context, userID int, fileIDs []int) (map[int]*models.ReadingPosition, error)
RetrievePositions returns userID's Reading Positions in fileIDs, by File id, in the form and copy their sources wrote, as RetrievePosition does.
func (*Service) RetrieveReadThrough ¶
func (svc *Service) RetrieveReadThrough(ctx context.Context, userID, id int) (*models.ReadThrough, error)
RetrieveReadThrough loads one of userID's Read-throughs, returning ErrReadThroughNotFound when it doesn't exist or belongs to someone else.
func (*Service) RetrieveStatusSummaries ¶ added in v0.7.0
func (svc *Service) RetrieveStatusSummaries(ctx context.Context, userID int, bookIDs []int) (map[int]*StatusSummary, error)
RetrieveStatusSummaries returns userID's StatusSummary of each of bookIDs, by Book id.
func (*Service) RetrieveWebReaderPosition ¶ added in v0.7.0
func (svc *Service) RetrieveWebReaderPosition(ctx context.Context, userID, fileID int) (*models.ReadingPosition, error)
RetrieveWebReaderPosition loads userID's Reading Position in fileID as the web reader reads it, or nil when there is none. A reflowable position another reader wrote, such as KOReader's XPointer, comes as a CFI in the File's own copy, which is the one the web reader opens. One that can't be translated, as when the File can't be read, comes as it was stored.
func (*Service) SetDeviceStatus ¶ added in v0.8.0
func (svc *Service) SetDeviceStatus(ctx context.Context, s DeviceStatus) error
SetDeviceStatus applies a status a device set on purpose:
- Read finishes the Read-through underway, ending on Day, or records a finished one ending on Day when none is underway
- Paused pauses the Read-through underway, or starts one on Day and pauses it
- Currently Reading resumes the Read-through underway, or starts one on Day, which is a reread when the Book was read before
Reading Sessions on no Read-through are then placed again by their time, since sessions a device sent before the status may now belong to the Read-through it started or finished. A supplement isn't the Book, so its status changes nothing. The caller decides whether the status is new: a Read with nothing underway records another finished Read-through.
func (*Service) SetEstimatedSessionEnd ¶ added in v0.7.0
func (svc *Service) SetEstimatedSessionEnd(ctx context.Context, userID, id int, endedAt time.Time, endPercentage float64) error
SetEstimatedSessionEnd moves the end of userID's estimated Reading Session id, as its source learns more of it. Its duration stays its span.
func (*Service) SetPageFlow ¶
SetPageFlow saves the Page flow userID chose for bookID; nil clears it.
func (*Service) SetRating ¶
SetRating sets userID's Rating of bookID in quarter-star units, or clears it when units is nil.
func (*Service) Start ¶
Start begins a new Read-through on today, takes the Book off To Read, and resets the Book's Reading Positions so its readers open at the start. Reading a finished or abandoned Book again is the same transition.
func (*Service) Stats ¶ added in v0.8.0
func (svc *Service) Stats(ctx context.Context, user *models.User, year *int) (*ReadingStatsResponse, error)
Stats returns user's Reading Stats for year, or for all time when year is nil. Read-throughs count by the day they ended, as stored; Session time is grouped into days in the user's time zone.
func (*Service) StatsCalendar ¶ added in v0.8.0
func (svc *Service) StatsCalendar(ctx context.Context, user *models.User, year, month int) (*ReadingStatsCalendarResponse, error)
StatsCalendar returns one month of user's Reading Stats calendar: the Session time on each Book on each day, split at midnight in the user's time zone, and the days Read-throughs finished.
func (*Service) StatsDay ¶ added in v0.8.0
func (svc *Service) StatsDay(ctx context.Context, user *models.User, day string) (*ReadingStatsDayResponse, error)
StatsDay returns user's Reading Sessions that touched day in their time zone, in the order they started, and the Read-throughs finished that day.
func (*Service) StatsFinished ¶ added in v0.8.0
func (svc *Service) StatsFinished(ctx context.Context, user *models.User, opts StatsFinishedOptions) (*ListReadingStatsFinishedResponse, error)
StatsFinished returns a page of user's finished Read-throughs that ended in the year, or for all time, and match the filters, latest first, and how many there are.
func (*Service) StatsHeatmap ¶ added in v0.8.0
func (svc *Service) StatsHeatmap(ctx context.Context, user *models.User, year *int) (*ReadingStatsHeatmapResponse, error)
StatsHeatmap returns user's Session time on each day of year, or of the last 12 months when year is nil, in their time zone and split at local midnight, and the first day they read anything.
func (*Service) ToReadPlace ¶
func (svc *Service) ToReadPlace(ctx context.Context, userID, bookID int, libraryIDs []int) (int, error)
ToReadPlace returns bookID's 1-based place on userID's To Read, counting only Books in libraryIDs (nil for every library), as the To Read page lists them. Call it only for a Book on To Read.
func (*Service) UndoAutoFinish ¶ added in v0.7.0
UndoAutoFinish undoes the automatic finish of rt, for Undo on the finish toast, refusing with ErrNotAutoFinished a finish no position update made, and with ErrAlreadyUnderway when another Read-through is underway.
func (*Service) UpdatePosition ¶ added in v0.7.0
func (svc *Service) UpdatePosition(ctx context.Context, u PositionUpdate) (*UpdatePositionResponse, error)
UpdatePosition is the position update service. In one transaction it:
- ignores an update older than the stored position, recording only its session
- undoes the File's automatic finish when this is the next update back before the end, within RevertWindow, from the reader that finished it
- starts a Read-through when none is underway, the update is real progress, and the Book is unread or on To Read, taking it off To Read and resetting its other positions
- resumes a paused Read-through on real progress made since the pause
- finishes the Read-through underway on reaching the end, or on a reported finish, dated in the user's time zone
- stores the position, logs the update, and records the session, both on the Read-through underway or just finished
An update with no locator, a status reported on its own, changes the Read-through and stores nothing else, unless it's PercentageOnly.
func (*Service) UpdateReadThroughDays ¶
func (svc *Service) UpdateReadThroughDays(ctx context.Context, rt *models.ReadThrough, beginDay, endDay *string) error
UpdateReadThroughDays replaces both days of rt. Nil clears a day.
type SessionInput ¶ added in v0.7.0
type SessionInput struct {
StartedAt time.Time
EndedAt time.Time
StartPercentage float64
EndPercentage float64
// Measured is false for a session the source estimated.
Measured bool
// DeviceID is the Device that reported the session, when a Device did.
// A session sent with a position update takes the update's.
DeviceID *string
// Duration is the seconds the source counted, when it counted less than
// the span; more is taken as the span.
Duration *int
}
SessionInput is a finished Reading Session handed in with an update.
type SessionPayload ¶ added in v0.7.0
type SessionPayload struct {
StartedAt time.Time `json:"started_at" validate:"required"`
EndedAt time.Time `json:"ended_at" validate:"required"`
StartPercentage *float64 `json:"start_percentage" validate:"required,min=0,max=1" tstype:",required"`
EndPercentage *float64 `json:"end_percentage" validate:"required,min=0,max=1" tstype:",required"`
// Duration is the seconds the reader counted, which caps each page; none
// counts the whole span.
Duration *int `json:"duration,omitempty" validate:"omitempty,min=0"`
}
SessionPayload is a finished Reading Session the web reader timed.
type SetPageFlowPayload ¶
type SetPageFlowPayload struct {
PageFlow *string `json:"page_flow" validate:"omitempty,oneof=paginated scrolled" tstype:"PageFlow | null"`
}
SetPageFlowPayload saves the flow the Page-based reader uses for the Book. Null clears it, so the reader picks one from the page shapes again.
type SetRatingPayload ¶
type SetRatingPayload struct {
Rating *float64 `json:"rating" validate:"omitempty,min=0.25,max=5" tstype:"number | null"`
}
SetRatingPayload sets the Rating in stars, in quarter steps from 0.25 to 5. Null clears it.
type StatsFinishedOptions ¶ added in v0.8.0
type StatsFinishedOptions struct {
Year *int
Genre *string
Tag *string
Author *string
Kind *string
Rating *float64
Limit int
Offset int
}
StatsFinishedOptions picks the page of finished Read-throughs StatsFinished returns; see ListReadingStatsFinishedQuery for the filters. It mirrors that query field for field, so a handler converts one to it.
type StatusSummary ¶ added in v0.7.0
type StatusSummary struct {
BookID int `bun:"book_id"`
Status *string `bun:"status"`
// ReadThroughAt and UserBookAt are the latest changes to the Book's
// Read-throughs and its To Read place; ChangedAt is the later of them.
ReadThroughAt *time.Time `bun:"read_through_at"`
UserBookAt *time.Time `bun:"user_book_at"`
ChangedAt *time.Time `bun:"-"`
ReadThroughs int `bun:"read_throughs"`
// LastBeginDay is when the Read-through the status comes from began, or
// the latest one when none does, if it says, and LastBeganAt the start of
// that day in the user's time zone.
LastBeginDay *string `bun:"last_begin_day"`
LastBeganAt *time.Time `bun:"-"`
// RatingUnits is the Rating in quarter-star units, nil when unrated, and
// RatingAt when it was last set or cleared.
RatingUnits *int `bun:"rating"`
RatingAt *time.Time `bun:"rating_at"`
}
StatusSummary is one user's reading of one Book as a device that shows only a status needs it: the Reading Status, when it last changed, how many times the Book was read, and when the latest read began.
type UpdatePositionPayload ¶ added in v0.7.0
type UpdatePositionPayload struct {
CFI *string `json:"cfi,omitempty" validate:"omitempty,min=1,max=4096"`
Page *int `json:"page,omitempty" validate:"omitempty,min=0"`
Seconds *float64 `json:"seconds,omitempty" validate:"omitempty,min=0"`
// Percentage is required with a position.
Percentage *float64 `json:"percentage,omitempty" validate:"omitempty,min=0,max=1"`
// AtEnd is the reader at the end of the File, or playback ending, which
// finishes the Read-through underway.
AtEnd bool `json:"at_end,omitempty"`
// ListenedSeconds is how long the player has played in this sitting,
// including any session sent with the update. A minute of it starts or
// resumes a Read-through.
ListenedSeconds *float64 `json:"listened_seconds,omitempty" validate:"omitempty,min=0"`
// ListeningSince is when this sitting began: a Read-through it starts
// begins that day and takes what it already recorded. Out of range, more
// than a day ago or in the future, it's ignored.
ListeningSince *time.Time `json:"listening_since,omitempty"`
// Opened is the reader opened at this place by a link, which saves it as
// the place without counting as reading.
Opened bool `json:"opened,omitempty"`
// OccurredAt is when the reader was at the position, so an update that
// arrives late can't replace a newer one. Omitted is now.
OccurredAt *time.Time `json:"occurred_at,omitempty"`
Session *SessionPayload `json:"session,omitempty"`
}
UpdatePositionPayload is a web reader reporting where the user is in a File. It carries the position in the one form the reader keeps (a CFI for the ebook reader, a 0-based page for comics and PDFs, seconds for audiobooks), and optionally a Reading Session the reader just finished. A reader that hasn't moved since opening sends only the session, which changes no position or status.
type UpdatePositionResponse ¶ added in v0.7.0
type UpdatePositionResponse struct {
BookID int `json:"book_id"`
// Accepted is false for an update older than the saved position, or
// one that carried only a session: neither changed the position.
Accepted bool `json:"accepted"`
// Started is true when the update started a Read-through.
Started bool `json:"started"`
// Resumed is true when the update resumed a paused Read-through.
Resumed bool `json:"resumed"`
// Reverted is true when the update undid an automatic finish.
Reverted bool `json:"reverted"`
// FinishedReadThroughID is the Read-through the update finished, which
// the toast's Undo names.
FinishedReadThroughID *int `json:"finished_read_through_id" tstype:"number | null,required"`
}
UpdatePositionResponse says what a position update did, so the reader can show the finish toast. The update service returns it for every source.
type UpdateReadThroughPayload ¶
type UpdateReadThroughPayload struct {
BeginDay *string `json:"begin_day" validate:"omitempty,date" tstype:"string | null"`
EndDay *string `json:"end_day" validate:"omitempty,date" tstype:"string | null"`
}
UpdateReadThroughPayload replaces both days of a Read-through. Null clears a day. A Read-through still underway has no end day.