workos 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fd3e38d33d428497a46f40df28c4d142bc9adaf90c166b61c05914030c50b25
-  data.tar.gz: c445aa218658fe1fb57add7cc9081b1e63223641d29cac1e276429d3fb1244fd
+  metadata.gz: 72c11606b98be63db5dab6a2c68eb69cab12ce9f9afe20b73475ce6948b24794
+  data.tar.gz: c7ea54043041810b71e2390b3efe20152870d8617da9a48a9922c775fb01f5d4
 SHA512:
-  metadata.gz: b94cf0c103286a457c3a73ab4ead5196ad2a8111f486ff22adbf4ecbdd5a21685dcb9483325b15813dcd5a25ea2383aec7d64fbc7545d4c80267731e97ed4a48
-  data.tar.gz: 30d4256a4b9218890dd880a5513dd90a09052f746085dffc282532bbf9ed5683b04d690181cfe1b209f02edc1fd1e37e04149819c8731afb81f5aba5561a2c18
+  metadata.gz: 8721f09bdcabce0772ffd6218b11859bbbdddb096f7d85c1b56b1f1b28816b8e2d86ef45838311e37c5c7bb322ffb2836d4ff355d8268ee15bbfcded71f1f658
+  data.tar.gz: 74b8126bedbd7c2f36da24376af99f2502d5ba3ac062c9067515d1fa6c5c402684ae0c6a3d2cfa42ee0ea61cbf75329b861a6362aa8fd7af361e58f8fff0604d

data/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# See GitHub's docs for more details:
+# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners
+
+# Rubyist Team
+* @workos-inc/ruby

data/.rubocop.yml

@@ -10,8 +10,12 @@ Layout/LineLength:
     - '(\A|\s)/.*?/'
 Metrics/BlockLength:
   ExcludedMethods: ['describe', 'context']
+Metrics/MethodLength:
+  Max: 15
 Metrics/ModuleLength:
   Max: 150
+Metrics/ParameterLists:
+  Max: 6
 Style/TrailingCommaInArguments:
   EnforcedStyleForMultiline: 'consistent_comma'
 Style/TrailingCommaInHashLiteral:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    workos (0.9.0)
+    workos (0.10.0)
       sorbet-runtime (~> 0.5)
 
 GEM
@@ -54,7 +54,7 @@ GEM
     simplecov-html (0.12.2)
     sorbet (0.5.5560)
       sorbet-static (= 0.5.5560)
-    sorbet-runtime (0.5.5943)
+    sorbet-runtime (0.5.6189)
     sorbet-static (0.5.5560-universal-darwin-14)
     unicode-display_width (1.6.0)
     vcr (5.0.0)

data/README.md

@@ -42,50 +42,9 @@ Alternatively, you may set the key yourself, such as in an initializer in your a
 WorkOS.key = '[your api key]'
 ```
 
-## The Audit Trail Module
-
-The Audit Trail Module provides methods for creating Audit Trail events on
-WorkOS.
-
-See our [Audit Trail
-Overview](https://docs.workos.com/audit-trail/overview) 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::AuditTrail.create_event(event: payload)
-```
-
-### Idempotency
-
-To perform an idempotent request, provide an additional idempotency_key
-parameter to the `create_event` options.
-
-```ruby
-WorkOS::AuditTrail.create_event(event: payload, idempotency_key: 'key123456')
-```
-
-See our [API
-Reference](https://docs.workos.com/audit-trail/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.
+The SSO Module provides convenient 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
@@ -94,7 +53,7 @@ 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: {})
+WorkOS::SSO.authorization_url(domain:, client_id:, redirect_uri:, state: {})
 ```
 
 > Generate an authorization URL to intitiate the WorkOS OAuth2 workflow.
@@ -102,25 +61,25 @@ WorkOS::SSO.authorization_url(domain:, project_id:, redirect_uri:, state: {})
 `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`)
+- `client_id` (string) — your application's WorkOS [Client 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.
+- `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 environment 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}`
+`https://${domain}/sso/authorize?response_type=code&client_id=${clientID}&redirect_uri=${redirectURI}&state=${state}`
 
 For example, when used in a [Sinatra app](http://sinatrarb.com/):
 
 ```ruby
 DOMAIN = 'example.com'
-PROJECT_ID = '{projectId}'
+CLIENT_ID = '{clientId}'
 REDIRECT_URI = 'http://localhost:4567/callback'
 
 get '/auth' do
   authorization_url = WorkOS::SSO.authorization_url(
     domain: DOMAIN,
-    project_id: PROJECT_ID,
+    client_id: CLIENT_ID,
     redirect_uri: REDIRECT_URI,
   )
 
@@ -130,14 +89,14 @@ 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`
+`https://api.workos.com/sso/authorize?response_type=code&client_id={clientID}&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>
+WorkOS::SSO.profile(code:, client_id:)
 ```
 
 > Fetch a WorkOS::Profile for an authorized user.
@@ -145,7 +104,7 @@ WorkOS::SSO.profile(code:, project_id:)</h4>
 `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`)
