@buildinternet/releases-api-types 0.15.0 → 0.17.0

package/src/schemas/overviews.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { OverviewPageItemSchema, OverviewCitationSchema } from "./shared.js";
+
+/**
+ * Response shape returned by `GET /v1/orgs/:slug/overview` — the org-scoped
+ * knowledge page with inline citations, or `null` when no overview has been
+ * generated yet.
+ */
+export const OrgOverviewResponseSchema = OverviewPageItemSchema.extend({
+  citations: z.array(OverviewCitationSchema).optional(),
+}).nullable();
+
+/**
+ * Incoming citation row attached to `POST /v1/orgs/:slug/overview`. Slimmer
+ * than the read-side `OverviewCitationSchema` because the wire shape doesn't
+ * carry `releaseId` — that's resolved server-side from `sourceUrl`. Spans
+ * must be in-range (`endIndex > startIndex`); the cross-field
+ * `endIndex <= content.length` check stays in the handler.
+ */
+export const IncomingOverviewCitationSchema = z
+  .object({
+    startIndex: z.number().int().min(0),
+    endIndex: z.number().int().min(1),
+    sourceUrl: z.string().min(1),
+    title: z.string().nullable().optional(),
+    citedText: z.string().min(1),
+  })
+  .refine((c) => c.endIndex > c.startIndex, {
+    message: "endIndex must be > startIndex",
+  });
+
+/**
+ * Body accepted by `POST /v1/orgs/:slug/overview` — the agent-authored
+ * markdown content, the release count it was derived from, the timestamp of
+ * the most-recent contributing release, and optional inline citations.
+ *
+ * `content` is non-empty. `releaseCount` is a finite non-negative integer.
+ * `citations` is an array of `IncomingOverviewCitation`; the handler still
+ * cross-checks `endIndex <= content.length` since that bound is content-aware.
+ */
+export const RegenerateOverviewBodySchema = z.object({
+  content: z.string().min(1),
+  releaseCount: z.number().int().min(0),
+  lastContributingReleaseAt: z.string().nullable().optional(),
+  citations: z.array(IncomingOverviewCitationSchema).optional(),
+});
+
+/** Response returned by `POST /v1/orgs/:slug/overview` on success. */
+export const RegenerateOverviewResponseSchema = z.object({
+  ok: z.literal(true),
+  citations: z.number().int().min(0),
+});
+
+/**
+ * Response shape returned by `GET /v1/products/:slug/overview` — the
+ * product-scoped knowledge page, or `null` when no overview exists.
+ * Does not include inline citations (products overview does not store them).
+ */
+export const ProductOverviewResponseSchema = OverviewPageItemSchema.nullable();
+
+/**
+ * Pre-flight payload returned by `GET /v1/orgs/:slug/overview/inputs?check=true`.
+ * Lets an orchestrator decide whether to dispatch a per-org sub-agent without
+ * paying for the full release-content hydration.
+ */
+export const OverviewInputsCheckResponseSchema = z.object({
+  orgSlug: z.string(),
+  selected: z.number().int().min(0),
+  totalAvailable: z.number().int().min(0),
+  hasExistingContent: z.boolean(),
+  wouldRegenerate: z.boolean(),
+  windowDays: z.number().int().min(1),
+});
+
+/**
+ * Full inputs payload returned by `GET /v1/orgs/:slug/overview/inputs` (without
+ * `?check=true`). Contains org metadata, active sources, the existing overview
+ * content if any, and the selected hydrated releases ready for the AI model.
+ *
+ * Typed loosely because the release shape includes hydrated media URLs that
+ * differ slightly from `ReleaseItem` — this avoids tight coupling to internal
+ * fields while still surfacing the discriminating top-level structure.
+ */
+export const OverviewInputsFullResponseSchema = z.object({
+  org: z.object({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    discovery: z.string(),
+  }),
+  sources: z.array(
+    z.object({
+      id: z.string(),
+      slug: z.string(),
+      name: z.string(),
+      type: z.string(),
+    }),
+  ),
+  existingContent: z.string().nullable(),
+  selected: z.array(z.unknown()),
+  totalAvailable: z.number().int().min(0),
+  windowDays: z.number().int().min(1),
+});
+
+/**
+ * Union of the two shapes `GET /v1/orgs/:slug/overview/inputs` can return.
+ * The pre-flight (`?check=true`) variant skips content hydration; the full
+ * variant carries org metadata + sources + selected releases. Single response
+ * entry — Zod union so OpenAPI emits one schema with the variants inlined.
+ */
+export const OverviewInputsResponseSchema = z.union([
+  OverviewInputsCheckResponseSchema,
+  OverviewInputsFullResponseSchema,
+]);
+
+/**
+ * Response returned by `GET /v1/orgs/:slug/playbook` — the playbook knowledge
+ * page (scope `"playbook"`), or `null` when no playbook exists for the org.
+ *
+ * The playbook `content` field holds a deterministic markdown header generated
+ * by `generatePlaybookHeader()` from `@releases/ai-internal/playbook`.
+ */
+export const PlaybookResponseSchema = OverviewPageItemSchema.extend({
+  scope: z.literal("playbook"),
+  notes: z.string().nullable().optional(),
+}).nullable();
+
+/** Body accepted by `PATCH /v1/orgs/:slug/playbook/notes`. */
+export const UpdatePlaybookNotesBodySchema = z.object({
+  notes: z.string(),
+});
+
+/** Response returned by `PATCH /v1/orgs/:slug/playbook/notes` on success. */
+export const UpdatePlaybookNotesResponseSchema = z.object({
+  ok: z.literal(true),
+  notes: z.string().nullable(),
+});

