Commit `b80180e77e`

b80180e77eebad8476aa66c8a5433764da672c62

parent: b70d3dd588

Unregistered key

cmc <hello@cleberg.net> · 2026-07-15 22:26 UTC
committer: <noreply@github.com>

docs: document the exported API, and fix five bugs found writing it (#2)

* docs: translate Russian comments and document exported API

The package carried 35 Russian comments and no doc comments on its
exported identifiers, so pkg.go.dev rendered a bare list of signatures.

Translate the Russian to English and give every exported identifier a
doc comment in godoc form. Add doc.go with a package overview covering
the guest-session requirement, the Error-as-struct convention, and
CloudFront blocking.

The comments record what the signatures cannot: that UpdateCSRF must run
first and that its token expires, that Error is a struct and so is never
nil, that Thread is one comment rather than a thread, and that
GetComments' page parameter costs one request per page.

Comments only; the struct field realignment is gofmt's, from doc comments
splitting alignment groups.

Refs #1

* add CODEOWNERS

* fix: stop the library killing its caller, and flatten text correctly

Writing doc comments for the exported API surfaced behavior too alarming
to document and leave alone. A library should never terminate the process
that imports it.

Crashes:

- GetComments panicked on a comment with an empty body: the shape check
  read m[0] and m[len(m)-1] with no length check.
- Group.Favourites and Group.Gallery indexed their variadic folderid
  without checking len, so omitting it — which the signature invites —
  panicked. Omitting it now means 0.
- AEmedia and PerformSearch called log.Fatalln on a bad argument rune,
  terminating the caller. Both now return an error, which their
  signatures already allowed for.

Draft.js flattening, in the same code both callers share:

- The block loop assigned rather than accumulated, so every block but the
  last was dropped and a multi-paragraph body came back as its closing
  line alone. Blocks are block-level elements, so join them with newlines.
- GetDeviation guarded on txt[1] == '{', the second character of a body
  that opens with {"blocks". It never fired, so descriptions were handed
  back as raw Draft.js JSON. It now shares flattenComment with
  GetComments rather than keeping its own copy.

Both flattening fixes change output for existing callers.

Refs #1

Layout: unified · split

CODEOWNERS added +1

	@@ -0,0 +1 @@
		1	* @ccleberg\ No newline at end of file

comments.go +64 −21

	@@ -4,18 +4,28 @@ import (
4	"encoding/json"	4	"encoding/json"
5	"net/url"	5	"net/url"
6	"strconv"	6	"strconv"
		7	"strings"
7	)	8	)
8		9
		10	// Thread is a single comment, despite the name. Replies are not nested inside
		11	// it: a thread arrives flattened into [Comments].Thread, and the shape is
		12	// recovered through Parent, which holds the ID of the comment being replied to
		13	// and is 0 for a top-level comment.
9	type Thread struct {	14	type Thread struct {
10	Replies, Likes int	15	Replies, Likes int
11	ID int `json:"commentId"`	16	ID int `json:"commentId"`
12	Parent int `json:"parentId"`	17	Parent int `json:"parentId"`
13		18
14	Posted timeStamp	19	Posted timeStamp
		20	// Author reports whether the commenter is the author of the deviation being
		21	// commented on.
15	Author bool `json:"isAuthorHighlited"`	22	Author bool `json:"isAuthorHighlited"`
16		23
17	Desctiption string	24	Desctiption string
18	Comment string	25
		26	// Comment is the comment's plain text, which [GetComments] extracts from
		27	// TextContent. Prefer it; TextContent is the unprocessed original.
		28	Comment string
19		29
20	TextContent Text	30	TextContent Text
21		31
	@@ -25,6 +35,10 @@ type Thread struct {
25	}	35	}
26	}	36	}
27		37
		38	// Comments is one page of comments. Thread holds the comments themselves,
		39	// flattened rather than nested; Total counts every comment on the item, not just
		40	// this page. Cursor resumes from the end of this page and HasMore reports
		41	// whether anything remains.
