vortex-ruby-sdk 1.9.0 → 1.18.0

data/examples/basic_usage.rb

@@ -50,7 +50,7 @@ begin
 
   # 3. Get invitations by group
   puts "3. Getting invitations for team group..."
-  group_invitations = client.get_invitations_by_group('team', 'team1')
+  group_invitations = client.get_invitations_by_scope('team', 'team1')
   puts "Found #{group_invitations.length} group invitation(s)"
   puts
 

data/examples/rails_app.rb

@@ -79,8 +79,8 @@ Rails.application.routes.draw do
     get 'invitations/:invitation_id', action: 'get_invitation'
     delete 'invitations/:invitation_id', action: 'revoke_invitation'
     post 'invitations/accept', action: 'accept_invitations'
-    get 'invitations/by-group/:group_type/:group_id', action: 'get_invitations_by_group'
-    delete 'invitations/by-group/:group_type/:group_id', action: 'delete_invitations_by_group'
+    get 'invitations/by-scope/:scope_type/:scope', action: 'get_invitations_by_scope'
+    delete 'invitations/by-scope/:scope_type/:scope', action: 'delete_invitations_by_scope'
     post 'invitations/:invitation_id/reinvite', action: 'reinvite'
   end
 
@@ -99,8 +99,8 @@ Rails.application.routes.draw do
           invitation: 'GET /api/vortex/invitations/:id',
           revoke: 'DELETE /api/vortex/invitations/:id',
           accept: 'POST /api/vortex/invitations/accept',
-          group_invitations: 'GET /api/vortex/invitations/by-group/:type/:id',
-          delete_group: 'DELETE /api/vortex/invitations/by-group/:type/:id',
+          group_invitations: 'GET /api/vortex/invitations/by-scope/:type/:id',
+          delete_group: 'DELETE /api/vortex/invitations/by-scope/:type/:id',
           reinvite: 'POST /api/vortex/invitations/:id/reinvite'
         }
       }.to_json
@@ -119,8 +119,8 @@ if __FILE__ == $0
   puts "  GET  /api/vortex/invitations/:id"
   puts "  DELETE /api/vortex/invitations/:id"
   puts "  POST /api/vortex/invitations/accept"
-  puts "  GET  /api/vortex/invitations/by-group/:type/:id"
-  puts "  DELETE /api/vortex/invitations/by-group/:type/:id"
+  puts "  GET  /api/vortex/invitations/by-scope/:type/:id"
+  puts "  DELETE /api/vortex/invitations/by-scope/:type/:id"
   puts "  POST /api/vortex/invitations/:id/reinvite"
 
   Rails.application.initialize!

data/examples/sinatra_app.rb

@@ -73,8 +73,8 @@ class VortexSinatraApp < Sinatra::Base
         invitation: 'GET /api/vortex/invitations/:id',
         revoke: 'DELETE /api/vortex/invitations/:id',
         accept: 'POST /api/vortex/invitations/accept',
-        group_invitations: 'GET /api/vortex/invitations/by-group/:type/:id',
-        delete_group: 'DELETE /api/vortex/invitations/by-group/:type/:id',
+        group_invitations: 'GET /api/vortex/invitations/by-scope/:type/:id',
+        delete_group: 'DELETE /api/vortex/invitations/by-scope/:type/:id',
         reinvite: 'POST /api/vortex/invitations/:id/reinvite'
       }
     }.to_json
@@ -105,8 +105,8 @@ if __FILE__ == $0
   puts "  GET  /api/vortex/invitations/:id"
   puts "  DELETE /api/vortex/invitations/:id"
   puts "  POST /api/vortex/invitations/accept"
-  puts "  GET  /api/vortex/invitations/by-group/:type/:id"
-  puts "  DELETE /api/vortex/invitations/by-group/:type/:id"
+  puts "  GET  /api/vortex/invitations/by-scope/:type/:id"
+  puts "  DELETE /api/vortex/invitations/by-scope/:type/:id"
   puts "  POST /api/vortex/invitations/:id/reinvite"
   puts
   puts "Authentication headers (for testing):"

data/lib/vortex/client.rb

