ao3

package
v0.0.0-...-2b7ac24 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2025 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SortBestMatch   = "_score"
	SortAuthor      = "authors_to_sort_on"
	SortTitle       = "title_to_sort_on"
	SortDatePosted  = "created_at"
	SortDateUpdated = "revised_at"
	SortWordCount   = "word_count"
	SortRating      = "rating_ids"
	SortHits        = "hits"
	SortBookmarks   = "bookmarks_count"
	SortComments    = "comments_count"
	SortKudos       = "kudos_count"

	SortDirectionDescending = "desc"
	SortDirectionAscending  = "asc"
)

Constants for sorting

View Source 
const VERSION = "1.0.0"

VERSION is the current version of the AO3 API

Variables

View Source 
var (
	ErrLogin              = errors.New("login error")
	ErrUnloaded           = errors.New("unloaded error")
	ErrUnexpectedResponse = errors.New("unexpected response error")
	ErrInvalidID          = errors.New("invalid ID error")
	ErrDownload           = errors.New("download error")
	ErrAuth               = errors.New("authentication error")
	ErrDuplicateComment   = errors.New("duplicate comment error")
	ErrPseud              = errors.New("pseud error")
	ErrHTTP               = errors.New("HTTP error")
	ErrBookmark           = errors.New("bookmark error")
	ErrCollect            = errors.New("collect error")
)

Error types

View Source 
var DefaultRequester = NewRequester()

Global requester instance

Functions

func ExtractWorkID 

func ExtractWorkID(urlStr string) int

ExtractWorkID extracts the work ID from an AO3 URL using regex This is a simpler alternative to WorkIDFromURL

func FormatString 

func FormatString(s string) string

FormatString formats a string by removing commas

func ParseDocument 

func ParseDocument(content []byte) (*goquery.Document, error)

ParseDocument parses HTML content into a goquery document

func SetRateLimiting 

func SetRateLimiting(enable bool)

SetRateLimiting enables or disables rate limiting

func URLJoin 

func URLJoin(base string, parts ...string) string

URLJoin joins URL parts

func WithAnyField 

func WithAnyField(value string) func(*Search)

WithAnyField sets the any_field search parameter

func WithAuthor 

func WithAuthor(value string) func(*Search)

WithAuthor sets the author search parameter

func WithBookmarks 

func WithBookmarks(constraint *Constraint) func(*Search)

WithBookmarks sets the bookmarks search parameter

func WithCharacters 

func WithCharacters(value string) func(*Search)

WithCharacters sets the characters search parameter

func WithComments 

func WithComments(constraint *Constraint) func(*Search)

WithComments sets the comments search parameter

func WithCompletionStatus 

func WithCompletionStatus(value bool) func(*Search)

WithCompletionStatus sets the completion_status search parameter

func WithCrossovers 

func WithCrossovers(value bool) func(*Search)

WithCrossovers sets the crossovers search parameter

func WithExcludedTags 

func WithExcludedTags(value string) func(*Search)

WithExcludedTags sets the excluded_tags search parameter

func WithFandoms 

func WithFandoms(value string) func(*Search)

WithFandoms sets the fandoms search parameter

func WithHits 

func WithHits(constraint *Constraint) func(*Search)

WithHits sets the hits search parameter

func WithKudos 

func WithKudos(constraint *Constraint) func(*Search)

WithKudos sets the kudos search parameter

func WithLanguage 

func WithLanguage(value string) func(*Search)

WithLanguage sets the language search parameter

func WithPage 

func WithPage(value int) func(*Search)

WithPage sets the page search parameter

func WithRating 

func WithRating(value int) func(*Search)

WithRating sets the rating search parameter

func WithRelationships 

func WithRelationships(value string) func(*Search)

WithRelationships sets the relationships search parameter

func WithRevisedAt 

func WithRevisedAt(value string) func(*Search)

WithRevisedAt sets the revised_at search parameter

func WithSession 

func WithSession(session *Session) func(*Search)

WithSession sets the session for the search

func WithSingleChapter 

