sdk/sdks/javascript/README.md

# @socialhose/api

Official TypeScript SDK for the Socialhose Public API.

Socialhose is a social-listening and media-monitoring API for turning large streams of public mentions into usable campaign intelligence. It helps backend applications answer questions like:

- What are people saying about a campaign, brand, organization, product, policy, person, or event?
- Which platforms are driving the conversation?
- Is sentiment improving or deteriorating?
- Which mentions have the most reach or engagement?
- Which keywords, topics, or entities are trending?
- Who should receive alerts or mailing-list updates?

The SDK wraps the Socialhose REST API with typed JavaScript/TypeScript methods for campaign discovery, analytics dashboards, mention search, mailing lists, and SDK-composed entity analytics. It handles API-key auth, browser-compatible headers, retries, timeouts, GET caching, and normalized response shapes so product code can focus on the analysis instead of raw HTTP plumbing.

## What you can build with it

Use `@socialhose/api` from server-side JavaScript/TypeScript to build:

- Social-listening dashboards for campaigns, topics, brands, people, organizations, or locations.
- Monitoring tools that search public mentions across supported platforms.
- Analytics views showing volume, reach, engagement, sentiment, platform mix, and growth.
- Trend and keyword reports.
- High-impact mention feeds ordered by recency or engagement.
- Entity pages that summarize one term/person/company/topic using mention-search facets.
- Alerting and mailing-list workflows backed by Socialhose mailing lists.
- Batch jobs, CLI scripts, or serverless functions that pull Socialhose data into another system.

This package is intended for **backend code only**. Do not ship your Socialhose API key to browsers.

## Getting an API key

API keys are issued by Socialhose. The SDK does not create keys, and there is no self-service key-generation flow documented in this package.

To use the SDK:

1. Request Socialhose Public API access from the Socialhose team or your account administrator.
2. Ask for an API key with access to the campaigns you need to query.
3. Store it as a server-side environment variable:

```bash
export SOCIALHOSE_API_KEY="sh_your_key_here"
```

4. Pass it to the client:

```ts
const socialhose = new SocialhoseClient({
  apiKey: process.env.SOCIALHOSE_API_KEY!,
});
```

Do not commit API keys, expose them in frontend bundles, or send them to browsers. If you are building a web app, call Socialhose from your server/API route and return only the data your frontend needs.

## Install

```bash
npm install @socialhose/api
```

Node 18+ is required because the SDK uses built-in `fetch`, `Response`, and `AbortSignal.timeout`. You can pass a custom `fetch` implementation if needed.

## Quickstart

```ts
import { SocialhoseClient } from '@socialhose/api';

const socialhose = new SocialhoseClient({
  apiKey: process.env.SOCIALHOSE_API_KEY!,
});

const mentions = await socialhose.getMentions({
  content_search: 'hospital',
  platforms: 'twitter',
  ordering: '-published_at',
});

console.log(mentions.count, mentions.results[0]?.content);
```

## Core capabilities

### Campaign discovery

Campaigns are the API's top-level monitoring containers. Use them to discover what this API key can access, resolve IDs, and scope analytics or mention search.

```ts
const campaigns = await socialhose.getCampaigns();
const campaign = await socialhose.getCampaign(campaigns[0].id);
```

Related methods:

- `getCampaigns()` — fetches the first page of accessible campaigns.
- `getCampaign(id)` — fetches one campaign by ID.
- `getCampaignIdByMatch(match)` — convenience helper that finds a campaign ID by case-insensitive name substring.

### Analytics dashboards

Analytics methods summarize campaign performance and conversation health.

```ts
const filters = {
  campaign_ids: 'campaign-id',
  date_from: '2026-05-01',
  date_to: '2026-05-29',
};

const [overview, timeline, sentiment, platforms] = await Promise.all([
  socialhose.getOverview(filters),
  socialhose.getTimeline({ ...filters, interval: 'day' }),
  socialhose.getSentiment(filters),
  socialhose.getPlatforms(filters),
]);
```

Analytics methods include:

- `getOverview()` — total mentions, authors, estimated reach, sentiment distribution, platform breakdown, engagement, and growth.
- `getTimeline()` — time-series mention volume with sentiment and engagement buckets.
- `getSentiment()` — aggregate and platform-specific sentiment splits.
- `getShareOfVoice()` — compares campaigns by mention share, engagement, and sentiment.
- `getPlatforms()` — mention and engagement totals grouped by platform.
- `getTopKeywords()` — most frequent keywords with sentiment split.
- `getTrending()` — keywords whose volume changed against the previous period.
- `getTopMentions()` — high-impact mentions with reach, engagement, author, URL, and content preview.

### Mention search

Mentions are the underlying public posts/articles/items Socialhose has collected and classified. Search them by campaign, date, platform, sentiment, content, page, and ordering.

```ts
const page = await socialhose.getMentions({
  campaign_ids: 'campaign-id',
  content_search: 'ozempic',
  platforms: 'twitter,reddit',
  sentiments: 'negative',
  ordering: '-engagement_count',
});

console.log(page.count);
for (const mention of page.results) {
  console.log(mention.platform, mention.sentiment, mention.url);
}
```

Use this for feeds, search results, moderation queues, source inspection, custom reports, or downstream enrichment.

