vortex-ruby-sdk 1.8.4 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 677efb240644fe95c61d07a325952a6d2f8c6851eb14d59d17178d2c74881629
-  data.tar.gz: 83ad91fa108419346c2b6a707b62316573fdc5137d213a141840a599eca02dbe
+  metadata.gz: 2fa76d2aa711c84370eb93e563946ee45c78c12d2a5c54d6b4de13ebb49f3c6a
+  data.tar.gz: 74e291d07ca213da127b5cb35e8964e63664d101ffff8fe06aa3e586b8efc42f
 SHA512:
-  metadata.gz: 324e85fc0660f7b952932a163ad10df4ae17f8f81dafd7c8eb6d8de70e771146474c0cc147d7643ae689f9629eafba0b9884c6f022b3091fb4147a3a1dc2f1eb
-  data.tar.gz: 2d780b17c5697ffcb0532bfcabce7756bd80a672b74417b5194e0c3e9089de31c0bc8c03977b4a0fdce0e416af1bb2a85868b2aa6050d2bf6a9fe9fbf7aa45e5
+  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
@@ -262,6 +294,50 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
+## Webhooks
+
+The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.
+
+```ruby
+require 'vortex'
+
+webhooks = Vortex::Webhooks.new(secret: ENV['VORTEX_WEBHOOK_SECRET'])
+
+# In your HTTP handler (Rails example):
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    payload = request.body.read
+    signature = request.headers['X-Vortex-Signature']
+
+    begin
+      event = webhooks.construct_event(payload, signature)
+    rescue Vortex::WebhookSignatureError
+      head :bad_request
+      return
+    end
+
+    case event
+    when Vortex::WebhookEvent
+      Rails.logger.info "Webhook event: #{event.type}"
+    when Vortex::AnalyticsEvent
+      Rails.logger.info "Analytics event: #{event.name}"
+    end
+
+    head :ok
+  end
+end
+```
+
+### Event Type Constants
+
+```ruby
+if event.type == Vortex::WebhookEventTypes::INVITATION_ACCEPTED
+  # Handle invitation accepted
+end
+```
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/vortexsoftware/vortex-ruby-sdk.
 
 ## License

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):"