api

type APIError struct {
	// Status is the HTTP status code.
	Status int
	// Code is the machine-readable code from the envelope ("" when absent).
	Code string
	// Message is human-readable; never empty.
	Message string
	// Body is the raw response body, retained so a caller can read a
	// non-envelope payload the generic decoder ignores — e.g. the feed-sync
	// 502 answers with {"summary":{...}} (carrying the failure reason) rather
	// than the error envelope. Nil when the response had no body.
	Body []byte
}

type APIKey struct {
	ID        string  `json:"id"`
	Name      string  `json:"name"`
	Start     *string `json:"start"`
	Prefix    *string `json:"prefix"`
	Key       string  `json:"key"`
	ExpiresAt *string `json:"expiresAt"`
}

type AdminListing struct {
	Listing
	Source string `json:"source"`
}

type AdminPost struct {
	Post
	Source string `json:"source"`
}

type AdminProfile struct {
	Profile
	Source string `json:"source"`
}

type AdminSoul struct {
	Soul
	Source string `json:"source"`
}

type Anonymous struct{}

type BotData struct {
	// Prompt is the paste-ready instruction the bot runs on each fire.
	Prompt string `json:"prompt"`
	// Integrations are services the bot is wired to (e.g. github, slack).
	Integrations []string `json:"integrations,omitempty"`
	// Schedule is the cron expression the bot fires on, if any.
	Schedule string `json:"schedule,omitempty"`
	// Platforms are harnesses the bot is known to run on.
	Platforms []string `json:"platforms,omitempty"`
	// SoulSlug is the soul this bot is paired with, if any.
	SoulSlug string `json:"soulSlug,omitempty"`
}

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

type Credentials struct {
	// APIKey is sent as the x-api-key header.
	APIKey string
	// Bearer is sent as "Authorization: Bearer ..." when APIKey is empty.
	Bearer string
}

type CredentialsProvider interface {
	Get() (Credentials, error)
}

type EnvCredentials struct{}

type FeedSource struct {
	// ID is the stable, immutable id (ULID).
	ID    string `json:"id"`
	Label string `json:"label"`
	// FeedURL is the github_release repo URL or the rss feed URL.
	FeedURL string `json:"feedUrl"`
	// Kind is one of FeedKinds: github_release | rss.
	Kind string `json:"kind"`
	// AuthorProfileID/AuthorHandle are the default byline stamped on mirrored
	// posts; the handle is left-joined for display. Null when unattributed.
	AuthorProfileID *string `json:"authorProfileId"`
	AuthorHandle    *string `json:"authorHandle"`
	// ListingID/ListingSlug are the related tool stamped on mirrored posts; the
	// slug is left-joined for display. Null when none.
	ListingID   *string `json:"listingId"`
	ListingSlug *string `json:"listingSlug"`
	// DefaultCategory is one of BlogCategories.
	DefaultCategory string   `json:"defaultCategory"`
	DefaultTags     []string `json:"defaultTags"`
	// AutoPublish publishes mirrored posts immediately instead of as drafts.
	AutoPublish bool `json:"autoPublish"`
	// Enabled is the on/off switch; false pauses the feed (there is no delete).
	Enabled bool `json:"enabled"`
	// LastFetchedAt/LastStatus record the last ingest run — null until the
	// first run; LastStatus is "ok" or the last error message (fail-loud).
	LastFetchedAt *string `json:"lastFetchedAt"`
	LastStatus    *string `json:"lastStatus"`
	CreatedAt     string  `json:"createdAt"`
	UpdatedAt     string  `json:"updatedAt"`
}

type FeedSyncSummary struct {
	FeedID  string `json:"feedId"`
	Label   string `json:"label"`
	Fetched int    `json:"fetched"`
	Created int    `json:"created"`
	Updated int    `json:"updated"`
	Skipped int    `json:"skipped"`
	// ItemErrors holds per-item failures on an otherwise-successful run; each
	// such item is counted in Skipped.
	ItemErrors []string `json:"itemErrors"`
	// Error is the fetch/parse failure reason; empty on success.
	Error string `json:"error,omitempty"`
}

