vapi-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f22947bfc1aff0910a372e417b00d3d627896f43d9bd9e2760a897c1343f75e5
+  data.tar.gz: d22223f4a7f7c5ad0b0144b93882ee78cb7fb274c0df14cbda07c135c489c4ce
+SHA512:
+  metadata.gz: f1cee1b70f543e6bdb66c20f2d7c1272c77cc54e9103ee0829bedf3c2411426f5f0cf5b964c214f94289145e4584dce2857dcb7baa4ebecc9091f2b0371881e9
+  data.tar.gz: 6f33b0187a90d34223e80b862abae104c954525f0e06f7dc9b711afe1c216899c8c84df4043d58cc1202225e1871345929e4d459c2c2a8b749accf371b349242

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-25
+
+### Added
+- Initial release
+- `Vapi::Assistant` — CRUD for voice AI assistants
+- `Vapi::Call` — create outbound calls, list, and manage call records
+- `Vapi::PhoneNumber` — manage phone numbers (Twilio, Vonage, VAPI)
+- `Vapi::Squad` — manage multi-assistant squads
+- `Vapi::Tool` — CRUD for function/API tools attached to assistants
+- `Vapi::File` — upload and manage files
+- `Vapi::KnowledgeBase` — manage knowledge bases for RAG
+- `Vapi::Log` — retrieve call and API logs
+- `Vapi::Analytics` — query call analytics
+- Bearer token authentication
+- Comprehensive error handling (401, 404, 429, 400/422, 5xx)
+- Full RSpec test suite with WebMock

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Eduardo Souza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,305 @@
+# VAPI Ruby [![Gem Version](https://badge.fury.io/rb/vapi-ruby.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/vapi-ruby)
+
+Ruby gem for integrating with the [VAPI](https://vapi.ai) voice AI platform. Supports assistants, calls, phone numbers, squads, tools, files, knowledge bases, logs, and analytics.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'vapi-ruby'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install vapi-ruby
+```
+
+## Configuration
+
+```ruby
+Vapi.configure do |config|
+  config.api_key = ENV['VAPI_API_KEY']
+
+  # Optional
+  config.timeout = 30 # seconds, default
+end
+```
+
+## Usage
+
+All resources can be initialized without arguments (uses `Vapi.client` by default) or with an explicit client.
+
+### Assistants
+
+```ruby
+assistants = Vapi::Assistant.new
+
+# List all assistants
+assistants.list
+
+# List with filters
+assistants.list(limit: 10, createdAtGt: '2024-01-01T00:00:00Z')
+
+# Get an assistant
+assistants.find('assistant_id')
+
+# Create an assistant
+assistants.create(
+  name: 'Sales Agent',
+  model: { provider: 'openai', model: 'gpt-4' },
+  voice: { provider: '11labs', voiceId: 'voice_id' },
+  firstMessage: 'Hello! How can I help you today?'
+)
+
+# Update an assistant
+assistants.update('assistant_id', name: 'Updated Name')
+
+# Delete an assistant
+assistants.delete('assistant_id')
+```
+
+### Calls
+
+```ruby
+calls = Vapi::Call.new
+
+# List all calls
+calls.list
+
+# Filter by assistant
+calls.list(assistantId: 'assistant_id')
+
+# Get a call
+calls.find('call_id')
+
+# Create an outbound call
+calls.create(
+  assistantId: 'assistant_id',
+  phoneNumberId: 'phone_number_id',
+  customer: { number: '+1234567890' }
+)
+
+# Update a call
+calls.update('call_id', name: 'Follow-up Call')
+
+# Delete a call
+calls.delete('call_id')
+```
+
+### Phone Numbers
+
+```ruby
+phone_numbers = Vapi::PhoneNumber.new
+
+# List phone numbers
+phone_numbers.list
+
+# Get a phone number
+phone_numbers.find('phone_number_id')
+
+# Create a phone number
+phone_numbers.create(
+  provider: 'twilio',
+  number: '+1234567890',
+  twilioAccountSid: 'sid',
+  twilioAuthToken: 'token'
+)
+
+# Update a phone number
+phone_numbers.update('phone_number_id', name: 'Main Line')
+
+# Delete a phone number
+phone_numbers.delete('phone_number_id')
+```
+
+### Squads
+
+```ruby
+squads = Vapi::Squad.new
+
+# List squads
+squads.list
+
+# Get a squad
+squads.find('squad_id')
+
+# Create a squad
+squads.create(
+  name: 'Sales Team',
+  members: [{ assistantId: 'assistant_id' }]
+)
+
+# Update a squad
+squads.update('squad_id', name: 'Updated Team')
+
+# Delete a squad
+squads.delete('squad_id')
+```
+
+### Tools
+
+```ruby
+tools = Vapi::Tool.new
+
+# List tools
+tools.list
+
+# Get a tool
+tools.find('tool_id')
+
+# Create a tool
+tools.create(
+  type: 'function',
+  function: {
+    name: 'lookup_order',
+    description: 'Look up an order by ID',
+    parameters: { type: 'object', properties: { orderId: { type: 'string' } } }
+  }
+)
+
+# Update a tool
+tools.update('tool_id', function: { name: 'updated_lookup' })
+
+# Delete a tool
+tools.delete('tool_id')
+```
+
+### Files
+
+```ruby
+files = Vapi::File.new
+
+# List files
+files.list
+
+# Get a file
+files.find('file_id')
+
+# Upload a file
+files.create(name: 'training_data.pdf')
+
+# Update a file
+files.update('file_id', name: 'renamed.pdf')
+
+# Delete a file
+files.delete('file_id')
+```
+
+### Knowledge Bases
+
+```ruby
+knowledge_bases = Vapi::KnowledgeBase.new
+
+# List knowledge bases
+knowledge_bases.list
+
+# Get a knowledge base
+knowledge_bases.find('knowledge_base_id')
+
+# Create a knowledge base
+knowledge_bases.create(
+  name: 'Product FAQ',
+  provider: 'trieve'
+)
+
+# Update a knowledge base
+knowledge_bases.update('knowledge_base_id', name: 'Updated FAQ')
+
+# Delete a knowledge base
+knowledge_bases.delete('knowledge_base_id')
+```
+
+### Logs
+
+```ruby
+logs = Vapi::Log.new
+
+# List all logs
+logs.list
+
+# Filter by call
+logs.list(callId: 'call_id')
+```
+
+### Analytics
+
+```ruby
+analytics = Vapi::Analytics.new
+
+# Query analytics
+analytics.query(
+  queries: [
+    {
+      name: 'total_calls',
+      table: 'call',
+      operations: [{ operation: 'count', column: 'id' }]
+    }
+  ]
+)
+```
+
+### Using Multiple Clients
+
+```ruby
+config1 = Vapi::Configuration.new
+config1.api_key = 'key_for_org_1'
+client1 = Vapi::Client.new(config1)
+
+config2 = Vapi::Configuration.new
+config2.api_key = 'key_for_org_2'
+client2 = Vapi::Client.new(config2)
+
+# Use explicit clients
+Vapi::Assistant.new(client1).list
+Vapi::Assistant.new(client2).list
+```
+
+### Error Handling
+
+```ruby
+begin
+  calls.create(assistantId: 'invalid')
+rescue Vapi::ConfigurationError => e
+  # Missing API key
+rescue Vapi::AuthenticationError => e
+  # Invalid API key
+rescue Vapi::ValidationError => e
+  puts e.errors
+rescue Vapi::NotFoundError => e
+  # 404 - Resource not found
+rescue Vapi::RateLimitError => e
+  puts e.retry_after # Seconds to wait
+rescue Vapi::APIError => e
+  puts e.status_code
+  puts e.response_body
+end
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/esouza/vapi-ruby). See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/vapi/analytics.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Analytics < Base
+    def query(params)
+      client.post("/analytics", params)
+    end
+  end
+end