### Entity analytics

Entity helpers build analytics around one search term even when native analytics endpoints are campaign-scoped. They use `/mentions/` facets to produce compact profiles for people, organizations, brands, products, places, hashtags, or arbitrary terms.

```ts
const stats = await socialhose.getEntityStats('RSF', 'campaign-id', {
  revalidateSeconds: 900,
});

console.log({
  total: stats.total,
  sentiment: stats.sentiment,
  platformMix: stats.platformMix,
  momentumPct: stats.momentumPct,
  topUrls: stats.sample.slice(0, 3).map((m) => m.url),
});
```

Entity methods:

- `getEntityBrief(term, campaignId?)` — one request for count plus a top-engagement sample; derives sentiment and platform mix from the sample.
- `getEntityStats(term, campaignId?)` — richer entity profile with exact facet reconciliation, newest mentions, daily sparkline, and momentum.
- `getEntityBriefs(terms, campaignId?, concurrency?)` — batch entity cards with bounded concurrency.

Entity analytics can fan out many requests. Use caching and conservative concurrency for production dashboards.

### Mailing lists

Mailing-list helpers support Socialhose alert/recipient workflows.

```ts
const lists = await socialhose.getMailingLists();

const result = await socialhose.inviteMailingListMember(lists[0].id, {
  email: 'analyst@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});
```

Methods:

- `getMailingLists()` — fetches first-page mailing-list metadata.
- `inviteMailingListMember()` — invites a recipient and normalizes `201` and `409` outcomes into `invited` or `already`.

### Low-level access

If the SDK does not yet expose a typed helper for an endpoint, use authenticated low-level methods:

```ts
const raw = await socialhose.get('/mentions/', {
  page: 1,
  content_search: 'cholera',
});

const created = await socialhose.post('/some-endpoint/', { value: true });
```

- `get<T>(path, params?, options?)` — authenticated cached GET with query serialization.
- `post<T>(path, body, options?)` — authenticated JSON POST, never cached.

## Configuration

```ts
const socialhose = new SocialhoseClient({
  apiKey: process.env.SOCIALHOSE_API_KEY!,
  baseUrl: 'https://socialhose.net/api/public/v1',
  timeoutMs: 8_000,
  retries: 3,
  cacheTtlMs: 60_000,
});
```

Important options:

- `apiKey` — required Socialhose API key. Missing keys fail on the first request.
- `baseUrl` — defaults to `https://socialhose.net/api/public/v1`.
- `timeoutMs` — per-attempt timeout. Default: `8000`.
- `retries` — retry count for network failures, timeouts, `429`, and `5xx`. Default: `3`.
- `cacheTtlMs` — default GET cache TTL in milliseconds. Default: `60000`; set `0` to disable built-in memory caching.
- `cache` — custom cache implementation, e.g. Redis or a platform cache.
- `fetch` — custom fetch for tests, instrumentation, or non-standard runtimes.
- `defaultHeaders` — extra headers sent with every request.

The SDK sends `Authorization: Api-Key <key>` and a browser-like `User-Agent` by default. The user-agent is intentional: the current Socialhose API edge rejects some non-browser requests.

## Caching, retries, and failure behavior

- GET requests are cached by full URL.
- POST requests are never cached.
- Default cache is process-local `MemoryCache`.
- `NoopCache` disables storage.
- Custom caches implement `Cache#get`, `Cache#set`, and `Cache#delete`.
- `revalidateSeconds` overrides TTL per request.
- Non-positive TTL means “do not cache”.
- Transient failures are retried: network errors, timeouts, `429`, and `5xx`.
- Client errors such as `400`, `401`, `403`, and `404` are not retried.

```ts
await socialhose.getMentions(
  { content_search: 'sudan' },
  { revalidateSeconds: 900 },
);
```

For multi-process, serverless, or high-traffic dashboards, inject a shared cache instead of relying on the default in-memory cache.

## Errors

Failed requests throw `SocialhoseError` with `status`, `path`, `body`, and `cause` when available.

```ts
import { SocialhoseError } from '@socialhose/api';

try {
  await socialhose.getCampaign('missing');
} catch (error) {
  if (error instanceof SocialhoseError) {
    console.error(error.status, error.path, error.body);
  }
}
```

## Documentation

- [Usage guide](./docs/GUIDE.md) — setup, workflows, filtering, pagination, caching, and operational guidance.
- [API reference](./docs/API.md) — every public class, function, method, option, and exported type.
- [Entity analytics](./docs/ENTITY_ANALYTICS.md) — how term-level analytics are built, accuracy safeguards, and rate-limit guidance.
- [Caching and retries](./docs/CACHING_AND_RETRIES.md) — cache contract, retry policy, request lifecycle, and failure semantics.
- [Examples](./examples) — runnable TypeScript examples.

## Development

```bash
pnpm install
pnpm test
pnpm typecheck
pnpm build
```

Publishing:

Preferred publish path is the release workflow, which runs with npm provenance from CI. Before publishing, verify npm authentication and `@socialhose` scope access:

```bash
npm whoami
npm publish --dry-run --access public --provenance
```

For the actual release, publish from CI with provenance enabled. If you must publish locally, first confirm whether npm provenance is supported in that environment.