@buildinternet/releases-api-types 0.23.0 → 0.24.0

package/package.json

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

@@ -64,6 +64,7 @@ import type {
   SourceDetailSchema,
   SourceFeedPaginationSchema,
   SourceMutationResponseSchema,
+  AppStoreMaterializeResponseSchema,
   SourceOrgRefSchema,
   SourcePatchInputSchema,
   CreateSourceBodySchema,
@@ -120,6 +121,7 @@ import type {
   ReleaseLatestProductSchema,
   ReleaseLatestItemSchema,
   ReleaseLatestResponseSchema,
+  ReleaseCoverageSiblingSchema,
   ReleaseCoverageRowSchema,
   ReleaseCoverageResponseSchema,
   LinkReleaseCoverageBodySchema,
@@ -288,6 +290,7 @@ export {
   SourceDetailSchema,
   SourceFeedPaginationSchema,
   SourceMutationResponseSchema,
+  AppStoreMaterializeResponseSchema,
   SourceOrgRefSchema,
   SourcePatchInputSchema,
   CreateSourceBodySchema,
@@ -370,6 +373,7 @@ export {
   ReleaseLatestProductSchema,
   ReleaseLatestItemSchema,
   ReleaseLatestResponseSchema,
+  ReleaseCoverageSiblingSchema,
   ReleaseCoverageRowSchema,
   ReleaseCoverageResponseSchema,
   LinkReleaseCoverageBodySchema,
@@ -546,6 +550,7 @@ export type SourceChangelogResponse = z.infer<typeof SourceChangelogResponseSche
 export type SourceDetail = z.infer<typeof SourceDetailSchema>;
 export type SourceFeedPagination = z.infer<typeof SourceFeedPaginationSchema>;
 export type SourceMutationResponse = z.infer<typeof SourceMutationResponseSchema>;
+export type AppStoreMaterializeResponse = z.infer<typeof AppStoreMaterializeResponseSchema>;
 export type SourceOrgRef = z.infer<typeof SourceOrgRefSchema>;
 export type SourceActivityResponse = z.infer<typeof SourceActivityResponseSchema>;
 export type SourceHeatmapResponse = z.infer<typeof SourceHeatmapResponseSchema>;
@@ -700,6 +705,7 @@ export interface ReleaseDetail {
   appStore?: { platform: "ios" | "macos"; iconUrl: string | null } | null;
 }
 
+export type ReleaseCoverageSibling = z.infer<typeof ReleaseCoverageSiblingSchema>;
 export type ReleaseCoverageRow = z.infer<typeof ReleaseCoverageRowSchema>;
 export type ReleaseCoverageResponse = z.infer<typeof ReleaseCoverageResponseSchema>;
 export type LinkReleaseCoverageBody = z.infer<typeof LinkReleaseCoverageBodySchema>;

package/src/schemas/collections.ts

@@ -107,6 +107,16 @@ export const CollectionReleaseItemSchema = ReleaseItemSchema.extend({
    * typecheck — clients should treat missing and `null` identically.
    */
   product: z.object({ slug: z.string(), name: z.string() }).nullable().optional(),
+  /**
+   * Server-resolved grouping identity — `COALESCE(product.slug, source.slug)` /
+   * `COALESCE(product.name, source.name)`. The web release feeds key and label
+   * SDK/package-cluster rollups on these instead of reconstructing
+   * `product ?? source` client-side. Optional on the wire: older workers omit
+   * them, so clients must fall back to deriving from `product ?? source`. Never
+   * null when present (`source` is always set). #1234
+   */
+  groupSlug: z.string().optional(),
+  groupName: z.string().optional(),
 });
 
 /** Cursor pagination shape matches `/v1/orgs/:slug/releases`. */

package/src/schemas/orgs.ts

@@ -348,6 +348,16 @@ export const OrgReleaseItemSchema = ReleaseItemSchema.extend({
    * omit this field; treat `undefined` as `null`. #1217.
    */
   product: z.object({ slug: z.string(), name: z.string() }).nullable().optional(),
+  /**
+   * Server-resolved grouping identity — `COALESCE(product.slug, source.slug)` /
+   * `COALESCE(product.name, source.name)`. The web releases feed keys and labels
+   * SDK/package-cluster rollups on these instead of reconstructing
+   * `product ?? source` client-side. Optional on the wire: older workers omit
+   * them, so clients must fall back to deriving from `product ?? source`. Never
+   * null when present (`source` is always set). #1234
+   */
+  groupSlug: z.string().optional(),
+  groupName: z.string().optional(),
 });
 
 /** Cursor pagination shape for the org releases feed. */

package/src/schemas/products.ts

@@ -38,6 +38,8 @@ export type ProductCreateResponse = z.infer<typeof ProductCreateResponseSchema>;
  * Per-product row returned by `GET /v1/products`. Adds `sourceCount` to
  * the row shape but omits the internal `embeddedAt` / `deletedAt` columns
  * (the list handler explicitly selects only the user-facing fields).
+ * `avatarUrl` (the product icon, e.g. an App Store app icon) is included so
+ * list surfaces can render the avatar without a per-row detail round-trip.
  */
 export const ProductListItemSchema = z.object({
   id: z.string(),
@@ -48,6 +50,7 @@ export const ProductListItemSchema = z.object({
   description: z.string().nullable(),
   category: CategorySchema.nullable(),
   kind: z.enum(KIND_VALUES).nullable().optional(),
+  avatarUrl: z.string().nullable().optional(),
   createdAt: z.string(),
   sourceCount: z.number().int().min(0),
 });

package/src/schemas/releases.ts

@@ -62,9 +62,31 @@ export const ReleaseLatestResponseSchema = z.object({
   releases: z.array(ReleaseLatestItemSchema),
 });
 
+/**
+ * Display fields for the counterpart release a coverage row points at —
+ * the canonical for a `coverage`-role response, or each rolled-up coverage
+ * release for a `canonical`-role response. Lets `GET /releases/:id/coverage`
+ * render a cluster without a follow-up `GET /releases/:id` per sibling.
+ * `null` when the counterpart is suppressed or its source was removed.
+ *
+ * Coverage-side rows are surfaced here on purpose, even though the
+ * `releases_visible` view (and thus `GET /releases/:id`) hides them — a
+ * cluster view's whole job is to show its members.
+ */
+export const ReleaseCoverageSiblingSchema = z.object({
+  id: z.string(),
+  version: z.string().nullable(),
+  title: z.string(),
+  sourceName: z.string(),
+  publishedAt: z.string().nullable(),
+  org: z.object({ slug: z.string(), name: z.string() }).nullable(),
+});
+
 /**
  * Single row of the `release_coverage` join table. Drives the
- * GET /releases/:id/coverage response.
+ * GET /releases/:id/coverage response. `sibling` carries the counterpart
+ * release's display fields (see {@link ReleaseCoverageSiblingSchema}); it is
+ * optional so an older server that doesn't populate it still validates.
  */
 export const ReleaseCoverageRowSchema = z.object({
   coverageId: z.string(),
@@ -72,6 +94,7 @@ export const ReleaseCoverageRowSchema = z.object({
   reason: z.string().nullable(),
   decidedBy: z.string(),
   decidedAt: z.string(),
+  sibling: ReleaseCoverageSiblingSchema.nullable().optional(),
 });
 
 /**

package/src/schemas/sources.ts

@@ -194,6 +194,38 @@ export const SourceMutationResponseSchema = z.looseObject({
   kind: z.enum(KIND_VALUES).nullable().optional(),
 });
 
+/**
+ * Response from `POST /v1/sources/appstore` — materializes an App Store listing
+ * into a curated Org → Product → Source → first Release (modeled on the GitHub
+ * coordinate `LookupResponse`).
+ *
+ * Unlike `SourceMutationResponse`, the `source` here is the **bare inserted (or
+ * idempotently looked-up) drizzle row** the materialize handler returns verbatim:
+ * no resolved `org { id, slug, name }` block and no `productSlug`. `loose` so the
+ * untyped timestamp/counter columns on the row pass through.
+ *
+ * `status: "indexed"` is a brand-new source (HTTP 201); `"existing"` is the
+ * idempotent hit on a prior materialize of the same trackId (HTTP 200).
+ */
+export const AppStoreMaterializeResponseSchema = z.object({
+  status: z.enum(["indexed", "existing"]),
+  source: z.looseObject({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    type: SourceTypeSchema,
+    url: z.string(),
+    orgId: z.string().nullable(),
+    productId: z.string().nullable(),
+    metadata: z.string().nullable(),
+    kind: z.enum(KIND_VALUES).nullable().optional(),
+    discovery: SourceDiscoverySchema.optional(),
+    isHidden: z.boolean().nullable().optional(),
+    createdAt: z.string().optional(),
+  }),
+  releaseCount: z.number(),
+});
+
 /** Body accepted by `PATCH /v1/sources/:slug`. */
 export const SourcePatchInputSchema = z.object({
   name: z.string().optional(),