# @socialhose/api

TypeScript SDK for the Socialhose Public API.

## Install

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

Node 18+ is required because the SDK uses the built-in `fetch`, `Response`, and `AbortSignal.timeout` APIs. 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);
```

## 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,
});
```

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.

## Endpoints

- `getCampaigns()`
- `getCampaign(id)`
- `getOverview(filters)`
- `getTimeline(filters)`
- `getSentiment(filters)`
- `getShareOfVoice(filters)`
- `getPlatforms(filters)`
- `getTopKeywords(filters)`
- `getTrending(filters)`
- `getTopMentions(filters)`
- `getMentions(filters)`
- `getMailingLists()`
- `inviteMailingListMember(listId, invite)`
- `get(path, params)` for lower-level GET access
- `post(path, body)` for lower-level POST access

## Filtering examples

```ts
await socialhose.getOverview({
  campaign_ids: 'campaign-id',
  date_from: '2026-05-01',
  date_to: '2026-05-29',
  platforms: 'twitter,reddit',
  sentiments: 'negative',
});

await socialhose.getTimeline({
  campaign_ids: 'campaign-id',
  interval: 'day',
});
```

## Next.js cache integration

Pass `revalidateSeconds` per request. In Next.js this is forwarded as `fetch(..., { next: { revalidate } })`; outside Next.js it is harmless.

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

## Errors

Failed requests throw `SocialhoseError` with `status`, `path`, and response `body` 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);
  }
}
```

## Publishing

```bash
pnpm test
pnpm typecheck
pnpm build
npm publish --access public --provenance
```