@buildinternet/releases-api-types 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@buildinternet/releases-core": "^0.21.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "publishConfig": {
     "access": "public"

package/src/api-types.ts

@@ -16,6 +16,7 @@ import type {
   StatsSchema,
   ErrorResponseSchema,
   ReleaseTypeSchema,
+  ReleaseCompositionSchema,
   ReleaseItemSchema,
   ReleaseSummaryItemSchema,
   OverviewPageItemSchema,
@@ -148,6 +149,7 @@ import type {
   SearchSourceHitSchema,
   SearchReleaseHitSchema,
   SearchChunkHitSchema,
+  SearchCollectionHitSchema,
   LookupResultPayloadSchema,
   UnifiedSearchResponseSchema,
 } from "./schemas/search.js";
@@ -221,6 +223,7 @@ export {
   StatsSchema,
   ErrorResponseSchema,
   ReleaseTypeSchema,
+  ReleaseCompositionSchema,
   ReleaseItemSchema,
   ReleaseSummaryItemSchema,
   OverviewPageItemSchema,
@@ -367,6 +370,7 @@ export {
   SearchSourceHitSchema,
   SearchReleaseHitSchema,
   SearchChunkHitSchema,
+  SearchCollectionHitSchema,
   LookupResultPayloadSchema,
   UnifiedSearchResponseSchema,
 } from "./schemas/search.js";
@@ -569,6 +573,7 @@ export interface OrgsRollupResponse extends ListResponse<OrgsRollupRow> {
 export type ReleaseType = z.infer<typeof ReleaseTypeSchema>;
 
 export type ReleaseItem = z.infer<typeof ReleaseItemSchema>;
+export type ReleaseComposition = z.infer<typeof ReleaseCompositionSchema>;
 
 export interface ReleaseDetail {
   id: string;
@@ -597,6 +602,8 @@ export interface ReleaseDetail {
   org: { slug: string; name: string } | null;
   /** Release type. See {@link ReleaseType}. */
   type?: ReleaseType;
+  /** Per-category item counts from the AI release-content pass. See {@link ReleaseComposition}. */
+  composition?: ReleaseComposition | null;
 }
 
 export type ReleaseCoverageRow = z.infer<typeof ReleaseCoverageRowSchema>;
@@ -676,6 +683,63 @@ export function foldSourcesIntoCatalog(
 
 export type SearchReleaseHit = z.infer<typeof SearchReleaseHitSchema>;
 export type SearchChunkHit = z.infer<typeof SearchChunkHitSchema>;
+export type SearchCollectionHit = z.infer<typeof SearchCollectionHitSchema>;
+
+/**
+ * Merge collection hits from three independent sources into one ordered,
+ * deduped array on the wire:
+ *
+ *   1. Direct lexical matches   — name/slug/description LIKE.
+ *   2. Direct semantic matches  — vector hit (hybrid/semantic only).
+ *   3. Member rollups           — collections containing one of the result orgs.
+ *
+ * A direct row always wins for a given slug; member rollups attach their
+ * `matchedOrgSlugs` to a winning direct row so the UI keeps the "shown
+ * because" affordance. Within each `via` bucket, rows order by score desc
+ * (missing scores last) then by name.
+ *
+ * Pure: no DB, no Workers runtime. Used by both `/v1/search` and the MCP
+ * `search` tool so the merge stays in lockstep across surfaces.
+ */
+export function mergeCollectionHits(
+  direct: SearchCollectionHit[],
+  semantic: SearchCollectionHit[],
+  member: SearchCollectionHit[],
+  limit: number,
+): SearchCollectionHit[] {
+  // Pure: never mutate caller-owned objects. Always replace map entries with
+  // shallow copies so two callers (e.g. API and MCP merging from the same
+  // upstream list) can't see each other's writes.
+  const bySlug = new Map<string, SearchCollectionHit>();
+  for (const c of direct) bySlug.set(c.slug, { ...c });
+  for (const c of semantic) {
+    const existing = bySlug.get(c.slug);
+    if (existing) {
+      if (c.score !== undefined && (existing.score === undefined || c.score > existing.score)) {
+        bySlug.set(c.slug, { ...existing, score: c.score });
+      }
+    } else {
+      bySlug.set(c.slug, { ...c });
+    }
+  }
+  for (const c of member) {
+    const existing = bySlug.get(c.slug);
+    if (existing) {
+      bySlug.set(c.slug, { ...existing, matchedOrgSlugs: c.matchedOrgSlugs });
+    } else {
+      bySlug.set(c.slug, { ...c });
+    }
+  }
+  return [...bySlug.values()]
+    .toSorted((a, b) => {
+      if (a.via !== b.via) return a.via === "direct" ? -1 : 1;
+      const sa = a.score ?? -Infinity;
+      const sb = b.score ?? -Infinity;
+      if (sa !== sb) return sb - sa;
+      return a.name.localeCompare(b.name);
+    })
+    .slice(0, limit);
+}
 
 // ── Lookups ──
 
@@ -931,6 +995,15 @@ export interface LatestRelease {
   /** AI-generated smart-brevity headline (#852, renamed in #860). */
   titleShort?: string | null;
   media: MediaItem[];
+  /**
+   * Cached release-body size — `LENGTH(content)` and `countTokensSafe(content)`
+   * snapshotted at ingest, so clients can advertise "this release is ~1.5K
+   * tokens" without round-tripping the body. Both fields are optional and
+   * nullable: pre-existing rows land null until the backfill script
+   * populates them. See #958.
+   */
+  contentChars?: number | null;
+  contentTokens?: number | null;
 }
 
 // ── Stats ──

package/src/schemas/orgs.ts

@@ -75,8 +75,11 @@ export const UpdateOrgBodySchema = z.object({
   domain: z.string().nullable().optional(),
   description: z.string().nullable().optional(),
   category: z.string().min(1).nullable().optional(),
+  avatarUrl: z.string().nullable().optional(),
   tags: z.array(z.string()).optional(),
   aliases: z.array(z.string()).optional(),
+  /** Admin-only: pause/unpause all ingest for this org without touching sources (#1057). */
+  fetchPaused: z.boolean().optional(),
 });
 
 // Org detail's products query selects a strict subset of `ProductListItem` —

package/src/schemas/releases.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
 import { SOURCE_TYPES } from "@buildinternet/releases-core/source-enums";
-import { MediaItemSchema, ReleaseTypeSchema } from "./shared.js";
+import { MediaItemSchema, ReleaseCompositionSchema, ReleaseTypeSchema } from "./shared.js";
+
+// ReleaseCompositionSchema lives in ./shared.js (single source of truth) — both
+// this file and ReleaseItemSchema reference it from there.
 
 /**
  * Per-row shape returned by `GET /v1/releases/latest`. Distinct from the
@@ -32,6 +35,11 @@ export const ReleaseLatestItemSchema = z.object({
   media: z.array(MediaItemSchema),
   source: ReleaseLatestSourceSchema,
   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.
+  contentChars: z.number().int().min(0).nullable().optional(),
+  contentTokens: z.number().int().min(0).nullable().optional(),
+  composition: ReleaseCompositionSchema.nullable().optional(),
 });
 
 export const ReleaseLatestResponseSchema = z.object({
@@ -151,6 +159,7 @@ export const ReleaseDetailResponseSchema = z.object({
   sourceSlug: z.string().nullable(),
   sourceType: z.enum(SOURCE_TYPES).nullable(),
   org: ReleaseDetailOrgSchema.nullable(),
+  composition: ReleaseCompositionSchema.nullable(),
 });
 
 /**
@@ -173,6 +182,8 @@ export const UpdateReleaseBodySchema = z
     summary: z.string().nullable().optional(),
     titleGenerated: z.string().nullable().optional(),
     titleShort: z.string().nullable().optional(),
+    // `null` removes `$.composition` from metadata; an object replaces it.
+    composition: ReleaseCompositionSchema.nullable().optional(),
   })
   .strict();
 

package/src/schemas/search.ts

@@ -80,6 +80,34 @@ export const SearchReleaseHitSchema = z.object({
   coverageCount: z.number().int().min(0).optional(),
 });
 
+/**
+ * Collection hit on the unified `/v1/search` response. Two origins are folded
+ * into the same wire shape via the `via` discriminator:
+ *
+ * - `direct`  — the collection itself matched (name/description via LIKE in
+ *               every mode, plus vector match in hybrid/semantic mode).
+ * - `member`  — the collection was surfaced because one of the orgs that
+ *               *did* match the query is a member of it; `matchedOrgSlugs`
+ *               carries the subset of result-set org slugs that triggered
+ *               the rollup so the UI can render an "includes X, Y" hint.
+ *
+ * `direct` rows always sort ahead of `member` rows; ties break on
+ * `score` then `memberCount`. Slugs are unique across the array — a
+ * direct hit that's also a member rollup keeps only the `direct` row
+ * with `matchedOrgSlugs` carried over.
+ */
+export const SearchCollectionHitSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  memberCount: z.number().int().min(0),
+  via: z.enum(["direct", "member"]),
+  /** Hybrid/semantic fusion score; absent on pure-lexical hits. */
+  score: z.number().optional(),
+  /** Result-set org slugs that triggered this rollup. Always present on `via=member`. */
+  matchedOrgSlugs: z.array(z.string()).optional(),
+});
+
 /**
  * Heading-aware CHANGELOG.md slice returned by hybrid / semantic search.
  * Clients can deep-link to
@@ -149,6 +177,13 @@ export const UnifiedSearchResponseSchema = z.object({
   catalog: z.array(SearchCatalogHitSchema),
   sources: z.array(SearchSourceHitSchema),
   releases: z.array(SearchReleaseHitSchema),
+  /**
+   * Curated collections matching the query, either directly (name/description
+   * match or vector hit) or via member rollup (one of the result orgs is in
+   * the collection). Optional on the wire so older workers mid-rollout don't
+   * trip the schema check; clients should treat missing and `[]` identically.
+   */
+  collections: z.array(SearchCollectionHitSchema).optional(),
   chunks: z.array(SearchChunkHitSchema).optional(),
   mode: z.enum(["lexical", "semantic", "hybrid"]).optional(),
   degraded: z.boolean().optional(),

package/src/schemas/shared.ts

@@ -29,6 +29,12 @@ export const ListResponseSchema = <T extends z.ZodTypeAny>(item: T) =>
 export const ErrorResponseSchema = z.object({
   error: z.string(),
   message: z.string(),
+  // Stable D1 error classification from `classifyDbError()` in
+  // `@releases/lib/db-errors`. Set on 5xx responses that originate from a
+  // classified D1 failure so callers can branch on a stable code instead of
+  // substring-matching the upstream message. Absent on non-D1 errors and on
+  // routes that have not yet been wired. See DbErrorCode in packages/lib.
+  errorCode: z.string().optional(),
 });
 
 export const StatsSchema = z.object({
@@ -40,6 +46,19 @@ export const StatsSchema = z.object({
 
 export const ReleaseTypeSchema = z.enum(RELEASE_TYPES);
 
+/**
+ * Per-category item counts produced by the AI release-content pass and
+ * persisted on `releases.metadata.composition`. Surfaces as a chip on the
+ * release detail UI ("12 fixes · 3 features"); `null` when the row hasn't
+ * been through the AI pass yet, the body was empty/boilerplate, or all
+ * three counts came back zero (we filter that case out on the parse side).
+ */
+export const ReleaseCompositionSchema = z.object({
+  bugs: z.number().int().min(0),
+  features: z.number().int().min(0),
+  enhancements: z.number().int().min(0),
+});
+
 export const ReleaseItemSchema = z.object({
   id: z.string().optional(),
   version: z.string().nullable(),
@@ -74,6 +93,19 @@ export const ReleaseItemSchema = z.object({
   // detail-page round trip. `.optional()` — older API responses and pinned
   // workers omit the field; treat undefined as 0.
   coverageCount: z.number().int().min(0).optional(),
+  // Cached `LENGTH(content)` and `countTokensSafe(content)` for the release
+  // body — lets feed surfaces ("releases get <org>", `/v1/releases/latest`,
+  // MCP `get_latest_releases`) advertise "this release is ~1.5K tokens" so
+  // agents can decide whether to pull the full body. `.optional()` and
+  // nullable because pre-existing rows landed without the columns; the
+  // backfill script populates them and renderers degrade to "size unknown"
+  // when null. See #958.
+  contentChars: z.number().int().min(0).nullable().optional(),
+  contentTokens: z.number().int().min(0).nullable().optional(),
+  // Per-category item counts produced by the AI release-content pass and
+  // stored on `releases.metadata.composition`. `null`/`undefined` when the
+  // row hasn't been through the AI pass yet or the body was boilerplate.
+  composition: ReleaseCompositionSchema.nullable().optional(),
 });
 
 export const ReleaseSummaryItemSchema = z.object({