@buildinternet/releases-api-types 0.35.0 → 0.37.0

package/package.json

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

@@ -309,10 +309,23 @@ export {
 } from "./schemas/account-profile.js";
 export {
   ReleasesJsonConfigSchema,
+  ReleasesJsonDomainReleaseSchema,
+  ReleasesJsonDomainSchema,
   ReleasesJsonProductSchema,
+  ReleasesJsonRegistriesSchema,
+  ReleasesJsonRepoProductSchema,
+  ReleasesJsonRepoReleaseSchema,
+  ReleasesJsonRepoSchema,
   SyncWellKnownResponseSchema,
 } from "./schemas/well-known.js";
-export type { ReleasesJsonConfig, ReleasesJsonProduct } from "./schemas/well-known.js";
+export type {
+  ReleasesJsonConfig,
+  ReleasesJsonDomain,
+  ReleasesJsonDomainRelease,
+  ReleasesJsonProduct,
+  ReleasesJsonRepo,
+  ReleasesJsonRepoRelease,
+} from "./schemas/well-known.js";
 export {
   SourceListItemSchema,
   SourceWithOrgSchema,
@@ -766,6 +779,12 @@ export interface WhatsChangedEntry {
   breaking: BreakingLevel;
   migrationNotes: string | null;
   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.
+   */
+  webUrl: string | null;
 }
 
 /**
@@ -818,6 +837,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;
@@ -1235,7 +1259,7 @@ export type UpdatePlaybookNotesResponse = z.infer<typeof UpdatePlaybookNotesResp
 
 export type OverviewStaleness = "missing" | "behind" | "fresh";
 /**
- * `opted_out` — the org has `autoGenerateContent=false`, so the batch-overview
+ * `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).
@@ -1261,7 +1285,7 @@ export interface OverviewManifestRow {
   staleness: OverviewStaleness;
   /**
    * Whether the org is opted into automatic AI content. When `false`, the
-   * batch-overview cron/manual regen skips it — the staleness signal alone is
+   * overview-regen cron skips it — the staleness signal alone is
    * misleading without this (#1795). Older workers may omit it mid-deploy.
    */
   autoGenerateContent?: boolean;

package/src/schemas/orgs.ts

@@ -120,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). */
@@ -465,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