@@ -44,7 +44,85 @@ module Vortex
     #     user: { id: 'user-123', email: 'user@example.com' },
     #     attributes: { role: 'admin', department: 'Engineering' }
     #   })
-    def generate_jwt(params)
+    # Sign a user object for use with the widget signature prop.
+    #
+    # @param user [Hash] User data with :id, :email, etc.
+    # @return [String] Signature in "kid:hexDigest" format
+    #
+    # @example
+    #   client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
+    #   signature = client.sign({ id: 'user-123', email: 'user@example.com' })
+    #   # Pass signature to frontend alongside user prop
+    def sign(user)
+      user_id = user[:id] || user['id']
+      raise VortexError, 'User must have an :id field' if user_id.nil? || user_id.to_s.empty?
+
+      kid, signing_key = parse_and_derive_key
+
+      # Build canonical payload — include ALL user fields with key normalization
+      key_map = { id: 'userId', email: 'userEmail',
+                  admin_scopes: 'adminScopes', allowed_email_domains: 'allowedEmailDomains' }
+      canonical = {}
+      user.each do |k, v|
+        str_key = k.to_s
+        mapped = key_map[k] || key_map[k.to_s.to_sym]
+        if mapped
+          canonical[mapped] = v
+        elsif str_key == 'id'
+          canonical['userId'] = v
+        elsif str_key == 'email'
+          canonical['userEmail'] = v
+        elsif !%w[name user_name avatar_url user_avatar_url].include?(str_key)
+          # Skip name/avatar fields here - handle them explicitly below
+          canonical[str_key] = v
+        end
+      end
+      canonical['userId'] = user_id  # ensure normalized
+
+      # Prefer new property names (name/avatar_url), fall back to deprecated (user_name/user_avatar_url)
+      user_name = user[:name] || user[:user_name]
+      canonical['name'] = user_name if user_name
+
+      user_avatar_url = user[:avatar_url] || user[:user_avatar_url]
+      canonical['avatarUrl'] = user_avatar_url if user_avatar_url
+
+      # Recursive canonical JSON (sorted keys at every level)
+      canonical_json = JSON.generate(canonicalize_value(canonical))
+
+      digest = OpenSSL::HMAC.hexdigest('SHA256', signing_key, canonical_json)
+      "#{kid}:#{digest}"
+    end
+
+    private
+
+    def canonicalize_value(value)
+      case value
+      when Hash
+        value.sort_by { |k, _| k.to_s }.map { |k, v| [k.to_s, canonicalize_value(v)] }.to_h
+      when Array
+        value.map { |item| canonicalize_value(item) }
+      else
+        value
+      end
+    end
+
+    def parse_and_derive_key
+      parts = @api_key.split('.')
+      raise VortexError, 'Invalid API key format' unless parts.length == 3
+      prefix, encoded_id, key = parts
+      raise VortexError, 'Invalid API key format' unless prefix && encoded_id && key
+      raise VortexError, 'Invalid API key prefix' unless prefix == 'VRTX'
+
+      uuid_bytes = Base64.urlsafe_decode64(encoded_id)
+      raise VortexError, "Invalid API key: decoded UUID must be 16 bytes, got #{uuid_bytes.length}" unless uuid_bytes.length == 16
+      kid = format_uuid(uuid_bytes)
+      signing_key = OpenSSL::HMAC.digest('SHA256', key, kid)
+      [kid, signing_key]
+    end
+
+    public
+
+    def generate_jwt(params, options = {})
       user = params[:user]
       attributes = params[:attributes]
 
@@ -60,7 +138,9 @@ module Vortex
       # Convert to UUID string format (same as uuidStringify in Node.js)
       id = format_uuid(decoded_bytes)
 
-      expires = Time.now.to_i + 3600
+      raw_expires = options[:expires_in] || options[:expiresIn]
+      expires_in_seconds = raw_expires ? parse_expires_in(raw_expires) : 2592000 # 30 days
+      expires = Time.now.to_i + expires_in_seconds
 
       # Step 1: Derive signing key from API key + ID (same as Node.js)
       signing_key = OpenSSL::HMAC.digest('sha256', key, id)