data/lib/vapi/assistant.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Assistant < Base
+    def list(**params)
+      client.get("/assistant", params)
+    end
+
+    def find(id)
+      client.get("/assistant/#{id}")
+    end
+
+    def create(params)
+      client.post("/assistant", params)
+    end
+
+    def update(id, params)
+      client.patch("/assistant/#{id}", params)
+    end
+
+    def delete(id)
+      client.delete("/assistant/#{id}")
+    end
+  end
+end

data/lib/vapi/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Base
+    attr_reader :client
+
+    def initialize(client = nil)
+      @client = client || Vapi.client
+    end
+  end
+end

data/lib/vapi/call.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Call < Base
+    def list(**params)
+      client.get("/call", params)
+    end
+
+    def find(id)
+      client.get("/call/#{id}")
+    end
+
+    def create(params)
+      client.post("/call", params)
+    end
+
+    def update(id, params)
+      client.patch("/call/#{id}", params)
+    end
+
+    def delete(id)
+      client.delete("/call/#{id}")
+    end
+  end
+end

data/lib/vapi/client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Client
+    include HTTParty
+
+    attr_reader :configuration
+
+    def initialize(configuration = nil)
+      @configuration = configuration || Vapi.configuration
+      validate_configuration!
+    end
+
+    def get(path, params = {})
+      request(:get, path, query: params)
+    end
+
+    def post(path, data = {})
+      request(:post, path, body: data.to_json)
+    end
+
+    def patch(path, data = {})
+      request(:patch, path, body: data.to_json)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def validate_configuration!
+      raise ConfigurationError unless configuration&.valid?
+    end
+
+    def request(method, path, options = {})
+      url = "#{configuration.base_url}#{path}"
+      request_options = {
+        headers: default_headers,
+        timeout: configuration.timeout
+      }
+
+      if options[:query] && !options[:query].empty?
+        request_options[:query] = options[:query]
+      end
+
+      if options[:body]
+        request_options[:body] = options[:body]
+      end
+
+      response = self.class.send(method, url, request_options)
+      handle_response(response)
+    end
+
+    def default_headers
+      {
+        'Authorization' => "Bearer #{configuration.api_key}",
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json'
+      }
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201, 202, 204
+        response.parsed_response
+      when 401
+        raise AuthenticationError, "Authentication failed: #{response.body}"
+      when 404
+        raise NotFoundError.new("Resource not found", response.code, response.body)
+      when 429
+        retry_after = response.headers['retry-after']
+        raise RateLimitError.new("Rate limit exceeded", response.code, response.body, retry_after)
+      when 400, 422
+        parsed = response.parsed_response || {}
+        errors = parsed['errors'] || parsed['message'] || {}
+        raise ValidationError.new(
+          parsed['message'] || 'Validation failed',
+          response.code,
+          response.body,
+          errors
+        )
+      when 500..599
+        raise APIError.new("Server error", response.code, response.body)
+      else
+        raise APIError.new("Unexpected response", response.code, response.body)
+      end
+    end
+  end
+end

