opium 1.5.3 → 1.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb9239c124be4e458967d7fe92d4073ea2cb996b
-  data.tar.gz: ee2dd7e877cfcd1892659b8645daa4b08cc9fc99
+  metadata.gz: 5e532f3a073fd1b08d3b659faf9a2012b75de256
+  data.tar.gz: c4df755ca1dd1d8f3af4822740e8bb086197679b
 SHA512:
-  metadata.gz: 770af57f72afb14bcf366157f7c3f4b7c628b44e0877e382441f628d2c2379d5e1449c07e57b7f59af6e3f4bc211e616a3d60139facf12d5f8d05d5aaff341d2
-  data.tar.gz: 9fb435ce9b0acfe2ebb5a18282cc6e5adb684fe5e83a818322cab5d1f04c213fb6fcdc9ff835690e9670016302fd2004da30607cfa7693415b18ff7b0cee3973
+  metadata.gz: 1caaf649218ecbc0ac3e69ae32bc5d8f087b2189ff9280f3b335010ae4173ee5dc7d74b7c9df987607205a1a6d667dde62df44e11d51c115d71e8f4c2ca7e3f9
+  data.tar.gz: fa9d3fdf08b4c3c635fd579529540aade5b3c7bcb5ceea1cc4fb56ad8e27edf5825aa37cfa767313625c31646baa7ae91f6414bba93711c92c0a97bdeaf5ed96

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.5.4
+### Resolved Issues
+- #55: Opium::Installation was not properly using the master key for performing queries. Parse requires the presence of the master key to perform any sort of non-id query on installations.
+
 ## 1.5.3
 ### New Features
 - #54: Installation queries are now supported by Opium::Push to perform a more finely targeted push.

data/README.md

@@ -285,6 +285,80 @@ JSON serialization is built around an object's `attributes` hash, which is publi
 
 Be aware that all Opium models use `ActiveModel::ForbiddenAttributesProtection` for mass assignment sanitization.
 
