vortex-ruby-sdk 1.1.0 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7f6c2f423b5aa8099f7ccce759daaf6dcdd114c6052f1ffb9d9f5072d505916
-  data.tar.gz: 46755e0df9a92907219042a2f2373f6f067aa46f57a1409159cc215ae14823f3
+  metadata.gz: c2f54f415260bef01b6106dc5d32cf274e4b9c45e00cdd89e18ad6dfbc1df177
+  data.tar.gz: 32e1ab2a8a7bc1ee1a3a683d82832a301f4e3403289a64ff8eea4c77410dc104
 SHA512:
-  metadata.gz: 55c8a0671bcad40614d75363ef1b0aaf7b2323f47e9dd717940f59fd026b449c64d79b6c7b9bbed6493199c4c3d1beaac97c3e728409407339bb41363c93b1f9
-  data.tar.gz: fcce54f801ef8115f7567cded83704409fb8436f34056aa296c77210099e0519dd59d8b51f29ff8eb05669acefb088e5cdf4a8a7f2603033f84de1767192b025
+  metadata.gz: 61262106b17af91ce480f7fac66a79a9d4bf2b7b77c264eba92ea07bf7a82967991e3629b59c84f0edbed77054a4f3f9ac661f9a101a4e28f8dd1efc16deafe9
+  data.tar.gz: efc03cda77c4d08a66ef056da5d6c72930ce0003bd6418e2cb145a6a95930e0895f7057d4e864c6c78ca7c5a69ac05dca35d0d6e17ea1aec01e480d795244a32

data/.claude/implementation-guide.md

