design and implement scry api for FE use.

• full state
• blok
• pend
• sent
• flok
• available chats - use as hosts or flok-mates - will make sure u don't double up.

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"
    }
  }

Osprey

PLEASE USE rb/osprey-on-wire as a starting point

Osprey is a mixture of Peat, Expo and Doombot. If you take a device intended for
murder, and add to it some administrative overhead, you get a bird of prey. thus

NOTE: though osprey has the ability to backup dms and clubs, it does not have the ability to restore those messages built in. they are stored in a different format and the business logic for restoring them is not perfectly clear. i will discuss with tlon later. please do not implement features for backing up / restoring dms at this time.

+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:

• /every

  • get all used flags across everything - we use this as a shorthand check so we don't have to check per type

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-EVERY",
    "fact": [
      "~zod/test-chat",
      "~zod/test-heap",
      "~zod/test-note"
    ]
  }

• /dms

  • get existing DMs

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-DMS",
    "fact": [
      "~zod",
      "~wet",
      "~nut"
    ]
  }

• /chats

  • get existing chats

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-CHAT",
    "fact": [
      "~zod/test-chat",
      "~zod/test-chat-2",
      "~zod/test-chat-3"
    ]
  }

• /heaps

  • get existing heaps

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-HEAPS",
    "fact": [
      "~zod/test-heap",
      "~zod/test-heap-2",
      "~zod/test-heap-3"
    ]
  }

• /groups

  • get existing groups

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-GROUPS",
    "fact": [
      "~zod/group",
      "~zod/group-2",
      "~zod/group-3"
    ]
  }

• /diaries

  • get existing diaries

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-DIARIES",
    "fact": [
      "~zod/test-diary",
      "~zod/test-diary-2",
      "~zod/test-diary-3"
    ]
  }

• /schedule

  • schedule state object

  {
    "type": "SCRY",
    "face": "OSPREY-STATE-SCHEDULE",
    "fact": [
      {
        "last": 123456,
        "next": 123456,
        "area": {
          "type": "HEAP" || "ALL-HOSTED", // in the latter case, no further data
          "flag": "~zod/this",
        }
      }
    ]
  }

• /mailslot

  • mailslot state object

  {
    "type": "SCRY",
    "face": "OSPREY-STATE-MAILSLOT",
    "fact": {
      "~zod": [
        {
          "group": "~zod/this",
          "data": {
            "members": ["~zod" "~wet"],
            "admins":  ["~zod"],
            "domain": {
              "first": 161243124,
              "last": 162123124,
              "hash": "0v1234"
            },
            "included-files": [
              {
                "type": "chat",
                "flag": "~zod/chat"
              }
            ]
          }
        }
      ]
    }
  }

• /on-trial

  • on-trial state object

  {
    "type": "SCRY",
    "face": "OSPREY-STATE-ON-TRIAL",
    "fact": {
      "0v1234" : {
        "flag": "~zod/flag",
        "type": "doom",
        "limit": "12",
        "age": "~d30",
        "ships": [
          "~zod",
          "~wet"
        ]
      },
      "0v2345": {
        "flag": "~zod/flag",
        "type": "boot",
        "rank": "czar",
        "ships": [
          "~zod",
          "~wet"
        ]
      },
    }
  }

+on-poke:

you can perform the following actions

• archive an archive backs up an existing channel, once.
  • [%mine ~] - all channels you host
  • [%heap [ship term]] - a specific heap
  • [%chat [ship term]] - a specific chat
  • [%diary [ship term]] - a specific diary
  • [%group [ship term]] - the resources in a specific group

Note: strongly encourage users to utilize [%mine ~] on a discretionary basis, e.g. full system failure. While it's fine to use [%mine ~] on a recurring basis, it might take a lot of system resources.
Note: currently there is no protection for rapid recurring output - this will be added in for the user at no more often than ever 12 hours. For testing purposes, you can put in a few minutes (no less than 1 minute).

