@waldofyi/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,37 +1,85 @@
 # @waldofyi/sdk
 
-Official TypeScript SDK for the **public** Waldo API. Generated from the OpenAPI
-spec with [hey-api](https://heyapi.dev) — do not hand-edit `src/`.
+Official TypeScript SDK for the [Waldo](https://data.waldo.fyi/v1/docs) public API —
+brand intelligence, social discovery, and enrichment across every major
+platform. Fully typed, generated from Waldo's OpenAPI spec.
 
-## Regenerate
+```bash
+npm install @waldofyi/sdk
+```
 
-The OpenAPI input (`openapi.json`) is built **locally from this repo's own REST
-app** — not fetched from a deployed URL — so the SDK always matches the code
-being shipped (no drift, no deploy dependency).
+## Quick start
 
-```bash
-pnpm --filter @waldo/graphql-api gen:sdk-spec   # rebuild the committed openapi.json
-pnpm --filter @waldofyi/sdk codegen             # generate src/ from openapi.json
-pnpm --filter @waldofyi/sdk build               # compile to dist/
+```ts
+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);
 ```
 
-`codegen` + `build` also run automatically via `prepublishOnly`.
+## 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:
+
+```ts
+await brandSearch({
+  query: { q: "Nike" },
+  headers: { Authorization: `Bearer ${apiKey}` },
+});
+```
 
-## What's in / out
+## Responses
 
-`gen:sdk-spec` builds the spec for the public SDK flag set (see
-`packages/api/scripts/gen-sdk-spec.ts`). Admin/platform routes are excluded;
-brand-intelligence routes are **included** (v0.1.0). The server's feature-flag
-exposure system stays the single source of truth for what's public — the
-generator only picks the flag set.
+Each call resolves to `{ data, error }` — no exceptions thrown for HTTP errors.
+`data` is the response envelope; list endpoints page with a cursor:
 
-Method names come from each route's `operationId`, which the API emits from the
-operation registry's `operationName` (`packages/api/src/rest/lib/operation-route.ts`)
-and stamps onto the spec in `buildFilteredOpenApiSpec`.
+```ts
+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*`)
+- **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.
+Full interactive reference: **https://data.waldo.fyi/v1/docs**
+
+## Base URL
+
+Defaults to production (`https://data.waldo.fyi`). Override for a non-prod
+stage:
+
+```ts
+client.setConfig({ baseUrl: "https://rest-staging.development.waldo.fyi" });
+```
 
-The internal, admin-capable client used by the CLI lives at
-`packages/cli/src/sdk/` (hand-written, GraphQL + REST).
+## License
 
-> Generated `src/*.gen.ts` is not committed (gitignored) — it's produced fresh
-> from the committed `openapi.json` at codegen/publish. Only `openapi.json` and
-> the placeholder `src/index.ts` are committed.
+MIT. Generated with [hey-api](https://heyapi.dev).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waldofyi/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official TypeScript SDK for the Waldo public API — generated from the OpenAPI spec",
   "type": "module",
   "main": "dist/index.js",