people

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterRoutes added in v0.1.0

func RegisterRoutes(g *echo.Group, db *bun.DB, authMiddleware *auth.Middleware, reviewRecomputer review.BookReviewRecomputer, fileOrganizer FileOrganizer)

RegisterRoutes registers people routes on a group the server has already configured with authentication and the resource's read permission. reviewRecomputer is required; pass a books service with app settings attached, or the delete handler's review recompute does nothing. fileOrganizer is optional and can be nil if file organization on person name change is not needed.

Types

type FileOrganizer

type FileOrganizer interface {
	// OrganizeBookFiles reorganizes files for a book with the given ID.
	// Returns error only for critical failures (database errors, etc.).
	// File system errors are logged but don't cause failure.
	OrganizeBookFiles(ctx context.Context, bookID int) error

	// RenameNarratedFile renames an M4B file to include the updated narrator name.
	// Returns the new path, or the original path if no rename was needed.
	RenameNarratedFile(ctx context.Context, fileID int) (string, error)

	// GetLibraryOrganizeSetting checks if a library has OrganizeFileStructure enabled.
	GetLibraryOrganizeSetting(ctx context.Context, libraryID int) (bool, error)
}

FileOrganizer defines the interface for organizing files when person metadata changes. This is used to break the import cycle between people and books packages.

type ListNarratedFilesResponse added in v0.0.47

type ListNarratedFilesResponse struct {
	Items []*models.File `json:"items" tstype:"File[]"`
	Total int            `json:"total"`
}

ListNarratedFilesResponse is the narrated-files sub-resource envelope.

type ListPeopleOptions

type ListPeopleOptions struct {
	Limit      *int
	Offset     *int
	LibraryID  *int
	LibraryIDs []int // Filter by multiple library IDs (for access control)
	ListID     *int  // Filter to authors of a book on this list
	// MainFileTypes keeps only people who author a book with a main file of
	// one of these types. Nil means no filter; an empty list matches no one.
	MainFileTypes []string
	Search        *string
	Sort          []sortspec.SortLevel // Defaults to name ascending
	// contains filtered or unexported fields
}

type ListPeopleQuery

type ListPeopleQuery struct {
	Limit     int     `query:"limit" json:"limit,omitempty" default:"24" validate:"min=1,max=100"`
	Offset    int     `query:"offset" json:"offset,omitempty" validate:"min=0"`
	LibraryID *int    `query:"library_id" json:"library_id,omitempty" validate:"omitempty,min=1" tstype:"number"`
	Search    *string `query:"search" json:"search,omitempty" validate:"omitempty,max=100" tstype:"string"`
	Sort      string  `query:"sort" json:"sort,omitempty" validate:"omitempty,max=200"`
}

type ListPeopleResponse added in v0.0.47

type ListPeopleResponse struct {
	Items []PersonListItem `json:"items"`
	Total int              `json:"total"`
}

ListPeopleResponse is the list-endpoint envelope.

type MergePeoplePayload

type MergePeoplePayload struct {
	SourceID int `json:"source_id" validate:"required,min=1"`
}

type PersonListItem added in v0.5.0

type PersonListItem struct {
	PersonResponse `tstype:",extends"`
	PreviewBooks   []bookpreviews.PreviewBook `json:"preview_books" tstype:"PreviewBook[]"`
}

PersonListItem is a person row of the list endpoint: the single-person response plus the covers the list shows for it.

type PersonResponse added in v0.0.47

type PersonResponse struct {
	models.Person     `tstype:",extends"`
	AuthoredBookCount int      `json:"authored_book_count"`
	NarratedFileCount int      `json:"narrated_file_count"`
	Aliases           []string `json:"aliases"`
}

PersonResponse is the single-person API response. It embeds the Person model by value (so tygo emits `extends Person`) and reshapes the aliases relation into a flat []string. AuthoredBookCount and NarratedFileCount are derived counts; Aliases shadows the embedded model's same-json-tag field, so the wire format is byte-identical to the previous anonymous struct.

type RetrievePersonOptions

type RetrievePersonOptions struct {
	ID        *int
	Name      *string
	LibraryID *int
}

type Service

type Service struct {
	// contains filtered or unexported fields
}

func NewService

func NewService(db *bun.DB) *Service

func (*Service) CleanupOrphanedPeople

