captcha

type AbortScope string

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

type Challenge struct {
	// ID identifies this challenge to the Source that produced it. Opaque:
	// callers pass it back to Answer/Abort unchanged and must not parse it -
	// the JD-backed Source's ID happens to be a stringified int64, but
	// nothing here promises another Source's will be.
	ID string `json:"id"`
	// Source names which Source produced this challenge (SourceJD today).
	// Carried on the value itself, not only implied by which Source a caller
	// happened to ask, because a consumer holding challenges from more than
	// one Source needs to tell them apart without threading that context
	// through separately.
	Source string `json:"source"`
	// Host is the hoster the challenge is guarding, e.g. "rapidgator.net".
	Host string `json:"host"`
	// TaskID is the KnightLoader task this challenge blocks, when whoever
	// built this Source could work that out. Empty is a real, expected
	// answer, not a bug - see jdsource.go's NewJDSource on why this package
	// cannot resolve it unaided.
	TaskID string `json:"taskId,omitempty"`
	// Kind is how this challenge must be rendered - see Kind's own doc
	// comment.
	Kind Kind `json:"kind"`
	// Prompt is the instructions a human reads, in whatever language the
	// hoster wrote them. Can be empty - not every challenge populates one.
	Prompt string `json:"prompt,omitempty"`
	// Payload is the kind-specific data a solver needs: *ImagePayload for
	// KindImage/KindClick, *WidgetPayload for KindWidget, *UnsupportedPayload
	// for KindUnsupported. A concrete Go type rather than raw JSON so a
	// same-process consumer (this wave's own tests, and 7A's app-level code)
	// can switch on Kind and type-assert without a redundant decode; it still
	// marshals to plain JSON for the eventual HTTP route exactly the same way.
	Payload any `json:"payload,omitempty"`
	// ExpiresAt is when this challenge stops being answerable, computed from
	// the Source's own live countdown at the moment it was listed rather than
	// a deadline fixed at creation - see jdsource.go's doc comment on why
	// that is the honest field to trust. Calling List again can move this
	// later without the challenge having changed identity, exactly as it
	// should when the challenge is still alive. Zero means the Source could
	// not say.
	ExpiresAt time.Time `json:"expiresAt,omitempty"`
}

type ClickPayload = ImagePayload

type ImagePayload struct {
	DataURL string `json:"dataUrl"`
}

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

type Kind string

type Solver interface {
	// Solve submits image and returns the exact text to hand to
	// Source.Answer unchanged - recognized text for KindImage, JD's own
	// click-answer JSON for KindClick (see encodeClickAnswer). image is
	// Challenge.Payload's own DataURL field (ImagePayload/ClickPayload - a
	// full "data:image/...;base64,..." string) or a bare base64 string;
	// either is accepted, see decodeSolverImage. prompt is Challenge.Prompt,
	// "" when the challenge carried none - both services accept free-text
	// worker instructions and solve more accurately with one than without.
	//
	// kind must be KindImage or KindClick. Anything else (KindWidget,
	// KindUnsupported) returns ErrUnsupportedKind before any network call is
	// made - see this file's package comment for why widget solving is out
	// of scope here.
	Solve(ctx context.Context, kind Kind, image, prompt string) (string, error)
}

type Source interface {
	// List returns every challenge currently waiting for an answer. An empty
	// slice with a nil error is the ordinary "nothing waiting" case, not a
	// failure - a poll loop must not treat every quiet tick as one.
	List(ctx context.Context) ([]Challenge, error)

	// Answer submits text as the solution to challenge id. stillValid reports
	// whether id was still live when the Source received it - the direct,
	// authoritative answer to "did this arrive too late", read from the
	// backend rather than guessed at from a client-side countdown (see
	// build-plan.md section 9 package 16: "solving an expired id silently
	// does nothing while the user sees sent"). false with a nil error is not
	// itself a failure: it means the challenge expired, or was already
	// answered elsewhere, between List and this call, and the caller should
	// treat that as "refresh and show whatever replaced it", not as
	// something to report to the user as an error.
	//
	// err is reserved for everything else going wrong: a transport failure,
	// an id the Source never issued, an answer shape the challenge rejected
	// outright.
	Answer(ctx context.Context, id string, text string) (stillValid bool, err error)

	// Abort tells the Source the user chose not to answer id, at the given
	// scope - see AbortScope. Aborting a challenge that has already expired
	// or been answered elsewhere is not an error: the end state Abort exists
	// to reach (id no longer pending) already holds, so a Source should
	// return nil for that case rather than making every caller special-case
	// a race it did not cause.
	Abort(ctx context.Context, id string, scope AbortScope) error
}

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

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

type UnsupportedPayload struct {
	// Vendor names the real origin of the challenge - for the JD-backed
	// Source, JD's own challenge class name (e.g. "AccountLoginOAuthChallenge"),
	// never a value this package invented or guessed at. See jdsource.go's
	// classify.
	Vendor string `json:"vendor"`
}

type WidgetPayload struct {
	SiteKey    string `json:"siteKey"`
	SiteURL    string `json:"siteUrl"`
	ContextURL string `json:"contextUrl"`
	// Type is the widget variant ("normal"/"invisible" for reCAPTCHA v2;
	// hCaptcha's own API always reports "normal" - see jdsource.go). Rendered
	// as-is; this package does not interpret it.
	Type string `json:"type,omitempty"`
	// Enterprise and V3Action only ever apply to reCAPTCHA; hCaptcha's own
	// Storable has no such fields and leaves them at the zero value - see
	// jdsource.go's jdWidgetToken.
	Enterprise bool   `json:"enterprise,omitempty"`
	V3Action   string `json:"v3Action,omitempty"`
	// SecureToken is JD's own "stoken". Kept even though the one Source this
	// package ships never observed hCaptcha populate it (its Storable's
	// getStoken() is hardcoded to return nil - see jdsource.go): dropping a
	// field JD's wire format genuinely carries is a silent regression the day
	// a JD build starts sending it, not a simplification.
	SecureToken string `json:"secureToken,omitempty"`
}