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 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 WithGitHubToken(token string) Option
  • func WithHTTPCache(httpCache cache.HTTPCache) 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 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 "generic" if unknown. This uses the same matching logic as Fetch() to ensure consistency.

Types

type HTTPCache

type HTTPCache = cache.HTTPCache

HTTPCache re-exports cache.HTTPCache 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 WithGitHubToken

func WithGitHubToken(token string) Option

WithGitHubToken sets the GitHub API token for authenticated requests.

func WithHTTPCache

func WithHTTPCache(httpCache cache.HTTPCache) 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.