@buildinternet/releases-api-types 0.15.0 → 0.17.0

package/src/schemas/search.ts

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { MediaItemSchema, ReleaseTypeSchema } from "./shared.js";
+import { SourceTypeSchema } from "./sources.js";
+import { LookupStatusSchema } from "./lookups.js";
+
+/**
+ * Org hit on the unified `/v1/search` response. The list is built either
+ * from `searchOrgs` LIKE matches or, when `?domain=` resolves, from a
+ * single-row "scoped org" projection — both produce the same wire shape.
+ *
+ * `category` is loose (`z.string().nullable()`) rather than the canonical
+ * `CategorySchema` enum because the scoped-org projection passes the raw
+ * DB column through without going through `resolveCategoryInput`; legacy
+ * rows may carry deprecated slugs that haven't been migrated yet. Tighten
+ * once #689 (category overlay backfill) lands across the prod data set.
+ */
+export const SearchOrgHitSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
+  category: z.string().nullable(),
+});
+
+/**
+ * Unified catalog entry — either a product row or a standalone source
+ * presented as product-shaped. `kind` routes clicks to the right URL but
+ * the two forms are otherwise interchangeable for display. `kind` (not
+ * `type`) because source rows already carry
+ * `type: github|scrape|feed|agent` on the wire.
+ */
+export const SearchCatalogHitSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  orgSlug: z.string().nullable(),
+  orgName: z.string().nullable(),
+  // Loose `z.string().nullable()` rather than the canonical `CategorySchema`
+  // enum because `foldSourcesIntoCatalog` and the catalog-search handlers
+  // pass `s.productCategory` / `o.category` through without validating
+  // against `resolveCategoryInput`. Legacy rows may carry deprecated slugs
+  // that haven't been migrated yet. Tighten once #689 (category overlay
+  // backfill) lands across the prod data set.
+  category: z.string().nullable(),
+  kind: z.enum(["product", "source"]),
+  sourceSlug: z.string().optional(),
+  sourceType: SourceTypeSchema.optional(),
+});
+
+export const SearchSourceHitSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  type: SourceTypeSchema,
+  orgSlug: z.string().nullable(),
+  orgName: z.string().nullable(),
+  productSlug: z.string().nullable(),
+});
+
+export const SearchReleaseHitSchema = z.object({
+  id: z.string(),
+  sourceSlug: z.string(),
+  sourceName: z.string(),
+  // Loose `z.string()` rather than `SourceTypeSchema` because the
+  // release-hit hydration path reads `sources.type` straight from the DB
+  // without re-validating; legacy rows occasionally drift from the
+  // canonical four-value set. Used by the web byline icon.
+  sourceType: z.string().optional(),
+  orgSlug: z.string().nullable(),
+  orgName: z.string().nullable().optional(),
+  version: z.string().nullable(),
+  title: z.string(),
+  summary: z.string(),
+  titleGenerated: z.string().nullable().optional(),
+  titleShort: z.string().nullable().optional(),
+  content: z.string().optional(),
+  media: z.array(MediaItemSchema).optional(),
+  publishedAt: z.string().nullable(),
+  // Hybrid fusion score; absent on pure-lexical results.
+  score: z.number().optional(),
+  type: ReleaseTypeSchema.optional(),
+});
+
+/**
+ * Heading-aware CHANGELOG.md slice returned by hybrid / semantic search.
+ * Clients can deep-link to
+ * `/source/<sourceSlug>?tab=changelog&offset=<offset>` to read the
+ * surrounding file content.
+ */
+export const SearchChunkHitSchema = z.object({
+  sourceSlug: z.string(),
+  sourceName: z.string(),
+  orgSlug: z.string().nullable(),
+  orgName: z.string().nullable().optional(),
+  filePath: z.string(),
+  offset: z.number().int().min(0),
+  length: z.number().int().min(0),
+  heading: z.string().nullable(),
+  snippet: z.string(),
+  score: z.number(),
+});
+
+/**
+ * Slim wire payload embedded in a search response when the query is a
+ * GitHub `org/repo` coordinate and no existing entity matched. Reuses
+ * `LookupStatusSchema` from `./lookups.js` rather than redefining — the
+ * thick `POST /v1/lookups` response and the slim search-embedded payload
+ * share the same status set.
+ */
+export const LookupResultPayloadSchema = z.object({
+  status: LookupStatusSchema,
+  source: z
+    .object({
+      id: z.string(),
+      slug: z.string(),
+      name: z.string(),
+      url: z.string(),
+      discovery: z.enum(["curated", "agent", "on_demand"]),
+    })
+    .optional(),
+  releases: z
+    .array(
+      z.object({
+        id: z.string(),
+        version: z.string().nullable(),
+        title: z.string(),
+        publishedAt: z.string().nullable(),
+      }),
+    )
+    .optional(),
+  // Unambiguous "did you mean" rail; null when the org segment matches
+  // multiple curated orgs or none.
+  relatedOrg: z
+    .object({
+      org: z.object({ id: z.string(), slug: z.string(), name: z.string() }),
+      sources: z.array(
+        z.object({ id: z.string(), slug: z.string(), name: z.string(), url: z.string() }),
+      ),
+    })
+    .nullable(),
+});
+
+export const UnifiedSearchResponseSchema = z.object({
+  query: z.string(),
+  // Normalized `?domain=` echo + resolution outcome. Both absent when no
+  // domain filter was applied.
+  domain: z.string().optional(),
+  domainStatus: z.enum(["matched", "not_found"]).optional(),
+  orgs: z.array(SearchOrgHitSchema),
+  catalog: z.array(SearchCatalogHitSchema),
+  sources: z.array(SearchSourceHitSchema),
+  releases: z.array(SearchReleaseHitSchema),
+  chunks: z.array(SearchChunkHitSchema).optional(),
+  mode: z.enum(["lexical", "semantic", "hybrid"]).optional(),
+  degraded: z.boolean().optional(),
+  degradedReason: z.string().optional(),
+  lookup: LookupResultPayloadSchema.nullable().optional(),
+});

