passkit 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14879f088666efc426ff4d2861589f526991129dd83f91a70d7bf8867f64071c
-  data.tar.gz: d52fca69a103bb5fd958502449e61ad194ba41928b8d1337c7f715cd799add79
+  metadata.gz: 37dfbf2ceba4423e2a1eba28d94aa8f5fbf676c011429efb8759af2f7fd8c477
+  data.tar.gz: 5909695a00d94a28da5f4ae1ee318a1d7d7320c8599646457a408b7c2a780af0
 SHA512:
-  metadata.gz: 37a9f00cc34e6f272ebb811a199fb9457eb750297b616bfd487cb091b48dad0fae0d5782674c50a70033eadd803767bdccc11b53f6e6b4149b5ecbf5c619bf54
-  data.tar.gz: ac193511be72f80a214a3e4bf4dd149430fc2682b4381368e6352e19635010298c623fe1b6c51b9b6f1323a062f023f1c2c45e53123a4fc801e2dfe9785be80d
+  metadata.gz: 637340fef65ed2655a1e8bedaf9d86a5ece533782bbd6c3c92a26d2e49d5153de1be57e27977994b13b63e1f47a2b39b30e481c57539771b8c06b3f2db4b6691
+  data.tar.gz: 5350a3793c359fbbf00d197541e7b51577c93c46c68068f8e0f7cb852ff46f6c9d1f60e4a3a8c00fc66a52c82c6e95b94b768ff602b1c188bb887f3128214821

data/.example.env

@@ -0,0 +1,6 @@
+PASSKIT_WEB_SERVICE_HOST=https://localhost:3000
+PASSKIT_CERTIFICATE_KEY=path/to/certificate.key
+PASSKIT_PRIVATE_P12_CERTIFICATE=path/to/certificate.p12
+PASSKIT_APPLE_INTERMEDIATE_CERTIFICATE=path/to/AppleWWDRCA.cer
+PASSKIT_APPLE_TEAM_IDENTIFIER=XXXXXXXXXX
+PASSKIT_PASS_TYPE_IDENTIFIER=pass.com.example.pass

data/README.md

@@ -1,6 +1,31 @@
-# Passkit
+# <img src="./docs/wallet.png" alt="Goboony" height="50"/> Passkit
 