+### Special Models: User and Installation
+
+Parse defines a couple of utility classes for each app, which require special access privileges. Amongst these are two models for dealing with users of the app and the devices the app are installed on.
+
+Opium provides wrappers around these constructs, in the form of `Opium::User` and `Opium::Installation`. For the most part, these two classes behave exactly like other models. Both classes are inheritable, so you can extend either of them with more information as necessary. Please be aware that the new subclasses will still be wrapping the core parse model, rather than being new models within the app; this means that you can still access their data via their superclasses, but would lose the convenient access to custom data.
+
+#### Opium::User
+
+The user model comes with the following data defined upon it:
+
+| Field          | Data type      |
+|----------------|----------------|
+| id             | String         |
+| created_at     | DateTime       |
+| updated_at     | DateTime       |
+| username       | String         |
+| password       | String         |
+| email          | String         |
+| email_verified | Opium::Boolean |
+| session_token  | String         |
+
+To further customize the User model with other fields, associations, or scopes, you can subclass `Opium::User`, as in the following example:
+
+```ruby
+class CustomUser < Opium::User
+  field :gamer_score, type: Integer
+  has_many :high_scores
+end
+```
+
+Note that as `Opium::User` is already an `Opium::Model`, you do not need to include that module into the custom user.
+
+`Opium::User` provides a set of utility methods at the class level for handling user authentication and session handling.
+
+- `authenticate[!]`: takes two parameters, being the `username` and `password` combo to test. Passwords are assumed to be in cleartext, so plan accordingly. The bang version of this method will raise an exception on failure, while the regular method will silently fail with nil. Otherwise, returns the instance of `Opium::User` associated with the provided credentials.
+- `find_by_session_token`: takes a single parameter, the token to search for. Should the token be found, the associated user object is returned. If the token is not found, raises an exception.
+
+At the instance level, `Opium::User` also provides a set of methods for reseting the users password:
+
+- `reset_password[!]`: requires the user have a set email address. The bang variant will raise an exception on failure, while the regular method sets an error in the instance's `errors` object. Requests that parse reset the password for this current user, who will then get information sent to them via their email address.
+
+#### Opium::Installation
+
+The `Opium::Installation` class comes with a number of different fields predefined upon it:
+
+| Field           | Data Type |
+|-----------------|-----------|
+| id              | String    |
+| created_at      | DateTime  |
+| updated_at      | DateTime  |
+| badge           | Integer   |
+| channels        | Array     |
+| time_zone       | String    |
+| device_type     | Symbol    |
+| push_type       | Symbol    |
+| gcm_sender_id   | Integer   |
+| installation_id | String    |
+| device_token    | String    |
+| channel_uris    | Array     |
+| app_name        | String    |
+| app_version     | String    |
+| parse_version   | String    |
+| app_identifier  | String    |
+
+Like `Opium::User`, the `Installation` class may be extended to provide access to more information stored within the parse database:
+
+```ruby
+class CustomInstallation < Opium::Installation
+  field :notify_on_score_change, type: Opium::Boolean
+end
+```
+
+Installations provide a convenient method to perform advanced targeting when sending [push notifications](#push-notifications).
+
 ### Creating and updating models
 
 After defining a model with Opium, you might want to create new instances of it, or update the data of an existing instance. Opium has been designed to be familiar to anyone who has used other Rails-centric ORMs, such as ActiveRecord. In this regard, object creation follows two patterns: delayed persistence, and immediate persistence.
@@ -406,6 +480,35 @@ gem 'opium'
 
 Models and Criteria will gain the methods defined by Kaminari, and should be compatible with Kaminari's pagination partials.
 
+## Push Notifications
+
+Opium provides support for Parse's push endpoint via the `Opium::Push` class. The following attributes may be configured on a push before it is created:
+
+- `channels`: an array of strings, indicating the channels to send the push to.
+- `where`: used to perform an installation query. See [advanced targeting](#advanced-targeting) for more details.
+- `data`: a payload hash to be delivered as part of the push.
+- `expires_at`: the DateTime when the push expires; Parse will no longer attempt to send the notification after this time.
+- `push_at`: used to schedule the notification for some point in the future.
+- `exiration_interval`: used with `push_at`; specifies an interval, expressed in seconds relative to `push_at`, to attempt to send the notification for.
+
+Note that `expires_at` and `push_at` are mutually exclusive; Opium prioritizes `push_at`. `push_at` can only be a value within a two week window of Time.now.
+
+Furthermore, the `data` payload has some common fields which are accessible from the push object itself:
+
+- `alert`: A message payload to send. Assumed to be a string.
+- `badge`: (iOS only) can be either a string value of "Increment" to increase the badge count by 1 on the receiving device, or a number indicating the new badge count.
+- `sound`: (iOS only) a string indicating the file within the app bundle to play upon receiving the notification.
+- `content_available`: (iOS only) will cause the app to trigger a background download if set to a value of 1.
+- `category`: (iOS only) the identifier of the UIUserNotificationCategory of this notification.
+- `uri`: (android only) specifies an Activity to be activated associated with the provided value.
+- `title`: (android only) the value displayed in for the push in the system tray.
+
+Note that note all of these data are supported on all platforms.
+
+Once the push has be configured as desired, it can be sent out by triggering the `create` method, which will either raise an error on failure or return true on success. Note that a truthy return value does not necessarily indicate that Parse has successfully sent any notifications; rather it merely indicates that Parse has successfully received the push request and did not find anything egregious in it.
+
+### Advanced Targeting
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/opium/fork )

data/lib/opium/installation.rb

@@ -3,7 +3,12 @@ module Opium
     include Opium::Model
 
     no_object_prefix!
-    requires_heightened_privileges!
+    no_really_i_need_master!
+
+    def self.inherited( subclass )
+      subclass.no_really_i_need_master!
+      super
+    end
 
     field :badge, type: Integer
     field :channels, type: Array

data/lib/opium/model/connectable.rb

@@ -103,6 +103,10 @@ module Opium
           @always_heightened_privileges = true
         end
 
+        def has_a_master_complex?
+          !@always_heightened_privileges.nil?
+        end
+
         private
 
         def http( method, options, &block )

data/lib/opium/version.rb

@@ -1,3 +1,3 @@
 module Opium
-  VERSION = "1.5.3"
+  VERSION = "1.5.4"
 end

data/spec/opium/installation_spec.rb

@@ -6,7 +6,7 @@ describe Opium::Installation do
 
   it { should be_an( Opium::Model ) }
 
-  it { expect( described_class ).to have_heightened_privileges }
+  it { expect( described_class ).to have_a_master_complex }
 
   describe '#object_prefix' do
     it { expect( described_class.object_prefix ).to be_empty }
@@ -41,7 +41,8 @@ describe Opium::Installation do
     it { is_expected.to respond_to( :field, :fields ) }
     it { expect( subject.fields.keys ).to include( 'badge', 'device_token', 'has_web_access' ) }
 
-    it { expect( subject ).to have_heightened_privileges }
+    # it { expect( subject ).to have_heightened_privileges }
+    it { expect( subject ).to have_a_master_complex }
 
     describe '#object_prefix' do
       it { expect( subject.object_prefix ).to be_empty }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opium
 version: !ruby/object:Gem::Version
-  version: 1.5.3
+  version: 1.5.4
 platform: ruby
 authors:
 - Joshua Bowers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-28 00:00:00.000000000 Z
+date: 2017-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler