iterable-api-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e8201ff2a2c62a1817c30094aa37799ef99baa1
-  data.tar.gz: b4123101be7019b2f6961af79065546674ac70a4
+  metadata.gz: 6f1a6522fb06840f8b7c767538880aed5c69a690
+  data.tar.gz: d108b3a889f96eb9dd5eb4ec604be87d2854baec
 SHA512:
-  metadata.gz: d9a14a9ae700dad75fb3b2d07e1db0f4bcddc48915e4d2b593114aabec50f6df20e1000b408e650d73ab0c1ade50c32218ee801b5e282505485827002d79e80b
-  data.tar.gz: 41dcf29ebd25f1a842c76cd021de51fea96dd656827312f1f9e2bbf2a14daf653378709737f51d846c98d7721fcdff30a20f5e4f70023beaf57bf563f6b646ec
+  metadata.gz: 0daf7c4c00d23299e08f3cac3b74fd8473d89a9cd36d7c9479364232eb9b41ac61f5428c1c5d23aa0f766c01ee98ab806f3e1a7bebf622bec0f482399a89eaa1
+  data.tar.gz: 5e8ae858899f57becc8c21865735c8b00396215fd7b5e72b1fbd63e1f3cdb128bd6e74da17ff632fcb8eb69268a8635413b979a48d3becd3f749641cbc54d7a1

data/README.md

@@ -1,4 +1,6 @@
 # Iterable API Gem