@@ -80,14 +160,16 @@ module Vortex
         expires: expires
       }
 
-      # Add name if present (convert snake_case to camelCase for JWT)
-      if user[:user_name]
-        payload[:userName] = user[:user_name]
+      # Add name if present (prefer new property, fall back to deprecated)
+      user_name = user[:name] || user[:user_name]
+      if user_name
+        payload[:name] = user_name
       end
 
-      # Add userAvatarUrl if present (convert snake_case to camelCase for JWT)
-      if user[:user_avatar_url]
-        payload[:userAvatarUrl] = user[:user_avatar_url]
+      # Add avatarUrl if present (prefer new property, fall back to deprecated)
+      user_avatar_url = user[:avatar_url] || user[:user_avatar_url]
+      if user_avatar_url
+        payload[:avatarUrl] = user_avatar_url
       end
 
       # Add adminScopes if present
@@ -118,6 +200,153 @@ module Vortex
       raise VortexError, "JWT generation failed: #{e.message}"
     end
 
+    # Generate a signed token for use with Vortex widgets.
+    #
+    # This method generates a signed JWT token containing your payload data.
+    # The token can be passed to widgets via the `token` prop to authenticate
+    # and authorize the request.
+    #
+    # @param payload [Hash] Data to sign (user, component, scope, vars, etc.)
+    #   At minimum, include user[:id] for secure invitation attribution.
+    # @param options [Hash] Optional configuration
+    # @option options [String, Integer] :expires_in Expiration time (default: 30 days)
+    #   Can be a duration string ("5m", "1h", "24h", "7d") or seconds as integer.
+    # @return [String] Signed JWT token
+    # @raise [VortexError] If API key format is invalid or token generation fails
+    #
+    # @example Sign just the user (minimum for secure attribution)
+    #   token = client.generate_token({ user: { id: 'user-123' } })
+    #
+    # @example Sign full payload
+    #   token = client.generate_token({
+    #     component: 'widget-abc',
+    #     user: { id: 'user-123', name: 'Peter', email: 'peter@example.com' },
+    #     scope: 'workspace_456',
+    #     vars: { company_name: 'Acme' }
+    #   })
+    #
+    # @example Custom expiration (default is 30 days)
+    #   token = client.generate_token(payload, { expires_in: '1h' })
+    #   token = client.generate_token(payload, { expires_in: 3600 }) # seconds
+    def generate_token(payload, options = nil)
+      # Validate inputs
+      raise VortexError, "payload must be a Hash" unless payload.is_a?(Hash)
+      raise VortexError, "options must be a Hash or nil" if options && !options.is_a?(Hash)
+
+      # Normalize payload keys to symbols
+      payload = symbolize_keys(payload)
+
+      # Warn if user.id is missing
+      user = payload[:user]
+      if user.nil? || user[:id].nil? || user[:id].to_s.empty?
+        warn "[Vortex SDK] Warning: signing payload without user.id means invitations won't be securely attributed to a user."
+      end
+
+      # Parse expiration
+      expires_in_seconds = 30 * 24 * 60 * 60 # Default: 30 days
+      if options
+        options = symbolize_keys(options)
+        raw_expires = options[:expires_in] || options[:expiresIn]
+        expires_in_seconds = parse_expires_in(raw_expires) if raw_expires
+      end
+
+      # Parse API key and derive signing key
+      kid, signing_key = parse_and_derive_key
+
+      # Build JWT
+      now = Time.now.to_i
+      exp = now + expires_in_seconds
+
+      header = { alg: 'HS256', typ: 'JWT', kid: kid }
+
+      # Build JWT payload
+      jwt_payload = {}
+
+      # Add user if present
+      if user
+        user_map = {}
+        user_map[:id] = user[:id] if user[:id]
+        user_map[:email] = user[:email] if user[:email]
+        user_map[:name] = user[:name] if user[:name]
+        user_map[:avatarUrl] = user[:avatar_url] || user[:avatarUrl] if user[:avatar_url] || user[:avatarUrl]
+        user_map[:adminScopes] = user[:admin_scopes] || user[:adminScopes] if user[:admin_scopes] || user[:adminScopes]
+        user_map[:allowedEmailDomains] = user[:allowed_email_domains] || user[:allowedEmailDomains] if user[:allowed_email_domains] || user[:allowedEmailDomains]
+        jwt_payload[:user] = user_map unless user_map.empty?
+      end
+
+      # Add other payload fields
+      jwt_payload[:component] = payload[:component] if payload[:component]
+      jwt_payload[:scope] = payload[:scope] if payload[:scope]
+      jwt_payload[:vars] = payload[:vars] if payload[:vars] && !payload[:vars].empty?
+
+      # Add any extra fields from payload (except known keys)
+      known_keys = %i[user component scope vars]
+      payload.each do |k, v|
+        jwt_payload[k] = v unless known_keys.include?(k)
+      end
+
+      # Add JWT claims
+      jwt_payload[:iat] = now
+      jwt_payload[:exp] = exp
+
+      # Encode header and payload
+      header_b64 = base64url_encode(JSON.generate(header))
+      payload_b64 = base64url_encode(JSON.generate(jwt_payload))
+
+      # Sign
+      to_sign = "#{header_b64}.#{payload_b64}"
+      signature = OpenSSL::HMAC.digest('SHA256', signing_key, to_sign)
+      signature_b64 = base64url_encode(signature)
+
+      "#{to_sign}.#{signature_b64}"
+    rescue => e
+      raise VortexError, "Token generation failed: #{e.message}"
+    end
+
+    private
+
+    # Parse expiration time string or int into seconds.
+    # Supports: '5m', '1h', '24h', '7d' or raw seconds as int.
+    #
+    # @param expires_in [String, Integer] Expiration time
+    # @return [Integer] Expiration time in seconds
+    # @raise [VortexError] If format is invalid
+    def parse_expires_in(expires_in)
+      return 30 * 24 * 60 * 60 if expires_in.nil?
+
+      if expires_in.is_a?(Integer)
+        raise VortexError, "Invalid expires_in value: #{expires_in}. Numeric expires_in must be a positive integer number of seconds." if expires_in <= 0
+        return expires_in
+      end
+
+      unless expires_in.is_a?(String)
+        raise VortexError, "Invalid expires_in type: #{expires_in.class}. Must be String or Integer."
+      end
+
+      match = expires_in.match(/^(\d+)(m|h|d)$/)
+      unless match
+        raise VortexError, "Invalid expires_in format: \"#{expires_in}\". Use format like \"5m\", \"1h\", \"24h\", \"7d\" or a number of seconds."
+      end
+
+      value = match[1].to_i
+      if value <= 0
+        raise VortexError, "Invalid expires_in value: \"#{expires_in}\". Duration must be positive (e.g., \"5m\", \"1h\", \"7d\")."
+      end
+      unit = match[2]
+
+      multipliers = { 'm' => 60, 'h' => 60 * 60, 'd' => 60 * 60 * 24 }
+      value * multipliers[unit]
+    end
+
+    # Recursively convert hash keys to symbols
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+      hash.each_with_object({}) do |(k, v), result|
+        key = k.is_a?(String) ? k.to_sym : k
+        result[key] = v.is_a?(Hash) ? symbolize_keys(v) : v
+      end
+    end
+
     public
 
     # Get invitations by target
