@buildinternet/releases-api-types 0.5.0 → 0.7.0

package/README.md

@@ -15,16 +15,17 @@ npm install @buildinternet/releases-api-types
 ## Usage
 
 ```ts
-import type { OrgListItem } from "@buildinternet/releases-api-types";
+import type { OrgListResponse } from "@buildinternet/releases-api-types";
 
-async function listOrgs(): Promise<OrgListItem[]> {
+async function listOrgs(): Promise<OrgListResponse> {
   const res = await fetch("https://api.releases.sh/v1/orgs");
-  return (await res.json()) as OrgListItem[];
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return (await res.json()) as OrgListResponse;
 }
 ```
 
-Some list endpoints wrap results in a `ListResponse<T>` envelope (`{ items, pagination }`) — that contract lives in
-`@buildinternet/releases-core/cli-contracts`. Check the route docs at [releases.sh/docs/api](https://releases.sh/docs/api) for the exact shape per endpoint.
+Paginated list endpoints return a `ListResponse<T>` envelope (`{ items, pagination }`). The shared pagination semantics also live in
+`@buildinternet/releases-core/cli-contracts` for CLI callers.
 
 ## Versioning
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.5.0",
+  "version": "0.7.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

@@ -23,6 +23,22 @@ export interface Stats {
   products: number;
 }
 
+// ── Pagination ──
+
+export interface Pagination {
+  page: number;
+  pageSize: number;
+  returned: number;
+  totalItems?: number;
+  totalPages?: number;
+  hasMore: boolean;
+}
+
+export interface ListResponse<T> {
+  items: T[];
+  pagination: Pagination;
+}
+
 // ── Sitemap (bulk URL emission) ──
 
 export interface SitemapPayload {
@@ -47,6 +63,16 @@ export interface OrgListItem {
   sparkline: number[];
 }
 
+export type OrgListResponse = ListResponse<OrgListItem>;
+
+export interface OrgAccountItem {
+  platform: string;
+  handle: string;
+}
+
+export type OrgAccountsResponse = ListResponse<OrgAccountItem>;
+export type OrgTagsResponse = ListResponse<string>;
+
 export interface OrgDetail {
   id?: string;
   slug: string;
@@ -64,7 +90,7 @@ export interface OrgDetail {
   lastPolledAt: string | null;
   trackingSince: string;
   aliases?: string[];
-  accounts: { platform: string; handle: string }[];
+  accounts: OrgAccountItem[];
   products: Array<{
     id: string;
     slug: string;
@@ -238,13 +264,40 @@ export interface SourceDetail {
   lastPolledAt: string | null;
   trackingSince: string;
   releases: ReleaseItem[];
-  pagination: { page: number; pageSize: number; totalPages: number; totalItems: number };
+  pagination: Pagination;
   summaries: {
     rolling: ReleaseSummaryItem | null;
     monthly: ReleaseSummaryItem[];
   };
 }
 
+// ── Admin telemetry: orgs rollup ──
+
+export interface OrgsRollupRow {
+  /** Org slug, or "—" for sources without an org. */
+  orgSlug: string;
+  sourceCount: number;
+  /** Sources with no release on file or `latestDate` older than `staleDays`. */
+  staleCount: number;
+  /** Most-recent release across all of the org's sources, or null. */
+  mostRecentRelease: string | null;
+  mostRecentAgeDays: number | null;
+  /** True iff every source in the org is stale (and the org has at least one source). */
+  allStale: boolean;
+}
+
+export interface OrgsRollupResponse extends ListResponse<OrgsRollupRow> {
+  meta: {
+    /** Stale cutoff used server-side, in days. */
+    staleDays: number;
+    totalOrgs: number;
+    /** Orgs where every source is stale. */
+    dormantOrgs: number;
+    /** Orgs with at least one stale source. */
+    anyStaleOrgs: number;
+  };
+}
+
 // ── Releases ──
 
 /**
@@ -520,6 +573,51 @@ export interface OverviewPageItem {
 /** @deprecated Use OverviewPageItem */
 export type KnowledgePageItem = OverviewPageItem;
 
+// ── Overview Manifest (admin planning) ──
+
+export type OverviewStaleness = "missing" | "behind" | "fresh";
+export type OverviewPlanAction = "missing" | "refresh" | "skip";
+
+/**
+ * Per-org row returned by GET /v1/admin/overviews. Designed for orchestrators
+ * planning a maintenance sweep — `releasesSinceOverview` is the freshness
+ * signal that matters, not date diff alone.
+ */
+export interface OverviewManifestRow {
+  orgSlug: string;
+  orgName: string;
+  discovery: "curated" | "agent" | "on_demand";
+  overviewUpdatedAt: string | null;
+  overviewGeneratedAt: string | null;
+  lastContributingReleaseAt: string | null;
+  orgLastActivity: string | null;
+  releasesSinceOverview: number;
+  recentReleaseCount: number;
+  staleness: OverviewStaleness;
+  /** Only populated when ?format=plan. */
+  action?: OverviewPlanAction;
+  /** Only populated when ?format=plan. */
+  needsFetch?: boolean;
+}
+
+export type OverviewManifestResponse = ListResponse<OverviewManifestRow>;
+
+// ── Overview inputs (?check=true) ──
+
+/**
+ * Lightweight pre-flight payload returned by GET /v1/orgs/:slug/overview/inputs?check=true.
+ * Skips the heavy release-content hydration so an orchestrator can decide whether
+ * to dispatch without paying for the full payload.
+ */
+export interface OverviewInputsCheck {
+  orgSlug: string;
+  selected: number;
+  totalAvailable: number;
+  hasExistingContent: boolean;
+  wouldRegenerate: boolean;
+  windowDays: number;
+}
+
 /** @deprecated Use UnifiedSearchResponse */
 export type SearchResult = SearchReleaseHit;
 /** @deprecated Use UnifiedSearchResponse */
@@ -614,6 +712,8 @@ export interface ProductListItem {
   sourceCount: number;
 }
 
+export type ProductListResponse = ListResponse<ProductListItem>;
+
 export interface ProductDetail {
   id: string;
   name: string;
@@ -799,6 +899,29 @@ export interface Session {
   cancelRequested?: boolean;
 }
 
+export type SessionListResponse = ListResponse<Session>;
+
+// ── Admin URL Lists ──
+
+export interface IgnoredUrlItem {
+  id: string;
+  url: string;
+  orgId: string;
+  reason: string | null;
+  ignoredAt: string;
+}
+
+export interface BlockedUrlItem {
+  id: string;
+  pattern: string;
+  type: "exact" | "domain";
+  reason: string | null;
+  createdAt: string;
+}
+
+export type IgnoredUrlListResponse = ListResponse<IgnoredUrlItem>;
+export type BlockedUrlListResponse = ListResponse<BlockedUrlItem>;
+
 // ── Embed (admin) ──
 
 export interface EmbedBackfillResponse {
@@ -843,3 +966,23 @@ export interface EmbedStatusResponse {
   };
   chunks: { total: number; embedded: number; unembedded: number };
 }
+
+// ── Evaluate (URL recommendation) ──
+
+/**
+ * Returned verbatim by GET /v1/evaluate. Lives in the public api-types package
+ * so external consumers (CLI, third-party clients) can import the shape
+ * without depending on worker-internal AI helpers.
+ */
+export interface EvaluationResult {
+  recommendedMethod: "feed" | "github" | "markdown" | "scrape" | "crawl";
+  recommendedUrl: string;
+  feedUrl?: string;
+  feedType?: "rss" | "atom" | "jsonfeed";
+  githubRepo?: string;
+  pageStructure: "single-page" | "index" | "unknown";
+  alternatives: Array<{ url: string; method: string; note: string }>;
+  confidence: "high" | "medium" | "low";
+  provider?: string;
+  notes?: string;
+}