update documentation for CRAN release

cloudyr · Dec 8, 2016 · 2a70f3a · 2a70f3a
1 parent 6fb19ee
commit 2a70f3a
Show file tree

Hide file tree

Showing 23 changed files with 372 additions and 424 deletions.
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -2,3 +2,4 @@
 README.Rmd
 drat.sh
 knitreadme.sh
+CONTRIBUTING.md
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,18 +1,19 @@
 Package: aws.sns
 Type: Package
 Title: AWS SNS Client Package
-Version: 0.1.3
-Date: 2016-03-17
+Version: 0.1.5
+Date: 2016-12-08
 Author: Thomas J. Leeper
 Maintainer: Thomas J. Leeper <thosjleeper@gmail.com>
 Description: A simple client package for the Amazon Web Services (AWS) Simple
     Notification Service (SNS) API.
 License: GPL (>= 2)
 Imports:
+    stats,
     httr,
-    XML,
+    xml2,
     jsonlite,
-    aws.signature
+    aws.signature (>= 0.2.6)
 URL: https://github.com/cloudyr/aws.sns
 BugReports: https://github.com/cloudyr/aws.sns/issues
-RoxygenNote: 5.0.1.9000
+RoxygenNote: 5.0.1
diff --git a/NAMESPACE b/NAMESPACE
@@ -5,6 +5,8 @@ export(create_topic)
 export(delete_topic)
 export(get_subscription_attrs)
 export(get_topic_attrs)
+export(list_subscriptions)
+export(list_topics)
 export(publish)
 export(remove_permission)
 export(set_subscription_attrs)
@@ -13,8 +15,9 @@ export(snsHTTP)
 export(subscribe)
 export(unsubscribe)
 import(httr)
-importFrom(XML,xmlParse)
-importFrom(XML,xmlToList)
 importFrom(aws.signature,signature_v4_auth)
 importFrom(jsonlite,fromJSON)
 importFrom(jsonlite,toJSON)
+importFrom(stats,setNames)
+importFrom(xml2,as_list)
+importFrom(xml2,read_xml)
diff --git a/NEWS b/NEWS
@@ -1,3 +1,7 @@
-# CHANGES TO aws.sns 0.1 #
+# CHANGES TO aws.sns 0.1.5
+
+* Add examples and cleanup documentation.
+
+# CHANGES TO aws.sns 0.1.1
 
 * Initial release.
diff --git a/R/http.r b/R/http.r
@@ -1,31 +1,25 @@
 #' @title Execute SNS API Request
 #' @description This is the workhorse function to execute calls to the SNS API.
-#' @details 
-#' This function constructs and signs an SNS API request and returns the
-#' results thereof, or relevant debugging information in the case of error.
-#' 
-#' @param query An optional named list containing query string parameters and
-#' their character values.
-#' @param region A character string containing an AWS region. If missing, the
-#' default \dQuote{us-east-1} is used.
-#' @param key A character string containing an AWS Access Key ID. The default
-#' is pulled from environment variable \dQuote{AWS_ACCESS_KEY_ID}.
-#' @param secret A character string containing an AWS Secret Access Key. The
-#' default is pulled from environment variable \dQuote{AWS_SECRET_ACCESS_KEY}.
+#' @param query An optional named list containing query string parameters and their character values.
+#' @param region A character string containing an AWS region. If missing, the default \dQuote{us-east-1} is used.
+#' @param key A character string containing an AWS Access Key ID. The default is pulled from environment variable \dQuote{AWS_ACCESS_KEY_ID}.
+#' @param secret A character string containing an AWS Secret Access Key. The default is pulled from environment variable \dQuote{AWS_SECRET_ACCESS_KEY}.
+#' @param session_token Optionally, a character string containing an AWS temporary Session Token. If missing, defaults to value stored in environment variable \dQuote{AWS_SESSION_TOKEN}.
 #' @param ... Additional arguments passed to \code{\link[httr]{GET}}.
-#' @return If successful, a named list. Otherwise, a data structure of class
-#' \dQuote{aws-error} containing any error message(s) from AWS and information
-#' about the request attempt.
+#' @return If successful, a named list. Otherwise, a data structure of class \dQuote{aws-error} containing any error message(s) from AWS and information about the request attempt.
+#' @details This function constructs and signs an SNS API request and returns the results thereof, or relevant debugging information in the case of error.
 #' @author Thomas J. Leeper
 #' @import httr
 #' @importFrom jsonlite fromJSON
