@stellar-light/api-client 1.0.0 → 1.1.0

package/README.md

@@ -50,6 +50,7 @@ const research = await scout.searchResearch({
 |---|---|
 | `getStatus()` | `GET /api/status` |
 | `searchProjects(params)` | `GET /api/projects/search` |
+| `searchRepos(params)` | `GET /api/repos/search` |
 | `getHackathons(params)` | `GET /api/hackathons` |
 | `getHackathon(slug)` | `GET /api/hackathons/{slug}` |
 | `compareHackathons(slugs)` | `GET /api/hackathons/compare` |

package/dist/index.d.ts

@@ -64,8 +64,10 @@ interface paths {
                     hackathon?: string;
                     /** @description Filter to SCF-funded projects only */
                     scfAwarded?: boolean;
-                    /** @description Max results returned */
+                    /** @description Max results returned (per-page) */
                     limit?: components["parameters"]["limit"];
+                    /** @description Number of matching rows to skip before returning (pagination). Page until offset + meta.counts.returned >= meta.counts.total. */
+                    offset?: components["parameters"]["offset"];
                 };
                 header?: never;
                 path?: never;
@@ -92,6 +94,56 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/repos/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search the Stellar GitHub repo / code-reference index
+         * @description Search ~1,900 indexed-and-scored Stellar ecosystem GitHub repos by tech/keyword — the code layer beneath the project directory. Answers *'show me the repos / code for X'* and prior-art **code** lookups that project search can't. Indexes GitHub topics + description + language + README, expands synonyms (zk→zero-knowledge/snark, oracle→price-feed, …), and ranks by `repoScore` (0–100 = freshness + traction + hackathon/SCF/builder authority). Lead with high-score repos as the strongest references and cite each repo's `url` / `homepageUrl`. The same graded repos are injected inline into `/api/projects/search` as `codeReferences`.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Keyword query (free text) */
+                    q?: components["parameters"]["q"];
+                    /** @description Filter by primary language (case-insensitive substring, e.g. 'Rust', 'TypeScript') */
+                    language?: string;
+                    /** @description Only return repos with repoScore ≥ this (0–100). Use 40+ for high-signal references. */
+                    minScore?: number;
+                    /** @description Max results returned (per-page) */
+                    limit?: components["parameters"]["limit"];
+                    /** @description Number of matching rows to skip before returning (pagination). Page until offset + meta.counts.returned >= meta.counts.total. */
+                    offset?: components["parameters"]["offset"];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Repo search results graded by repoScore */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RepoSearchResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/hackathons": {
         parameters: {
             query?: never;
@@ -112,7 +164,7 @@ interface paths {
                     organizer?: string;
                     /** @description Restrict to one feed (curated vs DoraHacks) */
                     source?: "curated" | "dorahacks";
-                    /** @description Max results returned */
+                    /** @description Max results returned (per-page) */
                     limit?: components["parameters"]["limit"];
                 };
                 header?: never;
@@ -205,7 +257,7 @@ interface paths {
         get: {
             parameters: {
                 query: {
-                    /** @description 2–5 hackathon slugs */
+                    /** @description 2–5 hackathon slugs, comma-separated (?slugs=a,b) */
                     slugs: string[];
                 };
                 header?: never;
@@ -253,8 +305,10 @@ interface paths {
                     skill?: string;
                     /** @description Filter by SCF tier */
                     scfTier?: string;
-                    /** @description Max results returned */
+                    /** @description Max results returned (per-page) */
                     limit?: components["parameters"]["limit"];
+                    /** @description Number of matching rows to skip before returning (pagination). Page until offset + meta.counts.returned >= meta.counts.total. */
+                    offset?: components["parameters"]["offset"];
                 };
                 header?: never;
                 path?: never;
@@ -281,6 +335,109 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/partners": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List ecosystem partners
+         * @description Published partners (anchors, on/off ramps, infrastructure, tooling, protocols, wallets, audit firms). Each carries partner-claimed facts AND system-verified signals (GitHub activity, on-chain footprint, SCF involvement) plus a `freshness` object — consumers should down-rank or skip partners flagged `freshness.excludeFromMatching`. Fresh partners sort first.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Filter by partner type */
+                    type?: "anchor" | "on-off-ramp" | "infrastructure" | "tooling" | "protocol" | "wallet" | "audit-firm" | "legal" | "agency" | "other";
+                    /** @description Filter by sector served (defi, payments, rwa, stablecoins, …) */
+                    sector?: string;
+                    /** @description Filter by region served (global, latam, africa, …) */
+                    region?: string;
+                    /** @description Set to 1 to return only partners currently accepting new clients */
+                    accepting?: "1";
+                    /** @description Keyword query (free text) */
+                    q?: components["parameters"]["q"];
+                    /** @description Max results returned (per-page) */
+                    limit?: components["parameters"]["limit"];
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Partner directory */
+                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/partners/{slug}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get one partner's full profile
+         * @description Full published profile for one partner by slug, including verified signals + freshness. 404 for unknown or unpublished slugs.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Partner slug */
+                    slug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Partner profile */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": Record<string, never>;
+                    };
+                };
+                /** @description Partner not found or not published */
+                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/rfps": {
         parameters: {
             query?: never;
@@ -299,8 +456,10 @@ interface paths {
                     status?: "open" | "closed";
                     /** @description Filter by quarter slug (e.g. 'q1-2026') */
                     quarter?: string;
-                    /** @description Max results returned */
+                    /** @description Max results returned (per-page) */
                     limit?: components["parameters"]["limit"];
+                    /** @description Number of matching rows to skip before returning (pagination). Page until offset + meta.counts.returned >= meta.counts.total. */
+                    offset?: components["parameters"]["offset"];
                 };
                 header?: never;
                 path?: never;
@@ -336,7 +495,7 @@ interface paths {
         };
         /**
          * 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).
+         * @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. Each result carries a `confidence` object — `{ score (0-1), label (high/medium/low), relevance, freshness, authority, ageDays }` — blending match strength, source-aware recency, and source authority so an agent can tell a strong, fresh, canonical hit from a weak or stale one. Sort by `confidence.score` for trust-ranked results; `meta.scoreModel.version` identifies the model. The raw `score` field remains cosine similarity (0–1, higher = more relevant).
          */
         get: {
             parameters: {
@@ -674,7 +833,10 @@ interface components {
                 [key: string]: unknown;
             };
             counts?: {
+                /** @description Rows in this page (post limit/offset slice) */
                 returned?: number;
+                /** @description Rows matching the filter before slicing (paginated endpoints). Page until offset + returned >= total. */
+                total?: number;
             };
         };
         ErrorResponse: {
@@ -720,7 +882,7 @@ interface components {
             category: "Infrastructure" | "Tooling" | "User-Facing App" | "Asset" | "Protocol/Contract" | "Anchor" | "Partner Integration";
             shortDescription?: string;
             /** @enum {string} */
-            status: "Live" | "Development" | "Abandoned";
+            status: "Draft" | "Development" | "Pre-Release" | "Live";
             logoUrl?: string | null;
             scfAwarded?: boolean;
             scfTotalAwardedUSD?: number | null;
@@ -732,6 +894,19 @@ interface components {
             score?: number;
             /** Format: uri */
             url?: string;
+            /** @description Editorial ranking boost (0-100); higher = more canonical for its category. */
+            prominence?: number;
+            verificationLevel?: string | null;
+            /** @description Capability tags (Wallet, DEX, Lending, Oracle, SDK, RPC, Faucet, NFT, RWA, Anchor, Stablecoin, Indexer, Explorer, Security, Gaming). */
+            types?: string[];
+            /** @description The project OWN canonical homes - cite these as the primary source, not StellarLight or any directory. Only present, non-empty fields are included. */
+            links?: {
+                website?: string;
+                github?: string;
+                docs?: string;
+                twitter?: string;
+                discord?: string;
+            };
         };
         ProjectSearchResponse: {
             meta: components["schemas"]["Meta"] & {
@@ -743,6 +918,8 @@ interface components {
                 matchModeLabel?: string;
             };
             projects: components["schemas"]["Project"][];
+            /** @description Top graded repos matching the same query, surfaced inline (max 5, first page only; same shape as /api/repos/search). Cite as existing code references for prior-art questions. */
+            codeReferences?: components["schemas"]["Repo"][];
         };
         HackathonsResponse: {
             meta?: components["schemas"]["Meta"] & {
@@ -759,6 +936,44 @@ interface components {
             meta?: components["schemas"]["Meta"];
             hackathon?: Record<string, never>;
         };
+        /** @description An indexed Stellar ecosystem GitHub repository graded by repoScore. Cite the repo's url / homepageUrl as the primary source. */
+        Repo: {
+            /** @description owner/name */
+            fullName: string;
+            owner?: string | null;
+            name?: string | null;
+            /** Format: uri */
+            url?: string | null;
+            description?: string | null;
+            topics?: string[];
+            primaryLanguage?: string | null;
+            stars?: number;
+            openIssues?: number;
+            /** Format: date-time */
+            lastCommitAt?: string | null;
+            homepageUrl?: string | null;
+            isFork?: boolean;
+            isArchived?: boolean;
+            /** @description The curated project this repo is linked to, if any. */
+            project?: {
+                slug?: string;
+                name?: string | null;
+            } | null;
+            hackathonWinner?: boolean;
+            scfAwarded?: boolean;
+            builderReputation?: number;
+            judgeScore?: number | null;
+            judgedHackathon?: string | null;
+            /** @description Quality grade (0–100) = freshness + traction + hackathon/SCF/builder authority. Lead with high-score repos. */
+            repoScore: number;
+            repoScoreLabel?: string | null;
+            /** @description Keyword-relevance score for the current query (higher = better match). */
+            score?: number;
+        };
+        RepoSearchResponse: {
+            meta: components["schemas"]["Meta"];
+            repos: components["schemas"]["Repo"][];
+        };
         FeedbackRequest: {
             /** @enum {string} */
             kind: "bug" | "missing-data" | "wrong-answer" | "suggestion" | "other";
@@ -772,8 +987,10 @@ interface components {
     parameters: {
         /** @description Keyword query (free text) */
         q: string;
-        /** @description Max results returned */
+        /** @description Max results returned (per-page) */
         limit: number;
+        /** @description Number of matching rows to skip before returning (pagination). Page until offset + meta.counts.returned >= meta.counts.total. */
+        offset: number;
     };
     requestBodies: never;
     headers: never;
@@ -802,12 +1019,15 @@ interface components {
 /** Re-exported component schemas for consumer convenience. */
 type Project = components["schemas"]["Project"];
 type ProjectSearchResponse = components["schemas"]["ProjectSearchResponse"];
+type Repo = components["schemas"]["Repo"];
+type RepoSearchResponse = components["schemas"]["RepoSearchResponse"];
 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 SearchReposParams = NonNullable<paths["/api/repos/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"]>;
@@ -843,6 +1063,12 @@ declare class ScoutClient {
     getStatus(): Promise<StatusResponse>;
     /** Search 741+ curated Stellar projects (prior art / competitor lookup). */
     searchProjects(params?: SearchProjectsParams): Promise<ProjectSearchResponse>;
+    /**
+     * Search ~1,900 indexed-and-scored Stellar GitHub repos by tech/keyword —
+     * the code layer beneath the project directory. Ranked by repoScore
+     * (freshness + traction + hackathon/SCF/builder authority).
+     */
+    searchRepos(params?: SearchReposParams): Promise<RepoSearchResponse>;
     /** List Stellar hackathons (curated + DoraHacks merged feed). */
     getHackathons(params?: GetHackathonsParams): Promise<HackathonsResponse>;
     /** Full detail for one hackathon by slug. */
@@ -875,4 +1101,4 @@ declare class ScoutClient {
     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 };
+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, type Repo, type RepoSearchResponse, ScoutApiError, ScoutClient, type ScoutClientOptions, type SearchProjectsParams, type SearchReposParams, type SearchResearchParams, type StatusResponse, type components, type paths };

package/dist/index.js

@@ -13,7 +13,7 @@ var ScoutApiError = class extends Error {
   }
 };
 var DEFAULT_BASE_URL = "https://stellarlight.xyz";
-var CLIENT_VERSION = "1.0.0";
+var CLIENT_VERSION = "1.1.0";
 var ScoutClient = class {
   baseUrl;
   timeoutMs;
@@ -36,6 +36,14 @@ var ScoutClient = class {
   searchProjects(params = {}) {
     return this.get("/api/projects/search", params);
   }
+  /**
+   * Search ~1,900 indexed-and-scored Stellar GitHub repos by tech/keyword —
+   * the code layer beneath the project directory. Ranked by repoScore
+   * (freshness + traction + hackathon/SCF/builder authority).
+   */
+  searchRepos(params = {}) {
+    return this.get("/api/repos/search", params);
+  }
   /** List Stellar hackathons (curated + DoraHacks merged feed). */
   getHackathons(params = {}) {
     return this.get("/api/hackathons", params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar-light/api-client",
-  "version": "1.0.0",
+  "version": "1.1.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",