Merge pull request #14 from CallFire/develop

added uploading contacts from csv & javadocs update

README.md

@@ -6,25 +6,3 @@ How to build Callfire client:</br>
     - callfire-api-client-1.0.0-SNAPSHOT-all.jar - client with all dependencies</br>
     - callfire-api-client-1.0.0-SNAPSHOT-javadoc.jar - client javadoc pages</br>
     - callfire-api-client-1.0.0-SNAPSHOT-sources.jar - client source code</br>
-
-If you see such stacktrace:
-<pre>
-Exception in thread "main" com.callfire.api.client.CallfireClientException: javax.net.ssl.SSLProtocolException: handshake alert:  unrecognized_name
-	at com.callfire.api.client.RestApiClient.get(RestApiClient.java:131)
-	at com.callfire.api.client.RestApiClient.get(RestApiClient.java:92)
-	at com.callfire.api.client.api.account.MeApi.getAccount(MeApi.java:64)
-	at com.callfire.api.client.integration.Main.getMeAccount(Main.java:13)
-	at com.callfire.api.client.integration.Main.main(Main.java:23)
-	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
-	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
-	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
-	at java.lang.reflect.Method.invoke(Method.java:497)
-	at com.intellij.rt.execution.application.AppMain.main(AppMain.java:140)
-Caused by: javax.net.ssl.SSLProtocolException: handshake alert:  unrecognized_name
-	at sun.security.ssl.ClientHandshaker.handshakeAlert(ClientHandshaker.java:1410)
-</pre>
-
-this is temporary SSL configuration issue, please set jsse.enableSNIExtension property to false.
-To do that set system propery:
- - System.setProperty("jsse.enableSNIExtension", "false");
- - or -Djsse.enableSNIExtension=false

gradle.properties

@@ -1,3 +1,3 @@
 group = com.callfire
 baseName = callfire-api-client
-version = 1.2.0
+version = 1.3.0

src/main/java/com/callfire/api/client/CallfireClient.java