-Generate Wallet Passes for iOS.
+Your out-of-the-box solution to start serving Wallet Passes in your Ruby On Rails application.
+
+Do you have a QRCode or a Barcode anywhere in your app that you want to distribute as Wallet Pass, compatible for iOS and Android? Look no further!
+
+This gem provides everything necessary to distribute Wallet Passes in pkpass format, and gives you all the steps to follow for what we cannot provide.
+
+**We provide:**
+
+* A (not yet) fancy dashboard to manage your passes, registered devices and logs.
+* All API endpoints to serve your passes: create, register, update, unregister, etc...
+* All necessary ActiveRecord models.
+* A BasePass model that you can extend to create your own passes.
+* Some helpers to generate the necessary URLs, so that you can include them in the emails.
+* Examples for everything.
+
+**We don't provide (yet):**
+
+* Full tests coverage: we are working on it!
+* A fancy dashboard: our dashboard is really really simple right now. Pull requests are welcome!
+* Push notifications: this is the most wanted feature I believe. Pull requests are welcome!
+* Google Wallet integration: we use https://walletpasses.io/ on Android to read .pkpass format.
+
+## Apple documentation
+
+* [Apple Wallet Passes](https://developer.apple.com/documentation/walletpasses)
+* [Send Push Notifications](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns)
 
 ## Installation
 
@@ -18,9 +43,97 @@ Or install it yourself as:
 
     $ gem install passkit
 
+Run the initializer:
+
+    $ rails g passkit:install
+
+that will generate the migrations and the initializer file.
+
+Mount the engine in your `config/routes.rb`:
+
+```ruby
+mount Passkit::Engine => '/passkit', as: 'passkit'
+```
+
+and run `bin/rails db:migrate`.
+
+### Setup environment variables
+
+If you followed the installation steps, you already saw that Passkit provides
+you the tables and ActiveRecord models, and also an engine with the necessary APIs already implemented.
+
+Now is your turn. Before proceeding, you need to set these ENV variables:
+* `PASSKIT_WEB_SERVICE_HOST`
+* `PASSKIT_CERTIFICATE_KEY`
+* `PASSKIT_PRIVATE_P12_CERTIFICATE`
+* `PASSKIT_APPLE_INTERMEDIATE_CERTIFICATE`
+* `PASSKIT_APPLE_TEAM_IDENTIFIER`
+* `PASSKIT_PASS_TYPE_IDENTIFIER`
+
+We have a [specific guide on how to get all these](docs/passkit_environment_variables.md), please follow it.
+You cannot start using this library without these variables set, and we cannot do the work for you.
+
 ## Usage
 
-TODO: Write usage instructions here
+If you followed the installation steps and you have the ENV variables set, we can start looking at what is provided for you.
+
+### Dashboard
+
+Head to `http://localhost:3000/passkit/previews` and you will see a first `ExampleStoreCard` available for download.
+You can click on the button and you will obtain a `.pkpass` file that you can simply open or install on your phone.
+The dashboard has also a view for logs, and a view for emitted passes.
+
+### Mailer Helpers
+
+If you use mailer previews, you can create the following file in `spec/mailers/previews/passkit/example_mailer_preview.rb`:
+
+```ruby
+module Passkit
+  class ExampleMailerPreview < ActionMailer::Preview
+    def example_email
+      Passkit::ExampleMailer.example_email
+    end
+  end
+end
+```
+
+and head to `http://localhost:3000/rails/mailers/` to see an example of email with links to download the Wallet Pass.
+Please check the source code of [ExampleMailer](app/mailers/passkit/example_mailer.rb) to see how to distribute your own Wallet Passes.
+
+### Example Passes
+
+Please check the source code of the [ExampleStoreCard](lib/passkit/example_store_card.rb) to see how to create your own Wallet Passes.
+
+Again, looking at these examples, is the easiest way to get started.
+
+### Create your own Wallet Pass
+
+You can create your own Wallet Passes by creating a new class that inherits from `Passkit::BasePass` and 
+defining the methods that you want to override.
+
+You can define colors, fields and texts. You can also define the logo and the background image.
+
+You should place the images in a 'private/passkit/<your_downcased_passname>' folder.
+There is a [dummy app in the gem](test/dummy) that you can use to check how to create your own Wallet Passes.
+
+### Serve your Wallet Pass
+
+Use the [Passkit::UrlGenerator](lib/passkit/url_generator.rb) to generate the URL to serve your Wallet Pass. 
+You can initialize it with:
+
+```ruby
+Passkit::UrlGenerator.new(pass_class: Passkit::MyPass, generator: User.find(1))
+```
+
+and then use `.android` or `.ios` to get the URL to serve the Wallet Pass.
+Again, check the example mailer included in the gem to see how to use it.
+
+## Debug issues 
+
+* On Mac, open the `Console.app` to view the errors.
+* Check the logs on http://localhost:3000/passkit/logs
+* In case of error "The passTypeIdentifier or teamIdentifier provided may not match your certificate, 
+or the certificate trust chain could not be verified." the certificate (p12) might be expired.
 
 ## Development
 
@@ -30,7 +143,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/passkit. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/passkit/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/coorasse/passkit. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/coorasse/passkit/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -38,4 +151,10 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Passkit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/passkit/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Passkit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/coorasse/passkit/blob/master/CODE_OF_CONDUCT.md).
+
+## Credits
+
+* <a href="https://www.flaticon.com/free-icons/credit-card" title="credit card icons">Credit card icons created by Iconfromus - Flaticon</a>
+
+* https://www.sitepoint.com/whats-in-your-wallet-handling-ios-passbook-with-ruby/

data/app/controllers/passkit/api/v1/logs_controller.rb

@@ -0,0 +1,14 @@
+module Passkit
+  module Api
+    module V1
+      class LogsController < ActionController::API
+        def create
+          params[:logs].each do |message|
+            Log.create!(content: message)
+          end
+          render json: {}, status: :ok
+        end
+      end
+    end
+  end
+end

data/app/controllers/passkit/api/v1/passes_controller.rb

