@buildinternet/releases-api-types 0.58.3 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.58.3",
+  "version": "0.59.0",
   "description": "Wire protocol — request/response types for the Releases Index API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -10,7 +10,8 @@
     "directory": "packages/api-types"
   },
   "exports": {
-    ".": "./src/api-types.ts"
+    ".": "./src/api-types.ts",
+    "./datasets": "./src/schemas/datasets.ts"
   },
   "files": [
     "src",

package/src/api-types.ts

@@ -161,6 +161,7 @@ import type {
   ReleasesWithMediaResponseSchema,
   ReleaseDetailOrgSchema,
   ReleaseDetailResponseSchema,
+  ReleaseUrlConflictDetailsSchema,
   UpdateReleaseBodySchema,
   ReleasePatchResponseSchema,
   ReleaseDeleteResponseSchema,
@@ -555,6 +556,7 @@ export {
   ReleasesWithMediaResponseSchema,
   ReleaseDetailOrgSchema,
   ReleaseDetailResponseSchema,
+  ReleaseUrlConflictDetailsSchema,
   UpdateReleaseBodySchema,
   ReleasePatchResponseSchema,
   ReleaseDeleteResponseSchema,
@@ -997,11 +999,11 @@ export interface WhatsChangedEntry {
   summary: string | null;
   breaking: BreakingLevel;
   migrationNotes: string | null;
+  /** Original source URL. Primary citation link; prefer this over `webUrl`. */
   url: string | null;
   /**
-   * Absolute canonical web URL — the slugged `/release/<id>-<slug>` form
-   * (#1906), built from `WEB_BASE_URL`. Distinct from `url` (the upstream
-   * source URL); lets an upgrade-planning agent link the release detail page.
+   * releases.sh detail page — the slugged `/release/<id>-<slug>` form (#1906),
+   * built from `WEB_BASE_URL`. Secondary to `url` (the original source).
    */
   webUrl: string | null;
 }
@@ -1061,10 +1063,11 @@ export interface ReleaseDetail {
    * scored. Additive — older servers omit it.
    */
   importance?: number | null;
+  /** Original source URL. Primary citation link; `webUrl` is the releases.sh copy. */
   url: string | null;
   /**
-   * Canonical releases.sh detail-page URL (friendly form: ID + current
-   * title slug). Additive — older servers omit it.
+   * releases.sh detail-page URL (friendly form: ID + current title slug).
+   * Secondary to `url`. Additive — older servers omit it.
    */
   webUrl?: string;
   media: MediaItem[];
@@ -1124,6 +1127,7 @@ export type ReleasesWithMediaResponse = z.infer<typeof ReleasesWithMediaResponse
 
 export type ReleaseDetailOrg = z.infer<typeof ReleaseDetailOrgSchema>;
 export type ReleaseDetailResponse = z.infer<typeof ReleaseDetailResponseSchema>;
+export type ReleaseUrlConflictDetails = z.infer<typeof ReleaseUrlConflictDetailsSchema>;
 export type UpdateReleaseBody = z.infer<typeof UpdateReleaseBodySchema>;
 export type ReleasePatchResponse = z.infer<typeof ReleasePatchResponseSchema>;
 export type ReleaseDeleteResponse = z.infer<typeof ReleaseDeleteResponseSchema>;
@@ -2221,3 +2225,5 @@ export interface TokenIdentity {
   expiresAt?: string | null;
   lastUsedAt?: string | null;
 }
+
+export * from "./schemas/datasets.js";

package/src/schemas/datasets.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+
+export const DatasetDescriptionSchema = z.object({
+  name: z.string().trim().min(1).max(200),
+  description: z.string().trim().min(50).max(5000),
+});
+
+/** Stored under source.metadata.dataset. Null removes the override. */
+export const SourceDatasetSettingsSchema = DatasetDescriptionSchema.partial()
+  .extend({
+    enabled: z.boolean().optional(),
+  })
+  .strict();
+export type SourceDatasetSettings = z.infer<typeof SourceDatasetSettingsSchema>;
+export type DatasetDescription = z.infer<typeof DatasetDescriptionSchema>;
+export interface AdminDatasetSource {
+  id: string;
+  slug: string;
+  name: string;
+  orgSlug: string | null;
+  orgName: string | null;
+  defaultEnabled: boolean;
+  settings: SourceDatasetSettings | null;
+  effective: DatasetDescription | null;
+  blockedReasons: string[];
+}
+export interface AdminDatasetsResponse {
+  sources: AdminDatasetSource[];
+  pagination: { page: number; limit: number; hasMore: boolean };
+  query: string;
+}

package/src/schemas/releases.ts

@@ -74,10 +74,11 @@ export const ReleaseLatestItemSchema = z.object({
   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(),
   /**
-   * Canonical releases.sh detail-page URL (friendly form: ID + current
-   * title slug). Additive — older servers and the digest-cron path omit it.
+   * 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),
@@ -268,12 +269,12 @@ export const ReleaseDetailResponseSchema = z.object({
    * 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(),
   /**
-   * 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.
+   * 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(),
@@ -314,6 +315,18 @@ export const ReleaseDetailResponseSchema = z.object({
  * 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(),

package/src/schemas/sitemap.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { DatasetDescriptionSchema } from "./datasets.js";
 
 /**
  * Per-source row in `GET /v1/sitemap`. `hasChangelog` and `hasHighlights`
@@ -12,6 +13,8 @@ export const SitemapSourceSchema = z.object({
    * may omit it and the web degrades to the bare URL.
    */
   id: z.string().optional(),
+  /** Null explicitly disables; absence supports older API deploys. */
+  dataset: DatasetDescriptionSchema.nullable().optional(),
   orgSlug: z.string(),
   slug: z.string(),
   latestDate: z.string().nullable(),