@@ -24,9 +24,28 @@
 
 /**
  * Callfire API v2 client
+ * <p>
+ * <b>Authentication:</b> the CallFire API V2 uses HTTP Basic Authentication to verify
+ * the user of an endpoint. A generated username/password API credential from your
+ * account settings is required.
+ * </p>
+ * <p>
+ * <b>Errors:</b> codes in the 400s range detail all of the errors a CallFire Developer could
+ * encounter while using the API. Bad Request, Rate Limit Reached, and Unauthorized
+ * are some of the sorts of responses in the 400s block. Codes in the 500s range are
+ * error responses from the CallFire system. If an error has occurred anywhere in
+ * the execution of a resource that was not due to user input, a 500 response
+ * will be returned with a corresponding JSON error body.
+ * In that body will contain a message detailing what went wrong. In both cases
+ * {@link CallfireApiException} will be thrown, if error occurred inside client -
+ * {@link CallfireClientException}
+ * </p>
  *
  * @author Vladimir Mikhailov (email: vmikhailov@callfire.com)
- * @version 1.0
+ * @see <a href="https://developers.callfire.com/docs.html">Callfire API documentation</a>
+ * @see <a href="https://developers.callfire.com/learn.html">HowTos and examples</a>
+ * @see <a href="http://stackoverflow.com/questions/tagged/callfire">Stackoverflow community questions</a>
+ * @since 1.0
  */
 public class CallfireClient {
     private static Properties clientConfig = new Properties();

src/main/java/com/callfire/api/client/JsonConverter.java

@@ -43,7 +43,8 @@ public String serialize(Object obj) throws CallfireClientException {
      * Deserialize the given JSON string to Java object.
      *
      * @param body The JSON string
-     * @param type The type to deserialize body
+     * @param type The type of deserialized entity
+     * @param <T>  type of deserialized entity
      * @return deserialized Java object
      * @throws CallfireClientException in case body cannot be deserialized
      */

src/main/java/com/callfire/api/client/api/account/MeApi.java

@@ -53,7 +53,7 @@ public MeApi(RestApiClient client) {
     }
 
     /**
-     * Method queries account info like id, email, name, etc...
+     * Find account details for the user. Details include name, email, and basic account permissions.
      * GET /me/account
      *
      * @return user's account
@@ -77,7 +77,8 @@ public BillingPlanUsage getBillingPlanUsage() {
     }
 
     /**
-     * Get callerIds associated with account.
+     * Returns a list of verified caller ids. If the number is not shown in the list,
+     * then it is not verified, and will have to send for a verification code.
      * GET /me/callerids
      *
      * @return list of callerId numbers
@@ -90,8 +91,8 @@ public List<CallerId> getCallerIds() {
 
     /**
      * Send generated verification code to callerid number.
-     * After receiving verification code on phone call POST /callerids/{callerid}/verification-code
-     * to verify number.
+     * The verification code is delivered via a phone call.
+     * After receiving verification code on phone call POST /callerids/{callerid}/verification-code to verify number.
      * POST /me/callerids/{callerid}
      *
      * @param callerid callerid number
@@ -119,8 +120,10 @@ public Boolean verifyCallerId(CallerIdVerificationRequest request) {
     }
 
     /**
-     * Creates API credentials. ApiCredentials.name property required
-     * Performs POST /me/api/credentials request
+     * Create API credentials for the CallFire API. This endpoint requires full CallFire account
+     * credentials to be used, authenticated using Basic Authentication. At this time, the user
+     * can only supply the name for the credentials. The generated credentials can be used to
+     * access any endpoint on the CallFire API. ApiCredentials.name property required
      *
      * @param credentials API credentials to create
      * @return {@link ApiCredentials} object

src/main/java/com/callfire/api/client/api/account/OrdersApi.java

@@ -36,7 +36,8 @@ public OrdersApi(RestApiClient client) {
     }
 
     /**
-     * Order keywords by list
+     * Purchase keywords. Send a list of available keywords into this API to purchase them
+     * using CallFire credits. Be sure the account has credits before trying to purchase.
      *
      * @param request request payload
      * @return ResourceId with id of created order
@@ -48,7 +49,10 @@ public ResourceId orderKeywords(KeywordPurchaseRequest request) {
     }
 
     /**
-     * Order numbers by list of number or by a query
+     * Purchase numbers. There are many ways to purchase a number. Set either tollFreeCount or localCount
+     * along with some querying fields to purchase numbers by bulk query. Set the list of numbers
+     * to purchase by list. Available numbers will be purchased using CallFire credits owned by the user.
+     * Be sure the account has credits before trying to purchase.
      *
      * @param request request payload
      * @return ResourceId with id of created order

src/main/java/com/callfire/api/client/api/callstexts/CallsApi.java

@@ -20,7 +20,11 @@
 
 /**
  * Represents rest endpoint /calls
+ * Use the /calls API to quickly send individual calls, get results.
+ * A verified Caller ID and sufficient credits are required to make a call.
+ * <br>
  *
+ * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
  * @since 1.0
  */
 public class CallsApi {
@@ -40,12 +44,15 @@ public CallsApi(RestApiClient client) {
     }
 
     /**
-     * Find calls by different properties, broadcast id, toNumber, fromNumber, label, state, etc.
+     * Finds all calls sent or received by the user, filtered by different properties, broadcast id,
+     * toNumber, fromNumber, label, state, etc. Use "campaignId=0" parameter to query
+     * for all calls sent through the POST /calls API {@link CallsApi#send(List)}.
      *
      * @param request request object with different fields to filter
      * @return Page with @{Call} objects
      * @throws CallfireApiException    in case API cannot be queried for some reason and server returned error
      * @throws CallfireClientException in case error has occurred in client
+     * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
      */
     public Page<Call> find(FindCallsRequest request) {
         return client.get(CALLS_PATH, PAGE_OF_CALLS_TYPE, request);
@@ -81,7 +88,9 @@ public Call get(Long id, String fields) {
     }
 
     /**
-     * Send calls to recipients through default campaign
+     * Send calls to recipients through default campaign.
+     * Use the API to quickly send individual calls.
+     * A verified Caller ID and sufficient credits are required to make a call.
      *
      * @param recipients call recipients
      * @return list of {@link Call}
@@ -94,10 +103,12 @@ public List<Call> send(List<CallRecipient> recipients) {
 
     /**
      * Send call to recipients through existing campaign, if null default campaign will be used
+     * Use the API to quickly send individual calls.
+     * A verified Caller ID and sufficient credits are required to make a call.
      *
-     * @param recipients text recipients
-     * @param campaignId id of outbound campaign
-     * @param fields     limit fields returned. Example fields=id,name
+     * @param recipients call recipients
+     * @param campaignId specify a campaignId to send calls quickly on a previously created campaign
+     * @param fields     fields returned. E.g. fields=id,name or fields=items(id,name)
      * @return list of {@link Call}
      * @throws CallfireApiException    in case API cannot be queried for some reason and server returned error
      * @throws CallfireClientException in case error has occurred in client

src/main/java/com/callfire/api/client/api/callstexts/TextsApi.java

@@ -20,7 +20,10 @@
 
 /**
  * Represents rest endpoint /texts
+ * Use the /texts API to quickly send individual texts. A verified Caller ID and sufficient
+ * credits are required to make a call.
  *
+ * @see <a href="https://developers.callfire.com/results-responses-errors.html">text states and results</a>
  * @since 1.0
  */
 public class TextsApi {
@@ -40,12 +43,15 @@ public TextsApi(RestApiClient client) {
     }
 
     /**
-     * Find texts by broadcast id etc... If no limit is given then the last 100 texts will be returned.
+     * Finds all texts sent or received by the user. Use "campaignId=0"  parameter to query for all
+     * texts sent through the POST /texts API.
+     * If no limit is given then the last 100 texts will be returned.
      *
      * @param request request object with different fields to filter
      * @return Page with @{Text} objects
      * @throws CallfireApiException    in case API cannot be queried for some reason and server returned error
      * @throws CallfireClientException in case error has occurred in client
+     * @see <a href="https://developers.callfire.com/results-responses-errors.html">text states and results</a>
      */
     public Page<Text> find(FindTextsRequest request) {
         return client.get(TEXTS_PATH, PAGE_OF_TEXTS_TYPE, request);
@@ -82,6 +88,8 @@ public Text get(Long id, String fields) {
 
     /**
      * Send texts to recipients through default campaign
+     * Use the /texts API to quickly send individual texts. A verified Caller ID and sufficient
+     * credits are required to make a call.
      *
      * @param recipients text recipients
      * @return list of {@link Text}
@@ -94,6 +102,8 @@ public List<Text> send(List<TextRecipient> recipients) {
 
     /**
      * Send texts to recipients through existing campaign, if null default campaign will be used
+     * Use the /texts API to quickly send individual texts. A verified Caller ID and sufficient
+     * credits are required to make a call.
      *
      * @param recipients text recipients
      * @param campaignId id of outbound campaign

src/main/java/com/callfire/api/client/api/callstexts/model/request/FindCallsRequest.java

@@ -8,8 +8,12 @@
 import java.util.List;
 
 /**
- * Request object for GET /calls which incapsulates
- * different query pairs
+ * <p>
+ * Request object used to find all calls sent or received by the user.
+ * Use "campaignId=0" parameter to query for all calls sent through the POST /calls API.
+ * </p>
+ *
+ * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
  */
 public class FindCallsRequest extends FindCallsTextsRequest {
     @ConvertToString
@@ -30,18 +34,20 @@ public static Builder create() {
     }
 
     /**
-     * Get text statuses
+     * Get call statuses
      *
-     * @return text statuses
+     * @return call statuses
+     * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
      */
     public List<Call.State> getStates() {
         return states;
     }
 
     /**
-     * Get text results
+     * Get call results.
      *
-     * @return list of text results
+     * @return list of call results
+     * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
      */
     public List<Call.CallResult> getResults() {
         return results;
@@ -65,19 +71,23 @@ private Builder() {
         }
 
         /**
-         * Set text statuses to filter
+         * Set call statuses to filter
          *
          * @param states list of states to filter
+         * @return builder self reference
+         * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
          */
         public Builder states(List<Call.State> states) {
             request.states = states;
             return this;
         }
 
         /**
-         * Set text results
+         * Set call results
          *
-         * @param results text results to set
+         * @param results call results to set
+         * @return builder self reference
+         * @see <a href="https://developers.callfire.com/results-responses-errors.html">call states and results</a>
          */
         public Builder results(List<Call.CallResult> results) {
             request.results = results;