workos 0.11.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1368d9f2e05190d798f6b29b419ec7e4ad220074973f4fbd0e06096808854886
-  data.tar.gz: eaa0cb1aef9de77897c949cbd7c4652c24163f33b3f87fd67920c41ebea691de
+  metadata.gz: 5088a3dd82cef707b21e05ece2df2966516576c48f7f389aacaffe4c5301f755
+  data.tar.gz: ac715b624752ff8266a3fa714c698b77b4b1d8b64d38aaff9505882549715082
 SHA512:
-  metadata.gz: eb2a17a7450f9f54a91fdb1f2eeeb8ae63ee8d4fa9ffd4086d0e7f012e562130a6198dc7a8a9750b67312d7f678abb9a4a2e8f9af228df116386931cfcd92cba
-  data.tar.gz: 40e578a8e57f22675db3911c636564b8eeb31bda2d07685a0349d57da02fb09f1aab14e22c702939e44e3315e6dc6b138943e571893a41c57931f32bec407718
+  metadata.gz: 6552a77d12715130a9f8f90f46359b33f79d9ee0d076fd2d8ee47c403b9156d4f32a115e850482d2ca19da0b6f95bb226459835f73ff3304f3b63e3c7105df8c
+  data.tar.gz: baefeeb217e2394450fadfa3305e93da63b4dc7266c49d872c9d9c1394c1399dc767696432c6136a4272d3a554ed6408a33c3eabb7083461df5081f7e5fc032a

data/.rubocop.yml

@@ -20,3 +20,5 @@ Style/TrailingCommaInArguments:
   EnforcedStyleForMultiline: 'consistent_comma'
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: 'consistent_comma'
+AllCops:
+  TargetRubyVersion: 2.5

data/.semaphore/semaphore.yml

@@ -33,13 +33,13 @@ blocks:
         - name: Ruby 1.9.3
           commands:
             - checkout
-            - sem-version ruby 1.9.3
+            - sem-version ruby 1.9.3-p551
             - bundle install
             - bundle exec rspec
         - name: Ruby 2.0.0
           commands:
             - checkout
-            - sem-version ruby 2.0.0
+            - sem-version ruby 2.0.0-p648
             - bundle install
             - bundle exec rspec
         - name: Ruby 2.3.4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    workos (0.11.1)
+    workos (1.2.1)
       sorbet-runtime (~> 0.5)
 
 GEM
@@ -60,7 +60,7 @@ GEM
     simplecov_json_formatter (0.1.2)
     sorbet (0.5.6388)
       sorbet-static (= 0.5.6388)
-    sorbet-runtime (0.5.6391)
+    sorbet-runtime (0.5.6427)
     sorbet-static (0.5.6388-universal-darwin-14)
     sorbet-static (0.5.6388-universal-darwin-15)
     sorbet-static (0.5.6388-universal-darwin-16)

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 WorkOS
+Copyright (c) 2021 WorkOS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,22 +1,22 @@
-# 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 Ruby Library
 
-WorkOS official Ruby gem for interacting with WorkOS APIs
+The WorkOS library for Ruby provides convenient access to the WorkOS API from applications written in Ruby.
 
 ## Documentation
 
