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

# Ruby SDK

> Install and use the official Essal Ruby SDK to access all six apps from your Ruby project.

The `essal-ruby` gem provides an idiomatic Ruby client for the Essal API. It supports Ruby 3.0+.

## Installation

Add to your `Gemfile`:

```ruby theme={null}
gem "essal", "~> 1.0"
```

Then run:

```bash theme={null}
bundle install
```

## Initialisation

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

client = Essal::Client.new(
  api_key: ENV["ESSAL_API_KEY"],
  environment: :production # :production, :staging, :sandbox
)
```

## Usage Examples

```ruby theme={null}
# List documents
docs = client.office.documents.list(limit: 20)
docs.each { |doc| puts doc.title }

# Create a Sales contact
contact = client.sales.contacts.create(
  display_name: "Jane Smith",
  email: "jane@acmecorp.com",
  organization_name: "Acme Corp"
)

# Create a Project task
task = client.project.tasks.create(
  project_id: "proj_01HXYZ9876",
  title: "Design review",
  priority: "high"
)
```

## Pagination

```ruby theme={null}
client.office.documents.list(limit: 50).auto_paging_each do |doc|
  puts doc.title
end
```

## Error Handling

```ruby theme={null}
begin
  contact = client.sales.contacts.get("cnt_nonexistent")
rescue Essal::ResourceNotFoundError => e
  puts "Not found: #{e.message}"
rescue Essal::RateLimitError => e
  sleep(e.retry_after)
  retry
end
```