apps 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d762a4824f66d6229928fc34470ea42b524e3b1bf3a4caf9a0fb8404f1ef24d
-  data.tar.gz: b091af6a9df6243fb7e266eb49a01c1b0b8e711cb713d7c236423af626f52549
+  metadata.gz: 76c0dd94631910ba52d822088647ffbe60838983b938472cb3d94d006e632720
+  data.tar.gz: 9001b062a90772948b2472bf08ca3ce4e1cdb58d74a590c08a67bed9e91d23b6
 SHA512:
-  metadata.gz: fc96c1269946cda1d7bfd47af3b90866cfb205e2a069b0db3e4e17ad5dce08f12344b5d48c0da5db22d699132b4d46caec0107963f20b0da6adf98526c73dbdb
-  data.tar.gz: 8c0d93de8530add374a3f006086f03b40752a38d1e18aa6561a9f00d9ceb987027f376b4cfddf9315a0f3c41ef1dd45ab9482bdfaf4de277485c3c259c5e0f33
+  metadata.gz: '058630fac77f03e0e9feb6b8648ad1809b8ba8de5990ae9323be349c16aad07734c153626180237e81013c920bcb4cca8fa98afb760738c13ce7214d20294dbd'
+  data.tar.gz: e937dcfa758a607370a5548eff21772f77c21c7445542b3a81e8225da497f689d355e27ee1d7ebafcb9724dd1a0606813fb25164443dec39fd1a386b518e98a6

data/.gitignore

@@ -11,3 +11,7 @@
 .rspec_status
 *.gem
 Gemfile.lock
+
+node_modules
+yarn.lock
+package-lock.json

data/README.md

@@ -4,9 +4,9 @@ This is a toolkit to easily integrate into platform marketplaces and extension p
 
 The Apps gem is currently under development, with the goal of facilitating the following:
 