@@ -132,7 +361,7 @@ module Vortex
         req.params['targetValue'] = target_value
       end
 
-      handle_response(response)['invitations'] || []
+      transform_invitation_results(handle_response(response)['invitations'] || [])
     rescue => e
       raise VortexError, "Failed to get invitations by target: #{e.message}"
     end
@@ -144,7 +373,7 @@ module Vortex
     # @raise [VortexError] If the request fails
     def get_invitation(invitation_id)
       response = @connection.get("/api/v1/invitations/#{invitation_id}")
-      handle_response(response)
+      transform_invitation_result(handle_response(response))
     rescue => e
       raise VortexError, "Failed to get invitation: #{e.message}"
     end
@@ -236,9 +465,17 @@ module Vortex
       # Validate that either email or phone is provided
       raise VortexError, 'User must have either email or phone' if user[:email].nil? && user[:phone].nil?
 
+      # Transform user keys to camelCase for API
+      api_user = user.compact.transform_keys do |key|
+        case key
+        when :is_existing then :isExisting
+        else key
+        end
+      end
+
       body = {
         invitationIds: invitation_ids,
-        user: user.compact # Remove nil values
+        user: api_user
       }
 
       response = @connection.post('/api/v1/invitations/accept') do |req|
@@ -246,7 +483,7 @@ module Vortex
         req.body = JSON.generate(body)
       end
 
