> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Official Zavu SDK for Ruby

<Warning>
  **Server-side only** — This SDK is designed for server-side environments (Rails, Sinatra, background jobs). Never use it in browser/frontend code as this exposes your API key. See [Frontend Integration](/authentication#frontend-integration) for the proxy pattern.
</Warning>

The official Zavu SDK for Ruby provides an idiomatic Ruby interface to the Zavu API.

## Installation

```bash theme={null}
gem install zavudev
# or add to your Gemfile
gem "zavudev"
```

## Requirements

* Ruby 3.0 or higher

## Quick Start

```ruby theme={null}
require "zavudev"

client = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)

result = client.messages.send(
  to: "+14155551234",
  text: "Hello from Zavu!"
)

puts "Message sent: #{result.message.id}"
```

## Configuration

### Initialize the Client

```ruby theme={null}
require "zavudev"

# Basic initialization
client = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)

# With custom base URL
client = Zavudev::Client.new(
  api_key: "zv_live_xxx",
  base_url: "https://api.zavu.dev"
)
```

### Environment Variables

We recommend storing your API key in environment variables:

```ruby theme={null}
client = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)
```

## Accessing Response Headers

Use `.with_raw_response` to access the full HTTP response including headers (useful for rate limiting):

```ruby theme={null}
response = client.messages.send.with_raw_response(
  to: "+14155551234",
  text: "Hello!"
)

remaining = response.headers["X-RateLimit-Remaining"]
puts "Remaining requests: #{remaining}"

result = response.parse
puts "Message ID: #{result.message.id}"
```

## Error Handling

```ruby theme={null}
require "zavudev"

client = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)

begin
  client.messages.send(to: "invalid-number", text: "Hello")
rescue Zavudev::APIError => e
  puts "Status: #{e.status}"
  puts "Message: #{e.message}"
rescue Zavudev::ZavudevError => e
  puts "Error: #{e.message}"
end
```

### Error Types

| Error Code | Description                |
| ---------- | -------------------------- |
| `400`      | Invalid request parameters |
| `401`      | Invalid or missing API key |
| `403`      | Insufficient permissions   |
| `404`      | Resource not found         |
| `429`      | Rate limit exceeded        |

## Retries

The SDK supports automatic retries with configurable backoff:

```ruby theme={null}
client = Zavudev::Client.new(
  api_key: "zv_live_xxx",
  max_retries: 3
)

result = client.messages.send(
  to: "+14155551234",
  text: "Hello!"
)
```

## Thread Safety

The client is thread-safe and can be shared across threads:

```ruby theme={null}
# Create a single client instance
$zavu = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)

# Safe to use from multiple threads
threads = 10.times.map do |i|
  Thread.new do
    $zavu.messages.send(
      to: "+14155551234",
      text: "Message #{i}"
    )
  end
end

threads.each(&:join)
```

## Rails Integration

```ruby theme={null}
# config/initializers/zavu.rb
require "zavudev"

ZAVU_CLIENT = Zavudev::Client.new(
  api_key: Rails.application.credentials.dig(:zavu, :api_key)
)
```

```ruby theme={null}
# app/services/notification_service.rb
class NotificationService
  def send_sms(phone_number, message)
    ZAVU_CLIENT.messages.send(
      to: phone_number,
      text: message
    )
  end
end
```