feat: init codebase with bare API client implementation

.Rbuildignore

@@ -0,0 +1,5 @@
+^.vscode
+^LICENSE\.md$
+^nix
+^shell.nix$
+^tmp

.gitignore

@@ -0,0 +1,2 @@
+.vscode
+tmp/

DESCRIPTION

@@ -0,0 +1,14 @@
+Package: rocketbase
+Title: Unofficial PocketBase API Client
+Version: 0.0.0.9000
+Authors@R:
+    person("Vehbi Sinan", "Tunalioglu", , "vst@vsthost.com", role = c("aut", "cre"))
+Description: This package is an unofficial API client to the opensource headless content management service PocketBase.
+License: MIT + file LICENSE
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.2.1
+Imports:
+    R6,
+    crul,
+    jsonlite

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2022
+COPYRIGHT HOLDER: rocketbase authors

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2022 rocketbase authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NAMESPACE

@@ -0,0 +1,6 @@
+# Generated by roxygen2: do not edit by hand
+
+export(RocketBase)
+importFrom(R6,R6Class)
+importFrom(crul,HttpClient)
+importFrom(jsonlite,fromJSON)

R/base.R

@@ -0,0 +1,107 @@
+#' @title PocketBase API Client
+#'
+#' @description Instances of this class can be used for conveniently issuing
+#' HTTP requests to remote PocketBase API instances.
+#'
+#' Note that this client only works with admin users at the moment.
+#'
+#' @importFrom crul HttpClient
+#' @importFrom jsonlite fromJSON
+#' @importFrom R6 R6Class
+#' @export
+RocketBase <- R6::R6Class("RocketBase", ## nolint
+    public = list(
+        #' @field url Base URL of the remote PocketBase API instance.
+        url = NULL,
+
+        #' @field bare Bare HTTP client for the remote PocketBase API instance.
+        #'
+        #' This is a plain vanilla `crul::HttpClient` instance that is ready to
+        #' issue requests to remote PocketBase API instance. Indeed, this
+        #' instance should be sufficient for most API communication with
+        #' PocketBase API instances.
+        bare = NULL,
+
+        #' @description Creates a PocketBase API client instance.
+        #'
+        #' @param url Base URL of the remote PocketBase API instance.
+        #' @param identity Identity credential for authentication.
+        #' @param password Password credential for authentication.
+        #'
+        #' @return A new `RocketBase` object.
+        #' @examples
+        #' \dontrun{
+        #' client <- rocketbase::RocketBase$new(
+        #'     url = "https://httpbin.org",
+        #'     identity = "hebele",
+        #'     password = "hubele"
+        #' )
+        #' }
+        initialize = function(url, identity, password) {
+            self$url <- url
+            private$identity <- identity
+            private$password <- password
+            private$setup()
+        },
+
+        #' @description Prints rudimentary information about the remote PocketBase API instance.
+        info = function() {
+            cat(sprintf("PocketBase Instance URL: %s\n", self$url))
+        },
+
+        #' @description Provides the print function for `RocketBase` object.
+        print = function() {
+            print(sprintf("<ROCKETBASE (url = %s)>", self$url))
+        }
+    ),
+    private = list(
+        ## Identity credential for the remote PocketBase API instance.
+        identity = NULL,
+
+        ## Password credential for the remote PocketBase API instance.
+        password = NULL,
+
+        ## Token credential for the remote PocketBase API instance.
+        token = NULL,
+
+        ## Setups this instance.
+        setup = function() {
+            ## Attempt to authenticate and get the authentication token:
+            private$token <- private$authenticate()
+
+            ## Build the bare HTTP client:
+            self$bare <- crul::HttpClient$new(
+                url = self$url,
+                headers = list(
+                    Authorization=sprintf("%s", private$token),
+                    "User-Agent"=private$useragent()
+                )
+            )
+        },
+
+        ## Attempts to authenticate and get a token.
+        authenticate = function() {
+            ## Build the HTTP client:
+            client <- crul::HttpClient$new(url = self$url)
+
+            ## Issue the authentication request and get a response:
+            response <- client$post("/api/admins/auth-with-password", body=list(identity=private$identity, password=private$password))
+
+            ## Check if response status is 200. If not, raise error as it implies that authentication has failed.
+            if (response$status_code != 200) {
+                stop("Authentication failed.")
+            }
+
+            ## Parse the content of the response:
+            content <- jsonlite::fromJSON(response$parse(encoding="UTF-8"))
+
+            ## Return the authentication token:
+            content$token
+        },
+
+        ## Builds the user-agent string.
+        useragent = function() {
+            sprintf( "rocketbase/%s (%s; on:%s)", utils::packageVersion("rocketbase"), Sys.info()["sysname"], Sys.info()["nodename"])
+        }
+    )
+)

