workos 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4a148a2a3c606738d27e79bcaf6c599ed6dcbfe28f89fbfd19e49fa06616c02
-  data.tar.gz: 298806d027c6dd44d45a73f58c25fe8ac046de1e846f9cfe552e3ef4a1ea4b75
+  metadata.gz: 70741b6fe93402cbd090a16e41cf7ea2cb6df08073f1bdb95c0fc8ab06f7e5b5
+  data.tar.gz: 0a2726acf7ca96b490c4c66585dd3cf9ad0f70f89ec00991d69460ec8ec4907d
 SHA512:
-  metadata.gz: 91a635da667d2c6b84148df8c27667249e5e68888120837e934aff39b2a9c1df14f5c090b2755e5f1686cb26b549c9b5092570c193ff9055c9ef902f04325e7d
-  data.tar.gz: bddb0eaf54cbe9d95a9ffbe20ffa1ed8ba729aae5e0c5eeff7b1c86913ed8989cd7411ce30f44f4d9d499d8b6a576bb224e00beb4d1920700926d7143c08ed30
+  metadata.gz: 2d3d401843a2d5a19adf7a1ebb9e6c8cdf49228702cd93bf82fe5c2cb368ad9770bffe0a567d9e2e94772df4dad4ecbb2f594a37de9ddba3f8334648a270ec9e
+  data.tar.gz: a0a7f900ad0d0a60ccfb3aa8f5ac20e2f19dd0577cd27d9ecde782b4740ad50ef4bc2fbc326bca03fa7b7a55950bdfc73ef91db59c05904097ee753b79e09f59

data/.rubocop.yml

@@ -3,11 +3,14 @@ Layout/DotPosition:
 Layout/EmptyLineAfterMagicComment:
   Enabled: false
 Layout/EmptyLines:
-  Enabled: false  
+  Enabled: false
+Layout/LineLength:
+  IgnoredPatterns:
+    - 'VCR\.use_cassette'
+    - '(\A|\s)/.*?/'
 Metrics/BlockLength:
   ExcludedMethods: ['describe', 'context']
 Style/TrailingCommaInArguments:
   EnforcedStyleForMultiline: 'consistent_comma'
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: 'consistent_comma'
- 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    workos (0.0.2)
+    workos (0.1.0)
       sorbet-runtime (~> 0.5)
 
 GEM
@@ -56,14 +56,16 @@ GEM
     simplecov-html (0.10.2)
     sorbet (0.5.5181)
       sorbet-static (= 0.5.5181)
-    sorbet-runtime (0.5.5181)
+    sorbet-runtime (0.5.5182)
     sorbet-static (0.5.5181-universal-darwin-14)
     unicode-display_width (1.6.0)
     url (0.3.2)
+    vcr (5.0.0)
     webmock (3.7.6)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.22)
 
 PLATFORMS
   ruby
@@ -75,8 +77,10 @@ DEPENDENCIES
   rspec (~> 3.9.0)
   rubocop (~> 0.77)
   sorbet (~> 0.5)
+  vcr (~> 5.0.0)
   webmock
   workos!
+  yard
 
 BUNDLED WITH
    2.1.2

data/README.md

@@ -1,21 +1,192 @@
-# workos-rb
+# workos-ruby [![codecov](https://codecov.io/gh/workos-inc/workos-ruby/branch/master/graph/badge.svg)](https://codecov.io/gh/workos-inc/workos-ruby)
+
 WorkOS official Ruby gem for interacting with WorkOS APIs
 