func WithSingleChapter(value bool) func(*Search)

WithSingleChapter sets the single_chapter search parameter

func WithSortColumn 

func WithSortColumn(value string) func(*Search)

WithSortColumn sets the sort_column search parameter

func WithSortDirection 

func WithSortDirection(value string) func(*Search)

WithSortDirection sets the sort_direction search parameter

func WithTags 

func WithTags(value string) func(*Search)

WithTags sets the tags search parameter

func WithTitle 

func WithTitle(value string) func(*Search)

WithTitle sets the title search parameter

func WithWordCount 

func WithWordCount(constraint *Constraint) func(*Search)

WithWordCount sets the word_count search parameter

func WordCount 

func WordCount(text string) int

WordCount counts the number of words in a text

func WorkIDFromURL 

func WorkIDFromURL(urlStr string) (int, error)

WorkIDFromURL extracts the work ID from an AO3 URL (supports both full and relative URLs)

Types

type Chapter 

type Chapter struct {
	ID                int
	Title             string
	Number            int
	Words             int
	Summary           string
	StartNotes        string
	EndNotes          string
	AuthenticityToken string
	// contains filtered or unexported fields
}

Chapter represents an AO3 chapter

func NewChapter 

func NewChapter(chapterID int, work *Work, session *Session, load bool) *Chapter

NewChapter creates a new Chapter object

func (*Chapter) Comment 

func (c *Chapter) Comment(commentText, email, name string, pseud *string) (*resty.Response, error)

Comment leaves a comment on this chapter

func (*Chapter) GetComments 

func (c *Chapter) GetComments(maximum *int) ([]*Comment, error)

GetComments returns a list of all threads of comments in the chapter

func (*Chapter) GetImages 

func (c *Chapter) GetImages() ([]ImageInfo, error)

GetImages gets all images from this chapter

func (*Chapter) GetText 

func (c *Chapter) GetText() (string, error)

GetText returns the text of this chapter

func (*Chapter) GetURL 

func (c *Chapter) GetURL() string

GetURL returns the URL to this chapter

func (*Chapter) GetWork 

func (c *Chapter) GetWork() *Work

GetWork returns the work this chapter is a part of

func (*Chapter) IsLoaded 

func (c *Chapter) IsLoaded() bool

IsLoaded returns true if this chapter has been loaded

func (*Chapter) Reload 

func (c *Chapter) Reload() error

Reload loads or reloads the chapter's information

func (*Chapter) SetSession 

func (c *Chapter) SetSession(session *Session)

SetSession sets the session used to make requests for this chapter

func (*Chapter) String 

func (c *Chapter) String() string

String returns a string representation of the chapter

type Comment 

type Comment struct {
	ID                int
	Text              string
	Author            *User
	AuthenticityToken string
	// contains filtered or unexported fields
}

Comment represents an AO3 comment

func NewComment 

func NewComment(commentID int, commentable interface{}, session *Session, load bool) *Comment

NewComment creates a new Comment object

func (*Comment) Delete 

func (c *Comment) Delete() error

Delete deletes this comment

func (*Comment) GetThread 

func (c *Comment) GetThread() ([]*Comment, error)

GetThread returns all comments in this thread

func (*Comment) IsLoaded 

func (c *Comment) IsLoaded() bool

IsLoaded returns true if this comment has been loaded

func (*Comment) Reload 

func (c *Comment) Reload() error

Reload loads or reloads the comment's information

func (*Comment) Reply 

func (c *Comment) Reply(commentText, email, name string, pseud *string) (*resty.Response, error)

Reply replies to this comment

func (*Comment) SetSession 

func (c *Comment) SetSession(session *Session)

SetSession sets the session used to make requests for this comment

func (*Comment) String 

func (c *Comment) String() string

String returns a string representation of the comment

type Constraint 

type Constraint struct {
	LowerBound int
	UpperBound *int
}

Constraint represents a numeric constraint (e.g., for word count)

func NewConstraint 

func NewConstraint(lowerBound int, upperBound *int) Constraint

NewConstraint creates a new constraint

func (Constraint) String 

func (c Constraint) String() string

String returns the string representation of the constraint

type GuestSession 

type GuestSession struct {
	IsAuthed          bool
	AuthenticityToken string
	Username          string
	// contains filtered or unexported fields
}

GuestSession represents an unauthenticated AO3 session

func NewGuestSession 

func NewGuestSession() *GuestSession

NewGuestSession creates a new guest session

func (*GuestSession) Comment 

func (s *GuestSession) Comment(commentable interface{}, commentText string, oneshot bool, commentID *int, email, name string) (*resty.Response, error)

Comment leaves a comment on a specific work or chapter

func (*GuestSession) Get 

func (s *GuestSession) Get(url string) (*resty.Response, error)

Get makes a GET request

func (*GuestSession) Kudos 

func (s *GuestSession) Kudos(work *Work) (bool, error)

Kudos leaves kudos on a work

func (*GuestSession) Post 

func (s *GuestSession) Post(url string, data url.Values) (*resty.Response, error)

Post makes a POST request

func (*GuestSession) RefreshAuthToken 

func (s *GuestSession) RefreshAuthToken() error

RefreshAuthToken refreshes the authenticity token

func (*GuestSession) Request 

func (s *GuestSession) Request(url string) (*goquery.Document, error)

Request makes a request and returns a goquery document

type ImageInfo 

type ImageInfo struct {
	URL     string
	LineNum int
}

ImageInfo represents an image in a chapter

type Query 

type Query struct {
	Fields []string
}

Query represents a URL query builder

func NewQuery 

func NewQuery() *Query

NewQuery creates a new query

func (*Query) AddField 

func (q *Query) AddField(field string)

AddField adds a field to the query

func (*Query) String 

func (q *Query) String() string

String returns the string representation of the query

type Requester 

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

Requester handles HTTP requests with rate limiting

func NewRequester 

func NewRequester() *Requester

NewRequester creates a new Requester with default settings

func (*Requester) Request 

func (r *Requester) Request(method, url string, cookies []*http.Cookie, headers map[string]string) (*resty.Response, error)

Request makes an HTTP request with rate limiting

func (*Requester) SetRequestsPerTimeWindow 

func (r *Requester) SetRequestsPerTimeWindow(num int)

SetRequestsPerTimeWindow sets the maximum number of requests per time window

func (*Requester) SetTimeWindow 

func (r *Requester) SetTimeWindow(d time.Duration)

SetTimeWindow sets the time window for rate limiting 

type Search struct {
	AnyField         string
	Title            string
	Author           string
	SingleChapter    bool
	WordCount        *Constraint
	Language         string
	Fandoms          string
	Characters       string
	Relationships    string
	Tags             string
	Rating           *int
	Hits             *Constraint
	Kudos            *Constraint
	Crossovers       *bool
	Bookmarks        *Constraint
	ExcludedTags     string
	Comments         *Constraint
	CompletionStatus *bool
	Page             int
	SortColumn       string
	SortDirection    string
	RevisedAt        string

	Results      []*Work
	TotalResults int
	Pages        int
	// contains filtered or unexported fields
}

Search represents an AO3 search

func NewSearch 

func NewSearch(options ...func(*Search)) *Search

NewSearch creates a new Search object

func (*Search) FetchPages 

func (s *Search) FetchPages(startPage, numPages int) ([]*Work, error)

FetchPages fetches multiple pages of search results and returns all works

func (*Search) Update 

func (s *Search) Update() error

Update sends a request to the AO3 website with the defined search parameters and updates all info

type Series 

type Series struct {
	ID                int
	Name              string
	URL               string
	Description       string
	WorkList          []*Work
	Authors           []*User
	AuthenticityToken string
	SubscriptionID    *int
	IsSubscribed      bool
	// contains filtered or unexported fields
}

Series represents an AO3 series

func NewSeries 

func NewSeries(seriesID int, session *Session, load bool) *Series

NewSeries creates a new Series object

func (*Series) Bookmark 

