@buildinternet/releases-api-types 0.18.0 → 0.19.0

package/package.json

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

@@ -148,6 +148,7 @@ import type {
   SearchSourceHitSchema,
   SearchReleaseHitSchema,
   SearchChunkHitSchema,
+  SearchCollectionHitSchema,
   LookupResultPayloadSchema,
   UnifiedSearchResponseSchema,
 } from "./schemas/search.js";
@@ -367,6 +368,7 @@ export {
   SearchSourceHitSchema,
   SearchReleaseHitSchema,
   SearchChunkHitSchema,
+  SearchCollectionHitSchema,
   LookupResultPayloadSchema,
   UnifiedSearchResponseSchema,
 } from "./schemas/search.js";
@@ -676,6 +678,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 +990,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,6 +75,7 @@ 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(),
 });

package/src/schemas/releases.ts

@@ -32,6 +32,10 @@ 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(),
 });
 
 export const ReleaseLatestResponseSchema = z.object({

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({
@@ -74,6 +80,15 @@ 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(),
 });
 
 export const ReleaseSummaryItemSchema = z.object({