-Complete documentation for the latest version of WorkOS Ruby Gem can be found [here](https://workos-inc.github.io/workos-ruby/).
+See the [API Reference](https://workos.com/docs/reference/client-libraries) for Ruby usage examples.
 
 ## Installation
 
-To get started, you can install the WorkOS gem via RubyGems with:
+Install the package with:
 
-```ruby
+```
 gem install workos
 ```
 
 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'
@@ -24,17 +24,13 @@ 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_API_KEY` environment variable or by calling `WorkOS.key = [your API key]`.
-
-The WorkOS Gem will read the environment variable `WORKOS_API_KEY`:
+To use the library you must provide an API key, located in the WorkOS dashboard, as an environment variable `WORKOS_API_KEY`:
 
 ```sh
 $ WORKOS_API_KEY=[your api key] ruby app.rb
 ```
 
-Alternatively, you may set the key yourself, such as in an initializer in your application load path:
+Or, you may set the key yourself, such as in an initializer in your application load path:
 
 ```ruby
 # /config/initializers/workos.rb
@@ -42,222 +38,9 @@ Alternatively, you may set the key yourself, such as in an initializer in your a
 WorkOS.key = '[your api key]'
 ```
 
-## The SSO Module
-
-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
-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:, client_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`)
-- `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 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=${clientID}&redirect_uri=${redirectURI}&state=${state}`
-
-For example, when used in a [Sinatra app](http://sinatrarb.com/):
-
-```ruby
-DOMAIN = 'example.com'
-CLIENT_ID = '{clientId}'
-REDIRECT_URI = 'http://localhost:4567/callback'
-
-get '/auth' do
-  authorization_url = WorkOS::SSO.authorization_url(
-    domain: DOMAIN,
-    client_id: CLIENT_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={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:, client_id:)
-```
-
-> 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
-- `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:
-
-```ruby
-<WorkOS::Profile:0x00007fb6e4193d20
-  @id="prof_01DRA1XNSJDZ19A31F183ECQW5",
-  @email="demo@workos-okta.com",
-  @first_name="WorkOS",
-  @connection_id="conn_01EMH8WAK20T42N2NBMNBCYHAG",
-  @connection_type="OktaSAML",
-  @last_name="Demo",
-  @idp_id="00u1klkowm8EGah2H357",
-  @raw_attributes={
-    :id=>"prof_01DRA1XNSJDZ19A31F183ECQW5",
-    :email=>"demo@workos-okta.com",
-    :first_name=>"WorkOS",
-    :last_name=>"Demo",
-    :idp_id=>"00u1klkowm8EGah2H357"
-  },
->
-```
-
-Our Sinatra app can be extended to use this method:
-
-```ruby
-DOMAIN = 'example.com'
-CLIENT_ID = '{clientId}'
-REDIRECT_URI = 'http://localhost:4567/callback'
-
-get '/auth' do
-  authorization_url = WorkOS::SSO.authorization_url(
-    domain: DOMAIN,
-    client_id: CLIENT_ID,
-    redirect_uri: REDIRECT_URI,
-  )
-
-  redirect authorization_url
-end
-
-get '/callback' do
-  profile = WorkOS::SSO.profile(
-    code: params['code'],
-    client_id: CLIENT_ID,
-  )
-
-  session[:user] = profile.to_json
-
-  redirect '/'
-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')
-```
+## More Information
 
-See our [API
-Reference](https://docs.workos.com/audit-trail/api-reference#idempotency)
-for more information on idempotency keys.
+* [Single Sign-On Guide](https://workos.com/docs/sso/guide)
+* [Directory Sync Guide](https://workos.com/docs/directory-sync/guide)
+* [Admin Portal Guide](https://workos.com/docs/admin-portal/guide)
+* [Magic Link Guide](https://workos.com/docs/magic-link/guide)

data/lib/workos.rb

@@ -35,9 +35,11 @@ module WorkOS
   autoload :Directory, 'workos/directory'
   autoload :DirectoryGroup, 'workos/directory_group'
   autoload :Organization, 'workos/organization'
+  autoload :Organizations, 'workos/organizations'
   autoload :Passwordless, 'workos/passwordless'
   autoload :Portal, 'workos/portal'
   autoload :Profile, 'workos/profile'
+  autoload :ProfileAndToken, 'workos/profile_and_token'
   autoload :SSO, 'workos/sso'
   autoload :DirectoryUser, 'workos/directory_user'
 

data/lib/workos/client.rb

@@ -19,7 +19,7 @@ module WorkOS
 
     sig do
       params(
-        request: T.any(Net::HTTP::Get, Net::HTTP::Post, Net::HTTP::Delete),
+        request: T.any(Net::HTTP::Get, Net::HTTP::Post, Net::HTTP::Delete, Net::HTTP::Put),
       ).returns(::T.untyped)
     end
     def execute_request(request:)
@@ -36,9 +36,10 @@ module WorkOS
         path: String,
         auth: T.nilable(T::Boolean),
         params: T.nilable(Hash),
+        access_token: T.nilable(String),
       ).returns(Net::HTTP::Get)
     end
-    def get_request(path:, auth: false, params: {})
+    def get_request(path:, auth: false, params: {}, access_token: nil)
       uri = URI(path)
       uri.query = URI.encode_www_form(params) if params
 
@@ -47,7 +48,7 @@ module WorkOS
         'Content-Type' => 'application/json',
       )
 
-      request['Authorization'] = "Bearer #{WorkOS.key!}" if auth
+      request['Authorization'] = "Bearer #{access_token || WorkOS.key!}" if auth
       request['User-Agent'] = user_agent
       request
     end
@@ -90,6 +91,23 @@ module WorkOS
       request
     end
 
+    sig do
+      params(
+        path: String,
+        auth: T.nilable(T::Boolean),
+        idempotency_key: T.nilable(String),
+        body: T.nilable(Hash),
+      ).returns(Net::HTTP::Put)
+    end
+    def put_request(path:, auth: false, idempotency_key: nil, body: nil)
+      request = Net::HTTP::Put.new(path, 'Content-Type' => 'application/json')
+      request.body = body.to_json if body
+      request['Authorization'] = "Bearer #{WorkOS.key!}" if auth
+      request['Idempotency-Key'] = idempotency_key if idempotency_key
+      request['User-Agent'] = user_agent
+      request
+    end
+
     sig { returns(String) }
     def user_agent
       engine = defined?(::RUBY_ENGINE) ? ::RUBY_ENGINE : 'Ruby'

data/lib/workos/connection.rb

@@ -5,11 +5,12 @@ module WorkOS
   # The Connection class provides a lightweight wrapper around
   # a WorkOS Connection resource. This class is not meant to be instantiated
   # in user space, and is instantiated internally but exposed.
+  # Note: status is deprecated - use state instead
   class Connection
     extend T::Sig
 
     attr_accessor :id, :name, :connection_type, :domains, :organization_id,
-                  :status
+                  :state, :status
 
     sig { params(json: String).void }
     def initialize(json)
@@ -20,6 +21,7 @@ module WorkOS
       @connection_type = T.let(raw.connection_type, String)
       @domains = T.let(raw.domains, Array)
       @organization_id = T.let(raw.organization_id, String)
+      @state = T.let(raw.state, String)
       @status = T.let(raw.status, String)
     end
 
@@ -30,6 +32,7 @@ module WorkOS
         connection_type: connection_type,
         domains: domains,
         organization_id: organization_id,
+        state: state,
         status: status,
       }
     end
@@ -46,6 +49,7 @@ module WorkOS
         connection_type: hash[:connection_type],
         domains: hash[:domains],
         organization_id: hash[:organization_id],
+        state: hash[:state],
         status: hash[:status],
       )
     end

data/lib/workos/organizations.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'net/http'
+
+module WorkOS
+  # The Organizations module provides resource methods for working with Organizations
+  module Organizations
+    class << self
+      extend T::Sig
+      include Base
+      include Client
+
+      # Retrieve a list of organizations that have connections configured
+      # within your WorkOS dashboard.
+      #
+      # @param [Array<String>] domains Filter organizations to only return those
+      #  that are associated with the provided domains.
+      # @param [String] before A pagination argument used to request
+      #  organizations before the provided Organization ID.
+      # @param [String] after A pagination argument used to request
+      #  organizations after the provided Organization ID.
+      # @param [Integer] limit A pagination argument used to limit the number
+      #  of listed Organizations that are returned.
+      sig do
+        params(
+          options: T::Hash[Symbol, String],
+        ).returns(WorkOS::Types::ListStruct)
+      end
+      def list_organizations(options = {})
+        response = execute_request(
+          request: get_request(
+            path: '/organizations',
+            auth: true,
+            params: options,
+          ),
+        )
+
+        parsed_response = JSON.parse(response.body)
+
+        organizations = parsed_response['data'].map do |organization|
+          ::WorkOS::Organization.new(organization.to_json)
+        end
+
+        WorkOS::Types::ListStruct.new(
+          data: organizations,
+          list_metadata: parsed_response['listMetadata'],
+        )
+      end
+
+      # Get an Organization
+      #
+      # @param [String] id Organization unique identifier
+      #
+      # @example
+      #   WorkOS::Portal.get_organization(id: 'org_02DRA1XNSJDZ19A31F183ECQW9')
+      #   => #<WorkOS::Organization:0x00007fb6e4193d20
+      #         @id="org_02DRA1XNSJDZ19A31F183ECQW9",
+      #         @name="Foo Corp",
+      #         @domains=
+      #          [{:object=>"organization_domain",
+      #            :id=>"org_domain_01E6PK9N3XMD8RHWF7S66380AR",
+      #            :domain=>"foo-corp.com"}]>
+      #
+      # @return [WorkOS::Organization]
+      sig { params(id: String).returns(WorkOS::Organization) }
+      def get_organization(id:)
+        request = get_request(
+          auth: true,
+          path: "/organizations/#{id}",
+        )
+
+        response = execute_request(request: request)
+
+        WorkOS::Organization.new(response.body)
+      end
+
+      # Create an organization
+      #
+      # @param [Array<String>] domains List of domains that belong to the
+      #  organization
+      # @param [String] name A unique, descriptive name for the organization
+      sig do
+        params(
+          domains: T::Array[String],
+          name: String,
+        ).returns(WorkOS::Organization)
+      end
+      def create_organization(domains:, name:)
+        request = post_request(
+          auth: true,
+          body: { domains: domains, name: name },
+          path: '/organizations',
+        )
+
+        response = execute_request(request: request)
+        check_and_raise_organization_error(response: response)
+
+        WorkOS::Organization.new(response.body)
+      end
+
+      # Update an organization
+      #
+      # @param [String] organization Organization unique identifier
+      # @param [Array<String>] domains List of domains that belong to the
+      #  organization
+      # @param [String] name A unique, descriptive name for the organization
+      sig do
+        params(
+          organization: String,
+          domains: T::Array[String],
+          name: String,
+        ).returns(WorkOS::Organization)
+      end
+      def update_organization(organization:, domains:, name:)
+        request = put_request(
+          auth: true,
+          body: { domains: domains, name: name },
+          path: "/organizations/#{organization}",
+        )
+
+        response = execute_request(request: request)
+        check_and_raise_organization_error(response: response)
+
+        WorkOS::Organization.new(response.body)
+      end
+
+      # Delete an Organization
+      #
+      # @param [String] id Organization unique identifier
+      #
+      # @example
+      #   WorkOS::SSO.delete_organization(id: 'org_01EHZNVPK3SFK441A1RGBFSHRT')
+      #   => true
+      #
+      # @return [Bool] - returns `true` if successful
+      sig { params(id: String).returns(T::Boolean) }
+      def delete_organization(id:)
+        request = delete_request(
+          auth: true,
+          path: "/organizations/#{id}",
+        )
+
+        response = execute_request(request: request)
+
+        response.is_a? Net::HTTPSuccess
+      end
+
+      private
+
+      sig { params(response: Net::HTTPResponse).void }
+      def check_and_raise_organization_error(response:)
+        begin
+          body = JSON.parse(response.body)
+          return unless body['message']
+
+          message = body['message']
+          request_id = response['x-request-id']
+        rescue StandardError
+          message = 'Something went wrong'
+        end
+
+        raise APIError.new(
+          message: message,
+          http_status: nil,
+          request_id: request_id,
+        )
+      end
+    end
+  end
+end