@@ -62,6 +62,11 @@ export const ReleaseLatestItemSchema = z.object({
   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,
   /**
@@ -237,6 +242,13 @@ export const ReleaseDetailResponseSchema = z.object({
    */
   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/well-known.test.ts

@@ -1,66 +1,163 @@
-import { describe, it, expect } from "bun:test";
-import { ReleasesJsonConfigSchema } from "./well-known.js";
+import { describe, expect, it } from "bun:test";
+import {
+  ReleasesJsonConfigSchema,
+  ReleasesJsonDomainSchema,
+  ReleasesJsonRepoSchema,
+} from "./well-known.js";
 
-describe("ReleasesJsonConfigSchema", () => {
-  it("accepts an empty object (no-op file)", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({}).success).toBe(true);
+const location = (n: number) => ({ url: `https://acme.com/releases/${n}` });
+
+describe("releases.json v2 schemas", () => {
+  it("accepts the minimal domain manifest", () => {
+    expect(
+      ReleasesJsonDomainSchema.parse({
+        version: 2,
+        releases: [{ url: "https://acme.com/updates", feed: "https://acme.com/updates.xml" }],
+      }),
+    ).toEqual({
+      version: 2,
+      releases: [{ url: "https://acme.com/updates", feed: "https://acme.com/updates.xml" }],
+    });
   });
 
-  it("accepts a full org-scope file", () => {
-    const r = ReleasesJsonConfigSchema.safeParse({
+  it("accepts the full domain shape with advisory taxonomy", () => {
+    const parsed = ReleasesJsonDomainSchema.parse({
       $schema: "https://releases.sh/schemas/releases.json",
-      version: 1,
+      version: 2,
       name: "Acme",
       description: "CI for teams.",
-      category: "developer-tools",
+      category: "future-category",
       avatar: "https://acme.com/logo.png",
-      tags: ["ci", "observability"],
+      tags: ["future-tag"],
       social: { twitter: "acmehq", github: "acme" },
-      notice: { message: "Docs moved", href: "https://acme.com/docs" },
+      products: [
+        {
+          name: "Acme Cloud",
+          slug: "acme-cloud",
+          kind: "future-kind",
+          category: "future-category",
+          description: "Managed CI runners.",
+          website: "https://acme.com/cloud",
+          docs: "https://docs.acme.com/cloud",
+          support: "https://acme.com/support",
+          social: { twitter: "acmecloud" },
+          archived: true,
+          releases: [{ github: "acme/cloud", canonical: true }],
+        },
+      ],
+      registries: {
+        "releases.sh": {
+          org: "org_abc123",
+          verification: "verification-token",
+          futureKey: true,
+        },
+        "example.com": { anything: "goes" },
+      },
     });
-    expect(r.success).toBe(true);
+
+    expect(parsed.products?.[0]?.kind).toBe("future-kind");
+    expect(parsed.registries?.["example.com"]).toEqual({ anything: "goes" });
   });
 
-  it("accepts a product-scope file", () => {
-    const r = ReleasesJsonConfigSchema.safeParse({
-      product: { name: "Acme Cloud", slug: "acme-cloud", category: "cloud", kind: "platform" },
-    });
-    expect(r.success).toBe(true);
+  it("accepts the repo variant including github self", () => {
+    expect(
+      ReleasesJsonRepoSchema.safeParse({
+        version: 2,
+        product: { name: "Acme Cloud", slug: "acme-cloud" },
+        releases: [{ github: "self", canonical: true }],
+        registries: { "releases.sh": { product: "prd_abc123" } },
+      }).success,
+    ).toBe(true);
   });
 
-  it("rejects a non-https avatar", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ avatar: "http://acme.com/x.png" }).success).toBe(
-      false,
-    );
+  it("requires the version 2 literal with no v1 compatibility", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({ releases: [location(1)] }).success).toBe(false);
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 1 }).success).toBe(false);
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 3 }).success).toBe(false);
   });
 
-  it("rejects a product with no name", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ product: { slug: "x" } }).success).toBe(false);
+  it("requires at least one locator per release location", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ title: "Updates" }] }).success,
+    ).toBe(false);
   });
 
-  it("rejects an unknown product kind", () => {
+  it("allows github self only in repo files", () => {
     expect(
-      ReleasesJsonConfigSchema.safeParse({ product: { name: "Acme Cloud", kind: "saas" } }).success,
+      ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ github: "self" }] }).success,
     ).toBe(false);
+    expect(
+      ReleasesJsonRepoSchema.safeParse({ version: 2, releases: [{ github: "self" }] }).success,
+    ).toBe(true);
   });
 
-  it("rejects an over-long notice message", () => {
-    const r = ReleasesJsonConfigSchema.safeParse({ notice: { message: "x".repeat(281) } });
-    expect(r.success).toBe(false);
+  it("enforces product and release-location caps", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: Array.from({ length: 25 }, (_, i) => ({ name: `Product ${i}` })),
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", releases: Array.from({ length: 9 }, (_, i) => location(i)) }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: Array.from({ length: 33 }, (_, i) => location(i)),
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: Array.from({ length: 25 }, (_, i) => location(i)),
+        products: [
+          { name: "Cloud", releases: Array.from({ length: 8 }, (_, i) => location(i + 25)) },
+        ],
+      }).success,
+    ).toBe(false);
   });
 
-  it("accepts an integer version", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ version: 1, name: "Acme" }).success).toBe(true);
+  it("allows at most one canonical location per scope", () => {
+    const canonical = (n: number) => ({ ...location(n), canonical: true });
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [canonical(1), canonical(2)],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", releases: [canonical(1), canonical(2)] }],
+      }).success,
+    ).toBe(false);
   });
 
-  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("rejects removed v1 identity fields", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, website: "https://acme.com" }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, notice: { message: "Moved" } }).success,
+    ).toBe(false);
   });
 
-  it("strips unknown top-level keys", () => {
-    const r = ReleasesJsonConfigSchema.parse({ name: "Acme", bogus: 1 });
-    expect("bogus" in r).toBe(false);
+  it("requires typed stable ids for the releases.sh registry", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        registries: { "releases.sh": { org: "prd_wrong" } },
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonRepoSchema.safeParse({
+        version: 2,
+        registries: { "releases.sh": { product: "org_wrong" } },
+      }).success,
+    ).toBe(false);
   });
 });