func (svc *Service) CleanupOrphanedPeople(ctx context.Context) ([]int, error)

CleanupOrphanedPeople deletes people with no authors or narrators and returns the IDs of deleted people. Callers must pass the returned IDs to searchService.DeleteFromPersonIndex to keep persons_fts in sync — persons_fts is a virtual FTS5 table not tied to persons via foreign keys, so it is not cleaned up automatically.

func (*Service) CreatePerson

func (svc *Service) CreatePerson(ctx context.Context, person *models.Person) error

func (*Service) DeletePerson

func (svc *Service) DeletePerson(ctx context.Context, personID int) ([]int, error)

DeletePerson deletes a person and all their associations. Every book the person authored gets author_source = manual and every file the person narrated gets narrator_source = manual first, whatever the prior source was and even when other people remain, the same state the Edit form leaves after removing them. The delete is a deliberate user action, so an ordinary Scan must not bring the person back from a sidecar or the file, while Refresh all metadata and Reset to file metadata still may (ADR 0006). Only this service path is supported.

Returns the IDs of the books the person authored plus the books that own a file the person narrated, each once, so the caller can recompute their review state after the transaction commits.

func (*Service) FindOrCreatePerson

func (svc *Service) FindOrCreatePerson(ctx context.Context, name string, libraryID int) (*models.Person, error)

FindOrCreatePerson finds an existing person or creates a new one (case-insensitive match).

func (*Service) GetAuthoredBookCount

func (svc *Service) GetAuthoredBookCount(ctx context.Context, personID int) (int, error)

GetAuthoredBookCount returns the count of books authored by this person. A person has an author row per role on a book, so it counts distinct books.

func (*Service) GetAuthoredBooks

func (svc *Service) GetAuthoredBooks(ctx context.Context, personID int) ([]*models.Book, error)

GetAuthoredBooks returns all books authored by this person.

func (*Service) GetNarratedFileCount

func (svc *Service) GetNarratedFileCount(ctx context.Context, personID int) (int, error)

GetNarratedFileCount returns the count of files narrated by this person.

func (*Service) GetNarratedFiles

func (svc *Service) GetNarratedFiles(ctx context.Context, personID int) ([]*models.File, error)

GetNarratedFiles returns all files narrated by this person.

func (*Service) GetNarratedFilesPaginated added in v0.0.44

func (svc *Service) GetNarratedFilesPaginated(ctx context.Context, personID, limit, offset int) ([]*models.File, int, error)

GetNarratedFilesPaginated returns a paginated list of files narrated by this person.

func (*Service) ListPeople

func (svc *Service) ListPeople(ctx context.Context, opts ListPeopleOptions) ([]*models.Person, error)

func (*Service) ListPeopleWithTotal

func (svc *Service) ListPeopleWithTotal(ctx context.Context, opts ListPeopleOptions) ([]*models.Person, int, error)

func (*Service) MergePeople

func (svc *Service) MergePeople(ctx context.Context, targetID, sourceID int) error

MergePeople merges sourcePerson into targetPerson (moves all associations, transfers aliases, deletes source).

A Person cannot be merged into itself. Where the source and the target already author the same Book in the same role, or narrate the same File, the source's row is dropped instead of re-pointed, so the merge never violates ux_authors_book_person_role or ux_narrators_file_person and never lists the target twice.

func (*Service) RetrievePerson

func (svc *Service) RetrievePerson(ctx context.Context, opts RetrievePersonOptions) (*models.Person, error)

func (*Service) UpdatePerson

func (svc *Service) UpdatePerson(ctx context.Context, person *models.Person, opts UpdatePersonOptions) error

type SubResourceQuery added in v0.0.44

type SubResourceQuery struct {
	Limit  int `query:"limit" json:"limit,omitempty" default:"24" validate:"min=1,max=100"`
	Offset int `query:"offset" json:"offset,omitempty" validate:"min=0"`
}

type UpdatePersonOptions

type UpdatePersonOptions struct {
	Columns []string
}

type UpdatePersonPayload

type UpdatePersonPayload struct {
	Name     *string  `json:"name,omitempty" validate:"omitempty,max=300"`
	SortName *string  `json:"sort_name,omitempty" validate:"omitempty,max=300"`
	Aliases  []string `json:"aliases,omitempty" validate:"omitempty,dive,min=1,max=300"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址