### Setup Tourvisor Development Environment

Source: https://github.com/kimrgrey/tourvisor/blob/master/README.md

After cloning the repository, run `bin/setup` to install dependencies. Use `rake test` to run tests or `bin/console` for an interactive prompt.

```bash
bin/setup
```

```bash
rake test
```

```bash
bin/console
```

--------------------------------

### Install Tourvisor Gem

Source: https://github.com/kimrgrey/tourvisor/blob/master/README.md

After adding the gem to your Gemfile, execute `bundle` to install it. Alternatively, you can install it directly using `gem install tourvisor`.

```bash
bundle
```

```bash
gem install tourvisor
```

--------------------------------

### Install Tourvisor Gem Locally

Source: https://github.com/kimrgrey/tourvisor/blob/master/README.md

To install the gem onto your local machine, run `bundle exec rake install`.

```bash
bundle exec rake install
```

--------------------------------

### Configure Tourvisor Gem

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Configure the Tourvisor gem with your API login, password, and optional base URL and format. Access configuration values after setup.

```ruby
require 'tourvisor'

# Configure with your Tourvisor.ru API credentials
Tourvisor.configure do |config|
  config.login = 'your_api_login'
  config.password = 'your_api_password'
  config.format = 'json'  # Default format
  config.base_url = 'http://tourvisor.ru/xml'  # Default base URL
end

# Access the configuration object
puts Tourvisor.config.login
# => "your_api_login"

puts Tourvisor.config.base_url
# => "http://tourvisor.ru/xml"
```

--------------------------------

### Complete Tour Search Workflow

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Demonstrates the full workflow: configuring the client using environment variables, initiating a search, and preparing for status polling and result retrieval.

```ruby
require 'tourvisor'

# Step 1: Configure the client
Tourvisor.configure do |config|
  config.login = ENV['TOURVISOR_LOGIN']
  config.password = ENV['TOURVISOR_PASSWORD']
end

```

--------------------------------

### Initiate Tour Search and Fetch Results

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Initiates a tour search with specified criteria, polls for completion, and then fetches and displays tour results. Handles potential API errors during the process.

```ruby
request = Tourvisor::Request.new

begin
  request.search(
    departure: 1,           # Moscow
    country: 90,            # Turkey
    datefrom: '01.07.2024',
    dateto: '31.07.2024',
    nightsfrom: 7,
    nightsto: 14,
    adults: 2,
    child: 1,
    childage: 5
  )

  puts "Search started: #{request.request_id}"

  # Step 3: Poll for completion
  loop do
    status = request.status
    puts "Status: #{status[:state]} - Progress: #{status[:progress]}%"

    break if request.finished?
    sleep(3)
  end

  # Step 4: Fetch and display results
  results = request.result(onpage: 10)

  if results[:data][:result][:hotel]
    results[:data][:result][:hotel].each do |hotel|
      puts "\n#{hotel[:hotelname]} (#{hotel[:hotelstars]}*)"
      puts "  Price: #{hotel[:price]} #{hotel[:currency]}"
      puts "  Nights: #{hotel[:nights]}"
      puts "  Meal: #{hotel[:meal]}"
    end
  else
    puts "No tours found matching criteria"
  end

rescue Tourvisor::UnexpectedResponseError => e
  puts "API Error: #{e.message}"
rescue Tourvisor::UnknownFormatError => e
  puts "Format Error: #{e.message}"
end
```

--------------------------------

### Create Tourvisor Request Instance

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Instantiate the `Tourvisor::Request` class to interact with the API. Ensure configuration is set before creating an instance. The `request_id` is nil until a search is performed.

```ruby
require 'tourvisor'

# Ensure configuration is set first
Tourvisor.configure do |config|
  config.login = 'your_api_login'
  config.password = 'your_api_password'
end

# Create a new request instance
request = Tourvisor::Request.new

# The request instance provides access to search, result, and status methods
puts request.request_id
# => nil (before any search is performed)
```

--------------------------------

### Configure Tourvisor Gem and Handle Errors

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Configures the Tourvisor gem with API credentials and demonstrates basic error handling for API requests and response formats using custom exception classes.

