@buildinternet/releases-api-types 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.28.0",
+  "version": "0.29.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.22.0",
+    "@buildinternet/releases-core": "^0.23.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -250,6 +250,7 @@ export {
   OverviewPageItemSchema,
   OverviewCitationSchema,
   CategorySchema,
+  NoticeSchema,
 } from "./schemas/shared.js";
 export {
   OrgListItemSchema,

package/src/schemas/orgs.ts

@@ -4,6 +4,7 @@ import {
   AppStoreSourceInfoSchema,
   CategorySchema,
   ListResponseSchema,
+  NoticeSchema,
   OverviewPageItemSchema,
   PaginationSchema,
   ReleaseItemSchema,
@@ -114,6 +115,7 @@ export const UpdateOrgBodySchema = z.object({
   featured: z.boolean().optional(),
   /** Admin-only: promote or demote the org's discovery status (curated/agent/on_demand). */
   discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
+  notice: NoticeSchema.nullable().optional(),
 });
 
 // Org detail's products query selects a strict subset of `ProductListItem` —
@@ -455,4 +457,5 @@ export const OrgDetailSchema = z.object({
   sources: z.array(SourceListItemSchema),
   overview: OverviewPageItemSchema.nullable().optional(),
   playbook: OrgDetailPlaybookSchema.nullable().optional(),
+  notice: NoticeSchema.nullable().optional(),
 });

package/src/schemas/products.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { CategorySchema, ListResponseSchema, ReleaseItemSchema } from "./shared.js";
+import { CategorySchema, ListResponseSchema, NoticeSchema, ReleaseItemSchema } from "./shared.js";
 import { SourceTypeSchema, SourceFeedPaginationSchema } from "./sources.js";
 
 /**
@@ -89,6 +89,7 @@ export const ProductDetailSchema = ProductRowSchema.extend({
   releases: z.array(ReleaseItemSchema).optional(),
   /** Cursor pagination for the embedded release feed — set by the web format adapter (PR #1207), absent on bare product detail. */
   pagination: SourceFeedPaginationSchema.optional(),
+  notice: NoticeSchema.nullable().optional(),
 });
 
 /**
@@ -125,6 +126,7 @@ export const UpdateProductBodySchema = z.object({
   aliases: z.array(z.string()).optional(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
   avatarUrl: z.string().nullable().optional(),
+  notice: NoticeSchema.nullable().optional(),
 });
 
 /**

package/src/schemas/shared.notice.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "bun:test";
+import { NoticeSchema } from "./shared";
+
+describe("NoticeSchema", () => {
+  it("accepts a message-only notice", () => {
+    expect(NoticeSchema.safeParse({ message: "Heads up" }).success).toBe(true);
+  });
+  it("accepts a message + internal coordinate", () => {
+    expect(
+      NoticeSchema.safeParse({
+        message: "Moved",
+        coordinate: "cognition/devin",
+        linkText: "View Devin",
+      }).success,
+    ).toBe(true);
+  });
+  it("accepts a message + external href", () => {
+    expect(NoticeSchema.safeParse({ message: "Moved", href: "https://devin.ai" }).success).toBe(
+      true,
+    );
+  });
+  it("rejects both coordinate and href", () => {
+    expect(
+      NoticeSchema.safeParse({ message: "x", coordinate: "a/b", href: "https://x.com" }).success,
+    ).toBe(false);
+  });
+  it("rejects an empty message and an over-long message", () => {
+    expect(NoticeSchema.safeParse({ message: "" }).success).toBe(false);
+    expect(NoticeSchema.safeParse({ message: "x".repeat(281) }).success).toBe(false);
+  });
+  it("rejects a malformed coordinate", () => {
+    expect(NoticeSchema.safeParse({ message: "x", coordinate: "/leading" }).success).toBe(false);
+    expect(NoticeSchema.safeParse({ message: "x", coordinate: "a/b/c" }).success).toBe(false);
+    expect(NoticeSchema.safeParse({ message: "x", coordinate: "" }).success).toBe(false);
+  });
+});

package/src/schemas/shared.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { RELEASE_TYPES } from "@buildinternet/releases-core/schema";
 import { CATEGORIES } from "@buildinternet/releases-core/categories";
+import { isValidNoticeCoordinate } from "@buildinternet/releases-core/notice";
 
 export const CategorySchema = z.enum(CATEGORIES);
 
@@ -150,6 +151,26 @@ export const OverviewCitationSchema = z.object({
   releaseId: z.string().nullable().optional(),
 });
 
+/**
+ * Entity notice — a small curator-set note on an org / product / source. Stored
+ * under the `notice` key of the entity's metadata JSON; mirrors the `Notice`
+ * type in @buildinternet/releases-core/notice. `coordinate` is an internal
+ * registry path ("org" / "org/slug"); `href` is an external URL; at most one.
+ */
+export const NoticeSchema = z
+  .object({
+    message: z.string().min(1).max(280),
+    linkText: z.string().min(1).max(60).optional(),
+    coordinate: z.string().min(1).max(200).optional(),
+    href: z.url().max(500).optional(),
+  })
+  .refine((n) => !(n.coordinate && n.href), {
+    message: "notice may set coordinate or href, not both",
+  })
+  .refine((n) => !n.coordinate || isValidNoticeCoordinate(n.coordinate), {
+    message: "notice.coordinate must be 'org' or 'org/slug'",
+  });
+
 export const OverviewPageItemSchema = z.object({
   scope: z.enum(["org", "product"]),
   orgSlug: z.string().nullable().optional(),

package/src/schemas/sources.ts

@@ -5,7 +5,12 @@ import {
   SOURCE_FETCH_PRIORITIES,
 } from "@buildinternet/releases-core/source-enums";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { ListResponseSchema, ReleaseItemSchema, ReleaseSummaryItemSchema } from "./shared.js";
+import {
+  ListResponseSchema,
+  NoticeSchema,
+  ReleaseItemSchema,
+  ReleaseSummaryItemSchema,
+} from "./shared.js";
 
 export const SourceTypeSchema = z.enum(SOURCE_TYPES);
 export const SourceDiscoverySchema = z.enum(SOURCE_DISCOVERY);
@@ -176,6 +181,7 @@ export const SourceDetailSchema = z.object({
   // carry `null`. Consumers treat null/undefined as "unknown".
   stars: z.number().int().min(0).nullable().optional(),
   starsFetchedAt: z.string().nullable().optional(),
+  notice: NoticeSchema.nullable().optional(),
 });
 
 /**
@@ -263,6 +269,7 @@ export const SourcePatchInputSchema = z.object({
   kind: z.enum(KIND_VALUES).nullable().optional(),
   /** Admin-only: promote or demote the source's discovery status (curated/agent/on_demand). */
   discovery: SourceDiscoverySchema.optional(),
+  notice: NoticeSchema.nullable().optional(),
 });
 
 /** Body accepted by `POST /v1/sources`. */