package/src/schemas/well-known.ts

@@ -1,54 +1,172 @@
 import { z } from "zod";
-import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { NoticeSchema } from "./shared.js";
 
-/** A single social handle/URL. Bare handles allowed; URLs must be https. */
+const MAX_PRODUCTS = 24;
+const MAX_PRODUCT_RELEASES = 8;
+const MAX_FILE_RELEASES = 32;
+
+/** A single social handle/URL. Bare handles are intentionally accepted. */
 const SocialValueSchema = z.string().min(1).max(200);
+const SocialSchema = z.record(z.string().min(1).max(40), SocialValueSchema);
 
-/** Product-scope block: declares the hosting repo's source belongs to this product. */
-export const ReleasesJsonProductSchema = z
-  .object({
-    name: z.string().min(1).max(120),
-    slug: z.string().min(1).max(120).optional(),
-    description: z.string().max(2000).optional(),
-    // Accepted leniently as a string; resolved/validated against CATEGORIES at apply time.
-    category: z.string().min(1).max(120).optional(),
-    kind: z.enum(KIND_VALUES).optional(),
+const HttpsUrlSchema = z
+  .url()
+  .refine((url) => url.startsWith("https://"), "locator must be an https URL");
+
+const ReleaseLocationFields = {
+  url: HttpsUrlSchema.optional(),
+  feed: HttpsUrlSchema.optional(),
+  appstore: HttpsUrlSchema.optional(),
+  file: HttpsUrlSchema.optional(),
+  title: z.string().min(1).max(200).optional(),
+  canonical: z.boolean().optional(),
+};
+
+function hasLocator(value: {
+  url?: string;
+  feed?: string;
+  github?: string;
+  appstore?: string;
+  file?: string;
+}): boolean {
+  return Boolean(value.url || value.feed || value.github || value.appstore || value.file);
+}
+
+/** A domain manifest can name a concrete GitHub repository, but never `self`. */
+export const ReleasesJsonDomainReleaseSchema = z
+  .strictObject({
+    ...ReleaseLocationFields,
+    github: z
+      .string()
+      .regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, "github must be owner/repo")
+      .optional(),
   })
-  .strict();
+  .refine(hasLocator, "at least one release locator is required");
+
+/** A repo manifest additionally accepts `github: "self"`. */
+export const ReleasesJsonRepoReleaseSchema = z
+  .strictObject({
+    ...ReleaseLocationFields,
+    github: z
+      .union([
+        z.literal("self"),
+        z.string().regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, "github must be owner/repo"),
+      ])
+      .optional(),
+  })
+  .refine(hasLocator, "at least one release locator is required");
+
+function releasesArray<T extends z.ZodType>(item: T, max: number) {
+  return z
+    .array(item)
+    .max(max)
+    .refine(
+      (items) =>
+        items.filter((entry) => Boolean((entry as { canonical?: boolean }).canonical)).length <= 1,
+      "at most one canonical release location is allowed per scope",
+    );
+}
+
+const DomainProductReleasesSchema = releasesArray(
+  ReleasesJsonDomainReleaseSchema,
+  MAX_PRODUCT_RELEASES,
+);
+const RepoReleasesSchema = releasesArray(ReleasesJsonRepoReleaseSchema, MAX_FILE_RELEASES);
+const DomainReleasesSchema = releasesArray(ReleasesJsonDomainReleaseSchema, MAX_FILE_RELEASES);
 
 /**
- * One file name, two hosting scopes. Org-identity keys are honored only from a
- * domain `.well-known/releases.json`; `product` is honored only from a repo-root
- * file. The server enforces which keys it honors based on the host the file came
- * from — this schema only validates shape.
+ * Product declaration in a domain manifest. Taxonomy strings are deliberately
+ * lenient here; the reconciler resolves known values and ignores the rest.
  */