+- `client_id` (string) — your application's WorkOS [Client ID](https://dashboard.workos.com/sso/configuration) (ex. `project_01JG3BCPTRTSTTWQR4VSHXGWCQ`)
 
 This method will return an instance of a `WorkOS::Profile` with the following attributes:
 
@@ -168,17 +127,17 @@ This method will return an instance of a `WorkOS::Profile` with the following at
 >
 ```
 
-Our Sintatra app can be extended to use this method:
+Our Sinatra app can be extended to use this method:
 
 ```ruby
 DOMAIN = 'example.com'
-PROJECT_ID = '{projectId}'
+CLIENT_ID = '{clientId}'
 REDIRECT_URI = 'http://localhost:4567/callback'
 
 get '/auth' do
   authorization_url = WorkOS::SSO.authorization_url(
     domain: DOMAIN,
-    project_id: PROJECT_ID,
+    client_id: CLIENT_ID,
     redirect_uri: REDIRECT_URI,
   )
 
@@ -188,7 +147,7 @@ end
 get '/callback' do
   profile = WorkOS::SSO.profile(
     code: params['code'],
-    project_id: PROJECT_ID,
+    client_id: CLIENT_ID,
   )
 
   session[:user] = profile.to_json
@@ -198,3 +157,107 @@ end
 ```
 
 Given the `WorkOS::Profile`, you can now sign the user in according to your own authentication setup.
+
+## The Magic Link Module
+
+The Magic Link Module provides methods for authenticating a Passwordless user via WorkOS.
+
+First, you'll create a Passwordless Session for a Magic Link connection.
+Then, using the session ID, you'll email a user the Magic Link confirmation URL.
+The user can then click on that link to be authenticated to your application.
+
+> Create a Passwordless Session for a Magic Link Connection.
+
+`WorkOS::Passwordless.create_session` accepts four arguments:
+
+- `email` (string) - the email of the user to authenticate.
+- `type` (string) - The type of Passwordless Session to create. Currently, the only supported value is `MagicLink`.
+- `state` (optional, string) - Optional parameter that a Developer can choose to include in their authorization URL. If included, then the redirect URI received from WorkOS will contain the exact `state` that was passed in the authorization URL.
+- `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 environment on your WorkOS dashboard.
+
+This method will return a Passwordless Session object, containing the following attributes:
+
+- `id` (string) - the unique ID of the session.
+- `email` (string) - the email address of the user for the session.
+- `expires_at` (date) - the ISO-8601 datetime at which the session expires.
+- `link` (string) - the link for the user to authenticate with. You can use this link to send a custom email to the user, or send an email using the `WorkOS::Passwordless.send_session` method, described below.
+
+> Email a user the Magic Link confirmation URL.
+
+`WorkOS::Passwordless.send_session` accepts one argument:
+
+- `id` (string) - the unique identifier of the Passwordless Session to send an email for.
+
+This method will return a boolean confirming the Magic Link was sent.
+
+> Example with Sinatra application
+
+Our Sinatra app can be altered to use Magic Link:
+
+```ruby
+CLIENT_ID = '{clientId}'
+REDIRECT_URI = 'http://localhost:4567/callback'
+
+post '/passwordless-auth' do
+  session = WorkOS::Passwordless.create_session(
+    email: params[:email],
+    type: 'MagicLink',
+    redirect_uri: REDIRECT_URI
+  )
+  WorkOS::Passwordless.send_session(session.id)
+
+  redirect '/check-email'
+end
+
+get '/callback' do
+  profile = WorkOS::SSO.profile(
+    code: params['code'],
+    client_id: CLIENT_ID,
+  )
+
+  session[:user] = profile.to_json
+
+  redirect '/'
+end
+```
+
+## The Audit Trail Module
+
+The Audit Trail Module provides methods for creating Audit Trail events on
+WorkOS.
+
+See our [Audit Trail
+Overview](https://docs.workos.com/audit-trail/overview) 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::AuditTrail.create_event(event: payload)
+```
+
+### Idempotency
+
+To perform an idempotent request, provide an additional idempotency_key
+parameter to the `create_event` options.
+
+```ruby
+WorkOS::AuditTrail.create_event(event: payload, idempotency_key: 'key123456')
+```
+
+See our [API
+Reference](https://docs.workos.com/audit-trail/api-reference#idempotency)
+for more information on idempotency keys.