GitHub Followers

# @name    GitHub Followers
# @desc    Follower count from the GitHub users API
# @author  Golevka2001
# @version 1.1
# @config  user    text    "Username"  help="Required. github.com/<username>"
# @config  token   text    "Token"     help="Optional. Raises the rate limit from 60 to 5000/hour"
# @config  ic      text    "Icon ID"   default="71442"  help="LaMetric icon ID"
# @config  every   number  "Refresh"   default=60  min=1  unit=min

import string

class GithubFollowers
  var url, hdr, units, label, tx, tc, ic, err
  # refresh countdown + failure backoff, see due()/failed()/ok()/now()
  var ticks, span, retry, busy

  def init()
    # saving a setting restarts the app, so the URL and headers built here never
    # go stale. Username is required (as in github-heatmap); a token is optional
    # and only raises the rate limit, it never replaces the username.
    var t = store.get("token")
    var u = store.get("user")
    self.url = ""
    # GitHub answers 403 without a User-Agent
    self.hdr = {'User-Agent': "awtrix-github-followers",
                'Accept': "application/vnd.github+json",
                'X-GitHub-Api-Version': "2022-11-28"}
    if u != nil && u != ""
      self.url = "https://api.github.com/users/" + str(u)
      if t != nil && t != ""
        self.hdr['Authorization'] = "Bearer " + str(t)
      end
    end

    self.units = ["", "k", "M", "B", "T"]

    self.label = self.url == "" ? "SET?" : "..."
    self.tx = 9
    self.tc = 0xFFFFFF
    self.ic = ""
    self.ticks = 0
    self.span = 60
    self.retry = 30
    self.busy = false
    self.err = false
  end

  # first fetch + fill display state before the first frame
  def setup()
    self.loop()
  end

  # select forces a refresh; left and right just rotate
  def on_button(btn)
    if btn == "select"
      self.now()
    end
  end

  def on_body(body, status)
    shared.set("f", 0)
    # non-200 or nil body: nothing usable this attempt
    if status != 200 || body == nil
      self.failed()
      return
    end
    # ` *` tolerates the pretty-printed space after the colon; the colon keeps
    # the needle off the earlier "followers_url" field
    var m = re.search("\"followers\": *(\\d+)", body)
    if m == nil
      self.failed()
      return
    end
    var n = num(m[1])
    if n == nil
      self.failed()
      return
    end
    self.ok()

    # format here, not in draw() -- draw() must not allocate
    var d = 1
    var i = 0
    # promote at 999.5 so a count rounding up to 1000 becomes 1.00 of the next unit
    while n >= d * 999.5 && i < 4
      d *= 1000
      i += 1
    end
    if i == 0
      self.label = str(int(n))
    else
      var v = n * 1.0 / d             # * 1.0 forces real division
      # cut on the rounded value so 9999 reads "10.0k", never "10.00k"
      if v < 9.995
        self.label = string.format("%.2f", v) + self.units[i]
      elif v < 99.95
        self.label = string.format("%.1f", v) + self.units[i]
      else
        self.label = str(round(v)) + self.units[i]
      end
    end
  end

  def loop()
    # url checked first: due() raises busy as a side effect
    if self.url != "" && self.due(store.get("every"))
      shared.set("f", 1)
      http.get(self.url, / b, st -> self.on_body(b, st),
               {'headers': self.hdr, 'find': "\"followers\":", 'keep': 24})
    end

    # while there is no reading yet, the placeholder reflects the last attempt
    if self.label == "..."
      self.label = self.err ? "?" : "..."
    end
    self.tx = 9 + int((width() - 9 - text_ink_width(self.label)) / 2)
    self.ic = store.get("ic")
    self.tc = settings.get("textColor")
    if self.tc == nil self.tc = 0xFFFFFF end
    if self.label == "?" self.tc = 0xCC7722 end
  end

  # Fires at most once per interval, never while a request is out or another
  # app's TLS handshake is running (shared "f" flag, official convention).
  # Raises busy, so only call it when a request will actually be issued.
  def due(every)
    self.span = max(60, num(every, 1) * 60)
    if self.ticks > 0
      self.ticks = self.ticks - 1
      return false
    end
    if self.busy
      return false
    end
    for k : shared.keys()
      var n = size(k)
      if n > 2 && k[n - 2 .. n - 1] == ".f" && shared.get(k) == 1
        var a = shared.age(k)
        if a != nil && a < 20000
          return false
        end
      end
    end
    self.ticks = self.span
    self.busy = true
    return true
  end

  # failure backoff: retry at 30s, doubling, capped at the interval; raises
  # err so a fetch with no data yet can show "?" instead of "..."
  def failed()
    self.busy = false
    self.ticks = self.retry
    self.retry = min(self.retry * 2, self.span)
    self.err = true
  end

  def ok()
    self.busy = false
    self.retry = 30
    self.err = false
  end

  # manual refresh: clears the countdown but leaves busy alone, so a press
  # while a request is out can't fire a second one
  def now()
    self.ticks = 0
    self.retry = 30
  end

  def draw()
    clear()
    if !icon(self.ic, 0, 0)
      rect_fill(0, 0, 8, 8, 0x222222)
    end
    text(self.tx, 6, self.label, self.tc)
  end
end

return GithubFollowers()

These icons belong on the device, in /ICONS. Each one is at most 32×8 pixels — shown here magnified, at their real proportions.