28	type Comments struct {	42	type Comments struct {
29	Cursor string	43	Cursor string
30	PrevOffset int	44	PrevOffset int
	@@ -34,7 +48,17 @@ type Comments struct {
34	Thread []Thread	48	Thread []Thread
35	}	49	}
36		50
37	// 1 - комментарии поста; 4 - комментарии на стене группы или пользователя	51	// GetComments retrieves comments on an item, 50 per page, with each comment's
		52	// plain text extracted into [Thread].Comment.
		53	//
		54	// typ selects what postid refers to: 1 for comments on a deviation, 4 for those
		55	// on a user's or group's profile wall. cursor resumes from a previous call's
		56	// [Comments].Cursor; pass an empty string to start from the newest comment.
		57	//
		58	// page is an offset from cursor rather than an absolute page number, and it is
		59	// walked one request at a time: page 5 costs six round-trips and returns only
		60	// the sixth page. Paginating by feeding each result's Cursor back in with page 0
		61	// costs one request per page, and is the cheaper way to walk a long thread.
38	func GetComments(postid string, cursor string, page int, typ int) (cmmts Comments, err Error) {	62	func GetComments(postid string, cursor string, page int, typ int) (cmmts Comments, err Error) {
39	for x := 0; x <= page; x++ {	63	for x := 0; x <= page; x++ {
40	err = ujson(	64	err = ujson(
	@@ -46,28 +70,47 @@ func GetComments(postid string, cursor string, page int, typ int) (cmmts Comment
46		70
47	cursor = cmmts.Cursor	71	cursor = cmmts.Cursor
48		72
49	// парсинг json внутри json
50	for i := 0; i < len(cmmts.Thread); i++ {	73	for i := 0; i < len(cmmts.Thread); i++ {
51	m, l := cmmts.Thread[i].TextContent.Html.Markup, len(cmmts.Thread[i].TextContent.Html.Markup)	74	cmmts.Thread[i].Comment = flattenComment(cmmts.Thread[i].TextContent.Html.Markup)
52	cmmts.Thread[i].Comment = m
53
54	// если начало строки {, а конец }, то срабатывает этот иф
55	if m[0] == '{' && m[l-1] == '}' {
56	var content struct {
57	Blocks []struct {
58	Text string
59	}
60	}
61
62	e := json.Unmarshal([]byte(m), &content)
63	try(e)
64
65	for _, a := range content.Blocks {
66	cmmts.Thread[i].Comment = a.Text
67	}
68	}
69	}	75	}
70	}	76	}
71		77
72	return	78	return
73	}	79	}
		80
		81	// flattenComment renders a body of user-written markup as plain text, be it a
		82	// comment or a deviation's description. Bodies are JSON inside JSON: newer ones
		83	// are a Draft.js document encoded into the markup string, older ones are plain
		84	// HTML, which passes through unchanged. Markup that does not parse, and empty
		85	// markup, also pass through.
		86	//
		87	// A Draft.js document is a list of blocks, which are block-level elements
		88	// (paragraphs, list items); they are joined with newlines, one block per line.
		89	func flattenComment(m string) string {
		90	l := len(m)
		91	if l == 0 \|\| m[0] != '{' \|\| m[l-1] != '}' {
		92	return m
		93	}
		94
		95	var content struct {
		96	Blocks []struct {
		97	Text string
		98	}
		99	}
		100
		101	e := json.Unmarshal([]byte(m), &content)
		102	try(e)
		103
		104	if len(content.Blocks) == 0 {
		105	return m
		106	}
		107
		108	var b strings.Builder
		109	for i, a := range content.Blocks {
		110	if i > 0 {
		111	b.WriteString("\n")
		112	}
		113	b.WriteString(a.Text)
		114	}
		115	return b.String()
		116	}

comments_test.go added +51

@@ -0,0 +1,51 @@
	1	package devianter
	2
	3	import "testing"
	4
	5	// Regression: flattenComment's shape check used to read m[0] and m[len(m)-1]
	6	// without a length check, so a comment with an empty markup body panicked with
	7	// index out of range and killed the caller's process.
	8	func TestFlattenCommentEmptyMarkup(t *testing.T) {
	9	if got := flattenComment(""); got != "" {
	10	t.Errorf("want an empty comment for empty markup, got %q", got)
	11	}
	12	}
	13
	14	func TestFlattenComment(t *testing.T) {
	15	// A newer, Draft.js-encoded body is flattened to its text.
	16	draft := `{"blocks":[{"text":"hello there"}]}`
	17	if got := flattenComment(draft); got != "hello there" {
	18	t.Errorf("want the Draft.js block text, got %q", got)
	19	}
	20
	21	// An older, plain-HTML body passes through untouched.
	22	html := "<b>hello</b> there"
	23	if got := flattenComment(html); got != html {
	24	t.Errorf("want plain HTML passed through, got %q", got)
	25	}
	26
	27	// Regression: the block loop used to assign rather than accumulate, so every
	28	// block but the last was silently dropped and a multi-paragraph comment came
	29	// back as its closing line only.
	30	multi := `{"blocks":[{"text":"first"},{"text":"second"},{"text":"third"}]}`
	31	if got, want := flattenComment(multi), "first\nsecond\nthird"; got != want {
	32	t.Errorf("want every block, one per line:\n got %q\nwant %q", got, want)
	33	}
	34
	35	// An empty block is a blank line in the comment, not something to skip.
	36	blank := `{"blocks":[{"text":"first"},{"text":""},{"text":"third"}]}`
	37	if got, want := flattenComment(blank), "first\n\nthird"; got != want {
	38	t.Errorf("want an empty block preserved as a blank line:\n got %q\nwant %q", got, want)
	39	}
	40
	41	// Brace-shaped markup that isn't a Draft.js document falls back to itself
	42	// rather than to an empty string.
	43	if got := flattenComment("{}"); got != "{}" {
	44	t.Errorf("want the original markup when there are no blocks, got %q", got)
	45	}
	46
	47	// A single brace satisfies neither end of the shape check.
	48	if got := flattenComment("{"); got != "{" {
	49	t.Errorf("want a lone brace passed through, got %q", got)
	50	}
	51	}

deviantion.go +44 −26

 package devianter
 import (
-	"encoding/json"
 	"strconv"
 	"strings"
 	"time"
 )
-// хрень для парсинга времени публикации
+// timeStamp is a time.Time that parses DeviantArt's publication timestamps,
+// which are ISO 8601 with no colon in the zone offset and so are rejected by
+// encoding/json's default time handling.
 type timeStamp struct {
 	time.Time
 }
 	return
 }
-// самая главная структура для поста
+// Deviation is a single artwork and its metadata: the central type of this
+// package. Most endpoints return these, either alone or in slices.
+//
+// How much of it is populated depends on the endpoint. Search results and
+// gallery listings return a shallow Deviation — enough for a thumbnail and a
+// title — while [GetDeviation] fills in Extended, with the tags, original file
+// details, and description. A zero-valued field usually means the endpoint did
+// not send it rather than that the artwork lacks it.
 type Deviation struct {
 	Title, Url, License string
 	PublishedTime       timeStamp
 	TextContent Text
 }
-// её выпердыши
+// Media locates a deviation's image files. It is not a usable URL on its own:
+// the pieces have to be assembled, and the result signed with a token. Pass it
+// to [UrlFromMedia] rather than building the URL by hand.
 type Media struct {
 	BaseUri string
 	Name    string `json:"prettyName"`
 	Token   []string
-	Types   []struct {
+	// Types are the renditions available (thumbnails, preview, "fullview"), each
+	// with its own dimensions.
+	Types []struct {
 		T    string
 		H, W int
 	}
 }
+// Text is a block of user-written text — a description, a comment, a group's
+// about page. Markup holds either HTML or a JSON-encoded Draft.js document,
+// distinguished by Type; the functions that return a Text generally extract the
+// plain text into a neighbouring field, which is easier to use.
 type Text struct {
 	Excerpt string
 	Html    struct {
 	}
 }
-// структура поста
+// Post is a deviation together with its comment metadata, as returned by
+// [GetDeviation]. IMG and Description are conveniences that GetDeviation derives
+// from the Deviation, so callers need not assemble a URL or decode Draft.js
+// markup themselves.
+//
+// Comments holds only a total and a cursor. To retrieve the comments, pass them
+// to [GetComments] with type 1.
 type Post struct {
 	Deviation Deviation
 	Comments  struct {
 	IMG, Description string
 }
-// преобразование урла в правильный
+// UrlFromMedia assembles a usable, token-signed image URL from a [Media], along
+// with the filename DeviantArt would serve it under. It selects the "fullview"
+// rendition and returns empty strings if the media has none.
+//
+// An optional thumb argument scales the request down towards that many pixels
+// per side, for fetching a smaller copy than the original. GIFs and very large
+// images (beyond roughly 33 megapixels) are returned at their original URL
+// without resizing, as DeviantArt's resizer refuses them.
 func UrlFromMedia(m Media, thumb ...int) (urlParsed, wellFormattedFilename string) {
 	var url strings.Builder
 	return
 }
-// для работы функции нужно ID поста и имя пользователя.
+// GetDeviation retrieves a single deviation by its numeric ID and its author's
+// username. Both are required: the endpoint will not resolve an ID alone. They
+// appear in a deviation's page URL, which ends in a slug of the form
+// title-by-author-123456789.
+//
+// The returned Post has its IMG and Description already derived, and its
+// Deviation is fully populated, including Extended.
 func GetDeviation(id string, user string) (st Post, err Error) {
 	err = ujson(
 		"dadeviation/init?deviationid="+id+"&username="+user+"&type=art&include_session=false&expand=deviation.related&preload=true",
 	st.IMG, _ = UrlFromMedia(st.Deviation.Media)
-	// базовая обработка описания
+	st.Description = flattenComment(st.Deviation.TextContent.Html.Markup)
-	txt := st.Deviation.TextContent.Html.Markup
-	if len(txt) > 1 && txt[1] == '{' {
-		var description struct {
-			Blocks []struct {
-				Text string
-			}
-		}
-		if err := json.Unmarshal([]byte(txt), &description); err != nil {
-			// Handle error appropriately
-			try(err) // or log/return the error
-		}
-		for _, a := range description.Blocks {
-			txt = a.Text
-		}
-	}
-	st.Description = txt
 	return
 }

doc.go added +45

@@ -0,0 +1,45 @@
	1	// Package devianter is a client for DeviantArt's internal "_puppy" API, the
	2	// JSON backend that deviantart.com's own web frontend calls.
	3	//
	4	// This is not the official, documented DeviantArt API. There is no application
	5	// registration and no OAuth: the package authenticates the way a logged-out
	6	// browser does, by fetching a guest session cookie and a CSRF token from the
	7	// homepage. Everything reachable here is what an anonymous visitor can see.
	8	// Because the endpoints are internal, DeviantArt can change or remove them
	9	// without notice.
	10	//
	11	// # Usage
	12	//
	13	// Call [UpdateCSRF] once before anything else to establish the guest session.
	14	// Every other call depends on the cookie and token it stores, and will fail
	15	// until it has run:
	16	//
	17	// if err := devianter.UpdateCSRF(); err != nil {
	18	// log.Fatal(err)
	19	// }
	20	//
	21	// post, apiErr := devianter.GetDeviation("123456789", "someuser")
	22	// if apiErr.Reason != "" {
	23	// log.Fatal(apiErr.Error)
	24	// }
	25	// fmt.Println(post.Deviation.Title, post.IMG)
	26	//
	27	// The session does not refresh itself. A long-running program should call
	28	// [UpdateCSRF] again when calls start failing, since tokens expire.
	29	//
	30	// # Errors
	31	//
	32	// Most functions return an [Error] value rather than a Go error. It is a struct,
	33	// not an interface, so it is never nil; a call succeeded if Error.Reason is
	34	// empty. Functions that can also fail on their arguments before any request is
	35	// made (such as [PerformSearch] and [Group.Gallery]) return an ordinary error
	36	// alongside it for that case.
	37	//
	38	// # Rate limiting and blocking
	39	//
	40	// DeviantArt sits behind CloudFront, which blocks IP addresses that request too
	41	// aggressively. A blocked request surfaces as an [Error] whose Error field
	42	// mentions CloudFront/WAF. This package does no rate limiting, retrying, or
	43	// backoff of its own; a caller making bulk requests is expected to pace itself.
	44	// Set [UserAgent] to identify your client and [Timeout] to bound each request.
	45	package devianter

misc.go +55 −18

 import (
 	"errors"
-	"log"
 	"math"
 	"net/url"
 	"strconv"
 )
 /* AVATARS AND EMOJIS */
+// AEmedia fetches a user's avatar or a site emoji by name. t selects which:
+// 'a' for an avatar, 'e' for an emoji.
+//
+// It returns the image data itself, not a URL. DeviantArt does not say which
+// format a given name is stored in, so this tries .jpg, .png, and .gif in turn
+// and returns the first that exists — up to three requests per call, and three
+// for a name that does not exist.
+//
+// Passing any other t returns an error without making a request.
 func AEmedia(name string, t rune) (string, error) {
 	if len(name) < 2 {
 		return "", errors.New("name must be specified")
 	}
-	// список всех возможных расширений
 	var extensions = [3]string{
 		".jpg",
 		".png",
 		".gif",
 	}
-	// надо
 	name = strings.ToLower(name)
-	// построение ссылок. билдер потому что он быстрее обычного сложения строк.
+	// Avatars and emoji are sharded into directories by the leading characters of
+	// the name; avatars additionally normalise dashes to underscores first.
 	var b strings.Builder
 	switch t {
 	case 'a':
 		b.WriteString(name[:1])
 		b.WriteString("/")
 	default:
-		log.Fatalln("Invalid type.\n- 'a' -- avatar;\n- 'e' -- emoji.")
+		return "", errors.New("invalid type: want 'a' (avatar) or 'e' (emoji)")
 	}
 	b.WriteString(name)
-	// проверка ссылки на доступность
+	// Probe each extension; the first 200 is the real format.
 	for x := 0; x < len(extensions); x++ {
 		req := request(b.String() + extensions[x])
 		if req.Status == 200 {
 }
 /* DAILY DEVIATIONS */
+// DailyDeviations is the staff-curated front page selection. The picks are
+// grouped into Strips, each a titled row as the site presents it; Deviations is
+// the ungrouped listing.
 type DailyDeviations struct {
 	HasMore bool
 	Strips  []struct {
 	Deviations []Deviation
 }
+// GetDailyDeviations retrieves a page of the daily deviation selection. Pages
+// are zero-based; check the returned HasMore before asking for the next.
 func GetDailyDeviations(page int) (dd DailyDeviations, err Error) {
 	err = ujson("dabrowse/networkbar/rfy/deviations?page="+strconv.Itoa(page), &dd)
 	return
 }
 /* SEARCH */
+// Search is a page of search results. Read the matches from Results, which
+// [PerformSearch] populates whichever field the endpoint used.
+//
+// Total is DeviantArt's own estimate and is approximate. Pages is derived from
+// it and capped at 417, the depth a guest session can reach before the API stops
+// paginating.
 type Search struct {
-	Total              int `json:"estTotal"`
+	Total   int `json:"estTotal"`
-	Pages              int // only for 'a' and 'g' scope.
+	Pages   int // only for 'a' and 'g' scope.
-	HasMore            bool
+	HasMore bool
-	Results            []Deviation `json:"deviations"`
+	Results []Deviation `json:"deviations"`
+	// ResultsGalleryTemp receives the results of gallery and collection searches,
+	// which return them under a different key. PerformSearch copies it into
+	// Results; callers should not need this field.
 	ResultsGalleryTemp []Deviation `json:"results"`
 }
+// PerformSearch searches DeviantArt. scope selects what is being searched:
+//
+//	'a' — everything, by title and description
+//	't' — by tag
+//	'g' — within one user's or group's gallery
+//	'f' — within one user's or group's collections (favourites)
+//
+// Scopes 'g' and 'f' search a particular account, so they require the username
+// as the final argument and return an error without it. The other two ignore it.
+//
+// Pages are zero-based. A guest session cannot page beyond roughly 417 pages
+// deep regardless of how many results Total claims.
+//
+// Passing any other scope returns an error without making a request.
 func PerformSearch(query string, page int, scope rune, user ...string) (ss Search, daError Error, err error) {
 	var buildurl strings.Builder
-	// о5 построение ссылок.
 	switch scope {
-	case 'a': // поиск артов по названию
+	case 'a':
 		buildurl.WriteString("dabrowse/search/all?q=")
-	case 't': // поиск артов по тегам
+	case 't':
 		buildurl.WriteString("dabrowse/networkbar/tag/deviations?tag=")
-	case 'g', 'f': // поиск артов пользователя или группы
+	case 'g', 'f':
 		if user == nil {
 			err = errors.New("missing username (last argument)")
 			return
 		}
 		buildurl.WriteString("&order=most-recent&init=true&limit=50&q=")
 	default:
-		log.Fatalln("Invalid type.\n- 'a' -- all;\n- 't' -- tag;\n- 'g' - gallery\n- 'f' - folders.")
+		err = errors.New("invalid scope: want 'a' (all), 't' (tag), 'g' (gallery) or 'f' (favourites)")
+		return
 	}
 	buildurl.WriteString(url.QueryEscape(query))
-	if scope != 'g' { // если область поиска не равна поиску по группам, то активируется этот код
+	// Gallery search paginates by item offset rather than page number.
+	if scope != 'g' {
 		buildurl.WriteString("&page=")
-	} else { // иначе вместо страницы будет оффсет и страница умножится на 50
+	} else {
 		buildurl.WriteString("&offset=")
 		page = 50 * page
 	}
 		ss.Results = ss.ResultsGalleryTemp
 	}
-	// расчёт, сколько всего страниц по запросу. без токена, 417 страниц - максимум
+	// Derive the page count from the result estimate, clamped to the 417 pages a
+	// guest session can actually reach.
 	totalfloat := int(math.Round(float64(ss.Total / 25)))
 	for x := 0; x < totalfloat; x++ {
 		if x <= 417 {

misc_test.go added +40

@@ -0,0 +1,40 @@
	1	package devianter
	2
	3	import "testing"
	4
	5	// Regression: AEmedia used to call log.Fatalln on an unknown type, terminating
	6	// the calling process. If this test ever regresses it will not fail — the test
	7	// binary will exit(1) mid-run.
	8	func TestAEmediaInvalidTypeReturnsError(t *testing.T) {
	9	_, err := AEmedia("someuser", 'z')
	10	if err == nil {
	11	t.Fatal("want an error for an unknown type, got nil")
	12	}
	13	}
	14
	15	// The argument checks must run in an order that never leaves a valid-looking
	16	// call unreported: a short name is an error regardless of type.
	17	func TestAEmediaShortNameReturnsError(t *testing.T) {
	18	if _, err := AEmedia("", 'a'); err == nil {
	19	t.Fatal("want an error for an empty name, got nil")
	20	}
	21	}
	22
	23	// Regression: PerformSearch used to call log.Fatalln on an unknown scope. As
	24	// above, a regression exits the test binary rather than failing this test.
	25	func TestPerformSearchInvalidScopeReturnsError(t *testing.T) {
	26	_, _, err := PerformSearch("cats", 0, 'z')
	27	if err == nil {
	28	t.Fatal("want an error for an unknown scope, got nil")
	29	}
	30	}
	31
	32	// The account-scoped searches need a username, and must say so rather than
	33	// requesting a URL with an empty one.
	34	func TestPerformSearchAccountScopesRequireUser(t *testing.T) {
	35	for _, scope := range []rune{'g', 'f'} {
	36	if _, _, err := PerformSearch("cats", 0, scope); err == nil {
	37	t.Errorf("want an error for scope %q with no username, got nil", scope)
	38	}
	39	}
	40	}

user-group.go +72 −11

 	"strings"
 )
-// структура группы или пользователя
+// GRuser is a profile — a user's or a group's, as DeviantArt models both the
+// same way. Owner.Group distinguishes them, and determines which of the
+// ModuleData fields are populated: GroupAbout and GroupAdmins for a group, the
+// embedded users for a person.
+//
+// The Page.Modules slice mirrors the site's own profile layout, so a caller
+// looking for one piece of information has to search the slice for the module
+// that carries it rather than reading a field directly.
 type GRuser struct {
 	ErrorDescription string
 	Owner            struct {
 	} `json:"pageExtraData"`
 }
+// Gallery is a listing of deviations from a profile, returned by
+// [Group.Gallery] and [Group.Favourites].
+//
+// Where the deviations land depends on the call. Results is the flat listing;
+// folder-scoped requests instead nest them inside the Modules slice, under
+// Folder for a gallery or Folders for the folder index itself.
 type Gallery struct {
 	Gruser struct {
 		ID   int `json:"gruserId"`
 			Modules []struct {
 				Name       string
 				ModuleData struct {
-					// группы
+					// Folders is the index of a profile's folders, each with a
+					// representative thumbnail.
 					Folders struct {
 						HasMore bool
 						Results []struct {
 						}
 					}
-					// галерея
+					// Folder is the contents of one folder.
 					Folder struct {
 						HasMore    bool
 						Username   string
 	Results []Deviation
 }
+// Group is the entry point for everything scoped to one profile. Despite the
+// name it addresses users as well as groups, since DeviantArt treats the two
+// alike.
+//
+// Name is the profile's username and must be set; the methods return an error
+// otherwise. Construct it directly:
+//
+//	g := devianter.Group{Name: "someuser"}
+//	profile, apiErr, err := g.Get()
 type Group struct {
-	Name    string // обязательно заполнить
+	Name    string // required
 	Content Gallery
 }
-// подходит как группа, так и пользователь
+// Get retrieves the profile itself — its about page, statistics, and, for a
+// group, its admins. It works for both users and groups; inspect
+// Owner.Group on the result to tell which was returned.
 func (s Group) Get() (g GRuser, daError Error, err error) {
 	if s.Name == "" {
 		return g, daError, errors.New("missing Name field")
 	return
 }
+// Favourites retrieves a page of the profile's favourites (its collections), 50
+// at a time, zero-based.
+//
+// Set all to gather every folder's contents into one listing. Otherwise pass a
+// positive folderid to read a single folder, or 0 for the profile's default
+// favourites listing.
+//
+// folderid is optional; omitting it is the same as passing 0. Only the first
+// value is used.
 func (s Group) Favourites(page int, all bool, folderid ...int) (g Group, err Error) {
 	var url strings.Builder
-	if fid := folderid[0]; fid > 0 || all {
+	fid := 0
+	if len(folderid) > 0 {
+		fid = folderid[0]
+	}
+	if fid > 0 || all {
 		url.WriteString("dashared/gallection/contents")
 		if all {
 			url.WriteString("?all_folder=true")
 	return
 }
-// гарелея пользователя или группы
+// Gallery retrieves a page of the profile's gallery, 50 deviations at a time.
+// Pass a positive folderid to read one folder, or 0 for the whole gallery.
+//
+// folderid is optional; omitting it is the same as passing 0. Only the first
+// value is used.
+//
+// Note that page is interpreted differently by the two paths this takes: the
+// whole-gallery listing is zero-based, while a folder listing is one-based.
 func (s Group) Gallery(page int, folderid ...int) (g Group, daError Error, err error) {
 	if s.Name == "" {
 		return g, daError, errors.New("missing Name field")
 	}
+	fid := 0
+	if len(folderid) > 0 {
+		fid = folderid[0]
+	}
 	var url strings.Builder
-	if folderid[0] > 0 {
+	if fid > 0 {
 		page--
 		url.WriteString("dashared/gallection/contents?username=")
 		url.WriteString(s.Name)
 		url.WriteString("&folderid=")
-		url.WriteString(strconv.Itoa(folderid[0]))
+		url.WriteString(strconv.Itoa(fid))
 		url.WriteString("&offset=")
 		url.WriteString(strconv.Itoa(page * 50))
 		url.WriteString("&type=gallery&")
 	return
 }
+// GroupAbout is a group's about page: when it was founded and its description.
 type GroupAbout struct {
 	FoundatedAt timeStamp `json:"foundationTs"`
 	Description Text
 }
+// GroupAdmins lists a group's staff. TypeId encodes each member's role
+// (founder, co-founder, contributor).
 type GroupAdmins struct {
 	Results []struct {
 		TypeId int
 	}
 }
+// About is a person's profile information, all of it self-reported and any of
+// it possibly empty.
 type About struct {
 	Country, Website, WebsiteLabel, Gender string
-	RegDate                                int64 `json:"deviantFor"`
+	// RegDate is how long the account has existed, in seconds — an age, not a
-	Description                            Text  `json:"textContent"`
+	// registration date, despite the name.
+	RegDate     int64 `json:"deviantFor"`
+	Description Text  `json:"textContent"`
 	SocialLinks []struct {
 		Value string
 	}
 }
+// users is the person-specific half of a profile's module data, embedded into
+// [GRuser] so its fields surface inline.
 type users struct {
 	About          About
 	CoverDeviation struct {

user-group_test.go added +43

@@ -0,0 +1,43 @@
	1	package devianter
	2
	3	import (
	4	"testing"
	5	"time"
	6	)
	7
	8	// Regression: Favourites and Gallery took folderid as a variadic, which invites
	9	// omitting it, but then indexed folderid[0] with no length check — so the call
	10	// the signature invites most panicked with index out of range.
	11	//
	12	// Both reach a request before returning, and neither takes a base URL, so these
	13	// squeeze Timeout down to make that request fail immediately. The failure is
	14	// expected and ignored: only the absence of a panic is under test.
	15	func TestFolderidIsOptional(t *testing.T) {
	16	defer func(d time.Duration) { Timeout = d }(Timeout)
	17	Timeout = time.Millisecond
	18
	19	s := Group{Name: "someuser"}
	20
	21	t.Run("Gallery", func(t *testing.T) {
	22	if _, _, err := s.Gallery(0); err != nil {
	23	t.Errorf("omitting folderid is not an argument error, got %v", err)
	24	}
	25	})
	26
	27	t.Run("Favourites all", func(t *testing.T) {
	28	_, _ = s.Favourites(0, true)
	29	})
	30
	31	t.Run("Favourites default listing", func(t *testing.T) {
	32	_, _ = s.Favourites(0, false)
	33	})
	34	}
	35
	36	// Name is what every request is scoped to, so Gallery reports its absence
	37	// rather than requesting a URL with an empty username.
	38	func TestGalleryRequiresName(t *testing.T) {
	39	var s Group
	40	if _, _, err := s.Gallery(0, 0); err == nil {
	41	t.Fatal("want an error for a Group with no Name, got nil")
	42	}
	43	}

util.go +55 −8

 	"time"
 )
-// функция для высера ошибки в stderr
+// try prints a non-nil error to stderr and swallows it. It is how this package
+// reports problems it does not propagate, such as a response that parsed only
+// partially.
 func try(txt error) {
 	if txt != nil {
 		println(txt.Error())
 	}
 }
+// ujson fetches a _puppy endpoint and unmarshals the response into output.
+// data is the path and query string after the endpoint root, without a leading
+// slash and without the csrf_token parameter, which puppy appends.
+//
+// A malformed response is reported through try and leaves output partially
+// populated, so a returned Error with an empty Reason does not by itself
+// guarantee that output is complete.
 func ujson(data string, output any) Error {
 	input, err := puppy(data)
 	if err == nil {
 	return APIError(err)
 }
+// Error is a failed API call. It is a struct rather than an error interface, so
+// a zero value means success: test Reason for emptiness rather than comparing
+// against nil.
+//
+// For errors DeviantArt itself reports, Reason and Error hold its machine and
+// human readable descriptions. For anything else (a transport failure, or a
+// CloudFront block page) Reason is "request_failed" and Error carries the
+// underlying message.
 type Error struct {
 	Reason string `json:"error"`
 	Error  string `json:"errorDescription"`
 	RAW    []byte `json:"-"`
 }
+// APIError converts an error from the request layer into an [Error], decoding
+// DeviantArt's JSON error body when that is what it is. A nil input yields the
+// zero Error, which signals success.
 func APIError(inputError error) (err Error) {
 	if inputError != nil {
 		err.RAW = []byte(inputError.Error())
 }
 /* REQUEST SECTION */
-// структура для ответа сервера
+// reqrt is a completed HTTP response, flattened into the pieces this package
+// needs. On a transport failure Err is set and every other field is zero.
 type reqrt struct {
 	Body    string
 	Status  int
 	Err error
 }
-// функция для совершения запроса
+// UserAgent overrides the browser User-Agent this package sends by default.
+// Setting it to something that identifies your client is polite, but DeviantArt
+// is more likely to serve a block page to a non-browser agent.
 var UserAgent string
 // Timeout bounds a single request end-to-end (dial, response, body read).
 // Without it, a hung connection blocks its caller forever.
 var Timeout = 30 * time.Second
+// request performs a GET and never panics or returns a partial response without
+// saying so: any failure is reported in reqrt.Err. An optional second argument
+// supplies the Cookie header.
 func request(uri string, other ...string) reqrt {
 	var r reqrt
-	// создаём новый запрос
 	// Transport is deliberately left nil so http.DefaultTransport applies: that
 	// keeps HTTPS_PROXY support and lets callers wrap it (e.g. to rate-limit).
 	cli := &http.Client{Timeout: Timeout}
 		return r
 	}
+	// Impersonate a browser by default: the endpoints are the web frontend's own,
+	// and an unfamiliar agent draws a block page.
 	req.Header.Set("User-Agent", "Mozilla/5.0 (X11; Linux x86_64; rv:123.0) Gecko/20100101 Firefox/123.0.0")
-	// куки и UA-шник
 	if UserAgent != "" {
 		req.Header.Set("User-Agent", UserAgent)
 	}
 		r.Err = e
 	}
-	// заполняем структуру
 	r.Body = string(body)
 	r.Cookies = resp.Cookies()
 	r.Headers = resp.Header
 }
 /* PUPPY aka DeviantArt API */
-// получение или обновление токена
+// The guest session: a cookie from the _puppy endpoint and a CSRF token scraped
+// from the homepage. UpdateCSRF populates both; puppy sends them on every call.
+//
+// These are package-level and unsynchronised, so a program that calls UpdateCSRF
+// concurrently with any other function of this package races on them.
 var cookie string
 var token string
 	xhrMarker  = "window.__XHR_LOCAL__"
 )
+// UpdateCSRF establishes the guest session that every other call in this package
+// depends on, and must be called before them. It fetches a session cookie (only
+// on the first call; later calls reuse it) and scrapes a fresh CSRF token from
+// the DeviantArt homepage.
+//
+// Tokens expire, so a long-running program should call this again when requests
+// begin to fail. It is not safe to call concurrently with other functions of
+// this package.
+//
+// An error means the session was not established: the homepage was blocked,
+// served a challenge, or changed its markup such that the token is no longer
+// where this package looks for it.
 func UpdateCSRF() error {
 	if cookie == "" {
 		req := request("https://www.deviantart.com/_puppy")
 	return nil
 }
+// puppy calls a _puppy endpoint with the guest session applied and returns the
+// raw JSON body. data is a path and query string; the CSRF token and API version
+// are appended to it, so it must already end in a parameter (callers conclude
+// theirs with a trailing "&" or a final value).
+//
+// It returns an error for a transport failure, a non-200 status, or a 200 whose
+// body is not JSON, which is how a CDN block page arrives.
 func puppy(data string) (string, error) {
 	var url strings.Builder
 	url.WriteString("https://www.deviantart.com/_puppy/")
 		return "", body.Err
 	}
-	// если код ответа не 200, возвращается ошибка
 	if body.Status != 200 {
 		return "", errors.New(describe(body))
 	}

Commit b80180e77e

Commit `b80180e77e`