+
+[![Gem](https://img.shields.io/gem/v/iterable-api-client.svg)](https://rubygems.org/gems/iterable-api-client)
 [![build status](https://gitlab.com/mtchavez/iterable/badges/master/build.svg)](https://gitlab.com/mtchavez/iterable/commits/master)
 [![coverage report](https://gitlab.com/mtchavez/iterable/badges/master/coverage.svg)](https://gitlab.com/mtchavez/iterable/commits/master)
 
@@ -6,9 +8,739 @@ Rubygem to interact with the [Iterable][iterable] API.
 
 ## Installation
 
-## Setup
+```ruby
+gem install iterable-api-client
+```
+
+or with Bundler in your `Gemfile`
+
+```ruby
+gem 'iterable-api-client'
+```
 
 ## Usage
 
+### Documentation
+
+Documentation can be found on [rubydoc][docs] or in this README
+
+### API Documentation
+
+The Iterable [API documentation][api-docs] can be a helpful reference for looking
+up all the possible endpoint data interactions. The docs outline all the possible
+parameters to each endpoints as well as custom data fields.
+
+### Configuration
+
+#### Global Config
+
+Configure the gem with a default global configuration to use.
+
+```ruby
+Iterable.configure do |config|
+  config.token = 'api-token'
+end
+```
+
+### Config Object
+
+If you have multiple tokens to use you can create a `Iterable::Config` object
+with a different token from the global default and pass in on requests.
+
+```ruby
+# Creating a new config with a different token
+conf = Iterable::Config.new(token: 'new-token')
+
+# Example of using it with the campaigns endpoints
+# which will then make API requests using the passed in config
+campaigns = Iterable::Campaigns.new(config)
+```
+
+### Responses
+
+Response objects will attempt to parse the API response as JSON using the `multi_json`
+gem so you can have your own JSON parser handle the loading of responses.
+
+You can access some of the response data for example:
+
+```ruby
+templates = Iterable::Templates.new
+response = templates.all
+
+# Check if the response code is a succesfull HTTP Code from 200-299
+response.success?
+
+# Get response code
+response.code
+
+# Body of response - will attempt to parse as JSON
+response.body
+
+# HTTP message
+response.message
+
+# The URI used to make the request for the response
+reponse.uri
+```
+
+## API Endpoints
+
+* [Campaigns](#campaigns)
+  * [All](#campaigns-all)
+  * [Create](#campaigns-create)
+  * [Metrics](#campaigns-metrics)
+  * [Child Campaigns](#campaigns-child)
+* [Channels](#channels)
+  * [All](#channels-all)
+* [Commerce](#commerce)
+  * [Track Purchase](#commerce-track-purchase)
+  * [Update Cart](#commerce-update-cart)
+* [Device](#device)
+  * [Register Device Token](#device-register-token)
+* [Email](#email)
+  * [View](#email-view)
+* [Email Templates](#email-templates)
+  * [Get](#email-templates-get)
+  * [Update](#email-templates-update)
+  * [Upsert](#email-templates-upsert)
+* [Events](#events)
+  * [For Email](#events-for-email)
+  * [Track](#events-track)
+  * [Track Push Open](#events-track-push-open)
+* [Experiments](#experiments)
+  * [Metrics](#experiments-metrics)
+* [Export](#export)
+  * [JSON](#export-json)
+  * [CSV](#export-csv)
+* [Lists](#lists)
+  * [All](#lists-all)
+  * [Create](#lists-create)
+  * [Delete](#lists-delete)
+  * [Get Users](#lists-users)
+  * [Subscribe](#lists-subscribe)
+  * [Unsubscribe](#lists-unsubscribe)
+* [Message Types](#message-types)
+  * [All](#message-types-all)
+* [Metadata](#metadata)
+  * [Get](#metadata-get)
+  * [List Keys](#metadata-list-keys)
+  * [Delete](#metadata-delete)
+  * [Get Key](#metadata-get-key)
+  * [Remove Key](#metadata-remove-key)
+  * [Add Key](#metadata-add-key)
+* [Push Templates](#push-templates)
+  * [Get](#push-templates-get)
+  * [Update](#push-templates-update)
+  * [Upsert](#push-templates-upsert)
+* [Templates](#templates)
+  * [All](#templates-all)
+  * [Get](#templates-get)
+* [Users](#users)
+  * [Update](#users-update)
+  * [Bulk Update](#users-bulk-update)
+  * [Update Subscriptions](#users-update-subscriptions)
+  * [Bulk Update Subscriptions](#users-bulk-update-subscriptions)
+  * [For Email](#users-for-email)
+  * [By User ID](#users-by-id)
+  * [Get Fields](#users-get-fields)
+  * [Update Email](#users-update-email)
+  * [Delete](#users-delete)
+  * [Delete By ID](#users-delete-by-id)
+  * [Register Browser Token](#users-register-browser-token)
+  * [Disable Device](#users-disable-device)
+  * [Get Sent Messages](#users-get-messages)
+* [Workflows](#workflows)
+  * [Trigger](#workflows-trigger)
+
+### Campaigns
+
+#### Campaigns All
+
+Endpoint: `GET /campaigns`
+
+```ruby
+campaigns = Iterable::Campaigns.new
+response = campaigns.all
+```
+
+#### Campaigns Create
+
+Endpoint: `POST /campaigns/create`
+
+```ruby
+campaigns = Iterable::Campaigns.new
+# List IDs to associate with the campaign
+list_ids = [1234, 1235, 1236]
+# Additional campaign attributes
+attrs = { dataFields: { foo: 'bar' } }
+response = campaigns.create 'name', 'template-id', list_ids, attrs
+```
+
+#### Campaigns Metrics
+
+Endpoint: `GET /campaigns/metrics`
+
+```ruby
+campaigns = Iterable::Campaigns.new
+campaign_ids = [754321, 4321, 3456]
+end_time = Time.now
+start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
+response = campaigns.metrics campaign_ids, start_time, end_time
+```
+
+#### Campaigns Rrecurring
+
+Endpoint: `GET /campaigns/recurring/{id}/childCampaigns`
+
+```ruby
+campaigns = Iterable::Campaigns.new
+response = campaigns.recurring 'campaign-id'
+```
+
+
+### Channels
+
+#### Channels All
+
+Endpoint: `GET /channels`
+
+```ruby
+channels = Iterable::Channels.new
+response = channels.all
+```
+
+### Commerce
+
+#### Commerce Track Purchase
+
+Endpoint: `POST /commerce/trackPurchase`
+
+```ruby
+# Set up items to track
+items = [{
+  id: 'abcd-1234-hjkl-4321',
+  name: 'Mustard',
+  price: 34.0,
+  quantity: 13
+}]
+# Calculate total of items i.e. 34.0
+total = items.reduce(0) { |total, item| total += item.fetch(:price, 0.0) }
+# Gather user information for purchase
+user = { userId: '42', email: 'user@example.com' }
+
+commerce = Iterable::Commerce.new
+response = commerce.track_purchase total, items, user
+```
+
+#### Commerce Update Cart
+
+Endpoint: `POST /commerce/updateCart`
+
+```ruby
+# Items to update the user's cart with
+items = [{
+  id: 'abcd-1234-hjkl-4321',
+  name: 'Mustard',
+  price: 34.0,
+  quantity: 13
+}]
+# User of the cart you want to update
+user = { userId: '42', email: 'user@example.com' }
+
+commerce = Iterable::Commerce.new
+response = commerce.update_cart items, user
+```
+
+### Device
+
+#### Device Register Token
+
+Endpoint: `POST /users/registerDeviceToken`
+
+```ruby
+data_fields = { some: 'data', fields: 'here' }
+device = Device.new 'token', 'mobile-push-app', Iterable::Device::APNS, data_fields
+device.register 'foo@example.com'
+
+# Can pass in a user ID as well
+device.register 'user@example.com', '42'
+```
+
+### Email
+
+#### Email View
+
+Endpoint: `GET /email/viewInBrowser`
+
+```ruby
+email = Iterable::Email.new
+response = email.view 'user@example.com', 'message-id'
+```
+
+### Email Templates
+
+#### Email Templates Get
+
+Endpoint: `GET /templates/email/get`
+
+```ruby
+templates = Iterable::EmailTemplates.new
+response = templates.get 'template-id'
+```
+
+#### Email Templates Update
+
+Endpoint: `POST /templates/email/update`
+
+```ruby
+templates = Iterable::EmailTemplates.new
+# Additional template attributes
+attrs = { metadata: {}, name: 'name', fromEmail: 'co@co.co' }
+response = templates.update 'template-id', attrs
+```
+
+#### Email Templates Upsert
+
+Endpoint: `POST /templates/email/update`
+
+```ruby
+templates = Iterable::EmailTemplates.new
+# Additional template attributes
+attrs = { metadata: {}, name: 'name', fromEmail: 'co@co.co' }
+response = templates.upsert 'client-template-id', attrs
+```
+
+### Events
+
+#### Events for Email
+
+Endpoint: `GET /events/{email}`
+
+```ruby
+events = Iterable::Events.new
+# Default limit of 30
+response = events.for_email 'user@example.com'
+```
+
+#### Events Track
+
+Endpoint: `POST /events/track`
+
+```ruby
+events = Iterable::Events.new
+# Any aditional attributes for the event
+attrs = { campaignId: 42, dataFields: {} }
+response = events.track 'event-name', 'user@example.com', attrs
+```
+
+#### Events Track Push Open
+
+Endpoint: `GET /events/{email}`
+
+```ruby
+events = Iterable::Events.new
+response = events.for_email 'user@example.com'
+campaign_id = 42
+message_id = 123
+# Any aditional attributes for the event
+attrs = { dataFields: {} }
+response = events.track_push_open campaign_id, message_id, 'user@example.com', attrs
+```
+
+### Experiments
+
+#### Experiments Metrics
+
+Endpoint: `GET /experiments/metrics`
+
+```ruby
+experiment_ids = [1, 2, 3, 4]
+experiments = Iterable::Experiments.new experiment_ids
+end_time = Time.now
+start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
+response = experiments.metrics campaign_ids, start_time, end_time
+```
+
+### Export
+
+#### Export JSON
+
+Endpoint: `GET /export/data.json`
+
+```ruby
+exporter = Iterable::JsonExporter.new Iterable::Export::EMAIL_SEND_TYPE
+
+# Export with an iterable range
+response = exporter.export_range Iterable::Export::BEFORE_TODAY
+
+# Export with a custom time range
+end_time = Time.now
+start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
+response = exporter.export start_time, end_time
+```
+
+#### Export CSV
+
+Endpoint: `GET /export/data.csv`
+
+```ruby
+exporter = Iterable::CsvExporter.new Iterable::Export::EMAIL_SEND_TYPE
+
+# Export with an iterable range
+response = exporter.export_range Iterable::Export::BEFORE_TODAY
+
+# Export with a custom time range
+end_time = Time.now
+start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
+response = exporter.export start_time, end_time
+```
+
+### Lists
+
+#### Lists All
+
+Endpoint: `GET /lists`
+
+```ruby
+lists = Iterable::Lists.new
+response = lists.all
+```
+
+#### Lists Create
+
+Endpoint: `POST /lists`
+
+```ruby
+lists = Iterable::Lists.new
+response = lists.create 'list-name'
+```
+
+#### Lists Delete
+
+Endpoint: `DELETE /lists/{listId}`
+
+```ruby
+lists = Iterable::Lists.new
+response = lists.delete 'list-id'
+```
+
+#### Lists Get Users
+
+Endpoint: `GET /lists/getUsers`
+
+```ruby
+lists = Iterable::Lists.new
+response = lists.users 'list-id'
+```
+
+#### Lists Subscribe
+
+Endpoint: `POST /lists/subscribe`
+
+```ruby
+lists = Iterable::Lists.new
+subscribers = [
+	{ email: 'user@example.com', dataFields: {}, userId: '42' }
+]
+response = lists.subscribe 'list-id', subscribers
+```
+
+#### Lists Unsubscribe
+
+Endpoint: `POST /lists/unsubscribe`
+
+```ruby
+lists = Iterable::Lists.new
+subscribers = [
+	{ email: 'user@example.com', dataFields: {}, userId: '42' }
+]
+response = lists.unsubscribe 'list-id', subscribers
+```
+
+### Message Types
+
+#### Message Types All
+
+Endpoint: `GET /messageTypes`
+
+```ruby
+metadata = Iterable::MessageTypes.new
+response = metadata.all
+```
+
+### Metadata
+
+#### Metadata Get
+
+Endpoint: `GET /metadata`
+
+```ruby
+metadata = Iterable::Metadata.new
+response = metadata.get
+```
+
+#### Metadata List Keys
+
+Endpoint: `GET /metadata/{table}`
+
+```ruby
+metadata_table = Iterable::MetadataTable.new 'table-name'
+response = metadata_table.list_keys
+
+# Next marker is thenext result set id which is returned by previous
+# search if more hits exist
+response = metadata_table.list_keys 'next-marker-id'
+```
+
+#### Metadata Delete Key
+
+Endpoint: `DELETE /metadata/{table}`
+
+```ruby
+metadata_table = Iterable::MetadataTable.new 'table-name'
+response = metadata_table.delete
+```
+
+#### Metadata Get Key
+
+Endpoint: `GET /metadata/{table}/{key}`
+
+```ruby
+metadata_table = Iterable::MetadataTable.new 'table-name'
+response = metadata_table.get 'metadata-key'
+```
+
+#### Metadata Remove Key
+
+Endpoint: `DELETE /metadata/{table}/{key}`
+
+```ruby
+metadata_table = Iterable::MetadataTable.new 'table-name'
+response = metadata_table.remove 'metadata-key'
+```
+
+#### Metadata Add Key
+
+Endpoint: `PUT /metadata/{table}/{key}`
+
+```ruby
+metadata_table = Iterable::MetadataTable.new 'table-name'
+value = { foo: 'bar', data: 'stuffs' }
+response = metadata_table.add 'metadata-key', value
+```
+
+### Push Templates
+
+#### Push Templates Get
+
+Endpoint: `GET /templates/push/get`
+
+```ruby
+templates = Iterable::PushTemplates.new
+# Additional template params to query by
+params = { locale: 'en-US' }
+response = templates.get 'template-id', params
+```
+
+#### Push Templates Update
+
+Endpoint: `POST /templates/push/update`
+
+```ruby
+templates = Iterable::PushTemplates.new
+# Additional template attrs to update
+attrs = { name: 'Template', message: 'Template message'}
+response = templates.update 'client-template-id', attrs
+```
+
+#### Push Templates Upsert
+
+Endpoint: `POST /templates/push/upsert`
+
+```ruby
+templates = Iterable::PushTemplates.new
+# Additional template attrs to upsert
+attrs = { name: 'Template', message: 'Template message'}
+response = templates.upsert 'client-template-id', attrs
+```
+
+### Templates
+
+#### Templates All
+
+Endpoint: `GET /templates`
+
+```ruby
+templates = Iterable::Templates.new
+# Additional params to filter and search by
+params = { templateType: Iterable::Templates::BLAST_TYPE, messageMedium: Iterable::MessageTypes::EMAIL_MEDIUM }
+response = templates.all params
+```
+
+#### Templates Get
+
+Endpoint: `GET /templates/getByClientTemplateId`
+
+```ruby
+templates = Iterable::Templates.new
+response = templates.for_client_template_id 'client-template-id'
+```
+
+### Users
+
+#### Users Update
+
+Endpoint: `POST /users/update`
+
+```ruby
+users = Iterable::Users.new
+# Additional attributes to send
+attrs = { userID: 'custom-id' }
+response = users.update 'user@example.com', attrs
+```
+
+#### Users Bulk Update
+
+Endpoint: `POST /users/bulkUpdate`
+
+```ruby
+users = Iterable::Users.new
+# Array of users to update by email with additional
+# fields if needed
+users = [
+	{ email: 'user@example.com', userID: 'custom-id' }
+]
+response = users.bulk_update users
+```
+
+#### Users Update Subscriptions
+
+Endpoint: `POST /users/updateSubscriptions`
+
+```ruby
+users = Iterable::Users.new
+# Additional attributes to send
+attrs = { userID: 'custom-id' }
+response = users.update_subscriptions 'user@example.com', attrs
+```
+
+#### Users Bulk Update Subscriptions
+
+Endpoint: `POST /users/bulkUpdateSubscriptions`
+
+```ruby
+users = Iterable::Users.new
+# Array of users to update by email with additional
+# fields if needed
+users = [
+	{ email: 'user@example.com', userID: 'custom-id' }
+]
+response = users.bulk_update_subscriptions users
+```
+
+#### Users For Email
+
+Endpoint: `GET /users/{email}`
+
+```ruby
+users = Iterable::Users.new
+response = users.for_email 'user@example.com'
+```
+
+#### Users For ID
+
+Endpoint: `GET /users/byUserID/{userID}`
+
+```ruby
+users = Iterable::Users.new
+response = users.for_id '42'
+```
+
+#### Users Get Fields
+
+Endpoint: `GET /users/getFields`
+
+```ruby
+users = Iterable::Users.new
+response = users.fields
+```
+
+#### Users Update Email
+
+Endpoint: `POST /users/updateEmail`
+
+```ruby
+users = Iterable::Users.new
+response = users.update_email 'old-email@me.com', 'new-email@email.me'
+```
+
+#### Users Delete
+
+Endpoint: `DELETE /users/{email}`
+
+```ruby
+users = Iterable::Users.new
+response = users.delete 'user@example.com'
+```
+
+#### Users Delete By ID
+
+Endpoint: `DELETE /users/byUserId/{userID}`
+
+```ruby
+users = Iterable::Users.new
+response = users.delete_by_id '42'
+```
+
+#### Users Register Browser Token
+
+Endpoint: `POST /users/registerBrowserToken`
+
+```ruby
+users = Iterable::Users.new
+# Additional attrs to associate with token
+attrs = { userID: '42' }
+response = users.register_browser_token 'user@example.com', 'the-token', attrs
+```
+
+#### Users Disable Device
+
+Endpoint: `POST /users/registerBrowserToken`
+
+```ruby
+users = Iterable::Users.new
+response = users.disable_device 'the-token', 'user@example.com'
+
+# Optionally can use a user ID over email
+response = users.disable_device 'the-token', nil, '42'
+```
+
+#### Users Get Sent Messages
+
+Endpoint: `POST /users/update`
+
+```ruby
+users = Iterable::Users.new
+# Additional params to filter and query by
+params = { campaignId: 'custom-id', limit: 30 }
+end_time = Time.now
+start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
+response = users.sent_messages 'user@example.com', start_time, end_time, params
+```
+
+### Workflows
+
+#### Workflows Trigger
+
+Endpoint: `POST /workflows/triggerWorkflow`
+
+```ruby
+workflows = Iterable::Workflows.new
+# Additional attributes to send
+attrs = { listId: 'listId' }
+response = workflows.trigger 'workflow-id', attrs
+```
 
+[api-docs]: https://api.iterable.com/api/docs
+[docs]: http://www.rubydoc.info/gems/iterable-api-client
 [iterable]: https://iterable.com