DESK TAKEOVER API
=================

Rob has a TRMNL e-ink display on his desk. It is 800 by 480 pixels, pure
black and white, no grey. A takeover is a picture or a few words that replaces his
normal screen for a chosen time. You queue one here; his Mac pulls the queue every
few minutes and puts it up. Nothing is instant, so expect up to 15 minutes.

AUTHENTICATION
--------------
Every contributor has a personal token. Send it as a bearer token:

  Authorization: Bearer YOUR_TOKEN

The server stores only the sha256 of each token, so a lost token cannot be read back
from here, it has to be replaced. If you get a 401, your token is wrong or retired.

ERRORS
------
Every failure is JSON, with the same shape, and the sentence says what to change:

  {"ok": false, "error": "Set \"minutes\" to one of 15, 30, 60, 120."}

POST /api/takeover
------------------
Queue a takeover. JSON body:

  kind        "image" or "text", required
  png_base64  base64 of the PNG file, images only
  text        1 to 240 characters, words only
  caption     optional, up to 60 characters, shown small under the picture or words
  minutes     one of 15, 30, 60, 120, how long it stays up

Returns {"ok": true, "id": "...", "status": "queued"}.

PICTURE RULES
-------------
  The PNG must be exactly 800 by 480 pixels.
  It must be 90,000 bytes or smaller once decoded.
  The screen has no grey. Send 1 bit black and white, dithered if the source is a photo.
  Measured on this encoder: an 800 by 480 file at bit depth 1,
  colour type 0, comes to 0.2 KB for flat artwork, 32 KB for a dithered photograph and
  47 KB for pure noise, which is the ceiling. So the limit is never in the way if you do
  the dithering yourself. An 8 bit or RGBA PNG of the same picture is often too big, and
  the screen will threshold it anyway.
  Atkinson dithering suits e-ink better than Floyd and Steinberg: fewer stray dots.

WORDS RULES
-----------
  1 to 240 characters, trimmed. The screen sets them in the house type as large as
  they fit, so short reads better. Line breaks are kept.

HOW OFTEN
---------
  6 takeovers per contributor per rolling 24 hours. Over that you get a 429 and a
  sentence saying when the next slot frees up.

GET /api/mine
-------------
Your last 10 submissions, newest first, no image data. Each carries a status:

  queued     waiting for the next pull
  showing    on the screen now, see "until"
  shown      it has been up and come down
  rejected   it was not shown, see "note"

EXAMPLES
--------
Words:

  curl -sS -X POST https://desk-takeover.pages.dev/api/takeover \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "content-type: application/json" \
    -d '{"kind":"text","text":"Back Tuesday. Water the plants.","minutes":60}'

Picture, from a file called takeover.png:

  curl -sS -X POST https://desk-takeover.pages.dev/api/takeover \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "content-type: application/json" \
    -d "$(jq -n --arg p "$(base64 < takeover.png | tr -d '\n')" \
          '{kind:"image", png_base64:$p, caption:"From Maya", minutes:30}')"

Your recent submissions:

  curl -sS https://desk-takeover.pages.dev/api/mine -H "Authorization: Bearer YOUR_TOKEN"

THE REST
--------
/api/pull and /api/ack belong to Rob's Mac and need a different key. They are not
part of the contributor API.