package/src/schemas/sitemap.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+/**
+ * Per-source row in `GET /v1/sitemap`. `hasChangelog` and `hasHighlights`
+ * are `.optional()` for backwards compatibility — older clients ignore the
+ * fields, but the current handler always populates them (#875).
+ */
+export const SitemapSourceSchema = z.object({
+  orgSlug: z.string(),
+  slug: z.string(),
+  latestDate: z.string().nullable(),
+  /**
+   * 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.
+   */
+  hasChangelog: z.boolean().optional(),
+  /**
+   * Whether this source has any rolling or monthly highlight summaries.
+   * Drives `/{org}/{src}/highlights` sitemap emission.
+   */
+  hasHighlights: z.boolean().optional(),
+});
+
+/**
+ * Bulk URL payload consumed by the web sitemap generator. Lists every
+ * orgs/sources/products/collections slug paired with the timestamp the web
+ * uses to drive `<lastmod>`. Soft-deleted / hidden / on_demand rows are
+ * excluded.
+ */
+export const SitemapPayloadSchema = z.object({
+  orgs: z.array(z.object({ slug: z.string(), lastActivity: z.string().nullable() })),
+  sources: z.array(SitemapSourceSchema),
+  products: z.array(z.object({ orgSlug: z.string(), slug: z.string() })),
+  collections: z.array(z.object({ slug: z.string(), updatedAt: z.string() })),
+});

package/src/schemas/sources.ts

@@ -265,3 +265,294 @@ export const SourceChangelogResponseSchema = z.object({
    */
   files: z.array(ChangelogFileSummarySchema),
 });
