Related Skills Generator

# Implement the SharpAPI "Related Skills Generator" endpoint

You are adding an integration with SharpAPI's Related Skills Generator 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 a skill, this API returns related skills and their weights as float values ranging from 1.0 to 10.0, where 10 represents the highest relevance. This API is valuable for developers building skills assessment tools, career development platforms, or educational software. It helps in identifying complementary skills, enhancing skills matching algorithms, and supporting personalized learning paths. Use cases include creating skill recommendation engines, enhancing employee training programs, and improving career development resources. Only the `content` parameter is required. You can specify the language of the output, which defaults to `English`. You can limit the output with the `max_quantity` parameter.

## 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/hr/related_skills`
Related Skills
Request body: `application/json`
- `content` (string), e.g. `Laravel`
- `language` (string), e.g. `English`
Example:

```json
{
    "content": "Laravel",
    "language": "English"
}
```

### `GET https://sharpapi.com/api/v1/hr/parse_resume/job/status/{uuid}`
Related Skills - Job Results
- path parameter `uuid` (required), string, e.g. `"76650524-36f6-4062-9afa-de8fc6be4ebd"`

## 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": "bac70cd7-5347-4443-9632-c82019f73e9a",
        "type": "api_job_result",
        "attributes": {
            "type": "hr_related_skills",
            "result": {
                "skill": "Quicken",
                "related_skills": [
                    {
                        "name": "Accounting",
                        "weight": 8.7
                    },
                    {
                        "name": "Bookkeeping",
                        "weight": 7
                    },
                    {
                        "name": "Financial Management",
                        "weight": 6.8
                    }
                ]
            },
            "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