@@ -0,0 +1,533 @@
+# Vortex Ruby SDK Implementation Guide
+
+**Gem:** `vortex-ruby-sdk`
+**Type:** Base SDK (Core library for Ruby applications)
+**Requires:** Ruby 3.0+
+
+## Prerequisites
+From integration contract you need: API endpoint prefix, scope entity, authentication pattern
+From discovery data you need: Ruby framework (Rails, Sinatra), database ORM, auth pattern
+
+## Key Facts
+- Framework-agnostic Ruby SDK
+- Client-based: instantiate `Vortex::Client` class and call methods
+- Built-in Rails and Sinatra helpers
+- Faraday-based HTTP client
+- Accept invitations requires custom database logic (must implement)
+
+---
+
+## Step 1: Install
+
+Add to `Gemfile`:
+```ruby
+gem 'vortex-ruby-sdk'
+```
+
+Then install:
+```bash
+bundle install
+```
+
+---
+
+## Step 2: Set Environment Variable
+
+Add to `.env`:
+
+```bash
+VORTEX_API_KEY=VRTX.your-api-key-here.secret
+```
+
+**Rails:** Use `config/credentials.yml.enc` or `dotenv-rails` gem
+**Sinatra:** Use `dotenv` gem
+
+**Never commit API key to version control.**
+
+---
+
+## Step 3: Create Vortex Client
+
+### Rails Initializer (`config/initializers/vortex.rb`):
+```ruby
+Rails.application.config.vortex = Vortex::Client.new(
+  Rails.application.credentials.vortex_api_key || ENV['VORTEX_API_KEY']
+)
+```
+
+### Rails Concern (`app/controllers/concerns/vortex_helper.rb`):
+```ruby
+module VortexHelper
+  extend ActiveSupport::Concern
+
+  private
+
+  def vortex_client
+    @vortex_client ||= Vortex::Client.new(
+      Rails.application.credentials.vortex_api_key || ENV['VORTEX_API_KEY']
+    )
+  end
+end
+```
+
+### Sinatra Configuration:
+```ruby
+# app.rb or config.ru
+require 'sinatra/base'
+require 'vortex'
+
+class MyApp < Sinatra::Base
+  configure do
+    set :vortex_client, Vortex::Client.new(ENV['VORTEX_API_KEY'])
+  end
+
+  helpers do
+    def vortex
+      settings.vortex_client
+    end
+  end
+end
+```
+
+---
+
+## Step 4: Extract Authenticated User
+
+### Rails with Devise:
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  private
+
+  def current_vortex_user
+    return nil unless current_user
+
+    {
+      id: current_user.id.to_s,
+      email: current_user.email,
+      admin_scopes: current_user.admin? ? ['autojoin'] : []
+    }
+  end
+
+  def require_authentication!
+    render json: { error: 'Unauthorized' }, status: :unauthorized unless current_user
+  end
+end
+```
+
+### Rails with JWT:
+```ruby
+class ApplicationController < ActionController::API
+  before_action :authenticate_user_from_token!
+
+  private
+
+  def authenticate_user_from_token!
+    token = request.headers['Authorization']&.split(' ')&.last
+    return render json: { error: 'Unauthorized' }, status: :unauthorized unless token
+
+    begin
+      payload = JWT.decode(token, Rails.application.credentials.secret_key_base, true, algorithm: 'HS256')[0]
+      @current_user = User.find(payload['user_id'])
+    rescue JWT::DecodeError, ActiveRecord::RecordNotFound
+      render json: { error: 'Unauthorized' }, status: :unauthorized
+    end
+  end
+
+  def current_vortex_user
+    return nil unless @current_user
+
+    {
+      id: @current_user.id.to_s,
+      email: @current_user.email,
+      admin_scopes: @current_user.admin? ? ['autojoin'] : []
+    }
+  end
+end
+```
+
+### Sinatra:
+```ruby
+# app/helpers/auth_helper.rb
+module AuthHelper
+  def current_user
+    return @current_user if defined?(@current_user)
+
+    # Session-based
+    if session[:user_id]
+      @current_user = User.find(session[:user_id])
+    # JWT-based
+    elsif request.env['HTTP_AUTHORIZATION']
+      token = request.env['HTTP_AUTHORIZATION'].split(' ').last
+      payload = JWT.decode(token, ENV['SECRET_KEY_BASE'], true, algorithm: 'HS256')[0]
+      @current_user = User.find(payload['user_id'])
+    end
+
+    @current_user
+  rescue
+    nil
+  end
+
+  def current_vortex_user
+    return nil unless current_user
+
+    {
+      id: current_user.id.to_s,
+      email: current_user.email,
+      admin_scopes: current_user.admin? ? ['autojoin'] : []
+    }
+  end
+
+  def require_authentication!
+    halt 401, { error: 'Unauthorized' }.to_json unless current_user
+  end
+end
+```
+
+**Adapt to their patterns:**
+- Match their auth mechanism (Devise, JWT, sessions)
+- Match their user structure
+- Match their admin detection logic
+
+---
+
+## Step 5: Implement JWT Generation Endpoint
+
+### Rails (`app/controllers/vortex_controller.rb`):
+```ruby
+class VortexController < ApplicationController
+  before_action :require_authentication!
+  include VortexHelper
+
+  def generate_jwt
+    user = current_vortex_user
+    extra = params.permit(:componentId, :scope, :scopeType).to_h.compact
+
+    jwt = vortex_client.generate_jwt(
+      user: user,
+      attributes: extra.empty? ? nil : extra
+    )
+
+    render json: { jwt: jwt }
+  rescue Vortex::VortexError => e
+    Rails.logger.error("JWT generation error: #{e.message}")
+    render json: { error: 'Internal server error' }, status: :internal_server_error
+  end
+end
+```
+
+### Sinatra:
+```ruby
+require 'sinatra/base'
+require 'json'
+
+class MyApp < Sinatra::Base
+  helpers AuthHelper
+
+  post '/api/vortex/jwt' do
+    require_authentication!
+
+    content_type :json
+
+    begin
+      user = current_vortex_user
+      request_body = JSON.parse(request.body.read) rescue {}
+
+      extra = request_body.slice('componentId', 'scope', 'scopeType').compact
+      extra = nil if extra.empty?
+
+      jwt = vortex.generate_jwt(
+        user: user,
+        attributes: extra
+      )
+
+      { jwt: jwt }.to_json
+    rescue Vortex::VortexError => e
+      logger.error("JWT generation error: #{e.message}")
+      status 500
+      { error: 'Internal server error' }.to_json
+    end
+  end
+end
+```
+
+---
+
+## Step 6: Implement Accept Invitations Endpoint (CRITICAL)
+
+### Rails Routes (`config/routes.rb`):
+```ruby
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :vortex do
+      post 'jwt', to: 'vortex#generate_jwt'
+      get 'invitations', to: 'vortex#get_invitations_by_target'
+      get 'invitations/:invitation_id', to: 'vortex#get_invitation'
+      post 'invitations/accept', to: 'vortex#accept_invitations'
+      delete 'invitations/:invitation_id', to: 'vortex#revoke_invitation'
+      post 'invitations/:invitation_id/reinvite', to: 'vortex#reinvite'
+    end
+  end
+end
+```
+
+### Rails with ActiveRecord:
+```ruby
+class Api::VortexController < ApplicationController
+  before_action :require_authentication!
+  include VortexHelper
+
+  def accept_invitations
+    invitation_ids = params[:invitationIds] || []
+    user = params[:user]
+
+    return render json: { error: 'Missing invitationIds or user' }, status: :bad_request if invitation_ids.empty? || !user
+
+    begin
+      # 1. Mark as accepted in Vortex
+      vortex_client.accept_invitations(invitation_ids, user)
+
+      # 2. CRITICAL - Add to database
+      ActiveRecord::Base.transaction do
+        invitation_ids.each do |invitation_id|
+          invitation = vortex_client.get_invitation(invitation_id)
+
+          (invitation['groups'] || []).each do |group|
+            GroupMembership.find_or_create_by!(
+              user_id: current_user.id,
+              group_type: group['type'],
+              group_id: group['groupId']
+            ) do |membership|
+              membership.role = invitation['role'] || 'member'
+            end
+          end
+        end
+      end
+
+      render json: {
+        success: true,
+        acceptedCount: invitation_ids.length
+      }
+    rescue Vortex::VortexError => e
+      Rails.logger.error("Accept invitations error: #{e.message}")
+      render json: { error: 'Internal server error' }, status: :internal_server_error
+    rescue => e
+      Rails.logger.error("Database error: #{e.message}")
+      render json: { error: 'Internal server error' }, status: :internal_server_error
+    end
+  end
+end
+```
+
+### Sinatra with Sequel:
+```ruby
+post '/api/vortex/invitations/accept' do
+  require_authentication!
+  content_type :json
+
+  request_body = JSON.parse(request.body.read)
+  invitation_ids = request_body['invitationIds'] || []
+  user = request_body['user']
+
+  halt 400, { error: 'Missing invitationIds or user' }.to_json if invitation_ids.empty? || !user
+
+  begin
+    # 1. Mark as accepted in Vortex
+    vortex.accept_invitations(invitation_ids, user)
+
+    # 2. CRITICAL - Add to database
+    DB.transaction do
+      invitation_ids.each do |invitation_id|
+        invitation = vortex.get_invitation(invitation_id)
+
+        (invitation['groups'] || []).each do |group|
+          GroupMembership.insert_conflict(
+            target: [:user_id, :group_type, :group_id],
+            update: { role: invitation['role'] || 'member' }
+          ).insert(
+            user_id: current_user.id,
+            group_type: group['type'],
+            group_id: group['groupId'],
+            role: invitation['role'] || 'member',
+            joined_at: Time.now
+          )
+        end
+      end
+    end
+
+    {
+      success: true,
+      acceptedCount: invitation_ids.length
+    }.to_json
+  rescue Vortex::VortexError => e
+    logger.error("Accept invitations error: #{e.message}")
+    status 500
+    { error: 'Internal server error' }.to_json
+  end
+end
+```
+
+**Critical - Adapt database logic:**
+- Use their actual table/model names (from discovery)
+- Use their actual field names
+- Use their ORM pattern (ActiveRecord, Sequel)
+- Handle duplicate memberships if needed
+
+---
+
+## Step 7: Database Models
+
+### Rails Migration:
+```ruby
+# db/migrate/YYYYMMDDHHMMSS_create_group_memberships.rb
+class CreateGroupMemberships < ActiveRecord::Migration[7.0]
+  def change
+    create_table :group_memberships do |t|
+      t.string :user_id, null: false
+      t.string :group_type, null: false, limit: 100
+      t.string :group_id, null: false
+      t.string :role, default: 'member', limit: 50
+      t.timestamp :joined_at, null: false, default: -> { 'CURRENT_TIMESTAMP' }
+
+      t.index [:user_id, :group_type, :group_id], unique: true, name: 'unique_membership'
+      t.index [:group_type, :group_id], name: 'idx_group'
+      t.index [:user_id], name: 'idx_user'
+    end
+  end
+end
+```
+
+### Rails Model:
+```ruby
+# app/models/group_membership.rb
+class GroupMembership < ApplicationRecord
+  validates :user_id, presence: true
+  validates :group_type, presence: true
+  validates :group_id, presence: true
+  validates :role, presence: true
+
+  validates :user_id, uniqueness: { scope: [:group_type, :group_id] }
+end
+```
+
+### Sequel Migration:
+```ruby
+# db/migrations/001_create_group_memberships.rb
+Sequel.migration do
+  change do
+    create_table(:group_memberships) do
+      primary_key :id
+      String :user_id, null: false
+      String :group_type, size: 100, null: false
+      String :group_id, null: false
+      String :role, size: 50, default: 'member'
+      DateTime :joined_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+
+      index [:user_id, :group_type, :group_id], unique: true, name: :unique_membership
+      index [:group_type, :group_id], name: :idx_group
+      index [:user_id], name: :idx_user
+    end
+  end
+end
+```
+
+---
+
+## Step 8: Build and Test
+
+```bash
+# Run migrations
+rails db:migrate  # Rails
+sequel -m db/migrations $DATABASE_URL  # Sequel
+
+# Start server
+rails server  # Rails
+bundle exec rackup  # Sinatra
+
+# Test JWT endpoint
+curl -X POST http://localhost:3000/api/vortex/jwt \
+  -H "Authorization: Bearer your-auth-token"
+```
+
+Expected response:
+```json
+{
+  "jwt": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+---
+
+## Common Errors
+
+**"LoadError: cannot load such file -- vortex"** → Run `bundle install`
+
+**"VORTEX_API_KEY not set"** → Check `.env` file, credentials, or environment variables
+
+**User not added to database** → Must implement database logic in accept handler (see Step 6)
+
+**"NoMethodError: undefined method `admin?'"** → Implement admin check in User model
+
+**CORS errors** → Add CORS middleware:
+
+**Rails:**
+```ruby
+# Gemfile
+gem 'rack-cors'
+
+# config/initializers/cors.rb
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+  allow do
+    origins 'http://localhost:3000'
+    resource '*', headers: :any, methods: [:get, :post, :delete, :options]
+  end
+end
+```
+
+**Sinatra:**
+```ruby
+require 'sinatra/cross_origin'
+
+class MyApp < Sinatra::Base
+  register Sinatra::CrossOrigin
+
+  configure do
+    enable :cross_origin
+  end
+
+  options '*' do
+    response.headers['Access-Control-Allow-Methods'] = 'GET, POST, DELETE, OPTIONS'
+    response.headers['Access-Control-Allow-Headers'] = 'Content-Type, Authorization'
+    200
+  end
+end
+```
+
+---
+
+## After Implementation Report
+
+List files created/modified:
+- Dependency: Gemfile
+- Client: config/initializers/vortex.rb (or concern)
+- Controller: app/controllers/vortex_controller.rb (or Sinatra routes)
+- Model: app/models/group_membership.rb
+- Migration: db/migrate/XXX_create_group_memberships.rb
+
+Confirm:
+- Vortex gem installed
+- VortexClient instance created
+- JWT endpoint returns valid JWT
+- Accept invitations includes database logic
+- Routes registered at correct prefix
+- Migrations run
+
+## Endpoints Registered
+
+All endpoints at `/api/vortex`:
+- `POST /jwt` - Generate JWT for authenticated user
+- `GET /invitations` - Get invitations by target
+- `GET /invitations/:id` - Get invitation by ID
+- `POST /invitations/accept` - Accept invitations (custom DB logic)
+- `DELETE /invitations/:id` - Revoke invitation
+- `POST /invitations/:id/reinvite` - Resend invitation

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to the Vortex Ruby SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.3] - 2025-01-29
+
+### Added
+- **ACCEPT_USER Type**: New preferred format for accepting invitations with `email`, `phone`, and `name` fields
+- Enhanced `accept_invitations` method to support both new User hash format and legacy target format
+
+### Changed
+- **DEPRECATED**: Legacy target hash format for `accept_invitations` - use User hash instead
+- Internal API calls now always use User format for consistency
+- Added warning messages when legacy target format is used
+
+### Fixed
+- Maintained 100% backward compatibility - existing code using legacy target format continues to work