@@ -0,0 +1,58 @@
+module Passkit
+  module Api
+    module V1
+      class PassesController < ActionController::API
+        before_action :decrypt_payload, only: :create
+
+        def create
+          send_file(fetch_pass(@payload))
+        end
+
+        # @return If request is authorized, returns HTTP status 200 with a payload of the pass data.
+        # @return If the request is not authorized, returns HTTP status 401.
+        # @return Otherwise, returns the appropriate standard HTTP status.
+        def show
+          authentication_token = request.headers["Authorization"]&.split(" ")&.last
+          unless authentication_token.present?
+            render json: {}, status: :unauthorized
+            return
+          end
+
+          pass = Pass.find_by(serial_number: params[:serial_number], authentication_token: authentication_token)
+          unless pass
+            render json: {}, status: :unauthorized
+            return
+          end
+
+          pass_output_path = Passkit::Generator.new(pass).generate_and_sign
+
+          response.headers["last-modified"] = pass.last_update.strftime("%Y-%m-%d %H:%M:%S")
+          if request.headers["If-Modified-Since"].nil? ||
+              (pass.last_update.to_i > Time.zone.parse(request.headers["If-Modified-Since"]).to_i)
+            send_file(pass_output_path)
+          else
+            head :not_modified
+          end
+        end
+
+        private
+
+        def decrypt_payload
+          @payload = Passkit::UrlEncrypt.decrypt(params[:payload])
+          if DateTime.parse(@payload[:valid_until]).past?
+            head :not_found
+          end
+        end
+
+        def fetch_pass(payload)
+          generator = nil
+          if payload[:generator_class].present? && payload[:generator_id].present?
+            generator_class = payload[:generator_class].constantize
+            generator = generator_class.find(payload[:generator_id])
+          end
+          Passkit::Factory.create_pass(payload[:pass_class], generator)
+        end
+      end
+    end
+  end
+end

data/app/controllers/passkit/api/v1/registrations_controller.rb

@@ -0,0 +1,115 @@
+module Passkit
+  module Api
+    module V1
+      # TODO: check with authentication_token
+      # This Class Implements the Apple PassKit API
+      # @see Apple: https://developer.apple.com/library/archive/documentation/PassKit/Reference/PassKit_WebService/WebService.html
+      # @see Android: https://walletpasses.io/developer/
+      class RegistrationsController < ActionController::API
+        before_action :load_pass, only: %i[create destroy]
+        before_action :load_device, only: %i[show]
+
+        # @return If the serial number is already registered for this device, returns HTTP status 200.
+        # @return If registration succeeds, returns HTTP status 201.
+        # @return If the request is not authorized, returns HTTP status 401.
+        # @return Otherwise, returns the appropriate standard HTTP status.
+        def create
+          if @pass.devices.find_by(identifier: params[:device_id])
+            render json: {}, status: :ok
+            return
+          end
+
+          register_device
+          render json: {}, status: :created
+        end
+
+        # @return If there are matching passes, returns HTTP status 200
+        #         with a JSON dictionary with the following keys and values:
+        #         lastUpdated (string): The current modification tag.
+        #         serialNumbers (array of strings): The serial numbers of the matching passes.
+        # @return If there are no matching passes, returns HTTP status 204.
+        # @return Otherwise, returns the appropriate standard HTTP status
+        def show
+          if @device.nil?
+            render json: {}, status: :not_found
+            return
+          end
+
+          passes = fetch_registered_passes
+          if passes.none?
+            render json: {}, status: :no_content
+            return
+          end
+
+          render json: updatable_passes(passes).to_json
+        end
+
+        # @return If disassociation succeeds, returns HTTP status 200.
+        # @return If the request is not authorized, returns HTTP status 401.
+        # @return Otherwise, returns the appropriate standard HTTP status.
+        def destroy
+          devices = @pass.devices.where(device_id: params[:device_id],
+            pass_type_id: params[:pass_type_id])
+          if devices.any?
+            devices.delete_all
+            render json: {}, status: :ok
+          else
+            render json: {}, status: :unauthorized
+          end
+        end
+
+        private
+
+        def load_pass
+          authentication_token = request.headers["Authorization"]&.split(" ")&.last
+          unless authentication_token.present?
+            render json: {}, status: :unauthorized
+            return
+          end
+
+          @pass = Pass.find_by(serial_number: params[:serial_number], authentication_token: authentication_token)
+          unless @pass
+            render json: {}, status: :unauthorized
+          end
+        end
+
+        def load_device
+          @device = Passkit::Device.find_by(identifier: params[:device_id])
+        end
+
+        def register_device
+          @pass.devices.create!(identifier: params[:device_id], push_token: push_token)
+        end
+
+        def fetch_registered_passes
+          passes = @device.passes
+
+          if params[:passesUpdatedSince]&.present?
+            passes.all.filter { |a| a.generator.updated_at >= Date.parse(params[:passesUpdatedSince]) }
+          else
+            passes
+          end
+        end
+
+        def updatable_passes(passes)
+          {lastUpdated: Time.zone.now, serialNumbers: passes.pluck(:serial_number)}
+        end
+
+        # TODO: add authentication_token
+        # The value is the word ApplePass, followed by a space
+        # The value is the word AndroidPass (instead of ApplePass), followed by a space
+        def authentication_token
+          ""
+        end
+
+        def push_token
+          return unless request&.body
+
+          request.body.rewind
+          json_body = JSON.parse(request.body.read)
+          json_body["pushToken"]
+        end
+      end
+    end
+  end
+end