-export const ReleasesJsonConfigSchema = z
+export const ReleasesJsonProductSchema = z.strictObject({
+  name: z.string().min(1).max(120),
+  slug: z.string().min(1).max(120).optional(),
+  kind: z.string().min(1).max(120).optional(),
+  category: z.string().min(1).max(120).optional(),
+  description: z.string().max(2000).optional(),
+  website: z.url().optional(),
+  docs: z.url().optional(),
+  support: z.url().optional(),
+  social: SocialSchema.optional(),
+  archived: z.boolean().optional(),
+  releases: DomainProductReleasesSchema.optional(),
+});
+
+/** Repo-scope product binding. Slug is only a creation suggestion. */
+export const ReleasesJsonRepoProductSchema = z.strictObject({
+  name: z.string().min(1).max(120),
+  slug: z.string().min(1).max(120).optional(),
+});
+
+const ReleasesRegistrySchema = z
+  .object({
+    org: z
+      .string()
+      .regex(/^org_[A-Za-z0-9]+$/)
+      .optional(),
+    product: z
+      .string()
+      .regex(/^prd_[A-Za-z0-9]+$/)
+      .optional(),
+    verification: z.string().min(1).max(500).optional(),
+  })
+  .catchall(z.unknown());
+
+/** Registry-specific extensions are forward-compatible by design. */
+export const ReleasesJsonRegistriesSchema = 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
+    "releases.sh": ReleasesRegistrySchema.optional(),
+  })
+  .catchall(z.unknown());
+
+/** Top-level fields shared by every manifest scope. */
+const BaseFields = {
+  $schema: z.url().optional(),
+  version: z.literal(2),
+  registries: ReleasesJsonRegistriesSchema.optional(),
+};
+
+const CommonFields = {
+  ...BaseFields,
+  releases: DomainReleasesSchema.optional(),
+};
+
+/** Domain-hosted variant: flat org identity plus product and release declarations. */
+export const ReleasesJsonDomainSchema = z
+  .strictObject({
+    ...CommonFields,
     name: z.string().min(1).max(120).optional(),
     description: z.string().max(2000).optional(),
     category: z.string().min(1).max(120).optional(),
-    avatar: z
-      .url()
-      .refine((u) => u.startsWith("https://"), "avatar must be an https URL")
-      .optional(),
+    avatar: HttpsUrlSchema.optional(),
     tags: z.array(z.string().min(1).max(60)).max(50).optional(),
-    social: z.record(z.string().min(1).max(40), SocialValueSchema).optional(),
-    notice: NoticeSchema.optional(),
-    // Source/product scope
-    product: ReleasesJsonProductSchema.optional(),
+    social: SocialSchema.optional(),
+    products: z.array(ReleasesJsonProductSchema).max(MAX_PRODUCTS).optional(),
   })
-  .strip();
+  .refine(
+    (manifest) =>
+      (manifest.releases?.length ?? 0) +
+        (manifest.products?.reduce((sum, product) => sum + (product.releases?.length ?? 0), 0) ??
+          0) <=
+      MAX_FILE_RELEASES,
+    `at most ${MAX_FILE_RELEASES} release locations are allowed per file`,
+  );
+
+/** Repo-root variant: product binding plus repo-scoped release declarations. */
+export const ReleasesJsonRepoSchema = z.strictObject({
+  ...BaseFields,
+  product: ReleasesJsonRepoProductSchema.optional(),
+  releases: RepoReleasesSchema.optional(),
+});
+
+/** Public schema accepts either hosting scope; reconcilers use the scoped schema. */
+export const ReleasesJsonConfigSchema = z.union([ReleasesJsonDomainSchema, ReleasesJsonRepoSchema]);
 
 export type ReleasesJsonConfig = z.infer<typeof ReleasesJsonConfigSchema>;
+export type ReleasesJsonDomain = z.infer<typeof ReleasesJsonDomainSchema>;
+export type ReleasesJsonRepo = z.infer<typeof ReleasesJsonRepoSchema>;
 export type ReleasesJsonProduct = z.infer<typeof ReleasesJsonProductSchema>;
+export type ReleasesJsonDomainRelease = z.infer<typeof ReleasesJsonDomainReleaseSchema>;
+export type ReleasesJsonRepoRelease = z.infer<typeof ReleasesJsonRepoReleaseSchema>;
 
 /** Response shape of POST /v1/orgs/:slug/sync-well-known. */
 export const SyncWellKnownResponseSchema = z.object({