diff --git a/README.md b/README.md index 122d00b..7af9742 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,36 @@ Official SDKs 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 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? + +## What you can build + +Use Socialhose SDKs 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. + +## API access + +API access is available with paid Socialhose subscriptions. See [Socialhose pricing](https://socialhose.net/pricing) for current plans, or use a publicly provided API key if Socialhose offers one from time to time. + +API keys are provisioned by Socialhose or your account administrator. The SDKs consume existing keys; they do not create, rotate, or manage keys. + +Keep API keys server-side. Do not commit keys, expose them in frontend bundles, or send them to browsers. For browser applications, call Socialhose from your own backend and return only the data your frontend needs. + ## SDKs - `sdks/javascript` — npm package `@socialhose/api` @@ -10,7 +40,7 @@ Future SDKs can live beside it, e.g. `sdks/python`, `sdks/go`, or `sdks/php`. ## JavaScript / TypeScript -API keys are provisioned by Socialhose or your account administrator. Set the key server-side before using the SDK: +Set the key server-side before using the SDK: ```bash export SOCIALHOSE_API_KEY="sh_your_key_here" diff --git a/sdks/javascript/README.md b/sdks/javascript/README.md index e68e5ac..d471720 100644 --- a/sdks/javascript/README.md +++ b/sdks/javascript/README.md @@ -2,47 +2,24 @@ 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. +See the repository [API access notes](../../README.md#api-access) for subscription and key-provisioning details. This package consumes an existing key; it does not create keys, and there is no self-service key-generation flow documented here. 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: +1. Get a Socialhose API key with access to the campaigns you need to query. +2. Store it as a server-side environment variable: ```bash export SOCIALHOSE_API_KEY="sh_your_key_here" ``` -4. Pass it to the client: +3. Pass it to the client: ```ts const socialhose = new SocialhoseClient({ diff --git a/sdks/javascript/docs/API.md b/sdks/javascript/docs/API.md index 30a3764..c88c708 100644 --- a/sdks/javascript/docs/API.md +++ b/sdks/javascript/docs/API.md @@ -66,7 +66,7 @@ Type exports: ## Authentication -Socialhose API keys are provisioned by Socialhose or by your account administrator. This SDK consumes an existing key; it does not create or manage keys. +See the repository [API access notes](../../../README.md#api-access) for subscription and key-provisioning details. This SDK consumes an existing key; it does not create or manage keys. Every request sends: diff --git a/sdks/javascript/docs/GUIDE.md b/sdks/javascript/docs/GUIDE.md index c02de57..5ef73bd 100644 --- a/sdks/javascript/docs/GUIDE.md +++ b/sdks/javascript/docs/GUIDE.md @@ -22,9 +22,9 @@ Requires Node 18+ or a custom `fetch` implementation. ## Getting API access -Socialhose API keys are provisioned by Socialhose. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you. +See the repository [API access notes](../../../README.md#api-access) for subscription and key-provisioning details. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you. -Ask the Socialhose team or your account administrator for a Public API key and confirm which campaigns it can access. Then set it in your server environment: +Use your provided Public API key and confirm which campaigns it can access. Then set it in your server environment: ```bash export SOCIALHOSE_API_KEY="sh_your_key_here"