data/lib/vapi/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+
+    def initialize
+      @base_url = "https://api.vapi.ai"
+      @timeout = 30
+    end
+
+    def valid?
+      !api_key.nil? && !api_key.empty?
+    end
+  end
+end

data/lib/vapi/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Error < StandardError; end
+
+  class ConfigurationError < Error
+    def initialize(message = "Missing required configuration: api_key")
+      super(message)
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super(message)
+    end
+  end
+
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code = nil, response_body = nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  class ValidationError < APIError
+    attr_reader :errors
+
+    def initialize(message, status_code = nil, response_body = nil, errors = {})
+      super(message, status_code, response_body)
+      @errors = errors
+    end
+  end
+
+  class NotFoundError < APIError
+    def initialize(message = "Resource not found", status_code = 404, response_body = nil)
+      super(message, status_code, response_body)
+    end
+  end
+
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", status_code = 429, response_body = nil, retry_after = nil)
+      super(message, status_code, response_body)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/vapi/file.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vapi
+  class File < Base
+    def list(**params)
+      client.get("/file", params)
+    end
+
+    def find(id)
+      client.get("/file/#{id}")
+    end
+
+    def create(params)
+      client.post("/file", params)
+    end
+
+    def update(id, params)
+      client.patch("/file/#{id}", params)
+    end
+
+    def delete(id)
+      client.delete("/file/#{id}")
+    end
+  end
+end

data/lib/vapi/knowledge_base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vapi
+  class KnowledgeBase < Base
+    def list(**params)
+      client.get("/knowledge-base", params)
+    end
+
+    def find(id)
+      client.get("/knowledge-base/#{id}")
+    end
+
+    def create(params)
+      client.post("/knowledge-base", params)
+    end
+
+    def update(id, params)
+      client.patch("/knowledge-base/#{id}", params)
+    end
+
+    def delete(id)
+      client.delete("/knowledge-base/#{id}")
+    end
+  end
+end

data/lib/vapi/log.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Log < Base
+    def list(**params)
+      client.get("/logs", params)
+    end
+  end
+end

data/lib/vapi/phone_number.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vapi
+  class PhoneNumber < Base
+    def list(**params)
+      client.get("/phone-number", params)
+    end
+
+    def find(id)
+      client.get("/phone-number/#{id}")
+    end
+
+    def create(params)
+      client.post("/phone-number", params)
+    end
+
+    def update(id, params)
+      client.patch("/phone-number/#{id}", params)
+    end
+
+    def delete(id)
+      client.delete("/phone-number/#{id}")
+    end
+  end
+end

data/lib/vapi/squad.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vapi
+  class Squad < Base
+    def list(**params)
+      client.get("/squad", params)
+    end
+
+    def find(id)
+      client.get("/squad/#{id}")
+    end
+
+    def create(params)
+      client.post("/squad", params)
+    end
+
+    def update(id, params)
+      client.patch("/squad/#{id}", params)
+    end
+
+    def delete(id)
+      client.delete("/squad/#{id}")
+    end
+  end
+end