+## Documentation
+
+Complete documentation for the latest version of WorkOS Ruby Gem can be found [here](https://workos-inc.github.io/workos-ruby/).
+
 ## Installation
 
-You don't need this source code unless you want to modify the gem. If you just
-want to use the package, just run:
+To get started, you can install the WorkOS gem via RubyGems with:
 
-```sh
+```ruby
 gem install workos
 ```
 
-If you want to build the gem from source:
+If you're using Bundler to manage your application's gems, add the WorkOS gem to your Gemfile:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'workos'
+```
+
+## Configuration
+
+To use the SDK you must first provide your API key from the [WorkOS Developer Dashboard](https://dashboard.workos.com/api-keys).
+
+You can do this through the `WORKOS_KEY` environment variable or by calling `WorkOS.key = [your API key]`.
+
+The WorkOS Gem will read the environment variable `WORKOS_KEY`:
 
 ```sh
-gem build workos.gemspec
+$ WORKOS_KEY=[your api key] ruby app.rb
+```
+
+Alternatively, you may set the key yourself, such as in an initializer in your application load path:
+
+```ruby
+# /config/initializers/workos.rb
+
+WorkOS.key = '[your api key]'
+```
+
+## The Audit Log Module
+
+The Audit Log Module provides methods for creating Audit Log events on
+WorkOS.
+
+See our [Audit Log
+Quickstart](https://dashboard.workos.com/docs/audit-log/quickstart) for
+more information.
+
+```ruby
+payload = {
+  group: 'Foo Corp',
+  location: '127.0.0.1',
+  action: 'user.created',
+  action_type: 'C',
+  actor_name: 'Foo',
+  actor_id: 'user_12345',
+  target_name: 'Bar',
+  target_id: 'user_67890',
+  occurred_at: '2020-01-10T15:30:00-05:00',
+  metadata: {
+    source: 'Email',
+  }
+}
+
+WorkOS::AuditLog.create_event(event: payload)
+```
+
+### Idempotency
+
+To perform an idempotent request, provide an additional idempotency_key
+parameter to the `create_event` options.
+
+```ruby
+WorkOS::AuditLog.create_event(event: payload, idempotency_key: 'key123456')
+```
+
+See our [API
+Reference](https://dashboard.workos.com/docs/api-reference#idempotency)
+for more information on idempotency keys.
+
+## The SSO Module
+
+The SSO Module provides convenience methods for authenticating a Single Sign On (SSO) user via WorkOS. WorkOS SSO follows the Oauth 2.0 specification.
+
+First, you'll direct your SSO users to an `authorization_url`. They will sign in to their SSO account with their Identity Provider, and be redirected to a
+callback URL that you set in your WorkOS Dashboard. The user will be redirected with a `code` URL parameter, which you can then exchange for a WorkOS::Profile
+using the `WorkOS::SSO.get_profile` method.
+
+See our Ruby SSO example app for a [complete example](https://github.com/workos-inc/ruby-sso-example).
+
+```ruby
+WorkOS::SSO.authorization_url(domain:, project_id:, redirect_uri:, state: {})
+```
+
+> Generate an authorization URL to intitiate the WorkOS OAuth2 workflow.
+
+`WorkOS::SSO.authorization_url` accepts four arguments:
+
+- `domain` (string) — the authenticating user's company domain, without protocol (ex. `example.com`)
+- `project_id` (string) — your application's WorkOS [Project ID](https://dashboard.workos.com/sso/configuration) (ex. `project_01JG3BCPTRTSTTWQR4VSHXGWCQ`)
+- `state` (optional, hash) — an optional hash used to manage state across authorization transactions (ex. `{ next_page: '/docs'}`)
+- `redirect_uri` (string) — a callback URL where your application redirects the user-agent after an authorization code is granted (ex. `workos.dev/callback`). This must match one of your configured callback URLs for the associated project on your WorkOS dashboard.
+
+This method will return an OAuth2 query string of the form:
+
+`https://${domain}/sso/authorize?response_type=code&client_id=${projectID}&redirect_uri=${redirectURI}&state=${state}`
+
+For example, when used in a [Sinatra app](http://sinatrarb.com/):
+
+```ruby
+DOMAIN = 'example.com'
+PROJECT_ID = '{projectId}'
+REDIRECT_URI = 'http://localhost:4567/callback'
+
+get '/auth' do
+  authorization_url = WorkOS::SSO.authorization_url(
+    domain: DOMAIN,
+    project_id: PROJECT_ID,
+    redirect_uri: REDIRECT_URI,
+  )
+
+  redirect authorization_url
+end
+```
+
+The user would be redirected to:
+
+`https://api.workos.com/sso/authorize?response_type=code&client_id={projectID}&redirect_uri=http://localhost:4567/callback`
+
+WorkOS takes over from here, sending the user to authenticate with their IDP, and on successful login, returns
+the user to your callback URL with a `code` parameter. You'll use `WorkOS::SSO.profile` to exchange the
+code for a `WorkOS::Profile`.
+
+```ruby
+WorkOS::SSO.profile(code:, project_id:)</h4>
+```
+
+> Fetch a WorkOS::Profile for an authorized user.
+
+`WorkOS::SSO.profile` accepts two arguments:
+
+- `code` (string) — an opaque string provided by the authorization server; will be exchanged for an Access Token when the user's profile is sent
+- `project_id` (string) — your application's WorkOS [Project ID](https://dashboard.workos.com/sso/configuration) (ex. `project_01JG3BCPTRTSTTWQR4VSHXGWCQ`)
+
+This method will return an instance of a `WorkOS::Profile` with the following attributes:
+
+```ruby
+<WorkOS::Profile:0x00007fb6e4193d20
+  @id="prof_01DRA1XNSJDZ19A31F183ECQW5",
+  @email="demo@workos-okta.com",
+  @first_name="WorkOS",
+  @connection_type="OktaSAML",
+  @last_name="Demo",
+  @idp_id="00u1klkowm8EGah2H357",
+>
 ```
 
-### Requirements
+Our Sintatra app can be extended to use this method:
+
+```ruby
+DOMAIN = 'example.com'
+PROJECT_ID = '{projectId}'
+REDIRECT_URI = 'http://localhost:4567/callback'
+
+get '/auth' do
+  authorization_url = WorkOS::SSO.authorization_url(
+    domain: DOMAIN,
+    project_id: PROJECT_ID,
+    redirect_uri: REDIRECT_URI,
+  )
+
+  redirect authorization_url
+end
+
+get '/callback' do
+  profile = WorkOS::SSO.profile(
+    code: params['code'],
+    project_id: PROJECT_ID,
+  )
+
+  session[:user] = profile.to_json
+
+  redirect '/'
+end
+```
 
-- Ruby 2.3+.
+Given the `WorkOS::Profile`, you can now sign the user in according to your own authentication setup.

data/bin/docs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
 
-yard -o docs
+bundle exec yard -o docs
 rm docs/index.html
-mv docs/_index.html docs/index.html
+mv docs/_index.html docs/index.html

data/codecov.yml

@@ -1,5 +1,6 @@
 coverage:
   status:
+    patch: off
     project:
       default:
         target: 90%

data/docs/WorkOS.html

@@ -6,15 +6,15 @@
 <title>
   Module: WorkOS
   
-    &mdash; Documentation by YARD 0.9.20
+    &mdash; Documentation by YARD 0.9.22
   
 </title>
 
-  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
 
-  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
 
-<script type="text/javascript" charset="utf-8">
+<script type="text/javascript">
   pathId = "WorkOS";
   relpath = '';
 </script>
@@ -79,7 +79,7 @@
   <dl>
     <dt>Defined in:</dt>
     <dd>lib/workos.rb<span class="defines">,<br />
-  lib/workos/sso.rb,<br /> lib/workos/base.rb,<br /> lib/workos/types.rb,<br /> lib/workos/profile.rb,<br /> lib/workos/version.rb,<br /> lib/workos/request_error.rb,<br /> lib/workos/types/profile_struct.rb</span>
+  lib/workos/sso.rb,<br /> lib/workos/base.rb,<br /> lib/workos/types.rb,<br /> lib/workos/client.rb,<br /> lib/workos/errors.rb,<br /> lib/workos/profile.rb,<br /> lib/workos/version.rb,<br /> lib/workos/audit_log.rb,<br /> lib/workos/types/provider_enum.rb,<br /> lib/workos/types/profile_struct.rb</span>
 </dd>
   </dl>
   
@@ -88,11 +88,7 @@
 <h2>Overview</h2><div class="docstring">
   <div class="discussion">
     
-<p>Use the WorkOS module to authenticate your requests to the WorkOS API. The
-gem will read your API key automatically from the ENV var `WORKOS_KEY`.
-Alternatively, you can set the key yourself with `WorkOS.key = [your api
-key]` somewhere in the load path of your application, such as an
-initializer.</p>
+<p>typed: strict</p>
 
 
   </div>
@@ -104,11 +100,11 @@ initializer.</p>
 <p class="children">
   
     
-      <strong class="modules">Modules:</strong> <span class='object_link'><a href="WorkOS/SSO.html" title="WorkOS::SSO (module)">SSO</a></span>, <span class='object_link'><a href="WorkOS/Types.html" title="WorkOS::Types (module)">Types</a></span>
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="WorkOS/AuditLog.html" title="WorkOS::AuditLog (module)">AuditLog</a></span>, <span class='object_link'><a href="WorkOS/Base.html" title="WorkOS::Base (module)">Base</a></span>, <span class='object_link'><a href="WorkOS/Client.html" title="WorkOS::Client (module)">Client</a></span>, <span class='object_link'><a href="WorkOS/SSO.html" title="WorkOS::SSO (module)">SSO</a></span>, <span class='object_link'><a href="WorkOS/Types.html" title="WorkOS::Types (module)">Types</a></span>
     
   
     
-      <strong class="classes">Classes:</strong> <span class='object_link'><a href="WorkOS/Base.html" title="WorkOS::Base (class)">Base</a></span>, <span class='object_link'><a href="WorkOS/Profile.html" title="WorkOS::Profile (class)">Profile</a></span>, <span class='object_link'><a href="WorkOS/RequestError.html" title="WorkOS::RequestError (class)">RequestError</a></span>
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="WorkOS/APIError.html" title="WorkOS::APIError (class)">APIError</a></span>, <span class='object_link'><a href="WorkOS/AuthenticationError.html" title="WorkOS::AuthenticationError (class)">AuthenticationError</a></span>, <span class='object_link'><a href="WorkOS/InvalidRequestError.html" title="WorkOS::InvalidRequestError (class)">InvalidRequestError</a></span>, <span class='object_link'><a href="WorkOS/Profile.html" title="WorkOS::Profile (class)">Profile</a></span>, <span class='object_link'><a href="WorkOS/WorkOSError.html" title="WorkOS::WorkOSError (class)">WorkOSError</a></span>
     
   
 </p>
@@ -129,7 +125,7 @@ initializer.</p>
         <dt id="VERSION-constant" class="">VERSION =
           
         </dt>
-        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.0.2</span><span class='tstring_end'>&#39;</span></span></pre></dd>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.1.0</span><span class='tstring_end'>&#39;</span></span></pre></dd>
       
     </dl>
   
@@ -238,15 +234,15 @@ initializer.</p>
       <pre class="lines">
 
 
+20
 21
-22
-23</pre>
+22</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/workos.rb', line 21</span>
+      <pre class="code"><span class="info file"># File 'lib/workos.rb', line 20</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_key'>key</span>
-  <span class='const'><span class='object_link'><a href="WorkOS/Base.html" title="WorkOS::Base (class)">Base</a></span></span><span class='period'>.</span><span class='id identifier rubyid_key'><span class='object_link'><a href="WorkOS/Base.html#key-class_method" title="WorkOS::Base.key (method)">key</a></span></span>
+  <span class='const'><span class='object_link'><a href="WorkOS/Base.html" title="WorkOS::Base (module)">Base</a></span></span><span class='period'>.</span><span class='id identifier rubyid_key'><span class='object_link'><a href="WorkOS/Base.html#key-class_method" title="WorkOS::Base.key (method)">key</a></span></span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -268,12 +264,12 @@ initializer.</p>
       <pre class="lines">
 
 
+24
 25
-26
-27</pre>
+26</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/workos.rb', line 25</span>
+      <pre class="code"><span class="info file"># File 'lib/workos.rb', line 24</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_key!'>key!</span>
   <span class='id identifier rubyid_key'>key</span> <span class='op'>||</span> <span class='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>WorkOS.key not set</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
@@ -298,15 +294,15 @@ initializer.</p>
       <pre class="lines">
 
 
+16
 17
-18
-19</pre>
+18</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/workos.rb', line 17</span>
+      <pre class="code"><span class="info file"># File 'lib/workos.rb', line 16</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_key='>key=</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
-  <span class='const'><span class='object_link'><a href="WorkOS/Base.html" title="WorkOS::Base (class)">Base</a></span></span><span class='period'>.</span><span class='id identifier rubyid_key'><span class='object_link'><a href="WorkOS/Base.html#key-class_method" title="WorkOS::Base.key (method)">key</a></span></span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span>
+  <span class='const'><span class='object_link'><a href="WorkOS/Base.html" title="WorkOS::Base (module)">Base</a></span></span><span class='period'>.</span><span class='id identifier rubyid_key'><span class='object_link'><a href="WorkOS/Base.html#key-class_method" title="WorkOS::Base.key (method)">key</a></span></span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -318,9 +314,9 @@ initializer.</p>
 </div>
 
       <div id="footer">
-  Generated on Wed Dec 18 08:33:35 2019 by
+  Generated on Thu Jan 30 09:12:47 2020 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.20 (ruby-2.4.9).
+  0.9.22 (ruby-2.6.5).
 </div>
 
     </div>

data/docs/WorkOS/APIError.html

@@ -0,0 +1,160 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Exception: WorkOS::APIError
+  
+    &mdash; Documentation by YARD 0.9.22
+  
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "WorkOS::APIError";
+  relpath = '../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../_index.html">Index (A)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../WorkOS.html" title="WorkOS (module)">WorkOS</a></span></span>
+     &raquo; 
+    <span class="title">APIError</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Exception: WorkOS::APIError
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName"><span class='object_link'><a href="WorkOSError.html" title="WorkOS::WorkOSError (class)">WorkOSError</a></span></span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">StandardError</li>
+          
+            <li class="next"><span class='object_link'><a href="WorkOSError.html" title="WorkOS::WorkOSError (class)">WorkOSError</a></span></li>
+          
+            <li class="next">WorkOS::APIError</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/workos/errors.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>APIError is a generic error that may be raised in cases where none of the other named errors cover the problem. It could also be raised in the case that a new error has been introduced in the API, but this version of the Ruby SDK doesn&#39;t know how to handle it.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
+
+
+
+
+
+  <h2>Instance Attribute Summary</h2>
+  
+  <h3 class="inherited">Attributes inherited from <span class='object_link'><a href="WorkOSError.html" title="WorkOS::WorkOSError (class)">WorkOSError</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="WorkOSError.html#http_status-instance_method" title="WorkOS::WorkOSError#http_status (method)">#http_status</a></span>, <span class='object_link'><a href="WorkOSError.html#request_id-instance_method" title="WorkOS::WorkOSError#request_id (method)">#request_id</a></span></p>
+
+
+
+  
+  
+  
+  
+  
+  
+  <h2>Method Summary</h2>
+  
+  <h3 class="inherited">Methods inherited from <span class='object_link'><a href="WorkOSError.html" title="WorkOS::WorkOSError (class)">WorkOSError</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="WorkOSError.html#initialize-instance_method" title="WorkOS::WorkOSError#initialize (method)">#initialize</a></span>, <span class='object_link'><a href="WorkOSError.html#to_s-instance_method" title="WorkOS::WorkOSError#to_s (method)">#to_s</a></span></p>
+
+  
+  <div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  
+    <p class="notice">This class inherits a constructor from <span class='object_link'><a href="WorkOSError.html#initialize-instance_method" title="WorkOS::WorkOSError#initialize (method)">WorkOS::WorkOSError</a></span></p>
+  
+</div>
+
+
+</div>
+
+      <div id="footer">
+  Generated on Thu Jan 30 09:12:47 2020 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.22 (ruby-2.6.5).
+</div>
+
+    </div>
+  </body>
+</html>