@waldofyi/sdk

Official TypeScript SDK for the Waldo public API — brand intelligence, social discovery, and enrichment across every major platform. Fully typed, generated from Waldo's OpenAPI spec.

npm install @waldofyi/sdk

Quick start

import { client, brandSearch, brandOwnedMediaSummary } from "@waldofyi/sdk";

// Configure once. The base URL defaults to https://data.waldo.fyi.
client.setConfig({
  headers: { Authorization: `Bearer ${process.env.WALDO_API_KEY}` },
});

// Find a brand, then pull its owned-media summary.
const { data: search } = await brandSearch({ query: { q: "Gatorade" } });
const brand = search?.data?.[0];

const { data: owned } = await brandOwnedMediaSummary({
  path: { brand_id: brand.id },
  query: { window: "30d" },
});

console.log(brand.name, owned?.data);

Authentication

Every request needs a Waldo API key as a bearer token. Create one in the Waldo app under Settings → API Keys, then set it on the client (as above) or per-call:

await brandSearch({
  query: { q: "Nike" },
  headers: { Authorization: `Bearer ${apiKey}` },
});

Responses

Each call resolves to { data, error } — no exceptions thrown for HTTP errors. data is the response envelope; list endpoints page with a cursor:

const { data, error } = await brandMentionsList({
  path: { brand_id },
  query: { limit: 50, cursor },
});

if (error) { /* handle it */ }
for (const mention of data.data) { /* ... */ }
const next = data.meta.next_cursor; // pass back as `cursor` for the next page

What's available

• Brands — search, overview, owned/paid/earned media, mentions, platforms, timeseries, and competitive comparison (brand*)
• Audiences — segments with their linked brands, subreddits, influencers, podcasts, Substacks, posts, and insights (audience*)
• Categories — Waldo's industry taxonomy with brand populations, news, landscape, whitespace, and trends (category*)
• Discovery — posts, ads, companies, communities, users, and trends across platforms (discover*)
• Enrichment — profiles, posts, companies, and video transcripts (enrichment*)

Method names map to the API's operations; every request and response is typed. The SDK types the full surface; which endpoints your key can actually call depends on the entitlements on your team — a few (audience insights, category trends, brand overview, competitive analysis) are beta and return 403 until they're enabled for you. Full interactive reference: https://data.waldo.fyi/v1/docs

Base URL

Defaults to production (https://data.waldo.fyi). Override for a non-prod stage:

client.setConfig({ baseUrl: "https://rest-staging.development.waldo.fyi" });

License

MIT. Generated with hey-api.