data/app/controllers/passkit/logs_controller.rb

@@ -0,0 +1,9 @@
+module Passkit
+  class LogsController < ActionController::Base
+    layout "passkit/application"
+
+    def index
+      @logs = Passkit::Log.order(created_at: :desc).first(100)
+    end
+  end
+end

data/app/controllers/passkit/passes_controller.rb

@@ -1,24 +1,9 @@
 module Passkit
-  class PassesController  < ActionController::Base
-    skip_before_action :verify_authenticity_token
-    before_action :decrypt_payload, only: :create
+  class PassesController < ActionController::Base
+    layout "passkit/application"
 
-    def create
-      send_file(fetch_pass(@payload))
-    end
-
-    private
-
-    def decrypt_payload
-      @payload = Passkit::UrlEncrypt.decrypt(params[:payload])
-      if DateTime.parse(@payload[:valid_until]).past?
-        head :not_found
-      end
-    end
-
-    def fetch_pass(payload)
-      generator = payload[:generator_type].constantize.find(payload[:generator_id])
-      Passkit::Factory.create_pass(generator)
+    def index
+      @passes = Passkit::Pass.order(created_at: :desc).includes(:devices).first(100)
     end
   end
 end

data/app/controllers/passkit/previews_controller.rb

@@ -0,0 +1,13 @@
+module Passkit
+  class PreviewsController < ActionController::Base
+    layout "passkit/application"
+
+    def index
+    end
+
+    def show
+      builder = Passkit.configuration.available_passes[params[:class_name]]
+      send_file Factory.create_pass(builder.call, params[:class_name].constantize)
+    end
+  end
+end

data/app/mailers/passkit/example_mailer.rb

@@ -0,0 +1,8 @@
+module Passkit
+  class ExampleMailer < ActionMailer::Base
+    def example_email
+      @passkit_url_generator = Passkit::UrlGenerator.new(Passkit::ExampleStoreCard, nil)
+      mail(to: "passkit@example.com", subject: "Here is an example of a passkit email")
+    end
+  end
+end

data/{lib → app/models}/passkit/device.rb

@@ -1,9 +1,9 @@
 module Passkit
   class Device < ActiveRecord::Base
-    validates_uniqueness_of :device_identifier
+    validates_uniqueness_of :identifier
     validates_uniqueness_of :push_token
 
-    has_many :registrations
+    has_many :registrations, foreign_key: :passkit_device_id
     has_many :passes, through: :registrations
   end
 end

data/app/models/passkit/pass.rb

@@ -0,0 +1,49 @@
+module Passkit
+  class Pass < ActiveRecord::Base
+    validates_uniqueness_of :serial_number
+    validates_presence_of :klass
+
+    belongs_to :generator, polymorphic: true, optional: true
+    has_many :registrations, foreign_key: :passkit_pass_id
+    has_many :devices, through: :registrations
+
+    delegate :file_name,
+      :pass_path,
+      :language,
+      :format_version,
+      :apple_team_identifier,
+      :foreground_color,
+      :background_color,
+      :web_service_url,
+      :barcode,
+      :voided,
+      :organization_name,
+      :description,
+      :logo_text,
+      :locations,
+      :pass_type_identifier,
+      :pass_type,
+      :header_fields,
+      :primary_fields,
+      :secondary_fields,
+      :auxiliary_fields,
+      :back_fields,
+      to: :instance
+
+    before_validation on: :create do
+      self.authentication_token ||= SecureRandom.hex
+      loop do
+        self.serial_number = SecureRandom.uuid
+        break unless self.class.exists?(serial_number: serial_number)
+      end
+    end
+
+    def instance
+      @instance ||= klass.constantize.new(generator)
+    end
+
+    def last_update
+      instance.last_update || updated_at
+    end
+  end
+end

