# Ruby SDK

[View original](https://ittybit.com/sdks/ruby)

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'ittybit'
```

And then execute:

```bash
$ bundle install
```

Or install it yourself as:

```bash
$ gem install ittybit
```

***

## Usage

### Basic Usage

```ruby
require 'ittybit'

# Initialize the client
ittybit = Ittybit::Client.new(
  token: "ITTYBIT_API_KEY",
)

# Create a new media item
media = ittybit.media.create(
  title: "My Video",
  metadata: { "credit": "gtv-videos-bucket" }
)

# Upload a file
file = ittybit.files.create(
  url: "https://ittyb.it/sample.mp4",
  filename: "video.mp4",
  folder: "example",
  metadata: { "customKey": "your custom value" }
)

# Create a signed URL
signature = ittybit.signatures.create(
  filename: "video.mp4",
  folder: "private/user_123",
  expiry: 1735689600,
  method: "GET"
)
```

***

### Async Usage

The SDK also provides async clients for non-blocking operations:

```ruby
require 'ittybit'
require 'async'

Async do
  ittybit = Ittybit::AsyncClient.new(
    token: "ITTYBIT_API_KEY",
  )

  # Async operations
  media = ittybit.media.create(
    title: "My Video",
    metadata: { "credit": "gtv-videos-bucket" }
  )
end
```

***

## Features

### Media Management

```ruby
# List all media
media_list = ittybit.media.list(limit: 10)

# Get specific media
media = ittybit.media.get(id: "media_id")

# Update media
updated_media = ittybit.media.update(
  id: "media_id",
  title: "New Title",
  metadata: { "new_key": "new_value" }
)

# Delete media
ittybit.media.delete(id: "media_id")
```

***

### File Management

```ruby
# List files
files = ittybit.files.list(limit: 10)

# Get file details
file = ittybit.files.get(id: "file_id")

# Upload file from URL
file = ittybit.files.create(
  url: "https://example.com/video.mp4",
  filename: "video.mp4",
  folder: "videos",
  metadata: { "source": "example" }
)
```

***

### Task Management

```ruby
# Get task configuration
config = ittybit.tasks.get_task_config

# Create a new task
task = ittybit.tasks.create(
  kind: "ingest",
  url: "https://example.com/video.mp4",
  input: { "format": "mp4" }
)

# Get task status
task = ittybit.tasks.get(id: "task_id")

# List tasks
tasks = ittybit.tasks.list(
  limit: 10,
  status: "completed",
  kind: "ingest"
)
```

***

### Signed URLs

```ruby
# Generate a signed URL
signature = ittybit.signatures.create(
  filename: "video.mp4",
  folder: "private/user_123",
  expiry: Time.now.to_i + 3600, # 1 hour from now
  method: "GET"
)
```

***

## Advanced Features

### Request Options

You can customize individual requests with additional options:

```ruby
# Custom timeout
ittybit.media.create(
  title: "My Video",
  request_options: Ittybit::RequestOptions.new(
    timeout_in_seconds: 30
  )
)
```

The SDK only accepts the following headers:

* `Authorization`: Bearer token for authentication (required)

***

### Error Handling

The SDK raises exceptions for API errors:

```ruby
begin
  ittybit.media.get(id: "non_existent_id")
rescue Ittybit::Error => e
  puts "Error: #{e.message}"
  puts "Status code: #{e.status_code}"
  puts "Response body: #{e.body}"
end
```