@buildinternet/releases-api-types 0.33.0 → 0.34.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "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.23.0",
+    "@buildinternet/releases-core": "^0.24.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -13,6 +13,7 @@ export type {
 // Re-export above doesn't create local bindings; import for use in interfaces below.
 import type { SourceType, SourceFetchPriority } from "@buildinternet/releases-core/source-enums";
 import type { ApiScope } from "@buildinternet/releases-core/api-token";
+import type { BreakingLevel } from "@buildinternet/releases-core/breaking";
 import type {
   MediaItemSchema,
   PaginationSchema,
@@ -59,6 +60,12 @@ import type {
   OrgRecentReleasesResponseSchema,
   DeleteOrgAccountResponseSchema,
 } from "./schemas/orgs.js";
+import type {
+  UploadAvatarResponseSchema,
+  WorkspaceProfileFieldsSchema,
+  PatchWorkspaceProfileBodySchema,
+  WorkspaceProfileResponseSchema,
+} from "./schemas/account-profile.js";
 import type {
   SourceListItemSchema,
   SourceWithOrgSchema,
@@ -138,9 +145,13 @@ import type {
   UpdateReleaseBodySchema,
   ReleasePatchResponseSchema,
   ReleaseDeleteResponseSchema,
+  ReleaseBatchDeleteBodySchema,
+  ReleaseBatchDeleteResponseSchema,
   ReleaseSuppressResponseSchema,
   ReleaseUnsuppressResponseSchema,
   ReleaseSuppressBodySchema,
+  ReleaseBatchSuppressBodySchema,
+  ReleaseBatchSuppressResponseSchema,
   ReleaseStreamMessageSchema,
 } from "./schemas/releases.js";
 import type {
@@ -225,6 +236,8 @@ import type {
   ResolvedCollectionMemberSchema,
   ReplaceCollectionMembersResponseSchema,
   AddCollectionMemberResponseSchema,
+  CollectionDailySummarySchema,
+  CollectionDailySummariesResponseSchema,
 } from "./schemas/collections.js";
 import type {
   OrgOverviewResponseSchema,
@@ -255,6 +268,7 @@ export {
   CategorySchema,
   NoticeSchema,
 } from "./schemas/shared.js";
+export { SiteNoticeSchema, SiteNoticeResponseSchema } from "./schemas/site-notice.js";
 export {
   OrgListItemSchema,
   OrgListResponseSchema,
@@ -289,6 +303,12 @@ export {
   OrgRecentReleasesResponseSchema,
   DeleteOrgAccountResponseSchema,
 } from "./schemas/orgs.js";
+export {
+  UploadAvatarResponseSchema,
+  WorkspaceProfileFieldsSchema,
+  PatchWorkspaceProfileBodySchema,
+  WorkspaceProfileResponseSchema,
+} from "./schemas/account-profile.js";
 export {
   ReleasesJsonConfigSchema,
   ReleasesJsonProductSchema,
@@ -400,9 +420,13 @@ export {
   UpdateReleaseBodySchema,
   ReleasePatchResponseSchema,
   ReleaseDeleteResponseSchema,
+  ReleaseBatchDeleteBodySchema,
+  ReleaseBatchDeleteResponseSchema,
   ReleaseSuppressResponseSchema,
   ReleaseUnsuppressResponseSchema,
   ReleaseSuppressBodySchema,
+  ReleaseBatchSuppressBodySchema,
+  ReleaseBatchSuppressResponseSchema,
   ReleaseStreamMessageSchema,
 } from "./schemas/releases.js";
 export {
@@ -462,6 +486,8 @@ export {
   ResolvedCollectionMemberSchema,
   ReplaceCollectionMembersResponseSchema,
   AddCollectionMemberResponseSchema,
+  CollectionDailySummarySchema,
+  CollectionDailySummariesResponseSchema,
 } from "./schemas/collections.js";
 export {
   OrgOverviewResponseSchema,
@@ -560,6 +586,10 @@ export type CreateOrgBody = z.infer<typeof CreateOrgBodySchema>;
 export type UpdateOrgBody = z.infer<typeof UpdateOrgBodySchema>;
 export type SetOrgAvatarBody = z.infer<typeof SetOrgAvatarBodySchema>;
 export type SetOrgAvatarResponse = z.infer<typeof SetOrgAvatarResponseSchema>;
+export type UploadAvatarResponse = z.infer<typeof UploadAvatarResponseSchema>;
+export type WorkspaceProfileFields = z.infer<typeof WorkspaceProfileFieldsSchema>;
+export type PatchWorkspaceProfileBody = z.infer<typeof PatchWorkspaceProfileBodySchema>;
+export type WorkspaceProfileResponse = z.infer<typeof WorkspaceProfileResponseSchema>;
 export type OrgDetail = z.infer<typeof OrgDetailSchema>;
 
 export type OrgCatalogItem = z.infer<typeof OrgCatalogItemSchema>;
@@ -724,6 +754,44 @@ export type ReleaseType = z.infer<typeof ReleaseTypeSchema>;
 export type ReleaseItem = z.infer<typeof ReleaseItemSchema>;
 export type ReleaseComposition = z.infer<typeof ReleaseCompositionSchema>;
 
+/**
+ * One entry in a {@link WhatsChangedResponse} — a release in the requested
+ * upgrade range; a slim, release-derived projection. `breaking`/`migrationNotes`
+ * come from #1696 (`"unknown"` until classified or for non-dev-facing kinds).
+ */
+export interface WhatsChangedEntry {
+  version: string | null;
+  publishedAt: string | null;
+  /** AI-generated title when present, else the raw release title. */
+  title: string | null;
+  summary: string | null;
+  breaking: BreakingLevel;
+  migrationNotes: string | null;
+  url: string | null;
+}
+
+/**
+ * Response of `GET /v1/whats-changed` (#1697, upgrade intelligence Phase 1) —
+ * the changelog entries in the half-open version range `(from, to]` for a
+ * package (`from` exclusive, `to` inclusive). `status: "unknown"` (still
+ * HTTP 200 — a valid answer, not an error) when the package can't be resolved
+ * read-only from the catalog (e.g. an npm/PyPI name absent until #1345).
+ * `entries` are ordered oldest→newest; a range wider than the token budget is
+ * truncated (newest entries kept), flagged by `truncated` + `truncatedAtTokens`.
+ */
+export interface WhatsChangedResponse {
+  status: "resolved" | "unknown";
+  package: string;
+  ecosystem: "npm" | "pypi" | "github" | null;
+  from: string;
+  to: string;
+  source: { sourceId: string; sourceSlug: string; orgSlug: string } | null;
+  entries: WhatsChangedEntry[];
+  count: number;
+  truncated: boolean;
+  truncatedAtTokens?: number;
+}
+
 export interface ReleaseDetail {
   id: string;
   sourceId: string;
@@ -741,6 +809,16 @@ export interface ReleaseDetail {
   titleGenerated?: string | null;
   /** AI-generated smart-brevity headline (#852, renamed in #860). Same fallback as `titleGenerated`. */
   titleShort?: string | null;
+  /**
+   * Machine-readable breaking-change level (#1696). `.optional()` for mid-deploy
+   * / pinned-worker tolerance; absent or `"unknown"` means not classified (the
+   * fail-open default). Populated live at ingest for developer-facing source
+   * kinds; history is `"unknown"` pending a backfill. Route population + the web
+   * chip are #1696 follow-ups.
+   */
+  breaking?: BreakingLevel;
+  /** Explicit upgrade/migration steps lifted from the body (#1696); null when the body gives none. */
+  migrationNotes?: string | null;
   url: string | null;
   media: MediaItem[];
   publishedAt: string | null;
@@ -751,8 +829,17 @@ export interface ReleaseDetail {
   /**
    * Owning org. `avatarUrl` is the resolved `organizations.avatar_url`
    * (nullable; `.optional()` for mid-deploy / pinned-worker tolerance).
+   * `discovery` and `isHidden` are additive — older servers omit them.
    */
-  org: { slug: string; name: string; avatarUrl?: string | null } | null;
+  org: {
+    slug: string;
+    name: string;
+    avatarUrl?: string | null;
+    /** How the org was created. Additive — older servers omit it. */
+    discovery?: "curated" | "agent" | "on_demand";
+    /** Whether the org is hidden from public listings. Additive — older servers omit it. */
+    isHidden?: boolean;
+  } | null;
   /**
    * Owning product, when the source is grouped under one (`sources.product_id`).
    * `null` when ungrouped; `.optional()` so older servers that omit it still type.
@@ -766,6 +853,11 @@ export interface ReleaseDetail {
   appStore?: { platform: "ios" | "macos"; iconUrl: string | null } | null;
   /** Video provider tag, present only when `sourceType === "video"`. */
   video?: { provider: "youtube" | "vimeo" | "wistia" } | null;
+  /**
+   * Whether the release's source is hidden from public listings. Additive —
+   * older servers omit it; treat `undefined` as `false`.
+   */
+  sourceIsHidden?: boolean;
 }
 
 export type ReleaseCoverageSibling = z.infer<typeof ReleaseCoverageSiblingSchema>;
@@ -788,9 +880,13 @@ export type ReleaseDetailResponse = z.infer<typeof ReleaseDetailResponseSchema>;
 export type UpdateReleaseBody = z.infer<typeof UpdateReleaseBodySchema>;
 export type ReleasePatchResponse = z.infer<typeof ReleasePatchResponseSchema>;
 export type ReleaseDeleteResponse = z.infer<typeof ReleaseDeleteResponseSchema>;
+export type ReleaseBatchDeleteBody = z.infer<typeof ReleaseBatchDeleteBodySchema>;
+export type ReleaseBatchDeleteResponse = z.infer<typeof ReleaseBatchDeleteResponseSchema>;
 export type ReleaseSuppressResponse = z.infer<typeof ReleaseSuppressResponseSchema>;
 export type ReleaseUnsuppressResponse = z.infer<typeof ReleaseUnsuppressResponseSchema>;
 export type ReleaseSuppressBody = z.infer<typeof ReleaseSuppressBodySchema>;
+export type ReleaseBatchSuppressBody = z.infer<typeof ReleaseBatchSuppressBodySchema>;
+export type ReleaseBatchSuppressResponse = z.infer<typeof ReleaseBatchSuppressResponseSchema>;
 export type ReleaseStreamMessage = z.infer<typeof ReleaseStreamMessageSchema>;
 
 export type ReleaseSummaryItem = z.infer<typeof ReleaseSummaryItemSchema>;
@@ -849,11 +945,117 @@ export interface FeedTokenResponse {
   token: FeedToken | null;
 }
 
+/** Cursor pagination shape for GET /v1/me/feed (same as other release feeds). */
+export type PersonalizedFeedPagination = OrgFeedPagination;
+
 /**
  * GET /v1/me/feed response — the personalized release feed. Reuses the same item
- * shape as /v1/releases/latest (ReleaseLatestItem) inside the standard list envelope.
+ * shape as /v1/releases/latest (ReleaseLatestItem); cursor-paginated like other
+ * feed-shaped surfaces.
  */
-export type PersonalizedFeedResponse = ListResponse<ReleaseLatestItem>;
+export interface PersonalizedFeedResponse {
+  items: ReleaseLatestItem[];
+  pagination: PersonalizedFeedPagination;
+}
+
+// ── User webhooks ──
+
+/** High-level delivery posture derived from summary columns (no AE query). */
+export type WebhookDeliveryHealth =
+  | "never_delivered"
+  | "healthy"
+  | "degraded"
+  | "failing"
+  | "paused"
+  | "auto_paused";
+
+/** Self-serve webhook filter scope. */
+export type UserWebhookScope = "org" | "follows";
+
+/** Optional per-event filter on release taxonomy type. */
+export type UserWebhookReleaseTypeFilter = "feature" | "rollup";
+
+/** Webhook delivery output format. */
+export type UserWebhookFormat = "json" | "slack";
+
+/** A user-owned webhook subscription row (no signing secret). */
+export interface UserWebhookSubscription {
+  id: string;
+  userId: string;
+  scope: UserWebhookScope;
+  orgId: string | null;
+  url: string;
+  sourceId: string | null;
+  productId: string | null;
+  releaseType: UserWebhookReleaseTypeFilter | null;
+  format: UserWebhookFormat;
+  enabled: boolean;
+  description: string | null;
+  secretVersion: number;
+  createdAt: string;
+  lastSuccessAt: string | null;
+  lastErrorAt: string | null;
+  lastErrorMsg: string | null;
+  consecutiveFailures: number;
+  disabledReason: string | null;
+  failureStreakStartedAt: string | null;
+}
+
+/** Delivery health fields returned on user webhook read paths. */
+export interface UserWebhookDeliveryHealth {
+  deliveryHealth: WebhookDeliveryHealth;
+  deliveryHealthSummary: string;
+}
+
+/** List item returned by GET /v1/me/webhooks — includes org/source display fields. */
+export interface UserWebhookListItem
+  extends Omit<UserWebhookSubscription, "userId">, UserWebhookDeliveryHealth {
+  orgSlug: string | null;
+  orgName: string | null;
+  sourceSlug: string | null;
+  sourceName: string | null;
+  productSlug: string | null;
+  productName: string | null;
+}
+
+/** GET /v1/me/webhooks response. */
+export interface UserWebhookListResponse {
+  subscriptions: UserWebhookListItem[];
+}
+
+/** POST /v1/me/webhooks response — signing key shown once at creation (omitted for slack format). */
+export interface CreateUserWebhookResponse
+  extends UserWebhookSubscription, UserWebhookDeliveryHealth {
+  orgSlug: string | null;
+  orgName: string | null;
+  signingKey?: string;
+}
+
+/** POST /v1/me/webhooks/:id/rotate-secret response. */
+export interface RotateUserWebhookSecretResponse {
+  secretVersion: number;
+  signingKey: string;
+}
+
+/** POST /v1/me/webhooks/:id/test response. */
+export interface TestUserWebhookResponse {
+  enqueued: true;
+  eventId: string;
+}
+
+/** One Analytics Engine delivery-attempt row from GET …/webhooks/:id/deliveries. */
+export interface WebhookDeliveryRow {
+  timestamp?: string;
+  event_id?: string;
+  error_message?: string | null;
+  error_code?: string | null;
+  outcome?: string;
+  /** Delivery format — "json" (signed raw event) or "slack" (Block Kit). Empty on pre-format rows. */
+  format?: UserWebhookFormat | "";
+  http_status?: number;
+  latency_ms?: number;
+  attempt?: number;
+}
 
 // ── Digest emails ──
 
@@ -1208,6 +1410,10 @@ export type ReplaceCollectionMembersResponse = z.infer<
   typeof ReplaceCollectionMembersResponseSchema
 >;
 export type AddCollectionMemberResponse = z.infer<typeof AddCollectionMemberResponseSchema>;
+export type CollectionDailySummary = z.infer<typeof CollectionDailySummarySchema>;
+export type CollectionDailySummariesResponse = z.infer<
+  typeof CollectionDailySummariesResponseSchema
+>;
 
 // ── Releases (enriched) ──
 
@@ -1242,6 +1448,25 @@ export interface LatestRelease {
   publishedAt: string | null;
   sourceName: string;
   sourceSlug: string;
+  /**
+   * Source type (`github`/`scrape`/`feed`/`agent`/`appstore`/`video`). Lets the
+   * live feed render the source-type icon for a freshly-arrived event. Additive —
+   * older buffered events / pinned workers omit it.
+   */
+  sourceType?: string;
+  /**
+   * Owning-org context, resolved at publish time so the live feed can render an
+   * avatar + org name the instant an event arrives. Nested to match
+   * {@link ReleaseDetail.org} and the build-event input. Additive/nullable:
+   * absent for orphan sources or older buffered events. Avatar fallback chain:
+   * `avatarUrl` → `github.com/<githubHandle>.png` → an initial.
+   */
+  org?: {
+    slug: string;
+    name: string;
+    avatarUrl: string | null;
+    githubHandle: string | null;
+  } | null;
   /** AI-generated summary (#852, renamed in #860). Nullable — most rows unpopulated. */
   summary: string | null;
   /** AI-generated headline (#852, renamed in #860). See {@link ReleaseDetail.titleGenerated}. */
@@ -1526,6 +1751,21 @@ export interface TokenIdentity {
   scopes: string[];
   principalType: "internal" | "agent" | "user";
   principalId?: string | null;
+  /**
+   * Stable internal principal id for consumption telemetry (#1719). Same value the
+   * auth middleware attaches (`relk_` row id, `relu_${keyId}`, …) — never the raw
+   * secret. Returned on self-introspection so MCP can distinguish `relu_` keys.
+   */
+  tokenId?: string | null;
+  /**
+   * Owning user id for a user-scoped principal (`relu_` key) — the Better Auth
+   * `apikey.referenceId`. Lets a consumer bucket all of an account's credentials
+   * together. Null for the static root key and machine (`relk_`) tokens, which
+   * have no owning user. Distinct from `principalId`, which carries an
+   * agent/internal id for machine tokens. Used by the MCP worker to bucket
+   * `relu_` keys per-account on the rate-limit account tier (#1729).
+   */
+  userId?: string | null;
   expiresAt?: string | null;
   lastUsedAt?: string | null;
 }

package/src/schemas/account-profile.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/** Response shared by user + workspace avatar upload routes. */
+export const UploadAvatarResponseSchema = z.object({
+  avatarUrl: z.string(),
+  key: z.string(),
+  width: z.number(),
+  height: z.number(),
+});
+
+export const WorkspaceProfileFieldsSchema = z.object({
+  websiteUrl: z.string().nullable(),
+  changelogUrl: z.string().nullable(),
+  githubHandle: z.string().nullable(),
+});
+
+/** Body for `PATCH /v1/workspaces/:workspaceId/profile`. */
+export const PatchWorkspaceProfileBodySchema = z.object({
+  websiteUrl: z.string().nullable().optional(),
+  changelogUrl: z.string().nullable().optional(),
+  githubHandle: z.string().nullable().optional(),
+});
+
+export const WorkspaceProfileResponseSchema = z.object({
+  workspaceId: z.string(),
+  logo: z.string().nullable(),
+  profile: WorkspaceProfileFieldsSchema,
+});

package/src/schemas/collections.ts

@@ -85,6 +85,8 @@ export const CollectionDetailSchema = z.object({
   description: z.string().nullable(),
   /** Whether the collection is promoted on the homepage. */
   isFeatured: z.boolean(),
+  /** Per-collection enable toggle for the nightly daily-summary generation. */
+  dailySummaryEnabled: z.boolean(),
   members: z.array(CollectionMemberSchema),
   /** @deprecated Use `members`. Org-only subset, kept for back-compat. */
   orgs: z.array(CollectionMemberOrgSchema),
@@ -141,6 +143,8 @@ export const CollectionRowSchema = z.object({
   name: z.string(),
   description: z.string().nullable(),
   isFeatured: z.boolean(),
+  /** Per-collection enable toggle for the nightly daily-summary generation. */
+  dailySummaryEnabled: z.boolean(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -163,6 +167,8 @@ export const UpdateCollectionRequestSchema = z.object({
   description: z.string().max(2000).nullable().optional(),
   /** Promote / demote the collection on the homepage. */
   isFeatured: z.boolean().optional(),
+  /** Enable or disable the nightly daily-summary generation for this collection. */
+  dailySummaryEnabled: z.boolean().optional(),
 });
 
 /**
@@ -228,3 +234,18 @@ export const AddCollectionMemberResponseSchema = z.object({
   productId: z.string().optional(),
   position: z.number().int(),
 });
+
+/** One daily summary row returned by `GET /v1/collections/:slug/daily-summaries`. */
+export const CollectionDailySummarySchema = z.object({
+  /** Eastern calendar day, YYYY-MM-DD. */
+  date: z.string(),
+  title: z.string(),
+  summary: z.string(),
+  takeaways: z.array(z.string()),
+  releaseCount: z.number().int().nonnegative(),
+});
+
+/** Response envelope for `GET /v1/collections/:slug/daily-summaries`. */
+export const CollectionDailySummariesResponseSchema = z.object({
+  summaries: z.array(CollectionDailySummarySchema),
+});

package/src/schemas/releases.ts

@@ -29,6 +29,13 @@ export const ReleaseLatestSourceSchema = z.object({
   /** Owning org's display name (e.g. "Cloudflare"), distinct from the source
    *  name. Null when the source has no org. Additive — older responses omit it. */
   orgName: z.string().nullable().optional(),
+  /** Owning org's explicit avatar URL (`organizations.avatar_url`), when set.
+   *  Null/absent when the org has no stored avatar — clients fall back to the
+   *  GitHub handle below, then an initial. Additive — older responses omit it. */
+  orgAvatarUrl: z.string().nullable().optional(),
+  /** Owning org's GitHub handle, used to derive `github.com/<handle>.png` as the
+   *  avatar fallback when `orgAvatarUrl` is unset. Additive — older responses omit it. */
+  orgGithubHandle: z.string().nullable().optional(),
 });
 
 export const ReleaseLatestProductSchema = z.object({
@@ -178,6 +185,17 @@ export const ReleaseDetailOrgSchema = z.object({
    * related-rail feed.
    */
   avatarUrl: z.string().nullable().optional(),
+  /**
+   * How the org was created. Additive — older servers omit it; treat
+   * `undefined` as `"curated"`. Used by the web to emit `noindex` on
+   * on-demand-materialized org pages.
+   */
+  discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
+  /**
+   * Whether the org is hidden from public listings. Additive — older servers
+   * omit it; treat `undefined` as `false`. Used by the web to emit `noindex`.
+   */
+  isHidden: z.boolean().optional(),
 });
 
 /**
@@ -219,6 +237,12 @@ export const ReleaseDetailResponseSchema = z.object({
   composition: ReleaseCompositionSchema.nullable(),
   appStore: AppStoreSourceInfoSchema.nullable().optional(),
   video: VideoSourceInfoSchema.nullable().optional(),
+  /**
+   * Whether the release's source is hidden from public listings. Additive —
+   * older servers omit it; treat `undefined` as `false`. Used by the web to
+   * emit `noindex` on pages whose source is an on-demand-materialized stub.
+   */
+  sourceIsHidden: z.boolean().optional(),
 });
 
 /**
@@ -287,6 +311,32 @@ export const ReleaseDeleteResponseSchema = z.object({
   deleted: z.literal(true),
 });
 
+/** Body accepted by `DELETE /v1/releases/batch`. */
+export const ReleaseBatchDeleteBodySchema = z.object({
+  releaseIds: z.array(z.string()).min(1),
+});
+
+/** Response returned by `DELETE /v1/releases/batch`. */
+export const ReleaseBatchDeleteResponseSchema = z.object({
+  deleted: z.number().int().min(0),
+});
+
+/**
+ * Body accepted by `POST /v1/releases/batch-suppress`. When `suppressed` is
+ * true the optional `reason` is stored in `suppressed_reason`; when false the
+ * reason is cleared.
+ */
+export const ReleaseBatchSuppressBodySchema = z.object({
+  releaseIds: z.array(z.string()).min(1),
+  suppressed: z.boolean(),
+  reason: z.string().optional(),
+});
+
+/** Response returned by `POST /v1/releases/batch-suppress`. */
+export const ReleaseBatchSuppressResponseSchema = z.object({
+  updated: z.number().int().min(0),
+});
+
 /** Response returned by `POST /v1/releases/:id/suppress`. */
 export const ReleaseSuppressResponseSchema = z.object({
   suppressed: z.literal(true),

package/src/schemas/search.ts

@@ -8,6 +8,7 @@ import {
 } from "./shared.js";
 import { SourceTypeSchema } from "./sources.js";
 import { LookupStatusSchema } from "./lookups.js";
+import { CollectionMemberSchema } from "./collections.js";
 
 /**
  * Org hit on the unified `/v1/search` response. The list is built either
@@ -130,6 +131,14 @@ export const SearchCollectionHitSchema = z.object({
   score: z.number().optional(),
   /** Result-set org slugs that triggered this rollup. Always present on `via=member`. */
   matchedOrgSlugs: z.array(z.string()).optional(),
+  /**
+   * A small org preview (capped at 3) for an inline avatar facepile on the
+   * search card, mirroring the collections list page. Org-kind only — search's
+   * `memberCount` counts orgs, so the facepile and its "+N more" stay
+   * consistent. Attached after hit merge; optional on the wire so older workers
+   * mid-rollout don't trip the schema.
+   */
+  previewMembers: z.array(CollectionMemberSchema).optional(),
 });
 
 /**

package/src/schemas/site-notice.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "bun:test";
+import { SiteNoticeSchema, SiteNoticeResponseSchema } from "./site-notice";
+
+const valid = {
+  active: true,
+  message: "We shipped a new feed",
+  linkText: "See it",
+  href: "https://releases.sh/updates",
+  placement: "banner" as const,
+  color: "#0081e7",
+  dismissible: false,
+};
+
+describe("SiteNoticeSchema", () => {
+  it("accepts a fully-specified notice", () => {
+    expect(SiteNoticeSchema.safeParse(valid).success).toBe(true);
+  });
+  it("accepts a site-relative href and omitted link", () => {
+    const { href, linkText, ...rest } = valid;
+    expect(SiteNoticeSchema.safeParse({ ...rest, href: "/updates" }).success).toBe(true);
+    expect(SiteNoticeSchema.safeParse(rest).success).toBe(true);
+  });
+  it("rejects an over-length message", () => {
+    expect(SiteNoticeSchema.safeParse({ ...valid, message: "x".repeat(281) }).success).toBe(false);
+  });
+  it("rejects an empty message", () => {
+    expect(SiteNoticeSchema.safeParse({ ...valid, message: "" }).success).toBe(false);
+  });
+  it("rejects a bad placement", () => {
+    expect(SiteNoticeSchema.safeParse({ ...valid, placement: "footer" }).success).toBe(false);
+  });
+  it("rejects a non-hex color", () => {
+    expect(SiteNoticeSchema.safeParse({ ...valid, color: "blue" }).success).toBe(false);
+    expect(SiteNoticeSchema.safeParse({ ...valid, color: "#fff" }).success).toBe(false);
+  });
+  it("rejects an href that is neither absolute http(s) nor root-relative", () => {
+    expect(SiteNoticeSchema.safeParse({ ...valid, href: "ftp://x.y" }).success).toBe(false);
+    expect(SiteNoticeSchema.safeParse({ ...valid, href: "updates" }).success).toBe(false);
+  });
+  it("rejects linkText without an href (dead CTA)", () => {
+    const { href, ...noHref } = valid; // keeps linkText
+    expect(SiteNoticeSchema.safeParse(noHref).success).toBe(false);
+  });
+  it("accepts href without linkText", () => {
+    const { linkText, ...noLinkText } = valid;
+    expect(SiteNoticeSchema.safeParse(noLinkText).success).toBe(true);
+  });
+  it("rejects javascript:/data: schemes and protocol-relative hrefs", () => {
+    expect(SiteNoticeSchema.safeParse({ ...valid, href: "javascript:alert(1)" }).success).toBe(
+      false,
+    );
+    expect(SiteNoticeSchema.safeParse({ ...valid, href: "data:text/html,x" }).success).toBe(false);
+    expect(SiteNoticeSchema.safeParse({ ...valid, href: "//evil.com" }).success).toBe(false);
+  });
+});
+
+describe("SiteNoticeResponseSchema", () => {
+  it("accepts null", () => {
+    expect(SiteNoticeResponseSchema.safeParse({ notice: null }).success).toBe(true);
+  });
+  it("accepts a stored notice with updatedAt", () => {
+    const r = SiteNoticeResponseSchema.safeParse({
+      notice: { ...valid, updatedAt: "2026-06-11T00:00:00.000Z" },
+    });
+    expect(r.success).toBe(true);
+  });
+});

package/src/schemas/site-notice.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { SITE_NOTICE_PLACEMENTS } from "@buildinternet/releases-core/site-notice";
+
+/**
+ * Absolute http(s) URL or a site-relative path beginning with a single "/".
+ * Rejects other schemes (javascript:, data:, …) and protocol-relative "//host"
+ * so a stored href can never become an unexpected-scheme or off-site link.
+ */
+const HrefSchema = z
+  .string()
+  .max(500)
+  .refine((h) => /^https?:\/\//.test(h) || (h.startsWith("/") && !h.startsWith("//")), {
+    message: "href must be an absolute http(s) URL or a site-relative path",
+  });
+
+/**
+ * Editable site-notice fields. Kept structurally in sync with the
+ * `SiteNotice` interface in `@buildinternet/releases-core/site-notice`. Split
+ * from the refined `SiteNoticeSchema` below so the response schema can `.extend()`
+ * it (a `.refine()` returns a non-extendable effect).
+ */
+const SiteNoticeFieldsSchema = z.object({
+  active: z.boolean(),
+  message: z.string().min(1).max(280),
+  linkText: z.string().min(1).max(60).optional(),
+  href: HrefSchema.optional(),
+  placement: z.enum(SITE_NOTICE_PLACEMENTS),
+  color: z.string().regex(/^#[0-9a-fA-F]{6}$/, "color must be a 6-digit hex like #0081e7"),
+  dismissible: z.boolean(),
+});
+
+/**
+ * Editable site-notice payload. A bare `linkText` with no `href` renders nothing
+ * (the view only draws a link when there's a target), so require `href` whenever
+ * `linkText` is set.
+ */
+export const SiteNoticeSchema = SiteNoticeFieldsSchema.refine((n) => !(n.linkText && !n.href), {
+  message: "href is required when linkText is set",
+  path: ["href"],
+});
+
+/** GET /v1/site-notice response: the stored notice (+updatedAt) or null. */
+export const SiteNoticeResponseSchema = z.object({
+  notice: SiteNoticeFieldsSchema.extend({ updatedAt: z.iso.datetime() }).nullable(),
+});

package/src/schemas/taxonomy.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { CategorySchema } from "./shared.js";
-import { CollectionReleaseItemSchema } from "./collections.js";
+import { CollectionMemberSchema, CollectionReleaseItemSchema } from "./collections.js";
 
 /**
  * Org rollup row shared by category and tag detail responses. Slim by
@@ -38,6 +38,16 @@ export const CategoryListItemSchema = z.object({
   aliases: z.array(z.string()),
   orgCount: z.number().int().min(0),
   productCount: z.number().int().min(0),
+  /**
+   * A small mixed-kind preview (capped at 3) of the orgs and products in this
+   * category, so the list page can render an inline avatar facepile without a
+   * second round trip — same shape and intent as a collection's
+   * `previewMembers`. Org entries are surfaced first (they carry the avatar);
+   * product entries fill any remaining slots and dedupe against orgs already
+   * shown. The list page derives "+N more" from `orgCount + productCount`.
+   * Optional on the wire so older workers mid-rollout don't trip the schema.
+   */
+  previewMembers: z.array(CollectionMemberSchema).optional(),
 });
 
 export const CategoryListResponseSchema = z.array(CategoryListItemSchema);