vortex-ruby-sdk 1.9.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8665551bcdf4cf5b7ab05fc5b2dd880b9e1166dd4f544acceb864365e86c8db
-  data.tar.gz: 82d89462684d03e6b26769f20b8a44ba3f4fe71cf729ce78f54268f070fa36df
+  metadata.gz: 2fa76d2aa711c84370eb93e563946ee45c78c12d2a5c54d6b4de13ebb49f3c6a
+  data.tar.gz: 74e291d07ca213da127b5cb35e8964e63664d101ffff8fe06aa3e586b8efc42f
 SHA512:
-  metadata.gz: 32a6d0a546f91c5165f43af6ac0ed995386b92d267006eb6793b865676fe0bcfe6631e748294ecf589253d7621df492aff7b442881266f7906dc6833b78be63e
-  data.tar.gz: 39253da9f792aacc194e619eb4ab00104d15ce7901ca5345a82e1681f3aa2d0e0bb268c6b832fad3537736641378f57fe3ee2ae31a5af8b2157ea5a8a2b02c17
+  metadata.gz: ef4b13b91543a141f041d2bfcc812b48e55a63998a7d8da7e445107daec73bb10e3d047532dfce015ed51a8160ddf5df28f78ca46285311fefa3a6f692ad40af
+  data.tar.gz: 9a8723995e0cdfae388688385544242e30c2c280192938ac59aebfa724f5ebf0f3508ea1eb44765c92d8ec936885bdef30ee0b828fab6ecc4c4746b29a19860f

data/.claude/implementation-guide.md

@@ -5,10 +5,12 @@
 **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
@@ -20,11 +22,13 @@ From discovery data you need: Ruby framework (Rails, Sinatra), database ORM, aut
 ## Step 1: Install
 
 Add to `Gemfile`:
+
 ```ruby
 gem 'vortex-ruby-sdk'
 ```
 
 Then install:
+
 ```bash
 bundle install
 ```
@@ -49,6 +53,7 @@ VORTEX_API_KEY=VRTX.your-api-key-here.secret
 ## 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']
