@buildinternet/releases-api-types 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,10 @@
     "src",
     "README.md"
   ],
+  "dependencies": {
+    "@buildinternet/releases-core": "workspace:*",
+    "zod": "^4.3.6"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/api-types.ts

@@ -1,44 +1,132 @@
 /**
- * Shared API response types.
- *
- * This is the single source of truth for all API response shapes.
- * Consumed by: web frontend, CLI client, and (optionally) API worker routes.
+ * Shared API response types — single source of truth for the wire protocol.
+ * Consumed by: web frontend, MCP worker, OSS CLI, and the API worker.
  */
 
+import type { z } from "zod";
+
+export type {
+  SourceType,
+  SourceDiscovery,
+  SourceFetchPriority,
+} from "@buildinternet/releases-core/source-enums";
+import type {
+  MediaItemSchema,
+  PaginationSchema,
+  StatsSchema,
+  ErrorResponseSchema,
+  ReleaseTypeSchema,
+  ReleaseItemSchema,
+  ReleaseSummaryItemSchema,
+  OverviewPageItemSchema,
+} from "./schemas/shared.js";
+import type {
+  OrgListItemSchema,
+  OrgListResponseSchema,
+  OrgAccountItemSchema,
+  OrgAccountsResponseSchema,
+  OrgTagsResponseSchema,
+  CreateOrgBodySchema,
+  UpdateOrgBodySchema,
+  OrgDetailSchema,
+} from "./schemas/orgs.js";
+import type {
+  SourceListItemSchema,
+  SourceWithOrgSchema,
+  SourceListResponseSchema,
+  SourceListResultSchema,
+  SourceDetailSchema,
+  SourceMutationResponseSchema,
+  SourceOrgRefSchema,
+  SourcePatchInputSchema,
+  CreateSourceBodySchema,
+  ChangelogFileSummarySchema,
+  SourceChangelogResponseSchema,
+} from "./schemas/sources.js";
+import type {
+  ProductRowSchema,
+  ProductListItemSchema,
+  ProductListResponseSchema,
+  ProductDetailSourceSchema,
+  ProductDetailSchema,
+  CreateProductBodySchema,
+  UpdateProductBodySchema,
+  AdoptProductBodySchema,
+  ProductAdoptResultSchema,
+  ProductAdoptDryRunSchema,
+  ProductAdoptResponseSchema,
+  ProductDeleteResponseSchema,
+} from "./schemas/products.js";
+
+export {
+  MediaItemSchema,
+  PaginationSchema,
+  ListResponseSchema,
+  StatsSchema,
+  ErrorResponseSchema,
+  ReleaseTypeSchema,
+  ReleaseItemSchema,
+  ReleaseSummaryItemSchema,
+  OverviewPageItemSchema,
+  CategorySchema,
+} from "./schemas/shared.js";
+export {
+  OrgListItemSchema,
+  OrgListResponseSchema,
+  OrgAccountItemSchema,
+  OrgAccountsResponseSchema,
+  OrgTagsResponseSchema,
+  CreateOrgBodySchema,
+  UpdateOrgBodySchema,
+  OrgDetailSchema,
+} from "./schemas/orgs.js";
+export {
+  SourceListItemSchema,
+  SourceWithOrgSchema,
+  SourceListResponseSchema,
+  SourceListResultSchema,
+  SourceDetailSchema,
+  SourceMutationResponseSchema,
+  SourceOrgRefSchema,
+  SourcePatchInputSchema,
+  CreateSourceBodySchema,
+  ChangelogFileSummarySchema,
+  SourceChangelogResponseSchema,
+} from "./schemas/sources.js";
+export {
+  ProductRowSchema,
+  ProductListItemSchema,
+  ProductListResponseSchema,
+  ProductDetailSourceSchema,
+  ProductDetailSchema,
+  CreateProductBodySchema,
+  UpdateProductBodySchema,
+  AdoptProductBodySchema,
+  ProductAdoptResultSchema,
+  ProductAdoptDryRunSchema,
+  ProductAdoptResponseSchema,
+  ProductDeleteResponseSchema,
+} from "./schemas/products.js";
+
 // ── Media ──
 
-export interface MediaItem {
-  type: "image" | "video" | "gif";
-  url: string;
-  alt?: string;
-  r2Url?: string;
-}
+export type MediaItem = z.infer<typeof MediaItemSchema>;
 
 // ── Stats ──
 
-export interface Stats {
-  orgs: number;
-  sources: number;
-  releases: number;
-  products: number;
-}
+export type Stats = z.infer<typeof StatsSchema>;
 
 // ── Pagination ──
 
-export interface Pagination {
-  page: number;
-  pageSize: number;
-  returned: number;
-  totalItems?: number;
-  totalPages?: number;
-  hasMore: boolean;
-}
+export type Pagination = z.infer<typeof PaginationSchema>;
 
 export interface ListResponse<T> {
   items: T[];
   pagination: Pagination;
 }
 
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+
 // ── Sitemap (bulk URL emission) ──
 
 export interface SitemapPayload {
@@ -49,227 +137,29 @@ export interface SitemapPayload {
 
 // ── Organizations ──
 
-export interface OrgListItem {
-  slug: string;
-  name: string;
-  domain: string | null;
-  avatarUrl: string | null;
-  githubHandle: string | null;
-  sourceCount: number;
-  releaseCount: number;
-  recentReleaseCount: number;
-  lastActivity: string | null;
-  topProducts: string[];
-  sparkline: number[];
-}
+export type OrgListItem = z.infer<typeof OrgListItemSchema>;
+export type OrgListResponse = z.infer<typeof OrgListResponseSchema>;
+export type OrgAccountItem = z.infer<typeof OrgAccountItemSchema>;
+export type OrgAccountsResponse = z.infer<typeof OrgAccountsResponseSchema>;
+export type OrgTagsResponse = z.infer<typeof OrgTagsResponseSchema>;
+export type CreateOrgBody = z.infer<typeof CreateOrgBodySchema>;
+export type UpdateOrgBody = z.infer<typeof UpdateOrgBodySchema>;
 
-export type OrgListResponse = ListResponse<OrgListItem>;
-
-export interface OrgAccountItem {
-  platform: string;
-  handle: string;
-}
-
-export type OrgAccountsResponse = ListResponse<OrgAccountItem>;
-export type OrgTagsResponse = ListResponse<string>;
-
-export interface OrgDetail {
-  id?: string;
-  slug: string;
-  name: string;
-  domain: string | null;
-  description?: string | null;
-  category?: string | null;
-  avatarUrl: string | null;
-  tags?: string[];
-  sourceCount: number;
-  releaseCount: number;
-  releasesLast30Days: number;
-  avgReleasesPerWeek: number;
-  lastFetchedAt: string | null;
-  lastPolledAt: string | null;
-  trackingSince: string;
-  aliases?: string[];
-  accounts: OrgAccountItem[];
-  products: Array<{
-    id: string;
-    slug: string;
-    name: string;
-    url: string | null;
-    description: string | null;
-    sourceCount: number;
-  }>;
-  sources: SourceListItem[];
-  overview?: OverviewPageItem | null;
-  playbook?: { scope: "playbook"; content: string; updatedAt: string } | null;
-}
+export type OrgDetail = z.infer<typeof OrgDetailSchema>;
 
 // ── Sources ──
 
-export interface SourceListItem {
-  slug: string;
-  name: string;
-  type: string;
-  url?: string;
-  orgSlug?: string | null;
-  releaseCount: number;
-  latestVersion: string | null;
-  latestDate: string | null;
-  latestAddedAt?: string | null;
-  isPrimary?: boolean;
-  isHidden?: boolean;
-  /**
-   * How the row was created. Optional on the wire so older API responses
-   * (mid-deploy or pinned old workers) degrade gracefully — consumers that
-   * see `undefined` should treat it as `"curated"`.
-   */
-  discovery?: "curated" | "agent" | "on_demand";
-  fetchPriority?: "normal" | "low" | "paused" | null;
-  lastFetchedAt?: string | null;
-  lastPolledAt?: string | null;
-  changeDetectedAt?: string | null;
-  consecutiveNoChange?: number | null;
-  consecutiveErrors?: number | null;
-  nextFetchAfter?: string | null;
-  medianGapDays?: number | null;
-  lastRetieredAt?: string | null;
-  metadata?: string | null;
-  productName?: string | null;
-  productSlug?: string | null;
-}
-
-/**
- * Canonical shape returned by GET /v1/sources (list) and used by both
- * local-mode queries and the remote API client. Superset of SourceListItem
- * with required fields (id, orgName, orgSlug) that the CLI `list` command needs.
- */
-export interface SourceWithOrg {
-  id: string;
-  name: string;
-  slug: string;
-  type: string;
-  url: string;
-  orgName: string | null;
-  orgSlug: string | null;
-  productName: string | null;
-  productSlug: string | null;
-  isPrimary: boolean;
-  isHidden: boolean | null;
-  discovery?: "curated" | "agent" | "on_demand";
-  metadata: string | null;
-  releaseCount: number;
-  latestVersion: string | null;
-  latestDate: string | null;
-  lastFetchedAt: string | null;
-  lastPolledAt: string | null;
-  fetchPriority: string | null;
-  changeDetectedAt: string | null;
-  consecutiveNoChange: number | null;
-  consecutiveErrors: number | null;
-  nextFetchAfter: string | null;
-  medianGapDays: number | null;
-  lastRetieredAt: string | null;
-}
-
-/** Fields accepted by PATCH /v1/sources/:slug. */
-export interface SourcePatchInput {
-  name?: string;
-  url?: string;
-  type?: string;
-  slug?: string;
-  metadata?: string;
-  orgId?: string | null;
-  productId?: string | null;
-  lastFetchedAt?: string | null;
-  lastContentHash?: string | null;
-  fetchPriority?: string;
-  consecutiveNoChange?: number;
-  consecutiveErrors?: number;
-  nextFetchAfter?: string | null;
-  isPrimary?: boolean;
-  isHidden?: boolean;
-  changeDetectedAt?: string | null;
-  lastPolledAt?: string | null;
-}
-
-/** Lightweight summary of a changelog file — used for the file index. */
-export interface ChangelogFileSummary {
-  path: string;
-  filename: string;
-  url: string;
-  bytes: number;
-  fetchedAt: string;
-}
-
-export interface SourceChangelogResponse {
-  path: string;
-  filename: string;
-  url: string;
-  rawUrl: string;
-  content: string;
-  bytes: number;
-  fetchedAt: string;
-  /** Character offset of the first character in `content` within the full file. */
-  offset: number;
-  /** The limit (in chars) that was applied to produce this slice. */
-  limit: number;
-  /** Next offset to request for the next slice, or null if `content` is the tail. */
-  nextOffset: number | null;
-  /** Total length of the full file in characters. */
-  totalChars: number;
-  /** Requested token budget when in token mode (cl100k_base). */
-  tokens?: number;
-  /** Encoded token count of the returned `content`. Set in token mode. */
-  sliceTokens?: number;
-  /** Full-file token count (cl100k_base). Always populated. */
-  totalTokens: number;
-  /** True when the upstream file exceeded the 1MB cap and content was sliced. */
-  truncated: boolean;
-  /** Byte offset where the file was truncated, or null when not truncated. */
-  truncatedAt: number | null;
-  /**
-   * Index of every changelog file tracked for this source (root plus any
-   * discovered per-package files). Always present even for single-file
-   * sources so clients can lazily render a file picker.
-   */
-  files: ChangelogFileSummary[];
-}
-
-export interface SourceDetail {
-  slug: string;
-  name: string;
-  type: string;
-  url: string;
-  /**
-   * Hidden sources are reachable by direct URL but excluded from listings,
-   * sitemap, and AI features. Set on on-demand lookups and admin-suppressed
-   * rows; absent on canonical curated/agent sources.
-   */
-  isHidden?: boolean;
-  /**
-   * Pairs with `isHidden` to distinguish admin-suppressed rows (`curated` /
-   * `agent` + hidden) from rows materialized by `/v1/lookups` (`on_demand`).
-   * Optional for graceful degradation against older API responses.
-   */
-  discovery?: "curated" | "agent" | "on_demand";
-  changelogUrl?: string | null;
-  hasChangelogFile?: boolean;
-  org: { slug: string; name: string } | null;
-  releaseCount: number;
-  releasesLast30Days: number;
-  avgReleasesPerWeek: number;
-  latestVersion: string | null;
-  latestDate: string | null;
-  lastFetchedAt: string | null;
-  lastPolledAt: string | null;
-  trackingSince: string;
-  releases: ReleaseItem[];
-  pagination: Pagination;
-  summaries: {
-    rolling: ReleaseSummaryItem | null;
-    monthly: ReleaseSummaryItem[];
-  };
-}
+export type SourceListItem = z.infer<typeof SourceListItemSchema>;
+export type SourceWithOrg = z.infer<typeof SourceWithOrgSchema>;
+export type SourceListResponse = z.infer<typeof SourceListResponseSchema>;
+export type SourceListResult = z.infer<typeof SourceListResultSchema>;
+export type SourcePatchInput = z.infer<typeof SourcePatchInputSchema>;
+export type CreateSourceBody = z.infer<typeof CreateSourceBodySchema>;
+export type ChangelogFileSummary = z.infer<typeof ChangelogFileSummarySchema>;
+export type SourceChangelogResponse = z.infer<typeof SourceChangelogResponseSchema>;
+export type SourceDetail = z.infer<typeof SourceDetailSchema>;
+export type SourceMutationResponse = z.infer<typeof SourceMutationResponseSchema>;
+export type SourceOrgRef = z.infer<typeof SourceOrgRefSchema>;
 
 // ── Admin telemetry: orgs rollup ──
 
@@ -305,20 +195,9 @@ export interface OrgsRollupResponse extends ListResponse<OrgsRollupRow> {
  * Optional on the wire so older API responses (mid-deploy or pinned old workers)
  * degrade gracefully — consumers that see `undefined` should treat it as `"feature"`.
  */
-export type ReleaseType = "feature" | "rollup";
+export type ReleaseType = z.infer<typeof ReleaseTypeSchema>;
 
-export interface ReleaseItem {
-  id?: string;
-  version: string | null;
-  title: string;
-  summary: string;
-  content?: string;
-  publishedAt: string | null;
-  url: string | null;
-  media?: MediaItem[];
-  /** Release type. See {@link ReleaseType}. */
-  type?: ReleaseType;
-}
+export type ReleaseItem = z.infer<typeof ReleaseItemSchema>;
 
 export interface ReleaseDetail {
   id: string;
@@ -352,14 +231,7 @@ export type ReleaseCoverageResponse =
   | { role: "coverage"; canonical: ReleaseCoverageRow; covers: [] }
   | { role: "canonical"; canonical: null; covers: ReleaseCoverageRow[] };
 
-export interface ReleaseSummaryItem {
-  year?: number | null;
-  month?: number | null;
-  windowDays?: number | null;
-  summary: string;
-  releaseCount: number;
-  generatedAt: string;
-}
+export type ReleaseSummaryItem = z.infer<typeof ReleaseSummaryItemSchema>;
 
 // ── Search ──
 
@@ -497,6 +369,50 @@ export interface SearchChunkHit {
   score: number;
 }
 
+// ── Lookup by domain (entity resolution) ──
+
+/**
+ * Returned by GET /v1/lookups/by-domain. Pure resolution: the server
+ * normalizes the input domain, exact-matches against
+ * `organizations.domain` (primary) and `domain_aliases.domain` (alias for
+ * either an org or a product), and returns whatever it finds. Unknown
+ * domains 404 — there is no on-demand probing for domains, unlike the
+ * GitHub coordinate path.
+ */
+export interface DomainLookupResponse {
+  /** Normalized domain that was matched (lowercased, no scheme/path/www). */
+  domain: string;
+  /**
+   * Owning organization, if one exists. `matchedVia` distinguishes a hit
+   * on `organizations.domain` (`"primary"`) from an alias hit
+   * (`"alias"`) so the UI can render the difference.
+   */
+  org: {
+    id: string;
+    slug: string;
+    name: string;
+    domain: string | null;
+    description: string | null;
+    category: string | null;
+    avatarUrl: string | null;
+    matchedVia: "primary" | "alias";
+  } | null;
+  /**
+   * Products whose alias points at this domain. Multiple are possible
+   * when an org owns several products that all set the same alias —
+   * unusual, but allowed.
+   */
+  products: Array<{
+    id: string;
+    slug: string;
+    name: string;
+    orgId: string;
+    orgSlug: string;
+    orgName: string;
+    category: string | null;
+  }>;
+}
+
 // ── Lookup (on-demand GitHub index) ──
 
 export type LookupStatus = "indexed" | "existing" | "empty" | "not_found" | "deferred";
@@ -535,6 +451,21 @@ export interface LookupResultPayload {
 
 export interface UnifiedSearchResponse {
   query: string;
+  /**
+   * Normalized form of `?domain=` when the caller passed it. The server
+   * does the normalization once and echoes the canonical form back so
+   * clients don't have to re-normalize for analytics or display. Absent
+   * when no domain filter was applied.
+   */
+  domain?: string;
+  /**
+   * Outcome of the `?domain=` resolution step. `"matched"` means the
+   * domain resolved to a known org and results below are scoped to it.
+   * `"not_found"` means the domain didn't match anything; in that case
+   * orgs/catalog/releases will all be empty arrays — the caller can
+   * distinguish "no hits in scope" from "scope didn't exist."
+   */
+  domainStatus?: "matched" | "not_found";
   orgs: SearchOrgHit[];
   /** Products and standalone sources folded into a single list. */
   catalog: SearchCatalogHit[];
@@ -559,16 +490,7 @@ export interface UnifiedSearchResponse {
 
 // ── Overview Pages ──
 
-export interface OverviewPageItem {
-  scope: "org" | "product";
-  orgSlug?: string | null;
-  productSlug?: string | null;
-  content: string;
-  releaseCount: number;
-  lastContributingReleaseAt: string | null;
-  generatedAt: string;
-  updatedAt: string;
-}
+export type OverviewPageItem = z.infer<typeof OverviewPageItemSchema>;
 
 /** @deprecated Use OverviewPageItem */
 export type KnowledgePageItem = OverviewPageItem;
@@ -700,39 +622,20 @@ export interface OrgReleasesResponse {
 
 // ── Products ──
 
-export interface ProductListItem {
-  id: string;
-  name: string;
-  slug: string;
-  orgId: string;
-  url: string | null;
-  description: string | null;
-  category: string | null;
-  createdAt: string;
-  sourceCount: number;
-}
-
-export type ProductListResponse = ListResponse<ProductListItem>;
-
-export interface ProductDetail {
-  id: string;
-  name: string;
-  slug: string;
-  orgId: string;
-  url: string | null;
-  description: string | null;
-  category: string | null;
-  createdAt: string;
-  sources: Array<{ id: string; slug: string; name: string; type: string; url: string }>;
-  tags: string[];
-}
-
-export interface ProductAdoptResult {
-  product: ProductDetail;
-  sourcesMoved: number;
-  accountsMoved: number;
-  sourceOrgDeleted: string;
-}
+// `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 ProductListItem = z.infer<typeof ProductListItemSchema>;
+export type ProductListResponse = z.infer<typeof ProductListResponseSchema>;
+export type ProductDetailSource = z.infer<typeof ProductDetailSourceSchema>;
+export type ProductDetail = z.infer<typeof ProductDetailSchema>;
+export type CreateProductBody = z.infer<typeof CreateProductBodySchema>;
+export type UpdateProductBody = z.infer<typeof UpdateProductBodySchema>;
+export type AdoptProductBody = z.infer<typeof AdoptProductBodySchema>;
+export type ProductAdoptResult = z.infer<typeof ProductAdoptResultSchema>;
+export type ProductAdoptDryRun = z.infer<typeof ProductAdoptDryRunSchema>;
+export type ProductAdoptResponse = z.infer<typeof ProductAdoptResponseSchema>;
+export type ProductDeleteResponse = z.infer<typeof ProductDeleteResponseSchema>;
 
 // ── Taxonomy (categories + tags) ──
 

package/src/schemas/orgs.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { CategorySchema, ListResponseSchema, OverviewPageItemSchema } from "./shared.js";
+import { SourceListItemSchema } from "./sources.js";
+import { ProductListItemSchema } from "./products.js";
+
+export const OrgListItemSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  description: z.string().nullable(),
+  category: CategorySchema.nullable(),
+  avatarUrl: z.string().nullable(),
+  sourceCount: z.number().int().min(0),
+  releaseCount: z.number().int().min(0),
+  recentReleaseCount: z.number().int().min(0),
+  lastActivity: z.string().nullable(),
+  topProducts: z.array(z.string()),
+  sparkline: z.array(z.number().int().min(0)).length(30),
+});
+
+export const OrgListResponseSchema = ListResponseSchema(OrgListItemSchema);
+
+export const OrgAccountItemSchema = z.object({
+  platform: z.string(),
+  handle: z.string(),
+});
+
+export const OrgAccountsResponseSchema = ListResponseSchema(OrgAccountItemSchema);
+export const OrgTagsResponseSchema = ListResponseSchema(z.string());
+
+export const CreateOrgBodySchema = z.object({
+  name: z.string().min(1),
+  slug: z.string().optional(),
+  domain: z.string().optional(),
+  description: z.string().optional(),
+  category: CategorySchema.optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+export const UpdateOrgBodySchema = z.object({
+  name: z.string().optional(),
+  slug: z.string().optional(),
+  domain: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  category: CategorySchema.nullable().optional(),
+  tags: z.array(z.string()).optional(),
+  aliases: z.array(z.string()).optional(),
+});
+
+// Org detail's products query selects a strict subset of `ProductListItem` —
+// no category/orgId/createdAt because the parent already names the org and
+// the org detail UI doesn't surface those columns.
+const OrgDetailProductSchema = ProductListItemSchema.pick({
+  id: true,
+  slug: true,
+  name: true,
+  url: true,
+  description: true,
+  sourceCount: true,
+});
+
+const OrgDetailPlaybookSchema = z.object({
+  scope: z.literal("playbook"),
+  content: z.string(),
+  updatedAt: z.string(),
+});
+
+export const OrgDetailSchema = z.object({
+  id: z.string().optional(),
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  description: z.string().nullable().optional(),
+  category: CategorySchema.nullable().optional(),
+  avatarUrl: z.string().nullable(),
+  tags: z.array(z.string()).optional(),
+  sourceCount: z.number().int().min(0),
+  releaseCount: z.number().int().min(0),
+  releasesLast30Days: z.number().int().min(0),
+  avgReleasesPerWeek: z.number(),
+  lastFetchedAt: z.string().nullable(),
+  lastPolledAt: z.string().nullable(),
+  trackingSince: z.string(),
+  aliases: z.array(z.string()).optional(),
+  accounts: z.array(OrgAccountItemSchema),
+  products: z.array(OrgDetailProductSchema),
+  sources: z.array(SourceListItemSchema),
+  overview: OverviewPageItemSchema.nullable().optional(),
+  playbook: OrgDetailPlaybookSchema.nullable().optional(),
+});

package/src/schemas/products.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { CategorySchema, ListResponseSchema } from "./shared.js";
+import { SourceTypeSchema } from "./sources.js";
+
+/**
+ * Raw `products` table row, returned by `POST /v1/products` and
+ * `PATCH /v1/products/:slug`. The OSS CLI types these responses against
+ * `Product` from `@buildinternet/releases-core/schema` (the drizzle row
+ * type), so `embeddedAt` and `deletedAt` stay on the wire even though
+ * they're internal columns. `deletedAt` is always `null` on these paths
+ * (live rows only); `embeddedAt` reflects when the product was last
+ * indexed for semantic search.
+ */
+export const ProductRowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  orgId: z.string(),
+  url: z.string().nullable(),
+  description: z.string().nullable(),
+  category: CategorySchema.nullable(),
+  createdAt: z.string(),
+  embeddedAt: z.string().nullable(),
+  deletedAt: z.string().nullable(),
+});
+
+/**
+ * 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).
+ */
+export const ProductListItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  orgId: z.string(),
+  url: z.string().nullable(),
+  description: z.string().nullable(),
+  category: CategorySchema.nullable(),
+  createdAt: z.string(),
+  sourceCount: z.number().int().min(0),
+});
+
+export const ProductListResponseSchema = ListResponseSchema(ProductListItemSchema);
+
+/**
+ * Embedded source row returned in `ProductDetail.sources`. The detail
+ * handler explicitly selects only this small subset; reuses the shared
+ * `SourceTypeSchema` enum so source types stay in one place.
+ */
+export const ProductDetailSourceSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: SourceTypeSchema,
+  url: z.string(),
+});
+
+/**
+ * Returned by `GET /v1/products/:identifier` (and the org-scoped twin).
+ * Spreads the raw product row and adds `sources`, `tags`, `aliases`.
+ */
+export const ProductDetailSchema = ProductRowSchema.extend({
+  sources: z.array(ProductDetailSourceSchema),
+  tags: z.array(z.string()),
+  aliases: z.array(z.string()),
+});
+
+/** Body accepted by `POST /v1/products`. */
+export const CreateProductBodySchema = z.object({
+  name: z.string().min(1),
+  orgId: z.string().optional(),
+  orgSlug: z.string().optional(),
+  slug: z.string().optional(),
+  url: z.string().optional(),
+  description: z.string().optional(),
+  category: CategorySchema.optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+/** Body accepted by `PATCH /v1/products/:slug`. */
+export const UpdateProductBodySchema = z.object({
+  name: z.string().optional(),
+  url: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  category: CategorySchema.nullable().optional(),
+  tags: z.array(z.string()).optional(),
+  aliases: z.array(z.string()).optional(),
+});
+
+/** Body accepted by `POST /v1/products/adopt`. */
+export const AdoptProductBodySchema = z.object({
+  sourceOrgSlug: z.string().min(1),
+  targetOrgSlug: z.string().min(1),
+  slug: z.string().optional(),
+  url: z.string().optional(),
+  dryRun: z.boolean().optional(),
+});
+
+/** Live (non-dryRun) result from `POST /v1/products/adopt`. */
+export const ProductAdoptResultSchema = z.object({
+  product: ProductRowSchema,
+  sourcesMoved: z.number().int().min(0),
+  accountsMoved: z.number().int().min(0),
+  sourceOrgDeleted: z.string(),
+});
+
+/** Dry-run preview from `POST /v1/products/adopt` with `dryRun: true`. */
+export const ProductAdoptDryRunSchema = z.object({
+  dryRun: z.literal(true),
+  product: z.object({
+    name: z.string(),
+    slug: z.string(),
+    url: z.string().nullable(),
+    orgSlug: z.string(),
+  }),
+  sourcesToMove: z.array(z.string()),
+  sourceOrgToDelete: z.string(),
+});
+
+/** Response shape returned by `POST /v1/products/adopt` (union of live + dry-run). */
+export const ProductAdoptResponseSchema = z.union([
+  ProductAdoptResultSchema,
+  ProductAdoptDryRunSchema,
+]);
+
+/** Response shape returned by `DELETE /v1/products/:identifier`. */
+export const ProductDeleteResponseSchema = z.object({
+  deleted: z.literal(true),
+  hard: z.literal(true).optional(),
+  deletedAt: z.string().optional(),
+});

package/src/schemas/shared.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { RELEASE_TYPES } from "@buildinternet/releases-core/schema";
+import { CATEGORIES } from "@buildinternet/releases-core/categories";
+
+export const CategorySchema = z.enum(CATEGORIES);
+
+export const MediaItemSchema = z.object({
+  type: z.enum(["image", "video", "gif"]),
+  url: z.string(),
+  alt: z.string().optional(),
+  r2Url: z.string().optional(),
+});
+
+export const PaginationSchema = z.object({
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+  returned: z.number().int().min(0),
+  totalItems: z.number().int().min(0).optional(),
+  totalPages: z.number().int().min(0).optional(),
+  hasMore: z.boolean(),
+});
+
+export const ListResponseSchema = <T extends z.ZodTypeAny>(item: T) =>
+  z.object({
+    items: z.array(item),
+    pagination: PaginationSchema,
+  });
+
+export const ErrorResponseSchema = z.object({
+  error: z.string(),
+  message: z.string(),
+});
+
+export const StatsSchema = z.object({
+  orgs: z.number().int().min(0),
+  sources: z.number().int().min(0),
+  releases: z.number().int().min(0),
+  products: z.number().int().min(0),
+});
+
+export const ReleaseTypeSchema = z.enum(RELEASE_TYPES);
+
+export const ReleaseItemSchema = z.object({
+  id: z.string().optional(),
+  version: z.string().nullable(),
+  title: z.string(),
+  summary: z.string(),
+  content: z.string().optional(),
+  publishedAt: z.string().nullable(),
+  url: z.string().nullable(),
+  media: z.array(MediaItemSchema).optional(),
+  // `.optional()` — older API responses (mid-deploy or pinned old workers)
+  // may omit `type`; consumers should treat `undefined` as `"feature"`.
+  type: ReleaseTypeSchema.optional(),
+  // Pre-release flag (alpha/beta/rc/preview/nightly). Computed at ingest —
+  // GitHub uses the API's authoritative `prerelease` field; other adapters
+  // fall back to a SemVer-prerelease regex. `.optional()` for the same
+  // older-response degrade-gracefully reason as `type`.
+  prerelease: z.boolean().optional(),
+});
+
+export const ReleaseSummaryItemSchema = z.object({
+  year: z.number().int().nullable().optional(),
+  month: z.number().int().nullable().optional(),
+  windowDays: z.number().int().nullable().optional(),
+  summary: z.string(),
+  releaseCount: z.number().int().min(0),
+  generatedAt: z.string(),
+});
+
+export const OverviewPageItemSchema = z.object({
+  scope: z.enum(["org", "product"]),
+  orgSlug: z.string().nullable().optional(),
+  productSlug: z.string().nullable().optional(),
+  content: z.string(),
+  releaseCount: z.number().int().min(0),
+  lastContributingReleaseAt: z.string().nullable(),
+  generatedAt: z.string(),
+  updatedAt: z.string(),
+});

package/src/schemas/sources.ts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import {
+  SOURCE_TYPES,
+  SOURCE_DISCOVERY,
+  SOURCE_FETCH_PRIORITIES,
+} from "@buildinternet/releases-core/source-enums";
+import {
+  ListResponseSchema,
+  PaginationSchema,
+  ReleaseItemSchema,
+  ReleaseSummaryItemSchema,
+} from "./shared.js";
+
+export const SourceTypeSchema = z.enum(SOURCE_TYPES);
+export const SourceDiscoverySchema = z.enum(SOURCE_DISCOVERY);
+export const SourceFetchPrioritySchema = z.enum(SOURCE_FETCH_PRIORITIES);
+
+/**
+ * Per-source row used in list/embedded contexts (e.g. nested inside OrgDetail).
+ * Most fields are optional — embedded shapes (org detail) only carry the
+ * subset needed for that view.
+ */
+export const SourceListItemSchema = z.object({
+  id: z.string().optional(),
+  slug: z.string(),
+  name: z.string(),
+  type: SourceTypeSchema,
+  url: z.string().optional(),
+  // `orgSlug` is populated on the standalone `/v1/sources` list path; the
+  // `OrgDetail.sources` embedded path omits it (the parent already names the org).
+  orgSlug: z.string().nullable().optional(),
+  releaseCount: z.number().int().min(0),
+  latestVersion: z.string().nullable(),
+  latestDate: z.string().nullable(),
+  latestAddedAt: z.string().nullable().optional(),
+  isPrimary: z.boolean().optional(),
+  isHidden: z.boolean().optional(),
+  /**
+   * How the row was created. Optional on the wire so older API responses
+   * (mid-deploy or pinned old workers) degrade gracefully — consumers that
+   * see `undefined` should treat it as `"curated"`.
+   */
+  discovery: SourceDiscoverySchema.optional(),
+  fetchPriority: SourceFetchPrioritySchema.nullable().optional(),
+  lastFetchedAt: z.string().nullable().optional(),
+  lastPolledAt: z.string().nullable().optional(),
+  changeDetectedAt: z.string().nullable().optional(),
+  consecutiveNoChange: z.number().int().nullable().optional(),
+  consecutiveErrors: z.number().int().nullable().optional(),
+  nextFetchAfter: z.string().nullable().optional(),
+  medianGapDays: z.number().nullable().optional(),
+  lastRetieredAt: z.string().nullable().optional(),
+  metadata: z.string().nullable().optional(),
+  productName: z.string().nullable().optional(),
+  productSlug: z.string().nullable().optional(),
+});
+
+/**
+ * Canonical row returned by `GET /v1/sources` (list). Superset of
+ * `SourceListItem` with required `id` / `orgName` / `orgSlug` fields used by
+ * the CLI `list` command.
+ */
+export const SourceWithOrgSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  type: SourceTypeSchema,
+  url: z.string(),
+  orgName: z.string().nullable(),
+  orgSlug: z.string().nullable(),
+  productName: z.string().nullable(),
+  productSlug: z.string().nullable(),
+  isPrimary: z.boolean(),
+  isHidden: z.boolean().nullable(),
+  discovery: SourceDiscoverySchema.optional(),
+  metadata: z.string().nullable(),
+  releaseCount: z.number().int().min(0),
+  latestVersion: z.string().nullable(),
+  latestDate: z.string().nullable(),
+  lastFetchedAt: z.string().nullable(),
+  lastPolledAt: z.string().nullable(),
+  fetchPriority: SourceFetchPrioritySchema.nullable(),
+  changeDetectedAt: z.string().nullable(),
+  consecutiveNoChange: z.number().int().nullable(),
+  consecutiveErrors: z.number().int().nullable(),
+  nextFetchAfter: z.string().nullable(),
+  medianGapDays: z.number().nullable(),
+  lastRetieredAt: z.string().nullable(),
+});
+
+export const SourceListResponseSchema = ListResponseSchema(SourceWithOrgSchema);
+
+/**
+ * `GET /v1/sources` returns a bare array by default and an envelope when
+ * `?envelope=true` is passed. The OpenAPI spec advertises the union so
+ * either client expectation is documented.
+ */
+export const SourceListResultSchema = z.union([
+  z.array(SourceWithOrgSchema),
+  SourceListResponseSchema,
+]);
+
+const SourceDetailSummariesSchema = z.object({
+  rolling: ReleaseSummaryItemSchema.nullable(),
+  monthly: z.array(ReleaseSummaryItemSchema),
+});
+
+/**
+ * Resolved attribution block returned alongside a source row. `id` is
+ * additive vs the legacy `{ slug, name }` shape — older clients that ignored
+ * it still parse cleanly. `productId` / `productSlug` are sibling top-level
+ * fields on the source response (kept flat to mirror `orgId`), not nested
+ * inside this block.
+ */
+export const SourceOrgRefSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+});
+
+export const SourceDetailSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: SourceTypeSchema,
+  url: z.string(),
+  orgId: z.string().nullable(),
+  productId: z.string().nullable(),
+  productSlug: z.string().nullable(),
+  // Hidden sources are reachable by direct URL but excluded from listings,
+  // sitemap, and AI features. On-demand lookups and admin-suppressed rows
+  // set this true; canonical curated/agent sources leave it false.
+  isHidden: z.boolean(),
+  // Pairs with `isHidden` to distinguish admin-suppressed rows (`curated` /
+  // `agent` + hidden) from rows materialized by `/v1/lookups` (`on_demand`).
+  // Optional for graceful degradation against older API responses.
+  discovery: SourceDiscoverySchema.optional(),
+  isPrimary: z.boolean(),
+  metadata: z.string(),
+  changelogUrl: z.string().nullable().optional(),
+  hasChangelogFile: z.boolean().optional(),
+  org: SourceOrgRefSchema.nullable(),
+  releaseCount: z.number().int().min(0),
+  releasesLast30Days: z.number().int().min(0),
+  avgReleasesPerWeek: z.number(),
+  latestVersion: z.string().nullable(),
+  latestDate: z.string().nullable(),
+  lastFetchedAt: z.string().nullable(),
+  lastPolledAt: z.string().nullable(),
+  trackingSince: z.string(),
+  releases: z.array(ReleaseItemSchema),
+  pagination: PaginationSchema,
+  summaries: SourceDetailSummariesSchema,
+});
+
+/**
+ * Response returned by `POST /v1/sources` and `PATCH /v1/sources/:slug`.
+ *
+ * Pre-#794 these endpoints returned the bare drizzle row, leaving callers to
+ * round-trip a separate `GET` to confirm the resolved org/product attribution.
+ * Now they return the same source row plus a resolved `org { id, slug, name }`
+ * block and `productSlug`, so an agent can answer "did the write take?" from
+ * the response alone.
+ *
+ * Wire fields are loosely-typed (`z.unknown()`) for the timestamps/counters
+ * that aren't load-bearing for callers — the row is large and we don't want
+ * to hand-mirror every column. Stable, agent-relevant fields are typed.
+ */
+export const SourceMutationResponseSchema = z.looseObject({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: SourceTypeSchema,
+  url: z.string(),
+  orgId: z.string().nullable(),
+  productId: z.string().nullable(),
+  productSlug: z.string().nullable(),
+  org: SourceOrgRefSchema.nullable(),
+  metadata: z.string().nullable(),
+  isPrimary: z.boolean().nullable().optional(),
+  isHidden: z.boolean().nullable().optional(),
+  discovery: SourceDiscoverySchema.optional(),
+  createdAt: z.string().optional(),
+});
+
+/** Body accepted by `PATCH /v1/sources/:slug`. */
+export const SourcePatchInputSchema = z.object({
+  name: z.string().optional(),
+  url: z.string().optional(),
+  type: SourceTypeSchema.optional(),
+  slug: z.string().optional(),
+  metadata: z.string().optional(),
+  orgId: z.string().nullable().optional(),
+  productId: z.string().nullable().optional(),
+  lastFetchedAt: z.string().nullable().optional(),
+  lastContentHash: z.string().nullable().optional(),
+  fetchPriority: SourceFetchPrioritySchema.optional(),
+  consecutiveNoChange: z.number().int().optional(),
+  consecutiveErrors: z.number().int().optional(),
+  nextFetchAfter: z.string().nullable().optional(),
+  isPrimary: z.boolean().optional(),
+  isHidden: z.boolean().optional(),
+  changeDetectedAt: z.string().nullable().optional(),
+  lastPolledAt: z.string().nullable().optional(),
+});
+
+/** Body accepted by `POST /v1/sources`. */
+export const CreateSourceBodySchema = z.object({
+  name: z.string().min(1),
+  url: z.string().min(1),
+  type: SourceTypeSchema.optional(),
+  slug: z.string().optional(),
+  orgId: z.string().optional(),
+  orgSlug: z.string().optional(),
+  /**
+   * Either accepted; `productId` wins when both are supplied. `productSlug`
+   * resolves within the requested org (slug uniqueness is per-org). The
+   * legacy `productId` ingestion path is preserved for callers that already
+   * resolve products client-side; new agent flows should pass `productSlug`.
+   */
+  productId: z.string().optional(),
+  productSlug: z.string().optional(),
+  metadata: z.string().optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const ChangelogFileSummarySchema = z.object({
+  path: z.string(),
+  filename: z.string(),
+  url: z.string(),
+  bytes: z.number().int().min(0),
+  fetchedAt: z.string(),
+});
+
+export const SourceChangelogResponseSchema = z.object({
+  path: z.string(),
+  filename: z.string(),
+  url: z.string(),
+  rawUrl: z.string(),
+  content: z.string(),
+  bytes: z.number().int().min(0),
+  fetchedAt: z.string(),
+  /** Character offset of the first character in `content` within the full file. */
+  offset: z.number().int().min(0),
+  /** The limit (in chars) that was applied to produce this slice. */
+  limit: z.number().int().min(0),
+  /** Next offset to request for the next slice, or null if `content` is the tail. */
+  nextOffset: z.number().int().nullable(),
+  /** Total length of the full file in characters. */
+  totalChars: z.number().int().min(0),
+  /** Requested token budget when in token mode (cl100k_base). */
+  tokens: z.number().int().optional(),
+  /** Encoded token count of the returned `content`. Set in token mode. */
+  sliceTokens: z.number().int().optional(),
+  /** Full-file token count (cl100k_base). Always populated. */
+  totalTokens: z.number().int().min(0),
+  /** True when the upstream file exceeded the 1MB cap and content was sliced. */
+  truncated: z.boolean(),
+  /** Byte offset where the file was truncated, or null when not truncated. */
+  truncatedAt: z.number().int().nullable(),
+  /**
+   * Index of every changelog file tracked for this source (root plus any
+   * discovered per-package files). Always present even for single-file
+   * sources so clients can lazily render a file picker.
+   */
+  files: z.array(ChangelogFileSummarySchema),
+});