spec.yaml

name: digg
display_name: Digg
description: "Digg: tail the AI story leaderboard, GitHub feeds, ranking-change history, and live ingestion pipeline events from the terminal. Read-only."
version: "0.2.0"
base_url: "https://di.gg"
cli_description: "Read-only CLI for Digg — the AI story leaderboard, GitHub feeds, and ingestion pipeline events on digg.com."

auth:
  type: none

config:
  format: toml
  path: "~/.config/digg-pp-cli/config.toml"

resources:
  trending:
    description: "Public ingestion-pipeline status and event stream"
    endpoints:
      status:
        method: GET
        path: "/api/trending/status"
        description: "Read the current pipeline status: storiesToday, clustersToday, isFetching, nextFetchAt, and the recent event stream (cluster_detected, fast_climb, post_understanding, batch_started, batch_breakdown, posts_stored, embedding_progress)."
        params: []
        response:
          type: object
          item: TrendingStatus

  feed:
    description: "Top-level story feed (HTML page; CLI parses the embedded RSC stream)"
    endpoints:
      raw:
        method: GET
        path: "/ai"
        description: "Fetch the raw /ai HTML page. The CLI's sync command parses this; most users should run `sync` then `top` instead of calling this directly."
        params: []
        response:
          type: object
          item: RawHTML

      story_raw:
        method: GET
        path: "/ai/{cluster_url_id}"
        description: "Fetch the raw /ai/{clusterUrlId} story detail page (HTML). The CLI's `story` command parses this; users should not need to call this directly."
        params:
          - name: cluster_url_id
            type: string
            required: true
            positional: true
            description: "Short alphanumeric cluster URL ID (8 chars), e.g. iq7usf9e"
        response:
          type: object
          item: RawHTML

  github:
    description: "GitHub feeds Digg surfaces alongside the X-account leaderboard (stars / new / activity / recent)."
    endpoints:
      stars:
        method: GET
        path: "/ai/github/stars"
        description: "Top AI repos ranked by starring activity from Digg-tracked accounts. Returns repo_full_name, language, stargazers_count, recent starrer list, breakout/novel/ai_related scores, and the model's one-sentence classification."
        params:
          # PATCH(digg-rankings-and-min-starrers): smart-money-convergence filter.
          - name: min-starrers
            type: int
            required: false
            description: "Keep only repos starred by >= N distinct Digg-tracked accounts (reads .repo.distinct_starrers, falls back to len(.repo.starrers) when absent). Applied BEFORE --limit. 0 = no filter; must be >= 0."
        response:
          type: object
          item: RawHTML

      new:
        method: GET
        path: "/ai/github/new"
        description: "Recently first-seen GitHub repos with the Digg-tracked creator/starrer who first put them on Digg's radar (event_id + event_created_at + creator)."
        params: []
        response:
          type: object
          item: RawHTML

      activity:
        method: GET
        path: "/ai/github/activity"
        description: "Top GitHub contributor leaderboard: per-author rank, contribution count, and distinct repos count over Digg's tracking window."
        params: []
        response:
          type: object
          item: RawHTML

      recent:
        method: GET
        path: "/ai/github/recent"
        description: "Live GitHub activity feed: per-event entries with the github.com URL (issue/PR/commit/repo), the user who acted, and a short description of the target."
        params: []
        response:
          type: object
          item: RawHTML

  # PATCH(digg-rankings-and-min-starrers): three sub-views of the
  # /ai/x/rankings/companies page, each parsed from a distinct section
  # of the same embedded RSC stream.
  rankings:
    description: "Rankings views Digg publishes alongside the AI 1000 leaderboard. Three sub-views of the /ai/x/rankings/companies snapshot."
    endpoints:
      emerging:
        method: GET
        path: "/ai/x/rankings/companies"
        description: "Curated list of small AI companies (the 'EMERGING STARTUPS — CURATED THIS SNAPSHOT' block). ~10 rows refreshed per snapshot. Mixes AI-judge-flagged emerging startups (IsEmergingStartup=true) with adjacent new entrants the curator surfaced."
        params:
          - name: max-skip-ratio
            type: float
            required: false
            description: "Schema-drift tolerance: fraction of entries that may fail to decode before the command exits non-zero. Default 0.10. Range [0, 1]."
        response:
          type: object
          item: RawHTML

      movers:
        method: GET
        path: "/ai/x/rankings/companies"
        description: "Companies whose follower count shifted most since the last snapshot. --direction up returns gainers, down returns losers, both returns both with direction stamped per row."
        params:
          - name: direction
            type: string
            required: false
            description: "Movers direction: up | down | both (default both)."
          - name: max-skip-ratio
            type: float
            required: false
            description: "Schema-drift tolerance (see emerging)."
        response:
          type: object
          item: RawHTML

      list:
        method: GET
        path: "/ai/x/rankings/companies"
        description: "Full company ranking — the 'Companies followed by the AI 2K' section. Server-paginated; this returns the initial-HTML slice (typically the top 50-200 entries)."
        params:
          - name: limit
            type: int
            required: false
            description: "Max rows to return from the initial-HTML slice (0 = all)."
          - name: max-skip-ratio
            type: float
            required: false
            description: "Schema-drift tolerance (see emerging)."
        response:
          type: object
          item: RawHTML

types:
  TrendingStatus:
    fields:
      - name: computedAt
        type: string
      - name: nextFetchAt
        type: string
      - name: lastFetchCompletedAt
        type: string
      - name: isFetching
        type: bool
      - name: storiesToday
        type: int
      - name: clustersToday
        type: int

  RawHTML:
    fields:
      - name: body
        type: string