layer-api 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 538d2a8cc0b3bbd9b6ef83d72becf57b336f320a
-  data.tar.gz: 8521291618a62bfa87850ccf76947427b04cfb41
+  metadata.gz: 68514306a1bf3af9a052d78f8b05a0320187b8e8
+  data.tar.gz: bf7c980017a973f4161d4506a028c9946b1d9493
 SHA512:
-  metadata.gz: deb8c32cbaa0145116927020b171d2af2a9390217d3be88362033205b44fc16bd1b6edc04386d0eb7fe1e8941e3dff69d899e3497e2656bd6d1ee97ab6499ffa
-  data.tar.gz: 32b8602e8597ef2b784f9a68d67cd11a54640bdd2dc96b2bf1054cabb821dbbdf0095f78839234bfff42d38d89c90eb5d839606e0759184fae6428c268dd3f06
+  metadata.gz: 2ceea987ca922d113bb8fb8d96e696f8d8487a731915c68b28d78e4b1a6982e9ec8ad739d4324324ab51060ca3b0f2302f923bc6f6674efc85f5a1deffbebe87
+  data.tar.gz: d1b427e746217ed81afc5ed239113cffa7226ecb8b545a59416336841c0939a976987c24e538f934de20e95e5ae527595ea3b9f665f769271166e581d68f7b52

data/MIGRATING.md

