API Documentation

Implement a typed API client for the Connectively Business Plan API.

Base URL: https://connectively.us/api/external-users
Reference docs: https://connectively.us/api-integration/documentation/business

## Authentication
- Every endpoint except POST /login requires a JWT.
- Obtain a token via POST /login with a JSON body { "username": ..., "password": ... }. The token is returned in the `x-access-token` RESPONSE header, not the response body.
- Send that token in the `x-access-token` REQUEST header on all authenticated calls.
- Tokens expire after 24 hours — re-authenticate when a request returns 401.

## Endpoints
### Authentication
- POST /login — Authenticate external user
  Request body (application/json): { username: string (required), password: string (required, min 8 chars) }
  Returns: JWT token in x-access-token header

### Profiles
- POST /add-profile — Create a new profile
  Request body (multipart/form-data): { firstName: string (required), lastName: string (required), prefix: string (optional, max 20 chars), suffix: string (optional, max 50 chars), jobTitle: string (required), company: string (optional), companyWebsite: string (optional), identityLink: string (required) - LinkedIn URL, profileBlob: file (required) - JPEG/PNG/WebP, max 5MB, square, min 200x200px, optOut: string (required) - 'true' or 'false', clientEmail: string (optional) - email format }
  Returns: success, message, and profileId
- GET /profiles — Get user profiles
  Returns: profileList array with profileId, firstName, lastName, linkedinUrl, isActive, isFlagged, isUsed
- POST /edit-profile — Edit a profile
  Request body (multipart/form-data): { profileId: integer (required, min 1), firstName: string (optional) - queued for review, lastName: string (optional) - queued for review, prefix: string (optional, max 20 chars) - empty string clears, suffix: string (optional, max 50 chars) - empty string clears, jobTitle: string (optional), company: string (optional) - empty string clears, companyWebsite: string (optional) - empty string clears, identityLink: string (optional) - LinkedIn URL, queued for review, profileBlob: file (optional) - JPEG/PNG/WebP, max 5MB, square, min 200x200px, optOut: string (optional) - 'true' or 'false', clientEmail: string (optional) - email format, empty string clears }
  Returns: success, message, profileId, and pendingReview (fields awaiting staff approval)
- POST /deactivate-profile — Deactivate a profile
  Request body (application/json): { profileId: integer (required, min 1) }

### Questions
- GET /premium-question-list — Get premium questions
  Returns: array with featuredQuestionId, question, closeDate, openDate, domainAuthority, domainRating, agenticScore, attribution, sourceUrl, publicLink, mayCloseEarly, isHaroQuery, rejectsAi, categories
- POST /answer-question — Submit answer to a question
  Request body (application/json): { answer: string (required, 100-2500 chars), featuredQuestionId: integer (required, min 1), profileId: integer (required, min 1) }
  Returns: 'Success' as plain text

### Answers
- GET /submitted — Get submitted answers
  Query params: page (integer, optional, default 1) — Page number. 100 items per page; a page with fewer than 100 items is the last one.
  Returns: { submitted: [...] } — a plain array of up to 100 items for the requested page. No pagination metadata is returned.
- GET /selected — Get selected answers
  Query params: page (integer, optional, default 1) — Page number. 100 items per page; a page with fewer than 100 items is the last one.
  Returns: { note, selected: [...] } — a plain array of up to 100 items for the requested page. No pagination metadata is returned.
- GET /published — Get published answers
  Query params: page (integer, optional, default 1) — Page number. 100 items per page; a page with fewer than 100 items is the last one.
  Returns: { published: [...] } — a plain array of up to 100 items (each with publishDate, articleTitle, publishedLink) for the requested page. No pagination metadata is returned.
- GET /not-selected — Get not selected answers
  Query params: page (integer, optional, default 1) — Page number. 100 items per page; a page with fewer than 100 items is the last one.
  Returns: { notSelected: [...] } — a plain array of up to 100 items (each with discardedOn) for the requested page. No pagination metadata is returned.

### Opportunities
- GET /opportunities-list — Get media opportunities
  Returns: array with opportunity, mediaOutlet, source, createdAt, deadline, pitchUrl

### Subscription Management
- POST /add-seats — Add seats to subscription
  Request body (application/json): { addSeats: integer (required, min 1) }
  Returns: 'Success' as plain text

## Error handling
Handle these status codes:
- 400: validation error — surface the message
- 401: token missing/expired — re-authenticate and retry once
- 402: payment required — prompt to add seats
- 403: insufficient permissions
- 404: not found
- 409: conflict (e.g. duplicate)
- 429: rate limited — respect Retry-After / retryAfterSeconds and back off
- 500: server error — retry with backoff

## Requirements
- Use my project's language and HTTP conventions (default to TypeScript with fetch if unspecified).
- Expose one typed method per endpoint, with typed request and response models matching the fields above.
- Read credentials from environment variables; never hard-code them.
- Centralize auth: obtain and cache the token, attach the `x-access-token` header automatically, and transparently re-login on a 401.
- Add a small usage example showing login followed by one authenticated call.