```ruby
require 'tourvisor'

Tourvisor.configure do |config|
  config.login = 'your_api_login'
  config.password = 'your_api_password'
end

request = Tourvisor::Request.new

begin
  # Attempt search
  request.search(departure: 1, country: 1)

  # Wait and get results
  sleep(5) until request.finished?
  results = request.result

rescue Tourvisor::UnexpectedResponseError => e
  # Handles HTTP errors and unexpected API responses
  puts "API request failed: #{e.message}"

rescue Tourvisor::UnknownFormatError => e
  # Handles unsupported response formats
  puts "Cannot parse response format: #{e.message}"

rescue StandardError => e
  # Catch-all for other errors
  puts "Unexpected error: #{e.message}"
end
```

--------------------------------

### Perform Tour Search

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Initiate a tour search using the `search` method with required parameters like departure, country, dates, and nights. Handles potential `UnexpectedResponseError` during search initiation.

```ruby
require 'tourvisor'

Tourvisor.configure do |config|
  config.login = 'your_api_login'
  config.password = 'your_api_password'
end

request = Tourvisor::Request.new

# Perform a search with tour parameters
# Parameters depend on the Tourvisor.ru API documentation
begin
  request.search(
    departure: 1,           # Departure city ID
    country: 1,             # Country ID
    datefrom: '01.06.2024', # Start date
    dateto: '15.06.2024',   # End date
    nightsfrom: 7,          # Minimum nights
    nightsto: 14,           # Maximum nights
    adults: 2               # Number of adults
  )

  puts "Search initiated with request ID: #{request.request_id}"
  # => "Search initiated with request ID: abc123..."
rescue Tourvisor::UnexpectedResponseError => e
  puts "Search failed: #{e.message}"
end
```

--------------------------------

### Add Tourvisor Gem to Gemfile

Source: https://github.com/kimrgrey/tourvisor/blob/master/README.md

To use the Tourvisor gem, add this line to your application's Gemfile.

```ruby
gem 'tourvisor'
```

--------------------------------

### Release New Version of Tourvisor Gem

Source: https://github.com/kimrgrey/tourvisor/blob/master/README.md

To release a new version, update `version.rb`, then run `bundle exec rake release`. This creates a git tag, pushes commits and tags, and uploads the gem to rubygems.org.

```bash
bundle exec rake release
```

--------------------------------

### Retrieve Tour Search Results

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Retrieve tour search results using the `result` method after the search is complete. Supports pagination and filtering via optional parameters. Handles potential `UnexpectedResponseError`.

```ruby
require 'tourvisor'

Tourvisor.configure do |config|
  config.login = 'your_api_login'
  config.password = 'your_api_password'
end

request = Tourvisor::Request.new
request.search(
  departure: 1,
  country: 1,
  datefrom: '01.06.2024',
  dateto: '15.06.2024',
  nightsfrom: 7,
  adults: 2
)

# Wait for search to complete
sleep(2) until request.finished?

# Retrieve results with optional parameters
begin
  results = request.result(page: 1, onpage: 20)

  # Process tour results
  results[:data][:result][:hotel].each do |hotel|
    puts "Hotel: #{hotel[:hotelname]}"
    puts "Price: #{hotel[:price]} #{hotel[:currency]}"
    puts "---"
  end
rescue Tourvisor::UnexpectedResponseError => e
  puts "Failed to retrieve results: #{e.message}"
end
```

--------------------------------

### Check Tour Search Status

Source: https://context7.com/kimrgrey/tourvisor/llms.txt

Check the status of an ongoing search using the `status` method. The result is cached upon completion. Use `finished?` for a boolean check.

```ruby
require 'tourvisor'

Tourvisor.configure do |config|
  config.login = 'your_api_login'
  config.password = 'your_api_password'
end

request = Tourvisor::Request.new
request.search(departure: 1, country: 1, datefrom: '01.06.2024')

# Check if the search has finished
status = request.status
puts status
# => { state: "finished", progress: 100, ... }

# Use the convenience method to check completion
if request.finished?
  puts "Search completed!"
else
  puts "Search still in progress..."
end
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.