@buildinternet/releases-api-types 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.14.0",
+  "version": "0.16.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.19.0",
+    "@buildinternet/releases-core": "^0.21.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -133,7 +133,23 @@ export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
 
 export interface SitemapPayload {
   orgs: Array<{ slug: string; lastActivity: string | null }>;
-  sources: Array<{ orgSlug: string; slug: string; latestDate: string | null }>;
+  sources: Array<{
+    orgSlug: string;
+    slug: string;
+    latestDate: string | null;
+    /**
+     * Whether this source has a stored GitHub CHANGELOG file. Used by the web
+     * sitemap to emit `/{org}/{src}/changelog` URLs only for sources where the
+     * route resolves (#875). Optional for backwards compatibility — older
+     * clients ignore it.
+     */
+    hasChangelog?: boolean;
+    /**
+     * Whether this source has any rolling or monthly highlight summaries.
+     * Drives `/{org}/{src}/highlights` sitemap emission (#875).
+     */
+    hasHighlights?: boolean;
+  }>;
   products: Array<{ orgSlug: string; slug: string }>;
   collections: Array<{ slug: string; updatedAt: string }>;
 }
@@ -681,10 +697,71 @@ export interface TaxonomyProduct {
 
 export interface CategoryDetail {
   slug: string;
+  /**
+   * Display name — operator override from the `categories` table if present,
+   * otherwise `categoryDisplayName(slug)` from `@buildinternet/releases-core`.
+   */
+  name: string;
+  /**
+   * Operator-authored byline shown on the web category page. Null when no
+   * description has been set; clients render their own fallback copy.
+   */
+  description: string | null;
+  /**
+   * Alternative slugs that redirect to this canonical category. Empty when
+   * no aliases have been configured.
+   */
+  aliases: string[];
   orgs: TaxonomyOrg[];
   products: TaxonomyProduct[];
 }
 
+/**
+ * Item shape on GET /v1/categories — the overview list. Categories are a
+ * fixed taxonomy (`CATEGORIES` in `@buildinternet/releases-core/categories`),
+ * so the API always returns every slug, including ones with zero members.
+ * `orgCount` counts orgs whose `category` matches; `productCount` counts
+ * products whose own `category` matches (overriding any parent-org category).
+ * Both counts pass through `organizations_public`, so on_demand and
+ * soft-deleted orgs are excluded. `description` comes from the optional
+ * `categories` metadata overlay; null when no override has been set.
+ */
+export interface CategoryListItem {
+  slug: string;
+  name: string;
+  description: string | null;
+  aliases: string[];
+  orgCount: number;
+  productCount: number;
+}
+
+/**
+ * PATCH /v1/categories/:slug request body. All fields are optional. `name`
+ * and `description` accept `null` to clear the override; `aliases` replaces
+ * the full set when provided (pass `[]` to clear). The row is upserted —
+ * a category that has never been customized has no row in the table.
+ *
+ * Each alias must be a kebab-case slug not already in `CATEGORIES` and not
+ * claimed by another category row.
+ */
+export interface UpdateCategoryRequest {
+  name?: string | null;
+  description?: string | null;
+  aliases?: string[];
+}
+
+/**
+ * Aggregated release feed row for a category rollup — same wire shape as
+ * `CollectionReleaseItem` (both surfaces aggregate releases across multiple
+ * orgs). Aliased rather than duplicated so renderers can treat them as one.
+ */
+export type CategoryReleaseItem = CollectionReleaseItem;
+
+export interface CategoryReleasesResponse {
+  releases: CategoryReleaseItem[];
+  pagination: { nextCursor: string | null; limit: number };
+}
+
 export interface TagDetail {
   slug: string;
   name: string;

package/src/schemas/shared.ts

@@ -47,6 +47,12 @@ export const ReleaseItemSchema = z.object({
   summary: z.string(),
   content: z.string().optional(),
   publishedAt: z.string().nullable(),
+  // ISO timestamp of when the row was fetched/inserted — used by the feed
+  // cursor's tie-break (publishedAt|fetchedAt|id) so that same-`publishedAt`
+  // rows stay stably ordered across paginated requests. `.optional()` because
+  // not every endpoint that returns a ReleaseItem populates it (notably
+  // single-release reads).
+  fetchedAt: z.string().optional(),
   url: z.string().nullable(),
   media: z.array(MediaItemSchema).optional(),
   // `.optional()` — older API responses (mid-deploy or pinned old workers)