package/src/schemas/products.ts

@@ -66,7 +66,14 @@ export const ProductDetailSchema = ProductRowSchema.extend({
   aliases: z.array(z.string()),
 });
 
-/** Body accepted by `POST /v1/products`. */
+/**
+ * Body accepted by `POST /v1/products`. `category` is a non-empty string at
+ * the wire boundary so callers can pass either a canonical slug or one of
+ * its configured aliases (resolved server-side via `resolveCategoryInput`).
+ * Responses always carry the canonical slug. Empty strings are rejected so
+ * the truthy-guard around `resolveCategoryInput` in the handler can't be
+ * bypassed into persisting an invalid `""` value.
+ */
 export const CreateProductBodySchema = z.object({
   name: z.string().min(1),
   orgId: z.string().optional(),
@@ -74,16 +81,20 @@ export const CreateProductBodySchema = z.object({
   slug: z.string().optional(),
   url: z.string().optional(),
   description: z.string().optional(),
-  category: CategorySchema.optional(),
+  category: z.string().min(1).optional(),
   tags: z.array(z.string()).optional(),
 });
 
-/** Body accepted by `PATCH /v1/products/:slug`. */
+/**
+ * Body accepted by `PATCH /v1/products/:slug`. Same alias-allowed string rule
+ * as create, plus `null` to explicitly clear the overlay. Empty strings stay
+ * rejected so callers must pick between a slug/alias or `null`.
+ */
 export const UpdateProductBodySchema = z.object({
   name: z.string().optional(),
   url: z.string().nullable().optional(),
   description: z.string().nullable().optional(),
-  category: CategorySchema.nullable().optional(),
+  category: z.string().min(1).nullable().optional(),
   tags: z.array(z.string()).optional(),
   aliases: z.array(z.string()).optional(),
 });
@@ -144,3 +155,20 @@ export const ProductDeleteResponseSchema = z.object({
   hard: z.literal(true).optional(),
   deletedAt: z.string().optional(),
 });
+
+/**
+ * Tag list returned by `GET /v1/products/:identifier/tags`. Tag names are
+ * sorted alphabetically; the empty array is returned when the product has
+ * no tags rather than 404.
+ */
+export const ProductTagsListResponseSchema = z.array(z.string());
+
+/** Body accepted by `PUT` and `DELETE` `/v1/products/:identifier/tags`. */
+export const ProductTagsBodySchema = z.object({
+  tags: z.array(z.string()),
+});
+
+/** Response shape returned by `PUT` and `DELETE` `/v1/products/:identifier/tags`. */
+export const ProductTagsMutationResponseSchema = z.object({
+  ok: z.literal(true),
+});

package/src/schemas/related.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+
+/**
+ * Anchor scope for related-* lookups. `org` filters the Vectorize query by
+ * the anchor's org id; `global` (default) runs unscoped.
+ */
+export const RelatedScopeSchema = z.enum(["org", "global"]);
+
+/** Thumbnail picked from the release's first image-like media entry. */
+export const RelatedReleaseThumbnailSchema = z.object({
+  url: z.string(),
+  alt: z.string().optional(),
+});
+
+/** Owning source rollup attached to each related-release row. */
+export const RelatedReleaseSourceSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  orgSlug: z.string().nullable(),
+  orgName: z.string().nullable(),
+});
+
+/**
+ * One neighbor returned by `GET /v1/related/releases`. `score` is the
+ * Vectorize cosine similarity from the underlying query.
+ */
+export const RelatedReleaseItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  version: z.string().nullable(),
+  url: z.string().nullable(),
+  publishedAt: z.string().nullable(),
+  summary: z.string(),
+  titleGenerated: z.string().nullable(),
+  titleShort: z.string().nullable(),
+  thumbnail: RelatedReleaseThumbnailSchema.nullable(),
+  score: z.number(),
+  source: RelatedReleaseSourceSchema,
+});
+
+/**
+ * One neighbor returned by `GET /v1/related/sources`. Carries enough
+ * source + org + recent-release stats for the rail card to render without
+ * a follow-up request.
+ */
+export const RelatedSourceItemSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: z.string(),
+  url: z.string().nullable(),
+  score: z.number(),
+  orgSlug: z.string().nullable(),
+  orgName: z.string().nullable(),
+  orgAvatarUrl: z.string().nullable(),
+  releaseCount: z.number().int().min(0),
+  latestDate: z.string().nullable(),
+  latestTitle: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+  /** Total releases published in the last 30 days (includes the latest). */
+  recentCount: z.number().int().min(0),
+});
+
+/**
+ * Successful response from `GET /v1/related/releases`. The handler returns
+ * `{scope, items}` when Vectorize is reachable and the anchor has a vector.
+ */
+export const RelatedReleasesOkResponseSchema = z.object({
+  scope: RelatedScopeSchema,
+  items: z.array(RelatedReleaseItemSchema),
+});
+
+/**
+ * Degraded response from `GET /v1/related/releases`. Returned (HTTP 200) when
+ * Vectorize bindings are missing, the anchor hasn't been embedded yet, or a
+ * downstream call errored. Callers render nothing in this case rather than
+ * surfacing a hard failure. `degradedReason` is human-readable, not stable.
+ */
+export const RelatedReleasesDegradedResponseSchema = z.object({
+  degraded: z.literal(true),
+  degradedReason: z.string(),
+  items: z.array(RelatedReleaseItemSchema),
+});
+
+export const RelatedReleasesResponseSchema = z.union([
+  RelatedReleasesOkResponseSchema,
+  RelatedReleasesDegradedResponseSchema,
+]);
+
+/** Successful response from `GET /v1/related/sources`. */
+export const RelatedSourcesOkResponseSchema = z.object({
+  scope: RelatedScopeSchema,
+  items: z.array(RelatedSourceItemSchema),
+});
+
+/** Degraded response from `GET /v1/related/sources`. Same semantics as the releases variant. */
+export const RelatedSourcesDegradedResponseSchema = z.object({
+  degraded: z.literal(true),
+  degradedReason: z.string(),
+  items: z.array(RelatedSourceItemSchema),
+});
+
+export const RelatedSourcesResponseSchema = z.union([
+  RelatedSourcesOkResponseSchema,
+  RelatedSourcesDegradedResponseSchema,
+]);

package/src/schemas/releases.ts

@@ -0,0 +1,249 @@
+import { z } from "zod";
+import { SOURCE_TYPES } from "@buildinternet/releases-core/source-enums";
+import { MediaItemSchema, ReleaseTypeSchema } from "./shared.js";
+
+/**
+ * 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(),
+});
+
+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(),
+  publishedAt: z.string().nullable(),
+  url: z.string().nullable(),
+  media: z.array(MediaItemSchema),
+  source: ReleaseLatestSourceSchema,
+});
+
+export const ReleaseLatestResponseSchema = z.object({
+  releases: z.array(ReleaseLatestItemSchema),
+});
+
+/**
+ * Single row of the `release_coverage` join table. Drives the
+ * GET /releases/:id/coverage response.
+ */
+export const ReleaseCoverageRowSchema = z.object({
+  coverageId: z.string(),
+  canonicalId: z.string(),
+  reason: z.string().nullable(),
+  decidedBy: z.string(),
+  decidedAt: z.string(),
+});
+
+/**
+ * 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(),
+});
+
+/**
+ * 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(),
+  url: z.string().nullable(),
+  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(),
+});
+
+/**
+ * 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.
+ */
+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(),
+  })
+  .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),
+});
+
+/** 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") }),
+]);