TypeScript SDK

The official TypeScript SDK wraps the BrightBean REST API. Async-only, typed interfaces, every endpoint covered. Requires Node 18+. Ships ESM + CommonJS + type declarations.

• Package: brightbean on npm
• Source: github.com/JanSchm/social-intelligence-app/tree/main/sdks/typescript
• Default base URL: https://api.brightbean.xyz (override with apiUrl or BRIGHTBEAN_API_URL)

Install

npm install brightbean

Quickstart

import { BrightBean } from "brightbean";

const client = new BrightBean({ apiKey: "bb_..." });

const result = await client.score({
  title: "10 Tips to Boost Your Coding Productivity",
  thumbnailUrl: "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
});

console.log(result.score, result.percentile, result.niche_label);

The constructor reads BRIGHTBEAN_API_KEY from process.env if apiKey is omitted. Input fields are camelCase for ergonomics; response fields are snake_case to match the wire format. Every method returns a Promise.

Browser usage

The SDK is server-side first. Importing it in browser code logs a warning — never expose your API key in client code. Proxy through your backend instead.

Methods

client.score({ title, thumbnailUrl, thumbnailBase64 })

Packaging score (title and/or thumbnail). At least one input is required. Server auto-detects mode and charges accordingly: 1 credit title-only, 2 thumbnail-only, 3 combined.

Returns PackagingScoreResponse with: score_id, score (0–1), percentile (0–100), raw_score, mode, niche_slug, niche_label, niche_confidence.

client.videoHook({ youtubeUrl })

Hook quality for the first ~6 s. Returns VideoHookScoreResponse with primary_archetype (one of 13), nested scores (5 dimensions, 0–10 each), overall_score (0–100), strengths, weaknesses, suggestions, and delta_vs_niche_top. Cost: 10 credits.

client.benchmarkChannel({ url })

Channel vs. niche. Returns nested channel and niche with engagement percentiles, title patterns, and up to 5 exemplar channels. Cost: 5 credits.

client.benchmarkVideo({ url })

Single video vs. niche. Returns video and niche objects. Cost: 3 credits.

client.niches() and client.contentGaps({ niche, gapType, limit, minScore })

List catalogued niches (each with its gap_count); query ranked content opportunities. gapType is a subset of ["underserved", "stale", "competitive"]; default ["underserved", "stale"]. competitive is opt-in.

client.me() and client.usage()

Account info / plan details, and live credit balance + recent activity respectively.

Error handling

import {
  BrightBean,
  AuthenticationError,
  InsufficientCreditsError,
  RateLimitError,
  ServiceUnavailableError,
  NetworkError,
} from "brightbean";

try {
  await client.score({ title: "…" });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log("out of credits");
  } else if (err instanceof RateLimitError) {
    console.log(`retry after ${err.retryAfter}s`);
  } else if (err instanceof AuthenticationError) {
    console.log("auth failed");
  } else if (err instanceof ServiceUnavailableError || err instanceof NetworkError) {
    console.log("transport / server issue");
  } else {
    throw err;
  }
}

All errors carry requestId, statusCode, and the parsed error envelope. See Errors for the full taxonomy.

Retries

The client retries 429 and 5xx up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s, honouring Retry-After). Disable via retries: 0 in the constructor.

Configuration reference