sdk/sdks/javascript/README.md

# @socialhose/api

TypeScript SDK for the Socialhose Public API.

Use it from backend TypeScript/JavaScript to fetch campaigns, analytics, mentions, mailing lists, and SDK-composed entity analytics with authentication, retries, timeouts, and caching handled consistently.

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

## Documentation

- [Usage guide](./docs/GUIDE.md) — what the SDK is, setup, common workflows, 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, rate-limit guidance.
- [Caching and retries](./docs/CACHING_AND_RETRIES.md) — cache contract, retry policy, failure semantics.
- [Examples](./examples) — runnable TypeScript examples.

## 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.

## Main capabilities

- Campaign discovery: `getCampaigns()`, `getCampaign(id)`, `getCampaignIdByMatch(match)`.
- Analytics: `getOverview()`, `getTimeline()`, `getSentiment()`, `getShareOfVoice()`, `getPlatforms()`, `getTopKeywords()`, `getTrending()`, `getTopMentions()`.
- Mentions: `getMentions()` with campaign, date, platform, sentiment, text search, pagination, and ordering filters.
- Mailing lists: `getMailingLists()`, `inviteMailingListMember()`.
- Entity analytics: `getEntityBrief()`, `getEntityStats()`, `getEntityBriefs()`.
- Low-level access: `get(path, params)`, `post(path, body)`.
- Caching: built-in `MemoryCache`, disabling via `NoopCache`, or any custom `Cache` implementation.

## Entity analytics warning

Entity analytics fan out multiple `/mentions/` requests per term. Use `cacheTtlMs`, `revalidateSeconds`, or a persistent shared cache to stay under the approximate 60 req/min API-key rate limit.

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

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

## 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.