Hospitality Product Categorization

# Implement the SharpAPI "Hospitality Product Categorization" endpoint

You are adding an integration with SharpAPI's Hospitality Product Categorization API to this codebase. This brief is an alternative to the official SharpAPI SDKs (PHP/Laravel, JavaScript/Node, Python, Flutter, .NET): it describes everything needed to call the API directly over HTTP. If the project already uses a SharpAPI SDK, use the SDK instead.

## What it does

Generates a a list of suitable categories for the Hospitality type product with relevance weights as float value (1.0-10.0) where 10 equals 100%, the highest relevance score. By providing the product name and its parameters, this API delivers the best category matches possible. It is highly useful for populating product catalogues and processing bulk products efficiently. Ideal for developers working on travel platforms, hotel booking systems, or hospitality marketplaces. It streamlines the categorization of hospitality products, ensuring accuracy and enhancing searchability. Use cases include categorizing new hotel listings, improving the organization of hospitality offerings, and providing users with relevant category suggestions for a better experience. The weights are provided as float values (1.0-10.0) where 10 equals 100%, the highest relevance score. Only the `content` parameter is required. You can limit the output with the `max_quantity` parameter. You can set your preferred writing style by providing an optional `voice_tone` parameter. It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. Within an additional optional parameter `context`, you can provide a list of other categories that will be taken into consideration during the mapping process (for example your current categories).

## Authentication and base URL

- Base URL: `https://sharpapi.com/api/v1`
- Send `Authorization: Bearer <API key>`, `Accept: application/json` and a `User-Agent` that names your app on every request.
- Read the API key from configuration or an environment variable (for example `SHARPAPI_API_KEY`). Never hard-code or commit it. The key is in the SharpAPI dashboard: https://sharpapi.com/dashboard

## Endpoints

### `POST https://sharpapi.com/api/v1/tth/hospitality_product_categories`
Hospitality Product Categories
Request body: `application/json`
- `city` (string), e.g. `Tokyo`
- `content` (string), e.g. `Hotel Crystal 大人専用`
- `country` (string), e.g. `Japan`
- `language` (string), e.g. `English`
Example:

```json
{
    "city": "Tokyo",
    "content": "Hotel Crystal 大人専用",
    "country": "Japan",
    "language": "English"
}
```

### `GET https://sharpapi.com/api/v1/tth/hospitality_product_categories/job/status/{uuid}`
Hospitality Product Categories - Job Results
- path parameter `uuid` (required), string, e.g. `"afb7cc23-23a5-479c-92a9-be983792dabc"`

## Asynchronous job flow

This is an asynchronous AI endpoint. Mirror the official SDK client:

1. POST the request. The API answers `202 Accepted` with `{"job_id": "...", "status_url": "..."}` (the `Location` header holds the same URL).
2. GET `status_url` with the same headers. While `data.attributes.status` is `new` or `pending`, wait the number of seconds in the `Retry-After` header (10 seconds if it is missing) and poll again.
3. Stop when the status is `success` or `failed`. The result is in `data.attributes.result`, already decoded as JSON.
4. A `failed` job is a normal response, not an HTTP error: report it to the caller as a failure.
5. Give up after 180 seconds of polling in total and surface a timeout error.

Run the whole flow in a background job or queue, never inside a web request. SharpAPI can also call your own webhook when a job finishes (Dashboard → Webhooks), which avoids polling.

## Successful job result

```json
{
    "data": {
        "id": "afb7cc23-23a5-479c-92a9-be983792dabc",
        "type": "api_job_result",
        "attributes": {
            "type": "tth_hospitality_product_categories",
            "result": [
                {
                    "name": "Adult Only Hotels",
                    "weight": 10
                },
                {
                    "name": "Luxury Hotels",
                    "weight": 8.5
                },
                {
                    "name": "Boutique Hotels",
                    "weight": 7.5
                }
            ],
            "status": "success"
        }
    }
}
```

## Errors to handle

- `401` 401 Unauthorized: "Unauthorized"
- `402` 402 Payment Required: "You have exceeded your monthly words quota [1694]. Please login to the dashboard and increase number of credits."
- `404` 404 Not Found: "Resource Not Found"
- `422` 422 Unprocessable Content: "The content field is required."
- `429` 429 Too Many Requests: "Too Many Attempts."
- `500` 500 Internal Server Error: "Server Error"
- `503` 503 Service Unavailable: "Service Unavailable"
- `429`: rate limited. Wait the `Retry-After` seconds and retry, at most 3 times.
- `402`: the word quota is used up. Do not retry; tell the user to add credits or upgrade.
- `5xx`: retry later with backoff.

## Implementation rules
- Wrap the calls in one small client or service with a typed method for this endpoint, and map the result to a typed object or DTO.
- Track `X-RateLimit-Limit` and `X-RateLimit-Remaining`. When the remaining count drops to 3 or below, slow down (double the polling interval).
- `GET https://sharpapi.com/api/v1/ping` checks connectivity and `GET https://sharpapi.com/api/v1/quota` returns the remaining words: use them for a health check.
- Write tests with the HTTP layer mocked: success, `pending` then `success`, `failed` job, `422` validation error, `429` retry, and a missing API key.
- Full API reference: https://sharpapi.com/documentation