-#' @importFrom XML xmlParse xmlToList
+#' @importFrom xml2 read_xml as_list
 #' @importFrom aws.signature signature_v4_auth
 #' @export
 snsHTTP <- function(query, 
                     region = Sys.getenv("AWS_DEFAULT_REGION","us-east-1"), 
                     key = Sys.getenv("AWS_ACCESS_KEY_ID"), 
-                    secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"), ...) {
+                    secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"), 
+                    session_token = Sys.getenv("AWS_SESSION_TOKEN"),
+                    ...) {
     d_timestamp <- format(Sys.time(), "%Y%m%dT%H%M%SZ", tz = "UTC")
     if (key == "") {
         H <- add_headers(`x-amz-date` = d_timestamp)
@@ -40,16 +34,22 @@ snsHTTP <- function(query,
                canonical_headers = list(host = paste0("sns.",region,".amazonaws.com"),
                                         `x-amz-date` = d_timestamp),
                request_body = "",
-               key = key, secret = secret)
-        H <- add_headers(`x-amz-date` = d_timestamp, 
-                         `x-amz-content-sha256` = S$BodyHash,
-                         Authorization = S$SignatureHeader)
+               key = key, 
+               secret = secret,
+               session_token = session_token)
+        headers <- list(`x-amz-date` = d_timestamp, 
+                        `x-amz-content-sha256` = S$BodyHash,
+                        Authorization = S$SignatureHeader)
+        if (!is.null(session_token) && session_token != "") {
+            headers[["x-amz-security-token"]] <- session_token
+        }
+        H <- do.call(add_headers, headers)
     }
     r <- GET(paste0("https://sns.",region,".amazonaws.com"), H, query = query, ...)
     if (http_status(r)$category == "client error") {
-        x <- try(xmlToList(xmlParse(content(r, "text"))), silent = TRUE)
+        x <- try(as_list(read_xml(content(r, "text", encoding = "UTF-8"))), silent = TRUE)
         if (inherits(x, "try-error")) {
-            x <- try(fromJSON(content(r, "text"))$Error, silent = TRUE)
+            x <- try(fromJSON(content(r, "text", encoding = "UTF-8"))$Error, silent = TRUE)
         }
         warn_for_status(r)
         h <- headers(r)
@@ -58,9 +58,9 @@ snsHTTP <- function(query,
         attr(out, "request_string_to_sign") <- S$StringToSign
         attr(out, "request_signature") <- S$SignatureHeader
     } else {
-        out <- try(fromJSON(content(r, "text")), silent = TRUE)
+        out <- try(fromJSON(content(r, "text", encoding = "UTF-8")), silent = TRUE)
         if(inherits(out, "try-error"))
-            out <- structure(content(r, "text"), "unknown")
+            out <- structure(content(r, "text", encoding = "UTF-8"), "unknown")
     }
     return(out)
 }
diff --git a/R/package.R b/R/package.R
@@ -1,11 +1,10 @@
 #' @title aws.sqs
 #' @description AWS SNS Client Package
-#' @details A simple client package for the Amazon Web Services (AWS) Simple
-#' Notification Service (SNS) REST API.
+#' @details A simple client package for the Amazon Web Services (AWS) Simple Notification Service (SNS) REST API.
 #' @name aws.sns-package
 #' @aliases aws.sns-package aws.sns
 #' @docType package
-#' @author Thomas J. Leeper <thosjleeper@@gmail.com>
+#' @author Thomas J. Leeper <thosjleeper@gmail.com>
 #' @keywords package
 NULL
 
diff --git a/R/publish.r b/R/publish.r
@@ -1,26 +1,33 @@
 #' @title Publish to a topic or endpoint
 #' @description Publish a message to a specified topic or application endpoint.
+#' @param topic Optionally, a character string containing an SNS Topic Amazon Resource Name (ARN). Must specify \code{topic} or \code{endpoint}.
+#' @param endpoint Optionally, a character string containing an SNS Application Endpoint ARN. Must specify \code{topic} or \code{endpoint}.
+#' @param message Either a single character string containing a message to be sent to all endpoints, or a named list of messages to be sent to specific endpoints (where the names of each element correspond to endpoints).
+#' @param subject Optionally, a character string containing a subject line (e.g., to be used for an email endpoint).
+#' @param ... Additional arguments passed to \code{\link{snsHTTP}}.
+#' @return If successful, a character string containing a message ID. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt.
 #' @details 
 #' Publishes a message to a topic or an application endpoint. Messages can be
 #' the same for all endpoints or customized so that, for example, a short
 #' 140-character message is sent to SMS endpoints that are subscribed to a
 #' topic while longer messages are sent to email endpoints, etc. The allowed
 #' message types are: default, email, email-json, sqs, sms, http, https, and
 #' application.