-      handle_response(response)
+      transform_invitation_result(handle_response(response))
     rescue VortexError
       raise
     rescue => e
@@ -271,26 +508,26 @@ module Vortex
 
     # Get invitations by group
     #
-    # @param group_type [String] The group type
-    # @param group_id [String] The group ID
+    # @param scope_type [String] The group type
+    # @param scope [String] The group ID
     # @return [Array<Hash>] List of invitations for the group
     # @raise [VortexError] If the request fails
-    def get_invitations_by_group(group_type, group_id)
-      response = @connection.get("/api/v1/invitations/by-group/#{group_type}/#{group_id}")
+    def get_invitations_by_scope(scope_type, scope)
+      response = @connection.get("/api/v1/invitations/by-scope/#{scope_type}/#{scope}")
       result = handle_response(response)
-      result['invitations'] || []
+      transform_invitation_results(result['invitations'] || [])
     rescue => e
       raise VortexError, "Failed to get group invitations: #{e.message}"
     end
 
     # Delete invitations by group
     #
-    # @param group_type [String] The group type
-    # @param group_id [String] The group ID
+    # @param scope_type [String] The group type
+    # @param scope [String] The group ID
     # @return [Hash] Success response
     # @raise [VortexError] If the request fails
-    def delete_invitations_by_group(group_type, group_id)
-      response = @connection.delete("/api/v1/invitations/by-group/#{group_type}/#{group_id}")
+    def delete_invitations_by_scope(scope_type, scope)
+      response = @connection.delete("/api/v1/invitations/by-scope/#{scope_type}/#{scope}")
       handle_response(response)
     rescue => e
       raise VortexError, "Failed to delete group invitations: #{e.message}"
@@ -303,7 +540,7 @@ module Vortex
     # @raise [VortexError] If the request fails
     def reinvite(invitation_id)
       response = @connection.post("/api/v1/invitations/#{invitation_id}/reinvite")
-      handle_response(response)
+      transform_invitation_result(handle_response(response))
     rescue => e
       raise VortexError, "Failed to reinvite: #{e.message}"
     end
@@ -322,7 +559,7 @@ module Vortex
     # @param widget_configuration_id [String] The widget configuration ID to use
     # @param target [Hash] The invitation target: { type: 'email|sms|internal', value: '...' }
     # @param inviter [Hash] The inviter info: { user_id: '...', user_email: '...', name: '...' }
-    # @param groups [Array<Hash>, nil] Optional groups: [{ type: '...', group_id: '...', name: '...' }]
+    # @param groups [Array<Hash>, nil] Optional groups: [{ type: '...', scope: '...', name: '...' }]
     # @param source [String, nil] Optional source for analytics (defaults to 'api')
     # @param subtype [String, nil] Optional subtype for analytics segmentation (e.g., 'pymk', 'find-friends')
     # @param template_variables [Hash, nil] Optional template variables for email customization
@@ -336,7 +573,7 @@ module Vortex
     #     'widget-config-123',
     #     { type: 'email', value: 'invitee@example.com' },
     #     { user_id: 'user-456', user_email: 'inviter@example.com', name: 'John Doe' },
-    #     [{ type: 'team', group_id: 'team-789', name: 'Engineering' }],
+    #     [{ type: 'team', scope: 'team-789', name: 'Engineering' }],
     #     nil,
     #     nil,
     #     nil,
@@ -351,20 +588,28 @@ module Vortex
     #     nil,
     #     'pymk'
     #   )