+
+// ── Source activity (/sources/:slug/activity, /orgs/:orgSlug/sources/:sourceSlug/activity) ──
+
+const SourceActivityWeeklyBucketSchema = z.object({
+  weekStart: z.string(),
+  count: z.number().int().min(0),
+  earliestVersion: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+});
+
+/**
+ * Response shape for `GET /v1/sources/:slug/activity` and the org-scoped twin.
+ * Returns week-bucketed release counts for the full tracking lifetime of the source.
+ * Optional `?from=YYYY-MM-DD` and `?to=YYYY-MM-DD` narrow the range.
+ */
+export const SourceActivityResponseSchema = z.object({
+  source: z.object({
+    slug: z.string(),
+    name: z.string(),
+    orgSlug: z.string().nullable(),
+    orgName: z.string().nullable(),
+  }),
+  range: z.object({ from: z.string(), to: z.string() }),
+  weeklyBuckets: z.array(SourceActivityWeeklyBucketSchema),
+});
+
+// ── Source heatmap (/sources/:slug/heatmap, /orgs/:orgSlug/sources/:sourceSlug/heatmap) ──
+
+/**
+ * Response shape for `GET /v1/sources/:slug/heatmap` and the org-scoped twin.
+ * Returns daily release counts for the trailing 365 days — contribution-graph
+ * visualization for the source detail page.
+ */
+export const SourceHeatmapResponseSchema = z.object({
+  source: z.object({ slug: z.string(), name: z.string() }),
+  range: z.object({ from: z.string(), to: z.string() }),
+  dailyCounts: z.array(z.object({ date: z.string(), count: z.number().int().min(0) })),
+  total: z.number().int().min(0),
+});
+
+// ── Source known releases (/sources/:slug/known-releases, /orgs/:orgSlug/…) ──
+
+/**
+ * Single row returned inside `GET /v1/sources/:slug/known-releases`. Minimal
+ * identifier set used by the incremental parsing agent to skip already-known
+ * versions without fetching full content.
+ */
+export const SourceKnownReleaseItemSchema = z.object({
+  version: z.string().nullable(),
+  title: z.string(),
+  publishedAt: z.string().nullable(),
+});
+
+/**
+ * Response shape for `GET /v1/sources/:slug/known-releases`. Returns the
+ * N most-recent non-suppressed releases (default N=10, max 500), ordered
+ * by `publishedAt` descending. Accepts `?limit=N`.
+ */
+export const SourceKnownReleasesResponseSchema = z.array(SourceKnownReleaseItemSchema);
+
+// ── Source recent releases (/sources/:slug/recent-releases, /orgs/:orgSlug/…) ──
+
+/**
+ * Response shape for `GET /v1/sources/:slug/recent-releases`. Returns the
+ * full release rows (non-suppressed, published at or after `?cutoff=`) ordered
+ * by `publishedAt` descending. Used by the summarization agent to retrieve the
+ * release window it needs to summarize. `?cutoff=` is required (ISO-8601 date
+ * string); missing `?cutoff=` returns 400.
+ */
+export const SourceRecentReleasesResponseSchema = z.array(
+  z.looseObject({
+    id: z.string(),
+    sourceId: z.string(),
+    version: z.string().nullable(),
+    title: z.string(),
+    content: z.string(),
+    url: z.string().nullable(),
+    publishedAt: z.string().nullable(),
+    fetchedAt: z.string().optional(),
+  }),
+);
+
+// ── Source sessions (/sources/:slug/sessions) ──
+
+/**
+ * Response shape for `GET /v1/sources/:slug/sessions`. Returns the active
+ * discovery session (if any) touching this source. The session object is the
+ * live DO state blob from the `StatusHub` Durable Object. Returns `{ sessions:
+ * [] }` when no active session references this source.
+ */
+export const SourceSessionsResponseSchema = z.object({
+  sessions: z.array(z.record(z.string(), z.unknown())),
+});
+
+// ── Source summaries (/sources/:slug/summaries) ──
+
+/**
+ * Full summary row as stored in `release_summaries`, returned by
+ * `GET /v1/sources/:slug/summaries`. Filter by `?type=rolling|monthly`,
+ * `?year=`, `?month=`.
+ */
+export const SourceSummaryRowSchema = z.object({
+  id: z.string().optional(),
+  sourceId: z.string(),
+  orgId: z.string().nullable(),
+  type: z.enum(["rolling", "monthly"]),
+  year: z.number().int().nullable(),
+  month: z.number().int().nullable(),
+  windowDays: z.number().int().nullable(),
+  summary: z.string(),
+  releaseCount: z.number().int().min(0),
+  generatedAt: z.string(),
+});
+
+export const SourceSummariesResponseSchema = z.array(SourceSummaryRowSchema);
+
+/**
+ * Body accepted by `POST /v1/sources/:slug/summaries`.
+ *
+ * `month` is calendar-bounded (1..12) and `windowDays` must be a positive
+ * integer when present — silently dropping wrong-typed values masks client
+ * bugs, so the validator rejects them explicitly. `year` is not bound-checked
+ * (any cutoff would be arbitrary).
+ */
+export const CreateSourceSummaryBodySchema = z.object({
+  type: z.enum(["rolling", "monthly"]),
+  year: z.number().int().nullable().optional(),
+  month: z.number().int().min(1).max(12).nullable().optional(),
+  windowDays: z.number().int().min(1).nullable().optional(),
+  summary: z.string().min(1),
+  releaseCount: z.number().int().min(0),
+});
+
+/** Response for `POST /v1/sources/:slug/summaries` (upsert). */
+export const CreateSourceSummaryResponseSchema = z.object({
+  ok: z.literal(true),
+});
+
+// ── Source fetch trigger (POST /sources/:slug/fetch) ──
+
+/**
+ * Response shape for `POST /v1/sources/:slug/fetch`. Two branches:
+ *   - Feed/GitHub/scraped-with-feed sources: `{ fetched: true, releasesInserted, … }`
+ *   - Scrape/agent sources (flagged for CLI pickup): `{ queued: true, type: "flagged" }`
+ */
+export const SourceFetchResponseSchema = z.union([
+  z.looseObject({ fetched: z.literal(true) }),
+  z.object({ queued: z.literal(true), type: z.string() }),
+]);
+
+// ── Source content-hash check (POST /sources/:slug/content-hash) ──
+
+/** Response for `POST /v1/sources/:slug/content-hash`. */
+export const SourceContentHashResponseSchema = z.union([
+  z.object({ unchanged: z.literal(true) }),
+  z.object({ unchanged: z.literal(false) }),
+]);
+
+/** Body for `POST /v1/sources/:slug/content-hash`. */
+export const SourceContentHashBodySchema = z.object({
+  contentHash: z.string().min(1),
+});
+
+// ── Changelog token backfill (PATCH /sources/:slug/changelog/tokens) ──
+
+/** Response for `PATCH /v1/sources/:slug/changelog/tokens`. */
+export const ChangelogTokensResponseSchema = z.object({
+  path: z.string(),
+  oldTokens: z.number().int().nullable(),
+  tokens: z.number().int().min(0),
+});
+
+// ── Source metadata merge (PATCH /sources/:slug/metadata) ──
+
+/** Response for `PATCH /v1/sources/:slug/metadata`. Echoes the merged metadata object. */
+export const SourceMetadataResponseSchema = z.object({
+  metadata: z.record(z.string(), z.unknown()),
+});
+
+// ── Changelog probe (POST /sources/:slug/changelog/probe) ──
+
+/** Response for `POST /v1/sources/:slug/changelog/probe`. */
+export const ChangelogProbeResponseSchema = z.object({
+  sourceId: z.string(),
+  sourceSlug: z.string(),
+  url: z.string(),
+  paths: z.array(z.string()),
+});
+
+// ── Delete source (DELETE /sources/:slug) ──
+
+/**
+ * Response for `DELETE /v1/sources/:slug`. Two shapes:
+ *   - Soft delete: `{ deleted: true, deletedAt: "<iso>" }`
+ *   - Hard delete (`?hard=true`): `{ deleted: true, hard: true }`
+ */
+export const DeleteSourceResponseSchema = z.union([
+  z.object({ deleted: z.literal(true), deletedAt: z.string() }),
+  z.object({ deleted: z.literal(true), hard: z.literal(true) }),
+]);
+
+// ── Delete source releases (DELETE /sources/:slug/releases) ──
+
+/**
+ * Response for `DELETE /v1/sources/:slug/releases`. Two shapes:
+ *   - Soft (`?hard` absent): `{ suppressed: N }` — releases hidden, not deleted
+ *   - Hard (`?hard=true`): `{ deleted: N, hard: true }`
+ */
+export const DeleteSourceReleasesResponseSchema = z.union([
+  z.object({ suppressed: z.number().int().min(0) }),
+  z.object({ deleted: z.number().int().min(0), hard: z.literal(true) }),
+]);
+
+// ── Single release insert (POST /sources/:slug/releases) ──
+
+/**
+ * Response for `POST /v1/sources/:slug/releases`. Returns the inserted release
+ * row (201) or `{ skipped: true }` (200) on URL conflict.
+ */
+export const InsertReleaseResponseSchema = z.union([
+  z.looseObject({
+    id: z.string(),
+    sourceId: z.string(),
+    title: z.string(),
+  }),
+  z.object({ skipped: z.literal(true) }),
+]);
+
+// ── Batch release insert (POST /sources/:slug/releases/batch) ──
+
+/** Response for `POST /v1/sources/:slug/releases/batch`. */
+export const BatchReleasesResponseSchema = z.object({
+  inserted: z.number().int().min(0),
+  total: z.number().int().min(0),
+});
+
+// ── Oversized changelog files (GET /sources/changelog-files/oversized) ──
+
+/**
+ * Row returned by `GET /v1/sources/changelog-files/oversized`. Each row is a
+ * changelog file whose content length exceeds `?minBytes=` (default 256 KB).
+ * Used by `scripts/backfill-changelog-tokens.ts` to find rows with estimated
+ * (not exact) token counts.
+ */
+export const OversizedChangelogFileRowSchema = z.object({
+  sourceId: z.string(),
+  sourceSlug: z.string(),
+  sourceName: z.string(),
+  orgSlug: z.string(),
+  path: z.string(),
+  filename: z.string(),
+  bytes: z.number().int().min(0),
+  tokens: z.number().int().nullable(),
+  fetchedAt: z.string(),
+});
+
+export const OversizedChangelogFilesResponseSchema = z.array(OversizedChangelogFileRowSchema);
+
+// ── Fetchable sources (GET /sources/fetchable) ──
+
+/**
+ * Response for `GET /v1/sources/fetchable`. Returns raw source rows matching
+ * the requested fetch mode (`?mode=unfetched|stale|retry_errors|all`).
+ * Accepts `?staleHours=N` when `mode=stale`.
+ */
+export const FetchableSourcesResponseSchema = z.array(
+  z.looseObject({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    type: SourceTypeSchema,
+    url: z.string(),
+    metadata: z.string().nullable(),
+  }),
+);
+
+// ── Feed sources (GET /sources/feeds) ──
+
+/**
+ * Response for `GET /v1/sources/feeds`. Returns visible source rows where
+ * `metadata.feedUrl` is set and `fetchPriority != 'paused'`.
+ */
+export const FeedSourcesResponseSchema = FetchableSourcesResponseSchema;
+
+// ── Changed sources (GET /sources/changes) ──
+
+/**
+ * Response for `GET /v1/sources/changes`. Returns visible source rows that
+ * have a non-null `changeDetectedAt` — the set flagged for CLI pickup.
+ */
+export const ChangedSourcesResponseSchema = FetchableSourcesResponseSchema;

