Commits

Kevin Wetzels  committed 031e59e

Add LICENSE and README

  • Participants
  • Parent commits 7c0a2db

Comments (0)

Files changed (3)

+Copyright 2013 Roam - Kevin Wetzels
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+# Bold.io Java client
+
+This is the official Java client of Bold.io's SMS management application. You
+can either download the jar from the source's `bin` directory or clone this
+repository and build the client yourself. You can find the dependencies in the
+included POM file (Google's libphonenumber and Guava and Jackson).
+
+## Usage
+
+First of all, when specifying a phone number as a `String`, you should opt for
+the [E.164 format](http://en.wikipedia.org/wiki/E.164).
+
+- Bad: `32475001122`
+- Bad: `0475001122`
+- Bad: `0032475001122`
+- Good: `+32475001122`
+
+Prefer the methods with the `PhoneNumber` arguments.
+
+### Construct a client
+
+    String endpoint = "http://localhost:8000";
+    String user = "yourusername";
+    String pwd = "yourpassword";
+    Client client = new DefaultClient(endpoint, user, pwd);
+    String number = "+32475001122";
+
+### Working with subscriptions
+
+When working with a number not yet registered with a contact in Bold or simply
+a number without subscriptions, calling `findSubscriptions` will return an
+empty list:
+
+    List<Subscriptions> subscriptions = client.findSubscriptions(number);
+    assertTrue(subscriptions.isEmpty());
+
+After subscribing that changes:
+
+    boolean subscribed = client.subscribe(number, "INFO");
+    if (subscribed) {
+        System.out.println(number + " is now subscribed");
+    } else {
+        System.out.println(number + " was already subscribed");
+    }
+    List<Subscriptions> subscriptions = client.findSubscriptions(number);
+    assertEquals(1, subscriptions.size());
+
+Of course, unsubscribing changes that again:
+
+    boolean unsubscribed = client.unsubscribe(number, "INFO");
+    if (unsubscribed) {
+        System.out.println(number + " is now unsubscribed");
+    } else {
+        System.out.println(number + " wasn't subscribed");
+    }
+    List<Subscriptions> subscriptions = client.findSubscriptions(number);
+    assertTrue(subscriptions.isEmpty());
+
+### Sending a message
+
+Sending a message requires you to know the id of the hub (displayed on the
+hub's detail page).
+
+    String hubId = "5";
+    String content = "Hey there!";
+    OutboundSms sms = client.send(hubId, number, content, null);
+
+This will send the message to the given number through the given hub and
+provide you with the registered information about that message. If you
+only want to send the message when the number is subscribed to for example
+`CATFACTS`, do this instead:
+
+    OutboundSms sms = client.send(hubId, number, content, "CATFACTS");
+
+### Replying to a message
+
+Replying to a message is even easier:
+
+    long messageId = 123L;
+    OutboundSms reply = client.reply(messageId, "Thanks for the message!");
+
+
+## Extras
+
+This repo includes a demo server for handling webhook actions from Bold. Run
+`demo/java/io/bold/WebhookHandler` and register its URL (default
+`http://localhost:9000/`) with as the URL of a webhook action in a bucket of
+choice and you'll see inbound messages being logged to standard out.
+
+## Questions? Bugs?
+
+Please contact kevin@roam.be.
     <artifactId>bold-client</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>jar</packaging>
+
     <name>bold-client</name>
     <description>Java client for Bold.io SMS hub.</description>
+    <url>http://bold.io</url>
+
+    <licenses>
+        <license>
+            <name>The Apache Software License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+            <distribution>repo</distribution>
+        </license>
+    </licenses>
+
+    <scm>
+        <url>https://bitbucket.org/roam/bold-java-client</url>
+    </scm>
 
     <dependencies>
         <dependency>
             <version>14.0-rc1</version>
         </dependency>
         <dependency>
-            <groupId>org.json</groupId>
-            <artifactId>json</artifactId>
-            <version>20090211</version>
-        </dependency>
-        <dependency>
-            <groupId>org.slf4j</groupId>
-            <artifactId>slf4j-api</artifactId>
-            <version>1.7.1</version>
-        </dependency>
-        <dependency>
-            <groupId>org.slf4j</groupId>
-            <artifactId>slf4j-log4j12</artifactId>
-            <version>1.7.1</version>
-        </dependency>
-        <dependency>
-            <groupId>junit</groupId>
-            <artifactId>junit</artifactId>
-            <version>4.8.1</version>
-            <scope>test</scope>
-        </dependency>
-        <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-databind</artifactId>
             <version>2.1.0</version>