• repeat set an archive repetition schedule, or cancel it.

• doom prepare to kick some people who you haven't seen for a while.

• boot prepare to kick (but not ban) ships in a group, of a given rank.

• exec kick the people prepared in a specific instance.

• stop pardon the people prepared in a specific instance.

• restore restore a chat from backup - note this isn't a poke, only file upload.

• virtual use a wire to backup and restore a group

  • [%open who=@p wat=flag] - open a slot for someone to send a specific group (wat)
  • [%mail who=@p wat=flag] - send a group to someone
  • [%kill who=@p wat=flag] - delete a slot/the data
  • [%take *] - NOT FOR U - DO NOT USE

  • $:  %read
        who=@p
        wat=flag
        wer=@tas
        wit=[mem=? adm=?]
        wic=(list [hed=?(%chat %heap %note) wat=flag wer=@tas])
    ==

    • read an email from someone (who wat), recreating it in new group (wer), maybe including the members or admins (wit) and for any items you want to recreate, give a realignment method [?(%chat %heap %note) wat=flag wer=@tas]

archive

• poke:
  • mine:

    {
      "mine": null
    }

  • heap:

    {
      "heap": "~zod/test-heap"
    }

  • diary:

    {
      "diary": "~zod/test-diary"
    }

  • group:

    {
      "group": "~zod/my-group"
    }

  • chat:

    {
      "chat": {
        "flag": "~zod/a-chat" ||,
        "ship": "~wet" ||,  //a dm
        "club": "0v123456"  //a club
      }
    }

  • response (immediate):

    {
      "type": "FACT",
      "face": "ARCHIVE-START",
      "fact": {
        "archiving": <an archive json as above in the poke section>
      }
    }

  • response (incremental):

    {
      "type": "FACT",
      "face": "ARCHIVE-STATUS-UPDATE",
      "fact": {
        "archiving": <an archive json as above in the poke section>,
        "total": 10,   // count of total jam files to be produced, roughly
        "complete": 8, // count of completed jams
        "done": false  // will print as true when complete
      }
    }

repeat

• poke:

  {
    "repeat": {
      "archive": { "mine": null },  // or some other arrangement
      "frequency": 1000 // every x seconds
    }
  }

• response (on schedule):

  {
    "type": "FACT",
    "face": "ARCHIVE-SCHEDULE-SET",
    "fact": {
      "archiving": <an archive json as above>,
      "frequency": 1000  // number of seconds
    }
  }

• response (on cancel):

  {
    "type": "FACT",
    "face": "ARCHIVE-SCHEDULE-CANCEL",
    "fact": {
      "archiving": <an archive json as above>,
      "frequency": null
    }
  }

NOTE: when an archive schedule triggers, you'll get archive-start and other status updates as with a one off; expect them.

restore

• thread-report (working)

  {
    "type": "FACT",
    "face": "RESTORE-PROGRESS",
    "fact": {
      "channel-type": "chat",
      "progress": "0.333333333" (this will go up to ideally 100? lol you'll get a done when it's done),
      "group": {
        "type": "OLD" || "NEW",
        // if old, then:
        "flag": "~zod/this",
        // else if new, then:
        "name": "cool-chat"
      }
    }
  }

• thread-report (done)

  {
    "type": "FACT",
    "face": "RESTORE-STATUS-UPDATE",
    "fact": {
      "channel-type": "chat",
      "succeeded": true,
      "group": {
        "type": "OLD" || "NEW",
        // if old, then:
        "flag": "~zod/this",
        // else if new, then:
        "name": "cool-chat"
      }
    }
  }

doom

• poke:

  {
    "doom": {
      "limit": 10, //only allow for kicking up to 10 users
      "age": 1000, //limit for QOS kick - this case would be people last seen more than 1000 seconds ago,
      "group": "~zod/this-group"
    }
  }

• response (instant):

  {
    "type": "FACT",
    "face": "KICK-DOOMING",
    "fact": {
      "seconds": 1000,
      "group": "~zod/this-group"
    }
  }

