vortex-ruby-sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18819ec338fa097c24046e0a535a98483acbe55e0163fe6e6db86d0160334a1b
-  data.tar.gz: 1cdbc41d41372b4658ef5a38db7ee6cbda22f5c63227738bd8ac79140215af43
+  metadata.gz: e7f6c2f423b5aa8099f7ccce759daaf6dcdd114c6052f1ffb9d9f5072d505916
+  data.tar.gz: 46755e0df9a92907219042a2f2373f6f067aa46f57a1409159cc215ae14823f3
 SHA512:
-  metadata.gz: 950cf7e0435224d9e7aa534d94b3999ed72f823b2211eb368a332de4fe683f8c0998bbde59a445571b5b7fb81cc5de60036944c7944a124f4933ea0aae41a698
-  data.tar.gz: 561c091c7232a282cbe854dacdc3d2e3eaac70fb28a7b6c08dee852d4b7466d56f2fe4c07e7834cfe1e23c2802786c5019d6cf514f720ac3341fa5827085fa92
+  metadata.gz: 55c8a0671bcad40614d75363ef1b0aaf7b2323f47e9dd717940f59fd026b449c64d79b6c7b9bbed6493199c4c3d1beaac97c3e728409407339bb41363c93b1f9
+  data.tar.gz: fcce54f801ef8115f7567cded83704409fb8436f34056aa296c77210099e0519dd59d8b51f29ff8eb05669acefb088e5cdf4a8a7f2603033f84de1767192b025

data/README.md

@@ -5,6 +5,8 @@ A Ruby SDK for the Vortex invitation system, providing seamless integration with
 ## Features
 
 - **JWT Generation**: Identical algorithm to other SDKs for complete compatibility
+- **Simplified JWT Format**: New streamlined payload with `userEmail` and `adminScopes`
+- **Backward Compatible**: Legacy JWT format still supported
 - **Complete API Coverage**: All invitation management operations
 - **Framework Integration**: Built-in Rails and Sinatra helpers
 - **Same Route Structure**: Ensures React provider compatibility
@@ -39,13 +41,15 @@ require 'vortex'
 # Initialize the client
 client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
 
-# Generate JWT for a user
-jwt = client.generate_jwt(
-  user_id: 'user123',
-  identifiers: [{ type: 'email', value: 'user@example.com' }],
-  groups: [{ id: 'team1', type: 'team', name: 'Engineering' }],
-  role: 'admin'
-)
+# Create a user object
+user = {
+  id: 'user-123',
+  email: 'user@example.com',
+  admin_scopes: ['autojoin']  # Optional - included as adminScopes array in JWT
+}
+
+# Generate JWT
+jwt = client.generate_jwt(user: user)
 
 # Get invitations by target
 invitations = client.get_invitations_by_target('email', 'user@example.com')
