@stellar-light/api-client 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# `@stellar-light/api-client`
+
+Typed TypeScript client for the [Stellar Scout API](https://stellarlight.xyz/scout) — projects, builders, hackathons, SCF funding, audits, and research for the Stellar ecosystem.
+
+**Zero runtime dependencies.** Native `fetch`, works in Node 20+, browsers, and edge runtimes. Types are generated from the live [OpenAPI 3.1 spec](https://stellarlight.xyz/api/openapi.json).
+
+## Which package do I want?
+
+| You are building… | Use |
+|---|---|
+| An autonomous agent or aggregator that calls the API directly | **this package** |
+| A human-driven MCP client (Claude Desktop, Cursor, ChatGPT) | [`@stellar-light/scout-mcp`](https://www.npmjs.com/package/@stellar-light/scout-mcp) |
+| With an agent that loads `SKILL.md` (Claude Code, Codex, OpenClaw) | `npx skills add Stellar-Light/stellar-scout` |
+| Your own client from the spec | `npx openapi-typescript https://stellarlight.xyz/api/openapi.json -o scout.d.ts` |
+
+## Install
+
+```bash
+npm install @stellar-light/api-client
+```
+
+## Quickstart
+
+```ts
+import { ScoutClient } from "@stellar-light/api-client";
+
+const scout = new ScoutClient();
+
+// Has anyone already built this?
+const { projects, meta } = await scout.searchProjects({
+  q: "stablecoin off-ramp",
+  scfAwarded: true,
+  limit: 5,
+});
+console.log(meta.matchMode, projects.map((p) => p.name));
+
+// What's currently fundable?
+const { rfps } = await scout.getRfps({ status: "open" });
+
+// Search the research corpus (SEPs, audits, papers, SCF Handbook…)
+const research = await scout.searchResearch({
+  q: "SEP-24 anchor security",
+  source: "audit",
+});
+```
+
+## All methods
+
+| Method | Endpoint |
+|---|---|
+| `getStatus()` | `GET /api/status` |
+| `searchProjects(params)` | `GET /api/projects/search` |
+| `getHackathons(params)` | `GET /api/hackathons` |
+| `getHackathon(slug)` | `GET /api/hackathons/{slug}` |
+| `compareHackathons(slugs)` | `GET /api/hackathons/compare` |
+| `getBuilders(params)` | `GET /api/builders` |
+| `getRfps(params)` | `GET /api/rfps` |
+| `searchResearch(params)` | `GET /api/research` |
+| `listSkills(params)` | `GET /api/skills` |
+| `getSkill(name)` | `GET /api/skills/{name}` |
+| `getClusters(params)` | `GET /api/clusters` |
+| `analyzeEcosystem(params)` | `GET /api/analyze` |
+| `getLeaderboard(params)` | `GET /api/leaderboard` |
+| `submitFeedback(body)` | `POST /api/feedback` |
+
+All endpoints are public, read-only (except feedback), no auth, edge-cached.
+
+## Options
+
+```ts
+const scout = new ScoutClient({
+  baseUrl: "https://stellarlight.xyz", // default
+  timeoutMs: 30_000,                   // default
+  headers: { "x-agent-name": "my-aggregator" }, // identify yourself (appreciated!)
+  fetch: customFetch,                  // testing / instrumentation
+});
+```
+
+## Errors
+
+Non-2xx responses throw `ScoutApiError` with `.status`, `.url`, and the parsed error `.body`:
+
+```ts
+import { ScoutApiError } from "@stellar-light/api-client";
+
+try {
+  await scout.getSkill("nope");
+} catch (err) {
+  if (err instanceof ScoutApiError && err.status === 404) {
+    // handle unknown slug
+  }
+}
+```
+
+## Data sources behind the API
+
+The endpoints merge: the stellarlight directory (~741 curated Stellar projects), Stellar Passport builder profiles, Electric Capital developer activity, the Soroban audit corpus (Certora, OtterSec, Halborn, OpenZeppelin, Code4rena…), SDF's skills.stellar.org catalog, lumenloop ecosystem data, and primary research (SEPs, Mazières SCP paper, dev docs, SCF Handbook) — 4,541 embedded chunks searchable via `searchResearch`.
+
+## Regenerating types
+
+Types live in `src/schema.ts`, generated from the live spec:
+
+```bash
+pnpm generate
+```
+
+## License
+
+MIT — [stellarlight.xyz](https://stellarlight.xyz)

package/dist/index.d.ts

@@ -0,0 +1,878 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+    "/api/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Service health + endpoint enumeration
+         * @description Returns service health, data-source freshness per collection, and a self-describing enumeration of all 14 endpoints. Useful as a self-discovery call before making other queries.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Service status */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StatusResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/projects/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search Stellar projects (prior art / competitor lookup)
+         * @description Search 741+ curated Stellar projects with tiered match-mode (strict → loose → majority). Tier surfaced as `.meta.matchMode` so agents convey relevance honestly. Essential for *'has anyone already built this?'* gap-classification questions.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Keyword query (free text) */
+                    q?: components["parameters"]["q"];
+                    /** @description Filter by category */
+                    category?: "Infrastructure" | "Tooling" | "User-Facing App" | "Asset" | "Protocol/Contract" | "Anchor" | "Partner Integration";
+                    /** @description Filter by hackathon slug */
+                    hackathon?: string;
+                    /** @description Filter to SCF-funded projects only */
+                    scfAwarded?: boolean;
+                    /** @description Max results returned */
+                    limit?: components["parameters"]["limit"];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Project search results */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ProjectSearchResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/hackathons": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List Stellar hackathons
+         * @description Returns curated Stellar hackathons + live DoraHacks events. Empty status-scoped queries include fallback channels (BuildOnStellar / stellarlight / DoraHacks) so agents can route users to live announcement sources.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Filter by event status */
+                    status?: "upcoming" | "active" | "completed";
+                    /** @description Filter by organizer slug */
+                    organizer?: string;
+                    /** @description Restrict to one feed (curated vs DoraHacks) */
+                    source?: "curated" | "dorahacks";
+                    /** @description Max results returned */
+                    limit?: components["parameters"]["limit"];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Hackathon list */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["HackathonsResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/hackathons/{slug}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get one hackathon's full detail
+         * @description Returns submissions, placements, prize tracks, post-hack status funnel, and outcome data for one hackathon by slug. Dual-shape response: curated entries return full detail; DoraHacks-only entries return metadata + prize pool + an explicit `.meta.note`.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Hackathon slug */
+                    slug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Hackathon detail */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["HackathonDetailResponse"];
+                    };
+                };
+                /** @description Hackathon not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/hackathons/compare": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Compare 2–5 hackathons side-by-side
+         * @description Returns each hackathon's stats + a `.deltas` block highlighting differences agents care about (prize spread, hacker count, prize-per-winner). Useful for *'which Stellar hackathon should I enter?'* type questions.
+         */
+        get: {
+            parameters: {
+                query: {
+                    /** @description 2–5 hackathon slugs */
+                    slugs: string[];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Comparison rollup */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/builders": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search Stellar builders
+         * @description Returns Stellar builder profiles (sourced from Stellar Passport). Useful for *'find a teammate / collaborator who has shipped in X'* queries. Small + growing dataset — flag gaps honestly.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Filter by location substring (e.g. 'Lagos', 'Brazil') */
+                    location?: string;
+                    /** @description Filter by skill/tech mentioned in bio */
+                    skill?: string;
+                    /** @description Filter by SCF tier */
+                    scfTier?: string;
+                    /** @description Max results returned */
+                    limit?: components["parameters"]["limit"];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Builder list */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/rfps": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List Stellar RFPs (SCF-funded sponsor briefs)
+         * @description Returns open + closed Stellar RFPs (sponsor briefs that get SCF-funded for the winning team). Quarter-aware: response includes `.meta.activeQuarter` so agents know which RFPs are open *now* vs prior rounds.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Open RFPs are fundable for the current SCF quarter; closed are prior rounds */
+                    status?: "open" | "closed";
+                    /** @description Filter by quarter slug (e.g. 'q1-2026') */
+                    quarter?: string;
+                    /** @description Max results returned */
+                    limit?: components["parameters"]["limit"];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description RFP list */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/research": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Vector search over the Stellar research corpus
+         * @description Vector search over a 4,541-chunk corpus of primary Stellar sources: SEPs, SCF Handbook, dev docs, foundational papers (Mazières SCP), lumenloop community playbooks, Soroban audit reports (Certora, OtterSec, Halborn, OpenZeppelin, Code4rena, etc.), Electric Capital Developer Reports, SDF blog. Returns top-K chunks with severity metadata for audit chunks. Score field is cosine similarity (0–1, higher = more relevant).
+         */
+        get: {
+            parameters: {
+                query: {
+                    /** @description Natural-language search query */
+                    q: string;
+                    /** @description Optional source filter. Use 'audit' for security questions, 'ec-developer-report' for ecosystem stats, 'paper' for foundational protocol questions. */
+                    source?: "sdf-blog" | "scf-handbook" | "sep" | "dev-docs" | "paper" | "scf-proposal" | "lumenloop" | "lumenloop-research" | "audit" | "ec-developer-report";
+                    /** @description Max results (default 8, max 25) */
+                    limit?: number;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Research results */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/skills": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List AI skills for Stellar builders
+         * @description Merged catalog of SDF skills.stellar.org skills + curated Stellar Light entries + approved community submissions. Editorial source priority: Stellarlight → SDF → external ecosystem → competing aggregators → community. Featured skills sort first.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Filter by source */
+                    source?: "sdf" | "stellarlight" | "lumenloop" | "external" | "community";
+                    /** @description Filter by skill kind */
+                    kind?: "skill-md" | "mcp-server" | "sdk" | "cli" | "agent-kit" | "tool";
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Skills catalog */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/skills/{name}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get one skill's full content
+         * @description Returns full SKILL.md content for SDF + Stellar Light skills (where applicable) plus metadata for all sources. Use when a user mentions a specific skill by name — cheaper than filtering the full list endpoint.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Skill slug (e.g. 'soroban', 'stellar-scout', 'rozo-intent-pay') */
+                    name: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Skill detail with content */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+                /** @description Skill not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/clusters": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Topic clusters with crowdedness scores
+         * @description Returns clusters of projects by category or types, each with a log-scaled crowdedness score (1–10), SCF-funded count, and sample projects. Useful for *'what's most crowded on Stellar?'* / *'show me underbuilt categories'* queries.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Cluster by category (coarse 7-cat) or types (finer) */
+                    dimension?: "category" | "types";
+                    /** @description Only include clusters with at least N projects */
+                    minSize?: number;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Cluster list */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/analyze": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Cross-event Stellar ecosystem analytics rollup
+         * @description Aggregate stats across all hackathons + projects + SCF funding. Returns: total events, prize pool totals, top categories by project count + SCF-funded count, distribution of SCF awards, post-hackathon status funnel (Built / In Progress / Abandoned).
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Which slice to return */
+                    dimension?: "all" | "hackathons" | "categories" | "funding";
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Analytics rollup */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/leaderboard": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Stellar ecosystem developer activity
+         * @description Returns 28-day active dev counts, commits, full-time vs part-time vs one-time dev splits, geographic distribution. Sourced from Electric Capital. Useful for *'how does Stellar compare on dev activity?'* macro questions.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Optional comma-separated includes (e.g. 'hackathons' to surface hackathon context) */
+                    include?: string;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Leaderboard + ecosystem stats */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Submit feedback on Scout's output
+         * @description Send a feedback report when the skill returns wrong / missing / misleading information. Lands in the curator queue. Rate-limited to 6/min/IP (IP hashed with PAYLOAD_SECRET, never stored raw).
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["FeedbackRequest"];
+                };
+            };
+            responses: {
+                /** @description Feedback received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            ok: boolean;
+                            id: string;
+                            message?: string;
+                        };
+                    };
+                };
+                /** @description Validation error */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Rate limit exceeded */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        /** @description Standard meta block included on every list response */
+        Meta: {
+            /** Format: uri */
+            source?: string;
+            /** Format: date-time */
+            generatedAt?: string;
+            filters?: {
+                [key: string]: unknown;
+            };
+            counts?: {
+                returned?: number;
+            };
+        };
+        ErrorResponse: {
+            error: string;
+            details?: {
+                [key: string]: unknown;
+            };
+        };
+        StatusResponse: {
+            ok: boolean;
+            /** @constant */
+            service: "Stellar Scout";
+            version: string;
+            /** Format: date-time */
+            generatedAt: string;
+            sources?: {
+                name?: string;
+                count?: number;
+                /** Format: date-time */
+                lastUpdatedAt?: string | null;
+                notes?: string;
+            }[];
+            usage?: {
+                total?: number;
+                last24h?: number;
+                last7d?: number;
+                byEndpoint?: {
+                    endpoint?: string;
+                    count?: number;
+                }[];
+            };
+            endpoints: string[];
+            /** Format: uri */
+            docs?: string;
+            /** Format: uri */
+            skill?: string;
+        };
+        Project: {
+            id: string;
+            name: string;
+            slug: string;
+            /** @enum {string} */
+            category: "Infrastructure" | "Tooling" | "User-Facing App" | "Asset" | "Protocol/Contract" | "Anchor" | "Partner Integration";
+            shortDescription?: string;
+            /** @enum {string} */
+            status: "Live" | "Development" | "Abandoned";
+            logoUrl?: string | null;
+            scfAwarded?: boolean;
+            scfTotalAwardedUSD?: number | null;
+            hackathon?: string | null;
+            hackathonPlacement?: string | null;
+            hackathonPrize?: number | null;
+            hackathonPrizeTrack?: string | null;
+            /** @description Relevance score for the current query (higher = better match) */
+            score?: number;
+            /** Format: uri */
+            url?: string;
+        };
+        ProjectSearchResponse: {
+            meta: components["schemas"]["Meta"] & {
+                /**
+                 * @description Tier of match relaxation that produced these results
+                 * @enum {string}
+                 */
+                matchMode?: "strict" | "loose" | "majority";
+                matchModeLabel?: string;
+            };
+            projects: components["schemas"]["Project"][];
+        };
+        HackathonsResponse: {
+            meta?: components["schemas"]["Meta"] & {
+                /** @description Live announcement channels when query returns 0 events */
+                fallbackChannels?: {
+                    name?: string;
+                    /** Format: uri */
+                    url?: string;
+                }[];
+            };
+            hackathons?: Record<string, never>[];
+        };
+        HackathonDetailResponse: {
+            meta?: components["schemas"]["Meta"];
+            hackathon?: Record<string, never>;
+        };
+        FeedbackRequest: {
+            /** @enum {string} */
+            kind: "bug" | "missing-data" | "wrong-answer" | "suggestion" | "other";
+            message: string;
+            query?: string;
+            endpoint?: string;
+            agentName?: string;
+        };
+    };
+    responses: never;
+    parameters: {
+        /** @description Keyword query (free text) */
+        q: string;
+        /** @description Max results returned */
+        limit: number;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+/**
+ * @stellar-light/api-client — typed TypeScript client for the Stellar
+ * Scout API (https://stellarlight.xyz/api/openapi.json).
+ *
+ * Zero runtime dependencies — native fetch, works in Node 20+, browsers,
+ * and edge runtimes. For autonomous agents and aggregators that consume
+ * the API directly; human-driven MCP clients (Claude Desktop, Cursor)
+ * should use @stellar-light/scout-mcp instead.
+ *
+ *   import { ScoutClient } from "@stellar-light/api-client";
+ *
+ *   const scout = new ScoutClient();
+ *   const { projects } = await scout.searchProjects({ q: "stablecoin", scfAwarded: true });
+ *
+ * Types are generated from the live OpenAPI spec (src/schema.ts via
+ * openapi-typescript). Regenerate with `pnpm generate` when the spec
+ * changes.
+ */
+
+/** Re-exported component schemas for consumer convenience. */
+type Project = components["schemas"]["Project"];
+type ProjectSearchResponse = components["schemas"]["ProjectSearchResponse"];
+type StatusResponse = components["schemas"]["StatusResponse"];
+type HackathonsResponse = components["schemas"]["HackathonsResponse"];
+type HackathonDetailResponse = components["schemas"]["HackathonDetailResponse"];
+type FeedbackRequest = components["schemas"]["FeedbackRequest"];
+/** Query params, lifted from the generated paths for ergonomic call sites. */
+type SearchProjectsParams = NonNullable<paths["/api/projects/search"]["get"]["parameters"]["query"]>;
+type GetHackathonsParams = NonNullable<paths["/api/hackathons"]["get"]["parameters"]["query"]>;
+type GetBuildersParams = NonNullable<paths["/api/builders"]["get"]["parameters"]["query"]>;
+type GetRfpsParams = NonNullable<paths["/api/rfps"]["get"]["parameters"]["query"]>;
+type SearchResearchParams = NonNullable<paths["/api/research"]["get"]["parameters"]["query"]>;
+type ListSkillsParams = NonNullable<paths["/api/skills"]["get"]["parameters"]["query"]>;
+type GetClustersParams = NonNullable<paths["/api/clusters"]["get"]["parameters"]["query"]>;
+type AnalyzeEcosystemParams = NonNullable<paths["/api/analyze"]["get"]["parameters"]["query"]>;
+type GetLeaderboardParams = NonNullable<paths["/api/leaderboard"]["get"]["parameters"]["query"]>;
+interface ScoutClientOptions {
+    /** API origin. Defaults to https://stellarlight.xyz */
+    baseUrl?: string;
+    /** Request timeout in ms. Defaults to 30_000. */
+    timeoutMs?: number;
+    /** Extra headers sent with every request (e.g. identify your agent). */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (testing / instrumented runtimes). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Thrown on any non-2xx response. Carries status + parsed error body. */
+declare class ScoutApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly body: unknown;
+    constructor(status: number, url: string, body: unknown);
+}
+declare class ScoutClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(options?: ScoutClientOptions);
+    /** Service health, data-source freshness, endpoint enumeration. */
+    getStatus(): Promise<StatusResponse>;
+    /** Search 741+ curated Stellar projects (prior art / competitor lookup). */
+    searchProjects(params?: SearchProjectsParams): Promise<ProjectSearchResponse>;
+    /** List Stellar hackathons (curated + DoraHacks merged feed). */
+    getHackathons(params?: GetHackathonsParams): Promise<HackathonsResponse>;
+    /** Full detail for one hackathon by slug. */
+    getHackathon(slug: string): Promise<HackathonDetailResponse>;
+    /** Side-by-side comparison of 2–5 hackathons with a deltas block. */
+    compareHackathons(slugs: string[]): Promise<Record<string, unknown>>;
+    /** Search Stellar builder profiles (Stellar Passport directory). */
+    getBuilders(params?: GetBuildersParams): Promise<Record<string, unknown>>;
+    /** Open + closed SCF-funded sponsor briefs. */
+    getRfps(params?: GetRfpsParams): Promise<Record<string, unknown>>;
+    /** Vector search over the 4,541-chunk Stellar research corpus. */
+    searchResearch(params: SearchResearchParams): Promise<Record<string, unknown>>;
+    /** Merged AI-skill catalog (SDF + curated + community). */
+    listSkills(params?: ListSkillsParams): Promise<Record<string, unknown>>;
+    /** One skill's full content + metadata by slug. */
+    getSkill(name: string): Promise<Record<string, unknown>>;
+    /** Topic clusters with log-scaled crowdedness scores. */
+    getClusters(params?: GetClustersParams): Promise<Record<string, unknown>>;
+    /** Cross-event analytics rollup (hackathons + categories + funding). */
+    analyzeEcosystem(params?: AnalyzeEcosystemParams): Promise<Record<string, unknown>>;
+    /** Electric Capital developer-activity stats + project leaderboard. */
+    getLeaderboard(params?: GetLeaderboardParams): Promise<Record<string, unknown>>;
+    /** Report wrong / missing / misleading data to the curator queue. */
+    submitFeedback(body: FeedbackRequest): Promise<{
+        ok: boolean;
+        id: string;
+        message?: string;
+    }>;
+    private get;
+    private request;
+}
+
+export { type AnalyzeEcosystemParams, type FeedbackRequest, type GetBuildersParams, type GetClustersParams, type GetHackathonsParams, type GetLeaderboardParams, type GetRfpsParams, type HackathonDetailResponse, type HackathonsResponse, type ListSkillsParams, type Project, type ProjectSearchResponse, ScoutApiError, ScoutClient, type ScoutClientOptions, type SearchProjectsParams, type SearchResearchParams, type StatusResponse, type components, type paths };

package/dist/index.js

@@ -0,0 +1,129 @@
+// src/index.ts
+var ScoutApiError = class extends Error {
+  status;
+  url;
+  body;
+  constructor(status, url, body) {
+    const detail = body && typeof body === "object" && "error" in body ? ` \u2014 ${body.error}` : "";
+    super(`Scout API ${status} on ${url}${detail}`);
+    this.name = "ScoutApiError";
+    this.status = status;
+    this.url = url;
+    this.body = body;
+  }
+};
+var DEFAULT_BASE_URL = "https://stellarlight.xyz";
+var CLIENT_VERSION = "1.0.0";
+var ScoutClient = class {
+  baseUrl;
+  timeoutMs;
+  headers;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.headers = {
+      "user-agent": `stellar-light-api-client/${CLIENT_VERSION}`,
+      ...options.headers
+    };
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+  }
+  /** Service health, data-source freshness, endpoint enumeration. */
+  getStatus() {
+    return this.get("/api/status");
+  }
+  /** Search 741+ curated Stellar projects (prior art / competitor lookup). */
+  searchProjects(params = {}) {
+    return this.get("/api/projects/search", params);
+  }
+  /** List Stellar hackathons (curated + DoraHacks merged feed). */
+  getHackathons(params = {}) {
+    return this.get("/api/hackathons", params);
+  }
+  /** Full detail for one hackathon by slug. */
+  getHackathon(slug) {
+    return this.get(`/api/hackathons/${encodeURIComponent(slug)}`);
+  }
+  /** Side-by-side comparison of 2–5 hackathons with a deltas block. */
+  compareHackathons(slugs) {
+    return this.get("/api/hackathons/compare", { slugs: slugs.join(",") });
+  }
+  /** Search Stellar builder profiles (Stellar Passport directory). */
+  getBuilders(params = {}) {
+    return this.get("/api/builders", params);
+  }
+  /** Open + closed SCF-funded sponsor briefs. */
+  getRfps(params = {}) {
+    return this.get("/api/rfps", params);
+  }
+  /** Vector search over the 4,541-chunk Stellar research corpus. */
+  searchResearch(params) {
+    return this.get("/api/research", params);
+  }
+  /** Merged AI-skill catalog (SDF + curated + community). */
+  listSkills(params = {}) {
+    return this.get("/api/skills", params);
+  }
+  /** One skill's full content + metadata by slug. */
+  getSkill(name) {
+    return this.get(`/api/skills/${encodeURIComponent(name)}`);
+  }
+  /** Topic clusters with log-scaled crowdedness scores. */
+  getClusters(params = {}) {
+    return this.get("/api/clusters", params);
+  }
+  /** Cross-event analytics rollup (hackathons + categories + funding). */
+  analyzeEcosystem(params = {}) {
+    return this.get("/api/analyze", params);
+  }
+  /** Electric Capital developer-activity stats + project leaderboard. */
+  getLeaderboard(params = {}) {
+    return this.get("/api/leaderboard", params);
+  }
+  /** Report wrong / missing / misleading data to the curator queue. */
+  submitFeedback(body) {
+    return this.request("/api/feedback", { method: "POST", body });
+  }
+  /* ── transport ──────────────────────────────────────────────────── */
+  get(path, params) {
+    return this.request(path, { method: "GET", params });
+  }
+  async request(path, init) {
+    const url = new URL(this.baseUrl + path);
+    for (const [key, value] of Object.entries(init.params ?? {})) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) url.searchParams.append(key, String(v));
+      } else {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url.toString(), {
+        method: init.method,
+        headers: {
+          accept: "application/json",
+          ...init.body !== void 0 && {
+            "content-type": "application/json"
+          },
+          ...this.headers
+        },
+        ...init.body !== void 0 && { body: JSON.stringify(init.body) },
+        signal: controller.signal
+      });
+      const body = await res.json().catch(() => null);
+      if (!res.ok) {
+        throw new ScoutApiError(res.status, url.toString(), body);
+      }
+      return body;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+export {
+  ScoutApiError,
+  ScoutClient
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@stellar-light/api-client",
+  "version": "1.0.0",
+  "description": "Typed TypeScript client for the Stellar Scout API — projects, builders, hackathons, SCF, audits, research. Zero dependencies, for autonomous agents and aggregators.",
+  "keywords": [
+    "stellar",
+    "soroban",
+    "api-client",
+    "sdk",
+    "typescript",
+    "agent",
+    "ai",
+    "ecosystem",
+    "scf",
+    "openapi"
+  ],
+  "homepage": "https://stellarlight.xyz/scout",
+  "bugs": {
+    "url": "https://github.com/alexanderkoh/stellarlight/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexanderkoh/stellarlight.git",
+    "directory": "api-client"
+  },
+  "license": "MIT",
+  "author": "stellarlight.xyz",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --target node20 --clean",
+    "generate": "openapi-typescript https://stellarlight.xyz/api/openapi.json -o src/schema.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && node test/smoke.mjs",
+    "prepublishOnly": "pnpm build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "openapi-typescript": "^7.13.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}