@buildinternet/releases-api-types 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.27.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,
@@ -636,7 +637,10 @@ export interface StuckSource {
   isHidden: boolean;
   /** Non-`dry_run` attempts examined in the window (all errors when stuck). */
   recentAttempts: number;
-  /** Errors among the examined attempts (equals `recentAttempts` when stuck). */
+  /**
+   * Failed or degraded attempts (`error`, `crawl_timeout`, `blocked`) among the
+   * examined attempts (equals `recentAttempts` when stuck).
+   */
   recentErrors: number;
   /** Most-recent fetch attempt timestamp (ISO), or null. */
   lastAttemptAt: string | null;
@@ -1169,6 +1173,24 @@ export interface FetchLogEntry {
   createdAt: string;
 }
 
+/**
+ * The managed-agent session currently fetching a source, surfaced read-side on
+ * the fetch-log view so an operator/agent can tell "a fetch is in flight" from
+ * "stuck/dead" without waiting for a terminal `fetch_log` row (#1360). Only
+ * running, non-stale sessions are reported (the StatusHub DO drops sessions idle
+ * past its staleness cutoff), so the presence of this object means a fetch is
+ * live; `startedAt` says how long it has been running.
+ */
+export interface ActiveFetchSession {
+  sessionId: string;
+  /** Always `running` today — only running sessions are surfaced. */
+  status: string;
+  /** Session start, epoch ms. */
+  startedAt: number;
+  /** Last session activity, epoch ms. */
+  lastUpdatedAt: number;
+}
+
 // ── Usage ──
 
 export interface UsageBreakdownRow {

package/src/schemas/lookups.ts

@@ -38,6 +38,8 @@ export const LookupSourceSchema = z.looseObject({
   isHidden: z.boolean().nullable().optional(),
   discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
   metadata: z.string().nullable(),
+  stars: z.number().int().min(0).nullable().optional(),
+  starsFetchedAt: z.string().nullable().optional(),
   createdAt: z.string().optional(),
 });
 

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/search.ts

@@ -60,6 +60,7 @@ export const SearchSourceHitSchema = z.object({
   orgSlug: z.string().nullable(),
   orgName: z.string().nullable(),
   productSlug: z.string().nullable(),
+  stars: z.number().int().min(0).nullable().optional(),
 });
 
 export const SearchReleaseHitSchema = z.object({
@@ -164,6 +165,7 @@ export const LookupResultPayloadSchema = z.object({
       name: z.string(),
       url: z.string(),
       discovery: z.enum(["curated", "agent", "on_demand"]),
+      stars: z.number().int().min(0).nullable().optional(),
     })
     .optional(),
   releases: z

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);
@@ -50,6 +55,11 @@ export const SourceListItemSchema = z.object({
   productName: z.string().nullable().optional(),
   productSlug: z.string().nullable().optional(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  // GitHub stargazer count. `nullable().optional()` (the house idiom for these
+  // shapes): non-github sources and older responses omit it; a fetched row may
+  // carry `null`. Consumers treat null/undefined as "unknown".
+  stars: z.number().int().min(0).nullable().optional(),
+  starsFetchedAt: z.string().nullable().optional(),
 });
 
 /**
@@ -84,6 +94,11 @@ export const SourceWithOrgSchema = z.object({
   medianGapDays: z.number().nullable(),
   lastRetieredAt: z.string().nullable(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  // GitHub stargazer count. `nullable().optional()` (the house idiom for these
+  // shapes): non-github sources and older responses omit it; a fetched row may
+  // carry `null`. Consumers treat null/undefined as "unknown".
+  stars: z.number().int().min(0).nullable().optional(),
+  starsFetchedAt: z.string().nullable().optional(),
 });
 
 export const SourceListResponseSchema = ListResponseSchema(SourceWithOrgSchema);
@@ -161,6 +176,12 @@ export const SourceDetailSchema = z.object({
   pagination: SourceFeedPaginationSchema,
   summaries: SourceDetailSummariesSchema,
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  // GitHub stargazer count. `nullable().optional()` (the house idiom for these
+  // shapes): non-github sources and older responses omit it; a fetched row may
+  // 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(),
 });
 
 /**
@@ -248,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`. */