shared

README

socials-auto

Cross-cutting Go types and the Parser contract for w_popularity.

Every parser module imports this. Keep it tiny — only types/interfaces consumed by both backend and parsers belong here.

import shared "github.com/suenot/socials-auto"

type Parser interface {
    Platform() shared.Platform
    FetchChannel(ctx context.Context, handle string) (shared.ChannelSnapshot, error)
    FetchRecentPosts(ctx context.Context, handle string, since time.Time) ([]shared.PostSnapshot, error)
}

License

MIT

Documentation

Overview

Package shared defines the cross-platform Parser contract and snapshot types used by every w_popularity parser module and the backend.

Index

• Variables
• type ChannelSnapshot
• type Parser
• type Platform
• type PostKind
• type PostSnapshot

Variables

var (
	ErrNotImplemented = errors.New("parser: not implemented")
	ErrNotFound       = errors.New("parser: handle not found")
	ErrRateLimited    = errors.New("parser: rate limited")
	ErrAuth           = errors.New("parser: auth failed")
	ErrTransient      = errors.New("parser: transient failure")
)

Sentinel errors. Parsers should wrap with fmt.Errorf("...: %w", err).

Types

type ChannelSnapshot

type ChannelSnapshot struct {
	Platform      Platform               `json:"platform"`
	Handle        string                 `json:"handle"`
	URL           string                 `json:"url"`
	FetchedAt     time.Time              `json:"fetched_at"`
	Followers     int64                  `json:"followers"`
	PostsCount    int64                  `json:"posts_count"`
	TotalLikes    int64                  `json:"total_likes,omitempty"`
	TotalViews    int64                  `json:"total_views,omitempty"`
	TotalComments int64                  `json:"total_comments,omitempty"`
	Raw           map[string]interface{} `json:"raw,omitempty"`
}

ChannelSnapshot is one point-in-time measurement of a channel's audience. Backends persist these as append-only rows; deltas are computed downstream.

type Parser

type Parser interface {
	Platform() Platform

	// FetchChannel returns the latest snapshot for handle.
	FetchChannel(ctx context.Context, handle string) (ChannelSnapshot, error)

	// FetchRecentPosts returns posts published since `since`. May return more
	// than requested by the caller; ordering is newest-first.
	FetchRecentPosts(ctx context.Context, handle string, since time.Time) ([]PostSnapshot, error)
}

Parser is the contract every per-platform module satisfies. Implementations should be stateless across calls; configuration is injected at construction time. All methods must respect ctx cancellation.

type Platform

type Platform string

Platform identifies a social network.

const (
	PlatformYouTube       Platform = "youtube"
	PlatformX             Platform = "x"
	PlatformTelegram      Platform = "telegram"
	PlatformFacebook      Platform = "facebook"
	PlatformInstagram     Platform = "instagram"
	PlatformLinkedIn      Platform = "linkedin"
	PlatformHabr          Platform = "habr"
	PlatformStackOverflow Platform = "stackoverflow"
	PlatformTBankPulse    Platform = "tbank_pulse"
	PlatformSmartLab      Platform = "smartlab"
	PlatformReddit        Platform = "reddit"
	PlatformGitHub        Platform = "github"
	PlatformGitHubRepo    Platform = "github_repo"
	PlatformDiscord       Platform = "discord"
	// PlatformMarketmakerAuth tracks the auth.marketmaker.cc registered-user
	// count via its public /stats/users-count endpoint. It's a project-level
	// metric rather than a per-user channel, but fits the same shape:
	// Followers = total user count.
	PlatformMarketmakerAuth Platform = "marketmaker_auth"
)

type PostKind

type PostKind string

PostKind narrows a Post by its native form on the platform.

const (
	PostKindPost  PostKind = "post"
	PostKindVideo PostKind = "video"
	PostKindShort PostKind = "short"
	PostKindStory PostKind = "story"
	PostKindReel  PostKind = "reel"
)

type PostSnapshot

type PostSnapshot struct {
	Platform      Platform               `json:"platform"`
	ChannelHandle string                 `json:"channel_handle"`
	PostID        string                 `json:"post_id"`
	URL           string                 `json:"url"`
	Kind          PostKind               `json:"kind"`
	PublishedAt   time.Time              `json:"published_at"`
	FetchedAt     time.Time              `json:"fetched_at"`
	Likes         int64                  `json:"likes"`
	Views         int64                  `json:"views"`
	Comments      int64                  `json:"comments"`
	Shares        int64                  `json:"shares,omitempty"`
	Raw           map[string]interface{} `json:"raw,omitempty"`
}

PostSnapshot is one measurement of a single post's engagement at FetchedAt.