data/app/models/passkit/registration.rb

@@ -0,0 +1,6 @@
+module Passkit
+  class Registration < ActiveRecord::Base
+    belongs_to :device, foreign_key: :passkit_device_id
+    belongs_to :pass, foreign_key: :passkit_pass_id
+  end
+end

data/app/views/layouts/passkit/application.html.erb

@@ -0,0 +1,16 @@
+<html>
+<head>
+  <title>Passkit Previews</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">
+</head>
+<body>
+
+  <%= yield %>
+
+<footer>
+  Made with ❤️ by <a href="https://github.com/sponsors/coorasse/">coorasse</a>.
+</footer>
+</body>
+</html>

data/app/views/passkit/example_mailer/example_email.html.erb

@@ -0,0 +1,15 @@
+<p>
+  Here is an example of an email message that contains a link to Download a Wallet Pass.
+</p>
+<p>
+  <a href="<%=@passkit_url_generator.ios %>">
+    <%=image_tag 'passkit/add_to_apple_wallet_en.png', style: 'width: 150px;' %>
+    Download a iOS Wallet Pass
+  </a>
+</p>
+<p>
+  <a href="<%=@passkit_url_generator.android %>">
+    <%=image_tag 'https://walletpasses.io/badges/badge_web_black_en@3x.png', style: 'width: 150px;' %>
+    Download an Android Wallet Pass
+  </a>
+</p>

data/app/views/passkit/logs/index.html.erb

@@ -0,0 +1,22 @@
+<header>
+  <h1>Passkit Logs</h1>
+  <%= render 'shared/passkit/navigation' %>
+</header>
+
+<main>
+    <h2>Last 100 log entries</h2>
+    <table>
+      <thead>
+        <th>Timestamp</th>
+        <th>Content</th>
+      </thead>
+      <tbody>
+      <% @logs.each do |log| %>
+        <tr>
+          <td><%= I18n.l(log.created_at) %></td>
+          <td><%= log.content.sub(/^\[.*\]/, '') %></td>
+        </tr>
+      <% end %>
+      </tbody>
+    </table>
+</main>

data/app/views/passkit/passes/index.html.erb

@@ -0,0 +1,32 @@
+<header>
+  <h1>Passkit Passes</h1>
+  <%= render 'shared/passkit/navigation' %>
+</header>
+
+<main>
+  <h2>Last 100 passes and registered devices</h2>
+  <table>
+    <thead>
+    <th>Created at</th>
+    <th>Generator</th>
+    <th>Pass Class</th>
+    <th>Devices</th>
+    </thead>
+    <tbody>
+    <% @passes.each do |pass| %>
+      <tr>
+        <td><%= I18n.l(pass.created_at) %></td>
+        <td><%= pass.generator.to_s %></td>
+        <td><%= pass.klass %></td>
+        <td>
+          <% pass.devices.each do |device| %>
+            <div>
+                <%= device.push_token %>
+            </div>
+          <% end %>
+        </td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+</main>

data/app/views/passkit/previews/index.html.erb

@@ -0,0 +1,21 @@
+<header>
+  <h1>Passkit Previews</h1>
+  <%= render 'shared/passkit/navigation' %>
+</header>
+<main>
+  <p>Here you can generate a Pass from the ones available. Configure your available passes with:</p>
+  <pre>
+  Passkit.configure do |config|
+    config.available_passes['Passkit::YourPass'] = -> { FactoryBot.create(:user) }
+  end
+</pre>
+  <p>Where you specify the class name as key and a function to generate a builder,
+    that will be passed used to generte the Pass</p>
+
+  <% Passkit.configuration.available_passes.each do |pass_class_name, _builder_function| %>
+    <article>
+      <h2><%= pass_class_name %></h2>
+      <%= link_to 'Generate and download', preview_path(pass_class_name) %>
+    </article>
+  <% end %>
+</main>

data/app/views/shared/passkit/_navigation.html.erb

@@ -0,0 +1,5 @@
+<nav>
+  <%=link_to 'Logs', logs_path %>
+  <%=link_to 'Passes', passes_path %>
+  <%=link_to 'Passes Previews', previews_path %>
+</nav>