@buildinternet/releases-api-types 0.30.0 → 0.32.0

package/package.json

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

@@ -12,6 +12,7 @@ export type {
 } from "@buildinternet/releases-core/source-enums";
 // Re-export above doesn't create local bindings; import for use in interfaces below.
 import type { SourceType, SourceFetchPriority } from "@buildinternet/releases-core/source-enums";
+import type { ApiScope } from "@buildinternet/releases-core/api-token";
 import type {
   MediaItemSchema,
   PaginationSchema,
@@ -288,6 +289,12 @@ export {
   OrgRecentReleasesResponseSchema,
   DeleteOrgAccountResponseSchema,
 } from "./schemas/orgs.js";
+export {
+  ReleasesJsonConfigSchema,
+  ReleasesJsonProductSchema,
+  SyncWellKnownResponseSchema,
+} from "./schemas/well-known.js";
+export type { ReleasesJsonConfig, ReleasesJsonProduct } from "./schemas/well-known.js";
 export {
   SourceListItemSchema,
   SourceWithOrgSchema,
@@ -489,6 +496,38 @@ export interface ListResponse<T> {
   pagination: Pagination;
 }
 
+// === User-owned API keys (relu_) — self-serve surface served by /v1/api-keys ===
+
+/** A user-owned API key (relu_) as returned by GET /v1/api-keys. */
+export interface UserApiKey {
+  id: string;
+  name: string | null;
+  start: string | null;
+  scope: ApiScope | null;
+  enabled: boolean | null;
+  remaining: number | null;
+  lastRequest: string | null; // ISO 8601
+  createdAt: string; // ISO 8601
+  expiresAt: string | null; // ISO 8601
+}
+
+/** POST /v1/api-keys create response — includes the full key string exactly once. */
+export interface CreatedUserApiKey extends Omit<UserApiKey, "enabled" | "lastRequest"> {
+  key: string;
+}
+
+/** GET /v1/api-keys response envelope. */
+export interface ListUserApiKeysResponse {
+  apiKeys: UserApiKey[];
+}
+
+/** POST /v1/api-keys request body. Self-serve mints are capped at read server-side. */
+export interface CreateUserApiKeyBody {
+  name: string;
+  scope?: ApiScope;
+  expiresInDays?: number;
+}
+
 export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
 
 // ── Sitemap (bulk URL emission) ──
@@ -709,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}. */
@@ -747,6 +795,46 @@ 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;
+}
+
+/**
+ * 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>;
+
 // ── Search ──
 
 export type SearchOrgHit = z.infer<typeof SearchOrgHitSchema>;

package/src/schemas/releases.ts

@@ -168,6 +168,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 +206,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(),

package/src/schemas/well-known.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "bun:test";
+import { ReleasesJsonConfigSchema } from "./well-known.js";
+
+describe("ReleasesJsonConfigSchema", () => {
+  it("accepts an empty object (no-op file)", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({}).success).toBe(true);
+  });
+
+  it("accepts a full org-scope file", () => {
+    const r = ReleasesJsonConfigSchema.safeParse({
+      $schema: "https://releases.sh/schemas/releases.json",
+      name: "Acme",
+      description: "CI for teams.",
+      category: "developer-tools",
+      avatar: "https://acme.com/logo.png",
+      tags: ["ci", "observability"],
+      social: { twitter: "acmehq", github: "acme" },
+      notice: { message: "Docs moved", href: "https://acme.com/docs" },
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("accepts a product-scope file", () => {
+    const r = ReleasesJsonConfigSchema.safeParse({
+      product: { name: "Acme Cloud", slug: "acme-cloud", category: "cloud", kind: "platform" },
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("rejects a non-https avatar", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({ avatar: "http://acme.com/x.png" }).success).toBe(
+      false,
+    );
+  });
+
+  it("rejects a product with no name", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({ product: { slug: "x" } }).success).toBe(false);
+  });
+
+  it("rejects an unknown product kind", () => {
+    expect(
+      ReleasesJsonConfigSchema.safeParse({ product: { name: "Acme Cloud", kind: "saas" } }).success,
+    ).toBe(false);
+  });
+
+  it("rejects an over-long notice message", () => {
+    const r = ReleasesJsonConfigSchema.safeParse({ notice: { message: "x".repeat(281) } });
+    expect(r.success).toBe(false);
+  });
+
+  it("strips unknown top-level keys", () => {
+    const r = ReleasesJsonConfigSchema.parse({ name: "Acme", bogus: 1 });
+    expect("bogus" in r).toBe(false);
+  });
+});

package/src/schemas/well-known.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
+import { NoticeSchema } from "./shared.js";
+
+/** A single social handle/URL. Bare handles allowed; URLs must be https. */
+const SocialValueSchema = z.string().min(1).max(200);
+
+/** Product-scope block: declares the hosting repo's source belongs to this product. */
+export const ReleasesJsonProductSchema = z
+  .object({
+    name: z.string().min(1).max(120),
+    slug: z.string().min(1).max(120).optional(),
+    description: z.string().max(2000).optional(),
+    // Accepted leniently as a string; resolved/validated against CATEGORIES at apply time.
+    category: z.string().min(1).max(120).optional(),
+    kind: z.enum(KIND_VALUES).optional(),
+  })
+  .strict();
+
+/**
+ * One file name, two hosting scopes. Org-identity keys are honored only from a
+ * domain `.well-known/releases.json`; `product` is honored only from a repo-root
+ * file. The server enforces which keys it honors based on the host the file came
+ * from — this schema only validates shape.
+ */
+export const ReleasesJsonConfigSchema = z
+  .object({
+    $schema: z.url().optional(),
+    // Org scope
+    name: z.string().min(1).max(120).optional(),
+    description: z.string().max(2000).optional(),
+    category: z.string().min(1).max(120).optional(),
+    avatar: z
+      .url()
+      .refine((u) => u.startsWith("https://"), "avatar must be an https URL")
+      .optional(),
+    tags: z.array(z.string().min(1).max(60)).max(50).optional(),
+    social: z.record(z.string().min(1).max(40), SocialValueSchema).optional(),
+    notice: NoticeSchema.optional(),
+    // Source/product scope
+    product: ReleasesJsonProductSchema.optional(),
+  })
+  .strip();
+
+export type ReleasesJsonConfig = z.infer<typeof ReleasesJsonConfigSchema>;
+export type ReleasesJsonProduct = z.infer<typeof ReleasesJsonProductSchema>;
+
+/** Response shape of POST /v1/orgs/:slug/sync-well-known. */
+export const SyncWellKnownResponseSchema = z.object({
+  fetched: z.boolean(),
+  applied: z.boolean(),
+  skippedReason: z.string().optional(),
+  plan: z.unknown().optional(),
+});