@buildinternet/releases-api-types 0.59.0 → 0.60.0

package/src/schemas/releases.ts

@@ -1,449 +0,0 @@
-import { z } from "zod";
-import { SOURCE_TYPES } from "@buildinternet/releases-core/source-enums";
-import { BREAKING_LEVELS } from "@buildinternet/releases-core/breaking";
-import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import {
-  AppStoreSourceInfoSchema,
-  ImportanceScoreSchema,
-  MediaItemSchema,
-  ReleaseCompositionSchema,
-  ReleaseThumbnailSchema,
-  ReleaseTypeSchema,
-  VideoSourceInfoSchema,
-} 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
- * shared `ReleaseItemSchema` because the latest-feed handler joins the
- * source row in and exposes it as a nested `source` object instead of
- * leaving the caller to do a second lookup.
- *
- * `type` is required here — the latest handler reads it directly from
- * `releases.type` (NOT NULL with DB-default `'feature'`), so mid-deploy
- * degrade-gracefully nullability doesn't apply on this path.
- */
-export const ReleaseLatestSourceSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  type: z.enum(SOURCE_TYPES),
-  orgSlug: z.string().nullable(),
-  /** Owning org's display name (e.g. "Cloudflare"), distinct from the source
-   *  name. Null when the source has no org. Additive — older responses omit it. */
-  orgName: z.string().nullable().optional(),
-  /** Owning org's explicit avatar URL (`organizations.avatar_url`), when set.
-   *  Null/absent when the org has no stored avatar — clients fall back to the
-   *  GitHub handle below, then an initial. Additive — older responses omit it. */
-  orgAvatarUrl: z.string().nullable().optional(),
-  /** Owning org's GitHub handle, used to derive `github.com/<handle>.png` as the
-   *  avatar fallback when `orgAvatarUrl` is unset. Additive — older responses omit it. */
-  orgGithubHandle: z.string().nullable().optional(),
-  /** Source classification (`sdk`, `platform`, `docs`, …) from `sources.kind`.
-   *  Null when the source has no explicit kind — resolve against the product's
-   *  kind via `resolveSourceKind`. Additive — older responses omit it. Lets read
-   *  surfaces (e.g. the digest email) deprioritize/cluster SDK releases the way
-   *  the web sources table does. */
-  kind: z.enum(KIND_VALUES).nullable().optional(),
-});
-
-export const ReleaseLatestProductSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  /** Product classification from `products.kind`; the fallback `resolveSourceKind`
-   *  consults when the source itself has no kind. Additive — older responses omit it. */
-  kind: z.enum(KIND_VALUES).nullable().optional(),
-});
-
-export const ReleaseLatestItemSchema = z.object({
-  id: z.string(),
-  version: z.string().nullable(),
-  type: ReleaseTypeSchema,
-  title: z.string(),
-  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(),
-  importance: ImportanceScoreSchema,
-  publishedAt: z.string().nullable(),
-  /** Original source URL. Primary citation link; `webUrl` is the releases.sh copy. */
-  url: z.string().nullable(),
-  /**
-   * releases.sh detail-page URL (friendly form: ID + current title slug).
-   * Secondary to `url`. Additive — older servers and the digest-cron path omit it.
-   */
-  webUrl: z.string().optional(),
-  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(),
-  /**
-   * Server-resolved grouping identity — `product.slug ?? source.slug` /
-   * `product.name ?? source.name`. The web releases feed keys and labels
-   * SDK/package-cluster rollups on these instead of reconstructing
-   * `product ?? source` client-side; the digest email mirrors that. Optional on
-   * the wire: older workers omit them, so clients fall back to deriving from
-   * `product ?? source`. Never null when present (`source` is always set). #1234
-   */
-  groupSlug: z.string().optional(),
-  groupName: z.string().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.
-  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({
-  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(),
-  /** First image/gif thumbnail for the counterpart release; null when it has
-   * none. Optional so an older server that omits it still validates. */
-  thumbnail: ReleaseThumbnailSchema.nullable().optional(),
-});
-
-/**
- * Single row of the `release_coverage` join table. Drives the
- * 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(),
-  canonicalId: z.string(),
-  reason: z.string().nullable(),
-  decidedBy: z.string(),
-  decidedAt: z.string(),
-  sibling: ReleaseCoverageSiblingSchema.nullable().optional(),
-});
-
-/**
- * Discriminated by `role`:
- * - `standalone` — release is neither canonical nor coverage of anything.
- * - `coverage` — release is coverage rolling up to `canonical`.
- * - `canonical` — release is the canonical row; `covers` enumerates rollups.
- */
-export const ReleaseCoverageResponseSchema = z.discriminatedUnion("role", [
-  z.object({
-    role: z.literal("standalone"),
-    canonical: z.null(),
-    covers: z.array(z.never()).length(0),
-  }),
-  z.object({
-    role: z.literal("coverage"),
-    canonical: ReleaseCoverageRowSchema,
-    covers: z.array(z.never()).length(0),
-  }),
-  z.object({
-    role: z.literal("canonical"),
-    canonical: z.null(),
-    covers: z.array(ReleaseCoverageRowSchema),
-  }),
-]);
-
-/**
- * Body accepted by `POST /v1/releases/:id/coverage`. `decidedBy` MUST be
- * prefixed with `human:` or `agent:` so the audit trail records who linked
- * the rows; the handler enforces this with a regex.
- */
-export const LinkReleaseCoverageBodySchema = z.object({
-  coverageIds: z.array(z.string()).min(1),
-  reason: z.string().nullable().optional(),
-  decidedBy: z.string().regex(/^(human:|agent:)/),
-});
-
-export const LinkReleaseCoverageResponseSchema = z.object({
-  canonicalId: z.string(),
-  coverageIds: z.array(z.string()),
-  linked: z.number().int().min(0),
-});
-
-/**
- * Response for `DELETE /v1/releases/:id/coverage`. Idempotent — the handler
- * returns `{ unlinked: false }` when the release isn't in a cluster, so the
- * remote client can skip a brittle error-message sniff.
- */
-export const UnlinkReleaseCoverageResponseSchema = z.object({
-  unlinked: z.boolean(),
-});
-
-/**
- * Row returned by `GET /v1/releases?hasMedia=true`. Internal/admin escape
- * hatch consumed by the `media backfill` CLI command.
- */
-export const ReleaseWithMediaRowSchema = z.object({
-  id: z.string(),
-  sourceId: z.string(),
-  media: z.string().nullable(),
-});
-
-export const ReleasesWithMediaResponseSchema = z.array(ReleaseWithMediaRowSchema);
-
-/**
- * Nested org context joined into the `GET /v1/releases/:id` response.
- * Both fields are nullable — releases whose source has no org attached
- * return `null` for this object entirely.
- */
-export const ReleaseDetailOrgSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  /**
-   * Resolved org avatar URL (the `organizations.avatar_url` column). `null`
-   * when the org has no stored avatar. Additive — older servers omit it, so
-   * treat `undefined` as `null`. Mirrors the `orgAvatarUrl` field on the
-   * related-rail feed.
-   */
-  avatarUrl: z.string().nullable().optional(),
-  /**
-   * How the org was created. Additive — older servers omit it; treat
-   * `undefined` as `"curated"`. Used by the web to emit `noindex` on
-   * on-demand-materialized org pages.
-   */
-  discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
-  /**
-   * Whether the org is hidden from public listings. Additive — older servers
-   * omit it; treat `undefined` as `false`. Used by the web to emit `noindex`.
-   */
-  isHidden: z.boolean().optional(),
-});
-
-/**
- * Full release detail returned by `GET /v1/releases/:id`. Joins source
- * name/slug/type and a nullable org object; media is parsed from the raw
- * JSON stored in D1 and typed URLs are rewritten to the CDN origin. The
- * route only surfaces non-suppressed, non-coverage rows (filtered via the
- * `releases_visible` view).
- */
-export const ReleaseDetailResponseSchema = z.object({
-  id: z.string(),
-  sourceId: z.string(),
-  version: z.string().nullable(),
-  type: ReleaseTypeSchema,
-  title: z.string(),
-  content: z.string(),
-  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(),
-  importance: ImportanceScoreSchema,
-  /**
-   * 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(),
-  /** Original source URL. Primary citation link; `webUrl` is the releases.sh copy. */
-  url: z.string().nullable(),
-  /**
-   * releases.sh detail-page URL, `https://releases.sh/release/rel_<id>-<slug>`
-   * (immutable ID + current title slug). Secondary to `url`. Additive — older
-   * servers omit it.
-   */
-  webUrl: z.string().optional(),
-  contentHash: z.string().nullable(),
-  media: z.array(MediaItemSchema),
-  publishedAt: z.string().nullable(),
-  suppressed: z.boolean().nullable(),
-  suppressedReason: z.string().nullable(),
-  prerelease: z.boolean().nullable(),
-  fetchedAt: z.string().nullable(),
-  sourceName: z.string().nullable(),
-  sourceSlug: z.string().nullable(),
-  sourceType: z.enum(SOURCE_TYPES).nullable(),
-  org: ReleaseDetailOrgSchema.nullable(),
-  /**
-   * Owning product, when the release's source is grouped under a product
-   * (`sources.product_id`). `null` when the source has no product. Additive —
-   * older servers omit this field; treat `undefined` as `null`. Reuses the
-   * `{ slug, name }` shape from the latest feed.
-   */
-  product: ReleaseLatestProductSchema.nullable().optional(),
-  composition: ReleaseCompositionSchema.nullable(),
-  appStore: AppStoreSourceInfoSchema.nullable().optional(),
-  video: VideoSourceInfoSchema.nullable().optional(),
-  /**
-   * Whether the release's source is hidden from public listings. Additive —
-   * older servers omit it; treat `undefined` as `false`. Used by the web to
-   * emit `noindex` on pages whose source is an on-demand-materialized stub.
-   */
-  sourceIsHidden: z.boolean().optional(),
-});
-
-/**
- * Body accepted by `PATCH /v1/releases/:id`. All fields are optional;
- * omitted fields are not updated. The nullable string columns (`version`,
- * `url`, `publishedAt`, `contentHash`) accept a string or `null`. AI-generated
- * fields (`summary`, `titleGenerated`, `titleShort`) accept `null` to
- * explicitly clear the stored value. Non-whitelisted fields are rejected
- * via `.strict()` — the handler also re-runs the field-set check after
- * sanitization so an empty update payload still 400s.
- */
-/**
- * `error.details` on a 409 from `PATCH /v1/releases/:id` when the new `url`
- * collides with `UNIQUE(source_id, url)`. Additive: older servers omit `details`.
- */
-export const ReleaseUrlConflictDetailsSchema = z
-  .object({
-    releaseId: z
-      .string()
-      .describe("Id of the existing release that already stores this URL on the same source."),
-  })
-  .describe("Structured details for a release URL conflict (409).");
-
-export const UpdateReleaseBodySchema = z
-  .object({
-    title: z.string().optional(),
-    content: z.string().optional(),
-    version: z.string().nullable().optional(),
-    url: z.string().nullable().optional(),
-    publishedAt: z.string().nullable().optional(),
-    contentHash: z.string().nullable().optional(),
-    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(),
-    // Replace the release's stored `media[]` wholesale (curator manual edit).
-    // Items whose `url` is not already an R2/`media.releases.sh` origin are run
-    // through the ingest R2 mirror (`processMediaForR2`) so posters/images land
-    // in `released-media` and get `r2Key`/`r2Url` stamped — same path as ingest.
-    // Reuses the shared `MediaItemSchema` (type/url/alt/r2Url/r2Key/linkUrl).
-    media: z.array(MediaItemSchema).optional(),
-  })
-  .strict();
-
-/**
- * Response returned by `PATCH /v1/releases/:id`. The handler returns the raw
- * Drizzle row from the `releases` table — distinct from the augmented
- * `ReleaseDetailResponseSchema` shape served by `GET /v1/releases/:id`, which
- * adds joined source/org metadata and parses `media` from raw JSON. Clients
- * that need the augmented shape after an edit should re-fetch via GET.
- */
-export const ReleasePatchResponseSchema = z.object({
-  id: z.string(),
-  sourceId: z.string(),
-  version: z.string().nullable(),
-  type: ReleaseTypeSchema,
-  title: z.string(),
-  content: z.string(),
-  summary: z.string().nullable(),
-  titleGenerated: z.string().nullable(),
-  titleShort: z.string().nullable(),
-  url: z.string().nullable(),
-  contentHash: z.string().nullable(),
-  metadata: z.string().nullable(),
-  // Raw JSON string of the media array — not parsed at this endpoint.
-  media: z.string().nullable(),
-  publishedAt: z.string().nullable(),
-  prerelease: z.boolean().nullable(),
-  suppressed: z.boolean().nullable(),
-  suppressedReason: z.string().nullable(),
-  fetchedAt: z.string().nullable(),
-  embeddedAt: z.string().nullable(),
-});
-
-/** Response returned by `DELETE /v1/releases/:id`. */
-export const ReleaseDeleteResponseSchema = z.object({
-  deleted: z.literal(true),
-});
-
-/** Body accepted by `DELETE /v1/releases/batch`. */
-export const ReleaseBatchDeleteBodySchema = z.object({
-  releaseIds: z.array(z.string()).min(1),
-});
-
-/** Response returned by `DELETE /v1/releases/batch`. */
-export const ReleaseBatchDeleteResponseSchema = z.object({
-  deleted: z.number().int().min(0),
-});
-
-/**
- * Body accepted by `POST /v1/releases/batch-suppress`. When `suppressed` is
- * true the optional `reason` is stored in `suppressed_reason`; when false the
- * reason is cleared.
- */
-export const ReleaseBatchSuppressBodySchema = z.object({
-  releaseIds: z.array(z.string()).min(1),
-  suppressed: z.boolean(),
-  reason: z.string().optional(),
-});
-
-/** Response returned by `POST /v1/releases/batch-suppress`. */
-export const ReleaseBatchSuppressResponseSchema = z.object({
-  updated: z.number().int().min(0),
-});
-
-/** Response returned by `POST /v1/releases/:id/suppress`. */
-export const ReleaseSuppressResponseSchema = z.object({
-  suppressed: z.literal(true),
-});
-
-/** Response returned by `POST /v1/releases/:id/unsuppress`. */
-export const ReleaseUnsuppressResponseSchema = z.object({
-  unsuppressed: z.literal(true),
-});
-
-/**
- * Body accepted by `POST /v1/releases/:id/suppress`. The `reason` field
- * is optional; when omitted the stored `suppressed_reason` is set to null.
- */
-export const ReleaseSuppressBodySchema = z.object({
-  reason: z.string().optional(),
-});
-
-/**
- * WebSocket message schema for the `GET /v1/releases/stream` endpoint.
- * Each message is a JSON object with one of the following shapes:
- * - `{ type: "ready", seq: number }` — sent on connect to give the caller
- *   the current head sequence number for later resume.
- * - `{ type: "release.created", seq: number, release: object }` — a new
- *   release was indexed; `release` carries the full release row.
- * - `{ type: "snapshot_gap" }` — the requested `since` sequence fell
- *   behind the oldest buffered event; the client must REST-backfill.
- */
-export const ReleaseStreamMessageSchema = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("ready"), seq: z.number().int() }),
-  z.object({
-    type: z.literal("release.created"),
-    seq: z.number().int(),
-    release: z.record(z.string(), z.unknown()),
-  }),
-  z.object({ type: z.literal("snapshot_gap") }),
-]);