type Listing struct {
	// ID is the stable, immutable id (ULID).
	ID string `json:"id"`
	// Slug is the human-facing url segment: /listings/[slug].
	Slug string `json:"slug"`
	// ProfileHandle/ProfileName denormalize the authoring profile for cards.
	ProfileHandle string `json:"profileHandle"`
	ProfileName   string `json:"profileName"`
	// ProfileTier is the author's seal — "official" | "verified" | null.
	ProfileTier *string `json:"profileTier"`
	Name        string  `json:"name"`
	// Type is one of ListingTypes.
	Type string `json:"type"`
	// Tagline is the short one-liner shown on cards.
	Tagline     string   `json:"tagline"`
	Description *string  `json:"description"`
	Category    string   `json:"category"`
	Tags        []string `json:"tags"`
	// Official is true when published by the owner's verified official account.
	Official bool `json:"official"`
	// SourceURL is the official source that was verified: repo, docs, or registry.
	SourceURL string  `json:"sourceUrl"`
	RepoURL   *string `json:"repoUrl"`
	// InstallCmd is the canonical official install/run command, if any.
	InstallCmd *string `json:"installCmd"`
	// Data holds type-specific extras (e.g. LoopData for loops, SkillData for
	// skills, BotData for bots); {} when none.
	Data map[string]any `json:"data"`
	// HasAsset is true when a hosted SKILL.md asset exists for this (skill) listing.
	HasAsset bool `json:"hasAsset"`
	// AssetVersion is the hosted asset's semver, or null when HasAsset is false.
	AssetVersion *string `json:"assetVersion"`
	// AssetContentHash is the sha256 of the hosted asset body, or null — lets
	// clients skip identical re-downloads.
	AssetContentHash *string `json:"assetContentHash"`
	Confidence       string  `json:"confidence"`
	Status           string  `json:"status"`
	DownloadCount    int     `json:"downloadCount"`
	// ChargeCount is the running count of user "charges" (the energy boost).
	ChargeCount int    `json:"chargeCount"`
	CreatedAt   string `json:"createdAt"`
	UpdatedAt   string `json:"updatedAt"`
}

type LoopData struct {
	// Goal is what "done" looks like for the loop.
	Goal string `json:"goal,omitempty"`
	// CheckCommand is the command run between iterations to gauge progress.
	CheckCommand string `json:"checkCommand,omitempty"`
	// ExitCondition is the condition that ends the loop.
	ExitCondition string `json:"exitCondition,omitempty"`
	// MaxIterations is the safety cap on iterations.
	MaxIterations int `json:"maxIterations,omitempty"`
	// CompatibleTools lists agents/harnesses the loop is known to work with.
	CompatibleTools []string `json:"compatibleTools,omitempty"`
	// Kickoff is the prompt a user copies to start the loop.
	Kickoff string `json:"kickoff,omitempty"`
	// Bundles are slugs of listings this loop depends on (a loop usually drives
	// several skills).
	Bundles []string `json:"bundles,omitempty"`
}

type Me struct {
	User    User `json:"user"`
	IsAdmin bool `json:"isAdmin"`
}

type Option func(*Client)

type Post struct {
	PostCard
	Content string `json:"content"`
}

type PostCard struct {
	// ID is the stable, immutable id (ULID).
	ID string `json:"id"`
	// Slug is the human-facing url segment: /blog/[slug].
	Slug string `json:"slug"`
	// SlugHistory holds previous slugs; the server 301s them to the current slug.
	SlugHistory []string `json:"slugHistory"`
	// Kind is one of PostKinds: article | release | link.
	Kind  string `json:"kind"`
	Title string `json:"title"`
	// Excerpt is the short summary shown on cards and in the RSS feed.
	Excerpt string `json:"excerpt"`
	// Description is an optional longer SEO description.
	Description *string `json:"description"`
	// ContentHash is the sha256 of the normalized markdown body — the citation/dedup anchor.
	ContentHash string `json:"contentHash"`
	// Version is semver.
	Version  string   `json:"version"`
	Category string   `json:"category"`
	Tags     []string `json:"tags"`
	// AuthorHandle/AuthorName denormalize the authoring profile for cards; null when authorless.
	AuthorHandle *string `json:"authorHandle"`
	AuthorName   *string `json:"authorName"`
	// AuthorAvatar is the author's avatar URL; null falls back to the brand mark.
	AuthorAvatar *string `json:"authorAvatar"`
	// AuthorTier is the author's seal — "official" | "verified" | null.
	AuthorTier *string `json:"authorTier"`
	// ListingSlug/ListingName link a post about a registry tool to that listing; null otherwise.
	ListingSlug *string `json:"listingSlug"`
	ListingName *string `json:"listingName"`
	// CanonicalURL backlinks to the original GitHub release / RSS item; null for native posts.
	CanonicalURL *string `json:"canonicalUrl"`
	// Status is draft | pending | published.
	Status string `json:"status"`
	// ViewCount is the running page-view count.
	ViewCount int `json:"viewCount"`
	// PublishedAt is the canonical publish instant; null while unpublished.
	PublishedAt *string `json:"publishedAt"`
	CreatedAt   string  `json:"createdAt"`
	UpdatedAt   string  `json:"updatedAt"`
}