package/src/schemas/stats.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { StatsSchema } from "./shared.js";
+
+/**
+ * Per-source activity row in `GET /v1/stats`. `orgName` is nullable because
+ * the source-to-org JOIN is left-joined (legacy orphan sources still exist).
+ */
+export const StatsSourceActivitySchema = z.object({
+  sourceName: z.string(),
+  sourceSlug: z.string(),
+  sourceType: z.string(),
+  orgName: z.string().nullable(),
+  lastFetchedAt: z.string().nullable(),
+  totalReleases: z.number(),
+  recentReleases: z.number(),
+});
+
+/**
+ * Recent fetch-log row, joined with source + org for display. `durationMs`
+ * and `error` are nullable on the underlying table; `orgName` is nullable
+ * for the same orphan-source reason as above.
+ */
+export const StatsRecentActivitySchema = z.object({
+  sourceName: z.string(),
+  sourceSlug: z.string(),
+  orgName: z.string().nullable(),
+  releasesFound: z.number(),
+  releasesInserted: z.number(),
+  totalReleases: z.number(),
+  status: z.string(),
+  durationMs: z.number().nullable(),
+  error: z.string().nullable(),
+  createdAt: z.string(),
+});
+
+/**
+ * Response shape for `GET /v1/stats`. The handler returns a hybrid payload —
+ * the flat `Stats` counts (legacy `orgs/sources/releases/products` fields used
+ * by the web homepage banner) merged with the richer `StatsSummary` shape
+ * (period window + totals + sourceHealth + sourceActivity + recentActivity).
+ * Modelled with `z.object` over the union of both shapes; consumers may
+ * pick either subset.
+ */
+export const StatsResponseSchema = StatsSchema.extend({
+  period: z.object({
+    days: z.number().int().min(1),
+    cutoff: z.string(),
+  }),
+  totals: z.object({
+    organizations: z.number().int().min(0),
+    sources: z.number().int().min(0),
+    releases: z.number().int().min(0),
+    releasesInPeriod: z.number().int().min(0),
+  }),
+  sourceHealth: z.object({
+    upToDate: z.number().int().min(0),
+    stale: z.number().int().min(0),
+    neverFetched: z.number().int().min(0),
+  }),
+  sourceActivity: z.array(StatsSourceActivitySchema),
+  recentActivity: z.array(StatsRecentActivitySchema),
+});