-* Google
-  * [Gmail Add-ons](https://developers.google.com/gmail/add-ons/)
-  * [Gmail Email Markup](https://developers.google.com/gmail/markup/)
+* Gmail
+  * [Add-ons](https://developers.google.com/gmail/add-ons/)
+  * [Email Markup](https://developers.google.com/gmail/markup/)
   * AMP Pages
 * Microsoft Office 365
   * [Outlook Add-ins](https://docs.microsoft.com/en-us/outlook/add-ins/)
@@ -14,8 +14,8 @@ The Apps gem is currently under development, with the goal of facilitating the f
 * Slack
   * Bots
   * Commands
-* Heroku
-  * Addons Marketplace (SSO)
+* Heroku Elements Marketplace
+  * [Add-ons](https://devcenter.heroku.com/articles/building-an-add-on)
 * Facebook
   * Instant Articles
 
@@ -39,20 +39,75 @@ Or install it yourself as:
 
 ### Gmail Email Markup
 
-You can generate [schema.org](http://schema.org) markup for email in Gmail utilizing simple helper classes.
-
-* Use the helper methods in `Apps::Adapters::Gmail::Markup` to easily define your markup
-* Helper methods to generate an object model for you to "fill in":
-  * Confirm Action - `Apps::Adapters::Gmail::Markup#build_confirm_action`
-  * Save Action - `Apps::Adapters::Gmail::Markup#build_save_action`
-  * RSVP Action - `Apps::Adapters::Gmail::Markup#build_rsvp_action`
-  * View Action - `Apps::Adapters::Gmail::Markup#build_view_action`
-  * Track Action - `Apps::Adapters::Gmail::Markup#build_track_action`
-* Helper methods to serialize your object model:
-  * `as_json` generates a `Hash` represenation of metadata
-  * `to_json` generates a JSON string representation of metadata
-  * `to_script` generates a "pretty" JSON enclosed by `script` tags specifying `JSON-LD` type
-    * NOTE: `to_script` is only available on "context" objects that represent the root of the markup needed for embedding in emails. This is the object returned by each of the helper methods above for each "Action"
+You can generate [schema.org](http://schema.org) markup for email in Gmail utilizing simple helper classes. Use the helper methods in `Apps::Gmail::Markup` to easily define your markup.
+
+* [Confirm Action](https://developers.google.com/gmail/markup/reference/one-click-action)
+* [Save Action](https://developers.google.com/gmail/markup/reference/one-click-action)
+* [RSVP Action](https://developers.google.com/gmail/markup/reference/rsvp-action)
+* [View Action](https://developers.google.com/gmail/markup/reference/go-to-action)
+* [Track Action](https://developers.google.com/gmail/markup/reference/go-to-action)
+
+Explore `Apps::Gmail::Markup` and related classes to see how you can customize your metadata.
+
+```ruby
+require 'apps/gmail/markup'
+
+# Confirm Action (takes additional keyword options)
+confirm_action = Apps::Gmail::Markup.confirm_action('Button Text', 'http://example.org/confirm/endpoint')
+
+confirm_action.as_json
+# => {"@context"=>"http://schema.org", "@type"=>"EmailMessage", "potentialAction"=>{"@type"=>"ConfirmAction", "handler"=>{"@type"=>"HttpActionHandler", "url"=>"http://example.org/confirm/endpoint"}}}
+
+puts confirm_action.to_json
+# => {"@context":"http://schema.org","@type":"EmailMessage","potentialAction":{"@type":"ConfirmAction","handler":{"@type":"HttpActionHandler","url":"http://example.org/confirm/endpoint"}}}
+
+# NOTE: `to_script` is only available on "context" objects that represent the root of the markup
+#       needed for embedding in emails. This is the object returned by each of the helper methods
+#       above for each "Action"
+puts confirm_action.to_script
+# =>
+# <script type="application/ld+json">
+# {
+#   "@context": "http://schema.org",
+#   "@type": "EmailMessage",
+#   "potentialAction": {
+#     "@type": "ConfirmAction",
+#     "handler": {
+#       "@type": "HttpActionHandler",
+#       "url": "http://example.org/confirm/endpoint"
+#     }
+#   }
+# }
+# </script>
+
+# Save Action (takes additional keyword options)
+save_action = Apps::Gmail::Markup.save_action('Button Text', 'http://example.org/save/endpoint')
+
+# RSVP Action (takes additional keyword options)
+rsvp_action = Apps::Gmail::Markup.rsvp_action('Event Name',
+                yes_url:   'http://example.org/yes/endpoint',
+                no_url:    'http://example.org/no/endpoint',
+                maybe_url: 'http://example.org/maybe/endpoint'
+              )
+
+# View Action (takes additional keyword options)
+view_action = Apps::Gmail::Markup.view_action('Button Text', 'http://example.org/save/endpoint')
+
+# Track Action (takes additional keyword options)
+track_action = Apps::Gmail::Markup.track_action('Button Text', 'http://example.org/save/endpoint')
+```
+
+You need to [register with Google](https://developers.google.com/gmail/markup/registering-with-google) to get your actions approved.
+
+**Related Resoures:**
+
+* [Embeding JSON-LD in HTML Documents](https://json-ld.org/spec/latest/json-ld/#embedding-json-ld-in-html-documents)
+* [Test Your Schemas](https://developers.google.com/gmail/markup/testing-your-schema)
+  * [Email Markup Tester](https://www.google.com/webmasters/markup-tester/)
+  * [Structured Data Markup Helper](https://www.google.com/webmasters/markup-helper/?email=true)
+* [Register with Google](https://developers.google.com/gmail/markup/registering-with-google)
+* Articles:
+  * [A Guide to Setting up Gmail Inbox Actions](http://blog.meldium.com/home/2014/5/19/setting-up-gmail-inbox-actions) by Meldium
 
 #### TODO
 
@@ -60,6 +115,35 @@ You can generate [schema.org](http://schema.org) markup for email in Gmail utili
 * Email Markup helpers for other Gmail-supported metadata need to be implemented
 * Additional Gmail integrations need to be developed
 
+### Microsoft Office 365
+
+* [Office Developer](https://github.com/OfficeDev) - git repositories of example projects for Outlook Add-ins, etc.
+* [Yeoman generator](https://github.com/OfficeDev/generator-office) - generator for creating [Microsoft office Add-ins](https://docs.microsoft.com/en-us/office/dev/add-ins/)
+* [Message Card Playground](https://messagecardplayground.azurewebsites.net/) - test schema.org markup and how it generates add-in UI
+
+#### Outlook: Actionable Messages via Email
+
+All Actionable Card markup schemas supported by Microsoft Office are implemented in this library (see [Actionable message card reference](https://docs.microsoft.com/en-us/outlook/actionable-messages/card-reference)).
+
+```ruby
+require 'apps/outlook/actionable_messages'
+
+message_card = Apps::Outlook::ActionableMessages.message_card('Summary text', 'Title text')
+```
+
+You can take a look at (and run) [lib/examples.rb](./lib/examples.rb) to see some sample markup.
+
+    $ ruby lib/examples.rb
+
+You can get more example schemas or copy/paste the output of `examples.rb` to test rendering here: https://messagecardplayground.azurewebsites.net/
+
+**Related Resources:**
+
+* [Actionable Messages via Email](https://docs.microsoft.com/en-us/outlook/actionable-messages/actionable-messages-via-email)
+  * [Actionable message card reference](https://docs.microsoft.com/en-us/outlook/actionable-messages/card-reference)
+* [Register your service with the actionable email developer dashboard](https://docs.microsoft.com/en-us/outlook/actionable-messages/actionable-email-dev-dashboard)
+* [Register your connector with the Office 365 Connectors developer dashboard](https://docs.microsoft.com/en-us/outlook/actionable-messages/connectors-dev-dashboard) - setup a connector for users to authorize your add-in
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/setup

@@ -4,5 +4,4 @@ IFS=$'\n\t'
 set -vx
 
 bundle install
-
-# Do any other automated setup that you need to do here
+yarn install

data/lib/apps/common/schema.rb

@@ -0,0 +1,8 @@
+require_relative 'schema/base'
+
+module Apps
+  module Common
+    module Schema
+    end
+  end
+end

data/lib/apps/common/schema/base.rb

@@ -0,0 +1,91 @@
+require 'json'
+
+module Apps
+  module Common
+    module Schema
+      class Base
+        DEFAULT_CONTEXT = 'http://schema.org'
+
+        attr_reader :context,      # the schema.org URL if not the default
+                    :force_context # force including the default schema.org context if none specified
+
+        def initialize(**attrs)
+          prune(attrs).each { |name, value| instance_variable_set(:"@#{name}", value) }
+        end
+
+        def type
+          @type ||= self.class.name.split('::')[-1]
+        end
+
+        def serialize
+          {
+            "@context" => serialized_context,
+            "@type" => type
+          }
+        end
+
+        def serialize_hash(hash, key: 'name', value: 'value')
+          hash.map do |k, v|
+            {
+              key => k,
+              value => v
+            }
+          end
+        end
+
+        def serialized_context
+          if force_context
+            context || DEFAULT_CONTEXT
+          else
+            context
+          end
+        end
+        
+        def as_json(force_context: false)
+          serialized = serialize
+
+          if force_context == true
+            serialized['@context'] ||= DEFAULT_CONTEXT
+          elsif force_context.is_a?(String)
+            serialized['@context'] = force_context
+          end
+          
+          prune serialized
+        end
+
+        def to_json(force_context: false, pretty: false)
+          hash = as_json(force_context: force_context)
+
+          pretty ? JSON.pretty_generate(hash) : JSON.dump(hash)
+        end
+      
+        def to_script(force_context: false, pretty: true)
+          json = to_json(pretty: pretty, force_context: force_context)
+
+          %`<script type="application/ld+json">\n#{json}\n</script>`
+        end
+
+      protected
+
+        def prune(hash)
+          hash.each_with_object({}) do |(key, value), result|
+            # recursive prune
+            result[key] = case value
+                          when nil
+                            next
+                          when Array
+                            next if value.empty?
+                            value.map{ |v| v.is_a?(Hash) ? prune(v) : v }
+                          when Hash
+                            value = prune value
+                            next if value.empty?
+                            value
+                          else
+                            value
+                          end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apps/common/schema/concerns.rb

@@ -0,0 +1,10 @@
+require_relative 'concerns/potential_action'
+
+module Apps
+  module Common
+    module Schema
+      module Concerns
+      end
+    end
+  end
+end

data/lib/apps/common/schema/concerns/potential_action.rb

@@ -0,0 +1,35 @@
+module Apps
+  module Common
+    module Schema
+      module Concerns
+        module PotentialAction
+          # Handles the case when there is one action
+          def action
+            actions.first if actions.size == 1
+          end
+
+          def actions
+            @actions ||= [@action].compact
+          end
+
+          def serialize
+            if actions.any?
+              super.merge("potentialAction" => serialize_actions)
+            else
+              super
+            end
+          end
+          
+          def serialize_actions
+            # Gmail uses a hash for one action and an array for multiple.
+            # Outlook uses an array regardless and breaks if it's a hash.
+            # So we will always return an array.
+            
+            # action&.serialize || actions.map(&:serialize)
+            actions.map(&:serialize)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apps/gmail/markup.rb

@@ -0,0 +1,158 @@
+require_relative 'schema'
+
+module Apps
+  module Gmail
+    module Markup
+      class << self
+        # {
+        #   "@context": "http://schema.org",
+        #   "@type": "EmailMessage",
+        #   "potentialAction": {
+        #     "@type": "ConfirmAction",
+        #     "handler": {
+        #       "@type": "HttpActionHandler",
+        #       "url": "https://example.org/confirm/endpoint"
+        #     },
+        #     "name": "Action Name"
+        #   }
+        # }
+        def confirm_action(name, url, **attrs)
+          action = Schema::ConfirmAction.new(name: name, url: url)
+          root   = Schema::EmailMessage.new(action: action, **attrs)
+
+          root
+        end
+
+        # {
+        #   "@context": "http://schema.org",
+        #   "@type": "EmailMessage",
+        #   "potentialAction": {
+        #     "@type": "SaveAction",
+        #     "handler": {
+        #       "@type": "HttpActionHandler",
+        #       "url": "https://example.org/save/endpoint"
+        #     },
+        #     "name": "Action Name"
+        #   }
+        # }
+        def save_action(name, url, **attrs)
+          action = Schema::SaveAction.new(name: name, url: url)
+          root   = Schema::EmailMessage.new(action: action, **attrs)
+
+          root
+        end
+
+        # {
+        #   "@context": "http://schema.org",
+        #   "@type": "Event",
+        #   "name": "Action Name",
+        #   "location": {
+        #     "@type": "Place",
+        #     "address": {
+        #       "@type": "PostalAddress"
+        #     }
+        #   },
+        #   "potentialAction": [
+        #     {
+        #       "@type": "RsvpAction",
+        #       "handler": {
+        #         "@type": "HttpActionHandler",
+        #         "url": "http://example.org/yes/endpoint"
+        #       },
+        #       "rsvpResponse": "yes",
+        #       "attendance": "http://schema.org/RsvpAttendance/Yes"
+        #     },
+        #     {
+        #       "@type": "RsvpAction",
+        #       "handler": {
+        #         "@type": "HttpActionHandler",
+        #         "url": "http://example.org/no/endpoint"
+        #       },
+        #       "rsvpResponse": "no",
+        #       "attendance": "http://schema.org/RsvpAttendance/No"
+        #     },
+        #     {
+        #       "@type": "RsvpAction",
+        #       "handler": {
+        #         "@type": "HttpActionHandler",
+        #         "url": "http://example.org/maybe/endpoint"
+        #       },
+        #       "rsvpResponse": "maybe",
+        #       "attendance": "http://schema.org/RsvpAttendance/Maybe"
+        #     }
+        #   ]
+        # }
+        def rsvp_action(name, yes_url: nil, no_url: nil, maybe_url: nil, **attrs)
+          Schema::Event.new(name: name, **attrs).tap do |root|
+            root.build_location     unless root.location
+            root.build_rsvp_actions unless root.actions.any?
+
+            responses = {
+              'Yes' => yes_url,
+              'No' => no_url,
+              'Maybe' => maybe_url
+            }
+
+            # Specify RSVP URLs
+            responses.each do |response, url|
+              next if url.nil?
+
+              action = root.actions.find { |action| action.response == response }
+              action ||= root.add_action_for(response)
+
+              action.url = url
+            end
+          end
+        end
+
+        # {
+        #   "@context": "http://schema.org",
+        #   "@type": "EmailMessage",
+        #   "potentialAction": {
+        #     "@type": "ViewAction",
+        #     "name": "Action Name",
+        #     "target": "http://example.org/view/endpoint"
+        #   }
+        # }
+        def view_action(name, target, **attrs)
+          action = Schema::ViewAction.new(name: name, target: target)
+          root   = Schema::EmailMessage.new(action: action, **attrs)
+
+          root
+        end
+
+        # {
+        #   "@context": "http://schema.org",
+        #   "@type": "ParcelDelivery",
+        #   "deliveryAddress": {
+        #     "@type": "PostalAddress"
+        #   },
+        #   "carrier": {
+        #     "@type": "Organization"
+        #   },
+        #   "itemShipped": {
+        #     "@type": "Product"
+        #   },
+        #   "partOfOrder": {
+        #     "@type": "Order",
+        #     "merchant": {
+        #       "@type": "Organization"
+        #     }
+        #   },
+        #   "potentialAction": {
+        #     "@type": "TrackAction",
+        #     "name": "Action Name",
+        #     "target": "https://example.org/track/endpoint"
+        #   }
+        # }
+        def track_action(name, target, **attrs)
+          action = Schema::TrackAction.new(name: name, target: target)
+          
+          Schema::ParcelDelivery.new(action: action, **attrs).tap do |root|
+            root.build_delivery_address unless root.delivery_address
+          end
+        end
+      end
+    end
+  end
+end