vortex-ruby-sdk 1.9.0 → 1.18.0.pre.20260427181620

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8665551bcdf4cf5b7ab05fc5b2dd880b9e1166dd4f544acceb864365e86c8db
-  data.tar.gz: 82d89462684d03e6b26769f20b8a44ba3f4fe71cf729ce78f54268f070fa36df
+  metadata.gz: 0c1d76a55b4ddd17c08d1dcbd45a393e9bed146e1e76dcc0526bcd80fa57710e
+  data.tar.gz: 6ccf49c2301554141b1591e674147b58f9841dd5471106d057611c5731685fab
 SHA512:
-  metadata.gz: 32a6d0a546f91c5165f43af6ac0ed995386b92d267006eb6793b865676fe0bcfe6631e748294ecf589253d7621df492aff7b442881266f7906dc6833b78be63e
-  data.tar.gz: 39253da9f792aacc194e619eb4ab00104d15ce7901ca5345a82e1681f3aa2d0e0bb268c6b832fad3537736641378f57fe3ee2ae31a5af8b2157ea5a8a2b02c17
+  metadata.gz: 98cf940bc167c1c6a5d81875829a6281a15bd570ff17bff5430fce7f881d761840979507533e8926deddb4bb8bae970b5d80a2a0b9c80bc61d42efa4e51350d3
+  data.tar.gz: 53de4c4f581d6fc5a251887f4159a013f712da9e5f86a13cd442c00eef8deaaaa7af1e206374bb3163819ada40d5cb9509d99a6d4727b102a8f728c7da15b878

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