func (s *Series) Bookmark(notes string, tags, collections []string, private, recommend bool, pseud *string) error

Bookmark bookmarks this series

func (*Series) IsLoaded 

func (s *Series) IsLoaded() bool

IsLoaded returns true if this series has been loaded

func (*Series) Reload 

func (s *Series) Reload() error

Reload loads or reloads the series' information

func (*Series) SetSession 

func (s *Series) SetSession(session *Session)

SetSession sets the session used to make requests for this series

func (*Series) String 

func (s *Series) String() string

String returns a string representation of the series

func (*Series) Subscribe 

func (s *Series) Subscribe() error

Subscribe subscribes to this series

func (*Series) Unsubscribe 

func (s *Series) Unsubscribe() error

Unsubscribe unsubscribes from this series

type Session 

type Session struct {
	GuestSession
	// contains filtered or unexported fields
}

Session represents an authenticated AO3 session

func NewSession 

func NewSession(username, password string) (*Session, error)

NewSession creates a new authenticated session

func (*Session) ClearCache 

func (s *Session) ClearCache()

ClearCache clears the session's cache

func (*Session) GetBookmarkCount 

func (s *Session) GetBookmarkCount() (int, error)

GetBookmarkCount returns the number of bookmarks

func (*Session) GetBookmarkPages 

func (s *Session) GetBookmarkPages() (int, error)

GetBookmarkPages returns the number of bookmark pages

func (*Session) GetBookmarks 

func (s *Session) GetBookmarks(useThreading bool) ([]*Work, error)

GetBookmarks returns all bookmarks

func (*Session) GetMarkedForLater 

func (s *Session) GetMarkedForLater(sleep time.Duration, timeoutSleep time.Duration) ([]*Work, error)

GetMarkedForLater returns works marked for later

func (*Session) GetSeriesSubscriptions 

func (s *Session) GetSeriesSubscriptions(useThreading bool) ([]*Series, error)

GetSeriesSubscriptions returns the series subscriptions

func (*Session) GetStatistics 

func (s *Session) GetStatistics(year *int) (map[string]int, error)

GetStatistics returns user statistics

func (*Session) GetSubscriptions 

func (s *Session) GetSubscriptions(useThreading bool) ([]interface{}, error)

GetSubscriptions returns all subscriptions

func (*Session) GetUser 

func (s *Session) GetUser() *User

GetUser returns the user associated with this session

func (*Session) GetUserSubscriptions 

func (s *Session) GetUserSubscriptions(useThreading bool) ([]*User, error)

GetUserSubscriptions returns the user subscriptions

func (*Session) GetWorkSubscriptions 

func (s *Session) GetWorkSubscriptions(useThreading bool) ([]*Work, error)

GetWorkSubscriptions returns the work subscriptions

type SessionInterface 

type SessionInterface interface {
	Request(url string) (*goquery.Document, error)
	Get(url string) (*resty.Response, error)
}

SessionInterface defines the common methods between Session and GuestSession

func GetSessionInterface 

func GetSessionInterface(session interface{}) SessionInterface

GetSessionInterface returns a SessionInterface from either a Session or GuestSession

type SimpleWorkInfo 

type SimpleWorkInfo struct {
	ID       int
	Title    string
	Author   string
	Chapters int
	Words    int
	Kudos    int
	Hits     int
	Summary  string
	Fandoms  []string
	Tags     []string
}

SimpleWorkInfo represents basic information about an AO3 work

func GetSimpleWorkInfo 

func GetSimpleWorkInfo(workID int) (*SimpleWorkInfo, error)

GetSimpleWorkInfo gets basic information about a work without using the full Work struct

type User 

type User struct {
	Username          string
	URL               string
	Bio               string
	Works             int
	AuthenticityToken string
	SubscriptionID    *int
	IsSubscribed      bool
	// contains filtered or unexported fields
}

User represents an AO3 user

func NewUser 

func NewUser(username string, session *Session, load bool) *User

NewUser creates a new User object

func (*User) IsLoaded 

func (u *User) IsLoaded() bool

IsLoaded returns true if this user has been loaded