@@ -57,6 +61,22 @@ client.accept_invitations(['inv1', 'inv2'], { type: 'email', value: 'user@exampl
 group_invitations = client.get_invitations_by_group('team', 'team1')
 ```
 
+### Generate JWT with Additional Properties
+
+```ruby
+user = {
+  id: 'user-123',
+  email: 'user@example.com'
+}
+
+extra = {
+  role: 'admin',
+  department: 'Engineering'
+}
+
+jwt = client.generate_jwt(user: user, extra: extra)
+```
+
 ## Rails Integration
 
 Create a controller with Vortex routes:
@@ -70,13 +90,13 @@ class VortexController < ApplicationController
 
   def authenticate_vortex_user
     # Return user data hash or nil
+    admin_scopes = []
+    admin_scopes << 'autojoin' if current_user.admin?
+
     {
-      user_id: current_user.id,
-      identifiers: [{ type: 'email', value: current_user.email }],
-      groups: current_user.teams.map { |team|
-        { id: team.id, type: 'team', name: team.name }
-      },
-      role: current_user.role
+      id: current_user.id,
+      email: current_user.email,
+      admin_scopes: admin_scopes
     }
   end
 
@@ -86,7 +106,7 @@ class VortexController < ApplicationController
     when 'JWT', 'GET_INVITATIONS'
       true
     when 'REVOKE_INVITATION'
-      user[:role] == 'admin'
+      user[:admin_scopes]&.include?('autojoin')
     else
       false
     end
@@ -134,10 +154,9 @@ class MyApp < Sinatra::Base
     return nil unless user_id
 
     {
-      user_id: user_id,
-      identifiers: [{ type: 'email', value: 'user@example.com' }],
-      groups: [{ id: 'team1', type: 'team', name: 'Engineering' }],
-      role: 'user'
+      id: user_id,
+      email: 'user@example.com',
+      admin_scopes: []  # Optional
     }
   end
 
@@ -153,9 +172,13 @@ end
 All methods match the functionality of other Vortex SDKs:
 
 ### JWT Generation
-- `generate_jwt(user_id:, identifiers:, groups:, role: nil)` - Generate JWT token
+
+- `generate_jwt(user:, extra: nil)` - Generate JWT token
+  - `user`: Hash with `:id`, `:email`, and optional `:admin_scopes` array
+  - `extra`: Optional hash with additional properties to include in JWT payload
 
 ### Invitation Management
+
 - `get_invitations_by_target(target_type, target_value)` - Get invitations by target
 - `get_invitation(invitation_id)` - Get specific invitation
 - `revoke_invitation(invitation_id)` - Revoke invitation
@@ -177,13 +200,33 @@ The SDK provides these routes (same as other SDKs for React provider compatibili
 - `DELETE /api/vortex/invitations/by-group/:type/:id`
 - `POST /api/vortex/invitations/:id/reinvite`
 
+## JWT Payload Structure
+
+The SDK generates JWTs with the following payload structure:
+
+```ruby
+{
+  userId: 'user-123',
+  userEmail: 'user@example.com',
+  adminScopes: ['autojoin'],  # Full array included if admin_scopes provided
+  expires: 1234567890
+}
+```
+
+Additional properties from the `extra` parameter are merged into the payload.
+
 ## Error Handling
 
 All methods raise `Vortex::VortexError` on failures:
 
 ```ruby
 begin
-  jwt = client.generate_jwt(user_data)
+  jwt = client.generate_jwt(
+    user: {
+      id: 'user-123',
+      email: 'user@example.com'
+    }
+  )
 rescue Vortex::VortexError => e
   logger.error "Vortex error: #{e.message}"
 end
@@ -201,4 +244,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/vortex
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/examples/basic_usage.rb

@@ -13,29 +13,35 @@ require 'vortex'
 API_KEY = ENV['VORTEX_API_KEY'] || 'your-api-key-here'
 client = Vortex::Client.new(API_KEY)
 
-# Example user data - same structure as other SDKs
-user_data = {
-  user_id: 'user123',
-  identifiers: [
-    { type: 'email', value: 'user@example.com' }
-  ],
-  groups: [
-    { id: 'team1', type: 'team', name: 'Engineering Team' },
-    { id: 'dept1', type: 'department', name: 'Product Development' }
-  ],
-  role: 'admin'
+# Example user data
+user = {
+  id: 'user123',
+  email: 'user@example.com',
+  admin_scopes: ['autojoin']  # Optional - included as adminScopes array in JWT
+}
+
+# Additional properties (optional)
+extra = {
+  role: 'admin',
+  department: 'Engineering'
 }
 
 begin
   puts "=== Vortex Ruby SDK Example ==="
   puts
 
-  # 1. Generate JWT
+  # 1. Generate JWT for user
   puts "1. Generating JWT for user..."
-  jwt = client.generate_jwt(**user_data)
+  jwt = client.generate_jwt(user: user)
   puts "JWT generated: #{jwt[0..50]}..."
   puts
 
+  # 1b. Generate JWT with additional properties
+  puts "1b. Generating JWT with additional properties..."
+  jwt_with_extra = client.generate_jwt(user: user, extra: extra)
+  puts "JWT with extra generated: #{jwt_with_extra[0..50]}..."
+  puts
+
   # 2. Get invitations by target
   puts "2. Getting invitations by email target..."
   invitations = client.get_invitations_by_target('email', 'user@example.com')

data/examples/rails_app.rb

@@ -32,16 +32,15 @@ class VortexController < ActionController::Base
     user_id = session[:user_id] || request.headers['X-User-ID']
     return nil unless user_id
 
-    # Return user data in the format expected by Vortex
+    # Build admin_scopes array
+    admin_scopes = []
+    admin_scopes << 'autojoin' if session[:user_role] == 'admin'
+
+    # Return user data
     {
-      user_id: user_id,
-      identifiers: [
-        { type: 'email', value: session[:user_email] || 'user@example.com' }
-      ],
-      groups: [
-        { id: 'team1', type: 'team', name: 'Engineering' }
-      ],
-      role: session[:user_role] || 'user'
+      id: user_id,
+      email: session[:user_email] || 'user@example.com',
+      admin_scopes: admin_scopes
     }
   end
 
@@ -56,9 +55,9 @@ class VortexController < ActionController::Base
     when 'ACCEPT_INVITATIONS'
       true # Everyone can accept invitations
     when 'REVOKE_INVITATION', 'DELETE_GROUP_INVITATIONS'
-      user[:role] == 'admin' # Only admins can delete
+      user[:admin_scopes]&.include?('autojoin') # Only admins can delete
     when 'GET_GROUP_INVITATIONS', 'REINVITE'
-      user[:role] == 'admin' # Only admins can manage groups
+      user[:admin_scopes]&.include?('autojoin') # Only admins can manage groups
     else
       false
     end

data/examples/sinatra_app.rb

@@ -25,16 +25,15 @@ class VortexSinatraApp < Sinatra::Base
     user_id = request.env['HTTP_X_USER_ID'] || 'demo-user'
     return nil unless user_id
 
-    # Return user data in the format expected by Vortex
+    # Build admin_scopes array
+    admin_scopes = []
+    admin_scopes << 'autojoin' if request.env['HTTP_X_USER_ROLE'] == 'admin'
+
+    # Return user data
     {
-      user_id: user_id,
-      identifiers: [
-        { type: 'email', value: request.env['HTTP_X_USER_EMAIL'] || 'demo@example.com' }
-      ],
-      groups: [
-        { id: 'team1', type: 'team', name: 'Engineering' }
-      ],
-      role: request.env['HTTP_X_USER_ROLE'] || 'user'
+      id: user_id,
+      email: request.env['HTTP_X_USER_EMAIL'] || 'demo@example.com',
+      admin_scopes: admin_scopes
     }
   end
 
@@ -48,9 +47,9 @@ class VortexSinatraApp < Sinatra::Base
     when 'ACCEPT_INVITATIONS'
       true # Everyone can accept invitations
     when 'REVOKE_INVITATION', 'DELETE_GROUP_INVITATIONS'
-      user[:role] == 'admin' # Only admins can delete
+      user[:admin_scopes]&.include?('autojoin') # Only admins can delete
     when 'GET_GROUP_INVITATIONS', 'REINVITE'
-      user[:role] == 'admin' # Only admins can manage groups
+      user[:admin_scopes]&.include?('autojoin') # Only admins can manage groups
     else
       false
     end

data/lib/vortex/client.rb

@@ -23,18 +23,31 @@ module Vortex
       @connection = build_connection
     end
 
-    # Generate a JWT for the given user data
+    # Generate a JWT token for a user
     #
-    # This uses the exact same algorithm as the Node.js SDK to ensure
-    # complete compatibility across all platforms.
-    #
-    # @param user_id [String] Unique identifier for the user
-    # @param identifiers [Array<Hash>] Array of identifier hashes with :type and :value
-    # @param groups [Array<Hash>] Array of group hashes with :id, :type, and :name
-    # @param role [String, nil] Optional user role
+    # @param params [Hash] JWT parameters with :user (required) and optional :attributes
     # @return [String] JWT token
     # @raise [VortexError] If API key is invalid or JWT generation fails
-    def generate_jwt(user_id:, identifiers:, groups:, role: nil)
+    #
+    # @example Simple usage
+    #   client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
+    #   jwt = client.generate_jwt({
+    #     user: {
+    #       id: 'user-123',
+    #       email: 'user@example.com',
+    #       admin_scopes: ['autojoin']
+    #     }
+    #   })
+    #
+    # @example With additional attributes
+    #   jwt = client.generate_jwt({
+    #     user: { id: 'user-123', email: 'user@example.com' },
+    #     attributes: { role: 'admin', department: 'Engineering' }
+    #   })
+    def generate_jwt(params)
+      user = params[:user]
+      attributes = params[:attributes]
+
       # Parse API key - same format as Node.js SDK
       prefix, encoded_id, key = @api_key.split('.')
 
@@ -52,7 +65,7 @@ module Vortex
       # Step 1: Derive signing key from API key + ID (same as Node.js)
       signing_key = OpenSSL::HMAC.digest('sha256', key, id)
 
-      # Step 2: Build header + payload (same structure as Node.js)
+      # Step 2: Build header + payload
       header = {
         iat: Time.now.to_i,
         alg: 'HS256',
@@ -60,14 +73,23 @@ module Vortex
         kid: id
       }
 
+      # Build payload - start with required fields
       payload = {
-        userId: user_id,
-        groups: groups,
-        role: role,
-        expires: expires,
-        identifiers: identifiers
+        userId: user[:id],
+        userEmail: user[:email],
+        expires: expires
       }
 
+      # Add adminScopes if present
+      if user[:admin_scopes]
+        payload[:adminScopes] = user[:admin_scopes]
+      end
+
+      # Add any additional properties from attributes
+      if attributes && !attributes.empty?
+        payload.merge!(attributes)
+      end
+
       # Step 3: Base64URL encode (same as Node.js)
       header_b64 = base64url_encode(JSON.generate(header))
       payload_b64 = base64url_encode(JSON.generate(payload))
@@ -81,6 +103,8 @@ module Vortex
       raise VortexError, "JWT generation failed: #{e.message}"
     end
 
+    public
+
     # Get invitations by target
     #
     # @param target_type [String] Type of target (email, sms)

data/lib/vortex/rails.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'logger'
 require 'vortex/client'
 require 'vortex/error'
 
@@ -28,6 +29,17 @@ module Vortex
     #       @vortex_client ||= Vortex::Client.new(ENV['VORTEX_API_KEY'])
     #     end
     #   end
+    #
+    # Configure logging:
+    #   Vortex::Rails.logger = MyLogger.new
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= defined?(::Rails) ? ::Rails.logger : Logger.new(nil)
+      end
+    end
+
     module Controller
       extend ActiveSupport::Concern
 
@@ -39,28 +51,54 @@ module Vortex
       # Generate JWT for authenticated user
       # POST /api/vortex/jwt
       def generate_jwt
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#generate_jwt invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
         unless authorize_vortex_operation('JWT', user)
+          Vortex::Rails.logger.warn("Vortex JWT authorization failed for user #{user[:user_id]}")
           return render_forbidden('Not authorized to generate JWT')
         end
 
-        jwt = vortex_client.generate_jwt(
-          user_id: user[:user_id],
-          identifiers: user[:identifiers],
-          groups: user[:groups],
-          role: user[:role]
-        )
+        # Extract email from identifiers for the user hash
+        email = user[:identifiers]&.find { |i| i[:type] == 'email' }&.dig(:value)
+
+        # Build the JWT
+        jwt_params = {
+          user: {
+            id: user[:user_id],
+            email: email
+          }
+        }
 
+        # Add adminScopes if present
+        if user[:admin_scopes]&.any?
+          jwt_params[:user][:admin_scopes] = user[:admin_scopes]
+        end
+
+        # Add attributes if present
+        if user[:attributes]
+          jwt_params[:attributes] = user[:attributes]
+        end
+
+        jwt = vortex_client.generate_jwt(jwt_params)
+
+        Vortex::Rails.logger.debug("Vortex JWT generated successfully for user #{user[:user_id]}")
         render json: { jwt: jwt }
       rescue Vortex::VortexError => e
+        Vortex::Rails.logger.error("Vortex error generating JWT: #{e.message}")
         render_server_error("Failed to generate JWT: #{e.message}")
+      rescue StandardError => e
+        Vortex::Rails.logger.error("Unexpected error generating JWT: #{e.class} - #{e.message}")
+        render_server_error("Unexpected error: #{e.message}")
       end
 
       # Get invitations by target
       # GET /api/vortex/invitations?targetType=email&targetValue=user@example.com
       def get_invitations_by_target
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#get_invitations_by_target invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -82,6 +120,8 @@ module Vortex
       # Get specific invitation by ID
       # GET /api/vortex/invitations/:invitation_id
       def get_invitation
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#get_invitation invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -99,6 +139,8 @@ module Vortex
       # Revoke (delete) invitation
       # DELETE /api/vortex/invitations/:invitation_id
       def revoke_invitation
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#revoke_invitation invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -116,6 +158,8 @@ module Vortex
       # Accept invitations
       # POST /api/vortex/invitations/accept
       def accept_invitations
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#accept_invitations invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -139,6 +183,8 @@ module Vortex
       # Get invitations by group
       # GET /api/vortex/invitations/by-group/:group_type/:group_id
       def get_invitations_by_group
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#get_invitations_by_group invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -158,6 +204,8 @@ module Vortex
       # Delete invitations by group
       # DELETE /api/vortex/invitations/by-group/:group_type/:group_id
       def delete_invitations_by_group
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#delete_invitations_by_group invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -177,6 +225,8 @@ module Vortex
       # Reinvite user
       # POST /api/vortex/invitations/:invitation_id/reinvite
       def reinvite
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#reinvite invoked")
+
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
 
@@ -228,7 +278,6 @@ module Vortex
       end
 
       def handle_vortex_error(error)
-        Rails.logger.error("Vortex error: #{error.message}")
         render_server_error(error.message)
       end
     end

data/lib/vortex/types.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vortex
+  # Type documentation for Vortex SDK responses
+  # Ruby uses dynamic typing with Hashes, but this documents the expected structure
+  module Types
+    # Group structure for JWT generation (input)
+    # @example
+    #   {
+    #     type: 'workspace',
+    #     id: 'workspace-123',       # Legacy field (deprecated, use groupId)
+    #     groupId: 'workspace-123',  # Preferred field
+    #     name: 'My Workspace'
+    #   }
+    GROUP_INPUT = {
+      type: String,      # Required: Group type (e.g., "workspace", "team")
+      id: String,        # Optional: Legacy field (deprecated, use groupId)
+      groupId: String,   # Optional: Preferred - Customer's group ID
+      name: String       # Required: Group name
+    }.freeze
+
+    # InvitationGroup structure from API responses
+    # This matches the MemberGroups table structure from the API
+    # @example
+    #   {
+    #     id: '550e8400-e29b-41d4-a716-446655440000',
+    #     accountId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+    #     groupId: 'workspace-123',
+    #     type: 'workspace',
+    #     name: 'My Workspace',
+    #     createdAt: '2025-01-27T12:00:00.000Z'
+    #   }
+    INVITATION_GROUP = {
+      id: String,          # Vortex internal UUID
+      accountId: String,   # Vortex account ID
+      groupId: String,     # Customer's group ID (the ID they provided to Vortex)
+      type: String,        # Group type (e.g., "workspace", "team")
+      name: String,        # Group name
+      createdAt: String    # ISO 8601 timestamp when the group was created
+    }.freeze
+
+    # Invitation structure from API responses
+    # @example
+    #   {
+    #     id: '550e8400-e29b-41d4-a716-446655440000',
+    #     accountId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+    #     groups: [INVITATION_GROUP, ...],
+    #     # ... other fields
+    #   }
+    INVITATION = {
+      id: String,
+      accountId: String,
+      clickThroughs: Integer,
+      configurationAttributes: Hash,
+      attributes: Hash,
+      createdAt: String,
+      deactivated: :boolean,
+      deliveryCount: Integer,
+      deliveryTypes: Array, # of String
+      foreignCreatorId: String,
+      invitationType: String,
+      modifiedAt: String,
+      status: String,
+      target: Array, # of { type: String, value: String }
+      views: Integer,
+      widgetConfigurationId: String,
+      projectId: String,
+      groups: Array, # of INVITATION_GROUP structures
+      accepts: Array, # of acceptance structures
+      expired: :boolean,
+      expires: String # ISO 8601 timestamp (optional)
+    }.freeze
+  end
+end

data/lib/vortex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vortex
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vortex-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Vortex Software
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-17 00:00:00.000000000 Z
+date: 2025-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -156,6 +156,7 @@ files:
 - lib/vortex/error.rb
 - lib/vortex/rails.rb
 - lib/vortex/sinatra.rb
+- lib/vortex/types.rb
 - lib/vortex/version.rb
 - vortex-ruby-sdk.gemspec
 homepage: https://github.com/vortexsoftware/vortex-ruby-sdk
@@ -166,7 +167,7 @@ metadata:
   homepage_uri: https://github.com/vortexsoftware/vortex-ruby-sdk
   source_code_uri: https://github.com/vortexsoftware/vortex-ruby-sdk
   changelog_uri: https://github.com/vortexsoftware/vortex-ruby-sdk/blob/main/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -181,8 +182,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.5
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Ruby SDK for Vortex invitation system
 test_files: []