vortex-ruby-sdk 1.0.0

data/lib/vortex/rails.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'vortex/client'
+require 'vortex/error'
+
+module Vortex
+  module Rails
+    # Rails controller integration for Vortex SDK
+    #
+    # This module provides the same route structure as other SDKs (Express, Java, Python)
+    # to ensure complete compatibility with React providers and frontend frameworks.
+    #
+    # Usage in Rails controller:
+    #   class VortexController < ApplicationController
+    #     include Vortex::Rails::Controller
+    #
+    #     private
+    #
+    #     def authenticate_vortex_user
+    #       # Return user data or nil
+    #     end
+    #
+    #     def authorize_vortex_operation(operation, user)
+    #       # Return true/false
+    #     end
+    #
+    #     def vortex_client
+    #       @vortex_client ||= Vortex::Client.new(ENV['VORTEX_API_KEY'])
+    #     end
+    #   end
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        # Ensure these routes match exactly with other SDKs for React provider compatibility
+        rescue_from Vortex::VortexError, with: :handle_vortex_error
+      end
+
+      # Generate JWT for authenticated user
+      # POST /api/vortex/jwt
+      def generate_jwt
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('JWT', user)
+          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]
+        )
+
+        render json: { jwt: jwt }
+      rescue Vortex::VortexError => e
+        render_server_error("Failed to generate JWT: #{e.message}")
+      end
+
+      # Get invitations by target
+      # GET /api/vortex/invitations?targetType=email&targetValue=user@example.com
+      def get_invitations_by_target
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('GET_INVITATIONS', user)
+          return render_forbidden('Not authorized to get invitations')
+        end
+
+        target_type = params[:targetType]
+        target_value = params[:targetValue]
+
+        return render_bad_request('Missing targetType or targetValue') unless target_type && target_value
+
+        invitations = vortex_client.get_invitations_by_target(target_type, target_value)
+        render json: { invitations: invitations }
+      rescue Vortex::VortexError => e
+        render_server_error("Failed to get invitations: #{e.message}")
+      end
+
+      # Get specific invitation by ID
+      # GET /api/vortex/invitations/:invitation_id
+      def get_invitation
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('GET_INVITATION', user)
+          return render_forbidden('Not authorized to get invitation')
+        end
+
+        invitation_id = params[:invitation_id]
+        invitation = vortex_client.get_invitation(invitation_id)
+        render json: invitation
+      rescue Vortex::VortexError => e
+        render_not_found("Invitation not found: #{e.message}")
+      end
+
+      # Revoke (delete) invitation
+      # DELETE /api/vortex/invitations/:invitation_id
+      def revoke_invitation
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('REVOKE_INVITATION', user)
+          return render_forbidden('Not authorized to revoke invitation')
+        end
+
+        invitation_id = params[:invitation_id]
+        vortex_client.revoke_invitation(invitation_id)
+        render json: { success: true }
+      rescue Vortex::VortexError => e
+        render_server_error("Failed to revoke invitation: #{e.message}")
+      end
+
+      # Accept invitations
+      # POST /api/vortex/invitations/accept
+      def accept_invitations
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('ACCEPT_INVITATIONS', user)
+          return render_forbidden('Not authorized to accept invitations')
+        end
+
+        invitation_ids = params[:invitationIds]
+        target = params[:target]
+
+        unless invitation_ids && target
+          return render_bad_request('Missing invitationIds or target')
+        end
+
+        result = vortex_client.accept_invitations(invitation_ids, target)
+        render json: result
+      rescue Vortex::VortexError => e
+        render_server_error("Failed to accept invitations: #{e.message}")
+      end
+
+      # Get invitations by group
+      # GET /api/vortex/invitations/by-group/:group_type/:group_id
+      def get_invitations_by_group
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('GET_GROUP_INVITATIONS', user)
+          return render_forbidden('Not authorized to get group invitations')
+        end
+
+        group_type = params[:group_type]
+        group_id = params[:group_id]
+
+        invitations = vortex_client.get_invitations_by_group(group_type, group_id)
+        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
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('DELETE_GROUP_INVITATIONS', user)
+          return render_forbidden('Not authorized to delete group invitations')
+        end
+
+        group_type = params[:group_type]
+        group_id = params[:group_id]
+
+        vortex_client.delete_invitations_by_group(group_type, group_id)
+        render json: { success: true }
+      rescue Vortex::VortexError => e
+        render_server_error("Failed to delete group invitations: #{e.message}")
+      end
+
+      # Reinvite user
+      # POST /api/vortex/invitations/:invitation_id/reinvite
+      def reinvite
+        user = authenticate_vortex_user
+        return render_unauthorized('Authentication required') unless user
+
+        unless authorize_vortex_operation('REINVITE', user)
+          return render_forbidden('Not authorized to reinvite')
+        end
+
+        invitation_id = params[:invitation_id]
+        result = vortex_client.reinvite(invitation_id)
+        render json: result
+      rescue Vortex::VortexError => e
+        render_server_error("Failed to reinvite: #{e.message}")
+      end
+
+      private
+
+      # These methods should be implemented in the including controller
+      def authenticate_vortex_user
+        raise NotImplementedError, 'authenticate_vortex_user must be implemented'
+      end
+
+      def authorize_vortex_operation(operation, user)
+        raise NotImplementedError, 'authorize_vortex_operation must be implemented'
+      end
+
+      def vortex_client
+        raise NotImplementedError, 'vortex_client must be implemented'
+      end
+
+      # Error response helpers
+      def render_unauthorized(message)
+        render json: { error: message }, status: :unauthorized
+      end
+
+      def render_forbidden(message)
+        render json: { error: message }, status: :forbidden
+      end
+
+      def render_bad_request(message)
+        render json: { error: message }, status: :bad_request
+      end
+
+      def render_not_found(message)
+        render json: { error: message }, status: :not_found
+      end
+
+      def render_server_error(message)
+        render json: { error: message }, status: :internal_server_error
+      end
+
+      def handle_vortex_error(error)
+        Rails.logger.error("Vortex error: #{error.message}")
+        render_server_error(error.message)
+      end
+    end
+
+    # Rails routes helper
+    #
+    # Usage in routes.rb:
+    #   Rails.application.routes.draw do
+    #     mount Vortex::Rails.routes => '/api/vortex'
+    #   end
+    def self.routes
+      proc do
+        scope '/api/vortex', controller: 'vortex' do
+          post 'jwt', action: 'generate_jwt'
+          get 'invitations', action: 'get_invitations_by_target'
+          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'
+          post 'invitations/:invitation_id/reinvite', action: 'reinvite'
+        end
+      end
+    end
+  end
+end

