update readme and add cran badge

NEWS.md

@@ -11,7 +11,7 @@
 - `arc_base_req()` is introduce creating a standardized way to making base httr2 request objects. 
   - <https://github.com/R-ArcGIS/arcgisutils/pull/19>
 - httr2 must be >= 1.0.0 now
-* New function `arc_agent()` is added to set a package sepcific user agent 
+* New function `arc_agent()` is added to set a package specific user agent 
 * `fetch_layer_metadata()` now puts `f=json` in the url instead of the request body
   - accepts `NULL` tokens 
   - uses `req_auth_bearer_token()` to include token in header

README.Rmd

@@ -4,6 +4,7 @@ output: github_document
 
 <!-- badges: start -->
 [![R-CMD-check](https://github.com/R-ArcGIS/arcgisutils/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/R-ArcGIS/arcgisutils/actions/workflows/R-CMD-check.yaml)
+[![CRAN status](https://www.r-pkg.org/badges/version/arcgisutils)](https://CRAN.R-project.org/package=arcgisutils)
 <!-- badges: end -->
 
 ```{r, include = FALSE}
@@ -29,5 +30,69 @@ You can install the development version of arcgisutils from [GitHub](https://git
 remotes::install_github("R-ArcGIS/arcgisutils")
 ```
 
+arcgisutils is designed as the backbone of the package [`{arcgislayers}`](https://github.com/r-arcgis/arcgislayers) and other planned location services packages. 
+
+### Authorization 
+
+Authorization tokens are provided through the functions `auth_code()`, `auth_client()`, `auth_user()`, and `auth_binding()`. Additional token validation functions are provided via `refresh_token()` and `validate_or_refresh_token()`. 
+
+Tokens are managed in a session based cache using `set_arc_token()` and `unset_arc_token()`. They are fetched using `arc_token()`. Here is a minimal example:
+
+
+```{r}
+library(arcgisutils)
+
+tkn <- auth_client()
+
+set_arc_token(tkn)
+
+arc_token()
+```
+
+Alternatively, tokens can be set based on a key-value pair. 
+
+```{r}
+set_arc_token("A" = tkn, "B" = tkn)
+```
+
+And fetched based on their name via
+
+```{r}
+arc_token("A")
+```
+
+### Standardized Requests 
+
+The function `arc_base_req()` is used to create a standardized `httr2` request object. It handles authorization tokens and sets a user agent.
+
+```{r}
+host <- arc_host() # use arcgis.com by default
+
+arc_base_req(host) 
+```
+
+### Esri JSON
+
+There are also a number of utility functions for creating and parsing Esri JSON. For example we can create a list that represent an Esri `FeatureSet` using `as_featurset()` directly from an `sf` object. To convert to json, it is recommended to use `jsonify::to_json(x, unbox = TRUE)`.
+
+```{r}
+library(sf)
+
+nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
+nc_json <- as_featureset(nc)
+
+str(nc_json, 1)
+```
+
+Alternatively, you can use the set of functions with the `_esri_` infix to directly create the json. See the [Esri geometry reference page](https://r.esri.com/arcgisutils/reference/esri_geometry.html) for more on how the conversion functions work. 
+
+Additionally, sf's `crs` object can be converted to a [`spatialReference`](https://developers.arcgis.com/documentation/common-data-types/geometry-objects.htm#GUID-DFF0E738-5A42-40BC-A811-ACCB5814BABC) JSON object using `validate_crs()`.
+
+```{r}
+validate_crs(27700)
+```
+
+
+
 
 

README.md

@@ -2,6 +2,8 @@
 <!-- badges: start -->
 
 [![R-CMD-check](https://github.com/R-ArcGIS/arcgisutils/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/R-ArcGIS/arcgisutils/actions/workflows/R-CMD-check.yaml)
+[![CRAN
+status](https://www.r-pkg.org/badges/version/arcgisutils)](https://CRAN.R-project.org/package=arcgisutils)
 <!-- badges: end -->
 
 # arcgisutils
@@ -21,3 +23,109 @@ You can install the development version of arcgisutils from
 # install.packages("remotes")
 remotes::install_github("R-ArcGIS/arcgisutils")
 ```
+
+arcgisutils is designed as the backbone of the package
+[`{arcgislayers}`](https://github.com/r-arcgis/arcgislayers) and other
+planned location services packages.
+
+### Authorization
+
+Authorization tokens are provided through the functions `auth_code()`,
+`auth_client()`, `auth_user()`, and `auth_binding()`. Additional token
+validation functions are provided via `refresh_token()` and
+`validate_or_refresh_token()`.
+
+Tokens are managed in a session based cache using `set_arc_token()` and
+`unset_arc_token()`. They are fetched using `arc_token()`. Here is a
+minimal example:
+
+``` r
+library(arcgisutils)
+
+tkn <- auth_client()
+
+set_arc_token(tkn)
+
+arc_token()
+#> <httr2_token>
+#> token_type: bearer
+#> access_token: <REDACTED>
+#> expires_at: 2024-02-23 10:56:42
+#> arcgis_host: https://www.arcgis.com
+```
+
+Alternatively, tokens can be set based on a key-value pair.
+
+``` r
+set_arc_token("A" = tkn, "B" = tkn)
+#> ✔ Named tokens set: `A` and `B`
+#> ℹ Access named tokens with `arc_token("name")`
+```
+
+And fetched based on their name via
+
+``` r
+arc_token("A")
+#> <httr2_token>
+#> token_type: bearer
+#> access_token: <REDACTED>
+#> expires_at: 2024-02-23 10:56:42
+#> arcgis_host: https://www.arcgis.com
+```
+
+### Standardized Requests
+
+The function `arc_base_req()` is used to create a standardized `httr2`
+request object. It handles authorization tokens and sets a user agent.
+
+``` r
+host <- arc_host() # use arcgis.com by default
+
+arc_base_req(host) 
+#> <httr2_request>
+#> GET https://www.arcgis.com
+#> Body: empty
+#> Options:
+#> • useragent: 'arcgisutils v0.2.0'
+```
+
+### Esri JSON
+
+There are also a number of utility functions for creating and parsing
+Esri JSON. For example we can create a list that represent an Esri
+`FeatureSet` using `as_featurset()` directly from an `sf` object. To
+convert to json, it is recommended to use
+`jsonify::to_json(x, unbox = TRUE)`.
+
+``` r
+library(sf)
+#> Warning: package 'sf' was built under R version 4.3.1
+#> Linking to GEOS 3.11.0, GDAL 3.5.3, PROJ 9.1.0; sf_use_s2() is TRUE
+
+nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
+nc_json <- as_featureset(nc)
+
+str(nc_json, 1)
+#> List of 5
+#>  $ geometryType    : chr "esriGeometryPolygon"
+#>  $ spatialReference:List of 1
+#>  $ hasZ            : logi FALSE
+#>  $ hasM            : logi FALSE
+#>  $ features        :List of 100
+```
+
+Alternatively, you can use the set of functions with the `_esri_` infix
+to directly create the json. See the [Esri geometry reference
+page](https://r.esri.com/arcgisutils/reference/esri_geometry.html) for
+more on how the conversion functions work.
+
+Additionally, sf’s `crs` object can be converted to a
+[`spatialReference`](https://developers.arcgis.com/documentation/common-data-types/geometry-objects.htm#GUID-DFF0E738-5A42-40BC-A811-ACCB5814BABC)
+JSON object using `validate_crs()`.
+
+``` r
+validate_crs(27700)
+#> $spatialReference
+#> $spatialReference$wkid
+#> [1] 27700
+```