sociopath

Documentation

Overview

Package sociopath provides a unified API for fetching social media profiles.

Basic usage:

profile, err := sociopath.Fetch(ctx, "https://mastodon.social/@johndoe")
if err != nil {
    log.Fatal(err)
}
fmt.Println(profile.Name, profile.Bio)

For platforms requiring authentication (LinkedIn, Twitter):

profile, err := sociopath.Fetch(ctx, "https://linkedin.com/in/johndoe",
    sociopath.WithCookies(map[string]string{"li_at": "...", "JSESSIONID": "..."}))

Or use platform packages directly:

import "github.com/codeGROOVE-dev/sociopath/pkg/linkedin"
client, _ := linkedin.New(ctx, linkedin.WithBrowserCookies())
profile, _ := client.Fetch(ctx, "https://linkedin.com/in/johndoe")

Index

• Variables
• func Fetch(ctx context.Context, url string, opts ...Option) (*profile.Profile, error)
• func FetchEmail(ctx context.Context, emails []string, opts ...Option) ([]*profile.Profile, error)
• func FetchEmailRecursive(ctx context.Context, emails []string, opts ...Option) ([]*profile.Profile, error)
• func FetchRecursive(ctx context.Context, url string, opts ...Option) ([]*profile.Profile, error)
• func FetchRecursiveWithGuess(ctx context.Context, url string, opts ...Option) ([]*profile.Profile, error)
• func GuessFromUsername(ctx context.Context, username string, opts ...Option) ([]*profile.Profile, error)
• func PlatformForURL(url string) string
• type HTTPCache
• type Option
  • func WithBrowserCookies() Option
  • func WithCookies(cookies map[string]string) Option
  • func WithEmailHints(emails ...string) Option
  • func WithGitHubToken(token string) Option
  • func WithHTTPCache(httpCache httpcache.Cacher) Option
  • func WithLogger(logger *slog.Logger) Option
• type Profile

Variables

var (
	ErrAuthRequired    = profile.ErrAuthRequired
	ErrNoCookies       = profile.ErrNoCookies
	ErrProfileNotFound = profile.ErrProfileNotFound
	ErrRateLimited     = profile.ErrRateLimited
)

Re-export common errors.

Functions

func Fetch

func Fetch(ctx context.Context, url string, opts ...Option) (*profile.Profile, error)

Fetch retrieves a profile from the given URL. The platform is automatically detected from the URL.

func FetchEmail

func FetchEmail(ctx context.Context, emails []string, opts ...Option) ([]*profile.Profile, error)

FetchEmail fetches profiles from email-based services (Gravatar, Mail.ru, Google, GitHub). It returns all profiles found for the given email addresses.

func FetchEmailRecursive

func FetchEmailRecursive(ctx context.Context, emails []string, opts ...Option) ([]*profile.Profile, error)

FetchEmailRecursive fetches profiles from email-based services and recursively follows social links. Multiple emails are treated as belonging to the same person, with results deduplicated by URL.

func FetchRecursive

func FetchRecursive(ctx context.Context, url string, opts ...Option) ([]*profile.Profile, error)

FetchRecursive fetches a profile and recursively fetches all social links found. It returns all discovered profiles, avoiding duplicates by tracking visited URLs. Only links that match known social media platforms are followed. For platforms with single-account-per-person assumption (GitHub, LinkedIn, Twitter, etc.), it skips recursing into additional profiles from the same platform.

func FetchRecursiveWithGuess

func FetchRecursiveWithGuess(ctx context.Context, url string, opts ...Option) ([]*profile.Profile, error)

FetchRecursiveWithGuess is like FetchRecursive but also guesses related profiles based on discovered usernames. Guessed profiles are marked with IsGuess=true and include confidence scores.

func GuessFromUsername

func GuessFromUsername(ctx context.Context, username string, opts ...Option) ([]*profile.Profile, error)

GuessFromUsername guesses profiles across platforms based on a username. It creates a synthetic profile with the username and searches for matching profiles on supported platforms. All returned profiles are marked with IsGuess=true and include confidence scores.

func PlatformForURL

func PlatformForURL(url string) string

PlatformForURL returns the platform name for a URL, or "website" if unknown. This uses the same matching logic as Fetch() to ensure consistency.

Types

type HTTPCache

type HTTPCache = httpcache.Cache

HTTPCache re-exports httpcache.Cache for convenience.

type Option

type Option func(*config)

Option configures a Fetch call.

func WithBrowserCookies

func WithBrowserCookies() Option

WithBrowserCookies enables reading cookies from browser stores.

func WithCookies

func WithCookies(cookies map[string]string) Option

WithCookies sets explicit cookie values for authenticated platforms.

func WithEmailHints

func WithEmailHints(emails ...string) Option

WithEmailHints provides email addresses to associate with profiles. These emails are stored in Fields["email_hints"] and can be used for additional lookups (Gravatar, Google GAIA ID resolution, etc.).

func WithGitHubToken

func WithGitHubToken(token string) Option

WithGitHubToken sets the GitHub API token for authenticated requests.

func WithHTTPCache

func WithHTTPCache(httpCache httpcache.Cacher) Option

WithHTTPCache sets the HTTP cache for responses.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets a custom logger.

type Profile

type Profile = profile.Profile

Profile re-exports profile.Profile for convenience.