Add domain_data to Organizations Create and Update methods to repla…

…ce `domains` (#291)

* Add `domain_data` and mark `domains` as deprecated

* Fix development warnings and other test noise

* Rubocop fixes

* Replace with `any_args`

These assertions don't really care about the internal behavior of
`WorkOS::Deprecation`.

* Rubocop

lib/workos.rb

@@ -49,6 +49,7 @@ def self.key
   autoload :Client, 'workos/client'
   autoload :Connection, 'workos/connection'
   autoload :DeprecatedHashWrapper, 'workos/deprecated_hash_wrapper'
+  autoload :Deprecation, 'workos/deprecation'
   autoload :Directory, 'workos/directory'
   autoload :DirectoryGroup, 'workos/directory_group'
   autoload :DirectorySync, 'workos/directory_sync'

lib/workos/deprecation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module WorkOS
+  # Provides helpers for working with deprecated SDK and API features.
+  module Deprecation
+    def warn_deprecation(message)
+      full_message = "[DEPRECATION] #{message}"
+
+      if RUBY_VERSION > '3'
+        warn full_message, category: :deprecated
+      else
+        warn full_message
+      end
+    end
+  end
+end

lib/workos/mfa.rb

@@ -8,7 +8,8 @@ module WorkOS
   # MFA platform. You'll need a valid API key
   module MFA
     class << self
-      include Client
+      include Client, Deprecation
+
       def delete_factor(id:)
         response = execute_request(
           request: delete_request(
@@ -101,7 +102,7 @@ def verify_factor(
         authentication_challenge_id: nil,
         code: nil
       )
-        warn '[DEPRECATION] `verify_factor` is deprecated. Please use `verify_challenge` instead.'
+        warn_deprecation '`verify_factor` is deprecated. Please use `verify_challenge` instead.'
 
         verify_challenge(
           authentication_challenge_id: authentication_challenge_id,

lib/workos/organizations.rb

@@ -7,6 +7,7 @@ module WorkOS
   module Organizations
     class << self
       include Client
+      include Deprecation
 
       # Retrieve a list of organizations that have connections configured
       # within your WorkOS dashboard.
@@ -70,16 +71,28 @@ def get_organization(id:)
 
       # Create an organization
       #
-      # @param [Array<String>] domains List of domains that belong to the
-      #  organization
+      # @param [Array<Hash>] domain_data List of domain hashes describing an orgnaization domain.
+      # @option domain_data [String] domain The domain that belongs to the organization.
+      # @option domain_data [String] state The state of the domain. "verified" or "pending"
+      # @param [Array<String>] domains List of domains that belong to the organization.
+      #   Deprecated: Use domain_data instead.
       # @param [String] name A unique, descriptive name for the organization
       # @param [Boolean, nil] allow_profiles_outside_organization Whether Connections
       #  within the Organization allow profiles that are outside of the Organization's configured User Email Domains.
       # @param [String] idempotency_key An idempotency key
-      def create_organization(domains:, name:, allow_profiles_outside_organization: nil, idempotency_key: nil)
+      def create_organization(
+        domain_data: nil,
+        domains: nil,
+        name:,
+        allow_profiles_outside_organization: nil,
+        idempotency_key: nil
+      )
+        warn_deprecation '`domains` is deprecated. Use `domain_data` instead.' if domains
+
         request = post_request(
           auth: true,
           body: {
+            domain_data: domain_data,
             domains: domains,
             name: name,
             allow_profiles_outside_organization: allow_profiles_outside_organization,
@@ -97,12 +110,17 @@ def create_organization(domains:, name:, allow_profiles_outside_organization: ni
       # Update an organization
       #
       # @param [String] organization Organization unique identifier
-      # @param [Array<String>] domains List of domains that belong to the
-      #  organization
+      # @param [Array<Hash>] domain_data List of domain hashes describing an orgnaization domain.
+      # @option domain_data [String] domain The domain that belongs to the organization.
+      # @option domain_data [String] state The state of the domain. "verified" or "pending"
+      # @param [Array<String>] domains List of domains that belong to the organization.
+      #   Deprecated: Use domain_data instead.
       # @param [String] name A unique, descriptive name for the organization
       # @param [Boolean, nil] allow_profiles_outside_organization Whether Connections
       #  within the Organization allow profiles that are outside of the Organization's configured User Email Domains.
       def update_organization(organization:, domains:, name:, allow_profiles_outside_organization: nil)
+        warn_deprecation '`domains` is deprecated. Use `domain_data` instead.' if domains
+
         request = put_request(
           auth: true,
           body: {

lib/workos/sso.rb

@@ -11,7 +11,7 @@ module WorkOS
   # @see https://docs.workos.com/sso/overview
   module SSO
     class << self
-      include Client
+      include Client, Deprecation
 
       PROVIDERS = WorkOS::Types::Provider::ALL
 
@@ -65,7 +65,7 @@ def authorization_url(
         state: ''
       )
         if domain
-          warn '[DEPRECATION] `domain` is deprecated.
+          warn_deprecation '[DEPRECATION] `domain` is deprecated.
           Please use `organization` instead.'
         end
 

spec/lib/workos/mfa_spec.rb

@@ -130,14 +130,19 @@
 
   describe '.verify_factor' do
     it 'throws a warning' do
-      expect do
-        VCR.use_cassette 'mfa/verify_challenge_generic_valid' do
-          described_class.verify_factor(
-            authentication_challenge_id: 'auth_challenge_01FZ4YVRBMXP5ZM0A7BP4AJ12J',
-            code: '897792',
-          )
-        end
-      end.to output("[DEPRECATION] `verify_factor` is deprecated. Please use `verify_challenge` instead.\n").to_stderr
+      VCR.use_cassette 'mfa/verify_challenge_generic_valid' do
+        allow(Warning).to receive(:warn)
+
+        described_class.verify_factor(
+          authentication_challenge_id: 'auth_challenge_01FZ4YVRBMXP5ZM0A7BP4AJ12J',
+          code: '897792',
+        )
+
+        expect(Warning).to have_received(:warn).with(
+          "[DEPRECATION] `verify_factor` is deprecated. Please use `verify_challenge` instead.\n",
+          any_args,
+        )
+      end
     end
 
     it 'calls verify_challenge' do

spec/lib/workos/organizations_spec.rb

@@ -18,6 +18,59 @@
             expect(organization.domains.first[:domain]).to eq('example.io')
           end
         end
+
+        context 'without domains' do
+          it 'creates an organization' do
+            VCR.use_cassette 'organization/create_without_domains' do
+              organization = described_class.create_organization(
+                name: 'Test Organization',
+              )
+
+              expect(organization.id).to start_with('org_')
+              expect(organization.name).to eq('Test Organization')
+              expect(organization.domains).to be_empty
+            end
+          end
+        end
+
+        context 'with domains' do
+          it 'creates an organization and warns' do
+            VCR.use_cassette 'organization/create_with_domains' do
+              allow(Warning).to receive(:warn)
+
+              organization = described_class.create_organization(
+                domains: ['example.io'],
+                name: 'Test Organization',
+              )
+
+              expect(organization.id).to start_with('org_')
+              expect(organization.name).to eq('Test Organization')
+              expect(organization.domains.first[:domain]).to eq('example.io')
+
+              expect(Warning).to have_received(:warn).with(
+                "[DEPRECATION] `domains` is deprecated. Use `domain_data` instead.\n",
+                any_args,
+              )
+            end
+          end
+        end
+
+        context 'with domain_data' do
+          it 'creates an organization' do
+            VCR.use_cassette 'organization/create_with_domain_data' do
+              organization = described_class.create_organization(
+                domain_data: [{ domain: 'example.io', state: 'verified' }],
+                name: 'Test Organization',
+              )
+
+              expect(organization.id).to start_with('org_')
+              expect(organization.name).to eq('Test Organization')
+              expect(organization.domains.first).to include(
+                domain: 'example.io', state: 'verified',
+              )
+            end
+          end
+        end
       end
 
       context 'with idempotency key' do