vortex-ruby-sdk 1.0.0

data/Rakefile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+YARD::Rake::YardocTask.new
+
+desc 'Run all tests and linting'
+task test: [:spec, :rubocop]
+
+desc 'Run tests with coverage'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec'].execute
+end
+
+desc 'Generate documentation'
+task :docs do
+  Rake::Task['yard'].execute
+end
+
+desc 'Setup development environment'
+task :setup do
+  sh 'bundle install'
+  puts 'Development environment ready!'
+end
+
+desc 'Run interactive console'
+task :console do
+  require 'bundler/setup'
+  require 'vortex'
+  require 'irb'
+  IRB.start(__FILE__)
+end
+
+task default: :test

data/examples/basic_usage.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic usage example for Vortex Ruby SDK
+#
+# This example demonstrates how to use the core functionality of the Vortex Ruby SDK,
+# showing the same operations available in all other Vortex SDKs (Node.js, Python, Java, Go).
+
+require 'bundler/setup'
+require 'vortex'
+
+# Initialize the client with your API key
+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'
+}
+
+begin
+  puts "=== Vortex Ruby SDK Example ==="
+  puts
+
+  # 1. Generate JWT
+  puts "1. Generating JWT for user..."
+  jwt = client.generate_jwt(**user_data)
+  puts "JWT generated: #{jwt[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')
+  puts "Found #{invitations.length} invitation(s)"
+  puts
+
+  # 3. Get invitations by group
+  puts "3. Getting invitations for team group..."
+  group_invitations = client.get_invitations_by_group('team', 'team1')
+  puts "Found #{group_invitations.length} group invitation(s)"
+  puts
+
+  # 4. Example of accepting invitations (if any exist)
+  if invitations.any?
+    puts "4. Accepting first invitation..."
+    invitation_ids = [invitations.first['id']]
+    target = { type: 'email', value: 'user@example.com' }
+
+    result = client.accept_invitations(invitation_ids, target)
+    puts "Invitation accepted: #{result['id']}"
+  else
+    puts "4. No invitations to accept"
+  end
+  puts
+
+  puts "=== All operations completed successfully! ==="
+
+rescue Vortex::VortexError => e
+  puts "Vortex error: #{e.message}"
+  exit 1
+rescue => e
+  puts "Unexpected error: #{e.message}"
+  exit 1
+end

data/examples/rails_app.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Rails application example for Vortex Ruby SDK
+#
+# This example shows how to integrate the Vortex SDK with a Rails application,
+# providing the same API routes as other SDK integrations (Express, Java Spring, Python Flask).
+
+# Gemfile additions needed:
+# gem 'rails', '~> 7.0'
+# gem 'vortex-ruby-sdk'
+
+require 'rails'
+require 'action_controller/railtie'
+require 'vortex/rails'
+
+class VortexExampleApp < Rails::Application
+  config.api_only = true
+  config.eager_load = false
+  config.logger = Logger.new(STDOUT)
+end
+
+# Example Vortex controller with authentication
+class VortexController < ActionController::Base
+  include Vortex::Rails::Controller
+
+  private
+
+  # Implement user authentication - return user data hash or nil
+  def authenticate_vortex_user
+    # Example: get user from session/JWT/etc.
+    user_id = session[:user_id] || request.headers['X-User-ID']
+    return nil unless user_id
+
+    # Return user data in the format expected by Vortex
+    {
+      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'
+    }
+  end
+
+  # Implement authorization - return true/false
+  def authorize_vortex_operation(operation, user)
+    # Example: check user permissions
+    case operation
+    when 'JWT'
+      true # Everyone can generate JWT if authenticated
+    when 'GET_INVITATIONS', 'GET_INVITATION'
+      true # Everyone can view invitations
+    when 'ACCEPT_INVITATIONS'
+      true # Everyone can accept invitations
+    when 'REVOKE_INVITATION', 'DELETE_GROUP_INVITATIONS'
+      user[:role] == 'admin' # Only admins can delete
+    when 'GET_GROUP_INVITATIONS', 'REINVITE'
+      user[:role] == 'admin' # Only admins can manage groups
+    else
+      false
+    end
+  end
+
+  # Provide Vortex client instance
+  def vortex_client
+    @vortex_client ||= Vortex::Client.new(
+      ENV['VORTEX_API_KEY'] || 'your-api-key-here'
+    )
+  end
+end
+
+# Configure routes - these match exactly with other SDK routes
+Rails.application.routes.draw 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
+
+  # Health check
+  get '/health', to: proc { [200, {}, ['OK']] }
+
+  # Root route with API documentation
+  root to: proc do
+    [200, { 'Content-Type' => 'application/json' }, [
+      {
+        name: 'Vortex Rails API',
+        version: Vortex::VERSION,
+        endpoints: {
+          jwt: 'POST /api/vortex/jwt',
+          invitations: 'GET /api/vortex/invitations?targetType=email&targetValue=user@example.com',
+          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',
+          reinvite: 'POST /api/vortex/invitations/:id/reinvite'
+        }
+      }.to_json
+    ]]
+  end
+end
+
+if __FILE__ == $0
+  puts "🚀 Starting Vortex Rails API server..."
+  puts "📊 Health check: http://localhost:3000/health"
+  puts "🔧 Vortex API routes available at http://localhost:3000/api/vortex"
+  puts
+  puts "Available endpoints:"
+  puts "  POST /api/vortex/jwt"
+  puts "  GET  /api/vortex/invitations?targetType=email&targetValue=user@example.com"
+  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 "  POST /api/vortex/invitations/:id/reinvite"
+
+  Rails.application.initialize!
+  Rails.application.run(Port: 3000)
+end