@@ -56,6 +61,7 @@ Rails.application.config.vortex = Vortex::Client.new(
 ```
 
 ### Rails Concern (`app/controllers/concerns/vortex_helper.rb`):
+
 ```ruby
 module VortexHelper
   extend ActiveSupport::Concern
@@ -71,6 +77,7 @@ end
 ```
 
 ### Sinatra Configuration:
+
 ```ruby
 # app.rb or config.ru
 require 'sinatra/base'
@@ -94,6 +101,7 @@ end
 ## Step 4: Extract Authenticated User
 
 ### Rails with Devise:
+
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::API
@@ -116,6 +124,7 @@ end
 ```
 
 ### Rails with JWT:
+
 ```ruby
 class ApplicationController < ActionController::API
   before_action :authenticate_user_from_token!
@@ -147,6 +156,7 @@ end
 ```
 
 ### Sinatra:
+
 ```ruby
 # app/helpers/auth_helper.rb
 module AuthHelper
@@ -185,6 +195,7 @@ end
 ```
 
 **Adapt to their patterns:**
+
 - Match their auth mechanism (Devise, JWT, sessions)
 - Match their user structure
 - Match their admin detection logic
@@ -194,6 +205,7 @@ end
 ## Step 5: Implement JWT Generation Endpoint
 
 ### Rails (`app/controllers/vortex_controller.rb`):
+
 ```ruby
 class VortexController < ApplicationController
   before_action :require_authentication!
@@ -217,6 +229,7 @@ end
 ```
 
 ### Sinatra:
+
 ```ruby
 require 'sinatra/base'
 require 'json'
@@ -256,6 +269,7 @@ end
 ## Step 6: Implement Accept Invitations Endpoint (CRITICAL)
 
 ### Rails Routes (`config/routes.rb`):
+
 ```ruby
 Rails.application.routes.draw do
   namespace :api do
@@ -272,6 +286,7 @@ end
 ```
 
 ### Rails with ActiveRecord:
+
 ```ruby
 class Api::VortexController < ApplicationController
   before_action :require_authentication!
@@ -292,11 +307,11 @@ class Api::VortexController < ApplicationController
         invitation_ids.each do |invitation_id|
           invitation = vortex_client.get_invitation(invitation_id)
 
-          (invitation['groups'] || []).each do |group|
-            GroupMembership.find_or_create_by!(
+          (invitation["groups"] || []).each do |scope|
+            ScopeMembership.find_or_create_by!(
               user_id: current_user.id,
-              group_type: group['type'],
-              group_id: group['groupId']
+              scope_type: scope['type'],
+              scope_id: scope['groupId']
             ) do |membership|
               membership.role = invitation['role'] || 'member'
             end
@@ -320,6 +335,7 @@ end
 ```
 
 ### Sinatra with Sequel:
+
 ```ruby
 post '/api/vortex/invitations/accept' do
   require_authentication!
@@ -340,14 +356,14 @@ post '/api/vortex/invitations/accept' 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],
+        (invitation["groups"] || []).each do |scope|
+          ScopeMembership.insert_conflict(
+            target: [:user_id, :scope_type, :scope_id],
             update: { role: invitation['role'] || 'member' }
           ).insert(
             user_id: current_user.id,
-            group_type: group['type'],
-            group_id: group['groupId'],
+            scope_type: scope['type'],
+            scope_id: scope['groupId'],
             role: invitation['role'] || 'member',
             joined_at: Time.now
           )
@@ -368,6 +384,7 @@ end
 ```
 
 **Critical - Adapt database logic:**
+
 - Use their actual table/model names (from discovery)
 - Use their actual field names
 - Use their ORM pattern (ActiveRecord, Sequel)
@@ -378,19 +395,20 @@ end
 ## Step 7: Database Models
 
 ### Rails Migration:
+
 ```ruby
-# db/migrate/YYYYMMDDHHMMSS_create_group_memberships.rb
-class CreateGroupMemberships < ActiveRecord::Migration[7.0]
+# db/migrate/YYYYMMDDHHMMSS_create_scope_memberships.rb
+class CreateScopeMemberships < ActiveRecord::Migration[7.0]
   def change
-    create_table :group_memberships do |t|
+    create_table :scope_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 :scope_type, null: false, limit: 100
+      t.string :scope_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, :scope_type, :scope_id], unique: true, name: 'unique_membership'
+      t.index [:scope_type, :scope_id], name: 'idx_scope'
       t.index [:user_id], name: 'idx_user'
     end
   end
@@ -398,33 +416,35 @@ end
 ```
 
 ### Rails Model:
+
 ```ruby
-# app/models/group_membership.rb
-class GroupMembership < ApplicationRecord
+# app/models/scope_membership.rb
+class ScopeMembership < ApplicationRecord
   validates :user_id, presence: true
-  validates :group_type, presence: true
-  validates :group_id, presence: true
+  validates :scope_type, presence: true
+  validates :scope_id, presence: true
   validates :role, presence: true
 
-  validates :user_id, uniqueness: { scope: [:group_type, :group_id] }
+  validates :user_id, uniqueness: { scope: [:scope_type, :scope_id] }
 end
 ```
 
 ### Sequel Migration:
+
 ```ruby
-# db/migrations/001_create_group_memberships.rb
+# db/migrations/001_create_scope_memberships.rb
 Sequel.migration do
   change do
-    create_table(:group_memberships) do
+    create_table(:scope_memberships) do
       primary_key :id
       String :user_id, null: false
-      String :group_type, size: 100, null: false
-      String :group_id, null: false
+      String :scope_type, size: 100, null: false
+      String :scope_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, :scope_type, :scope_id], unique: true, name: :unique_membership
+      index [:scope_type, :scope_id], name: :idx_scope
       index [:user_id], name: :idx_user
     end
   end
@@ -450,6 +470,7 @@ curl -X POST http://localhost:3000/api/vortex/jwt \
 ```
 
 Expected response:
+
 ```json
 {
   "jwt": "eyJhbGciOiJIUzI1NiIs..."
@@ -471,6 +492,7 @@ Expected response:
 **CORS errors** → Add CORS middleware:
 
 **Rails:**
+
 ```ruby
 # Gemfile
 gem 'rack-cors'
@@ -485,6 +507,7 @@ end
 ```
 
 **Sinatra:**
+
 ```ruby
 require 'sinatra/cross_origin'
 
@@ -508,13 +531,15 @@ 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
+- Model: app/models/scope_membership.rb
+- Migration: db/migrate/XXX_create_scope_memberships.rb
 
 Confirm:
+
 - Vortex gem installed
 - VortexClient instance created
 - JWT endpoint returns valid JWT
@@ -525,6 +550,7 @@ Confirm:
 ## 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

data/README.md

@@ -61,8 +61,37 @@ invitations = client.get_invitations_by_target('email', 'user@example.com')
 # Accept an invitation
 client.accept_invitation('inv-123', { email: 'user@example.com' })
 
-# Get invitations by group
-group_invitations = client.get_invitations_by_group('team', 'team1')
+# Accept with new vs existing user tracking
+# is_existing: true if user was already registered, false if new signup
+client.accept_invitation('inv-123', {
+  email: 'user@example.com',
+  is_existing: false  # New user signup
+})
+
+# Get invitations by scope
+scope_invitations = client.get_invitations_by_scope('team', 'team1')
+```
+
+## Token Generation (for Widgets)
+
+Use `generate_token` for widget authentication. This method generates a signed JWT token that can be passed to Vortex widgets via the `token` prop.
+
+```ruby
+# Sign just the user (minimum for secure invitation attribution)
+token = client.generate_token({ user: { id: 'user-123' } })
+
+# Sign full payload with component, scope, and variables
+token = client.generate_token({
+  component: 'widget-abc',
+  user: { id: 'user-123', name: 'Peter', email: 'peter@example.com' },
+  scope: 'workspace_456',
+  vars: { company_name: 'Acme' }
+})
+
+# Custom expiration (default is 5 minutes)
+payload = { user: { id: 'user-123' } }
+token = client.generate_token(payload, { expires_in: '1h' })  # Supports "5m", "1h", "24h", "7d"
+token = client.generate_token(payload, { expires_in: 3600 })  # Or seconds as integer
 ```
 
 ## Rails Integration
@@ -116,8 +145,8 @@ Rails.application.routes.draw do
     get 'invitations/:invitation_id', action: 'get_invitation'
     delete 'invitations/:invitation_id', action: 'revoke_invitation'
     post 'invitations/accept', action: 'accept_invitations'
-    get 'invitations/by-group/:group_type/:group_id', action: 'get_invitations_by_group'
-    delete 'invitations/by-group/:group_type/:group_id', action: 'delete_invitations_by_group'
+    get 'invitations/by-scope/:scope_type/:scope', action: 'get_invitations_by_scope'
+    delete 'invitations/by-scope/:scope_type/:scope', action: 'delete_invitations_by_scope'
     post 'invitations/:invitation_id/reinvite', action: 'reinvite'
   end
 end
@@ -171,8 +200,8 @@ All methods match the functionality of other Vortex SDKs:
 - `get_invitation(invitation_id)` - Get specific invitation
 - `revoke_invitation(invitation_id)` - Revoke invitation
 - `accept_invitation(invitation_id, user)` - Accept an invitation
-- `get_invitations_by_group(group_type, group_id)` - Get group invitations
-- `delete_invitations_by_group(group_type, group_id)` - Delete group invitations
+- `get_invitations_by_scope(scope_type, scope)` - Get scope invitations
+- `delete_invitations_by_scope(scope_type, scope)` - Delete scope invitations
 - `reinvite(invitation_id)` - Reinvite user
 - `sync_internal_invitation(creator_id, target_value, action, component_id)` - Sync internal invitation action
 
@@ -182,12 +211,12 @@ The SDK provides these routes (same as other SDKs for React provider compatibili
 
 - `POST /api/vortex/jwt`
 - `GET /api/vortex/invitations?targetType=email&targetValue=user@example.com`
-- `GET /api/vortex/invitations/:id`
-- `DELETE /api/vortex/invitations/:id`
+- `GET /api/vortex/invitations/:invitation_id`
+- `DELETE /api/vortex/invitations/:invitation_id`
 - `POST /api/vortex/invitations/accept`
-- `GET /api/vortex/invitations/by-group/:type/:id`
-- `DELETE /api/vortex/invitations/by-group/:type/:id`
-- `POST /api/vortex/invitations/:id/reinvite`
+- `GET /api/vortex/invitations/by-scope/:scope_type/:scope`
+- `DELETE /api/vortex/invitations/by-scope/:scope_type/:scope`
+- `POST /api/vortex/invitations/:invitation_id/reinvite`
 - `POST /api/vortex/invitations/sync-internal-invitation`
 
 ## Sync Internal Invitation
@@ -208,16 +237,19 @@ puts "Invitation IDs: #{result['invitationIds']}"
 ```
 
 **Parameters:**
+
 - `creator_id` (String) — The inviter's user ID in your system
 - `target_value` (String) — The invitee's user ID in your system
 - `action` ("accepted" | "declined") — The invitation decision
 - `component_id` (String) — The widget component UUID
 
 **Response:**
+
 - `processed` (Integer) — Count of invitations processed
 - `invitationIds` (Array<String>) — IDs of processed invitations
 
 **Use cases:**
+
 - You handle invitation delivery through your own in-app notifications or UI
 - Users accept/decline invitations within your application
 - You need to keep Vortex updated with the invitation status

data/examples/basic_usage.rb

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

data/examples/rails_app.rb

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

data/examples/sinatra_app.rb

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

data/lib/vortex/client.rb

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

data/lib/vortex/rails.rb

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

data/lib/vortex/sinatra.rb

@@ -142,8 +142,8 @@ module Vortex
       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
+      # GET /api/vortex/invitations/by-scope/:scope_type/:scope
+      app.get '/api/vortex/invitations/by-scope/:scope_type/:scope' do
         with_vortex_error_handling do
           user = authenticate_vortex_user
           return render_unauthorized('Authentication required') unless user
@@ -152,17 +152,17 @@ module Vortex
             return render_forbidden('Not authorized to get group invitations')
           end
 
-          group_type = params['group_type']
-          group_id = params['group_id']
+          scope_type = params['scope_type']
+          scope = params['scope']
 
-          invitations = vortex_client.get_invitations_by_group(group_type, group_id)
+          invitations = vortex_client.get_invitations_by_scope(scope_type, scope)
           render_json({ invitations: invitations })
         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
+      # DELETE /api/vortex/invitations/by-scope/:scope_type/:scope
+      app.delete '/api/vortex/invitations/by-scope/:scope_type/:scope' do
         with_vortex_error_handling do
           user = authenticate_vortex_user
           return render_unauthorized('Authentication required') unless user
@@ -171,10 +171,10 @@ module Vortex
             return render_forbidden('Not authorized to delete group invitations')
           end
 
-          group_type = params['group_type']
-          group_id = params['group_id']
+          scope_type = params['scope_type']
+          scope = params['scope']
 
-          vortex_client.delete_invitations_by_group(group_type, group_id)
+          vortex_client.delete_invitations_by_scope(scope_type, scope)
           render_json({ success: true })
         end
       end

data/lib/vortex/types.rb

@@ -19,7 +19,7 @@ module Vortex
       name: String       # Required: Group name
     }.freeze
 
-    # InvitationGroup structure from API responses
+    # InvitationScope structure from API responses
     # This matches the MemberGroups table structure from the API
     # @example
     #   {
@@ -44,12 +44,14 @@ module Vortex
     #   {
     #     email: 'user@example.com',
     #     phone: '+1234567890',      # Optional
-    #     name: 'John Doe'           # Optional
+    #     name: 'John Doe',          # Optional
+    #     is_existing: true          # Optional - whether user was already registered
     #   }
     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
+      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
+      is_existing: 'Boolean (true/false/nil)' # Optional - true if existing user, false if new signup, nil if unknown
     }.freeze
 
     # Invitation structure from API responses

data/lib/vortex/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vortex-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.15.0
 platform: ruby
 authors:
 - Vortex Software
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-25 00:00:00.000000000 Z
+date: 2026-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday