sdk/sdks/javascript/docs/API.md

# API Reference

Public API reference for `@socialhose/api`, the TypeScript SDK for the Socialhose Public API.

The SDK is intended for server-side JavaScript/TypeScript. It authenticates requests with an API key, wraps Socialhose REST endpoints, normalizes common response shapes, retries transient failures, applies request timeouts, and caches GET responses.

## Common imports

```ts
import {
  SocialhoseClient,
  createSocialhoseClient,
  SocialhoseError,
  MemoryCache,
  NoopCache,
  type Cache,
  type SocialhoseClientOptions,
  type RequestOptions,
  type AnalyticsFilters,
  type MentionFilters,
  type Mention,
  type Paginated,
  type EntityBrief,
  type EntityStats,
} from '@socialhose/api';
```

## Public exports

Runtime exports:

- `SocialhoseClient`
- `createSocialhoseClient`
- `SocialhoseError`
- `MemoryCache`
- `NoopCache`

Type exports:

- `AnalyticsFilters`
- `Cache`
- `Campaign`
- `EntityBrief`
- `EntityStats`
- `InviteOutcome`
- `InviteResult`
- `KeywordStat`
- `MailingList`
- `MailingListInvitation`
- `Mention`
- `MentionFilters`
- `Overview`
- `Paginated`
- `PlatformShare`
- `PlatformStat`
- `QueryParams`
- `QueryValue`
- `RequestOptions`
- `Sentiment`
- `SentimentSplit`
- `ShareOfVoiceItem`
- `SocialhoseClientOptions`
- `TimelinePoint`
- `TopMention`
- `TrendingItem`

## Authentication

Socialhose API keys are provisioned by Socialhose or by your account administrator. This SDK consumes an existing key; it does not create or manage keys.

Every request sends:

- `Authorization: Api-Key <apiKey>`
- `Accept: application/json`
- a browser-like `User-Agent` by default
- `Content-Type: application/json` for `POST`

Do not use this SDK directly in browser code. Keep `SOCIALHOSE_API_KEY` on the server.

## `SocialhoseClientOptions`

Configuration object for `new SocialhoseClient(options)` and `createSocialhoseClient(options)`.

- `apiKey: string` — Socialhose API key. Required; empty strings fail on first request.
- `baseUrl?: string` — API root. Default: `https://socialhose.net/api/public/v1`.
- `userAgent?: string` — request user-agent. Default is Chrome-like because the API edge may reject generic Node clients.
- `fetch?: typeof fetch` — custom fetch implementation for tests, instrumentation, or runtimes without global fetch.
- `timeoutMs?: number` — per-attempt timeout. Default: `8000`.
- `retries?: number` — retry count after the first attempt. Default: `3`.
- `retryDelayMs?: (attempt: number) => number` — retry backoff function. Default: exponential backoff with jitter.
- `cacheTtlMs?: number` — default GET cache TTL in milliseconds. Default: `60000`; set `0` to disable the built-in memory cache.
- `cache?: Cache` — custom cache implementation. If supplied, it replaces the internal cache.
- `defaultHeaders?: Record<string, string>` — extra headers sent with every request.

## `RequestOptions`

Per-request options.

- `revalidateSeconds?: number` — override cache TTL for this call, in seconds. Passed only to `Cache.set`; not sent to the API.
- `signal?: AbortSignal` — caller abort signal combined with the SDK timeout.
- `headers?: Record<string, string>` — request-specific headers.

## `new SocialhoseClient(options)`

Creates an authenticated API client.

```ts
const socialhose = new SocialhoseClient({
  apiKey: process.env.SOCIALHOSE_API_KEY!,
  timeoutMs: 8_000,
  retries: 3,
  cacheTtlMs: 60_000,
});
```

## `createSocialhoseClient(options)`

Factory wrapper around the constructor.

```ts
const socialhose = createSocialhoseClient({ apiKey });
```

Returns `SocialhoseClient`.

## Low-level HTTP methods

### `client.get<T>(path, params?, options?)`

Performs an authenticated cached GET request.

- `path: string` — endpoint path, with or without leading slash.
- `params?: QueryParams` — query parameters. `undefined`, `null`, and `''` values are omitted.
- `options?: RequestOptions` — cache TTL, abort signal, and extra headers.

Returns `Promise<T>`.

Behavior:

- Builds the URL from `baseUrl`, `path`, and `params`.
- Uses the full URL as the cache key.
- Retries network errors, timeouts, `429`, and `5xx` responses.
- Throws `SocialhoseError` for non-OK responses after retries.

### `client.post<T>(path, body, options?)`

Performs an authenticated JSON POST request.

- `path: string` — endpoint path.
- `body: unknown` — JSON-serialized request body.
- `options?: RequestOptions` — abort signal and extra headers.

Returns `Promise<{ status: number; data: T | null }>`.

Behavior:

- Never uses the GET cache.
- Sends `Content-Type: application/json`.
- Returns the HTTP status so higher-level methods can normalize status-specific outcomes.
- Lets POST `409` responses through for conflict normalization.

## Campaign methods

### `client.getCampaigns(options?)`

Fetches first-page campaigns.

Endpoint: `GET /campaigns/?page=1`

Returns `Promise<Campaign[]>`.

Use it to list accessible campaigns or populate campaign selectors. The helper reads page 1 only; use `get<Paginated<Campaign>>()` for manual pagination.

### `client.getCampaign(id, options?)`

Fetches one campaign by ID.

Endpoint: `GET /campaigns/{id}/`

Returns `Promise<Campaign>`.

Throws `SocialhoseError` when the campaign is missing or inaccessible.

### `client.getCampaignIdByMatch(match, options?)`

Returns the first campaign ID whose name contains `match`, case-insensitively.

Returns `Promise<string | undefined>`.

If campaign fetching fails or no campaign matches, returns `undefined`. Use exact IDs when names may collide.

## Analytics filters

`AnalyticsFilters` are passed through as query params:

- `campaign_ids?: string` — one ID or comma-separated IDs.
- `date_from?: string` — lower date bound, commonly `YYYY-MM-DD`.
- `date_to?: string` — upper date bound, commonly `YYYY-MM-DD`.
- `platforms?: string` — platform or comma-separated platforms.
- `sentiments?: string` — sentiment or comma-separated sentiments.

## Analytics methods

### `client.getOverview(filters?, options?)`

Endpoint: `GET /analytics/overview/`

Returns `Promise<Overview>` with total mentions, authors, estimated reach, sentiment distribution, platform breakdown, engagement, and growth metrics.

The SDK coerces `total_mentions` and `total_authors` to numbers because some API responses may return numeric strings.

### `client.getTimeline(filters?, options?)`

Endpoint: `GET /analytics/timeline/`

Filters include `interval?: 'day' | 'week' | 'month'`, defaulting to `day`.

Returns `Promise<TimelinePoint[]>`. If the API response lacks `series`, returns `[]`.

### `client.getSentiment(filters?, options?)`

Endpoint: `GET /analytics/sentiment/`

Returns `Promise<{ distribution: SentimentSplit; by_platform: Record<string, SentimentSplit> }>`.

### `client.getShareOfVoice(filters?, options?)`

Endpoint: `GET /analytics/share-of-voice/`

Returns `Promise<{ total_mentions: number; campaigns: ShareOfVoiceItem[] }>`.

Each campaign row includes mention count, share percentage, engagement, and sentiment.

### `client.getPlatforms(filters?, options?)`

Endpoint: `GET /analytics/platforms/`

Returns `Promise<PlatformStat[]>`. If the API response lacks `platforms`, returns `[]`.

### `client.getTopKeywords(filters?, options?)`

Endpoint: `GET /analytics/top-keywords/`

Filters include `limit?: number`, defaulting to `12`.

Returns `Promise<KeywordStat[]>`. If the API response lacks `keywords`, returns `[]`.

### `client.getTrending(filters?, options?)`

Endpoint: `GET /analytics/trending/`

Filters include `limit?: number`, defaulting to `8`.

Returns `Promise<TrendingItem[]>`. If the API response lacks `trending`, returns `[]`.

### `client.getTopMentions(filters?, options?)`

Endpoint: `GET /analytics/top-mentions/`

Filters include `limit?: number`, defaulting to `6`.

Returns `Promise<TopMention[]>`. If the API response lacks `mentions`, returns `[]`.

## Mention methods

### `client.getMentions(filters?, optionsOrRevalidate?)`

Endpoint: `GET /mentions/`

Returns `Promise<Paginated<Mention>>`.

`MentionFilters` include all `AnalyticsFilters` plus:

- `page?: number` — page number, defaulting to `1`.
- `content_search?: string` — text search term.
- `ordering?: string` — sort key, such as `-published_at` or `-engagement_count`.

The second argument may be `RequestOptions` or the legacy shorthand `number` for `revalidateSeconds`.

## Mailing-list methods

### `client.getMailingLists(options?)`

Endpoint: `GET /mailing-lists/?page=1`

Returns `Promise<MailingList[]>` from the first page.

### `client.inviteMailingListMember(listId, invite, options?)`

Endpoint: `POST /mailing-lists/{listId}/members/`

`invite` fields:

- `email: string`
- `first_name?: string`
- `last_name?: string`
- `invitation_message?: string`

Returns `Promise<InviteResult>`:

- `{ outcome: 'invited', invitation }` for `201` plus `status: 'invited'`.
- `{ outcome: 'already', detail }` for `409` conflicts.
- `{ outcome: 'error', detail }` for unexpected successful/conflict response shapes.

Other non-OK statuses throw `SocialhoseError`.

## Entity analytics methods

Entity analytics are SDK-composed views built on `/mentions/` with `content_search`. They provide term/person/org/topic analytics when native analytics endpoints are campaign-scoped.

### `client.getEntityBrief(term, campaignId?, options?)`

Runs one mention search ordered by engagement.

Returns `Promise<EntityBrief>`:

- `term` — requested search term.
- `total` — exact API count.
- `exact` — true when the sample covers the full population.
- `sentiment` — sample-derived sentiment split.
- `platformMix` — sample-derived platform counts.
- `sample` — first page ordered by engagement.

`total` is exact. Sentiment and platform mix are exact only when `exact` is true.

### `client.getEntityStats(term, campaignId?, options?)`

Builds a richer dashboard for one term.

Returns `Promise<EntityStats>` with `EntityBrief` fields plus:

- `recent` — newest mentions.
- `recent7d` — latest seven-day count from the sparkline.
- `prev7d` — previous seven-day count.
- `momentumPct` — seven-day percentage change, or `null` if not computable.
- `sparkline` — daily counts for the last 14 days when date faceting is trustworthy.

Failure model:

- The initial brief must succeed.
- Follow-up subrequests are best-effort.
- Exact facets are used only when reconciliation checks pass; otherwise sample-derived values are retained.

### `client.getEntityBriefs(terms, campaignId?, concurrency?, options?)`

Fetches many entity briefs with bounded concurrency.

Returns `Promise<Map<string, EntityBrief>>`.

Failed terms are omitted from the map. Default concurrency is `20`; reduce it under rate limits.

## Cache API

### `Cache`

```ts
interface Cache {
  get(key: string): Promise<unknown | undefined>;
  set(key: string, value: unknown, ttlMs: number): Promise<void>;
  delete(key: string): Promise<void>;
}
```

The key is the full GET URL. `get()` returns `undefined` on cache miss. `ttlMs` is in milliseconds.

### `MemoryCache`

In-memory `Map` cache with per-entry TTL. Good for tests, scripts, and single-process services. Not enough for distributed rate-limit protection.

### `NoopCache`

Cache implementation that never stores values. Use it to force fresh data or disable caching explicitly.

### `client.clearCache()`

Deletes cache keys used by the current client instance. It is not a global purge for shared cache backends.

## `SocialhoseError`

Structured request failure.

Fields:

- `name: 'SocialhoseError'`
- `status?: number`
- `path: string`
- `body?: string`
- `cause?: unknown`

Thrown after retry exhaustion or unsupported non-OK HTTP responses.

## Core data types

- `Sentiment` — `'positive' | 'negative' | 'neutral'`.
- `SentimentSplit` — `{ positive: number; negative: number; neutral: number }`.
- `Paginated<T>` — `{ count, next, previous, results }`.
- `Campaign` — campaign metadata.
- `Overview` — aggregate analytics.
- `TimelinePoint` — one time-series bucket.
- `ShareOfVoiceItem` — campaign comparison row.
- `PlatformStat` — platform count and engagement.
- `KeywordStat` — keyword count and sentiment.
- `TrendingItem` — keyword momentum.
- `TopMention` — compact high-impact mention.
- `Mention` — full mention record with content, engagement, metadata, and author profile.
- `MailingList` — mailing-list metadata.
- `MailingListInvitation` — mailing-list invitation state.
- `InviteResult` — normalized invite result.
- `PlatformShare` — entity analytics platform count.
- `EntityBrief` — compact term analytics.
- `EntityStats` — full term dashboard.