Product Categorization

# Implement the SharpAPI "Product Categorization" endpoint

You are adding an integration with SharpAPI's 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

By providing the product name and its parameters, this API returns related categories and their weights as float values ranging from 1.0 to 10.0, where 10 represents the highest relevance. This API is highly useful for developers building e-commerce platforms, product catalogue management systems, or bulk product processing tools. It automates the categorization of products, ensuring accuracy and consistency. Use cases include populating product catalogue data, enhancing product search algorithms, and improving inventory management systems. You can set your preferred writing style by providing a `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 e-commerce categories). You can limit the output with the `max_quantity` parameter. Only the `content` parameter is required.

## 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/ecommerce/product_categories`
Product Categories
Request body: `application/json`
- `content` (string), e.g. `Razer Blade 16 Gaming Laptop: NVIDIA GeForce RTX 4090-13th Gen Intel 24-Core i9...`
- `language` (string), e.g. `English`
Example:

```json
{
    "content": "Razer Blade 16 Gaming Laptop: NVIDIA GeForce RTX 4090-13th Gen Intel 24-Core i9 HX CPU - 16\" Dual Mode Mini LED (4K UHD+ 120Hz & FHD+ 240Hz) - 32GB RAM - 2TB SSD - Compact GaN Charger - Windows 11",
    "language": "English"
}
```

### `GET https://sharpapi.com/api/v1/ecommerce/product_categories/job/status/{uuid}`
Product Categories  - Job Results
- path parameter `uuid` (required), string, e.g. `"6d3fec8c-34f8-4071-a5ba-af14910b4d77"`

## 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": "6d3fec8c-34f8-4071-a5ba-af14910b4d77",
        "type": "api_job_result",
        "attributes": {
            "type": "ecommerce_product_categories",
            "result": [
                {
                    "name": "Gaming Laptops",
                    "weight": 10
                },
                {
                    "name": "Razer Laptops",
                    "weight": 10
                },
                {
                    "name": "High-Performance Laptops",
                    "weight": 9.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