data/PUBLISHING.md

@@ -76,7 +76,7 @@ Create or update `CHANGELOG.md` with release notes:
 ### Step 4: Install Dependencies and Test
 
 ```bash
-cd packages/vortex-ruby-sdk
+cd sdks/vortex-ruby-sdk
 
 # Install dependencies
 bundle install
@@ -182,29 +182,29 @@ jobs:
 
       - name: Install dependencies
         run: |
-          cd packages/vortex-ruby-sdk
+          cd sdks/vortex-ruby-sdk
           bundle install
 
       - name: Run tests
         run: |
-          cd packages/vortex-ruby-sdk
+          cd sdks/vortex-ruby-sdk
           bundle exec rspec
 
       - name: Run RuboCop
         run: |
-          cd packages/vortex-ruby-sdk
+          cd sdks/vortex-ruby-sdk
           bundle exec rubocop
 
       - name: Build gem
         run: |
-          cd packages/vortex-ruby-sdk
+          cd sdks/vortex-ruby-sdk
           gem build vortex-ruby-sdk.gemspec
 
       - name: Publish to RubyGems
         env:
           GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
         run: |
-          cd packages/vortex-ruby-sdk
+          cd sdks/vortex-ruby-sdk
           gem push *.gem
 ```
 

data/lib/vortex/client.rb