func (*User) Reload 

func (u *User) Reload() error

Reload loads or reloads the user's information

func (*User) SetSession 

func (u *User) SetSession(session *Session)

SetSession sets the session used to make requests for this user

func (*User) String 

func (u *User) String() string

String returns a string representation of the user

func (*User) Subscribe 

func (u *User) Subscribe() error

Subscribe subscribes to this user

func (*User) Unsubscribe 

func (u *User) Unsubscribe() error

Unsubscribe unsubscribes from this user

type Work 

type Work struct {
	ID                int
	Title             string
	Authors           []*User
	Chapters          []*Chapter
	Series            []*Series
	Nchapters         int
	ExpectedChapters  *int
	Hits              int
	Kudos             int
	Comments          int
	Bookmarks         int
	Words             int
	Language          string
	Restricted        bool
	Complete          bool
	DatePublished     time.Time
	DateEdited        time.Time
	DateUpdated       time.Time
	Tags              []string
	Characters        []string
	Relationships     []string
	Fandoms           []string
	Categories        []string
	Warnings          []string
	Rating            string
	Summary           string
	StartNotes        string
	EndNotes          string
	Collections       []string
	Recommended       bool
	BookmarkID        *int
	AuthenticityToken string
	SubscriptionID    *int
	IsSubscribed      bool
	// contains filtered or unexported fields
}

Work represents an AO3 work

func NewWork 

func NewWork(workID int, session interface{}, load bool, loadChapters bool) *Work

NewWork creates a new Work object

func (*Work) Bookmark 

func (w *Work) Bookmark(notes string, tags, collections []string, private, recommend bool, pseud *string) error

Bookmark bookmarks this work

func (*Work) Collect 

func (w *Work) Collect(collections []string) error

Collect invites/collects this work to collections

func (*Work) Comment 

func (w *Work) Comment(commentText, email, name string, pseud *string) (*resty.Response, error)

Comment leaves a comment on this work

func (*Work) DeleteBookmark 

func (w *Work) DeleteBookmark() error

DeleteBookmark removes a bookmark from this work

func (*Work) Download 

func (w *Work) Download(filetype string) ([]byte, error)

Download downloads this work in the specified format

func (*Work) DownloadToFile 

func (w *Work) DownloadToFile(filename string, filetype string) error

DownloadToFile downloads this work and saves it to a file

func (*Work) GetComments 

func (w *Work) GetComments(maximum *int) ([]*Comment, error)

GetComments returns a list of all threads of comments in the work

func (*Work) GetImages 

func (w *Work) GetImages() (map[int][]ImageInfo, error)

GetImages gets all images from this work

func (*Work) GetMetadata 

func (w *Work) GetMetadata() map[string]interface{}

GetMetadata returns a map of all work metadata

func (*Work) GetText 

func (w *Work) GetText() (string, error)

GetText returns the full text of the work

func (*Work) GetURL 

func (w *Work) GetURL() string

GetURL returns the URL to this work

func (*Work) IsLoaded 

func (w *Work) IsLoaded() bool

IsLoaded returns true if this work has been loaded

func (*Work) IsOneshot 

func (w *Work) IsOneshot() bool

IsOneshot returns true if this work has only one chapter

func (*Work) LeaveKudos 

func (w *Work) LeaveKudos() (bool, error)

LeaveKudos leaves kudos on this work

func (*Work) LoadChapters 

func (w *Work) LoadChapters() error

LoadChapters loads chapter objects for each chapter in the work

func (*Work) Reload 

func (w *Work) Reload(loadChapters bool) error

Reload loads or reloads the work's information

func (*Work) SetSession 

func (w *Work) SetSession(session *Session)

SetSession sets the session used to make requests for this work

func (*Work) String 

func (w *Work) String() string

String returns a string representation of the work

func (*Work) Subscribe 

func (w *Work) Subscribe() error

Subscribe subscribes to this work

func (*Work) Unsubscribe 

func (w *Work) Unsubscribe() error

Unsubscribe unsubscribes from this work

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.