### Install Pricehubble Gem

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Instructions for adding the Pricehubble gem to your application's Gemfile and installing it using Bundler, or installing it directly via the gem command.

```ruby
gem 'pricehubble'
```

```bash
$ bundle

```

```bash
$ gem install pricehubble
```

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

### Configure Pricehubble Gem

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Example of configuring the Pricehubble gem using a Rails initializer. It covers setting authentication credentials, the base API URL, and logger options. The gem also supports configuration via environment variables.

```ruby
PriceHubble.configure do |conf|
  # Configure the API authentication credentials
  conf.username = 'your-username'
  conf.password = 'your-password'

  # The base URL of the API (there is no staging/canary
  # endpoint we know about)
  conf.base_url = 'https://api.pricehubble.com'

  # Writes to stdout by default, or use the Rails logger if present
  conf.logger = Logger.new(IO::NULL)

  # Enable request logging or not
  conf.request_logging = true
end
```

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

### Create Property Dossiers with Ruby

Source: https://context7.com/hausgold/pricehubble/llms.txt

Demonstrates how to create new property dossiers using the PriceHubble gem. It covers setting property details, valuations, and generating sharing links. Dependencies include the PriceHubble gem.

```ruby
dossier = PriceHubble::Dossier.new(
  title: 'Customer Dossier for Stresemannstr. 29',
  description: 'Best apartment in the city with excellent public transport connections',
  deal_type: :sale,
  country_code: 'DE',
  property: {
    location: {
      address: {
        post_code: '22769',
        city: 'Hamburg',
        street: 'Stresemannstr.',
        house_number: '29'
      }
    },
    property_type: { code: :apartment },
    building_year: 1990,
    living_area: 200
  },
  asking_sale_price: 600_000,  # Seller's minimum acceptable price

  # Optional: Override PriceHubble's calculated valuation
  valuation_override_sale_price: 650_000,
  valuation_override_reason_freetext: 'Recently renovated kitchen and bathrooms'

  # For rent dossiers:
  # valuation_override_rent_net: 2000,
  # valuation_override_rent_gross: 2500
)

dossier.save!

dossier.id

link = dossier.link(ttl: 365.days, locale: 'de_CH', lang: 'de')

link_en = dossier.link(ttl: 30.days, locale: 'en_GB', lang: 'en')
```

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

### Configure Apartment and House Property Types

Source: https://context7.com/hausgold/pricehubble/llms.txt

Illustrates how to define various apartment and house property types using codes and subcodes for detailed valuation. It also shows how to specify property conditions and qualities.

```ruby
# Apartment types
apartment_types = [
  { code: :apartment },                           # Generic apartment
  { code: :apartment, subcode: :apartment_normal },
  { code: :apartment, subcode: :apartment_maisonette },
  { code: :apartment, subcode: :apartment_attic },
  { code: :apartment, subcode: :apartment_penthouse },
  { code: :apartment, subcode: :apartment_terraced },
  { code: :apartment, subcode: :apartment_studio }
]

# House types
house_types = [
  { code: :house },                              # Generic house
  { code: :house, subcode: :house_detached },
  { code: :house, subcode: :house_semi_detached },
  { code: :house, subcode: :house_row_corner },
  { code: :house, subcode: :house_row_middle },
  { code: :house, subcode: :house_farm }
]

# Property conditions (for bathrooms, kitchen, flooring, windows, masonry)
conditions = [:renovation_needed, :well_maintained, :new_or_recently_renovated]

# Property qualities (for bathrooms, kitchen, flooring, windows, masonry)
qualities = [:simple, :normal, :high_quality, :luxury]

# Example with full property type
property = PriceHubble::Property.new(
  location: { address: { post_code: '8001', city: 'Zurich' } },
  property_type: { code: :apartment, subcode: :apartment_penthouse },
  building_year: 2010,
  living_area: 150,
  condition: { bathrooms: :new_or_recently_renovated, kitchen: :well_maintained },
  quality: { bathrooms: :luxury, kitchen: :high_quality }
)
```

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