boot

• poke

  {
    "boot": {
      "rank": "pawn", // or czar king duke earl see 4938 of zuse
      "group": "~zod/test-group"
    }
  }

• response (instant):

  {
    "type": "FACT",
    "face": "KICK-BOOTING",
    "fact": {
      "rank": "pawn",
      "group": "~zod/this-group"
    }
  }

exec

• poke

  {
    "exec": {
      "id": "0v1234"
    }
  }

• response (instant):

  {
    "type": "FACT",
    "face": "KICK-EXECUTING",
    "fact": {
      "id": "0v1234"
    }
  }

stop

• poke

  {
    "exec": {
      "id": "0v1234"
    }
  }

• response (instant):

  {
    "type": "FACT",
    "face": "KICK-PARDONING",
    "fact": {
      "id": "0v1234"
    }
  }

virtual

• mail

  • poke

    {
      "mail": {
        "recipient": "~zod",
        "group": "~wet/old-group"
      }
    }

  • response (immediate/host)

    {
      "type": "FACT",
      "face": "VIRTUAL-SEND-MAILS",
      "fact": {
        "recipient": "~zod",
        "group": "~wet/old-group"
      }
    }

  • response (recipient)

    {
      "type": "FACT",
      "face": "VIRTUAL-MAIL-RECEIVED",
      "fact": {
        "group": "~wet/old-group"
      }
    }

  • response (complete)

    {
      "type": "FACT",
      "face": "VIRTUAL-SENT-MAIL",
      "fact": {
        "old-group": "~wet/old-group",
        "old-graphs": ["~wet/test-chat"]
      }
    }

• open

  • poke

    {
      "open": {
        "host": "~zod",
        "group": "~wet/old-group"
      }
    }

  • response (immediate/host)

    {
      "type": "FACT",
      "face": "VIRTUAL-OPEN-MAILSLOT",
      "fact": {
        "host": "~zod",
        "group": "~wet/old-group"
      }
    }

• kill

  • poke

    {
      "kill": {
        "host": "~zod",
        "group": "~wet/old-group"
      }
    }

  • response (immediate/host)

    {
      "type": "FACT",
      "face": "VIRTUAL-CLOSE-MAILSLOT",
      "fact": {
        "host": "~zod",
        "group": "~wet/old-group"
      }
    }

• read

  • poke

    {
      "read": {
        "host": "~zod",
        "group": "~wet/old-group",
        "new-group-name": "new-group",
        "roster": {
          "members": false,
          "administrators": true
        },
        "include": [
          {
            "type": "chat" || "heap" || "note",
            "old-resource": "~zod/test-chat",
            "new-resource-name": "new-test"
          }
        ]
      }
    }

  • response (immediate/host)

    {
      "type": "FACT",
      "face": "VIRTUAL-READ-MAIL-TO-GROUPS",
      "fact": {
        "old-host": "~zod",
        "old-group": "~wet/old-group",
        "new-group": "new-group",
        "include-members": false,
        "include-administrators": true,
        "include-resources": [
          {
            "type": "chat" || "heap" || "note",
            "old-resource": "~zod/test-chat",
            "new-resource": "new-test"
          }
        ]
      }
    }

  • response (complete)

    {
      "type": "FACT",
      "face": "VIRTUAL-READ-MAIL-TO-GROUPS-COMPLETE",
      "fact": {
        "new-group": "~nus/phoenix",
        "new-graphs": ["~nus/phoenix-chat"],
        "include-members": false,
        "include-administrators": true
      }
    }

maybe?

Home screen that indicates the following capacities (maybe imagemap?):

• Parrot - like Orca
• Osprey - Echo, DoomBot, and Peat in One
• Corvid - the last chatbot you'll need on Groups2

Client requests backup and restore, automatically, over the wire

• Clean up on drop
• Get Joins
• Everyone avoids duping the message