+#' @examples
+#' \dontrun{
+#'   top <- create_topic("new_topic")
+#' 
+#'   # simple notifications
+#'   publish(top, message = "This is a notification message", subject = "Notification!")
+#' 
+#'   # endpoint-specific notification
+#'   publish(top, message = list(sms = "This is an sms message", 
+#'                               email = "This is an email"), 
+#'           subject = "Notification!")
+#' 
+#'   delete_topic(top)
+#' }
 #' 
-#' @param topic Optionally, a character string containing an SNS Topic Amazon
-#' Resource Name (ARN). Must specify \code{topic} or \code{endpoint}.
-#' @param endpoint Optionally, a character string containing an SNS Application
-#' Endpoint ARN. Must specify \code{topic} or \code{endpoint}.
-#' @param message Either a single character string containing a message to be
-#' sent to all endpoints, or a named list of messages to be sent to specific
-#' endpoints (where the names of each element correspond to endpoints).
-#' @param subject Optionally, a character string containing a subject line
-#' (e.g., to be used for an email endpoint).
-#' @param ... Additional arguments passed to \code{\link{snsHTTP}}.
-#' @return If successful, a character string containing a message ID.
-#' Otherwise, a data structure of class \dQuote{aws_error} containing any error
-#' message(s) from AWS and information about the request attempt.
 #' @author Thomas J. Leeper
 #' @references
 #' \href{http://docs.aws.amazon.com/sns/latest/api/API_Publish.html}{Publish}

diff --git a/R/subscriptions.r b/R/subscriptions.r
@@ -1,64 +1,60 @@
-#' @title Subscribe to a topic
+#' @rdname subscriptions
+#' @title Subscribe/Unsubscribe to a topic
 #' @description Subscribes an endpoint to the specified SNS topic.
+#' @param topic A character string containing an SNS Topic Amazon Resource Name (ARN).
+#' @param endpoint A character string containing the endpoint to be subscribed (e.g., an email address).
+#' @param protocol The allowed protocol types are: default, email, email-json, sqs, sms, http, https, and application.
+#' @param subscription A character string containing an SNS Subscription Amazon Resource Name (ARN).
+#' @param ... Additional arguments passed to \code{\link{snsHTTP}}.
+#' @return If successful, a character string containing a subscription ARN. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt.
 #' @details 
-#' Initiates a subscription of an endpoint to an SNS topic. For example, this
-#' is used to add an email address endpoint to a topic. Subscriptions need to
-#' be confirmed by the endpoint. For example, an SMS endpoint will require an
-#' SMS response to an subscription invitation message. Subscriptions can be
-#' removed using \code{\link{unsubscribe}} (or whatever method is described in
-#' the invitation message); thus subscriptions can be handled by both users and
-#' administrator (you).
+#' \code{subscribe} initiates a subscription of an endpoint to an SNS topic. For example, this is used to add an email address endpoint to a topic. Subscriptions need to be confirmed by the endpoint. For example, an SMS endpoint will require an SMS response to an subscription invitation message. Subscriptions can be removed using \code{\link{unsubscribe}} (or whatever method is described in the invitation message); thus subscriptions can be handled by both users and administrator (you).
 #' 
-#' @param topic A character string containing an SNS Topic Amazon Resource Name
-#' (ARN).
-#' @param endpoint A character string containing the endpoint to be subscribed
-#' (e.g., an email address).
-#' @param protocol The allowed protocol types are: default, email, email-json,
-#' sqs, sms, http, https, and application.
-#' @param ... Additional arguments passed to \code{\link{snsHTTP}}.
-#' @return If successful, a character string containing a subscription ARN.
-#' Otherwise, a data structure of class \dQuote{aws_error} containing any error
-#' message(s) from AWS and information about the request attempt.
+#' \code{unsubscribe} unsubscribes an endpoint from an SNS topic.
 #' @author Thomas J. Leeper
-#' @seealso \code{link{unsubscribe}} \code{\link{list_subscriptions}}
+#' @examples
+#' \dontrun{
+#'   top <- create_topic("new_topic")
+#'   # email subscription
+#'   subscribe(top, "example@example.com", protocol = "email")
+#' 
+#'   # sms subscription
+#'   subscribe(top, "555-123-4567", protocol = "sms")
+#' 
+#'   delete_topic(top)
+#' }
+#' 
+#' @seealso \code{\link{list_subscriptions}}
 #' @references
 #' \href{http://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html}{Subscribe}
+#' \href{http://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html}{Unsubscribe}
 #' @export
 subscribe <- function(topic, endpoint, protocol, ...) {
     query_list <- list(TopicArn = topic, Action = "Subscribe")
     query_list$Endpoint <- endpoint
     protocol_list <- c("http","https","email","email-json","sms","sqs","application")
-    if(!protocol %in% protocol_list)
+    if (!protocol %in% protocol_list) {
         stop("'protocol' must be one of: ", paste0('"',protocol_list,'"', collapse = ", "))
-    else
+    } else {
         query_list$Protocol <- protocol
+    }
     out <- snsHTTP(query = query_list, ...)
-    if(inherits(out, "aws_error"))
+    if (inherits(out, "aws_error")) {
         return(out)
+    }
     structure(out$SubscribeResponse$SubscribeResult$SubscriptionArn, 
               RequestId = out$SubscribeResponse$ResponseMetadata$RequestId)
 }
 
 
