@buildinternet/releases-api-types 0.30.0 → 0.31.0

package/package.json

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

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(),
+});