vortex-ruby-sdk 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7f6c2f423b5aa8099f7ccce759daaf6dcdd114c6052f1ffb9d9f5072d505916
-  data.tar.gz: 46755e0df9a92907219042a2f2373f6f067aa46f57a1409159cc215ae14823f3
+  metadata.gz: ef46095579ff2ce432423b52947fe7b09bcbac70a9aeaaa72c28245f79aee801
+  data.tar.gz: b71a185023f2593be2fd5adfa28771eb281de595b8539b023a60448119b29a7b
 SHA512:
-  metadata.gz: 55c8a0671bcad40614d75363ef1b0aaf7b2323f47e9dd717940f59fd026b449c64d79b6c7b9bbed6493199c4c3d1beaac97c3e728409407339bb41363c93b1f9
-  data.tar.gz: fcce54f801ef8115f7567cded83704409fb8436f34056aa296c77210099e0519dd59d8b51f29ff8eb05669acefb088e5cdf4a8a7f2603033f84de1767192b025
+  metadata.gz: f9fee1a62aa03ee7184bf596b13644f48bb3df7a6164eec8bae3be10ebe9f66e21c848410831a09ff99136d01a023aa7bebdbbe9cdf95c7333d7a55a94bd58ed
+  data.tar.gz: 315cdc79b63d0f79563d25e9568df67043245cd8c3d230ef79e322b02c39c7559eb3f5613f0c575b946b01f651397052e1ca8aa76ec51683bec5988a7b2445d2

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,32 @@
+# 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.2.0] - 2026-01-23
+
+### Added
+- **Internal Invitations**: New `'internal'` delivery type for customer-managed invitations
+  - Support for `deliveryTypes: ['internal']`
+  - No email/SMS communication triggered by Vortex
+  - Target value can be any customer-defined identifier
+  - Useful for in-app invitation flows managed by customer's application
+
+### Changed
+- Updated `deliveryTypes` field documentation to include `'internal'` as a valid value
+
+## [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/README.md

@@ -12,6 +12,8 @@ A Ruby SDK for the Vortex invitation system, providing seamless integration with
 - **Same Route Structure**: Ensures React provider compatibility
 - **Comprehensive Testing**: Full test coverage with RSpec
 - **Type Safety**: Clear method signatures and documentation
+- **Multiple Delivery Types**: Support for `email`, `phone`, `share`, and `internal` invitation delivery
+  - `internal` invitations allow for customer-managed, in-app invitation flows with no external communication
 
 ## Installation
 

data/lib/vortex/client.rb

@@ -80,6 +80,16 @@ module Vortex
         expires: expires
       }
 
+      # Add name if present (convert snake_case to camelCase for JWT)
+      if user[:name]
+        payload[:name] = user[:name]
+      end
+
+      # Add avatarUrl if present (convert snake_case to camelCase for JWT)
+      if user[:avatar_url]
+        payload[:avatarUrl] = user[:avatar_url]
+      end
+
       # Add adminScopes if present
       if user[:admin_scopes]
         payload[:adminScopes] = user[:admin_scopes]
@@ -146,16 +156,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 'phone', '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 +242,8 @@ module Vortex
       end
 
       handle_response(response)
+    rescue VortexError
+      raise
     rescue => e
       raise VortexError, "Failed to accept invitations: #{e.message}"
     end
@@ -207,6 +287,86 @@ module Vortex
       raise VortexError, "Failed to reinvite: #{e.message}"
     end
 
+    # Create an invitation from your backend
+    #
+    # This method allows you to create invitations programmatically using your API key,
+    # without requiring a user JWT token. Useful for server-side invitation creation,
+    # such as "People You May Know" flows or admin-initiated invitations.
+    #
+    # Target types:
+    # - 'email': Send an email invitation
+    # - 'phone': Create a phone invitation (short link returned for you to send)
+    # - 'internal': Create an internal invitation for PYMK flows (no email sent)
+    #
+    # @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 source [String, nil] Optional source for analytics (defaults to 'api')
+    # @param template_variables [Hash, nil] Optional template variables for email customization
+    # @param metadata [Hash, nil] Optional metadata passed through to webhooks
+    # @return [Hash] Created invitation with :id, :short_link, :status, :created_at
+    # @raise [VortexError] If the request fails
+    #
+    # @example Create an email invitation
+    #   result = client.create_invitation(
+    #     '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' }]
+    #   )
+    #
+    # @example Create an internal invitation (PYMK flow - no email sent)
+    #   result = client.create_invitation(
+    #     'widget-config-123',
+    #     { type: 'internal', value: 'internal-user-abc' },
+    #     { user_id: 'user-456' },
+    #     nil,
+    #     'pymk'
+    #   )
+    def create_invitation(widget_configuration_id, target, inviter, groups = nil, source = nil, template_variables = nil, metadata = 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?
+
+      # Build request body with camelCase keys for the API
+      body = {
+        widgetConfigurationId: widget_configuration_id,
+        target: target,
+        inviter: {
+          userId: inviter[:user_id],
+          userEmail: inviter[:user_email],
+          name: inviter[:name],
+          avatarUrl: inviter[:avatar_url]
+        }.compact
+      }
+
+      if groups && !groups.empty?
+        body[:groups] = groups.map do |g|
+          {
+            type: g[:type],
+            groupId: g[:group_id],
+            name: g[:name]
+          }
+        end
+      end
+
+      body[:source] = source if source
+      body[:templateVariables] = template_variables if template_variables
+      body[:metadata] = metadata if metadata
+
+      response = @connection.post('/api/v1/invitations') do |req|
+        req.headers['Content-Type'] = 'application/json'
+        req.body = JSON.generate(body)
+      end
+
+      handle_response(response)
+    rescue VortexError
+      raise
+    rescue => e
+      raise VortexError, "Failed to create invitation: #{e.message}"
+    end
+
     private
 
     def build_connection

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
     #   {
@@ -56,7 +69,7 @@ module Vortex
       createdAt: String,
       deactivated: :boolean,
       deliveryCount: Integer,
-      deliveryTypes: Array, # of String
+      deliveryTypes: Array, # of String - valid values: "email", "phone", "share", "internal"
       foreignCreatorId: String,
       invitationType: String,
       modifiedAt: String,

data/lib/vortex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vortex
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
 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.3.0
 platform: ruby
 authors:
 - Vortex Software
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-16 00:00:00.000000000 Z
+date: 2026-01-28 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