@@ -146,16 +146,84 @@ module Vortex
       raise VortexError, "Failed to revoke invitation: #{e.message}"
     end
 
-    # Accept invitations
+    # Accept invitations using the new User format (preferred)
+    #
+    # Supports three formats:
+    # 1. User hash (preferred): { email: '...', phone: '...', name: '...' }
+    # 2. Target hash (deprecated): { type: 'email', value: '...' }
+    # 3. Array of targets (deprecated): [{ type: 'email', value: '...' }, ...]
     #
     # @param invitation_ids [Array<String>] List of invitation IDs to accept
-    # @param target [Hash] Target hash with :type and :value
+    # @param user_or_target [Hash, Array] User hash with :email/:phone/:name keys, OR legacy target(s)
     # @return [Hash] The accepted invitation result
     # @raise [VortexError] If the request fails
-    def accept_invitations(invitation_ids, target)
+    #
+    # @example New format (preferred)
+    #   user = { email: 'user@example.com', name: 'John Doe' }
+    #   result = client.accept_invitations(['inv-123'], user)
+    #
+    # @example Legacy format (deprecated)
+    #   target = { type: 'email', value: 'user@example.com' }
+    #   result = client.accept_invitations(['inv-123'], target)
+    def accept_invitations(invitation_ids, user_or_target)
+      # Check if it's an array of targets (legacy format with multiple targets)
+      if user_or_target.is_a?(Array)
+        warn '[Vortex SDK] DEPRECATED: Passing an array of targets is deprecated. ' \
+             'Use the User format instead: accept_invitations(invitation_ids, { email: "user@example.com" })'
+
+        raise VortexError, 'No targets provided' if user_or_target.empty?
+
+        last_result = nil
+        last_exception = nil
+
+        user_or_target.each do |target|
+          begin
+            last_result = accept_invitations(invitation_ids, target)
+          rescue => e
+            last_exception = e
+          end
+        end
+
+        raise last_exception if last_exception
+
+        return last_result || {}
+      end
+
+      # Check if it's a legacy target format (has :type and :value keys)
+      is_legacy_target = user_or_target.key?(:type) && user_or_target.key?(:value)
+
+      if is_legacy_target
+        warn '[Vortex SDK] DEPRECATED: Passing a target hash is deprecated. ' \
+             'Use the User format instead: accept_invitations(invitation_ids, { email: "user@example.com" })'
+
+        # Convert target to User format
+        target_type = user_or_target[:type]
+        target_value = user_or_target[:value]
+
+        user = {}
+        case target_type
+        when 'email'
+          user[:email] = target_value
+        when 'sms', 'phoneNumber'
+          user[:phone] = target_value
+        else
+          # For other types, try to use as email
+          user[:email] = target_value
+        end
+
+        # Recursively call with User format
+        return accept_invitations(invitation_ids, user)
+      end
+
+      # New User format
+      user = user_or_target
+
+      # Validate that either email or phone is provided
+      raise VortexError, 'User must have either email or phone' if user[:email].nil? && user[:phone].nil?
+
       body = {
         invitationIds: invitation_ids,
-        target: target
+        user: user.compact # Remove nil values
       }
 
       response = @connection.post('/api/v1/invitations/accept') do |req|