### Perform a Bare Minimum Property Valuation Request

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Demonstrates how to initialize a ValuationRequest with property details and perform the request using the bang method to retrieve valuation data.

```ruby
valuations = PriceHubble::ValuationRequest.new(
  property: {
    location: {
      address: {
        post_code: '22769',
        city: 'Hamburg',
        street: 'Stresemannstr.',
        house_number: '29'
      }
    },
    property_type: { code: :apartment },
    building_year: 1990,
    living_area: 200
  }
).perform!
pp valuations.first.attributes.deep_compact
```

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

### Configure PriceHubble Ruby Client

Source: https://context7.com/hausgold/pricehubble/llms.txt

Demonstrates how to configure the PriceHubble Ruby client using a Rails initializer or environment variables. This includes setting API credentials, the base URL, and logging preferences. The configuration can be reset to default values.

```ruby
PriceHubble.configure do |conf|
  # Configure the API authentication credentials
  conf.username = 'your-username'
  conf.password = 'your-password'

  # The base URL of the API (defaults to production)
  conf.base_url = 'https://api.pricehubble.com'

  # Configure logging (defaults to stdout, or Rails.logger if available)
  conf.logger = Logger.new(IO::NULL) # disable logging

  # Enable or disable request logging (default: true)
  conf.request_logging = true
end

# Environment variable configuration
# PRICEHUBBLE_USERNAME: The API username for authentication
# PRICEHUBBLE_PASSWORD: The API password for authentication
# PRICEHUBBLE_BASE_URL: The base URL (defaults to https://api.pricehubble.com)

# Reset configuration to defaults
PriceHubble.reset_configuration!
```

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

### Request Rent Valuations

Source: https://context7.com/hausgold/pricehubble/llms.txt

Demonstrates how to request rental valuations instead of sale valuations. It shows the structure of a rent valuation request and how to access rent-specific values like gross and net rent.

```ruby
# Request rent valuation
valuations = PriceHubble::ValuationRequest.new(
  deal_type: :rent,
  property: {
    location: {
      address: {
        post_code: '22769',
        city: 'Hamburg',
        street: 'Stresemannstr.',
        house_number: '29'
      }
    },
    property_type: { code: :apartment },
    building_year: 1990,
    living_area: 200,
    is_furnished: true
  }
).perform!

valuation = valuations.first
puts valuation.deal_type.rent?   # => true
puts valuation.rent_gross        # => 2500 (monthly gross rent)
puts valuation.rent_gross_range  # => 2200..2800
puts valuation.rent_net          # => 2100 (monthly net rent)
puts valuation.rent_net_range    # => 1900..2400

# Generic value accessor works for both deal types
puts valuation.value       # => 2500 (rent_gross when deal_type is :rent)
puts valuation.value_range # => 2200..2800
```

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

### Build and Value a House Property

Source: https://context7.com/hausgold/pricehubble/llms.txt

Demonstrates how to create a house property object and perform a valuation request. It shows the creation of a detailed property object and a valuation request for multiple dates, followed by processing the results.

```ruby
house = PriceHubble::Property.new(
  location: {
    address: {
      post_code: '22769',
      city: 'Hamburg',
      street: 'Stresemannstr.',
      house_number: '31'
    }
  },
  property_type: { code: :house, subcode: :house_detached },
  building_year: 1985,
  land_area: 500,
  living_area: 250,
  number_of_floors_in_building: 2,
  has_pool: true,
  has_sauna: false,
  energy_label: 'B'
)

request = PriceHubble::ValuationRequest.new(
  deal_type: :sale,                    # or :rent
  country_code: 'DE',                  # DE, CH, AT, FR, NL, BE, etc.
  properties: [apartment, house],
  return_scores: true,                 # include quality/condition/location scores
  valuation_dates: [
    1.year.ago,
    Date.current,
    1.year.from_now
  ]
)
valuations = request.perform!

valuations.group_by(&:property).each do |property, vals|
  puts "#{property.property_type.code}: #{vals.map(&:value).join(', ')}"
end

valuation = valuations.first
puts valuation.scores.quality   # => 0.75
puts valuation.scores.condition # => 0.80
puts valuation.scores.location  # => 0.65
```

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