data/examples/sinatra_app.rb

@@ -0,0 +1,119 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Sinatra application example for Vortex Ruby SDK
+#
+# This example shows how to integrate the Vortex SDK with a Sinatra application,
+# providing the same API routes as other SDK integrations (Express, Java Spring, Python Flask).
+
+require 'bundler/setup'
+require 'sinatra/base'
+require 'json'
+require 'vortex/sinatra'
+
+class VortexSinatraApp < Sinatra::Base
+  register Vortex::Sinatra
+
+  configure do
+    set :vortex_api_key, ENV['VORTEX_API_KEY'] || 'your-api-key-here'
+    set :vortex_base_url, ENV['VORTEX_BASE_URL'] # optional
+  end
+
+  # Implement user authentication
+  def authenticate_vortex_user
+    # Example: get user from headers/session/JWT
+    user_id = request.env['HTTP_X_USER_ID'] || 'demo-user'
+    return nil unless user_id
+
+    # Return user data in the format expected by Vortex
+    {
+      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'
+    }
+  end
+
+  # Implement authorization
+  def authorize_vortex_operation(operation, user)
+    case operation
+    when 'JWT'
+      true # Everyone can generate JWT if authenticated
+    when 'GET_INVITATIONS', 'GET_INVITATION'
+      true # Everyone can view invitations
+    when 'ACCEPT_INVITATIONS'
+      true # Everyone can accept invitations
+    when 'REVOKE_INVITATION', 'DELETE_GROUP_INVITATIONS'
+      user[:role] == 'admin' # Only admins can delete
+    when 'GET_GROUP_INVITATIONS', 'REINVITE'
+      user[:role] == 'admin' # Only admins can manage groups
+    else
+      false
+    end
+  end
+
+  # Health check endpoint
+  get '/health' do
+    content_type :json
+    { status: 'OK', version: Vortex::VERSION }.to_json
+  end
+
+  # Root endpoint with API documentation
+  get '/' do
+    content_type :json
+    {
+      name: 'Vortex Sinatra API',
+      version: Vortex::VERSION,
+      endpoints: {
+        jwt: 'POST /api/vortex/jwt',
+        invitations: 'GET /api/vortex/invitations?targetType=email&targetValue=user@example.com',
+        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',
+        reinvite: 'POST /api/vortex/invitations/:id/reinvite'
+      }
+    }.to_json
+  end
+
+  # Error handlers
+  error Vortex::VortexError do
+    content_type :json
+    status 500
+    { error: env['sinatra.error'].message }.to_json
+  end
+
+  error do
+    content_type :json
+    status 500
+    { error: 'Internal server error' }.to_json
+  end
+end
+
+if __FILE__ == $0
+  puts "🚀 Starting Vortex Sinatra API server..."
+  puts "📊 Health check: http://localhost:4567/health"
+  puts "🔧 Vortex API routes available at http://localhost:4567/api/vortex"
+  puts
+  puts "Available endpoints:"
+  puts "  POST /api/vortex/jwt"
+  puts "  GET  /api/vortex/invitations?targetType=email&targetValue=user@example.com"
+  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 "  POST /api/vortex/invitations/:id/reinvite"
+  puts
+  puts "Authentication headers (for testing):"
+  puts "  X-User-ID: your-user-id"
+  puts "  X-User-Email: your-email@example.com"
+  puts "  X-User-Role: user|admin"
+
+  VortexSinatraApp.run!
+end