data/lib/vortex/sinatra.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'vortex/client'
+require 'vortex/error'
+
+module Vortex
+  module Sinatra
+    # Sinatra application integration for Vortex SDK
+    #
+    # This module provides the same route structure as other SDKs (Express, Java, Python)
+    # to ensure complete compatibility with React providers and frontend frameworks.
+    #
+    # Usage in Sinatra app:
+    #   require 'sinatra/base'
+    #   require 'vortex/sinatra'
+    #
+    #   class MyApp < Sinatra::Base
+    #     register Vortex::Sinatra
+    #
+    #     configure do
+    #       set :vortex_api_key, ENV['VORTEX_API_KEY']
+    #       set :vortex_base_url, ENV['VORTEX_BASE_URL'] # optional
+    #     end
+    #
+    #     # Implement authentication callbacks
+    #     def authenticate_vortex_user
+    #       # Return user hash or nil
+    #     end
+    #
+    #     def authorize_vortex_operation(operation, user)
+    #       # Return true/false
+    #     end
+    #   end
+    def self.registered(app)
+      app.helpers Helpers
+
+      # Ensure these routes match exactly with other SDKs for React provider compatibility
+
+      # Generate JWT for authenticated user
+      # POST /api/vortex/jwt
+      app.post '/api/vortex/jwt' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('JWT', user)
+            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]
+          )
+
+          render_json({ jwt: jwt })
+        end
+      end
+
+      # Get invitations by target
+      # GET /api/vortex/invitations?targetType=email&targetValue=user@example.com
+      app.get '/api/vortex/invitations' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('GET_INVITATIONS', user)
+            return render_forbidden('Not authorized to get invitations')
+          end
+
+          target_type = params['targetType']
+          target_value = params['targetValue']
+
+          unless target_type && target_value
+            return render_bad_request('Missing targetType or targetValue')
+          end
+
+          invitations = vortex_client.get_invitations_by_target(target_type, target_value)
+          render_json({ invitations: invitations })
+        end
+      end
+
+      # Get specific invitation by ID
+      # GET /api/vortex/invitations/:invitation_id
+      app.get '/api/vortex/invitations/:invitation_id' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('GET_INVITATION', user)
+            return render_forbidden('Not authorized to get invitation')
+          end
+
+          invitation_id = params['invitation_id']
+          invitation = vortex_client.get_invitation(invitation_id)
+          render_json(invitation)
+        end
+      end
+
+      # Revoke (delete) invitation
+      # DELETE /api/vortex/invitations/:invitation_id
+      app.delete '/api/vortex/invitations/:invitation_id' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('REVOKE_INVITATION', user)
+            return render_forbidden('Not authorized to revoke invitation')
+          end
+
+          invitation_id = params['invitation_id']
+          vortex_client.revoke_invitation(invitation_id)
+          render_json({ success: true })
+        end
+      end
+
+      # Accept invitations
+      # POST /api/vortex/invitations/accept
+      app.post '/api/vortex/invitations/accept' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('ACCEPT_INVITATIONS', user)
+            return render_forbidden('Not authorized to accept invitations')
+          end
+
+          request_body = parse_json_body
+
+          invitation_ids = request_body['invitationIds']
+          target = request_body['target']
+
+          unless invitation_ids && target
+            return render_bad_request('Missing invitationIds or target')
+          end
+
+          result = vortex_client.accept_invitations(invitation_ids, target)
+          render_json(result)
+        end
+      end
+
+      # Get invitations by group
+      # GET /api/vortex/invitations/by-group/:group_type/:group_id
+      app.get '/api/vortex/invitations/by-group/:group_type/:group_id' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('GET_GROUP_INVITATIONS', user)
+            return render_forbidden('Not authorized to get group invitations')
+          end
+
+          group_type = params['group_type']
+          group_id = params['group_id']
+
+          invitations = vortex_client.get_invitations_by_group(group_type, group_id)
+          render_json({ invitations: invitations })
+        end
+      end
+
+      # Delete invitations by group
+      # DELETE /api/vortex/invitations/by-group/:group_type/:group_id
+      app.delete '/api/vortex/invitations/by-group/:group_type/:group_id' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('DELETE_GROUP_INVITATIONS', user)
+            return render_forbidden('Not authorized to delete group invitations')
+          end
+
+          group_type = params['group_type']
+          group_id = params['group_id']
+
+          vortex_client.delete_invitations_by_group(group_type, group_id)
+          render_json({ success: true })
+        end
+      end
+
+      # Reinvite user
+      # POST /api/vortex/invitations/:invitation_id/reinvite
+      app.post '/api/vortex/invitations/:invitation_id/reinvite' do
+        with_vortex_error_handling do
+          user = authenticate_vortex_user
+          return render_unauthorized('Authentication required') unless user
+
+          unless authorize_vortex_operation('REINVITE', user)
+            return render_forbidden('Not authorized to reinvite')
+          end
+
+          invitation_id = params['invitation_id']
+          result = vortex_client.reinvite(invitation_id)
+          render_json(result)
+        end
+      end
+
+      # Configure Vortex client
+      app.configure do
+        unless app.respond_to?(:vortex_client)
+          app.set :vortex_client, nil
+        end
+      end
+    end
+
+    # Helper methods for Sinatra apps using Vortex
+    module Helpers
+      def vortex_client
+        @vortex_client ||= begin
+          api_key = settings.vortex_api_key
+          base_url = settings.respond_to?(:vortex_base_url) ? settings.vortex_base_url : nil
+
+          raise 'Vortex API key not configured' unless api_key
+
+          Vortex::Client.new(api_key, base_url: base_url)
+        end
+      end
+
+      def authenticate_vortex_user
+        # Default implementation - should be overridden in app
+        nil
+      end
+
+      def authorize_vortex_operation(operation, user)
+        # Default implementation - should be overridden in app
+        user != nil
+      end
+
+      def with_vortex_error_handling(&block)
+        yield
+      rescue Vortex::VortexError => e
+        logger.error("Vortex error: #{e.message}") if respond_to?(:logger)
+        render_server_error("Vortex error: #{e.message}")
+      rescue => e
+        logger.error("Unexpected error: #{e.message}") if respond_to?(:logger)
+        render_server_error("Internal server error")
+      end
+
+      def parse_json_body
+        request.body.rewind
+        body = request.body.read
+        return {} if body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        halt 400, render_json({ error: 'Invalid JSON in request body' })
+      end
+
+      def render_json(data)
+        content_type :json
+        JSON.generate(data)
+      end
+
+      def render_unauthorized(message)
+        halt 401, render_json({ error: message })
+      end
+
+      def render_forbidden(message)
+        halt 403, render_json({ error: message })
+      end
+
+      def render_bad_request(message)
+        halt 400, render_json({ error: message })
+      end
+
+      def render_not_found(message)
+        halt 404, render_json({ error: message })
+      end
+
+      def render_server_error(message)
+        halt 500, render_json({ error: message })
+      end
+    end
+  end
+end

