@buildinternet/releases-api-types 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",

package/src/api-types.ts

@@ -92,6 +92,12 @@ export interface SourceListItem {
   latestAddedAt?: string | null;
   isPrimary?: boolean;
   isHidden?: boolean;
+  /**
+   * How the row was created. Optional on the wire so older API responses
+   * (mid-deploy or pinned old workers) degrade gracefully — consumers that
+   * see `undefined` should treat it as `"curated"`.
+   */
+  discovery?: "curated" | "agent" | "on_demand";
   fetchPriority?: "normal" | "low" | "paused" | null;
   lastFetchedAt?: string | null;
   lastPolledAt?: string | null;
@@ -123,6 +129,7 @@ export interface SourceWithOrg {
   productSlug: string | null;
   isPrimary: boolean;
   isHidden: boolean | null;
+  discovery?: "curated" | "agent" | "on_demand";
   metadata: string | null;
   releaseCount: number;
   latestVersion: string | null;
@@ -207,6 +214,18 @@ export interface SourceDetail {
   name: string;
   type: string;
   url: string;
+  /**
+   * Hidden sources are reachable by direct URL but excluded from listings,
+   * sitemap, and AI features. Set on on-demand lookups and admin-suppressed
+   * rows; absent on canonical curated/agent sources.
+   */
+  isHidden?: boolean;
+  /**
+   * Pairs with `isHidden` to distinguish admin-suppressed rows (`curated` /
+   * `agent` + hidden) from rows materialized by `/v1/lookups` (`on_demand`).
+   * Optional for graceful degradation against older API responses.
+   */
+  discovery?: "curated" | "agent" | "on_demand";
   changelogUrl?: string | null;
   hasChangelogFile?: boolean;
   org: { slug: string; name: string } | null;
@@ -228,6 +247,13 @@ export interface SourceDetail {
 
 // ── Releases ──
 
+/**
+ * Release type — mirrors `RELEASE_TYPES` in `@buildinternet/releases-core/schema`.
+ * Optional on the wire so older API responses (mid-deploy or pinned old workers)
+ * degrade gracefully — consumers that see `undefined` should treat it as `"feature"`.
+ */
+export type ReleaseType = "feature" | "rollup";
+
 export interface ReleaseItem {
   id?: string;
   version: string | null;
@@ -237,6 +263,8 @@ export interface ReleaseItem {
   publishedAt: string | null;
   url: string | null;
   media?: MediaItem[];
+  /** Release type. See {@link ReleaseType}. */
+  type?: ReleaseType;
 }
 
 export interface ReleaseDetail {
@@ -254,6 +282,8 @@ export interface ReleaseDetail {
   sourceSlug: string;
   sourceType: string;
   org: { slug: string; name: string } | null;
+  /** Release type. See {@link ReleaseType}. */
+  type?: ReleaseType;
 }
 
 export interface ReleaseCoverageRow {
@@ -391,6 +421,8 @@ export interface SearchReleaseHit {
    * use this to interleave release and chunk hits into a single ranked list.
    */
   score?: number;
+  /** Release type. See {@link ReleaseType}. */
+  type?: ReleaseType;
 }
 
 /**
@@ -412,6 +444,42 @@ export interface SearchChunkHit {
   score: number;
 }
 
+// ── Lookup (on-demand GitHub index) ──
+
+export type LookupStatus = "indexed" | "existing" | "empty" | "not_found" | "deferred";
+
+/**
+ * Slim wire payload embedded in a search response when the query is a GitHub
+ * coordinate (org/repo) and no existing entity matched. The server performs an
+ * on-demand lookup and includes the result here so the client can surface a
+ * "just indexed" or "not found" rail without a second round trip.
+ */
+export interface LookupResultPayload {
+  status: LookupStatus;
+  source?: {
+    id: string;
+    slug: string;
+    name: string;
+    url: string;
+    discovery: "curated" | "agent" | "on_demand";
+  };
+  releases?: Array<{
+    id: string;
+    version: string | null;
+    title: string;
+    publishedAt: string | null;
+  }>;
+  /**
+   * Unambiguous "did you mean" rail: the curated org that owns GitHub repos
+   * under the same org segment, plus its top sources. Null when the org
+   * segment matches multiple curated orgs or none.
+   */
+  relatedOrg: {
+    org: { id: string; slug: string; name: string };
+    sources: Array<{ id: string; slug: string; name: string; url: string }>;
+  } | null;
+}
+
 export interface UnifiedSearchResponse {
   query: string;
   orgs: SearchOrgHit[];
@@ -429,6 +497,11 @@ export interface UnifiedSearchResponse {
   degraded?: boolean;
   /** Human-readable reason for degradation (e.g., missing Vectorize binding). */
   degradedReason?: string;
+  /**
+   * On-demand lookup result. Present when the query parsed as a GitHub
+   * `org/repo` coordinate and no existing entities matched. Null otherwise.
+   */
+  lookup?: LookupResultPayload | null;
 }
 
 // ── Overview Pages ──
@@ -561,6 +634,36 @@ export interface ProductAdoptResult {
   sourceOrgDeleted: string;
 }
 
+// ── Taxonomy (categories + tags) ──
+
+export interface TaxonomyOrg {
+  slug: string;
+  name: string;
+  domain: string | null;
+  avatarUrl: string | null;
+}
+
+export interface TaxonomyProduct {
+  slug: string;
+  name: string;
+  description: string | null;
+  orgSlug: string;
+  orgName: string;
+}
+
+export interface CategoryDetail {
+  slug: string;
+  orgs: TaxonomyOrg[];
+  products: TaxonomyProduct[];
+}
+
+export interface TagDetail {
+  slug: string;
+  name: string;
+  orgs: TaxonomyOrg[];
+  products: TaxonomyProduct[];
+}
+
 // ── Releases (enriched) ──
 
 /** Flat release shape returned by GET /v1/releases/:id with source metadata. */