data/lib/vortex/client.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'openssl'
+require 'securerandom'
+require 'faraday'
+
+module Vortex
+  # Vortex API client for Ruby
+  #
+  # Provides the same functionality as other Vortex SDKs with JWT generation,
+  # invitation management, and full API compatibility.
+  class Client
+    # Base URL for Vortex API
+    DEFAULT_BASE_URL = 'https://api.vortexsoftware.com'
+
+    # @param api_key [String] Your Vortex API key
+    # @param base_url [String] Custom base URL (optional)
+    def initialize(api_key, base_url: nil)
+      @api_key = api_key
+      @base_url = base_url || DEFAULT_BASE_URL
+      @connection = build_connection
+    end
+
+    # Generate a JWT for the given user data
+    #
+    # 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
+    # @return [String] JWT token
+    # @raise [VortexError] If API key is invalid or JWT generation fails
+    def generate_jwt(user_id:, identifiers:, groups:, role: nil)
+      # Parse API key - same format as Node.js SDK
+      prefix, encoded_id, key = @api_key.split('.')
+
+      raise VortexError, 'Invalid API key format' unless prefix && encoded_id && key
+      raise VortexError, 'Invalid API key prefix' unless prefix == 'VRTX'
+
+      # Decode the ID from base64url (same as Node.js Buffer.from(encodedId, 'base64url'))
+      decoded_bytes = Base64.urlsafe_decode64(encoded_id)
+
+      # Convert to UUID string format (same as uuidStringify in Node.js)
+      id = format_uuid(decoded_bytes)
+
+      expires = Time.now.to_i + 3600
+
+      # 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)
+      header = {
+        iat: Time.now.to_i,
+        alg: 'HS256',
+        typ: 'JWT',
+        kid: id
+      }
+
+      payload = {
+        userId: user_id,
+        groups: groups,
+        role: role,
+        expires: expires,
+        identifiers: identifiers
+      }
+
+      # Step 3: Base64URL encode (same as Node.js)
+      header_b64 = base64url_encode(JSON.generate(header))
+      payload_b64 = base64url_encode(JSON.generate(payload))
+
+      # Step 4: Sign with HMAC-SHA256 (same as Node.js)
+      signature = OpenSSL::HMAC.digest('sha256', signing_key, "#{header_b64}.#{payload_b64}")
+      signature_b64 = base64url_encode(signature)
+
+      "#{header_b64}.#{payload_b64}.#{signature_b64}"
+    rescue => e
+      raise VortexError, "JWT generation failed: #{e.message}"
+    end
+
+    # Get invitations by target
+    #
+    # @param target_type [String] Type of target (email, sms)
+    # @param target_value [String] Value of target (email address, phone number)
+    # @return [Array<Hash>] List of invitations
+    # @raise [VortexError] If the request fails
+    def get_invitations_by_target(target_type, target_value)
+      response = @connection.get('/api/v1/invitations') do |req|
+        req.params['targetType'] = target_type
+        req.params['targetValue'] = target_value
+      end
+
+      handle_response(response)['invitations'] || []
+    rescue => e
+      raise VortexError, "Failed to get invitations by target: #{e.message}"
+    end
+
+    # Get a specific invitation by ID
+    #
+    # @param invitation_id [String] The invitation ID
+    # @return [Hash] The invitation data
+    # @raise [VortexError] If the request fails
+    def get_invitation(invitation_id)
+      response = @connection.get("/api/v1/invitations/#{invitation_id}")
+      handle_response(response)
+    rescue => e
+      raise VortexError, "Failed to get invitation: #{e.message}"
+    end
+
+    # Revoke (delete) an invitation
+    #
+    # @param invitation_id [String] The invitation ID to revoke
+    # @return [Hash] Success response
+    # @raise [VortexError] If the request fails
+    def revoke_invitation(invitation_id)
+      response = @connection.delete("/api/v1/invitations/#{invitation_id}")
+      handle_response(response)
+    rescue => e
+      raise VortexError, "Failed to revoke invitation: #{e.message}"
+    end
+
+    # Accept invitations
+    #
+    # @param invitation_ids [Array<String>] List of invitation IDs to accept
+    # @param target [Hash] Target hash with :type and :value
+    # @return [Hash] The accepted invitation result
+    # @raise [VortexError] If the request fails
+    def accept_invitations(invitation_ids, target)
+      body = {
+        invitationIds: invitation_ids,
+        target: target
+      }
+
+      response = @connection.post('/api/v1/invitations/accept') do |req|
+        req.headers['Content-Type'] = 'application/json'
+        req.body = JSON.generate(body)
+      end
+
+      handle_response(response)
+    rescue => e
+      raise VortexError, "Failed to accept invitations: #{e.message}"
+    end
+
+    # Get invitations by group
+    #
+    # @param group_type [String] The group type
+    # @param group_id [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}")
+      result = handle_response(response)
+      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
+    # @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}")
+      handle_response(response)
+    rescue => e
+      raise VortexError, "Failed to delete group invitations: #{e.message}"
+    end
+
+    # Reinvite a user
+    #
+    # @param invitation_id [String] The invitation ID to reinvite
+    # @return [Hash] The reinvited invitation result
+    # @raise [VortexError] If the request fails
+    def reinvite(invitation_id)
+      response = @connection.post("/api/v1/invitations/#{invitation_id}/reinvite")
+      handle_response(response)
+    rescue => e
+      raise VortexError, "Failed to reinvite: #{e.message}"
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(@base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter Faraday.default_adapter
+
+        # Add API key header (same as Node.js SDK)
+        conn.headers['x-api-key'] = @api_key
+        conn.headers['User-Agent'] = "vortex-ruby-sdk/#{Vortex::VERSION}"
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body || {}
+      when 400..499
+        error_msg = response.body.is_a?(Hash) ? response.body['error'] || response.body['message'] : 'Client error'
+        raise VortexError, "Client error (#{response.status}): #{error_msg}"
+      when 500..599
+        error_msg = response.body.is_a?(Hash) ? response.body['error'] || response.body['message'] : 'Server error'
+        raise VortexError, "Server error (#{response.status}): #{error_msg}"
+      else
+        raise VortexError, "Unexpected response (#{response.status}): #{response.body}"
+      end
+    end
+
+    # Base64URL encode (no padding, URL-safe)
+    def base64url_encode(data)
+      Base64.urlsafe_encode64(data).tr('=', '')
+    end
+
+    # Format binary UUID data as string (same as Node.js uuidStringify)
+    def format_uuid(bytes)
+      return nil unless bytes.length == 16
+
+      # Convert to hex and format as UUID
+      hex = bytes.unpack1('H*')
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+  end
+end

data/lib/vortex/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Vortex
+  # Custom error class for Vortex SDK exceptions
+  #
+  # All Vortex-related errors inherit from this class, making it easy
+  # to catch and handle Vortex-specific exceptions.
+  class VortexError < StandardError
+    # @param message [String] Error message
+    # @param cause [Exception, nil] Original exception that caused this error
+    def initialize(message = nil, cause = nil)
+      super(message)
+      @cause = cause
+    end
+
+    # @return [Exception, nil] The original exception that caused this error
+    attr_reader :cause
+  end
+end