parrot: write json api spec about aviary

[rabsef-bicrym]

Parrot

Parrot is like orca, but different.

+on-watch:

watch on /web-ui to get your facts. you'll get an initial load of facts that mirror those you find in +on-peek.

+on-peek:

• /blok:

  • get blocked hosts - people who invited you that you blocked

  {
    "type": "SCRY",
    "face": "BLOCKED-HOSTS",
    "fact": [
      "~zod/b-chat",
      "~nus/d-chat",
      "~wet/a-chat"
    ]
  }

• /pend:

  • get pending invitations - invitations you've been sent

  {
    "type": "SCRY",
    "face": "PENDING-INVITES",
    "fact": {
      "host": "~nus/my-chat",
      "invitation": {
        "area": "video-games",
        "note": "yo, join my flock",
        "when": 161234567
      }
    }
  }

• /sent

  • get sent invitations - invitations you sent out

  {
    "type": "SCRY",
    "face": "SENT-INVITES",
    "fact": [
      {
        "area": "video-games",
        "invites": [
          {
            "to": "~zod",
            "invitation": {
              "area": "video-games",
              "note": "yo, join my flock",
              "status": {
                //  "DELETED" (remove), "TRANSMITTED", "RECEIVED", "REJECTED", "AFFIRMED"
                "status": "RECEIVED",
                "when": null || 161234556
              }
            }
          }
        ]
      }
    ]
  }

• /flok

  • get existing flocks - chat federations you're in

  {
    "type": "SCRY",
    "face": "EXISTING-FLOCKS",
    "fact": [
      {
        "area": "video-games",
        "host": "~nus/gaming-one-oh-one",
        "team": [
          "~zod/gaming-two-three",
          "~wet/gamer-girls"
        ]
      }
    ]
  }

• /aval

  • available chats - chats that aren't in flocks yet

  {
    "type": "SCRY",
    "face": "AVAILABLE-CHATS",
    "fact": [
      "~rabsef-bicrym/a-chat-rabsef-hosts",
      "~rabsef-bicrym/a-chat-not-in-use"
    ]
  }

+on-poke

you can perform the following actions:

• form create a flock
• join join a flock based on an invite (or decline)
• drop leave a flock
• send send an invite
• blok block further invites from some host (flag)
• free unblock an invite from some host (flag)

form

• poke:

  {
    "form": {
      "area": "video-games",
      "chat": "~nus/gamer-dudes"
    }
  }

• response:

  {
   "type": "FACT",
   "face": "FLOCK-FLOCK-START",
   "fact": {
     "area": "video-games",
     "host": "~nus/gamer-dudes",
     "team": null
   }
  }

join

note: that joins can be sent as a poke to your own ship, or a fact to let everyone (the host, the team) know
note: sending a null "join" declines the invite

• poke:

{
  "join": {
    "host": "~nus/gamer-dudes",
    "join": null || "~rabsef-bicrym/my-game-chat"
  }

}

• response on decline:
  • poker

  {
    "type": "FACT",
    "face": "INVITE-REPLIED-BIRD",
    "fact": {
      "area": "video-games",
      "act": "DECLINED",
      "host": "~nus/gamer-dudes",
      "chat": null
    }
  }

  • host

  {
    "type": "FACT",
    "face": "INVITE-REPLIED-HOST",
    "fact": {
      "area": "video-games",
      "who": "~rabsef-bicrym",
      "status": {
        "status": "REJECTED",
        "when": 161234567
      }
    }
  }

• response on accept, all recipients (host and other flokmates)

  note: this would indicate "someone has joined this flock"

  {
    "type": "FACT",
    "face": "INVITE-REPLIED-BIRD",
    "fact": {
      "area": "video-games",
      "act": "ACCEPTED",
      "host": "~nus/gamer-dudes",
      "chat": "~rabsef-bicrym/my-game-chat"
    }
  }

drop

• poke

  {
    "drop": {
      "area": "video-games"
    }
  }

• response on the host or ourselves leaving:

  {
    "type": "FACT",
    "face": "FLOCK-FLOCK-CEASE",
    "fact": {
      "area": "video-games"
    }
  }

• response on a flockmate leaving

  {
    "type": "FACT",
    "face": "FLOCK-TEAM-REMOVE",
    "fact": {
      "area": "video-games",
      "what": "~rabsef-bicrym/gamer-bros"
    }
  }

send

sends are invitations sent by the host to some recipient.
only the recipient and the host are made aware of them.
if the recipient joins, everyone will be notified w/ a join;
if the recipient declines, only the host and the recipient know.
a send can be un-sent, see below:

• poke (to invite some set of people)

  {
    "send": {
      "area": "video-games",
      "buds": {
        "note": "hey - join my gamer flock",
        "them": [
          "~zod",
          "~wet",
          "~nus"
        ]
      }
    }
  }

  • response (to host)

    {
      "type": "FACT",
      "face": "INVITE-SEND-INVITES",
      "fact": {
        "area": "video-games",
        "buds": [
          "~zod",
          "~wet",
          "~nus"
        ]
      }
    }

  • response in recipient

    {
      "type": "FACT",
      "face": "INVITE-RECEIVED-BIRD",
      "fact": {
        "host": "~rabsef-bicrym/gamer-bros",
        "invite": {
          "area": "video-games",
          "note": "hey, join my gamer flock",
          "when": 161234567
        }
      }
    }

• poke to rescind an invitation that isn't already accepted

  {
    "send": {
      "area": "video-games",
      "buds": "~zod"
    }
  }

  • response (to host) - delete from sent invites

    {
      "type": "FACT",
      "face": "INVITE-STATUS-UPDATE",
      "fact": {
        "area": "video-games",
        "who": "~rabsef-bicrym",
        "status": {
          "status": "DELETED",
          "when": null
        }
      }
    }

  • response in recipient

    {
      "type": "FACT",
      "face": "INVITE-RECEIVED-BIRD",
      "fact": {
        "host": "~rabsef-bicrym/gamer-bros",
        "invite": "RESCINDED"
      }
    }

blok

blocks some flag from being used as a host in an invitation
this is primarily a precaution and does not need to be implemented.

• poke

  {
    "blok": {
      "flag": "~zod/test"
    }
  }

• response

  {
    "type": "FACT",
    "face": "BLOCK-LIST",
    "fact": {
      "host": "~zod/video-games",
      "act": "BLOCKED"
    }
  }

free

frees some flag that was previously bloked - they can invite you again.

• poke

  {
    "free": {
      "flag": "~zod/test"
    }
  }

• response - just delete them from the retained block list

  {
    "type": "FACT",
    "face": "BLOCK-LIST",
    "fact": {
      "host": "~zod/video-games",
      "act": "ALLOWED"
    }
  }

[rabsef-bicrym]

as written