@buildinternet/releases-api-types 0.5.0 → 0.6.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.6.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;
@@ -520,6 +546,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 +685,8 @@ export interface ProductListItem {
   sourceCount: number;
 }
 
+export type ProductListResponse = ListResponse<ProductListItem>;
+
 export interface ProductDetail {
   id: string;
   name: string;
@@ -799,6 +872,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 {