-#' @title Unsubscribe from a topic
-#' @description Cancels an endpoint's subscription to a topic.
-#' @details Unsubscribes an endpoint from an SNS topic.
-#' @param subscription A character string containing an SNS Subscription Amazon
-#' Resource Name (ARN).
-#' @param ... Additional arguments passed to \code{\link{snsHTTP}}.
-#' @return If successful, a logical \code{TRUE}. Otherwise, a data structure of
-#' class \dQuote{aws_error} containing any error message(s) from AWS and
-#' information about the request attempt.
-#' @author Thomas J. Leeper
-#' @seealso \code{link{unsubscribe}} \code{\link{list_subscriptions}}
-#' @references
-#' \href{http://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html}{Unsubscribe}
+#' @rdname subscriptions
 #' @export
 unsubscribe <- function(subscription, ...) {
     query_list <- list(SubscriptionArn = subscription, Action = "Unsubscribe")
     out <- snsHTTP(query = query_list, ...)
-    if(inherits(out, "aws_error"))
+    if (inherits(out, "aws_error")) {
         return(out)
+    }
     structure(TRUE, 
               RequestId = out$UnsubscribeResponse$ResponseMetadata$RequestId)
 }
@@ -82,17 +78,17 @@ unsubscribe <- function(subscription, ...) {
 #' \dQuote{aws_error} containing any error message(s) from AWS and information
 #' about the request attempt.
 #' @author Thomas J. Leeper
-#' @seealso \code{link{subscribe}} \code{link{unsubscribe}}
-#' \code{link{list_subscriptions}}
+#' @seealso \code{link{subscribe}} \code{link{list_subscriptions}}
 #' @references
 #' \href{http://docs.aws.amazon.com/sns/latest/api/API_GetSubscriptionAttributes.html}{GetSubscriptionAttributes}
 #' \href{http://docs.aws.amazon.com/sns/latest/api/API_SetSubscriptionAttributes.html}{SetSubscriptionAttributes}
 #' @export
 get_subscription_attrs <- function(subscription, ...) {
     query_list <- list(SubscriptionArn = subscription, Action = "GetSubscriptionAttributes")
     out <- snsHTTP(query = query_list, ...)
-    if(inherits(out, "aws_error"))
+    if (inherits(out, "aws_error")) {
         return(out)
+    }
     structure(out$GetSubscriptionAttributesResponse$GetSubscriptionAttributesResult$Attributes, 
               RequestId = out$GetSubscriptionAttributesResponse$ResponseMetadata$RequestId)
 }
@@ -101,15 +97,16 @@ get_subscription_attrs <- function(subscription, ...) {
 #' @export
 set_subscription_attrs <- function(subscription, attribute, ...) {
     query_list <- list(SubscriptionArn = subscription, Action = "SetSubscriptionAttributes")
-    if(any(!names(attribute) %in% c("DeliveryPolicy","RawMessageDelivery")))
+    if (any(!names(attribute) %in% c("DeliveryPolicy","RawMessageDelivery"))) {
         stop("Attribute name must be 'DeliveryPolicy' or 'RawMessageDelivery'")
-    else {
+    } else {
         query_list$AttributeName <- names(attribute)
         query_list$AttributeValue <- attribute[[1]]
     }
     out <- snsHTTP(query = query_list, ...)
-    if(inherits(out, "aws_error"))
+    if (inherits(out, "aws_error")) {
         return(out)
+    }
     structure(TRUE, 
               RequestId = out$SetSubscriptionAttributesResponse$ResponseMetadata$RequestId)
 }
@@ -135,8 +132,9 @@ set_subscription_attrs <- function(subscription, attribute, ...) {
 #' @author Thomas J. Leeper
 #' @seealso \code{link{subscribe}} \code{link{unsubscribe}}
 #' \code{link{get_subscription_attrs}}
-#' @references
-#' \href{http://docs.aws.amazon.com/sns/latest/api/API_ListSubscriptions.html}{ListSubscriptions}
+#' @references \href{http://docs.aws.amazon.com/sns/latest/api/API_ListSubscriptions.html}{ListSubscriptions}
+#' @importFrom stats setNames
+#' @export
 list_subscriptions <- function(topic, token, ...) {
     if (missing(topic)) {
         query_list <- list(Action = "ListSubscriptions")