@buildinternet/releases-api-types 0.34.1 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@buildinternet/releases-core": "^0.24.0",
+    "@buildinternet/releases-core": "^0.25.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -18,7 +18,6 @@ import type {
   MediaItemSchema,
   PaginationSchema,
   StatsSchema,
-  ErrorResponseSchema,
   ReleaseTypeSchema,
   ReleaseCompositionSchema,
   ReleaseItemSchema,
@@ -258,7 +257,6 @@ export {
   PaginationSchema,
   ListResponseSchema,
   StatsSchema,
-  ErrorResponseSchema,
   ReleaseTypeSchema,
   ReleaseCompositionSchema,
   ReleaseItemSchema,
@@ -453,6 +451,8 @@ export {
   FeedbackDeleteResponseSchema,
 } from "./schemas/feedback.js";
 export { SitemapSourceSchema, SitemapPayloadSchema } from "./schemas/sitemap.js";
+export { errorEnvelopeSchema, decodeApiError, isApiError } from "./schemas/errors.js";
+export type { ErrorEnvelope, DecodedApiError } from "./schemas/errors.js";
 export {
   RelatedScopeSchema,
   RelatedReleaseThumbnailSchema,
@@ -554,8 +554,6 @@ export interface CreateUserApiKeyBody {
   expiresInDays?: number;
 }
 
-export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
-
 // ── Sitemap (bulk URL emission) ──
 
 export type SitemapSource = z.infer<typeof SitemapSourceSchema>;
@@ -820,6 +818,11 @@ export interface ReleaseDetail {
   /** Explicit upgrade/migration steps lifted from the body (#1696); null when the body gives none. */
   migrationNotes?: string | null;
   url: string | null;
+  /**
+   * Canonical releases.sh detail-page URL (friendly form: ID + current
+   * title slug). Additive — older servers omit it.
+   */
+  webUrl?: string;
   media: MediaItem[];
   publishedAt: string | null;
   fetchedAt: string;
@@ -1236,7 +1239,13 @@ export type UpdatePlaybookNotesResponse = z.infer<typeof UpdatePlaybookNotesResp
 // ── Overview Manifest (admin planning) ──
 
 export type OverviewStaleness = "missing" | "behind" | "fresh";
-export type OverviewPlanAction = "missing" | "refresh" | "skip";
+/**
+ * `opted_out` — the org has `autoGenerateContent=false`, so the overview-regen
+ * eligibility filter skips it regardless of staleness. Surfaced so an
+ * orchestrator planning a sweep doesn't queue a regen that will never run
+ * (#1795).
+ */
+export type OverviewPlanAction = "missing" | "refresh" | "skip" | "opted_out";
 
 /**
  * Per-org row returned by GET /v1/admin/overviews. Designed for orchestrators
@@ -1255,6 +1264,12 @@ export interface OverviewManifestRow {
   releasesSinceOverview: number;
   recentReleaseCount: number;
   staleness: OverviewStaleness;
+  /**
+   * Whether the org is opted into automatic AI content. When `false`, the
+   * overview-regen cron skips it — the staleness signal alone is
+   * misleading without this (#1795). Older workers may omit it mid-deploy.
+   */
+  autoGenerateContent?: boolean;
   /** Only populated when ?format=plan. */
   action?: OverviewPlanAction;
   /** Only populated when ?format=plan. */
@@ -1582,14 +1597,16 @@ export interface Session {
    * Sub-agent **role** label that ran this session — `"coordinator"` is the
    * parent orchestrator (typically Sonnet) when a multi-agent session
    * delegates, `"sonnet"` / `"haiku"` are direct single-agent runs.
-   * Surfaces on the detail GET.
+   * `"deterministic"` marks the #1878/#1881 update path that skips the
+   * Managed-Agents (Haiku) session entirely — no Anthropic session runs, so
+   * it must never be reported as `"haiku"`. Surfaces on the detail GET.
    *
    * This is a logical role label, not the runtime model identifier. The
-   * resolved Anthropic model string (e.g. `claude-sonnet-4-6`,
+   * resolved Anthropic model string (e.g. `claude-sonnet-5`,
    * `claude-haiku-4-5`) lives on `usage.model` when the session reported
    * one — consult that field for the concrete model.
    */
-  agent?: "sonnet" | "haiku" | "coordinator";
+  agent?: "sonnet" | "haiku" | "coordinator" | "deterministic";
   /** Identifies the client that started this session (e.g. hostname). */
   runner?: string;
   /** Correlation ID for end-to-end tracing across CLI → API → managed agent. */

package/src/schemas/errors.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import { ERROR_TYPES } from "@buildinternet/releases-core/errors";
+import { errorEnvelopeSchema, decodeApiError, isApiError } from "./errors";
+
+test("a valid envelope parses", () => {
+  const ok = errorEnvelopeSchema.safeParse({
+    error: { code: "not_found", type: "not_found", message: "Nope" },
+  });
+  expect(ok.success).toBe(true);
+});
+
+test("malformed envelopes reject", () => {
+  expect(errorEnvelopeSchema.safeParse({}).success).toBe(false);
+  expect(
+    errorEnvelopeSchema.safeParse({
+      error: { code: 1, type: "not_found", message: "x" },
+    }).success,
+  ).toBe(false);
+});
+
+test("schema type enum matches the core union (anti-drift invariant 2)", () => {
+  const options = errorEnvelopeSchema.shape.error.shape.type.options;
+  expect([...options].sort()).toEqual([...ERROR_TYPES].sort());
+});
+
+test("decodeApiError normalizes an unknown type to internal, preserves unknown code", () => {
+  const decoded = decodeApiError({
+    error: { code: "brand_new_code", type: "teapot", message: "?" },
+  });
+  expect(decoded.type).toBe("internal");
+  expect(decoded.code).toBe("brand_new_code");
+});
+
+test("decodeApiError degrades a malformed body without throwing", () => {
+  expect(decodeApiError(null)).toEqual({
+    code: "internal_error",
+    type: "internal",
+    message: "Unknown error",
+  });
+});
+
+test("decodeApiError carries details through when present", () => {
+  const decoded = decodeApiError({
+    error: { code: "not_found", type: "not_found", message: "x", details: { id: "src_1" } },
+  });
+  expect(decoded.details).toEqual({ id: "src_1" });
+});
+
+test("isApiError matches shape and optional code", () => {
+  const body = { error: { code: "not_found", type: "not_found", message: "x" } };
+  expect(isApiError(body)).toBe(true);
+  expect(isApiError(body, "not_found")).toBe(true);
+  expect(isApiError(body, "conflict")).toBe(false);
+  expect(isApiError({ nope: true })).toBe(false);
+});

package/src/schemas/errors.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { ERROR_TYPES, type ErrorType, type ErrorCode } from "@buildinternet/releases-core/errors";
+
+/**
+ * The one on-the-wire error shape. `type` is constrained (documents the
+ * contract, powers OpenAPI); `code` is an open string so a new server code an
+ * older client doesn't recognize still parses. The throwable hierarchy in
+ * `@releases/lib/releases-error` serializes to this via `toWire()`.
+ */
+export const errorEnvelopeSchema = z
+  .object({
+    error: z.object({
+      code: z
+        .string()
+        .describe(
+          "Stable, specific machine code (e.g. `not_found`, `rate_limited`). Never reworded once shipped, but open-ended — branch defensively on codes you don't recognize.",
+        ),
+      type: z
+        .enum(ERROR_TYPES)
+        .describe(
+          "Coarse category from a fixed set; determines the HTTP status. Safe to switch on.",
+        ),
+      message: z.string().describe("Human-readable explanation. May change; do not parse."),
+      details: z
+        .unknown()
+        .optional()
+        .describe(
+          "Optional structured context carried by select codes (e.g. `database_not_initialized`).",
+        ),
+    }),
+  })
+  .describe(
+    "Standardized error response — every non-2xx response uses this shape. Switch on `error.type` (fixed set → HTTP status) or match `error.code` (specific, stable). See https://releases.sh/docs/api/errors.",
+  );
+
+export type ErrorEnvelope = z.infer<typeof errorEnvelopeSchema>;
+
+/**
+ * Lenient variant used ONLY for decode: `type` is left open so an unknown
+ * category (older client, newer server) does not reject.
+ */
+const lenientEnvelopeSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    type: z.string(),
+    message: z.string(),
+    details: z.unknown().optional(),
+  }),
+});
+
+export interface DecodedApiError {
+  code: string;
+  type: ErrorType;
+  message: string;
+  details?: unknown;
+}
+
+/**
+ * Parse an API error body into a typed, normalized shape. Forward-compatible: a
+ * malformed body or an unknown `type` degrades to `internal` and never throws.
+ */
+export function decodeApiError(body: unknown): DecodedApiError {
+  const parsed = lenientEnvelopeSchema.safeParse(body);
+  if (!parsed.success) {
+    return { code: "internal_error", type: "internal", message: "Unknown error" };
+  }
+  const { code, type, message, details } = parsed.data.error;
+  const normalizedType: ErrorType = (ERROR_TYPES as readonly string[]).includes(type)
+    ? (type as ErrorType)
+    : "internal";
+  return details === undefined
+    ? { code, type: normalizedType, message }
+    : { code, type: normalizedType, message, details };
+}
+
+/** True if `body` is an API error envelope; if `code` is given, also matches it. */
+export function isApiError(body: unknown, code?: ErrorCode): boolean {
+  const parsed = lenientEnvelopeSchema.safeParse(body);
+  if (!parsed.success) return false;
+  return code === undefined || parsed.data.error.code === code;
+}

package/src/schemas/orgs.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
+import { BREAKING_LEVELS } from "@buildinternet/releases-core/breaking";
 import {
   AppStoreSourceInfoSchema,
   CategorySchema,
@@ -89,6 +90,14 @@ export const CreateOrgBodySchema = z.object({
   description: z.string().optional(),
   category: z.string().min(1).optional(),
   tags: z.array(z.string()).optional(),
+  /**
+   * Admin-only: opt the new org into automatic AI content (overviews +
+   * per-release summaries). Omitted → defaults to `true` server-side, since
+   * `POST /v1/orgs` only ever mints `curated` orgs and onboarding into the
+   * registry should mean it gets overviews. Pass `false` for a deliberate
+   * opt-out (#1795).
+   */
+  autoGenerateContent: z.boolean().optional(),
 });
 
 /**
@@ -111,6 +120,13 @@ export const UpdateOrgBodySchema = z.object({
   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(),
+  /**
+   * Admin-only: manual override for the automated overview-regen cadence in
+   * days (#1895). `null` clears back to automatic (velocity-tiered: 7d
+   * default, 2d at high release velocity). A set value pins the cadence in
+   * either direction — faster for a hot org, slower for a bursty one.
+   */
+  overviewCadenceDays: z.number().int().min(1).max(90).nullable().optional(),
   /** Admin-only: promote this org on the home-page featured rail. */
   featured: z.boolean().optional(),
   /** Admin-only: promote or demote the org's discovery status (curated/agent/on_demand). */
@@ -416,6 +432,12 @@ export const OrgRecentReleaseItemSchema = z.object({
   summary: z.string().nullable(),
   titleGenerated: z.string().nullable().optional(),
   titleShort: z.string().nullable().optional(),
+  /**
+   * Machine-readable breaking-change level (#1696, surfaced on read paths in
+   * #1710). `.optional()` for mid-deploy tolerance; absent or `"unknown"`
+   * means not classified. List paths carry `breaking` only.
+   */
+  breaking: z.enum(BREAKING_LEVELS).optional(),
   url: z.string().nullable(),
   contentHash: z.string().nullable(),
   metadata: z.string().nullable(),
@@ -450,6 +472,8 @@ export const OrgDetailSchema = z.object({
   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(),
+  /** Manual overview-regen cadence override in days (#1895); null = automatic velocity tier. Optional on the wire for older workers mid-deploy. */
+  overviewCadenceDays: z.number().int().nullable().optional(),
   /** Admin display flag: org is promoted on the home-page featured rail. Optional on the wire for older workers mid-deploy. */
   featured: z.boolean().optional(),
   /** Admin display flag: all ingest paused for this org. */

package/src/schemas/releases.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { SOURCE_TYPES } from "@buildinternet/releases-core/source-enums";
+import { BREAKING_LEVELS } from "@buildinternet/releases-core/breaking";
 import {
   AppStoreSourceInfoSchema,
   MediaItemSchema,
@@ -51,8 +52,21 @@ export const ReleaseLatestItemSchema = z.object({
   summary: z.string().nullable(),
   titleGenerated: z.string().nullable(),
   titleShort: z.string().nullable(),
+  /**
+   * Machine-readable breaking-change level (#1696, surfaced on read paths in
+   * #1710). `.optional()` for mid-deploy / pinned-worker tolerance and because
+   * rows predating the column omit it; absent or `"unknown"` means not
+   * classified (the fail-open default). List paths carry `breaking` only —
+   * `migrationNotes` stays detail-route-only to keep list payloads slim.
+   */
+  breaking: z.enum(BREAKING_LEVELS).optional(),
   publishedAt: z.string().nullable(),
   url: z.string().nullable(),
+  /**
+   * Canonical releases.sh detail-page URL (friendly form: ID + current
+   * title slug). Additive — older servers and the digest-cron path omit it.
+   */
+  webUrl: z.string().optional(),
   media: z.array(MediaItemSchema),
   source: ReleaseLatestSourceSchema,
   /**
@@ -215,7 +229,26 @@ export const ReleaseDetailResponseSchema = z.object({
   summary: z.string().nullable(),
   titleGenerated: z.string().nullable(),
   titleShort: z.string().nullable(),
+  /**
+   * Machine-readable breaking-change level (#1696, surfaced on read paths in
+   * #1710). `.optional()` — rows predating the column omit it; absent or
+   * `"unknown"` means not classified (the fail-open default). Mirrors
+   * `ReleaseDetail.breaking` in api-types.ts.
+   */
+  breaking: z.enum(BREAKING_LEVELS).optional(),
+  /**
+   * Explicit upgrade/migration steps lifted from the body (#1696); omitted
+   * when the body gives none. Detail-route-only — list paths never carry it.
+   */
+  migrationNotes: z.string().nullable().optional(),
   url: z.string().nullable(),
+  /**
+   * Canonical releases.sh detail-page URL, `https://releases.sh/release/
+   * rel_<id>-<slug>` (Zendesk-style: immutable ID + current title slug;
+   * the slug follows title regeneration, the ID keeps old links alive).
+   * Additive — older servers omit it.
+   */
+  webUrl: z.string().optional(),
   contentHash: z.string().nullable(),
   media: z.array(MediaItemSchema),
   publishedAt: z.string().nullable(),

package/src/schemas/shared.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { RELEASE_TYPES } from "@buildinternet/releases-core/schema";
+import { BREAKING_LEVELS } from "@buildinternet/releases-core/breaking";
 import { CATEGORIES } from "@buildinternet/releases-core/categories";
 import { isValidNoticeCoordinate } from "@buildinternet/releases-core/notice";
 
@@ -58,17 +59,6 @@ export const ListResponseSchema = <T extends z.ZodTypeAny>(item: T) =>
     pagination: PaginationSchema,
   });
 
-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({
   orgs: z.number().int().min(0),
   sources: z.number().int().min(0),
@@ -120,6 +110,12 @@ export const ReleaseItemSchema = z.object({
   // `.optional()` for the same mid-deploy / pinned-worker reason as `type`.
   titleGenerated: z.string().nullable().optional(),
   titleShort: z.string().nullable().optional(),
+  // Machine-readable breaking-change level (#1696, surfaced on read paths in
+  // #1710). `.optional()` for mid-deploy / pinned-worker tolerance and because
+  // rows predating the column omit it; absent or `"unknown"` means not
+  // classified (the fail-open default). List paths carry `breaking` only —
+  // `migrationNotes` stays detail-route-only to keep list payloads slim.
+  breaking: z.enum(BREAKING_LEVELS).optional(),
   // Count of demoted siblings rolling up into this row via `release_coverage`
   // (0 when standalone). Lets list views show a cluster indicator without a
   // detail-page round trip. `.optional()` — older API responses and pinned

package/src/schemas/well-known.test.ts

@@ -9,6 +9,7 @@ describe("ReleasesJsonConfigSchema", () => {
   it("accepts a full org-scope file", () => {
     const r = ReleasesJsonConfigSchema.safeParse({
       $schema: "https://releases.sh/schemas/releases.json",
+      version: 1,
       name: "Acme",
       description: "CI for teams.",
       category: "developer-tools",
@@ -48,6 +49,16 @@ describe("ReleasesJsonConfigSchema", () => {
     expect(r.success).toBe(false);
   });
 
+  it("accepts an integer version", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 1, name: "Acme" }).success).toBe(true);
+  });
+
+  it("rejects a zero, negative, or non-integer version", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 0 }).success).toBe(false);
+    expect(ReleasesJsonConfigSchema.safeParse({ version: -1 }).success).toBe(false);
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 1.5 }).success).toBe(false);
+  });
+
   it("strips unknown top-level keys", () => {
     const r = ReleasesJsonConfigSchema.parse({ name: "Acme", bogus: 1 });
     expect("bogus" in r).toBe(false);

package/src/schemas/well-known.ts

@@ -26,6 +26,11 @@ export const ReleasesJsonProductSchema = z
 export const ReleasesJsonConfigSchema = z
   .object({
     $schema: z.url().optional(),
+    // Manifest format version. Currently 1; optional — a missing value is read as
+    // v1. Bumped only on a breaking change to this file's shape, so a consumer can
+    // branch on it without fetching the JSON Schema. Lenient/fail-open: the
+    // reconciler ignores it entirely, so an unexpected value never fails the sync.
+    version: z.number().int().positive().max(1000).optional(),
     // Org scope
     name: z.string().min(1).max(120).optional(),
     description: z.string().max(2000).optional(),