docs: expand JavaScript SDK documentation

2026-05-29 13:35:09 -05:00
parent 252ea713b1
commit c860cf6d88
11 changed files with 850 additions and 116 deletions
@@ -0,0 +1,85 @@
+# Entity Analytics
+
+Entity analytics are SDK-composed analytics for a single term, person, organization, hashtag, product, or incident.
+
+They exist because Socialhose analytics endpoints are campaign-scoped, while `/mentions/` supports `content_search` and returns an exact `count`.
+
+## `getEntityBrief()`
+
+`getEntityBrief(term, campaignId?)` performs one mention search ordered by engagement.
+
+It returns:
+
+- exact total mention count
+- top mention sample
+- sample-derived sentiment split
+- sample-derived platform mix
+- `exact` flag indicating whether the sample covers the full population
+
+This is cheap enough for grids, tables, and autocomplete-like entity lists.
+
+## `getEntityStats()`
+
+`getEntityStats(term, campaignId?)` expands a brief into a detail dashboard.
+
+It fetches:
+
+- engagement-ordered sample
+- newest mentions
+- sentiment facets
+- platform facets
+- cumulative date boundaries for a 14-day sparkline
+
+The first brief request is required. Subrequests are best-effort; failures return fallbacks instead of zeroing out the entity.
+
+## Accuracy safeguards
+
+### Sentiment reconciliation
+
+The SDK facets `/mentions/` by sentiment and accepts exact sentiment only when:
+
+```txt
+positive + negative + neutral === total
+```
+
+If the sum does not match, the SDK assumes a filter was ignored or misapplied and falls back to sample-derived sentiment.
+
+### Platform reconciliation
+
+The SDK facets `/mentions/` over known platform keys. If the platform facet sum exceeds the entity total, the SDK assumes the API ignored a filter and falls back to sample-derived platform mix.
+
+A sum below total is allowed because some mentions may be on platforms outside the SDK's known list.
+
+### Timeline cumulative differencing
+
+The SDK avoids adjacent `[date_from, date_to]` daily windows because inclusive `date_to` can double-count boundary days.
+
+Instead it requests cumulative counts with `date_from` only:
+
+```txt
+count(on/after day N) - count(on/after day N+1) = day N count
+```
+
+If the earliest cumulative count exceeds the known entity total, the SDK treats date-filtered `content_search` as untrustworthy and returns an empty sparkline rather than wrong bars.
+
+## Rate-limit guidance
+
+A single `getEntityStats()` can perform approximately:
+
+- 1 brief request
+- 1 recent request
+- 3 sentiment facet requests
+- 6 platform facet requests
+- 15 timeline boundary requests
+
+Use caching and keep batch concurrency low.
+
+Recommended pattern:
+
+```ts
+const stats = await socialhose.getEntityStats('cholera', campaignId, {
+  revalidateSeconds: 900,
+});
+```
+
+Use `getEntityBriefs()` for lists and call `getEntityStats()` only for selected detail views.