@buildinternet/releases-api-types 0.31.0 → 0.33.0

package/package.json

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

@@ -748,7 +748,16 @@ export interface ReleaseDetail {
   sourceName: string;
   sourceSlug: string;
   sourceType: string;
-  org: { slug: string; name: string } | null;
+  /**
+   * Owning org. `avatarUrl` is the resolved `organizations.avatar_url`
+   * (nullable; `.optional()` for mid-deploy / pinned-worker tolerance).
+   */
+  org: { slug: string; name: string; avatarUrl?: string | null } | null;
+  /**
+   * Owning product, when the source is grouped under one (`sources.product_id`).
+   * `null` when ungrouped; `.optional()` so older servers that omit it still type.
+   */
+  product?: { slug: string; name: string } | null;
   /** Release type. See {@link ReleaseType}. */
   type?: ReleaseType;
   /** Per-category item counts from the AI release-content pass. See {@link ReleaseComposition}. */
@@ -786,6 +795,81 @@ export type ReleaseStreamMessage = z.infer<typeof ReleaseStreamMessageSchema>;
 
 export type ReleaseSummaryItem = z.infer<typeof ReleaseSummaryItemSchema>;
 
+// ── Follows ──
+
+/** What a user can follow. */
+export type FollowTarget = "org" | "product";
+
+/** A user's follow, enriched for rendering (returned by GET /v1/me/follows). */
+export interface Follow {
+  targetType: FollowTarget;
+  targetId: string;
+  name: string;
+  slug: string;
+  avatarUrl: string | null;
+  /** Owning org slug for product follows (null for org follows). */
+  orgSlug: string | null;
+  createdAt: string;
+}
+
+/** GET /v1/me/follows response. */
+export interface FollowsListResponse {
+  follows: Follow[];
+}
+
+/** POST /v1/me/follows request body. */
+export interface FollowRequest {
+  targetType: FollowTarget;
+  targetId: string;
+}
+
+/** POST/DELETE /v1/me/follows response. */
+export interface FollowMutationResponse {
+  success: true;
+  following: boolean;
+}
+
+/**
+ * A user's personalized feed token, including the full re-revealable feed URL.
+ * The token is reversible (stored recoverably) because the feed serves only
+ * public release data and carries no PII — so the URL can be re-displayed and
+ * copied on any visit (see #1519 design, decision 6). One per user.
+ */
+export interface FeedToken {
+  /** Absolute, tokenized Atom URL — e.g. https://api.releases.sh/v1/feed/relf_…_….atom */
+  feedUrl: string;
+  /** Non-secret public handle (for masked display). */
+  lookupId: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+}
+
+/** `GET /v1/me/feed/token` — the token, or null if the user has none yet. */
+export interface FeedTokenResponse {
+  token: FeedToken | null;
+}
+
+/**
+ * GET /v1/me/feed response — the personalized release feed. Reuses the same item
+ * shape as /v1/releases/latest (ReleaseLatestItem) inside the standard list envelope.
+ */
+export type PersonalizedFeedResponse = ListResponse<ReleaseLatestItem>;
+
+// ── Digest emails ──
+
+/** How often a user wants a digest email. `off` = no emails. */
+export type DigestCadence = "off" | "daily" | "weekly";
+
+/** GET /v1/me/digest response — the caller's current cadence. */
+export interface DigestPrefsResponse {
+  cadence: DigestCadence;
+}
+
+/** PUT /v1/me/digest request body. */
+export interface DigestPrefsRequest {
+  cadence: DigestCadence;
+}
+
 // ── Search ──
 
 export type SearchOrgHit = z.infer<typeof SearchOrgHitSchema>;
@@ -796,6 +880,8 @@ export type SearchSourceHit = z.infer<typeof SearchSourceHitSchema>;
 export interface RawSourceHit extends SearchSourceHit {
   productName?: string;
   productCategory?: string;
+  /** Owning org's avatar URL — folded onto the catalog hit for the byline avatar. */
+  orgAvatarUrl?: string | null;
   /** Entity taxonomy kind from the `sources.kind` column. */
   entityKind?: string | null;
 }
@@ -821,6 +907,7 @@ export function foldSourcesIntoCatalog(
         name: s.productName ?? s.name,
         orgSlug: s.orgSlug,
         orgName: s.orgName,
+        orgAvatarUrl: s.orgAvatarUrl ?? null,
         category: s.productCategory ?? null,
         entryType: "product",
         kind: undefined,
@@ -832,6 +919,7 @@ export function foldSourcesIntoCatalog(
         name: s.name,
         orgSlug: s.orgSlug,
         orgName: s.orgName,
+        orgAvatarUrl: s.orgAvatarUrl ?? null,
         category: null,
         entryType: "source",
         kind: (s.entityKind as SearchCatalogHit["kind"]) ?? undefined,

package/src/schemas/releases.ts

@@ -26,6 +26,9 @@ export const ReleaseLatestSourceSchema = z.object({
   name: z.string(),
   type: z.enum(SOURCE_TYPES),
   orgSlug: z.string().nullable(),
+  /** Owning org's display name (e.g. "Cloudflare"), distinct from the source
+   *  name. Null when the source has no org. Additive — older responses omit it. */
+  orgName: z.string().nullable().optional(),
 });
 
 export const ReleaseLatestProductSchema = z.object({
@@ -168,6 +171,13 @@ export const ReleasesWithMediaResponseSchema = z.array(ReleaseWithMediaRowSchema
 export const ReleaseDetailOrgSchema = z.object({
   slug: z.string(),
   name: z.string(),
+  /**
+   * Resolved org avatar URL (the `organizations.avatar_url` column). `null`
+   * when the org has no stored avatar. Additive — older servers omit it, so
+   * treat `undefined` as `null`. Mirrors the `orgAvatarUrl` field on the
+   * related-rail feed.
+   */
+  avatarUrl: z.string().nullable().optional(),
 });
 
 /**
@@ -199,6 +209,13 @@ export const ReleaseDetailResponseSchema = z.object({
   sourceSlug: z.string().nullable(),
   sourceType: z.enum(SOURCE_TYPES).nullable(),
   org: ReleaseDetailOrgSchema.nullable(),
+  /**
+   * Owning product, when the release's source is grouped under a product
+   * (`sources.product_id`). `null` when the source has no product. Additive —
+   * older servers omit this field; treat `undefined` as `null`. Reuses the
+   * `{ slug, name }` shape from the latest feed.
+   */
+  product: ReleaseLatestProductSchema.nullable().optional(),
   composition: ReleaseCompositionSchema.nullable(),
   appStore: AppStoreSourceInfoSchema.nullable().optional(),
   video: VideoSourceInfoSchema.nullable().optional(),
@@ -226,6 +243,12 @@ export const UpdateReleaseBodySchema = z
     titleShort: z.string().nullable().optional(),
     // `null` removes `$.composition` from metadata; an object replaces it.
     composition: ReleaseCompositionSchema.nullable().optional(),
+    // Replace the release's stored `media[]` wholesale (curator manual edit).
+    // Items whose `url` is not already an R2/`media.releases.sh` origin are run
+    // through the ingest R2 mirror (`processMediaForR2`) so posters/images land
+    // in `released-media` and get `r2Key`/`r2Url` stamped — same path as ingest.
+    // Reuses the shared `MediaItemSchema` (type/url/alt/r2Url/r2Key/linkUrl).
+    media: z.array(MediaItemSchema).optional(),
   })
   .strict();
 

package/src/schemas/search.ts

@@ -40,6 +40,9 @@ export const SearchCatalogHitSchema = z.object({
   name: z.string(),
   orgSlug: z.string().nullable(),
   orgName: z.string().nullable(),
+  /** Owning org's avatar URL, for a small inline byline avatar. Products have
+   *  no avatar of their own, so the web row anchors on the org's instead. */
+  orgAvatarUrl: z.string().nullable().optional(),
   // Loose `z.string().nullable()` rather than the canonical `CategorySchema`
   // enum because `foldSourcesIntoCatalog` and the catalog-search handlers
   // pass `s.productCategory` / `o.category` through without validating

package/src/schemas/shared.ts

@@ -9,7 +9,21 @@ export const MediaItemSchema = z.object({
   type: z.enum(["image", "video", "gif"]),
   url: z.string(),
   alt: z.string().optional(),
+  // R2 object key (`releases/<hash>.<ext>`) for media mirrored into the
+  // `released-media` bucket; read paths resolve it to a same-origin `r2Url`
+  // (`resolveR2Url`). Stamped by `processMediaForR2` at ingest / manual edit and
+  // part of the stored `media[]` JSON — surfaced on the wire so a curator round-
+  // tripping `media` through `PATCH /v1/releases/:id` can preserve an already-
+  // mirrored item without forcing a re-fetch.
+  r2Key: z.string().optional(),
   r2Url: z.string().optional(),
+  // For `type: "video"` items promoted from a hosted-video link found inline in
+  // a release body (Wistia/Loom/Vimeo/YouTube), `url` holds the poster/thumbnail
+  // (mirrored to R2 like any image) and `linkUrl` holds the human watch URL the
+  // play-card links out to. Absent for ordinary image/gif media. See
+  // `detectInlineVideos` in `@releases/rendering/video-embed` and web's
+  // release-content video card.
+  linkUrl: z.string().optional(),
 });
 
 /**

package/src/schemas/sources.ts

@@ -475,13 +475,27 @@ export const CreateSourceSummaryResponseSchema = z.object({
 // ── Source fetch trigger (POST /sources/:slug/fetch) ──
 
 /**
- * Response shape for `POST /v1/sources/:slug/fetch`. Two branches:
+ * Response shape for `POST /v1/sources/:slug/fetch`. Three branches:
  *   - Feed/GitHub/scraped-with-feed sources: `{ fetched: true, releasesInserted, … }`
  *   - Scrape/agent sources (flagged for CLI pickup): `{ queued: true, type: "flagged" }`
+ *   - Render dry-run probe (`?dryRun=true` on a client-rendered scrape source):
+ *     `{ renderCheck: true, rendered, candidateCount, sampleUrls, … }`
  */
 export const SourceFetchResponseSchema = z.union([
   z.looseObject({ fetched: z.literal(true) }),
   z.object({ queued: z.literal(true), type: z.string() }),
+  // Render dry-run probe (#1528): renders a client-rendered scrape source's
+  // index once and reports candidate links found, without the managed-agent
+  // extraction loop.
+  z.looseObject({
+    renderCheck: z.literal(true),
+    status: z.enum(["dry_run", "error"]),
+    rendered: z.boolean(),
+    candidateCount: z.number().int(),
+    sampleUrls: z.array(z.string()),
+    durationMs: z.number().int(),
+    error: z.string().optional(),
+  }),
 ]);
 
 // ── Source content-hash check (POST /sources/:slug/content-hash) ──