Add GraphQL API for managing rooms

guides/api.md

@@ -0,0 +1,237 @@
+# Overview
+Reticulum includes a [GraphQL](https://graphql.org/) API to better allow you to customize the app to your specific needs. 
+
+## Accessing the API
+The API can be accessed by sending `GET` or `POST` requests to `/api/v2/`.
+Requests can be sent in code with an `HTTP` client library, on the command line with a tool like `curl`, with a GraphQL-specific client library, or any other tool that speaks `HTTP`. There is also an interactive GUI for accessing the API available at `/api/v2/graphiql`. 
+
+## Authenticating requests
+Most requests sent to the API need to be authenticated. To authenticate a request, add the http header `Authorization` with value `Bearer: <your API token>`. Currently, your API token is the same as your account token, which you can find with the following steps:
+- Navigate to the homepage
+- Sign in
+- Open the developer console of your browser. (
+Instructions for opening the console in firefox: https://developer.mozilla.org/en-US/docs/Tools/Web_Console#Opening_the_Web_Console
+Instructions for chrome: https://developers.google.com/web/tools/chrome-devtools/open)
+- Type `window.APP.store.state.credentials.token` into the console and press enter.
+- Your token should be returned surrounded by quotations marks (`"<your API token here>"`)
+
+It is likely that the authentication method will change in future releases of the API to include something like API tokens whose permissions can be limited to specific scopes, so that people are not encouraged to share admin account tokens. Sharing account tokens is dangerous - don't do it.
+
+## Passing arguments
+We use a library called [`absinthe`](http://absinthe-graphql.org/) to power the `GraphQL` API. This library automatically converts between `camelCase` (a typical convention in `javascript`) and `snake_case` (a typical convention in `elixir`). For this reason, you will send and receive arguments and values in `camelCase`, but will see the corresponding values in `elixir` code as `snake_case`.
+
+## Rooms
+The following examples show the capabilities of creating, querying, and modifying rooms. The code for these commands and object types can be found in [`/lib/ret_web/schema/room_types.ex`](../lib/ret_web/schema/room_types.ex)
+
+### Create a room
+Request:
+```
+mutation {
+  createRoom(name:"My Fun Get-Together"){
+    id
+  }
+}
+```
+Response:
+```js
+{
+  "data": {
+    "createRoom": {
+      "id": "3FqxixG"
+    }
+  }
+}
+```
+
+### Querying Rooms
+Room queries return a `RoomList` object, which paginates responses. For a specific page or page size, pass the `page` or `pageSize` arguments along with  the request. 
+
+#### My rooms
+Request:
+```
+query {
+  myRooms(page: 1, pageSize: 10) {
+    entries {
+      name,
+      id,
+      scene {
+        ... on Scene {
+          id,
+          name
+        }
+        ... on SceneListing{
+          id,
+          name
+        }
+      }
+    }
+  }
+}
+```
+Response:
+```js
+{
+  "data": {
+    "myRooms": {
+      "entries": [
+        {
+          "id": "3FqxixG",
+          "name": "My Fun Get-Together",
+          "scene": null
+        },
+        {
+          "id": "FmNKVjL",
+          "name": "Foo",
+          "scene": {
+            "id": "tXkCgJw",
+            "name": "Crater 2"
+          }
+        },
+        "scene": {
+          "id": "74VD2Et",
+          "name": "Crater"
+        }
+      ]
+    }
+  }
+}
+```
+
+#### Query my favorite rooms
+Request:
+```
+query {
+  myFavorites {
+    entries {
+      name,
+      id
+    }
+  }
+}
+```
+Response:
+```js
+{
+  "data": {
+    "favoriteRooms": {
+      "entries": [
+        {
+          "id": "4jByd2w",
+          "name": "Uniform Ready Social"
+        },
+        {
+          "id": "5wQhhbG",
+          "name": "Angelic Vibrant Spot"
+        },
+        {
+          "id": "RmNv2k2",
+          "name": "Golden Perfect Volume"
+        },
+      ]
+    }
+  }
+}
+```
+
+
+#### Query public rooms
+Request:
+```
+query {
+  publicRooms {
+    entries {
+      name,
+      id
+    }
+  }
+}
+```
+Response:
+```js
+{
+  "data": {
+    "publicRooms": {
+      "entries": [
+        {
+          "id": "z7LQiNi",
+          "name": "Big Time Room"
+        },
+        {
+          "id": "SVnhCWq",
+          "name": "sdafasdf"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Updating rooms
+#### Set room properties like `name`, `description`, and `roomSize`
+```
+mutation {
+  updateRoom(
+    id:"FmNKVjL", 
+    name:"Foo bar baz", 
+    description:"Some description", 
+    roomSize:15,
+  ) {
+    id
+  }
+}
+```
+#### Change the scene of a given room:
+```
+mutation {
+  updateRoom(
+    id:"FmNKVjL", 
+    sceneId: "74VD2Et",
+  ) {
+    id
+  }
+}
+```
+
+#### Change member permissions in the room:
+```
+mutation {
+  updateRoom(
+    id:"FmNKVjL", 
+    memberPermissions: {
+      fly: true,
+      spawnEmoji: true,
+      spawnDrawing: true,
+      pinObjects: false,
+      spawnCamera: false,
+      spawnAndMoveMedia: true
+    }
+  ) {
+    id
+  }
+}
+```
+### Change everything all in one go:
+
+```
+mutation {
+  updateRoom(
+    id:"FmNKVjL", 
+    name:"Foo bar baz", 
+    description:"Some description", 
+    roomSize:15,
+    sceneId: "74VD2Et",
+    memberPermissions: {
+      fly: true,
+      spawnEmoji: true,
+      spawnDrawing: true,
+      pinObjects: false,
+      spawnCamera: false,
+      spawnAndMoveMedia: true
+    }
+  ) {
+    id
+  }
+}
+```
+
+

lib/ret/hub.ex

@@ -24,7 +24,8 @@ defmodule Ret.Hub do
     RoomAssigner,
     BitFieldUtils,
     HubRoleMembership,
-    AppConfig
+    AppConfig,
+    AccountFavorite
   }
 
   alias Ret.Hub.{HubSlug}
@@ -133,6 +134,14 @@ defmodule Ret.Hub do
     |> changeset(scene_or_scene_listing, params)
   end
 
+  def create(params) do
+    scene_or_scene_listing = get_scene_or_scene_listing(params)
+
+    %Hub{}
+    |> changeset(scene_or_scene_listing, params)
+    |> Repo.insert()
+  end
+
   defp get_scene_or_scene_listing(params) do
     if is_nil(params["scene_id"]) do
       SceneListing.get_random_default_scene_listing()
@@ -141,13 +150,46 @@ defmodule Ret.Hub do
     end
   end
 
+  def get_scene_or_scene_listing_by_id(nil) do
+    SceneListing.get_random_default_scene_listing()
+  end
+
+  def get_scene_or_scene_listing_by_id(id) do
+    Scene.scene_or_scene_listing_by_sid(id)
+  end
+
   def get_by_entry_code_string(entry_code_string) when is_binary(entry_code_string) do
     case Integer.parse(entry_code_string) do
       {entry_code, _} -> Hub |> Repo.get_by(entry_code: entry_code)
       _ -> nil
     end
   end
 
+  def get_my_rooms(account, params) do
+    Hub
+    |> where([h], h.created_by_account_id == ^account.account_id and h.entry_mode == ^"allow")
+    |> order_by(desc: :inserted_at)
+    |> preload(^Hub.hub_preloads())
+    |> Repo.paginate(params)
+  end
+
+  def get_favorite_rooms(account, params) do
+    Hub
+    |> where([h], h.entry_mode == ^"allow")
+    |> join(:inner, [h], f in AccountFavorite, on: f.hub_id == h.hub_id and f.account_id == ^account.account_id)
+    |> order_by([h, f], desc: f.last_activated_at)
+    |> preload(^Hub.hub_preloads())
+    |> Repo.paginate(params)
+  end
+
+  def get_public_rooms(params) do
+    Hub
+    |> where([h], h.allow_promotion and h.entry_mode == ^"allow")
+    |> order_by(desc: :inserted_at)
+    |> preload(^Hub.hub_preloads())
+    |> Repo.paginate(params)
+  end
+
   def changeset(%Hub{} = hub, %Scene{} = scene, attrs) do
     hub
     |> changeset(nil, attrs)
@@ -189,9 +231,9 @@ defmodule Ret.Hub do
     attrs["member_permissions"] |> Map.new(fn {k, v} -> {String.to_atom(k), v} end) |> member_permissions_to_int
   end
 
-  def add_member_permissions_update_to_changeset(changeset, hub, attrs) do
+  defp add_member_permissions_update_to_changeset(changeset, hub, member_permissions) do
     member_permissions =
-      Map.merge(member_permissions_for_hub(hub), attrs["member_permissions"])
+      Map.merge(member_permissions_for_hub(hub), member_permissions)
       |> Map.new(fn {k, v} -> {String.to_atom(k), v} end)
       |> member_permissions_to_int
 
@@ -212,7 +254,7 @@ defmodule Ret.Hub do
   end
 
   def add_promotion_to_changeset(changeset, attrs) do
-    changeset |> put_change(:allow_promotion, !!attrs["allow_promotion"])
+    changeset |> put_change(:allow_promotion, !!attrs["allow_promotion"] || !!attrs.allow_promotion)
   end
 
   def changeset_for_new_seen_occupant_count(%Hub{} = hub, occupant_count) do
@@ -349,6 +391,15 @@ defmodule Ret.Hub do
     hub.room_size || AppConfig.get_cached_config_value("features|default_room_size")
   end
 
+  def scene_or_scene_listing_for(%Hub{} = hub) do
+    case hub.scene || hub.scene_listing do
+      nil -> nil
+      %Scene{state: :removed} -> nil
+      %SceneListing{state: :delisted} -> nil
+      scene -> scene
+    end
+  end
+
   defp changeset_for_new_entry_code(%Hub{} = hub) do
     hub
     |> Ecto.Changeset.change()
@@ -542,6 +593,39 @@ defmodule Ret.Hub do
     |> Map.new(fn {k, v} -> {Atom.to_string(k), v} end)
   end
 
+  def member_permissions_for_hub_as_atoms(%Hub{} = hub) do
+    hub.member_permissions
+    |> BitFieldUtils.permissions_to_map(@member_permissions)
+  end
+
+  def maybe_add_member_permissions(changeset, hub, %{"member_permissions" => member_permissions}) do
+    add_member_permissions_update_to_changeset(
+      changeset,
+      hub,
+      member_permissions
+    )
+  end
+
+  def maybe_add_member_permissions(changeset, hub, %{:member_permissions => member_permissions}) do
+    add_member_permissions_update_to_changeset(
+      changeset,
+      hub,
+      Map.new(member_permissions, fn {k, v} -> {Atom.to_string(k), v} end)
+    )
+  end
+
+  def maybe_add_member_permissions(changeset, _hub, _params) do
+    changeset
+  end
+
+  def maybe_add_promotion(changeset, account, hub, %{"allow_promotion" => _} = hub_params),
+    do: changeset |> Hub.maybe_add_promotion_to_changeset(account, hub, hub_params)
+
+  def maybe_add_promotion(changeset, account, hub, %{allow_promotion: _} = hub_params),
+    do: changeset |> Hub.maybe_add_promotion_to_changeset(account, hub, hub_params)
+
+  def maybe_add_promotion(changeset, _account, _hub, _), do: changeset
+
   # The account argument here can be a Ret.Account, a Ret.OAuthProvider or nil.
   def perms_for_account(%Ret.Hub{} = hub, account) do
     %{

lib/ret/repo.ex

@@ -1,6 +1,6 @@
 defmodule Ret.Repo do
   use Ecto.Repo, otp_app: :ret, adapter: Ecto.Adapters.Postgres
-  use Scrivener, page_size: 20
+  use Scrivener, page_size: 20, max_page_size: 50
 
   def init(_, opts) do
     {:ok, Keyword.put(opts, :url, System.get_env("DATABASE_URL"))}