@buildinternet/releases-api-types 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.20.0",
+  "version": "0.22.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.21.0",
+    "@buildinternet/releases-core": "^0.22.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -60,6 +60,7 @@ import type {
   SourceListResponseSchema,
   SourceListResultSchema,
   SourceDetailSchema,
+  SourceFeedPaginationSchema,
   SourceMutationResponseSchema,
   SourceOrgRefSchema,
   SourcePatchInputSchema,
@@ -268,6 +269,7 @@ export {
   SourceListResponseSchema,
   SourceListResultSchema,
   SourceDetailSchema,
+  SourceFeedPaginationSchema,
   SourceMutationResponseSchema,
   SourceOrgRefSchema,
   SourcePatchInputSchema,
@@ -508,6 +510,7 @@ export type CreateSourceBody = z.infer<typeof CreateSourceBodySchema>;
 export type ChangelogFileSummary = z.infer<typeof ChangelogFileSummarySchema>;
 export type SourceChangelogResponse = z.infer<typeof SourceChangelogResponseSchema>;
 export type SourceDetail = z.infer<typeof SourceDetailSchema>;
+export type SourceFeedPagination = z.infer<typeof SourceFeedPaginationSchema>;
 export type SourceMutationResponse = z.infer<typeof SourceMutationResponseSchema>;
 export type SourceOrgRef = z.infer<typeof SourceOrgRefSchema>;
 export type SourceActivityResponse = z.infer<typeof SourceActivityResponseSchema>;
@@ -641,17 +644,22 @@ export type SearchSourceHit = z.infer<typeof SearchSourceHitSchema>;
 export interface RawSourceHit extends SearchSourceHit {
   productName?: string;
   productCategory?: string;
+  /** Entity taxonomy kind from the `sources.kind` column. */
+  entityKind?: string | null;
 }
 
 /**
  * Fold source hits into the catalog list. Sources under a matched product
- * are dropped (product wins); orphan sources become `kind: "source"`.
+ * are dropped (product wins); orphan sources become `entryType: "source"`.
  */
 export function foldSourcesIntoCatalog(
   existingProducts: SearchCatalogHit[],
   rawSources: RawSourceHit[],
 ): SearchCatalogHit[] {
-  const result: SearchCatalogHit[] = existingProducts.map((p) => ({ ...p, kind: "product" }));
+  const result: SearchCatalogHit[] = existingProducts.map((p) => ({
+    ...p,
+    entryType: "product" as const,
+  }));
   const seen = new Set(result.map((p) => p.slug));
   for (const s of rawSources) {
     if (s.productSlug) {
@@ -662,7 +670,8 @@ export function foldSourcesIntoCatalog(
         orgSlug: s.orgSlug,
         orgName: s.orgName,
         category: s.productCategory ?? null,
-        kind: "product",
+        entryType: "product",
+        kind: undefined,
       });
       seen.add(s.productSlug);
     } else {
@@ -672,7 +681,8 @@ export function foldSourcesIntoCatalog(
         orgSlug: s.orgSlug,
         orgName: s.orgName,
         category: null,
-        kind: "source",
+        entryType: "source",
+        kind: (s.entityKind as SearchCatalogHit["kind"]) ?? undefined,
         sourceSlug: s.slug,
         sourceType: s.type,
       });

package/src/schemas/lookups.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
 import { CategorySchema } from "./shared.js";
 
 /**
@@ -114,6 +115,7 @@ export const DomainLookupProductSchema = z.object({
   // path resolves through `resolveCategoryInput` before persisting — unlike
   // the search catalog category, which passes the column through raw.
   category: CategorySchema.nullable(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 export const DomainLookupResponseSchema = z.object({

package/src/schemas/orgs.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
 import {
   CategorySchema,
   ListResponseSchema,
   OverviewPageItemSchema,
+  PaginationSchema,
   ReleaseItemSchema,
 } from "./shared.js";
 import { SourceListItemSchema } from "./sources.js";
@@ -25,7 +27,28 @@ export const OrgListItemSchema = z.object({
   sparkline: z.array(z.number().int().min(0)).length(30),
 });
 
-export const OrgListResponseSchema = ListResponseSchema(OrgListItemSchema);
+/**
+ * Per-request side-channel for the orgs list (#746). `emptyOrgCount` is the
+ * number of orgs that match the same `q` filter but have zero indexed
+ * releases — used to label a "Show empty orgs" toggle without a second
+ * round-trip. The value is scoped by the search term but independent of
+ * `?includeEmpty=` so the toggle CTA can render a count whether the current
+ * response included empty orgs or not.
+ */
+export const OrgListMetaSchema = z.object({
+  emptyOrgCount: z.number().int().min(0),
+});
+
+/**
+ * `meta` is optional on the wire so older workers / pinned clients mid-deploy
+ * don't trip the schema check. New clients can treat missing as
+ * `emptyOrgCount: 0` (the toggle just won't render a count).
+ */
+export const OrgListResponseSchema = z.object({
+  items: z.array(OrgListItemSchema),
+  pagination: PaginationSchema,
+  meta: OrgListMetaSchema.optional(),
+});
 
 export const OrgAccountItemSchema = z.object({
   platform: z.string(),
@@ -103,7 +126,8 @@ const OrgDetailPlaybookSchema = z.object({
 // ── Org catalog (/orgs/:slug/catalog) ──
 
 const OrgCatalogProductItemSchema = z.object({
-  kind: z.literal("product"),
+  entryType: z.literal("product"),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
   id: z.string(),
   slug: z.string(),
   name: z.string(),
@@ -113,7 +137,8 @@ const OrgCatalogProductItemSchema = z.object({
 });
 
 const OrgCatalogSourceItemSchema = z.object({
-  kind: z.literal("source"),
+  entryType: z.literal("source"),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
   id: z.string(),
   slug: z.string(),
   name: z.string(),
@@ -124,10 +149,12 @@ const OrgCatalogSourceItemSchema = z.object({
 
 /**
  * Combined product + source catalog for `GET /v1/orgs/:slug/catalog`.
- * `kind` discriminates between the two row shapes. Products carry
- * `category` and `description`; sources carry `type` and `productId`.
+ * `entryType` discriminates between the two row shapes (`"product"` vs
+ * `"source"`). `kind` carries the entity taxonomy (platform/sdk/mobile/…).
+ * Products carry `category` and `description`; sources carry `type` and
+ * `productId`.
  */
-export const OrgCatalogItemSchema = z.discriminatedUnion("kind", [
+export const OrgCatalogItemSchema = z.discriminatedUnion("entryType", [
   OrgCatalogProductItemSchema,
   OrgCatalogSourceItemSchema,
 ]);

package/src/schemas/products.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
 import { CategorySchema, ListResponseSchema } from "./shared.js";
 import { SourceTypeSchema } from "./sources.js";
 
@@ -19,6 +20,7 @@ export const ProductRowSchema = z.object({
   url: z.string().nullable(),
   description: z.string().nullable(),
   category: CategorySchema.nullable(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
   createdAt: z.string(),
   embeddedAt: z.string().nullable(),
   deletedAt: z.string().nullable(),
@@ -37,6 +39,7 @@ export const ProductListItemSchema = z.object({
   url: z.string().nullable(),
   description: z.string().nullable(),
   category: CategorySchema.nullable(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
   createdAt: z.string(),
   sourceCount: z.number().int().min(0),
 });
@@ -83,6 +86,7 @@ export const CreateProductBodySchema = z.object({
   description: z.string().optional(),
   category: z.string().min(1).optional(),
   tags: z.array(z.string()).optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /**
@@ -97,6 +101,7 @@ export const UpdateProductBodySchema = z.object({
   category: z.string().min(1).nullable().optional(),
   tags: z.array(z.string()).optional(),
   aliases: z.array(z.string()).optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /**

package/src/schemas/search.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
 import { MediaItemSchema, ReleaseTypeSchema } from "./shared.js";
 import { SourceTypeSchema } from "./sources.js";
 import { LookupStatusSchema } from "./lookups.js";
@@ -24,10 +25,10 @@ export const SearchOrgHitSchema = z.object({
 
 /**
  * Unified catalog entry — either a product row or a standalone source
- * presented as product-shaped. `kind` routes clicks to the right URL but
- * the two forms are otherwise interchangeable for display. `kind` (not
- * `type`) because source rows already carry
- * `type: github|scrape|feed|agent` on the wire.
+ * presented as product-shaped. `entryType` discriminates between the two
+ * row shapes (`"product"` vs `"source"`). `kind` carries the entity
+ * taxonomy (platform/sdk/mobile/…). `entryType` (not `type`) because
+ * source rows already carry `type: github|scrape|feed|agent` on the wire.
  */
 export const SearchCatalogHitSchema = z.object({
   slug: z.string(),
@@ -41,7 +42,8 @@ export const SearchCatalogHitSchema = z.object({
   // that haven't been migrated yet. Tighten once #689 (category overlay
   // backfill) lands across the prod data set.
   category: z.string().nullable(),
-  kind: z.enum(["product", "source"]),
+  entryType: z.enum(["product", "source"]),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
   sourceSlug: z.string().optional(),
   sourceType: SourceTypeSchema.optional(),
 });

package/src/schemas/sources.ts

@@ -4,12 +4,8 @@ import {
   SOURCE_DISCOVERY,
   SOURCE_FETCH_PRIORITIES,
 } from "@buildinternet/releases-core/source-enums";
-import {
-  ListResponseSchema,
-  PaginationSchema,
-  ReleaseItemSchema,
-  ReleaseSummaryItemSchema,
-} from "./shared.js";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
+import { ListResponseSchema, ReleaseItemSchema, ReleaseSummaryItemSchema } from "./shared.js";
 
 export const SourceTypeSchema = z.enum(SOURCE_TYPES);
 export const SourceDiscoverySchema = z.enum(SOURCE_DISCOVERY);
@@ -53,6 +49,7 @@ export const SourceListItemSchema = z.object({
   metadata: z.string().nullable().optional(),
   productName: z.string().nullable().optional(),
   productSlug: z.string().nullable().optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /**
@@ -86,6 +83,7 @@ export const SourceWithOrgSchema = z.object({
   nextFetchAfter: z.string().nullable(),
   medianGapDays: z.number().nullable(),
   lastRetieredAt: z.string().nullable(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 export const SourceListResponseSchema = ListResponseSchema(SourceWithOrgSchema);
@@ -105,6 +103,17 @@ const SourceDetailSummariesSchema = z.object({
   monthly: z.array(ReleaseSummaryItemSchema),
 });
 
+/**
+ * Cursor pagination shape for the source detail's embedded release feed.
+ * Mirrors `OrgFeedPaginationSchema` and `CollectionFeedPaginationSchema` —
+ * release lists are feed-shaped (append-only, mutates between calls), so they
+ * use cursor pagination per the AGENTS.md convention.
+ */
+export const SourceFeedPaginationSchema = z.object({
+  nextCursor: z.string().nullable(),
+  limit: z.number().int().min(1),
+});
+
 /**
  * Resolved attribution block returned alongside a source row. `id` is
  * additive vs the legacy `{ slug, name }` shape — older clients that ignored
@@ -149,8 +158,9 @@ export const SourceDetailSchema = z.object({
   lastPolledAt: z.string().nullable(),
   trackingSince: z.string(),
   releases: z.array(ReleaseItemSchema),
-  pagination: PaginationSchema,
+  pagination: SourceFeedPaginationSchema,
   summaries: SourceDetailSummariesSchema,
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /**
@@ -181,6 +191,7 @@ export const SourceMutationResponseSchema = z.looseObject({
   isHidden: z.boolean().nullable().optional(),
   discovery: SourceDiscoverySchema.optional(),
   createdAt: z.string().optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /** Body accepted by `PATCH /v1/sources/:slug`. */
@@ -202,6 +213,7 @@ export const SourcePatchInputSchema = z.object({
   isHidden: z.boolean().optional(),
   changeDetectedAt: z.string().nullable().optional(),
   lastPolledAt: z.string().nullable().optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 /** Body accepted by `POST /v1/sources`. */
@@ -222,6 +234,7 @@ export const CreateSourceBodySchema = z.object({
   productSlug: z.string().optional(),
   metadata: z.string().optional(),
   isPrimary: z.boolean().optional(),
+  kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
 export const ChangelogFileSummarySchema = z.object({