type Profile struct {
	// ID is the stable, immutable id (ULID).
	ID string `json:"id"`
	// Handle is the human-facing handle: /profiles/[handle].
	Handle string `json:"handle"`
	Name   string `json:"name"`
	// Kind is person | org.
	Kind string `json:"kind"`
	// Verified is the white seal (team-curated or claimed); Official is the red seal.
	Verified  bool    `json:"verified"`
	Official  bool    `json:"official"`
	Website   *string `json:"website"`
	GithubURL *string `json:"githubUrl"`
	// GithubUserID is the immutable GitHub numeric id (person profiles).
	GithubUserID *string `json:"githubUserId"`
	AvatarURL    *string `json:"avatarUrl"`
	Bio          *string `json:"bio"`
	// Socials are public http(s) URLs.
	Socials   []string `json:"socials"`
	CreatedAt string   `json:"createdAt"`
	UpdatedAt string   `json:"updatedAt"`
}

type ResearchItem struct {
	Slug     string   `json:"slug"`
	Title    string   `json:"title"`
	Excerpt  string   `json:"excerpt"`
	Kind     string   `json:"kind"`
	Category string   `json:"category"`
	Tags     []string `json:"tags"`
	// URL is the absolute permalink: /blog/[slug].
	URL string `json:"url"`
	// MdURL is the absolute raw-markdown endpoint: /api/blog/[slug].md.
	MdURL        string  `json:"mdUrl"`
	CanonicalURL *string `json:"canonicalUrl"`
	ContentHash  string  `json:"contentHash"`
	PublishedAt  *string `json:"publishedAt"`
}

type ResearchQuery struct {
	// Q is a free-text query over title/excerpt.
	Q string
	// Kind narrows to one of PostKinds (article, release, link).
	Kind string
	// Category narrows to one blog category.
	Category string
	// Tag narrows to posts carrying this tag.
	Tag string
	// Since is an ISO-8601 instant; only posts published strictly after it are
	// returned (the delta since a previous poll).
	Since string
	// Limit caps the result count (server range 1–100). 0 omits the param and
	// takes the server default.
	Limit int
}

type ResearchResult struct {
	Results []ResearchItem `json:"results"`
	Latest  *string        `json:"latest"`
}

type SkillData struct {
	// Bundles are slugs of listings this skill bundles — its install-time deps.
	Bundles []string `json:"bundles,omitempty"`
}

type Soul struct {
	SoulCard
	Content string `json:"content"`
}

type SoulCard struct {
	// ID is the stable, immutable id (ULID). Never changes, even if the slug does.
	ID string `json:"id"`
	// Slug is the human-facing url segment: /souls/[slug].
	Slug string `json:"slug"`
	// SlugHistory holds previous slugs; the server 301s them to the current slug.
	SlugHistory []string `json:"slugHistory"`
	Name        string   `json:"name"`
	// AuthorHandle is the author handle — the join key for user accounts.
	AuthorHandle string  `json:"authorHandle"`
	AuthorName   *string `json:"authorName"`
	AuthorURL    *string `json:"authorUrl"`
	// Tagline is the short one-liner shown on cards.
	Tagline     string   `json:"tagline"`
	Description *string  `json:"description"`
	Category    string   `json:"category"`
	Tags        []string `json:"tags"`
	Frameworks  []string `json:"frameworks"`
	Models      []string `json:"models"`
	// Version is semver.
	Version string `json:"version"`
	// License is an SPDX license id, e.g. "MIT".
	License string  `json:"license"`
	RepoURL *string `json:"repoUrl"`
	// ContentHash is the sha256 of the normalized SOUL.md body.
	ContentHash string `json:"contentHash"`
	// Status is draft | pending | published.
	Status        string `json:"status"`
	DownloadCount int    `json:"downloadCount"`
	// ChargeCount is the running count of user "charges" (the energy boost).
	ChargeCount int      `json:"chargeCount"`
	RatingAvg   *float64 `json:"ratingAvg"`
	RatingCount int      `json:"ratingCount"`
	ArenaRank   *int     `json:"arenaRank"`
	CreatedAt   string   `json:"createdAt"`
	UpdatedAt   string   `json:"updatedAt"`
}

type User struct {
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Email       string  `json:"email"`
	Image       *string `json:"image"`
	GithubLogin *string `json:"githubLogin"`
}