README.md

@@ -0,0 +1,111 @@
+# rocketbase - Unofficial PocketBase API Client for R
+
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/telostat/rocketbase)
+![github last commit](https://img.shields.io/github/last-commit/telostat/rocketbase)
+![GitHub contributors](https://img.shields.io/github/contributors/telostat/rocketbase)
+
+`rocketbase` is an unofficial [PocketBase](https://pocketbase.io/) API client
+for R.
+
+## Installation
+
+`rocketbase` is currently not on [CRAN](https://cran.r-project.org/). The
+easiest way to install it is using [devtools](https://devtools.r-lib.org/).
+
+For the latest development snapshot:
+
+```R
+devtools::install_github("telostat/rocketbase", upgrade="ask")
+```
+
+For the latest version (`X.Y.Z`, following [semantic
+versioning](https://semver.org/)):
+
+```R
+devtools::install_github("telostat/rocketbase", ref="X.Y.Z", upgrade="ask")
+```
+
+## Development
+
+Enter the Nix shell and launch PocketBase:
+
+```sh
+nix-shell
+pocketbase-serve
+```
+
+Create an admin user account on PocketBase. Now, on another console session,
+enter Nix shell:
+
+```sh
+nix-shell
+```
+
+Launch R:
+
+```sh
+R
+```
+
+Here is a sample session:
+
+```R
+devtools::load_all(".")
+rb <- rocketbase::RocketBase$new("http://localhost:8090", identity = "hebele@hubele.com", password = "hebelehubele")
+response <- rb$bare$get("/api/collections/users/records")
+stopifnot(response$status_code == 200)
+my_data <- jsonlite::fromJSON(response$parse(encoding = "UTF-8"))
+print(my_data)
+
+table <- list(
+    name = "observations",
+    type = "base",
+    system = FALSE,
+    schema = list(
+        list(
+            "name" = "key",
+            "type" = "text",
+            "system" = FALSE,
+            "required" = TRUE,
+            "unique" = TRUE,
+            "nullable" = FALSE
+        ),
+        list(
+            "name" = "value",
+            "type" = "text",
+            "system" = FALSE,
+            "required" = FALSE,
+            "unique" = FALSE,
+            "nullable" = TRUE
+        )
+    )
+)
+response <- rb$bare$post("/api/collections", encode = "json", body=table)
+stopifnot(response$status_code == 200)
+
+response <- rb$bare$get("/api/collections/observations/records")
+stopifnot(response$status_code == 200)
+my_data <- jsonlite::fromJSON(response$parse(encoding = "UTF-8"))
+print(my_data)
+
+response <- rb$bare$post("/api/collections/observations/records", encode = "json", body=list(
+    key = "key1",
+    value = "value1"
+))
+stopifnot(response$status_code == 200)
+
+response <- rb$bare$post("/api/collections/observations/records", encode = "json", body=list(
+    key = "key2",
+    value = "value2"
+))
+stopifnot(response$status_code == 200)
+
+response <- rb$bare$get("/api/collections/observations/records")
+stopifnot(response$status_code == 200)
+my_data <- jsonlite::fromJSON(response$parse(encoding = "UTF-8"))
+print(my_data)
+```
+
+## License
+
+This work is licensed under MIT license. See [LICENSE](./LICENSE.md).