data/lib/vortex/version.rb

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

data/lib/vortex.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'vortex/version'
+require 'vortex/error'
+require 'vortex/client'
+
+# Vortex Ruby SDK
+#
+# This gem provides a Ruby interface to the Vortex invitation system,
+# with the same functionality and API compatibility as other Vortex SDKs
+# (Node.js, Python, Java, Go).
+#
+# Features:
+# - JWT generation with identical algorithm to other SDKs
+# - Complete invitation management API
+# - Rails and Sinatra framework integrations
+# - Same route structure for React provider compatibility
+#
+# Basic usage:
+#   require 'vortex'
+#
+#   client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
+#
+#   jwt = client.generate_jwt(
+#     user_id: 'user123',
+#     identifiers: [{ type: 'email', value: 'user@example.com' }],
+#     groups: [{ id: 'team1', type: 'team', name: 'Engineering' }],
+#     role: 'admin'
+#   )
+#
+# Framework integrations:
+#   # Rails
+#   require 'vortex/rails'
+#
+#   # Sinatra
+#   require 'vortex/sinatra'
+module Vortex
+  class << self
+    # Create a new Vortex client instance
+    #
+    # @param api_key [String] Your Vortex API key
+    # @param base_url [String] Custom base URL (optional)
+    # @return [Vortex::Client] A new client instance
+    def new(api_key, base_url: nil)
+      Client.new(api_key, base_url: base_url)
+    end
+
+    # Get the current version of the SDK
+    #
+    # @return [String] Version string
+    def version
+      VERSION
+    end
+  end
+end

data/vortex-ruby-sdk.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'lib/vortex/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'vortex-ruby-sdk'
+  spec.version = Vortex::VERSION
+  spec.authors = ['Vortex Software']
+  spec.email = ['support@vortexsoftware.io']
+
+  spec.summary = 'Ruby SDK for Vortex invitation system'
+  spec.description = 'A Ruby SDK that provides seamless integration with the Vortex invitation system, including JWT generation and invitation management.'
+  spec.homepage = 'https://github.com/vortexsoftware/vortex-ruby-sdk'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'faraday-net_http', '~> 3.0'
+
+  # Framework integration dependencies (optional)
+  spec.add_dependency 'rack', '>= 2.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'bundler', '>= 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+end