@@ -164,6 +232,8 @@ module Vortex
       end
 
       handle_response(response)
+    rescue VortexError
+      raise
     rescue => e
       raise VortexError, "Failed to accept invitations: #{e.message}"
     end

data/lib/vortex/types.rb

@@ -39,6 +39,19 @@ module Vortex
       createdAt: String    # ISO 8601 timestamp when the group was created
     }.freeze
 
+    # AcceptUser structure for accepting invitations (new format - preferred)
+    # @example
+    #   {
+    #     email: 'user@example.com',
+    #     phone: '+1234567890',      # Optional
+    #     name: 'John Doe'           # Optional
+    #   }
+    ACCEPT_USER = {
+      email: String,  # Optional but either email or phone must be provided
+      phone: String,  # Optional but either email or phone must be provided
+      name: String    # Optional
+    }.freeze
+
     # Invitation structure from API responses
     # @example
     #   {

data/lib/vortex/version.rb

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

data/lib/vortex.rb

@@ -2,6 +2,7 @@
 
 require 'vortex/version'
 require 'vortex/error'
+require 'vortex/types'
 require 'vortex/client'
 
 # Vortex Ruby SDK

data/vortex-ruby-sdk.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.name = 'vortex-ruby-sdk'
   spec.version = Vortex::VERSION
   spec.authors = ['Vortex Software']
-  spec.email = ['support@vortexsoftware.io']
+  spec.email = ['support@vortexsoftware.com']
 
   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.'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vortex-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.3
 platform: ruby
 authors:
 - Vortex Software
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-16 00:00:00.000000000 Z
+date: 2026-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -139,11 +139,13 @@ dependencies:
 description: A Ruby SDK that provides seamless integration with the Vortex invitation
   system, including JWT generation and invitation management.
 email:
-- support@vortexsoftware.io
+- support@vortexsoftware.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/implementation-guide.md"
+- CHANGELOG.md
 - LICENSE
 - PUBLISHING.md
 - README.md