### Create Property Dossier

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

This endpoint allows you to create a new property dossier by providing detailed information about the property and the deal.

```APIDOC
## POST /dossiers

### Description
Creates a new property dossier with specified details.

### Method
POST

### Endpoint
/dossiers

### Parameters
#### Request Body
- **title** (string) - Required - The title of the dossier.
- **description** (string) - Optional - A description for the dossier.
- **deal_type** (string) - Required - The type of deal (e.g., :sale, :rent).
- **property** (object) - Required - An object containing property details.
  - **location** (object) - Required
    - **address** (object) - Required
      - **post_code** (string) - Required
      - **city** (string) - Required
      - **street** (string) - Required
      - **house_number** (string) - Required
  - **property_type** (object) - Required
    - **code** (string) - Required - The type of property (e.g., :apartment).
  - **building_year** (integer) - Optional - The year the building was constructed.
  - **living_area** (number) - Optional - The living area of the property in square meters.
- **country_code** (string) - Required - The country code of the property's location.
- **asking_sale_price** (number) - Optional - The asking price for a sale.
- **valuation_override_sale_price** (number) - Optional - Overrides the calculated sale price valuation.
- **valuation_override_rent_net** (number) - Optional - Overrides the calculated net rent valuation.
- **valuation_override_rent_gross** (number) - Optional - Overrides the calculated gross rent valuation.
- **valuation_override_reason_freetext** (string) - Optional - Reason for overriding valuation.

### Request Example
```json
{
  "title": "Customer Dossier for Stresemannstr. 29",
  "description": "Best apartment in the city",
  "deal_type": "sale",
  "property": {
    "location": {
      "address": {
        "post_code": "22769",
        "city": "Hamburg",
        "street": "Stresemannstr.",
        "house_number": "29"
      }
    },
    "property_type": { "code": "apartment" },
    "building_year": 1990,
    "living_area": 200
  },
  "country_code": "DE",
  "asking_sale_price": 600000
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created dossier.
- **link** (string) - A sharing link for the dossier.

#### Response Example
```json
{
  "id": "25de5429-244e-4584-b58e-b0d7428a2377",
  "link": "https://dash.pricehubble.com/shared/dossier/eyJ0eXAiOiJ..."
}
```
```

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

### Create and Save a PriceHubble Dossier

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

This snippet demonstrates how to define a property object with location and building details, instantiate a PriceHubble::Dossier, and persist it to the service. It returns the unique identifier for the created dossier.

```ruby
apartment = {
  location: {
    address: {
      post_code: '22769',
      city: 'Hamburg',
      street: 'Stresemannstr.',
      house_number: '29'
    }
  },
  property_type: { code: :apartment },
  building_year: 1990,
  living_area: 200
}

dossier = PriceHubble::Dossier.new(
  title: 'Customer Dossier for Stresemannstr. 29',
  description: 'Best apartment in the city',
  deal_type: :sale,
  property: apartment,
  country_code: 'DE',
  asking_sale_price: 600_000
)

dossier.save!
puts dossier.id
```

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

### Perform Simple Property Valuation Request

Source: https://context7.com/hausgold/pricehubble/llms.txt

Shows how to perform a basic property valuation request using the PriceHubble gem. It covers the minimal configuration required and how to access the returned valuation data, including value, currency, and property details.

```ruby
# Bare minimum valuation request for a single property
valuations = PriceHubble::ValuationRequest.new(
  property: {
    location: {
      address: {
        post_code: '22769',
        city: 'Hamburg',
        street: 'Stresemannstr.',
        house_number: '29'
      }
    },
    property_type: { code: :apartment },
    building_year: 1990,
    living_area: 200
  }
).perform!
# => [#<PriceHubble::Valuation currency="EUR" sale_price=1283400 ...>]

# Access the valuation result
valuation = valuations.first
valuation.value           # => 1283400 (sale price for sale deal type)
valuation.value_range     # => 1180800..1386100
valuation.currency        # => "EUR"
valuation.confidence.good? # => true
valuation.valuation_date  # => Thu, 17 Oct 2024
valuation.deal_type.sale? # => true

# Access nested property information
valuation.property.property_type.apartment? # => true
valuation.property.building_year            # => 1990
valuation.property.living_area              # => 200
```

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

### Execute Bulk Property Valuations

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Shows how to construct a complex request for multiple properties across different dates. It demonstrates grouping properties and processing the resulting valuation data into a table.

```ruby
apartment = PriceHubble::Property.new(
  location: { address: { post_code: '22769', city: 'Hamburg', street: 'Stresemannstr.', house_number: '29' } },
  property_type: { code: :apartment },
  building_year: 1990,
  living_area: 200
)

house = PriceHubble::Property.new(
  location: { address: { post_code: '22769', city: 'Hamburg', street: 'Stresemannstr.', house_number: '29' } },
  property_type: { code: :house },
  building_year: 1990,
  land_area: 100,
  living_area: 500
)

request = PriceHubble::ValuationRequest.new(
  deal_type: :sale,
  properties: [apartment, house],
  valuation_dates: [1.year.ago, Date.current, 1.year.from_now]
)
valuations = request.perform!
```

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

### Define Property Location with Address and Coordinates

Source: https://context7.com/hausgold/pricehubble/llms.txt

Shows different ways to specify a property's location, including using only an address, only coordinates, or a combination of both. It also demonstrates using entity objects for location data.

```ruby
# Location with address only
location_address = {
  location: {
    address: {
      post_code: '22769',
      city: 'Hamburg',
      street: 'Stresemannstr.',
      house_number: '29'
    }
  }
}

# Location with coordinates only
location_coords = {
  location: {
    coordinates: {
      latitude: 53.5511,
      longitude: 9.9937
    }
  }
}

# Location with both address and coordinates
location_full = {
  location: {
    address: {
      post_code: '22769',
      city: 'Hamburg',
      street: 'Stresemannstr.',
      house_number: '29'
    },
    coordinates: {
      latitude: 53.5511,
      longitude: 9.9937
    }
  }
}

# Using entity objects
location = PriceHubble::Location.new(
  address: PriceHubble::Address.new(
    post_code: '22769',
    city: 'Hamburg',
    street: 'Stresemannstr.',
    house_number: '29'
  ),
  coordinates: PriceHubble::Coordinates.new(
    latitude: 53.5511,
    longitude: 9.9937
  )
)
```

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

### Retrieving Valuation Data

Source: https://context7.com/hausgold/pricehubble/llms.txt

Shows how to extract valuation objects and clean their attributes for display or processing using the deep_compact method.

```ruby
valuation = valuations.first
valuation.attributes.deep_compact
```

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

### Create Advanced Property Valuation Request

Source: https://context7.com/hausgold/pricehubble/llms.txt

Illustrates how to construct a detailed property object for advanced valuation requests. This includes specifying numerous attributes like property type, condition, quality, and dimensions, supporting complex scenarios and bulk operations.

```ruby
# Build detailed apartment property
apartment = PriceHubble::Property.new(
  location: {
    address: {
      post_code: '22769',
      city: 'Hamburg',
      street: 'Stresemannstr.',
      house_number: '29'
    }
  },
  property_type: { code: :apartment, subcode: :apartment_penthouse },
  building_year: 1990,
  living_area: 200,
  balcony_area: 30,
  floor_number: 5,
  has_lift: true,
  is_furnished: false,
  is_new: false,
  renovation_year: 2014,
  number_of_rooms: 5,
  number_of_bathrooms: 2,
  condition: {
    bathrooms: :well_maintained,
    kitchen: :well_maintained,
    flooring: :well_maintained,
    windows: :well_maintained,
    masonry: :well_maintained
  },
  quality: {
    bathrooms: :normal,
    kitchen: :high_quality,
    flooring: :normal,
    windows: :normal,
    masonry: :normal
  }
)
```

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

### Generate Dossier Sharing Link

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Retrieves a public-facing URL for an existing dossier instance, allowing users to share the valuation report externally.

```ruby
puts dossier.link
```

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

### Authenticate with PriceHubble API

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Demonstrates how to obtain and manage authentication tokens for the PriceHubble API using the PriceHubble gem. The gem handles token refreshing and expiration transparently.

```ruby
# Fetch the authentication/identity for the first time, subsequent calls
# to this method will return the cached authentication instance until it
# is expired (or near expiration, 5 minutes leeway) then a new
# authentication is fetched transparently
PriceHubble.identity
# => #<PriceHubble::Authentication access_token="...", ...>

# Check the expiration state (transparently always unexpired)
PriceHubble.identity.expired?
# => false

# Get the current authentication expiration date/time
PriceHubble.identity.expires_at
# => 2019-10-17 08:01:23 +0000
```

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

### POST /valuation/perform

Source: https://context7.com/hausgold/pricehubble/llms.txt

Performs a valuation request for one or more properties, supporting both sale and rent deal types.

```APIDOC
## POST /valuation/perform

### Description
Calculates property valuations based on provided property details, location, and deal type. Supports batch processing for multiple properties and dates.

### Method
POST

### Endpoint
/valuation/perform

### Parameters
#### Request Body
- **deal_type** (string) - Required - Type of valuation: 'sale' or 'rent'.
- **country_code** (string) - Required - ISO country code (e.g., 'DE', 'CH').
- **properties** (array) - Required - List of property objects.
- **valuation_dates** (array) - Optional - List of dates for historical or future valuation.
- **return_scores** (boolean) - Optional - Whether to include quality, condition, and location scores.

### Request Example
{
  "deal_type": "sale",
  "country_code": "DE",
  "properties": [{
    "location": { "address": { "post_code": "22769", "city": "Hamburg" } },
    "property_type": { "code": "house", "subcode": "house_detached" },
    "living_area": 250
  }],
  "return_scores": true
}

### Response
#### Success Response (200)
- **valuations** (array) - List of valuation results containing value, range, and scores.

#### Response Example
{
  "value": 1824800,
  "value_range": [1700000, 1950000],
  "scores": { "quality": 0.75, "condition": 0.80, "location": 0.65 }
}
```

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

### Accessing and Cleaning Property Attributes

Source: https://context7.com/hausgold/pricehubble/llms.txt

Demonstrates how to retrieve property attributes while removing nil values using deep_compact and how to navigate nested associations like location and property type.

```ruby
property.attributes.deep_compact
property.location.address.city
property.property_type.code
property.property_type.apartment?
```

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

### Manage Property Dossiers with Ruby

Source: https://context7.com/hausgold/pricehubble/llms.txt

Shows how to update and delete existing property dossiers using the PriceHubble gem. It covers modifying attributes and removing dossiers. Requires an existing dossier ID.

```ruby
dossier = PriceHubble::Dossier.new(
  title: 'Property Evaluation',
  deal_type: :sale,
  country_code: 'DE',
  property: {
    location: { address: { post_code: '22769', city: 'Hamburg' } },
    property_type: { code: :apartment },
    building_year: 1990,
    living_area: 200
  }
)
dossier.save!

dossier.title = 'Updated Property Evaluation'
dossier.asking_sale_price = 550_000
dossier.save!

dossier.id.present?

dossier.delete!  # or dossier.destroy!

dossier.save    # => true/false
dossier.delete  # => dossier/false
dossier.link    # => "https://..." or nil
```

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

### Process Valuation Data with Valuation Entity

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Shows how to use the PriceHubble::Valuation entity to access helper methods like value, value_range, and confidence checks for processed valuation results.

```ruby
valuations = PriceHubble::ValuationRequest.new(...).perform!
valuation = valuations.first
valuation.value
valuation.value_range
valuation.confidence.good?
valuation.property.property_type.apartment?
```

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

### POST /valuations

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Request a valuation for one or more properties. Supports bulk operations and multiple valuation dates.

```APIDOC
## POST /valuations

### Description
Performs a valuation request for one or more properties. The API supports bulk requests and multiple valuation dates. Note that deal_type must be consistent across all properties in a single request.

### Method
POST

### Endpoint
/valuations

### Parameters
#### Request Body
- **deal_type** (string) - Required - The type of deal (e.g., :sale).
- **properties** (array) - Required - A list of property objects containing location, type, and physical attributes.
- **valuation_dates** (array) - Optional - A list of dates for which to calculate the valuation.

### Request Example
{
  "deal_type": "sale",
  "properties": [
    {
      "location": { "address": { "post_code": "22769", "city": "Hamburg" } },
      "property_type": { "code": "apartment" },
      "living_area": 200
    }
  ],
  "valuation_dates": ["2023-01-01"]
}

### Response
#### Success Response (200)
- **valuations** (array) - List of valuation results including value and currency.

#### Response Example
{
  "valuations": [
    { "value": 1373100, "currency": "EUR" }
  ]
}
```

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

### Dossier Creation API

Source: https://context7.com/hausgold/pricehubble/llms.txt

API endpoint for creating new property dossiers. Dossiers can include property details, valuations, and branding for customer sharing.

```APIDOC
## Dossier Creation

### Description
Create property dossiers for sharing with customers. Dossiers include property details, valuations, and customizable branding.

### Method
POST

### Endpoint
/dossiers

### Parameters
#### Request Body
- **title** (string) - Required - The title of the dossier.
- **description** (string) - Optional - A description for the dossier.
- **deal_type** (enum: :sale, :rent) - Required - The type of deal (sale or rent).
- **country_code** (string) - Required - The ISO 3166-1 alpha-2 country code.
- **property** (object) - Required - Details of the property.
  - **location** (object) - Required - Property location.
    - **address** (object) - Required - Property address.
      - **post_code** (string) - Required - Postal code.
      - **city** (string) - Required - City name.
      - **street** (string) - Optional - Street name.
      - **house_number** (string) - Optional - House number.
  - **property_type** (object) - Required - Type of property.
    - **code** (enum) - Required - Code representing the property type (e.g., :apartment).
  - **building_year** (integer) - Optional - The year the building was constructed.
  - **living_area** (integer) - Optional - The living area in square meters.
- **asking_sale_price** (number) - Optional - The seller's minimum acceptable price for sale.
- **valuation_override_sale_price** (number) - Optional - Override PriceHubble's calculated sale price.
- **valuation_override_reason_freetext** (string) - Optional - Reason for overriding the sale price.
- **valuation_override_rent_net** (number) - Optional - Override PriceHubble's calculated net rent.
- **valuation_override_rent_gross** (number) - Optional - Override PriceHubble's calculated gross rent.

### Request Example
```ruby
PriceHubble::Dossier.new(
  title: 'Customer Dossier for Stresemannstr. 29',
  description: 'Best apartment in the city with excellent public transport connections',
  deal_type: :sale,
  country_code: 'DE',
  property: {
    location: {
      address: {
        post_code: '22769',
        city: 'Hamburg',
        street: 'Stresemannstr.',
        house_number: '29'
      }
    },
    property_type: { code: :apartment },
    building_year: 1990,
    living_area: 200
  },
  asking_sale_price: 600_000,
  valuation_override_sale_price: 650_000,
  valuation_override_reason_freetext: 'Recently renovated kitchen and bathrooms'
)
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created dossier.
- **link** (string) - A URL to share the dossier.

#### Response Example
```json
{
  "id": "25de5429-244e-4584-b58e-b0d7428a2377",
  "link": "https://dash.pricehubble.com/shared/dossier/eyJ0eXAiOiJ...?lang=de"
}
```
```

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

### Handle Errors in PriceHubble Operations with Ruby

Source: https://context7.com/hausgold/pricehubble/llms.txt

Illustrates error handling strategies for PriceHubble operations using bang (!) and non-bang methods. Bang methods raise exceptions for specific errors like invalid entities or authentication failures, while non-bang methods return nil or false.

```ruby
begin
  valuations = PriceHubble::ValuationRequest.new(
    property: {
      location: { address: { post_code: '22769', city: 'Hamburg' } },
      property_type: { code: :apartment },
      building_year: 2999,  # Invalid: future year
      living_area: 200
    }
  ).perform!
rescue PriceHubble::EntityInvalid => e
  puts e.message
  puts e.entity
rescue PriceHubble::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
  puts e.response
rescue PriceHubble::EntityNotFound => e
  puts "Entity not found: #{e.message}"
  puts e.criteria
rescue PriceHubble::RequestError => e
  puts "Request failed: #{e.message}"
  puts e.response.status
end

valuations = PriceHubble::ValuationRequest.new(
  property: {
    location: { address: { post_code: '22769', city: 'Hamburg' } },
    property_type: { code: :apartment },
    building_year: 2999,
    living_area: 200
  }
).perform

valuations = PriceHubble::ValuationRequest.new(
  properties: [valid_property, invalid_property]
).perform!

valuations.each do |valuation|
  if valuation.status.present?
    puts "Error: #{valuation.status}"
  else
    puts "Value: #{valuation.value}"
  end
end
```

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

### Handle Valuation Errors in Ruby

Source: https://github.com/hausgold/pricehubble/blob/master/README.md

Demonstrates how to perform a single property valuation and rescue from PriceHubble::EntityInvalid exceptions. This is essential for capturing validation errors returned by the API.

```ruby
begin
  PriceHubble::ValuationRequest.new(
    property: {
      location: {
        address: {
          post_code: '22769',
          city: 'Hamburg',
          street: 'Stresemannstr.',
          house_number: '29'
        }
      },
      property_type: { code: :apartment },
      building_year: 2999,
      living_area: 200
    }
  ).perform!
rescue PriceHubble::EntityInvalid => e
  e.message
end
```

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

### Serialize Property Attributes with Ruby

Source: https://context7.com/hausgold/pricehubble/llms.txt

Explains how to access and serialize property entity attributes using the PriceHubble gem. It covers retrieving all attributes and sanitized attributes suitable for API integration.

```ruby
property = PriceHubble::Property.new(
  location: {
    address: { post_code: '22769', city: 'Hamburg', street: 'Stresemannstr.', house_number: '29' }
  },
  property_type: { code: :apartment },
  building_year: 1990,
  living_area: 200,
  floor_number: 5
)

property.attributes

property.attributes(sanitize: true)
```

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

### Handle PriceHubble Authentication

Source: https://context7.com/hausgold/pricehubble/llms.txt

Explains how the PriceHubble gem handles authentication transparently. It covers fetching the identity, checking expiration status, accessing the access token, and resetting the cached identity to force re-authentication.

```ruby
# Fetch the authentication/identity (cached and auto-refreshed)
identity = PriceHubble.identity
# => #<PriceHubble::Authentication access_token="...", expires_in=7200>

# Check expiration state (always unexpired due to auto-refresh)
identity.expired?
# => false

# Get the current authentication expiration date/time
identity.expires_at
# => 2024-01-15 10:30:00 +0000

# Access the raw access token if needed
identity.access_token
# => "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Reset the cached identity (forces re-authentication on next request)
PriceHubble.reset_identity!
```

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

### Entity Attributes and Serialization API

Source: https://context7.com/hausgold/pricehubble/llms.txt

API for accessing and serializing entity attributes, useful for data storage and integration.

```APIDOC
## Entity Attributes and Serialization

### Description
Access and serialize entity attributes for storage or API integration.

### Method
N/A (Instance methods on entity objects)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```ruby
# Create a property entity
property = PriceHubble::Property.new(
  location: {
    address: { post_code: '22769', city: 'Hamburg', street: 'Stresemannstr.', house_number: '29' }
  },
  property_type: { code: :apartment },
  building_year: 1990,
  living_area: 200,
  floor_number: 5
)
```

### Response
#### Success Response (Instance Methods)
- **attributes**: Returns all attributes of the entity as a hash.
- **attributes(sanitize: true)**: Returns sanitized attributes, formatted for API consumption (e.g., camelCase).

#### Response Example
```ruby
# Get all attributes
property.attributes
# => { "location" => { "address" => { ... } }, "property_type" => { "code" => :apartment }, ... }

# Get sanitized attributes for API
property.attributes(sanitize: true)
# => { "location" => { "address" => { ... } }, "propertyType" => { "code" => "apartment" }, ... }
```
```

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

### Error Handling API

Source: https://context7.com/hausgold/pricehubble/llms.txt

Details on how the API handles errors, including the use of bang and non-bang method variants for flexible error management.

```APIDOC
## Error Handling

### Description
The gem provides bang and non-bang method variants for flexible error handling. Bang methods raise exceptions; non-bang methods return nil/false on failure.

### Error Types
- **PriceHubble::EntityInvalid**: Raised when an entity fails validation.
- **PriceHubble::AuthenticationError**: Raised on authentication failures.
- **PriceHubble::EntityNotFound**: Raised when a requested entity cannot be found.
- **PriceHubble::RequestError**: Raised for general request errors (e.g., network issues, server errors).

### Usage with Bang Methods (Raises Exceptions)
```ruby
begin
  # Attempt an operation that might fail
  PriceHubble::ValuationRequest.new(...).perform!
rescue PriceHubble::EntityInvalid => e
  puts e.message
  puts e.entity # Access the invalid entity object
rescue PriceHubble::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
  puts e.response # Access the raw Faraday response
rescue PriceHubble::EntityNotFound => e
  puts "Entity not found: #{e.message}"
  puts e.criteria # Access the criteria used for the lookup
rescue PriceHubble::RequestError => e
  puts "Request failed: #{e.message}"
  puts e.response.status # Access the HTTP status code
end
```

### Usage with Non-Bang Methods (Returns nil/false)
```ruby
# Perform an operation without raising exceptions
result = PriceHubble::ValuationRequest.new(...).perform

if result.nil? || result == false
  puts "Operation failed."
else
  puts "Operation successful: #{result}"
end
```

### Handling Partial Errors in Bulk Operations
```ruby
# For bulk operations, individual items might have errors
valuations = PriceHubble::ValuationRequest.new(properties: [valid_property, invalid_property]).perform!

valuations.each do |valuation|
  if valuation.status.present?
    # This specific valuation has an error
    puts "Error for item: #{valuation.status}"
  else
    puts "Value for item: #{valuation.value}"
  end
end
```
```

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

### Dossier Management API

Source: https://context7.com/hausgold/pricehubble/llms.txt

API endpoints for updating and deleting existing property dossiers.

```APIDOC
## Dossier Management

### Description
Update and delete existing dossiers.

### Method
PUT /dossiers/{id}
DELETE /dossiers/{id}

### Endpoint
- **PUT /dossiers/{id}**: Updates an existing dossier.
- **DELETE /dossiers/{id}**: Deletes an existing dossier.

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the dossier to update or delete.

#### Request Body (for PUT)
- **title** (string) - Optional - The updated title of the dossier.
- **description** (string) - Optional - The updated description for the dossier.
- **asking_sale_price** (number) - Optional - The updated seller's minimum acceptable price for sale.

### Request Example (Update)
```ruby
# Assume 'dossier' is an existing PriceHubble::Dossier object
dossier.title = 'Updated Property Evaluation'
dossier.asking_sale_price = 550_000
dossier.save! # Sends the update request
```

### Request Example (Delete)
```ruby
# Assume 'dossier' is an existing PriceHubble::Dossier object
dossier.delete!
```

### Response
#### Success Response (200)
- For PUT: Returns the updated dossier object.
- For DELETE: Returns a success confirmation.

#### Response Example (Update)
```json
{
  "id": "25de5429-244e-4584-b58e-b0d7428a2377",
  "title": "Updated Property Evaluation",
  "asking_sale_price": 550000
}
```

#### Response Example (Delete)
```json
{
  "message": "Dossier deleted successfully."
}
```
```

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