Mo Elzubeir
105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# @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:
|
|
|
|
```bash
|
|
npm publish --access public --provenance
|
|
```
|