package/src/schemas/taxonomy.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { CategorySchema } from "./shared.js";
+import { CollectionReleaseItemSchema } from "./collections.js";
+
+/**
+ * Org rollup row shared by category and tag detail responses. Slim by
+ * design — taxonomy pages link out to the full org detail page rather
+ * than embedding it.
+ */
+export const TaxonomyOrgSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
+});
+
+/** Product rollup row, paired with `TaxonomyOrg`. */
+export const TaxonomyProductSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  orgSlug: z.string(),
+  orgName: z.string(),
+});
+
+/**
+ * Per-category row on `GET /v1/categories`. Categories are a fixed
+ * taxonomy (`CATEGORIES` in `@buildinternet/releases-core/categories`),
+ * so the response always includes every slug, including ones with zero
+ * members. `name` / `description` / `aliases` come from the optional
+ * `categories` metadata overlay; `description` is null when no override
+ * has been set.
+ */
+export const CategoryListItemSchema = z.object({
+  slug: CategorySchema,
+  name: z.string(),
+  description: z.string().nullable(),
+  aliases: z.array(z.string()),
+  orgCount: z.number().int().min(0),
+  productCount: z.number().int().min(0),
+});
+
+export const CategoryListResponseSchema = z.array(CategoryListItemSchema);
+
+/** Returned by `GET /v1/categories/:slug` for the canonical slug. */
+export const CategoryDetailSchema = z.object({
+  slug: CategorySchema,
+  name: z.string(),
+  description: z.string().nullable(),
+  aliases: z.array(z.string()),
+  orgs: z.array(TaxonomyOrgSchema),
+  products: z.array(TaxonomyProductSchema),
+});
+
+/**
+ * Body accepted by `PATCH /v1/categories/:slug`. All fields are optional,
+ * but the body must set at least one of them — an empty body is rejected.
+ * `name` and `description` accept `null` to clear the overlay value;
+ * `aliases` replaces the full set (pass `[]` to clear). The row is
+ * upserted — categories that have never been customized have no row.
+ *
+ * `name` is bounded at 200 chars and `description` at 2000. Alias element
+ * shape (kebab-case, not a canonical slug, not claimed by another row) is
+ * enforced in the handler after the strings are trimmed + lowercased, since
+ * those checks depend on runtime state and case-folding.
+ */
+export const UpdateCategoryRequestSchema = z
+  .object({
+    name: z.string().max(200).nullable().optional(),
+    description: z.string().max(2000).nullable().optional(),
+    aliases: z.array(z.string()).optional(),
+  })
+  .refine((b) => b.name !== undefined || b.description !== undefined || b.aliases !== undefined, {
+    message: "Body must set at least one of `name`, `description`, or `aliases`",
+  });
+
+/** Response from `PATCH /v1/categories/:slug` — the resolved overlay values. */
+export const UpdateCategoryResponseSchema = z.object({
+  slug: CategorySchema,
+  name: z.string(),
+  description: z.string().nullable(),
+  aliases: z.array(z.string()),
+});
+
+/**
+ * Aggregated release row on `GET /v1/categories/:slug/releases`. Same wire
+ * shape as `CollectionReleaseItem` — both surfaces aggregate across orgs and
+ * use `formatAggregateReleaseRow` in `workers/api/src/utils.ts` for the
+ * formatting. Re-exported here so the two endpoints describe one schema
+ * instead of two drifting copies.
+ */
+export const CategoryReleaseItemSchema = CollectionReleaseItemSchema;
+
+export const CategoryFeedPaginationSchema = z.object({
+  nextCursor: z.string().nullable(),
+  limit: z.number().int().min(1),
+});
+
+export const CategoryReleasesResponseSchema = z.object({
+  releases: z.array(CategoryReleaseItemSchema),
+  pagination: CategoryFeedPaginationSchema,
+});
+
+/** Returned by `GET /v1/tags/:slug`. */
+export const TagDetailSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  orgs: z.array(TaxonomyOrgSchema),
+  products: z.array(TaxonomyProductSchema),
+});