-    def create_invitation(widget_configuration_id, target, inviter, groups = nil, source = nil, subtype = nil, template_variables = nil, metadata = nil, unfurl_config = nil)
+    def create_invitation(widget_configuration_id, target, inviter, groups = nil, source = nil, subtype = nil, template_variables = nil, metadata = nil, unfurl_config = nil, scopes: nil, scope_id: nil, scope_type: nil, scope_name: nil)
       raise VortexError, 'widget_configuration_id is required' if widget_configuration_id.nil? || widget_configuration_id.empty?
       raise VortexError, 'target must have type and value' if target[:type].nil? || target[:value].nil?
       raise VortexError, 'inviter must have user_id' if inviter[:user_id].nil?
 
+      # Scope translation: flat params > scopes > groups
+      if scope_id && groups.nil? && scopes.nil?
+        groups = [{ type: scope_type || '', scope_id: scope_id, name: scope_name || '' }]
+      elsif scopes && groups.nil?
+        groups = scopes
+      end
+
       # Build request body with camelCase keys for the API
+      # Prefer new property names (name/avatar_url), fall back to deprecated (user_name/user_avatar_url)
       body = {
         widgetConfigurationId: widget_configuration_id,
         target: target,
         inviter: {
           userId: inviter[:user_id],
           userEmail: inviter[:user_email],
-          userName: inviter[:user_name],
-          userAvatarUrl: inviter[:user_avatar_url]
+          name: inviter[:name] || inviter[:user_name],
+          avatarUrl: inviter[:avatar_url] || inviter[:user_avatar_url]
         }.compact
       }
 
@@ -372,7 +617,7 @@ module Vortex
         body[:groups] = groups.map do |g|
           {
             type: g[:type],
-            groupId: g[:group_id],
+            groupId: g[:scope] || g[:scope_id] || g[:group_id] || g[:scopeId] || g[:groupId],
             name: g[:name]
           }
         end
@@ -421,7 +666,11 @@ module Vortex
       encoded_scope = URI.encode_www_form_component(scope)
 
       response = @connection.get("/api/v1/invitations/by-scope/#{encoded_scope_type}/#{encoded_scope}/autojoin")
-      handle_response(response)
+      result = handle_response(response)
+      if result.is_a?(Hash) && result['invitation'].is_a?(Hash)
+        result['invitation'] = transform_invitation_result(result['invitation'])
+      end
+      result
     rescue VortexError
       raise
     rescue => e
@@ -437,7 +686,7 @@ module Vortex
     # @param scope [String] The scope identifier (customer's group ID)
     # @param scope_type [String] The type of scope (e.g., "organization", "team")
     # @param domains [Array<String>] Array of domains to configure for autojoin
-    # @param widget_id [String] The widget configuration ID
+    # @param component_id [String] The component ID
     # @param scope_name [String, nil] Optional display name for the scope
     # @param metadata [Hash, nil] Optional metadata to attach to the invitation
     # @return [Hash] Response with :autojoin_domains array and :invitation
@@ -448,20 +697,20 @@ module Vortex
     #     'acme-org',
     #     'organization',
     #     ['acme.com', 'acme.org'],
-    #     'widget-123',
+    #     'component-123',
     #     'Acme Corporation'
     #   )
-    def configure_autojoin(scope, scope_type, domains, widget_id, scope_name = nil, metadata = nil)
+    def configure_autojoin(scope, scope_type, domains, component_id, scope_name = nil, metadata = nil)
       raise VortexError, 'scope is required' if scope.nil? || scope.empty?
       raise VortexError, 'scope_type is required' if scope_type.nil? || scope_type.empty?
-      raise VortexError, 'widget_id is required' if widget_id.nil? || widget_id.empty?
+      raise VortexError, 'component_id is required' if component_id.nil? || component_id.empty?
       raise VortexError, 'domains must be an array' unless domains.is_a?(Array)
 
       body = {
         scope: scope,
         scopeType: scope_type,
         domains: domains,
-        widgetId: widget_id
+        componentId: component_id
       }
 
       body[:scopeName] = scope_name if scope_name
@@ -472,7 +721,11 @@ module Vortex
         req.body = JSON.generate(body)
       end
 
-      handle_response(response)
+      result = handle_response(response)
+      if result.is_a?(Hash) && result['invitation'].is_a?(Hash)
+        result['invitation'] = transform_invitation_result(result['invitation'])
+      end
+      result
     rescue VortexError
       raise
     rescue => e