@@ -0,0 +1,212 @@
+# Migrating from version `0.3.x` to `0.4`
+
+`0.4` introduces a pretty significant overhaul to the codebase, which isn't backwards compatible. There are a couple of reasons:
+
+* This gem was originally built with the purpose of only wrapping the [Platform API](https://developer.layer.com/docs/platform). Since then, Layer have added REST & Websocket API's, Webhook support, as well as adding more functionality to the Platform API.
+* While the existing code in `0.3.x` was fairly basic, it wasn't written in a way that is easily maintainable and extensible with all of Layer's API's
+
+If you are starting from `0.4` upwards, you can discard all of this.
+
+## Authentication
+In `0.3.x` authentication & setup would be done using the following:
+
+```ruby
+layer = Layer::Api::Client.new(
+  api_token: "your_api_token",
+  app_id: "your_app_id"
+)
+```
+
+In `0.4`, the following is required:
+
+```ruby
+layer = Layer::Platform::Client.new(api_token: "your_api_token", app_id: "your_app_id")
+```
+
+## Resources
+In `0.3.x`, each function returned a Hash containing a parsed JSON representation of each resource.
+
+`0.4` introduced `Resource` - A base class used to encapsulate each JSON response.
+
+`Resource` can allow attributes to be accessed with dot notation. Alternatively, you can return a Hashed version of the resource using `Resource.attributes`. For example:
+
+```ruby
+
+conv = layer.conversations.find("conversation_id")
+=> #<Layer::Resources::Conversation:0x007fea8b2be508 @attributes={...}>"
+
+conv.url
+=> "https://api.layer.com/apps/<APP_ID>/conversations/<CONV_ID>"
+
+conv.attributes
+=> {...}
+```
+
+## Retrieving conversations
+In `0.3.x` a conversation could be retrieved with:
+
+```ruby
+layer.get_conversation("conversation_id")
+```
+
+In `0.4`, the same result can be achieved with:
+
+```ruby
+conv = layer.conversations.find("conversation_id")
+conv.attributes
+
+```
+
+## Editing conversations
+
+In `0.3.x`:
+
+```ruby
+operations = [
+  {operation: "add", property: "participants", value: "user1"},
+  {operation: "add", property: "participants", value: "user2"}
+]
+
+layer.edit_conversation("conversation_id", operations)
+```
+
+In `0.4`:
+
+```ruby
+conv = layer.conversations.find("conversation_id")
+conv.update(operations)
+```
+
+## Sending messages
+
+In `0.3.x`:
+
+```ruby
+message = {
+  sender: {
+    name: "t-bone"
+  },
+  parts: [
+    {
+        body: "Hello, World!",
+        mime_type: "text/plain"
+    },
+    {
+        body: "YW55IGNhcm5hbCBwbGVhc3VyZQ==",
+        mime_type: "image/jpeg",
+        encoding: "base64"
+    }
+  ],
+  notification: {
+    text: "This is the alert text to include with the Push Notification.",
+    sound: "chime.aiff"
+  }
+}
+
+layer.send_message("conversation_id", message)
+```
+
+In `0.4`:
+
+```ruby
+conv = layer.conversations.find("conversation_id")
+conv.messages.create(message)
+```
+
+## Sending announcements
+
+In `0.3.x`:
+
+```ruby
+announcement = {
+  recipients: [ "1234", "5678" ],
+  sender: {
+    name: "The System"
+  },
+  parts: [
+    {
+        body: "Hello, World!",
+        mime_type: "text/plain"
+    },
+    {
+        body: "YW55IGNhcm5hbCBwbGVhc3VyZQ==",
+        mime_type: "image/jpeg",
+        encoding: "base64"
+    }
+  ],
+  notification: {
+    text: "This is the alert text to include with the Push Notification.",
+    sound: "chime.aiff"
+  }
+}
+
+layer.send_announcement(announcement)
+```
+
+In `0.4`:
+
+```ruby
+layer.announcements.send(announcement)
+```
+
+## Retrieving a users block list
+
+In `0.3.x`:
+
+```ruby
+layer.get_blocklist("user_id")
+```
+
+In `0.4`:
+
+```ruby
+user = layer.users.find("user_id")
+user.blocks.list
+```
+
+## Adding a user to a block list
+
+In `0.3.x`:
+
+```ruby
+layer.block_user("owner_id", "user_id")
+```
+
+In `0.4`:
+
+```ruby
+owner = layer.users.find("owner_id")
+owner.blocks.create(user_id: "user_id")
+```
+
+## Remove a user from another users block list
+
+In `0.3.x`:
+
+```ruby
+layer.unblock_user("owner_id", "user_id")
+```
+
+In `0.4`:
+
+```ruby
+block = layer.users.find("owner_id").blocks.find("user_id")
+block.destroy
+
+
+```
+
+## Generating identity tokens
+
+In `0.3.x`:
+
+```ruby
+layer.generate_identity_token(user_id: "1234", nonce: "your_random_nonce")
+```
+
+In `0.4.`:
+
+```ruby
+token = layer.generate_identity_token(user_id: "1234", nonce: "your_random_nonce")
+token.to_s
+```

data/README.md

@@ -1,11 +1,14 @@
-# Layer::Api
+# Layer API Ruby Client
 [![Build Status](https://travis-ci.org/cakejelly/layer-api.svg?branch=master)](https://travis-ci.org/cakejelly/layer-api) [![Gem Version](https://badge.fury.io/rb/layer-api.svg)](http://badge.fury.io/rb/layer-api)
 
-A very simple wrapper for the Layer Platform API.
+A very simple wrapper for Layer's Web API's
 
 If you want to learn more, check out the [official documentation](https://developer.layer.com/docs/platform).
 
-## Installation
+## Migrating from 0.3.x
+Version 0.4 is not compatible with older versions. SEE [MIGRATING](MIGRATING.md) for details on how to migrate your code to the latest version.
+
+## Installation ##
 
 Add this line to your application's Gemfile:
 
@@ -21,31 +24,68 @@ Or install it yourself as:
 
     $ gem install layer-api
 
+
 ## Usage
 
-### Authentication/setup
+### Resources
+All client methods return  `Resource` objects or a collection of `Resource` objects. Every attribute from a resource can be accessed calling attribute methods:
+
+```ruby
+conversation = platform.conversations.find("fb2f3a48-523d-4449-a57f-c6651fc6612c")
+#<Layer::Resources::Conversation:0x007fdb18b44bf0 @attributes={...}>
+
+# Get the stripped uuid for any resource
+conversation.uuid
+# => "fb2f3a48-523d-4449-a57f-c6651fc6612c"
+
+conversation.url
+# => "https://api.layer.com/apps/<APP_ID>/conversations/fb2f3a48-523d-4449-a57f-c6651fc6612c"
+
+# Retrieve all attributes
+conversation.attributes
+# => {"id" => "fb2f3a48-523d-4449-a57f-c6651fc6612c", "url" => "https://api.layer.com/apps/<APP_ID>/conversations/fb2f3a48-523d-4449-a57f-c6651fc6612c", ...}
+```
+
+### [Platform API](https://developer.layer.com/docs/platform)
+See the official [Platform API docs](https://developer.layer.com/docs/platform) for additional info.
+
+#### Authentication/setup
 
 ```ruby
-layer = Layer::Api::Client.new(
-  api_token: "your_api_token",
-  app_id: "your_app_id"
-)
+platform = Layer::Platform::Client.new(api_token: "your_api_token", app_id: "your_app_id")
+# => #<Layer::Platform::Client:0x007fdb19844f30 @api_token="...", @app_id="...">
 ```
-If you have `ENV['LAYER_API_TOKEN']` and `ENV['LAYER_APP_ID']` environment variables setup, they will be used by default don't need to be included:
+If you have `ENV['LAYER_API_TOKEN']` and `ENV['LAYER_APP_ID']` environment variables setup, they will be used by default and don't need to be included:
 ```ruby
-layer = Layer::Api::Client.new
+platform = Layer::Platform::Client.new
+# => #<Layer::Platform::Client:0x007fdb19844f30 @api_token="...", @app_id="...">
 ```
 
-### Retrieving conversations
+#### Retrieving Conversations ####
 
 ```ruby
-layer.get_conversation("conversation_id")
+user = platform.users.find("user_id")
+convs = user.conversations.list
+# => [#<Layer::Resources::Conversation>, #<Layer::Resources::Conversation>, ...]
+
 ```
 
-### Creating conversations
+#### Retrieving A Single Conversation ####
+
+```ruby
+# For a user
+user = platform.users.find("user_id")
+conv = user.conversations.find("conversation_id")
+# => #<Layer::Resources::Conversation:0x007fdb18b44bf0 @attributes={...}>
+
+# or alternatively
+conv = platform.conversations.find("conversation_id")
+# => #<Layer::Resources::Conversation:0x007fdb18b44bf0 @attributes={...}>
+```
+
+#### Creating Conversations ####
 
 ```ruby
-# A sample conversation
 conversation = {
   participants: [
     "1234",
@@ -57,24 +97,35 @@ conversation = {
   }
 }
 
-layer.create_conversation(conversation)
+platform.conversations.create(conversation)
+# => #<Layer::Resources::Conversation:0x007fdb18b44bf0 @attributes={...}>
 ```
 
-### Editing conversations
+#### Editing Conversations ####
 
 ```ruby
-# Sample edit operations
+conv = platform.conversations.find("conversation_id")
+
 operations = [
-  {operation: "add", property: "participants", value: "user1"},
-  {operation: "add", property: "participants", value: "user2"}
+  { operation: "add", property: "participants", value: "user1" },
+  { operation: "add", property: "participants", value: "user2" }
 ]
 
-layer.edit_conversation(operations)
+conv.update(operations)
+# => nil
 ```
+#### Deleting Conversations ####
+
+```ruby
+conv = platform.conversations.find("conversation_id")
+conv.destroy
+# => nil
+
+```
+
+#### Sending Messages ####
 
-### Sending messages
 ```ruby
-# A sample message to send
 message = {
   sender: {
     name: "t-bone"
@@ -96,14 +147,42 @@ message = {
   }
 }
 
-layer.send_message("conversation_id", message)
+conv = platform.conversations.find("conversation_id")
+conv.messages.create(message)
+# => #<Layer::Resources::Message:0x007fdb18b44bf0 @attributes={...}>
+```
+
+#### Retrieving Messages ####
+
+```ruby
+# From a specific user's perspective
+conv = platform.users.find("user_id").conversations.find("conversation_id")
+conv.messages.list
+# => [#<Layer::Resources::Message>, #<Layer::Resources::Message>, ...]
+
+# From the system's perspective
+conv = platform.conversations.find("conversation_id")
+conv.messages.list
+# => [#<Layer::Resources::Message>, #<Layer::Resources::Message>, ...]
+```
+
+#### Retrieving A Single Message ####
 
+```ruby
+# From a specific user's perspective
+user = platform.users.find("user_id")
+messages = user.messages.find("message_id")
+# => #<Layer::Resources::Message:0x007fdb18b44bf0 @attributes={...}>
+
+# From the systems perspective
+conv = platform.conversations.find("conversation_id")
+messages = conv.messages.find("message_id")
+# => #<Layer::Resources::Message:0x007fdb18b44bf0 @attributes={...}>
 ```
 
-### Sending Announcements
+#### Sending Announcements ####
 
 ```ruby
-# A sample announcement
 announcement = {
   recipients: [ "1234", "5678" ],
   sender: {
@@ -113,11 +192,6 @@ announcement = {
     {
         body: "Hello, World!",
         mime_type: "text/plain"
-    },
-    {
-        body: "YW55IGNhcm5hbCBwbGVhc3VyZQ==",
-        mime_type: "image/jpeg",
-        encoding: "base64"
     }
   ],
   notification: {
@@ -126,23 +200,68 @@ announcement = {
   }
 }
 
-layer.send_announcement(announcement)
+platform.announcements.create(announcement)
+# => #<Layer::Resources::Announcement:0x007fdb18b44bf0 @attributes={...}>
 ```
 
-### Managing User Block Lists
+#### Modifying A Users Block List ####
 
 ```ruby
-# Retrieves a users blocklist
-layer.get_blocklist("user_id")
+user = platform.users.find("user_id")
+
+operations = [
+    { operation: "add", property: "blocks", value: "blockMe1" },
+    { operation: "add", property: "blocks", value: "blockMe2" },
+    { operation: "remove", property: "blocks", value: "unblockMe" }
+]
+
+user.update(operations)
+# => nil
+```
 
-# Adds a user to another users blocklist
-layer.block_user("owner_id", "user_id")
+#### Retrieving A Users Block List
 
-# Removes a user from another users blocklist
-layer.unblock_user("owner_id", "user_id")
+```ruby
+user = platform.users.find("user_id")
+
+blocks = user.blocks.list
+# => [#<Layer::Resources::Block @attributes={...}>, [#<Layer::Resources::Block @attributes={...}>, ...]
 ```
 
-### Generating Identity Tokens
+#### Blocking Users
+
+```ruby
+# using params
+owner = platform.users.find("owner")
+owner.blocks.create(user_id: "blocked")
+# => #<Layer::Resources::Block @attributes={...}>
+
+# passing a User object
+owner = platform.users.find("owner")
+blocked = platform.users.find("blocked")
+
+owner.blocks.create(blocked)
+# => #<Layer::Resources::Block @attributes={...}>
+```
+
+#### Unblocking Users
+
+```ruby
+
+# using the blocked users id
+owner = platform.users.find("owner")
+owner.blocks.find("blocked_user").destroy
+# => nil
+
+# using a User object
+owner = platform.users.find("owner")
+blocked = platform.users.find("blocked")
+
+owner.blocks.find(blocked).destroy
+# => nil
+```
+
+#### Generating Identity Tokens ####
 See: [the official authentication guide](https://developer.layer.com/docs/android/guides#authentication)
 
 Make sure the following environment variables are set:
@@ -151,16 +270,20 @@ Make sure the following environment variables are set:
 `ENV['LAYER_PRIVATE_KEY']`
 
 ```ruby
-# Returns a valid signed identity token.
-layer.generate_identity_token(user_id: "1234", nonce: "your_random_nonce")
+# Returns a valid signed identity token. #
+token = platform.generate_identity_token(user_id: "1234", nonce: "your_random_nonce")
+# => #<Layer::IdentityToken:0x007f89b4adb890
+
+token.to_s
+# => "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInR.cCI6IkpXVCIsImN0eSI6ImxheWVyLWVpdDt2PTEiLCJraWQiOiJhNz.5YTE0MC02YzY3LTExZTUtYjM0Mi1jZGJmNDAwZTE5NDgifQ"
 ```
 
-## Development
+## Development ##
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+## Contributing ##
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/cakejelly/layer-api.