@buildinternet/releases-api-types 0.22.0 → 0.24.0

package/package.json

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

@@ -10,6 +10,8 @@ export type {
   SourceDiscovery,
   SourceFetchPriority,
 } from "@buildinternet/releases-core/source-enums";
+// 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 {
   MediaItemSchema,
   PaginationSchema,
@@ -62,6 +64,7 @@ import type {
   SourceDetailSchema,
   SourceFeedPaginationSchema,
   SourceMutationResponseSchema,
+  AppStoreMaterializeResponseSchema,
   SourceOrgRefSchema,
   SourcePatchInputSchema,
   CreateSourceBodySchema,
@@ -95,6 +98,7 @@ import type {
 } from "./schemas/sources.js";
 import type {
   ProductRowSchema,
+  ProductCreateResponseSchema,
   ProductListItemSchema,
   ProductListResponseSchema,
   ProductDetailSourceSchema,
@@ -109,11 +113,15 @@ import type {
   ProductTagsListResponseSchema,
   ProductTagsBodySchema,
   ProductTagsMutationResponseSchema,
+  ProductActivityResponseSchema,
+  ProductHeatmapResponseSchema,
 } from "./schemas/products.js";
 import type {
   ReleaseLatestSourceSchema,
+  ReleaseLatestProductSchema,
   ReleaseLatestItemSchema,
   ReleaseLatestResponseSchema,
+  ReleaseCoverageSiblingSchema,
   ReleaseCoverageRowSchema,
   ReleaseCoverageResponseSchema,
   LinkReleaseCoverageBodySchema,
@@ -171,6 +179,14 @@ import type {
   StatsRecentActivitySchema,
   StatsResponseSchema,
 } from "./schemas/stats.js";
+import type {
+  FeedbackTypeSchema,
+  FeedbackStatusSchema,
+  FeedbackItemSchema,
+  FeedbackListResponseSchema,
+  FeedbackUpdateBodySchema,
+  FeedbackDeleteResponseSchema,
+} from "./schemas/feedback.js";
 import type { SitemapSourceSchema, SitemapPayloadSchema } from "./schemas/sitemap.js";
 import type {
   RelatedScopeSchema,
@@ -187,6 +203,9 @@ import type {
 } from "./schemas/related.js";
 import type {
   CollectionMemberOrgSchema,
+  ProductParentOrgSchema,
+  CollectionMemberProductSchema,
+  CollectionMemberSchema,
   CollectionListItemSchema,
   CollectionListResponseSchema,
   CollectionDetailSchema,
@@ -271,6 +290,7 @@ export {
   SourceDetailSchema,
   SourceFeedPaginationSchema,
   SourceMutationResponseSchema,
+  AppStoreMaterializeResponseSchema,
   SourceOrgRefSchema,
   SourcePatchInputSchema,
   CreateSourceBodySchema,
@@ -304,6 +324,7 @@ export {
 } from "./schemas/sources.js";
 export {
   ProductRowSchema,
+  ProductCreateResponseSchema,
   ProductListItemSchema,
   ProductListResponseSchema,
   ProductDetailSourceSchema,
@@ -318,6 +339,8 @@ export {
   ProductTagsListResponseSchema,
   ProductTagsBodySchema,
   ProductTagsMutationResponseSchema,
+  ProductActivityResponseSchema,
+  ProductHeatmapResponseSchema,
 } from "./schemas/products.js";
 export {
   LookupStatusSchema,
@@ -347,8 +370,10 @@ export {
 } from "./schemas/taxonomy.js";
 export {
   ReleaseLatestSourceSchema,
+  ReleaseLatestProductSchema,
   ReleaseLatestItemSchema,
   ReleaseLatestResponseSchema,
+  ReleaseCoverageSiblingSchema,
   ReleaseCoverageRowSchema,
   ReleaseCoverageResponseSchema,
   LinkReleaseCoverageBodySchema,
@@ -381,6 +406,14 @@ export {
   StatsRecentActivitySchema,
   StatsResponseSchema,
 } from "./schemas/stats.js";
+export {
+  FeedbackTypeSchema,
+  FeedbackStatusSchema,
+  FeedbackItemSchema,
+  FeedbackListResponseSchema,
+  FeedbackUpdateBodySchema,
+  FeedbackDeleteResponseSchema,
+} from "./schemas/feedback.js";
 export { SitemapSourceSchema, SitemapPayloadSchema } from "./schemas/sitemap.js";
 export {
   RelatedScopeSchema,
@@ -397,6 +430,9 @@ export {
 } from "./schemas/related.js";
 export {
   CollectionMemberOrgSchema,
+  ProductParentOrgSchema,
+  CollectionMemberProductSchema,
+  CollectionMemberSchema,
   CollectionListItemSchema,
   CollectionListResponseSchema,
   CollectionDetailSchema,
@@ -426,6 +462,8 @@ export {
   UpdatePlaybookNotesBodySchema,
   UpdatePlaybookNotesResponseSchema,
 } from "./schemas/overviews.js";
+export { ResolveResponseSchema } from "./schemas/resolve.js";
+export type { ResolveResponse } from "./schemas/resolve.js";
 
 // ── Media ──
 
@@ -512,6 +550,7 @@ export type SourceChangelogResponse = z.infer<typeof SourceChangelogResponseSche
 export type SourceDetail = z.infer<typeof SourceDetailSchema>;
 export type SourceFeedPagination = z.infer<typeof SourceFeedPaginationSchema>;
 export type SourceMutationResponse = z.infer<typeof SourceMutationResponseSchema>;
+export type AppStoreMaterializeResponse = z.infer<typeof AppStoreMaterializeResponseSchema>;
 export type SourceOrgRef = z.infer<typeof SourceOrgRefSchema>;
 export type SourceActivityResponse = z.infer<typeof SourceActivityResponseSchema>;
 export type SourceHeatmapResponse = z.infer<typeof SourceHeatmapResponseSchema>;
@@ -566,6 +605,61 @@ export interface OrgsRollupResponse extends ListResponse<OrgsRollupRow> {
   };
 }
 
+// ── Admin telemetry: stuck sources ──
+
+/**
+ * A source whose recent fetch history is all errors with no reachability — a
+ * candidate for pausing. "Stuck" means: within the last `window` non-`dry_run`
+ * fetch attempts, every one was an `error` (zero `success`/`no_change`) and
+ * there were at least `minAttempts` of them.
+ *
+ * This keys off the `fetch_log` error streak rather than
+ * `sources.consecutive_errors`, because the scrape/agent fetch path never bumps
+ * that column (a source can fail for days with `consecutive_errors = 0`).
+ */
+export interface StuckSource {
+  sourceId: string;
+  sourceSlug: string;
+  name: string;
+  type: SourceType;
+  url: string;
+  kind: string | null;
+  orgSlug: string | null;
+  orgName: string | null;
+  /** Current fetch tier — `paused` rows only appear when `includePaused`. */
+  fetchPriority: SourceFetchPriority;
+  /** True when this is the org's primary changelog (Firebase's was). */
+  isPrimary: boolean;
+  isHidden: boolean;
+  /** Non-`dry_run` attempts examined in the window (all errors when stuck). */
+  recentAttempts: number;
+  /** Errors among the examined attempts (equals `recentAttempts` when stuck). */
+  recentErrors: number;
+  /** Most-recent fetch attempt timestamp (ISO), or null. */
+  lastAttemptAt: string | null;
+  /** Most-recent error message. */
+  lastError: string | null;
+  /** Most-recent error category, when the fetcher classified it. */
+  lastErrorCategory: string | null;
+  /** Last time the source was reachable (`success`/`no_change`), ISO; null = never. */
+  lastSuccessAt: string | null;
+  /** `sources.last_fetched_at` — null when the source has never fetched. */
+  lastFetchedAt: string | null;
+  /** When the source row was created (ISO) — proxy for how long it's failed. */
+  sourceCreatedAt: string | null;
+}
+
+export interface StuckSourcesResponse extends ListResponse<StuckSource> {
+  meta: {
+    /** Recent non-`dry_run` attempts examined per source. */
+    window: number;
+    /** Minimum attempts in the window required to flag a source. */
+    minAttempts: number;
+    /** Whether already-paused sources were included. */
+    includePaused: boolean;
+  };
+}
+
 // ── Releases ──
 
 /**
@@ -607,8 +701,11 @@ export interface ReleaseDetail {
   type?: ReleaseType;
   /** Per-category item counts from the AI release-content pass. See {@link ReleaseComposition}. */
   composition?: ReleaseComposition | null;
+  /** App Store platform + icon, present only when `sourceType === "appstore"`. */
+  appStore?: { platform: "ios" | "macos"; iconUrl: string | null } | null;
 }
 
+export type ReleaseCoverageSibling = z.infer<typeof ReleaseCoverageSiblingSchema>;
 export type ReleaseCoverageRow = z.infer<typeof ReleaseCoverageRowSchema>;
 export type ReleaseCoverageResponse = z.infer<typeof ReleaseCoverageResponseSchema>;
 export type LinkReleaseCoverageBody = z.infer<typeof LinkReleaseCoverageBodySchema>;
@@ -616,6 +713,7 @@ export type LinkReleaseCoverageResponse = z.infer<typeof LinkReleaseCoverageResp
 export type UnlinkReleaseCoverageResponse = z.infer<typeof UnlinkReleaseCoverageResponseSchema>;
 
 export type ReleaseLatestSource = z.infer<typeof ReleaseLatestSourceSchema>;
+export type ReleaseLatestProduct = z.infer<typeof ReleaseLatestProductSchema>;
 export type ReleaseLatestItem = z.infer<typeof ReleaseLatestItemSchema>;
 export type ReleaseLatestResponse = z.infer<typeof ReleaseLatestResponseSchema>;
 
@@ -861,7 +959,7 @@ export type SourceActivity = SourceActivityResponse;
 
 // ── Org Activity (Zod-derived aliases) ──
 // The old hand-written OrgActivitySource / OrgActivity / OrgSparklines /
-// OrgHeatmap / OrgReleaseItem / OrgReleasesResponse interfaces have been
+// OrgHeatmap / OrgReleaseItem interfaces have been
 // replaced by Zod-derived types in the Organizations section above. Keeping
 // the interface names as deprecated aliases so callsites don't need an
 // immediate churn.
@@ -875,9 +973,6 @@ export type OrgSparklines = OrgSparklinesResponse;
 /** @deprecated Use OrgHeatmapResponse */
 export type OrgHeatmap = OrgHeatmapResponse;
 
-/** @deprecated Use OrgReleasesFeedResponse */
-export type OrgReleasesResponse = OrgReleasesFeedResponse;
-
 // ── Org Sparklines (per-source/product breakdown) ──
 // (covered above)
 
@@ -905,6 +1000,7 @@ export interface SourceReleasesResponse {
 // `Category` lives in @buildinternet/releases-core/categories — import it from
 // there. CategorySchema is re-exported here for OpenAPI / Zod consumers only.
 export type ProductRow = z.infer<typeof ProductRowSchema>;
+export type ProductCreateResponse = z.infer<typeof ProductCreateResponseSchema>;
 export type ProductListItem = z.infer<typeof ProductListItemSchema>;
 export type ProductListResponse = z.infer<typeof ProductListResponseSchema>;
 export type ProductDetailSource = z.infer<typeof ProductDetailSourceSchema>;
@@ -919,6 +1015,8 @@ export type ProductDeleteResponse = z.infer<typeof ProductDeleteResponseSchema>;
 export type ProductTagsListResponse = z.infer<typeof ProductTagsListResponseSchema>;
 export type ProductTagsBody = z.infer<typeof ProductTagsBodySchema>;
 export type ProductTagsMutationResponse = z.infer<typeof ProductTagsMutationResponseSchema>;
+export type ProductActivityResponse = z.infer<typeof ProductActivityResponseSchema>;
+export type ProductHeatmapResponse = z.infer<typeof ProductHeatmapResponseSchema>;
 
 // ── Taxonomy (categories + tags) ──
 
@@ -947,6 +1045,9 @@ export type CategoryReleaseItem = CollectionReleaseItem;
 // /collections/frontier-ai-labs). Independent of the fixed `category` taxonomy.
 
 export type CollectionMemberOrg = z.infer<typeof CollectionMemberOrgSchema>;
+export type ProductParentOrg = z.infer<typeof ProductParentOrgSchema>;
+export type CollectionMemberProduct = z.infer<typeof CollectionMemberProductSchema>;
+export type CollectionMember = z.infer<typeof CollectionMemberSchema>;
 export type CollectionListItem = z.infer<typeof CollectionListItemSchema>;
 export type CollectionListResponse = z.infer<typeof CollectionListResponseSchema>;
 export type CollectionDetail = z.infer<typeof CollectionDetailSchema>;
@@ -1014,6 +1115,12 @@ export interface LatestRelease {
    */
   contentChars?: number | null;
   contentTokens?: number | null;
+  /**
+   * Owning product, when the release's source is grouped under a product.
+   * `null` / `undefined` when the source has no `product_id`. Additive — older
+   * API responses omit this field; treat `undefined` as `null`. #1217.
+   */
+  product?: { slug: string; name: string } | null;
 }
 
 // ── Stats ──
@@ -1034,6 +1141,14 @@ export type StatsResponse = z.infer<typeof StatsResponseSchema>;
  */
 export type StatsSummary = Omit<StatsResponse, "orgs" | "sources" | "releases" | "products">;
 
+// ── Feedback ──
+export type FeedbackType = z.infer<typeof FeedbackTypeSchema>;
+export type FeedbackStatus = z.infer<typeof FeedbackStatusSchema>;
+export type FeedbackItem = z.infer<typeof FeedbackItemSchema>;
+export type FeedbackListResponse = z.infer<typeof FeedbackListResponseSchema>;
+export type FeedbackUpdateBody = z.infer<typeof FeedbackUpdateBodySchema>;
+export type FeedbackDeleteResponse = z.infer<typeof FeedbackDeleteResponseSchema>;
+
 // ── Fetch log ──
 
 export interface FetchLogEntry {
@@ -1236,3 +1351,20 @@ export interface EvaluationResult {
   provider?: string;
   notes?: string;
 }
+
+/**
+ * Identity returned by `GET /v1/tokens/me` — the caller introspecting its own
+ * credential. `kind: "root"` is the static break-glass key (synthetic identity,
+ * no DB row); `kind: "token"` is a DB-backed `relk_` token.
+ */
+export interface TokenIdentity {
+  kind: "root" | "token";
+  /** Display label; "root" for the static key, "local-dev" when no secret is bound. */
+  name: string;
+  /** e.g. ["read","write"] or ["*"] for root. */
+  scopes: string[];
+  principalType: "internal" | "agent" | "user";
+  principalId?: string | null;
+  expiresAt?: string | null;
+  lastUsedAt?: string | null;
+}

package/src/schemas/collections.ts

@@ -17,30 +17,81 @@ export const CollectionMemberOrgSchema = z.object({
 });
 
 /**
- * Row on `GET /v1/collections`. `previewMembers` is the first few visible
- * members (capped at 3) so the list page can render inline avatars without a
- * second round trip.
+ * Org context attached to a product member so the chip can render the parent
+ * org's avatar / handle. Subset of `CollectionMemberOrg` — description is
+ * intentionally omitted because the byline comes from the product itself.
+ */
+export const ProductParentOrgSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
+  githubHandle: z.string().nullable(),
+});
+
+/**
+ * One product as it appears inside a collection. Carries the parent org block
+ * so the chip can render the org's avatar (products don't have their own).
+ */
+export const CollectionMemberProductSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  org: ProductParentOrgSchema,
+});
+
+/**
+ * Mixed-kind member entry. `kind` discriminates: `org` carries the org block at
+ * the top level; `product` carries the product fields plus a `org` parent block.
+ * Used by `GET /v1/collections/:slug` (`members` field) and the new
+ * `previewMembers` on `GET /v1/collections`.
+ */
+export const CollectionMemberSchema = z.discriminatedUnion("kind", [
+  CollectionMemberOrgSchema.extend({ kind: z.literal("org") }),
+  CollectionMemberProductSchema.extend({ kind: z.literal("product") }),
+]);
+
+/**
+ * Row on `GET /v1/collections`. `previewMembers` (the new mixed-kind preview)
+ * is the first few visible members so the list page can render inline avatars
+ * without a second round trip. `previewOrgs` is the legacy org-only preview,
+ * retained for back-compat — clients should migrate to `previewMembers`.
  */
 export const CollectionListItemSchema = z.object({
   slug: z.string(),
   name: z.string(),
   description: z.string().nullable(),
   memberCount: z.number().int().min(0),
-  previewMembers: z.array(CollectionMemberOrgSchema).optional(),
+  /** Whether the collection is promoted on the homepage. Filterable via `?featured=1`. */
+  isFeatured: z.boolean(),
+  /** Mixed-kind preview (org + product). Cap matches `previewOrgs`. */
+  previewMembers: z.array(CollectionMemberSchema).optional(),
+  /** Legacy org-only preview. Populated with the org-kind subset of `previewMembers`. */
+  previewOrgs: z.array(CollectionMemberOrgSchema).optional(),
 });
 
 export const CollectionListResponseSchema = z.array(CollectionListItemSchema);
 
-/** Returned by `GET /v1/collections/:slug`. */
+/**
+ * Returned by `GET /v1/collections/:slug`.
+ *
+ * `members` is the mixed-kind canonical list. `orgs` is the legacy org-only
+ * field, populated with the org-kind subset of `members` for back-compat —
+ * new clients should consume `members`.
+ */
 export const CollectionDetailSchema = z.object({
   slug: z.string(),
   name: z.string(),
   description: z.string().nullable(),
+  /** Whether the collection is promoted on the homepage. */
+  isFeatured: z.boolean(),
+  members: z.array(CollectionMemberSchema),
+  /** @deprecated Use `members`. Org-only subset, kept for back-compat. */
   orgs: z.array(CollectionMemberOrgSchema),
 });
 
 /**
- * Cross-org release feed row on `GET /v1/collections/:slug/releases`. Same
+ * Cross-member release feed row on `GET /v1/collections/:slug/releases`. Same
  * shape as `OrgReleaseItem` plus the origin `org` block (and optional
  * `product`) so the web's release card can render it identically. `source.type`
  * stays as `z.string()` because the SQL passes the column through unvalidated —
@@ -56,6 +107,16 @@ export const CollectionReleaseItemSchema = ReleaseItemSchema.extend({
    * typecheck — clients should treat missing and `null` identically.
    */
   product: z.object({ slug: z.string(), name: z.string() }).nullable().optional(),
+  /**
+   * Server-resolved grouping identity — `COALESCE(product.slug, source.slug)` /
+   * `COALESCE(product.name, source.name)`. The web release feeds key and label
+   * SDK/package-cluster rollups on these instead of reconstructing
+   * `product ?? source` client-side. Optional on the wire: older workers omit
+   * them, so clients must fall back to deriving from `product ?? source`. Never
+   * null when present (`source` is always set). #1234
+   */
+  groupSlug: z.string().optional(),
+  groupName: z.string().optional(),
 });
 
 /** Cursor pagination shape matches `/v1/orgs/:slug/releases`. */
@@ -79,6 +140,7 @@ export const CollectionRowSchema = z.object({
   slug: z.string(),
   name: z.string(),
   description: z.string().nullable(),
+  isFeatured: z.boolean(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -99,15 +161,26 @@ export const UpdateCollectionRequestSchema = z.object({
   slug: z.string().optional(),
   name: z.string().min(1).max(200).optional(),
   description: z.string().max(2000).nullable().optional(),
+  /** Promote / demote the collection on the homepage. */
+  isFeatured: z.boolean().optional(),
 });
 
 /**
- * One member entry accepted by the member-write endpoints. Either `orgId`
- * (`org_…`) or `orgSlug` is required; when both are given, `orgId` wins.
+ * One member entry accepted by the member-write endpoints.
+ *
+ * Exactly one of `orgId` / `orgSlug` / `productId` / `productSlug` must be
+ * present. When both an id and a slug are supplied for the same kind, the id
+ * wins. Mixing kinds (e.g. `orgId` + `productSlug`) is rejected by the handler.
+ *
+ * Product slug is resolved within an org — supply either `productId`
+ * (`prod_…`, globally unique) or pair `productSlug` with `orgSlug`/`orgId`.
+ * `productSlug` alone is rejected.
  */
 export const CollectionMemberInputSchema = z.object({
   orgId: z.string().optional(),
   orgSlug: z.string().optional(),
+  productId: z.string().optional(),
+  productSlug: z.string().optional(),
   /** Authoring position (default 0). For PUT, omit to use the array index. */
   position: z.number().int().optional(),
 });
@@ -115,14 +188,25 @@ export const CollectionMemberInputSchema = z.object({
 /** Body for `POST /v1/collections/:slug/members`. */
 export const AddCollectionMemberRequestSchema = CollectionMemberInputSchema;
 
-/** Body for `PUT /v1/collections/:slug/members`. Replaces the full membership atomically. */
+/**
+ * Body for `PUT /v1/collections/:slug/members`. Replaces the full membership
+ * atomically. The field is still named `orgs` for back-compat — it accepts
+ * any `CollectionMemberInput`, org or product.
+ */
 export const ReplaceCollectionMembersRequestSchema = z.object({
   orgs: z.array(CollectionMemberInputSchema),
 });
 
-/** Resolved member returned by `PUT /v1/collections/:slug/members`. */
+/**
+ * Resolved member returned by `PUT /v1/collections/:slug/members` and `POST
+ * /v1/collections/:slug/members`. `kind` discriminates which id field is
+ * populated. `orgId` is also set on legacy callers that only used org
+ * membership — for clean dispatch, dispatch on `kind`.
+ */
 export const ResolvedCollectionMemberSchema = z.object({
-  orgId: z.string(),
+  kind: z.enum(["org", "product"]),
+  orgId: z.string().optional(),
+  productId: z.string().optional(),
   position: z.number().int(),
 });
 
@@ -132,9 +216,15 @@ export const ReplaceCollectionMembersResponseSchema = z.object({
   members: z.array(ResolvedCollectionMemberSchema),
 });
 
-/** Response from `POST /v1/collections/:slug/members`. */
+/**
+ * Response from `POST /v1/collections/:slug/members`. `orgId` stays populated
+ * for org-kind members so existing CLI callers don't break; `kind` +
+ * `productId` are the canonical fields for new code.
+ */
 export const AddCollectionMemberResponseSchema = z.object({
   collectionSlug: z.string(),
-  orgId: z.string(),
+  kind: z.enum(["org", "product"]),
+  orgId: z.string().optional(),
+  productId: z.string().optional(),
   position: z.number().int(),
 });

package/src/schemas/feedback.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { FEEDBACK_TYPES, FEEDBACK_STATUSES } from "@buildinternet/releases-core/schema";
+
+/** Feedback category — mirrors `FEEDBACK_TYPES` in `@buildinternet/releases-core/schema`. */
+export const FeedbackTypeSchema = z.enum(FEEDBACK_TYPES);
+
+/** Triage lifecycle — mirrors `FEEDBACK_STATUSES` in `@buildinternet/releases-core/schema`. */
+export const FeedbackStatusSchema = z.enum(FEEDBACK_STATUSES);
+
+/**
+ * One submitted feedback row, as returned by `GET /v1/admin/feedback` and by
+ * the triage write-path (`PATCH /v1/feedback/:id` echoes the updated row).
+ * `archived` soft-removes the row from the default admin read view and is
+ * orthogonal to triage `status` — a row can be `closed` and visible, or `new`
+ * and archived. `createdAt` is epoch milliseconds.
+ */
+export const FeedbackItemSchema = z.object({
+  id: z.string(),
+  createdAt: z.number(),
+  message: z.string(),
+  contact: z.string().nullable(),
+  type: FeedbackTypeSchema,
+  status: FeedbackStatusSchema,
+  archived: z.boolean(),
+  cliVersion: z.string().nullable(),
+  clientKind: z.string(),
+  anonId: z.string().nullable(),
+  os: z.string().nullable(),
+  arch: z.string().nullable(),
+  runtime: z.string().nullable(),
+  surface: z.string(),
+});
+
+/**
+ * `GET /v1/admin/feedback` — cursor-paginated, newest-first. Archived rows are
+ * hidden unless the request passes `?includeArchived=true`.
+ */
+export const FeedbackListResponseSchema = z.object({
+  items: z.array(FeedbackItemSchema),
+  nextCursor: z.string().nullable(),
+});
+
+/**
+ * `PATCH /v1/feedback/:id` body — partial triage update. At least one field
+ * must be present; the response echoes the updated `FeedbackItem`.
+ */
+export const FeedbackUpdateBodySchema = z.object({
+  status: FeedbackStatusSchema.optional(),
+  archived: z.boolean().optional(),
+});
+
+/** `DELETE /v1/feedback/:id` response — hard delete of a single row. */
+export const FeedbackDeleteResponseSchema = z.object({
+  deleted: z.literal(true),
+  id: z.string(),
+});

package/src/schemas/orgs.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
 import {
+  AppStoreSourceInfoSchema,
   CategorySchema,
   ListResponseSchema,
   OverviewPageItemSchema,
@@ -103,6 +104,10 @@ export const UpdateOrgBodySchema = z.object({
   aliases: z.array(z.string()).optional(),
   /** Admin-only: pause/unpause all ingest for this org without touching sources (#1057). */
   fetchPaused: z.boolean().optional(),
+  /** Admin-only: hide the org from the homepage ticker + /v1/orgs directory. Stays reachable via detail, search, sitemap. */
+  isHidden: z.boolean().optional(),
+  /** Admin-only: opt the org into automatic AI content — org overviews AND per-release summaries (single backend flag `auto_generate_content`). */
+  autoGenerateContent: z.boolean().optional(),
 });
 
 // Org detail's products query selects a strict subset of `ProductListItem` —
@@ -115,6 +120,9 @@ const OrgDetailProductSchema = ProductListItemSchema.pick({
   url: true,
   description: true,
   sourceCount: true,
+  kind: true,
+}).extend({
+  releaseCount: z.number().int().min(0),
 });
 
 const OrgDetailPlaybookSchema = z.object({
@@ -328,7 +336,28 @@ export const OrgSparklinesResponseSchema = z.object({
  * with a `source` block identifying the originating source within the org.
  */
 export const OrgReleaseItemSchema = ReleaseItemSchema.extend({
-  source: z.object({ slug: z.string(), name: z.string(), type: z.string() }),
+  source: z.object({
+    slug: z.string(),
+    name: z.string(),
+    type: z.string(),
+    appStore: AppStoreSourceInfoSchema.optional(),
+  }),
+  /**
+   * Owning product, when the release's source is grouped under a product.
+   * `null` when the source has no `product_id`. Additive — older API responses
+   * omit this field; treat `undefined` as `null`. #1217.
+   */
+  product: z.object({ slug: z.string(), name: z.string() }).nullable().optional(),
+  /**
+   * Server-resolved grouping identity — `COALESCE(product.slug, source.slug)` /
+   * `COALESCE(product.name, source.name)`. The web releases feed keys and labels
+   * SDK/package-cluster rollups on these instead of reconstructing
+   * `product ?? source` client-side. Optional on the wire: older workers omit
+   * them, so clients must fall back to deriving from `product ?? source`. Never
+   * null when present (`source` is always set). #1234
+   */
+  groupSlug: z.string().optional(),
+  groupName: z.string().optional(),
 });
 
 /** Cursor pagination shape for the org releases feed. */
@@ -394,6 +423,14 @@ export const OrgDetailSchema = z.object({
   description: z.string().nullable().optional(),
   category: CategorySchema.nullable().optional(),
   avatarUrl: z.string().nullable(),
+  /** Admin display flag: true when the org is hidden from listings (homepage + /v1/orgs). Optional on the wire for older workers mid-deploy. */
+  isHidden: z.boolean().optional(),
+  /** Admin display flag: org is opted into automatic overviews + per-release summaries. Optional on the wire for older workers mid-deploy. */
+  autoGenerateContent: z.boolean().optional(),
+  /** Admin display flag: all ingest paused for this org. */
+  fetchPaused: z.boolean().optional(),
+  /** How the org row was created. `on_demand` orgs are excluded from overview generation regardless of `autoGenerateContent`. */
+  discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
   tags: z.array(z.string()).optional(),
   sourceCount: z.number().int().min(0),
   releaseCount: z.number().int().min(0),

package/src/schemas/products.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { CategorySchema, ListResponseSchema } from "./shared.js";
-import { SourceTypeSchema } from "./sources.js";
+import { CategorySchema, ListResponseSchema, ReleaseItemSchema } from "./shared.js";
+import { SourceTypeSchema, SourceFeedPaginationSchema } from "./sources.js";
 
 /**
  * Raw `products` table row, returned by `POST /v1/products` and
@@ -21,15 +21,25 @@ export const ProductRowSchema = z.object({
   description: z.string().nullable(),
   category: CategorySchema.nullable(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  avatarUrl: z.string().nullable().optional(),
   createdAt: z.string(),
   embeddedAt: z.string().nullable(),
   deletedAt: z.string().nullable(),
 });
 
+/** 201 body of POST /v1/products — ProductRow plus an optional non-blocking
+ *  warning emitted when the new slug shadows an existing same-org source (#1190). */
+export const ProductCreateResponseSchema = ProductRowSchema.extend({
+  warning: z.string().optional(),
+});
+export type ProductCreateResponse = z.infer<typeof ProductCreateResponseSchema>;
+
 /**
  * Per-product row returned by `GET /v1/products`. Adds `sourceCount` to
  * the row shape but omits the internal `embeddedAt` / `deletedAt` columns
  * (the list handler explicitly selects only the user-facing fields).
+ * `avatarUrl` (the product icon, e.g. an App Store app icon) is included so
+ * list surfaces can render the avatar without a per-row detail round-trip.
  */
 export const ProductListItemSchema = z.object({
   id: z.string(),
@@ -40,6 +50,7 @@ export const ProductListItemSchema = z.object({
   description: z.string().nullable(),
   category: CategorySchema.nullable(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  avatarUrl: z.string().nullable().optional(),
   createdAt: z.string(),
   sourceCount: z.number().int().min(0),
 });
@@ -57,16 +68,27 @@ export const ProductDetailSourceSchema = z.object({
   name: z.string(),
   type: SourceTypeSchema,
   url: z.string(),
+  metadata: z.string().nullable().optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /**
  * Returned by `GET /v1/products/:identifier` (and the org-scoped twin).
  * Spreads the raw product row and adds `sources`, `tags`, `aliases`.
+ *
+ * `releases` and `pagination` are populated only by the web format adapter
+ * (the `.json` / `.md` product route — see PR #1207), NOT by the bare product
+ * detail endpoint. They are optional so bare endpoint consumers see a valid
+ * `ProductDetail` without the embedded feed.
  */
 export const ProductDetailSchema = ProductRowSchema.extend({
   sources: z.array(ProductDetailSourceSchema),
   tags: z.array(z.string()),
   aliases: z.array(z.string()),
+  /** Embedded release feed — set by the web format adapter (PR #1207), absent on bare product detail. */
+  releases: z.array(ReleaseItemSchema).optional(),
+  /** Cursor pagination for the embedded release feed — set by the web format adapter (PR #1207), absent on bare product detail. */
+  pagination: SourceFeedPaginationSchema.optional(),
 });
 
 /**
@@ -102,6 +124,7 @@ export const UpdateProductBodySchema = z.object({
   tags: z.array(z.string()).optional(),
   aliases: z.array(z.string()).optional(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  avatarUrl: z.string().nullable().optional(),
 });
 
 /**
@@ -177,3 +200,49 @@ export const ProductTagsBodySchema = z.object({
 export const ProductTagsMutationResponseSchema = z.object({
   ok: z.literal(true),
 });
+
+// ── Product activity (/products/:slug/activity, /orgs/:orgSlug/products/:productSlug/activity) ──
+
+const ProductActivityWeeklyBucketSchema = z.object({
+  weekStart: z.string(),
+  count: z.number().int().min(0),
+  earliestVersion: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+});
+
+const ProductActivitySourceSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  releaseCount: z.number().int().min(0),
+  avgReleasesPerWeek: z.number(),
+  earliestVersion: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+  latestDate: z.string().nullable(),
+  weeklyBuckets: z.array(ProductActivityWeeklyBucketSchema),
+});
+
+/**
+ * Response shape for `GET /v1/products/:slug/activity` and the org-scoped twin.
+ * Returns per-source weekly release buckets plus an aggregate rollup — used for
+ * timeline visualization on the product detail page.
+ */
+export const ProductActivityResponseSchema = z.object({
+  product: z.object({ slug: z.string(), name: z.string() }),
+  range: z.object({ from: z.string(), to: z.string() }),
+  sources: z.array(ProductActivitySourceSchema),
+  aggregateWeekly: z.array(z.object({ weekStart: z.string(), count: z.number().int().min(0) })),
+});
+
+// ── Product heatmap (/products/:slug/heatmap, /orgs/:orgSlug/products/:productSlug/heatmap) ──
+
+/**
+ * Response shape for `GET /v1/products/:slug/heatmap` and the org-scoped twin.
+ * Returns daily release counts for the trailing 365 days — used for
+ * contribution-graph visualization on the product detail page.
+ */
+export const ProductHeatmapResponseSchema = z.object({
+  product: 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),
+});

package/src/schemas/related.ts

@@ -17,8 +17,12 @@ export const RelatedReleaseSourceSchema = z.object({
   id: z.string(),
   slug: z.string(),
   name: z.string(),
+  /** Parent product name, when the source belongs to one — preferred over the
+   * bare source/feed name for display. Null for sources with no product. */
+  productName: z.string().nullable(),
   orgSlug: z.string().nullable(),
   orgName: z.string().nullable(),
+  orgAvatarUrl: z.string().nullable(),
 });
 
 /**

package/src/schemas/releases.ts

@@ -1,6 +1,11 @@
 import { z } from "zod";
 import { SOURCE_TYPES } from "@buildinternet/releases-core/source-enums";
-import { MediaItemSchema, ReleaseCompositionSchema, ReleaseTypeSchema } from "./shared.js";
+import {
+  AppStoreSourceInfoSchema,
+  MediaItemSchema,
+  ReleaseCompositionSchema,
+  ReleaseTypeSchema,
+} from "./shared.js";
 
 // ReleaseCompositionSchema lives in ./shared.js (single source of truth) — both
 // this file and ReleaseItemSchema reference it from there.
@@ -22,6 +27,11 @@ export const ReleaseLatestSourceSchema = z.object({
   orgSlug: z.string().nullable(),
 });
 
+export const ReleaseLatestProductSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+});
+
 export const ReleaseLatestItemSchema = z.object({
   id: z.string(),
   version: z.string().nullable(),
@@ -34,6 +44,12 @@ export const ReleaseLatestItemSchema = z.object({
   url: z.string().nullable(),
   media: z.array(MediaItemSchema),
   source: ReleaseLatestSourceSchema,
+  /**
+   * Owning product, when the release's source is grouped under a product.
+   * `null` when the source has no `product_id`. Additive — older API responses
+   * omit this field; treat `undefined` as `null`. #1217.
+   */
+  product: ReleaseLatestProductSchema.nullable().optional(),
   coverageCount: z.number().int().min(0).optional(),
   // Cached release-body size hint — see {@link ReleaseItemSchema} for the
   // same fields on the org / collection feeds. #958.
@@ -46,9 +62,31 @@ export const ReleaseLatestResponseSchema = z.object({
   releases: z.array(ReleaseLatestItemSchema),
 });
 
+/**
+ * Display fields for the counterpart release a coverage row points at —
+ * the canonical for a `coverage`-role response, or each rolled-up coverage
+ * release for a `canonical`-role response. Lets `GET /releases/:id/coverage`
+ * render a cluster without a follow-up `GET /releases/:id` per sibling.
+ * `null` when the counterpart is suppressed or its source was removed.
+ *
+ * Coverage-side rows are surfaced here on purpose, even though the
+ * `releases_visible` view (and thus `GET /releases/:id`) hides them — a
+ * cluster view's whole job is to show its members.
+ */
+export const ReleaseCoverageSiblingSchema = z.object({
+  id: z.string(),
+  version: z.string().nullable(),
+  title: z.string(),
+  sourceName: z.string(),
+  publishedAt: z.string().nullable(),
+  org: z.object({ slug: z.string(), name: z.string() }).nullable(),
+});
+
 /**
  * Single row of the `release_coverage` join table. Drives the
- * GET /releases/:id/coverage response.
+ * GET /releases/:id/coverage response. `sibling` carries the counterpart
+ * release's display fields (see {@link ReleaseCoverageSiblingSchema}); it is
+ * optional so an older server that doesn't populate it still validates.
  */
 export const ReleaseCoverageRowSchema = z.object({
   coverageId: z.string(),
@@ -56,6 +94,7 @@ export const ReleaseCoverageRowSchema = z.object({
   reason: z.string().nullable(),
   decidedBy: z.string(),
   decidedAt: z.string(),
+  sibling: ReleaseCoverageSiblingSchema.nullable().optional(),
 });
 
 /**
@@ -160,6 +199,7 @@ export const ReleaseDetailResponseSchema = z.object({
   sourceType: z.enum(SOURCE_TYPES).nullable(),
   org: ReleaseDetailOrgSchema.nullable(),
   composition: ReleaseCompositionSchema.nullable(),
+  appStore: AppStoreSourceInfoSchema.nullable().optional(),
 });
 
 /**

package/src/schemas/resolve.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { ProductDetailSchema } from "./products.js";
+import { SourceDetailSchema } from "./sources.js";
+
+/**
+ * Response of `GET /v1/orgs/:org/resolve/:slug` (#1190). Product-first: when a
+ * product and a source share a slug in an org, the product variant is returned.
+ * A 404 (ErrorResponse) is returned when neither matches.
+ */
+export const ResolveResponseSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("product"), product: ProductDetailSchema }),
+  z.object({ kind: z.literal("source"), source: SourceDetailSchema }),
+]);
+
+export type ResolveResponse = z.infer<typeof ResolveResponseSchema>;

package/src/schemas/search.ts

@@ -68,6 +68,9 @@ export const SearchReleaseHitSchema = z.object({
   sourceType: z.string().optional(),
   orgSlug: z.string().nullable(),
   orgName: z.string().nullable().optional(),
+  /** Owning product slug — present when the source belongs to a product. Lets
+   *  the web byline link to the product page instead of the source. */
+  productSlug: z.string().nullable().optional(),
   version: z.string().nullable(),
   title: z.string(),
   summary: z.string(),
@@ -113,8 +116,9 @@ export const SearchCollectionHitSchema = z.object({
 /**
  * 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.
+ * `/<orgSlug>/<sourceSlug>/changelog?offset=<offset>#chunk` to read the
+ * surrounding file content (the web `chunkDeepLink` builder; falls back to
+ * the `/source/<sourceSlug>` redirect shim when `orgSlug` is null).
  */
 export const SearchChunkHitSchema = z.object({
   sourceSlug: z.string(),

package/src/schemas/shared.ts

@@ -11,6 +11,17 @@ export const MediaItemSchema = z.object({
   r2Url: z.string().optional(),
 });
 
+/**
+ * App Store platform + icon for a `type: "appstore"` source. Threaded onto
+ * read surfaces so the UI can render the compact app-update row (app icon +
+ * "Available for iOS/macOS") instead of the standard version/notes/thumbnail
+ * layout. Sourced from `source.metadata.appStore` server-side. #mobile-appstore-feed-row
+ */
+export const AppStoreSourceInfoSchema = z.object({
+  platform: z.enum(["ios", "macos"]),
+  iconUrl: z.string().nullable(),
+});
+
 export const PaginationSchema = z.object({
   page: z.number().int().min(1),
   pageSize: z.number().int().min(1),

package/src/schemas/sitemap.ts

@@ -6,6 +6,12 @@ import { z } from "zod";
  * fields, but the current handler always populates them (#875).
  */
 export const SitemapSourceSchema = z.object({
+  /**
+   * Source id. `.optional()` for backwards compatibility — added #1190 so the
+   * web can route shadowed sources to `/sources/:id`; older/cached responses
+   * may omit it and the web degrades to the bare URL.
+   */
+  id: z.string().optional(),
   orgSlug: z.string(),
   slug: z.string(),
   latestDate: z.string().nullable(),

package/src/schemas/sources.ts

@@ -194,6 +194,38 @@ export const SourceMutationResponseSchema = z.looseObject({
   kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
+/**
+ * Response from `POST /v1/sources/appstore` — materializes an App Store listing
+ * into a curated Org → Product → Source → first Release (modeled on the GitHub
+ * coordinate `LookupResponse`).
+ *
+ * Unlike `SourceMutationResponse`, the `source` here is the **bare inserted (or
+ * idempotently looked-up) drizzle row** the materialize handler returns verbatim:
+ * no resolved `org { id, slug, name }` block and no `productSlug`. `loose` so the
+ * untyped timestamp/counter columns on the row pass through.
+ *
+ * `status: "indexed"` is a brand-new source (HTTP 201); `"existing"` is the
+ * idempotent hit on a prior materialize of the same trackId (HTTP 200).
+ */
+export const AppStoreMaterializeResponseSchema = z.object({
+  status: z.enum(["indexed", "existing"]),
+  source: z.looseObject({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    type: SourceTypeSchema,
+    url: z.string(),
+    orgId: z.string().nullable(),
+    productId: z.string().nullable(),
+    metadata: z.string().nullable(),
+    kind: z.enum(KIND_VALUES).nullable().optional(),
+    discovery: SourceDiscoverySchema.optional(),
+    isHidden: z.boolean().nullable().optional(),
+    createdAt: z.string().optional(),
+  }),
+  releaseCount: z.number(),
+});
+
 /** Body accepted by `PATCH /v1/sources/:slug`. */
 export const SourcePatchInputSchema = z.object({
   name: z.string().optional(),
@@ -459,12 +491,25 @@ export const SourceMetadataResponseSchema = z.object({
 
 // ── Changelog probe (POST /sources/:slug/changelog/probe) ──
 
+/**
+ * A discovered CHANGELOG path returned by the probe. Mirrors
+ * `DiscoveredChangelogPath` from `@releases/adapters/github-discovery`:
+ * `origin` tags where the path came from (repo root, a workspace package, or
+ * an explicit `metadata.changelogPaths` override) and `exists` is true when a
+ * directory listing confirmed the file on HEAD.
+ */
+export const DiscoveredChangelogPathSchema = z.object({
+  path: z.string(),
+  origin: z.enum(["root", "workspace", "override"]),
+  exists: z.boolean(),
+});
+
 /** 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()),
+  paths: z.array(DiscoveredChangelogPathSchema),
 });
 
 // ── Delete source (DELETE /sources/:slug) ──