@buildinternet/releases-api-types 0.49.0 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@buildinternet/releases-core": "^0.29.0",
+    "@buildinternet/releases-core": "^0.30.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -363,6 +363,7 @@ export {
   ListingPromoteLocatorOutcomeSchema,
   ListingPromoteLocatorSchema,
   ListingPromoteResultSchema,
+  ListingCapabilitiesSchema,
   type ListingValidateBody,
   type ListingActivateBody,
   type ListingIssue,
@@ -381,6 +382,7 @@ export {
   type ListingPromoteLocatorOutcome,
   type ListingPromoteLocator,
   type ListingPromoteResult,
+  type ListingCapabilities,
 } from "./schemas/listing.js";
 export {
   SourceListItemSchema,
@@ -641,7 +643,9 @@ export interface CreateUserApiKeyBody {
 
 export type SitemapSource = z.infer<typeof SitemapSourceSchema>;
 export type SitemapPayload = z.infer<typeof SitemapPayloadSchema>;
+/** @deprecated The `GET /v1/sitemap/releases` endpoint was retired in #2219. */
 export type SitemapRelease = z.infer<typeof SitemapReleaseSchema>;
+/** @deprecated The `GET /v1/sitemap/releases` endpoint was retired in #2219. */
 export type SitemapReleasesPayload = z.infer<typeof SitemapReleasesPayloadSchema>;
 
 // ── Related (Vectorize neighbors) ──
@@ -825,6 +829,49 @@ export interface StuckSourcesResponse extends ListResponse<StuckSource> {
   };
 }
 
+// ── Admin telemetry: provider / ingest health ──
+
+/**
+ * A source flagged as "overdue for evaluation" — `sources.last_fetched_at`
+ * (written on every successful check, including `no_change`) is older than
+ * the health scan's threshold, or null. This is deliberately independent of
+ * release recency: a source can be perfectly healthy (actively checked, just
+ * quiet) while its latest release is months old, and conversely every source
+ * can look quiet-but-fine by release date while the thing that checks them —
+ * ingest, extraction, the AI provider — has silently stopped running. See the
+ * 2026-07-23 spend-cap outage (#2168): `last_fetched_at` froze across every
+ * affected source for six days while nothing else changed.
+ */
+export interface ProviderHealthSource {
+  sourceId: string;
+  sourceSlug: string;
+  name: string;
+  type: SourceType;
+  orgSlug: string | null;
+  orgName: string | null;
+  fetchPriority: SourceFetchPriority;
+  isPrimary: boolean;
+  /** `sources.last_fetched_at` — null when the source has never been fetched successfully. */
+  lastFetchedAt: string | null;
+  /** Days since `lastFetchedAt` (or since the source was created, if never fetched). */
+  daysSinceFetched: number;
+}
+
+export interface ProviderHealthResponse extends ListResponse<ProviderHealthSource> {
+  meta: {
+    /** A source is "overdue" once its last successful check exceeds this many days. */
+    overdueThresholdDays: number;
+    /** Active (non-paused, non-deleted) sources considered by the scan. */
+    totalActiveSources: number;
+    /** Sources whose last successful check is older than the threshold, or never. */
+    overdueSources: number;
+    /** Distinct orgs with at least one overdue source. */
+    overdueOrgs: number;
+    /** Distinct orgs represented among active sources. */
+    totalOrgs: number;
+  };
+}
+
 // ── Releases ──
 
 /**

package/src/schemas/listing.ts

@@ -168,3 +168,16 @@ export const ListingPromoteResultSchema = z.strictObject({
   locators: z.array(ListingPromoteLocatorSchema),
 });
 export type ListingPromoteResult = z.infer<typeof ListingPromoteResultSchema>;
+
+/**
+ * Public capability flags for the listing lane. Anonymous + always reachable
+ * (does NOT 404 when either kill switch is off) so the web UI can hide CTAs
+ * instead of offering a button that fails with "Not found".
+ */
+export const ListingCapabilitiesSchema = z.strictObject({
+  /** `listing-self-serve-enabled` — validate / activate / claim / verify. */
+  selfServeEnabled: z.boolean(),
+  /** `listing-self-serve-promotion-enabled` — POST /v1/listing/promote. */
+  promotionEnabled: z.boolean(),
+});
+export type ListingCapabilities = z.infer<typeof ListingCapabilitiesSchema>;

package/src/schemas/sitemap.ts

@@ -57,9 +57,14 @@ export const SitemapPayloadSchema = z.object({
 });
 
 /**
- * Per-release row in `GET /v1/sitemap/releases` (#1181, scoped down). Carries
- * exactly what the web needs to build the slugged canonical `/release/...`
- * URL (`releasePath()` inputs) plus `fetchedAt` for `<lastmod>`.
+ * Per-release row previously returned by `GET /v1/sitemap/releases` (#1181,
+ * scoped down). Carries what the web needed to build the slugged canonical
+ * `/release/...` URL (`releasePath()` inputs) plus `fetchedAt` for `<lastmod>`.
+ *
+ * @deprecated The endpoint was retired in #2219 — its only consumer
+ * (`sitemap-releases.xml`) was removed in #2218 when release pages went
+ * `noindex`. Kept for one minor version per the deprecation lane; will be
+ * removed in a future minor.
  */
 export const SitemapReleaseSchema = z.object({
   id: z.string(),
@@ -72,8 +77,12 @@ export const SitemapReleaseSchema = z.object({
 });
 
 /**
- * Payload for the curated release sitemap: visible releases with a summary
- * and importance at or above the experiment threshold, newest first, capped.
+ * Payload previously returned by the curated release sitemap endpoint.
+ *
+ * @deprecated The endpoint was retired in #2219 — its only consumer
+ * (`sitemap-releases.xml`) was removed in #2218 when release pages went
+ * `noindex`. Kept for one minor version per the deprecation lane; will be
+ * removed in a future minor.
  */
 export const SitemapReleasesPayloadSchema = z.object({
   releases: z.array(SitemapReleaseSchema),