vortex-ruby-sdk 1.9.0 → 1.18.0

data/README.md

@@ -1,313 +1,782 @@
-# Vortex Ruby SDK
+# vortex-ruby-sdk
 
-A Ruby SDK for the Vortex invitation system, providing seamless integration with the same functionality and API compatibility as other Vortex SDKs (Node.js, Python, Java, Go).
+<!-- AUTO-GENERATED FROM SDK MANIFEST — DO NOT EDIT DIRECTLY -->
 
-## Features
+![Version](https://img.shields.io/badge/version-1.18.0-blue)
+![Language](https://img.shields.io/badge/language-ruby-green)
 
-- **JWT Generation**: Identical algorithm to other SDKs for complete compatibility
-- **Simplified JWT Format**: New streamlined payload with `userEmail` and `adminScopes`
-- **Backward Compatible**: Legacy JWT format still supported
-- **Complete API Coverage**: All invitation management operations
-- **Framework Integration**: Built-in Rails and Sinatra helpers
-- **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
+**Invitation infrastructure for modern apps**
 
-## Installation
+Vortex handles the complete invitation lifecycle — sending invites via email/SMS/share links, tracking clicks and conversions, managing referral programs, and optimizing your invitation flows with A/B testing.
+[Learn more about Vortex →](https://tryvortex.com)
+
+## Why This SDK?
+
+This backend SDK securely signs user data for Vortex components. Your API key stays on your server, while the signed token is passed to the frontend where Vortex components render the invitation UI.
+
+- Keep your API key secure — it never touches the browser
+- Sign user identity for attribution — know who sent each invitation
+- Control what data components can access via scoped tokens
+- Verify webhook signatures for secure event handling
+
+## How It Works
+
+Vortex uses a split architecture: your backend signs tokens with the SDK, and your frontend renders components that use those tokens to securely interact with Vortex.
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Your Server   │     │  User Browser   │     │  Vortex Cloud   │
+│    (this SDK)   │     │   (component)   │     │                 │
+└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
+         │                       │                       │
+         │  1. generate_token    │                       │
+         │◄──────────────────────│                       │
+         │                       │                       │
+         │  2. Return token      │                       │
+         │──────────────────────►│                       │
+         │                       │                       │
+         │                       │  3. Component calls   │
+         │                       │     API with token    │
+         │                       │──────────────────────►│
+         │                       │                       │
+         │                       │  4. Render UI,        │
+         │                       │     send invitations  │
+         │                       │◄──────────────────────│
+         │                       │                       │
+```
+
+### Integration Flow
 
-Add this line to your application's Gemfile:
+**1. Install the backend SDK** `[backend]`
+
+Add this SDK to your Ruby project
 
 ```ruby
 gem 'vortex-ruby-sdk'
 ```
 
-And then execute:
+**2. Initialize the client** `[backend]`
 
-```bash
-bundle install
+Create a Vortex client with your API key (keep this on the server!)
+
+```ruby
+require 'vortex'
+
+client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
 ```
 
-Or install it yourself as:
+**3. Generate a token for the current user** `[backend]`
 
-```bash
-gem install vortex-ruby-sdk
+When a user loads a page with a Vortex component, generate a signed token on your server
+
+```ruby
+token = client.generate_token(user: { id: current_user.id })
+```
+
+**4. Pass the token to your frontend** `[backend]`
+
+Include the token in your page response or API response
+
+```ruby
+render json: { vortex_token: token }
+```
+
+**5. Render a Vortex component with the token** `[frontend]`
+
+Use the React/Angular/Web Component with the token
+
+```ruby
+import { VortexInvite } from "@teamvortexsoftware/vortex-react";
+
+<VortexInvite token={vortexToken} />
 ```
 
-## Basic Usage
+**6. Vortex handles the rest** `[vortex]`
+
+The component securely communicates with Vortex servers, displays the invitation UI, sends emails/SMS, tracks conversions, and reports analytics
+
+### Security Model
+
+> ⚠️ **Important:** Your Vortex API key is a secret that grants full access to your account. It must never be exposed to browsers or client-side code.
+
+By signing tokens on your server, you:
+
+- Keep your API key secret (it never leaves your server)
+- Control exactly what user data is shared with components
+- Ensure invitations are attributed to real, authenticated users
+- Prevent abuse — users can only send invitations as themselves
+
+#### When Signing is Optional
+
+Token signing is controlled by your component configuration in the Vortex dashboard. If "Require Secure Token" is enabled, requests without a valid token will be rejected. If disabled (e.g., for public referral programs), components work without backend signing.
+
+---
+
+## Quick Start
+
+Generate a secure token for Vortex components
 
 ```ruby
 require 'vortex'
 
-# Initialize the client
 client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
 
-# Create a user object
-user = {
-  id: 'user-123',
-  email: 'user@example.com',
-  user_name: 'Jane Doe',                                    # Optional: user's display name
-  user_avatar_url: 'https://example.com/avatars/jane.jpg',  # Optional: user's avatar URL
-  admin_scopes: ['autojoin']                                # Optional: grants autojoin admin privileges
-}
+# Generate a token for the current user
+token = client.generate_token(user: { id: 'user-123', email: 'user@example.com' })
 
-# Generate JWT
-jwt = client.generate_jwt(user: user)
+# Pass the token to your frontend component
 
-# Get invitations by target
-invitations = client.get_invitations_by_target('email', 'user@example.com')
+```
 
-# Accept an invitation
-client.accept_invitation('inv-123', { email: 'user@example.com' })
+## Installation
 
-# Get invitations by group
-group_invitations = client.get_invitations_by_group('team', 'team1')
+```bash
+gem install vortex-ruby-sdk
 ```
 
-## Rails Integration
+## Initialization
 
-Create a controller with Vortex routes:
+```ruby
+client = Vortex::Client.new(ENV['VORTEX_API_KEY'])
+```
+
+### Environment Variables
+
+| Variable         | Required | Description         |
+| ---------------- | -------- | ------------------- |
+| `VORTEX_API_KEY` | ✓        | Your Vortex API key |
+
+## Core Methods
+
+These are the methods you'll use most often.
+
+### `generate_token()`
+
+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.
+
+**Signature:**
 
 ```ruby
-# app/controllers/vortex_controller.rb
-class VortexController < ApplicationController
-  include Vortex::Rails::Controller
-
-  private
-
-  def authenticate_vortex_user
-    # Return user data hash or nil
-    admin_scopes = []
-    admin_scopes << 'autojoin' if current_user.admin?
-
-    {
-      id: current_user.id,
-      email: current_user.email,
-      admin_scopes: admin_scopes
-    }
-  end
+generate_token(payload, options = nil)
+```
 
-  def authorize_vortex_operation(operation, user)
-    # Implement your authorization logic
-    case operation
-    when 'JWT', 'GET_INVITATIONS'
-      true
-    when 'REVOKE_INVITATION'
-      user[:admin_scopes]&.include?('autojoin')
-    else
-      false
-    end
-  end
+**Parameters:**
 
-  def vortex_client
-    @vortex_client ||= Vortex::Client.new(Rails.application.credentials.vortex_api_key)
-  end
-end
+| Name      | Type   | Required | Description                                       |
+| --------- | ------ | -------- | ------------------------------------------------- |
+| `payload` | `Hash` | ✓        | Data to sign (user, component, scope, vars, etc.) |
+| `options` | `Hash` | ✓        | Optional configuration                            |
+
+**Returns:** `String`
+— Signed JWT token
+
+**Example:**
+
+```ruby
+#   token = client.generate_token({ user: { id: 'user-123' } })
+    #
+    #   token = client.generate_token({
+    #     component: 'widget-abc',
+    #     user: { id: 'user-123', name: 'Peter', email: 'peter@example.com' },
+    #     scope: 'workspace_456',
+    #     vars: { company_name: 'Acme' }
+    #   })
+    #
+    #   token = client.generate_token(payload, { expires_in: '1h' })
+    #   token = client.generate_token(payload, { expires_in: 3600 }) # seconds
 ```
 
-Add routes to `config/routes.rb`:
+_Added in v0.8.0_
+
+---
+
+### `get_invitation()`
+
+Get a specific invitation by ID
+
+**Signature:**
 
 ```ruby
-Rails.application.routes.draw do
-  scope '/api/vortex', controller: 'vortex' do
-    post 'jwt', action: 'generate_jwt'
-    get 'invitations', action: 'get_invitations_by_target'
-    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'
-    post 'invitations/:invitation_id/reinvite', action: 'reinvite'
-  end
-end
+get_invitation(invitation_id)
 ```
 
-## Sinatra Integration
+**Parameters:**
+
+| Name            | Type     | Required | Description       |
+| --------------- | -------- | -------- | ----------------- |
+| `invitation_id` | `String` | ✓        | The invitation ID |
+
+**Returns:** `String`
+— The invitation data
+
+_Added in v0.1.0_
+
+---
+
+### `accept_invitation()`
+
+Accept a single invitation (recommended method) This is the recommended method for accepting invitations.
+
+**Signature:**
 
 ```ruby
-require 'sinatra/base'
-require 'vortex/sinatra'
+accept_invitation(invitation_id, user)
+```
 
-class MyApp < Sinatra::Base
-  register Vortex::Sinatra
+**Parameters:**
 
-  configure do
-    set :vortex_api_key, ENV['VORTEX_API_KEY']
-  end
+| Name            | Type     | Required | Description                         |
+| --------------- | -------- | -------- | ----------------------------------- |
+| `invitation_id` | `String` | ✓        | Single invitation ID to accept      |
+| `user`          | `Hash`   | ✓        | User hash with :email and/or :phone |
 
-  def authenticate_vortex_user
-    # Implement authentication logic
-    user_id = request.env['HTTP_X_USER_ID']
-    return nil unless user_id
+**Returns:** `String`
+— The accepted invitation result
 
-    {
-      id: user_id,
-      email: 'user@example.com',
-      admin_scopes: []  # Optional
-    }
-  end
+**Example:**
 
-  def authorize_vortex_operation(operation, user)
-    # Implement authorization logic
-    user != nil
-  end
-end
+```ruby
+#   user = { email: 'user@example.com', name: 'John Doe' }
+    #   result = client.accept_invitation('inv-123', user)
 ```
 
-## API Methods
+_Added in v0.6.0_
 
-All methods match the functionality of other Vortex SDKs:
+---
 
-### JWT Generation
+## All Methods
 
-- `generate_jwt(user:, extra: nil)` - Generate JWT token
-  - `user`: Hash with `:id`, `:email`, and optional `:admin_scopes` array
-  - `extra`: Optional hash with additional properties to include in JWT payload
+<details>
+<summary>Click to expand full method reference</summary>
 
-### Invitation Management
+### `get_invitations_by_target()`
 
-- `get_invitations_by_target(target_type, target_value)` - Get invitations by target
-- `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
-- `reinvite(invitation_id)` - Reinvite user
-- `sync_internal_invitation(creator_id, target_value, action, component_id)` - Sync internal invitation action
+Get invitations by target
 
-## Route Structure
+**Signature:**
+
+```ruby
+get_invitations_by_target(target_type, target_value)
+```
+
+**Parameters:**
 
-The SDK provides these routes (same as other SDKs for React provider compatibility):
+| Name           | Type     | Required | Description                                   |
+| -------------- | -------- | -------- | --------------------------------------------- |
+| `target_type`  | `String` | ✓        | Type of target (email, sms)                   |
+| `target_value` | `String` | ✓        | Value of target (email address, phone number) |
 
-- `POST /api/vortex/jwt`
-- `GET /api/vortex/invitations?targetType=email&targetValue=user@example.com`
-- `GET /api/vortex/invitations/:id`
-- `DELETE /api/vortex/invitations/: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`
-- `POST /api/vortex/invitations/sync-internal-invitation`
+**Returns:** `String`
+— List of invitations
 
-## Sync Internal Invitation
+_Added in v0.1.0_
 
-If you're using `internal` delivery type invitations and managing the invitation flow within your own application, you can sync invitation decisions back to Vortex when users accept or decline invitations in your system.
+---
+
+### `revoke_invitation()`
+
+Revoke (delete) an invitation
+
+**Signature:**
 
 ```ruby
-# Sync an internal invitation action
-result = client.sync_internal_invitation(
-  'user-123',           # creator_id - The inviter's user ID in your system
-  'user-456',           # target_value - The invitee's user ID in your system
-  'accepted',           # action - "accepted" or "declined"
-  'component-uuid'      # component_id - The widget component UUID
-)
-
-puts "Processed: #{result['processed']}"
-puts "Invitation IDs: #{result['invitationIds']}"
+revoke_invitation(invitation_id)
 ```
 
 **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
+| Name            | Type     | Required | Description                 |
+| --------------- | -------- | -------- | --------------------------- |
+| `invitation_id` | `String` | ✓        | The invitation ID to revoke |
+
+**Returns:** `String`
+— Success response
 
-**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
+_Added in v0.1.0_
 
-## JWT Payload Structure
+---
 
-The SDK generates JWTs with the following payload structure:
+### `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: '...' }, ...]
+
+**Signature:**
 
 ```ruby
-{
-  userId: 'user-123',
-  userEmail: 'user@example.com',
-  adminScopes: ['autojoin'],  # Full array included if admin_scopes provided
-  expires: 1234567890
-}
+accept_invitations(invitation_ids, user_or_target)
 ```
 
-Additional properties from the `extra` parameter are merged into the payload.
+**Parameters:**
 
-## Error Handling
+| Name             | Type            | Required | Description                                                  |
+| ---------------- | --------------- | -------- | ------------------------------------------------------------ |
+| `invitation_ids` | `Array<String>` | ✓        | List of invitation IDs to accept                             |
+| `user_or_target` | `Hash, Array`   | ✓        | User hash with :email/:phone/:name keys, OR legacy target(s) |
 
-All methods raise `Vortex::VortexError` on failures:
+**Returns:** `String`
+— The accepted invitation result
+
+**Example:**
 
 ```ruby
-begin
-  jwt = client.generate_jwt(
-    user: {
-      id: 'user-123',
-      email: 'user@example.com'
-    }
-  )
-rescue Vortex::VortexError => e
-  logger.error "Vortex error: #{e.message}"
-end
+#   user = { email: 'user@example.com', name: 'John Doe' }
+    #   result = client.accept_invitations(['inv-123'], user)
+    #
+    #   target = { type: 'email', value: 'user@example.com' }
+    #   result = client.accept_invitations(['inv-123'], target)
 ```
 
-## Development
+_Added in v0.1.0_
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+---
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+### `get_invitations_by_scope()`
 
-## Contributing
+Get invitations by group
 
-## Webhooks
+**Signature:**
+
+```ruby
+get_invitations_by_scope(scope_type, scope)
+```
+
+**Parameters:**
+
+| Name         | Type     | Required | Description    |
+| ------------ | -------- | -------- | -------------- |
+| `scope_type` | `String` | ✓        | The group type |
+| `scope`      | `String` | ✓        | The group ID   |
+
+**Returns:** `String`
+— List of invitations for the group
+
+_Added in v0.4.0_
 
-The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.
+---
+
+### `delete_invitations_by_scope()`
+
+Delete invitations by group
+
+**Signature:**
 
 ```ruby
-require 'vortex'
+delete_invitations_by_scope(scope_type, scope)
+```
+
+**Parameters:**
+
+| Name         | Type     | Required | Description    |
+| ------------ | -------- | -------- | -------------- |
+| `scope_type` | `String` | ✓        | The group type |
+| `scope`      | `String` | ✓        | The group ID   |
+
+**Returns:** `String`
+— Success response
+
+_Added in v0.4.0_
+
+---
 
-webhooks = Vortex::Webhooks.new(secret: ENV['VORTEX_WEBHOOK_SECRET'])
+### `reinvite()`
 
-# In your HTTP handler (Rails example):
+Reinvite a user
+
+**Signature:**
+
+```ruby
+reinvite(invitation_id)
+```
+
+**Parameters:**
+
+| Name            | Type     | Required | Description                   |
+| --------------- | -------- | -------- | ----------------------------- |
+| `invitation_id` | `String` | ✓        | The invitation ID to reinvite |
+
+**Returns:** `String`
+— The reinvited invitation result
+
+_Added in v0.2.0_
+
+---
+
+### `get_autojoin_domains()`
+
+Get autojoin domains configured for a specific scope
+
+**Signature:**
+
+```ruby
+get_autojoin_domains(scope_type, scope)
+```
+
+**Parameters:**
+
+| Name         | Type     | Required | Description                                                 |
+| ------------ | -------- | -------- | ----------------------------------------------------------- |
+| `scope_type` | `String` | ✓        | The type of scope (e.g., "organization", "team", "project") |
+| `scope`      | `String` | ✓        | The scope identifier (customer's group ID)                  |
+
+**Returns:** `String`
+— Response with :autojoin_domains array and :invitation
+
+**Example:**
+
+```ruby
+#   result = client.get_autojoin_domains('organization', 'acme-org')
+    #   result['autojoinDomains'].each do |domain|
+    #     puts "Domain: #{domain['domain']}"
+    #   end
+```
+
+_Added in v0.6.0_
+
+---
+
+### `configure_autojoin()`
+
+Configure autojoin domains for a specific scope This endpoint syncs autojoin domains - it will add new domains, remove domains not in the provided list, and deactivate the autojoin invitation if all domains are removed (empty array).
+
+**Signature:**
+
+```ruby
+configure_autojoin(scope, scope_type, domains, component_id, scope_name = nil, metadata = nil)
+```
+
+**Parameters:**
+
+| Name           | Type            | Required | Description                                      |
+| -------------- | --------------- | -------- | ------------------------------------------------ |
+| `scope`        | `String`        | ✓        | The scope identifier (customer's group ID)       |
+| `scope_type`   | `String`        | ✓        | The type of scope (e.g., "organization", "team") |
+| `domains`      | `Array<String>` | ✓        | Array of domains to configure for autojoin       |
+| `component_id` | `String`        | ✓        | The component ID                                 |
+| `scope_name`   | `String, nil`   | ✓        | Optional display name for the scope              |
+| `metadata`     | `Hash, nil`     | ✓        | Optional metadata to attach to the invitation    |
+
+**Returns:** `String`
+— Response with :autojoin_domains array and :invitation
+
+**Example:**
+
+```ruby
+#   result = client.configure_autojoin(
+    #     'acme-org',
+    #     'organization',
+    #     ['acme.com', 'acme.org'],
+    #     'component-123',
+    #     'Acme Corporation'
+    #   )
+```
+
+_Added in v0.6.0_
+
+---
+
+</details>
+
+## Types
+
+<details>
+<summary>Click to expand type definitions</summary>
+
+### `GenerateTokenPayload`
+
+Payload for generate_token() - used to generate secure tokens for Vortex components
+
+| Field       | Type               | Required | Description                                                            |
+| ----------- | ------------------ | -------- | ---------------------------------------------------------------------- |
+| `user`      | `Hash (TokenUser)` |          | The authenticated user who will be using the Vortex component          |
+| `component` | `String`           |          | Component ID to generate token for (from your Vortex dashboard)        |
+| `scope`     | `String`           |          | Scope identifier to restrict invitations (format: "scopeType:scopeId") |
+| `vars`      | `Hash`             |          | Custom variables to pass to the component for template rendering       |
+
+### `TokenUser`
+
+User data for token generation - represents the authenticated user sending invitations
+
+| Field                   | Type            | Required | Description                                                                   |
+| ----------------------- | --------------- | -------- | ----------------------------------------------------------------------------- |
+| `id`                    | `String`        | ✓        | Unique identifier for the user in your system. Used to attribute invitations. |
+| `email`                 | `String`        |          | User's email address. Used for reply-to in invitation emails.                 |
+| `name`                  | `String`        |          | Display name shown to invitation recipients (e.g., "John invited you")        |
+| `avatar_url`            | `String`        |          | URL to user's avatar image. Displayed in invitation emails and widgets.       |
+| `admin_scopes`          | `Array<String>` |          | List of scope IDs where this user has admin privileges                        |
+| `allowed_email_domains` | `Array<String>` |          | Restrict invitations to specific email domains (e.g., ["acme.com"])           |
+
+### `AcceptUser`
+
+User data for accepting invitations - identifies who accepted the invitation
+
+| Field         | Type      | Required | Description                                                                        |
+| ------------- | --------- | -------- | ---------------------------------------------------------------------------------- |
+| `email`       | `String`  |          | Email address of the accepting user. At least one of email or phone is required.   |
+| `phone`       | `String`  |          | Phone number with country code. At least one of email or phone is required.        |
+| `name`        | `String`  |          | Display name of the accepting user (shown in notifications to inviter)             |
+| `is_existing` | `Boolean` |          | Whether user was already registered. true=existing, false=new signup, nil=unknown. |
+
+### `CreateInvitationTarget`
+
+Target specification when creating an invitation - where to send the invite
+
+| Field   | Type     | Required | Description                                                                        |
+| ------- | -------- | -------- | ---------------------------------------------------------------------------------- |
+| `type`  | `String` | ✓        | Delivery channel: "email", "phone", "share", or "internal"                         |
+| `value` | `String` | ✓        | Target address: email address, phone number with country code, or internal user ID |
+| `name`  | `String` |          | Display name of the recipient (used in email greetings)                            |
+
+### `CreateInvitationScope`
+
+Scope specification when creating an invitation - what group/team to invite into
+
+| Field      | Type     | Required | Description                                             |
+| ---------- | -------- | -------- | ------------------------------------------------------- |
+| `type`     | `String` | ✓        | Scope type (e.g., "team", "organization", "workspace")  |
+| `group_id` | `String` | ✓        | Your internal identifier for this scope/group           |
+| `name`     | `String` | ✓        | Display name for the scope (shown in invitation emails) |
+
+### `Identifier`
+
+Email or phone identifier for looking up users
+
+| Field   | Type     | Required | Description                                                     |
+| ------- | -------- | -------- | --------------------------------------------------------------- |
+| `type`  | `String` | ✓        | Identifier type: "email" or "phone"                             |
+| `value` | `String` | ✓        | The email address or phone number (with country code for phone) |
+
+### `ConfigureAutojoinRequest`
+
+Request to configure autojoin domains for a scope
+
+| Field        | Type            | Required | Description                                                       |
+| ------------ | --------------- | -------- | ----------------------------------------------------------------- |
+| `scope_type` | `String`        | ✓        | Type of scope (e.g., "team", "workspace")                         |
+| `scope_id`   | `String`        | ✓        | Your internal identifier for the scope                            |
+| `domains`    | `Array<String>` | ✓        | List of email domains to enable autojoin for (e.g., ["acme.com"]) |
+
+### `SyncInternalInvitationRequest`
+
+Request to sync an internal invitation (for tracking invitations made outside Vortex)
+
+| Field        | Type                            | Required | Description                                                  |
+| ------------ | ------------------------------- | -------- | ------------------------------------------------------------ |
+| `inviter_id` | `String`                        | ✓        | Your internal user ID for the person who sent the invitation |
+| `target`     | `Hash (CreateInvitationTarget)` | ✓        | The invitation recipient                                     |
+| `scopes`     | `Array<Hash>`                   |          | Scopes/groups the invitation grants access to                |
+
+### `InvitationResult`
+
+Complete invitation details as returned by the Vortex API
+
+| Field                      | Type             | Required | Description                                                                                                            |
+| -------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `id`                       | `String`         | ✓        | Unique identifier for this invitation                                                                                  |
+| `account_id`               | `String`         | ✓        | Your Vortex account ID                                                                                                 |
+| `click_throughs`           | `Integer`        | ✓        | Number of times the invitation link was clicked                                                                        |
+| `form_submission_data`     | `Hash \| nil`    |          | Invitation form data submitted by the user, including invitee identifiers (such as email addresses, phone numbers, or internal IDs) and the values of any custom fields. |
+| `configuration_attributes` | `Hash \| nil`    |          | Deprecated: Use form_submission_data instead. Contains the same data.                                                  |
+| `created_at`               | `String`         | ✓        | ISO 8601 timestamp when the invitation was created                                                                     |
+| `deactivated`              | `Boolean`        | ✓        | Whether this invitation has been revoked or expired                                                                    |
+| `delivery_count`           | `Integer`        | ✓        | Number of times the invitation was sent (including reminders)                                                          |
+| `delivery_types`           | `Array<String>`  | ✓        | Channels used to deliver: "email", "phone", "share", "internal"                                                        |
+| `foreign_creator_id`       | `String`         | ✓        | Your internal user ID for the person who created this invitation                                                       |
+| `invitation_type`          | `String`         | ✓        | Type: "single_use", "multi_use", or "autojoin"                                                                         |
+| `status`                   | `String`         | ✓        | Current status: queued, sending, sent, delivered, accepted, shared                                                     |
+| `target`                   | `Array<Hash>`    | ✓        | List of invitation recipients with their contact info and status                                                       |
+| `views`                    | `Integer`        | ✓        | Number of times the invitation page was viewed                                                                         |
+| `groups`                   | `Array<Hash>`    | ✓        | Scopes (teams/orgs) this invitation grants access to                                                                   |
+| `expired`                  | `Boolean`        | ✓        | Whether this invitation has passed its expiration date                                                                 |
+| `expires`                  | `String`         |          | ISO 8601 timestamp when this invitation expires                                                                        |
+| `inviter`                  | `Hash (Inviter)` |          | Information about who sent the invitation                                                                              |
+
+### `InvitationTarget`
+
+Target recipient of an invitation (from API response)
+
+| Field        | Type     | Required | Description                                                             |
+| ------------ | -------- | -------- | ----------------------------------------------------------------------- |
+| `type`       | `String` | ✓        | Delivery channel: "email", "phone", "share", or "internal"              |
+| `value`      | `String` | ✓        | Target address: email, phone number with country code, or share link ID |
+| `name`       | `String` |          | Display name of the recipient                                           |
+| `avatar_url` | `String` |          | Avatar URL for the recipient                                            |
+| `status`     | `String` |          | Delivery status for this specific target                                |
+
+### `InvitationScope`
+
+Scope/group that the invitation grants access to (from API response)
+
+| Field        | Type     | Required | Description                                            |
+| ------------ | -------- | -------- | ------------------------------------------------------ |
+| `id`         | `String` | ✓        | Vortex internal UUID for this scope record             |
+| `account_id` | `String` | ✓        | Your Vortex account ID                                 |
+| `group_id`   | `String` | ✓        | Your internal scope/group identifier                   |
+| `type`       | `String` | ✓        | Scope type (e.g., "team", "organization", "workspace") |
+| `name`       | `String` | ✓        | Display name for the scope                             |
+| `created_at` | `String` | ✓        | ISO 8601 timestamp when the scope was created          |
+
+### `InvitationAcceptance`
+
+Details about an invitation acceptance event
+
+| Field           | Type      | Required | Description                                     |
+| --------------- | --------- | -------- | ----------------------------------------------- |
+| `id`            | `String`  | ✓        | Unique identifier for this acceptance record    |
+| `invitation_id` | `String`  | ✓        | ID of the invitation that was accepted          |
+| `email`         | `String`  |          | Email of the user who accepted                  |
+| `phone`         | `String`  |          | Phone of the user who accepted                  |
+| `name`          | `String`  |          | Name of the user who accepted                   |
+| `is_existing`   | `Boolean` |          | Whether the user already had an account         |
+| `created_at`    | `String`  | ✓        | ISO 8601 timestamp when the acceptance occurred |
+
+### `Inviter`
+
+Information about the user who sent an invitation
+
+| Field        | Type     | Required | Description                           |
+| ------------ | -------- | -------- | ------------------------------------- |
+| `id`         | `String` | ✓        | Your internal user ID for the inviter |
+| `email`      | `String` |          | Email address of the inviter          |
+| `name`       | `String` |          | Display name of the inviter           |
+| `avatar_url` | `String` |          | Avatar URL of the inviter             |
+
+### `AutojoinDomain`
+
+Autojoin domain configuration - users with matching email domains automatically join
+
+| Field    | Type     | Required | Description                                            |
+| -------- | -------- | -------- | ------------------------------------------------------ |
+| `id`     | `String` | ✓        | Unique identifier for this autojoin configuration      |
+| `domain` | `String` | ✓        | Email domain that triggers autojoin (e.g., "acme.com") |
+
+### `AutojoinDomainsResponse`
+
+Response from get_autojoin_domains()
+
+| Field     | Type                    | Required | Description                         |
+| --------- | ----------------------- | -------- | ----------------------------------- |
+| `domains` | `Array<AutojoinDomain>` | ✓        | List of configured autojoin domains |
+
+### `SyncInternalInvitationResponse`
+
+Response from sync_internal_invitation()
+
+| Field        | Type                      | Required | Description                                                         |
+| ------------ | ------------------------- | -------- | ------------------------------------------------------------------- |
+| `invitation` | `Hash (InvitationResult)` | ✓        | The created or updated invitation                                   |
+| `created`    | `Boolean`                 | ✓        | true if a new invitation was created, false if existing was updated |
+
+### `VortexWebhookEvent`
+
+Webhook event payload delivered to your endpoint
+
+| Field       | Type     | Required | Description                                                |
+| ----------- | -------- | -------- | ---------------------------------------------------------- |
+| `id`        | `String` | ✓        | Unique identifier for this webhook delivery                |
+| `type`      | `String` | ✓        | Event type (e.g., "invitation.accepted", "member.created") |
+| `timestamp` | `String` | ✓        | ISO 8601 timestamp when the event occurred                 |
+| `data`      | `Hash`   | ✓        | Event-specific payload data                                |
+
+</details>
+
+## Webhooks
+
+Webhooks let your server receive real-time notifications when events happen in Vortex. Use them to sync invitation state with your database, trigger onboarding flows, update your CRM, or send internal notifications.
+
+### Setup
+
+1. Go to your Vortex dashboard → Integrations → Webhooks tab
+2. Click "Add Webhook"
+3. Enter your endpoint URL (must be HTTPS in production)
+4. Copy the signing secret — you'll use this to verify webhook signatures
+5. Select which events you want to receive
+
+### Verifying Webhooks
+
+Always verify webhook signatures using `Vortex::Webhooks.verify_signature()` to ensure requests are from Vortex.
+The signature is sent in the `X-Vortex-Signature` header.
+
+### Example: Rails webhook handler
+
+```ruby
 class WebhooksController < ApplicationController
   skip_before_action :verify_authenticity_token
 
-  def create
-    payload = request.body.read
+  def vortex
+    webhooks = Vortex::Webhooks.new(ENV['VORTEX_WEBHOOK_SECRET'])
+
+    payload = request.raw_post
     signature = request.headers['X-Vortex-Signature']
 
-    begin
-      event = webhooks.construct_event(payload, signature)
-    rescue Vortex::WebhookSignatureError
-      head :bad_request
-      return
+    # Verify the signature
+    unless webhooks.verify_signature(payload, signature)
+      return render json: { error: 'Invalid signature' }, status: 400
     end
 
-    case event
-    when Vortex::WebhookEvent
-      Rails.logger.info "Webhook event: #{event.type}"
-    when Vortex::AnalyticsEvent
-      Rails.logger.info "Analytics event: #{event.name}"
+    # Parse the event
+    event = webhooks.parse_event(payload)
+
+    case event['type']
+    when 'invitation.accepted'
+      # User accepted an invitation — activate their account
+      Rails.logger.info "Accepted: #{event['data']}"
+    when 'member.created'
+      # New member joined via invitation
+      Rails.logger.info "New member: #{event['data']}"
     end
 
-    head :ok
+    render json: { received: true }
   end
 end
+
 ```
 
-### Event Type Constants
+### Common Use Cases
 
-```ruby
-if event.type == Vortex::WebhookEventTypes::INVITATION_ACCEPTED
-  # Handle invitation accepted
-end
-```
+**Activate users on acceptance**
+
+When invitation.accepted fires, mark the user as active in your database and trigger your onboarding flow.
+
+**Track invitation performance**
+
+Monitor email.delivered, email.opened, and link.clicked events to measure invitation funnel metrics.
+
+**Sync team membership**
+
+Use member.created and group.member.added to keep your internal membership records in sync.
+
+**Alert on delivery issues**
+
+Watch for email.bounced events to proactively reach out via alternative channels.
+
+### Supported Events
+
+| Event                        | Description                                          |
+| ---------------------------- | ---------------------------------------------------- |
+| `invitation.created`         | A new invitation was created                         |
+| `invitation.accepted`        | An invitation was accepted by the recipient          |
+| `invitation.deactivated`     | An invitation was deactivated (revoked or expired)   |
+| `invitation.email.delivered` | Invitation email was successfully delivered          |
+| `invitation.email.bounced`   | Invitation email bounced (invalid address)           |
+| `invitation.email.opened`    | Recipient opened the invitation email                |
+| `invitation.link.clicked`    | Recipient clicked the invitation link                |
+| `invitation.reminder.sent`   | A reminder email was sent for a pending invitation   |
+| `member.created`             | A new member was created from an accepted invitation |
+| `group.member.added`         | A member was added to a scope/group                  |
+| `deployment.created`         | A new deployment configuration was created           |
+| `deployment.deactivated`     | A deployment was deactivated                         |
+| `abtest.started`             | An A/B test was started                              |
+| `abtest.winner_declared`     | An A/B test winner was declared                      |
+| `email.complained`           | Recipient marked the email as spam                   |
+
+## Error Handling
+
+All SDK errors extend `VortexError`.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/vortexsoftware/vortex-ruby-sdk.
+| Error         | Description                                                                              |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| `VortexError` | Raised for validation errors (e.g., missing API key, invalid parameters) or API failures |
 
-## License
+---
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+<!-- Generated from SDK v1.18.0 manifest -->