Initial Open Source Commit

.gitignore

@@ -0,0 +1,2 @@
+dist/*
+node_modules/*

LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 Procore Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,82 @@
+# Procore Iframe Helpers
+
+## Usage
+
+Create a new context object by calling:
+
+```javascript
+const context = procoreIframeHelpers.initialize();
+```
+
+This context can be used to gather information about the current environment
+your iframe application is in, or to perform certain actions within the iframe.
+
+
+## Authentication
+
+For security reasons, Procore's login page will not render within an iframe. To
+resolve this issue, this library will launch a new window where the user can
+safely sign into Procore, and return an access token to your application.
+
+To begin, create a signin button and initialize the `procoreIframeHelpers`
+library:
+
+```html
+<button onclick="login">Sign in With Procore</button>
+
+<script>
+  const context = procoreIframeHelpers.initialize();
+
+  function login() {
+    // Will be filled in
+  }
+</script>
+```
+
+When the user clicks the button, the `login` function will be run. It should
+look like this:
+
+```javascript
+function login() {
+  context.authentication.authenticate({
+    // Some URL on your domain that will start the authentication process. In
+    // this case, /auth/procore will just forward the user onto the
+    // /oauth/authorize endpoint with the appropriate client id and redirect URL
+    url: "/auth/procore",
+
+    // A function to run if authentication is successful. Payload, you will see
+    // below, is sent by you at the last stage of the authentication flow.
+    // In this case, we don't need to use payload, and instead just forward the
+    // user onto some protected content
+    onSuccess: function(payload) {
+      window.location = "/protected/content"
+    },
+
+    // A function to run if authentication fails. We are just logging the error
+    // to the console, but you will want to display an error to the user. This
+    // function can be triggered by you, or will be triggered automatically if the
+    // user closes the authenication window
+    onFailure: function(error) {
+      console.log(error);
+    }
+  })
+}
+```
+
+At the end of the authentication flow, there is still one piece to be done. You
+must notify the iframe that authentication succeeded in the login window. To do
+that, render an html page with just this script tag:
+
+```javascript
+<script>
+  const context = procoreIframeHelpers.initialize();
+
+  // Not required to send a payload, but you can if you'd like. This is the
+  // payload passed to your onSuccess handler.
+  context.authentication.notifySuccess({})
+</script>
+```
+
+`notifySuccess` will send a message from the login window to your iframe
+application, triggering the `onSuccess` callback. This will also automatically
+close the login window for you.

examples/sinatra.rb

@@ -0,0 +1,113 @@
+require 'rubygems'
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'sinatra'
+  gem 'omniauth'
+  gem 'omniauth-procore'
+end
+
+require 'sinatra'
+require 'omniauth'
+
+class App < Sinatra::Base
+  configure do
+    enable :sessions
+    enable :inline_templates
+
+    use OmniAuth::Builder do
+      provider(:procore, ENV['PROCORE_CLIENT_ID'], ENV['PROCORE_CLIENT_SECRET'])
+    end
+  end
+
+  # Protected content. If user is not signed in, redirect them to the sign in
+  # page. Otherwise, display some content for the currently signed in user.
+  get '/' do
+    if session[:procore_id].nil?
+      redirect '/signin'
+    else
+      "Protected Content: Your Procore ID is #{session[:procore_id]}"
+    end
+  end
+
+  # Sign in page. Renders a sign in button, which when clicked will launch a
+  # new window where the user can sign in.
+  get '/signin' do
+    erb :signin
+  end
+
+  # Callback from Oauth. Renders the auth end template, which only renders a
+  # single script tag that calls the notifySuccess method. This method will
+  # message the main window letting it know that authentication succeeded.
+  get '/auth/procore/callback' do
+    auth = request.env['omniauth.auth']
+    session[:procore_id] = auth.info.procore_id
+
+    erb :auth_end
+  end
+
+  # Callback from Oauth. Reached when an error occurs during the Oauth flow.
+  # Renders a script tag which calls that notifyFailure method. This method
+  # will message the main window letting it know that authentication has
+  # failed.
+  get '/auth/failure' do
+    erb :auth_failure
+  end
+
+  run!
+end
+
+__END__
+
+@@layout
+<html>
+  <head>
+    <script src="/ProcoreIframeHelpers.js"></script>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>
+
+
+@@signin
+<div id="errors"></div>
+<button onclick="signin()">Sign in with Procore</button>
+
+<script>
+  var context = procoreIframeHelpers.initialize()
+
+  function signin() {
+    context.authentication.authenticate({
+      url: "/auth/procore",
+      onSuccess: function(payload) {
+        window.location = "/content";
+      },
+      onFailure: function(error) {
+        var textnode = document.createElement("p");
+        textnode.appendChild(document.createTextNode(error.reason))
+        textnode.style.color = "red"
+        document.getElementById("errors").appendChild(textnode)
+      }
+    })
+  }
+</script>
+
+
+@@auth_end
+<script>
+  const context = procoreIframeHelpers.initialize();
+  context.authentication.notifySuccess({})
+</script>
+
+
+@@auth_failure
+<script>
+  const context = procoreIframeHelpers.initialize();
+  context.authentication.notifyFailure({
+    type: "oauth_failure",
+    reason: "<%= params[:message] %>"
+  })
+</script>

package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@procore/procore-iframe-helpers",
+  "author": "Procore",
+  "homepage": "https://github.com/procore/procore-iframe-helpers",
+  "version": "0.0.1",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "build": "webpack"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "ts-loader": "^5.3.3",
+    "typescript": "^3.3.4000",
+    "uglifyjs-webpack-plugin": "^2.1.2",
+    "webpack": "^4.29.6",
+    "webpack-cli": "^3.3.0"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ]
+}