@@ -521,6 +774,29 @@ module Vortex
 
     private
 
+    # Transform an invitation scope by adding scope_id (= groupId)
+    def transform_scope(scope)
+      return scope unless scope.is_a?(Hash) && scope.key?('groupId')
+      scope.merge('scopeId' => scope['groupId'])
+    end
+
+    # Transform an invitation result by adding scopes (= groups with scopeId)
+    def transform_invitation_result(result)
+      return result unless result.is_a?(Hash)
+      if result['groups'].is_a?(Array)
+        mapped = result['groups'].map { |g| transform_scope(g) }
+        result['scopes'] = mapped
+        result['groups'] = mapped
+      end
+      result
+    end
+
+    # Transform an array of invitation results
+    def transform_invitation_results(results)
+      return results unless results.is_a?(Array)
+      results.map { |r| transform_invitation_result(r) }
+    end
+
     def build_connection
       Faraday.new(@base_url) do |conn|
         conn.request :json
@@ -563,5 +839,17 @@ module Vortex
       hex = bytes.unpack1('H*')
       "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
     end
+
+    # Deprecated methods for backward compatibility
+
+    # @deprecated Use get_invitations_by_scope instead
+    def get_invitations_by_group(group_type, group)
+      get_invitations_by_scope(group_type, group)
+    end
+
+    # @deprecated Use delete_invitations_by_scope instead
+    def delete_invitations_by_group(group_type, group)
+      delete_invitations_by_scope(group_type, group)
+    end
   end
-end
+end

data/lib/vortex/rails.rb

@@ -181,9 +181,9 @@ module Vortex
       end
 
       # 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")
+      # GET /api/vortex/invitations/by-scope/:scope_type/:scope
+      def get_invitations_by_scope
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#get_invitations_by_scope invoked")
 
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
@@ -192,19 +192,19 @@ module Vortex
           return render_forbidden('Not authorized to get group invitations')
         end
 
-        group_type = params[:group_type]
-        group_id = params[:group_id]
+        scope_type = params[:scope_type]
+        scope = params[:scope]
 
-        invitations = vortex_client.get_invitations_by_group(group_type, group_id)
+        invitations = vortex_client.get_invitations_by_scope(scope_type, scope)
         render json: { invitations: invitations }
       rescue Vortex::VortexError => e
         render_server_error("Failed to get group invitations: #{e.message}")
       end
 
       # 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")
+      # DELETE /api/vortex/invitations/by-scope/:scope_type/:scope
+      def delete_invitations_by_scope
+        Vortex::Rails.logger.debug("Vortex::Rails::Controller#delete_invitations_by_scope invoked")
 
         user = authenticate_vortex_user
         return render_unauthorized('Authentication required') unless user
@@ -213,10 +213,10 @@ module Vortex
           return render_forbidden('Not authorized to delete group invitations')
         end
 
-        group_type = params[:group_type]
-        group_id = params[:group_id]
+        scope_type = params[:scope_type]
+        scope = params[:scope]
 
-        vortex_client.delete_invitations_by_group(group_type, group_id)
+        vortex_client.delete_invitations_by_scope(scope_type, scope)
         render json: { success: true }
       rescue Vortex::VortexError => e
         render_server_error("Failed to delete group invitations: #{e.message}")
@@ -296,8 +296,8 @@ module Vortex
           get 'invitations/:invitation_id', action: 'get_invitation'
           delete 'invitations/:invitation_id', action: 'revoke_invitation'
           post 'invitations/accept', action: 'accept_invitations'
-          get 'invitations/by-group/:group_type/:group_id', action: 'get_invitations_by_group'
-          delete 'invitations/by-group/:group_type/:group_id', action: 'delete_invitations_by_group'
+          get 'invitations/by-scope/:scope_type/:scope', action: 'get_invitations_by_scope'
+          delete 'invitations/by-scope/:scope_type/:scope', action: 'delete_invitations_by_scope'
           post 'invitations/:invitation_id/reinvite', action: 'reinvite'
         end
       end