@buildinternet/releases-api-types 0.15.0 → 0.17.0

package/src/schemas/collections.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { ReleaseItemSchema } from "./shared.js";
+
+/**
+ * One org as it appears inside a collection's preview list or detail page.
+ * Joined through `organizations_public`, so soft-deleted / on_demand orgs
+ * never leak via a collection.
+ */
+export const CollectionMemberOrgSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
+  /** GitHub handle from `org_accounts`; lets the avatar fall back to github.com/<handle>.png. */
+  githubHandle: z.string().nullable(),
+  description: z.string().nullable(),
+});
+
+/**
+ * Row on `GET /v1/collections`. `previewMembers` is the first few visible
+ * members (capped at 3) so the list page can render inline avatars without a
+ * second round trip.
+ */
+export const CollectionListItemSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  memberCount: z.number().int().min(0),
+  previewMembers: z.array(CollectionMemberOrgSchema).optional(),
+});
+
+export const CollectionListResponseSchema = z.array(CollectionListItemSchema);
+
+/** Returned by `GET /v1/collections/:slug`. */
+export const CollectionDetailSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  orgs: z.array(CollectionMemberOrgSchema),
+});
+
+/**
+ * Cross-org release feed row on `GET /v1/collections/:slug/releases`. Same
+ * shape as `OrgReleaseItem` plus the origin `org` block (and optional
+ * `product`) so the web's release card can render it identically. `source.type`
+ * stays as `z.string()` because the SQL passes the column through unvalidated —
+ * tightening to the SourceType enum would break pass-through code.
+ */
+export const CollectionReleaseItemSchema = ReleaseItemSchema.extend({
+  source: z.object({ slug: z.string(), name: z.string(), type: z.string() }),
+  org: z.object({ slug: z.string(), name: z.string() }),
+  /**
+   * Product the release belongs to, if the source is bound to one. `null` for
+   * orgs without products or standalone sources. Optional on the wire so older
+   * workers mid-rollout (and hand-constructed test fixtures) don't trip the
+   * typecheck — clients should treat missing and `null` identically.
+   */
+  product: z.object({ slug: z.string(), name: z.string() }).nullable().optional(),
+});
+
+/** Cursor pagination shape matches `/v1/orgs/:slug/releases`. */
+export const CollectionFeedPaginationSchema = z.object({
+  nextCursor: z.string().nullable(),
+  limit: z.number().int().min(1),
+});
+
+export const CollectionReleasesResponseSchema = z.object({
+  releases: z.array(CollectionReleaseItemSchema),
+  pagination: CollectionFeedPaginationSchema,
+});
+
+/**
+ * Bare row returned by `POST /v1/collections` and `PATCH /v1/collections/:slug`.
+ * Mirrors the `collections` table columns (no member rollup — that's a
+ * separate detail call).
+ */
+export const CollectionRowSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Body for `POST /v1/collections`. `slug` derives from `name` via `toSlug()`
+ * when omitted. Slug shape is lowercased alnum + hyphens, alnum-start, 2–64
+ * chars — enforced server-side.
+ */
+export const CreateCollectionRequestSchema = z.object({
+  slug: z.string().optional(),
+  name: z.string().min(1).max(200),
+  description: z.string().max(2000).nullable().optional(),
+});
+
+/** Body for `PATCH /v1/collections/:slug`. All fields optional; slug rename allowed. */
+export const UpdateCollectionRequestSchema = z.object({
+  slug: z.string().optional(),
+  name: z.string().min(1).max(200).optional(),
+  description: z.string().max(2000).nullable().optional(),
+});
+
+/**
+ * One member entry accepted by the member-write endpoints. Either `orgId`
+ * (`org_…`) or `orgSlug` is required; when both are given, `orgId` wins.
+ */
+export const CollectionMemberInputSchema = z.object({
+  orgId: z.string().optional(),
+  orgSlug: z.string().optional(),
+  /** Authoring position (default 0). For PUT, omit to use the array index. */
+  position: z.number().int().optional(),
+});
+
+/** Body for `POST /v1/collections/:slug/members`. */
+export const AddCollectionMemberRequestSchema = CollectionMemberInputSchema;
+
+/** Body for `PUT /v1/collections/:slug/members`. Replaces the full membership atomically. */
+export const ReplaceCollectionMembersRequestSchema = z.object({
+  orgs: z.array(CollectionMemberInputSchema),
+});
+
+/** Resolved member returned by `PUT /v1/collections/:slug/members`. */
+export const ResolvedCollectionMemberSchema = z.object({
+  orgId: z.string(),
+  position: z.number().int(),
+});
+
+/** Response from `PUT /v1/collections/:slug/members`. */
+export const ReplaceCollectionMembersResponseSchema = z.object({
+  collectionSlug: z.string(),
+  members: z.array(ResolvedCollectionMemberSchema),
+});
+
+/** Response from `POST /v1/collections/:slug/members`. */
+export const AddCollectionMemberResponseSchema = z.object({
+  collectionSlug: z.string(),
+  orgId: z.string(),
+  position: z.number().int(),
+});

package/src/schemas/lookups.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { CategorySchema } from "./shared.js";
+
+/**
+ * Status flags returned by `POST /v1/lookups`:
+ * - `indexed` — the source was just materialized and releases were ingested.
+ * - `existing` — the source already lives in the registry; we returned it as-is.
+ * - `empty` — the repo exists but has no releases or CHANGELOG to ingest. A
+ *   hidden stub row is left behind so the next cron pass can pick it up.
+ * - `not_found` — the repo doesn't exist, is archived, or isn't reachable.
+ * - `deferred` — GitHub probe rate-limited or 5xx'd; the next cron pass retries.
+ */
+export const LookupStatusSchema = z.enum(["indexed", "existing", "empty", "not_found", "deferred"]);
+
+/** Body accepted by `POST /v1/lookups`. v1 only supports GitHub coordinates. */
+export const LookupBodySchema = z.object({
+  provider: z.literal("github"),
+  coordinate: z.string().regex(/^[^/\s]+\/[^/\s]+$/, {
+    message: "coordinate must match {org}/{repo}",
+  }),
+});
+
+/**
+ * Source row embedded in `LookupResponse`. The handler returns the full
+ * Drizzle row, so `z.looseObject(...)` lets stable fields stay typed while
+ * letting timestamps/counters that aren't load-bearing for callers ride
+ * along unmodelled. Same pattern as `SourceMutationResponseSchema`.
+ */
+export const LookupSourceSchema = z.looseObject({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: z.string(),
+  url: z.string(),
+  orgId: z.string().nullable(),
+  productId: z.string().nullable(),
+  isHidden: z.boolean().nullable().optional(),
+  discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
+  metadata: z.string().nullable(),
+  createdAt: z.string().optional(),
+});
+
+/** Release row embedded in `LookupResponse.releases`. Loose for the same reason as `LookupSourceSchema`. */
+export const LookupReleaseSchema = z.looseObject({
+  id: z.string(),
+  sourceId: z.string(),
+  version: z.string().nullable(),
+  title: z.string(),
+  url: z.string().nullable(),
+  publishedAt: z.string().nullable(),
+});
+
+/** "Did you mean" rail returned alongside not_found / empty / deferred outcomes. */
+export const LookupRelatedOrgSchema = z
+  .object({
+    org: z.object({ id: z.string(), slug: z.string(), name: z.string() }),
+    sources: z.array(
+      z.object({ id: z.string(), slug: z.string(), name: z.string(), url: z.string() }),
+    ),
+  })
+  .nullable();
+
+/**
+ * Response returned by `POST /v1/lookups`. The `source` and `releases` fields
+ * are populated for `indexed` / `existing` outcomes; `empty` populates only
+ * `source`; `not_found` / `deferred` populate neither.
+ */
+export const LookupResponseSchema = z.object({
+  status: LookupStatusSchema,
+  source: LookupSourceSchema.optional(),
+  releases: z.array(LookupReleaseSchema).optional(),
+  relatedOrg: LookupRelatedOrgSchema,
+});
+
+/** Response from `GET /v1/lookups/source-by-slug?slug=…`. */
+export const LookupSourceBySlugResponseSchema = z.object({
+  sourceId: z.string(),
+  sourceSlug: z.string(),
+  orgSlug: z.string(),
+});
+
+/** Response from `GET /v1/lookups/product-by-slug?slug=…`. */
+export const LookupProductBySlugResponseSchema = z.object({
+  productId: z.string(),
+  productSlug: z.string(),
+  orgSlug: z.string(),
+});
+
+/**
+ * Response from `GET /v1/lookups/by-domain?domain=…`. Pure resolution: an
+ * unknown domain returns 404, never probes. Both an org and product list can
+ * be present when a product alias points at the same domain its parent org
+ * owns.
+ */
+export const DomainLookupOrgSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  description: z.string().nullable(),
+  category: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
+  matchedVia: z.enum(["primary", "alias"]),
+});
+
+export const DomainLookupProductSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  orgId: z.string(),
+  orgSlug: z.string(),
+  orgName: z.string(),
+  // Reuses the canonical `CategorySchema` enum because the products read
+  // path resolves through `resolveCategoryInput` before persisting — unlike
+  // the search catalog category, which passes the column through raw.
+  category: CategorySchema.nullable(),
+});
+
+export const DomainLookupResponseSchema = z.object({
+  domain: z.string(),
+  org: DomainLookupOrgSchema.nullable(),
+  products: z.array(DomainLookupProductSchema),
+});

package/src/schemas/orgs.ts

@@ -1,7 +1,13 @@
 import { z } from "zod";
-import { CategorySchema, ListResponseSchema, OverviewPageItemSchema } from "./shared.js";
+import {
+  CategorySchema,
+  ListResponseSchema,
+  OverviewPageItemSchema,
+  ReleaseItemSchema,
+} from "./shared.js";
 import { SourceListItemSchema } from "./sources.js";
 import { ProductListItemSchema } from "./products.js";
+import { CollectionListItemSchema } from "./collections.js";
 
 export const OrgListItemSchema = z.object({
   id: z.string(),
@@ -26,24 +32,49 @@ export const OrgAccountItemSchema = z.object({
   handle: z.string(),
 });
 
-export const OrgAccountsResponseSchema = ListResponseSchema(OrgAccountItemSchema);
+export const OrgAccountsListResponseSchema = ListResponseSchema(OrgAccountItemSchema);
+
+/**
+ * Response shape for `GET /v1/orgs/:slug/accounts`. Returns the paginated list
+ * by default; with `?platform=<name>` returns a single matching account or
+ * `null` when no row matches. The dual shape is preserved for compatibility
+ * with the OSS CLI which calls `?platform=` and expects a single row.
+ */
+export const OrgAccountsResponseSchema = z.union([
+  OrgAccountsListResponseSchema,
+  OrgAccountItemSchema,
+  z.null(),
+]);
 export const OrgTagsResponseSchema = ListResponseSchema(z.string());
 
+/**
+ * Body accepted by `POST /v1/orgs`. `category` is a non-empty string at the
+ * wire boundary so callers can pass either a canonical slug or one of its
+ * configured aliases (resolved server-side via `resolveCategoryInput`).
+ * Responses always carry the canonical slug. Empty strings are rejected so
+ * the truthy-guard around `resolveCategoryInput` in the handler can't be
+ * bypassed into persisting an invalid `""` value.
+ */
 export const CreateOrgBodySchema = z.object({
   name: z.string().min(1),
   slug: z.string().optional(),
   domain: z.string().optional(),
   description: z.string().optional(),
-  category: CategorySchema.optional(),
+  category: z.string().min(1).optional(),
   tags: z.array(z.string()).optional(),
 });
 
+/**
+ * Body accepted by `PATCH /v1/orgs/:slug`. Same alias-allowed string rule
+ * as create, plus `null` to explicitly clear the overlay. Empty strings
+ * stay rejected so callers must pick between a slug/alias or `null`.
+ */
 export const UpdateOrgBodySchema = z.object({
   name: z.string().optional(),
   slug: z.string().optional(),
   domain: z.string().nullable().optional(),
   description: z.string().nullable().optional(),
-  category: CategorySchema.nullable().optional(),
+  category: z.string().min(1).nullable().optional(),
   tags: z.array(z.string()).optional(),
   aliases: z.array(z.string()).optional(),
 });
@@ -66,6 +97,265 @@ const OrgDetailPlaybookSchema = z.object({
   updatedAt: z.string(),
 });
 
+// ── Org catalog (/orgs/:slug/catalog) ──
+
+const OrgCatalogProductItemSchema = z.object({
+  kind: z.literal("product"),
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  url: z.string().nullable(),
+  description: z.string().nullable(),
+  category: CategorySchema.nullable(),
+});
+
+const OrgCatalogSourceItemSchema = z.object({
+  kind: z.literal("source"),
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: z.string(),
+  url: z.string(),
+  productId: z.string().nullable(),
+});
+
+/**
+ * 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`.
+ */
+export const OrgCatalogItemSchema = z.discriminatedUnion("kind", [
+  OrgCatalogProductItemSchema,
+  OrgCatalogSourceItemSchema,
+]);
+
+export const OrgCatalogResponseSchema = z.object({
+  org: z.object({ id: z.string(), slug: z.string(), name: z.string() }),
+  items: z.array(OrgCatalogItemSchema),
+});
+
+// ── Org collections membership (/orgs/:slug/collections) ──
+
+/**
+ * List of collections the org belongs to, returned by
+ * `GET /v1/orgs/:slug/collections`. Each item follows the same shape as
+ * `CollectionListItem` on `GET /v1/collections` — `previewMembers` is
+ * omitted here because the context (one org's collections) makes inline
+ * member previews redundant.
+ */
+export const OrgCollectionsResponseSchema = z.array(CollectionListItemSchema);
+
+// ── Org accounts (/orgs/:slug/accounts) ──
+
+/**
+ * Body accepted by `POST /v1/orgs/:slug/accounts`.
+ * Both `platform` and `handle` are required.
+ */
+export const AddOrgAccountBodySchema = z.object({
+  platform: z.string().min(1),
+  handle: z.string().min(1),
+});
+
+// ── Org ignored URLs (/orgs/:slug/ignored-urls) ──
+
+export const IgnoredUrlItemSchema = z.object({
+  id: z.string(),
+  url: z.string(),
+  orgId: z.string(),
+  reason: z.string().nullable(),
+  ignoredAt: z.string(),
+});
+
+export const OrgIgnoredUrlsListResponseSchema = ListResponseSchema(IgnoredUrlItemSchema);
+
+/**
+ * Response shape for `GET /v1/orgs/:slug/ignored-urls`. Returns the paginated
+ * list by default; with `?url=<encoded>&single=1` returns the matching single
+ * row or `null` when not present.
+ */
+export const OrgIgnoredUrlsResponseSchema = z.union([
+  OrgIgnoredUrlsListResponseSchema,
+  IgnoredUrlItemSchema,
+  z.null(),
+]);
+
+/**
+ * Body accepted by `POST /v1/orgs/:slug/ignored-urls`.
+ * `reason` is optional.
+ */
+export const AddIgnoredUrlBodySchema = z.object({
+  url: z.string().min(1),
+  reason: z.string().optional(),
+});
+
+/** Response shape for `POST /v1/orgs/:slug/ignored-urls`. */
+export const AddIgnoredUrlResponseSchema = z.object({
+  ignored: z.literal(true),
+});
+
+/** Response shape for `DELETE /v1/orgs/:slug/ignored-urls/:url`. */
+export const DeleteIgnoredUrlResponseSchema = z.object({
+  deleted: z.literal(true),
+});
+
+// ── Org tags (/orgs/:slug/tags and PUT /DELETE) ──
+
+/** Body accepted by `PUT` and `DELETE` `/v1/orgs/:slug/tags`. */
+export const OrgTagsBodySchema = z.object({
+  tags: z.array(z.string()),
+});
+
+/** Response shape returned by `PUT` and `DELETE` `/v1/orgs/:slug/tags`. */
+export const OrgTagsMutationResponseSchema = z.object({
+  ok: z.literal(true),
+});
+
+// ── POST /tags (global tag creation) ──
+
+/** Body accepted by `POST /v1/tags`. */
+export const CreateTagBodySchema = z.object({
+  name: z.string().min(1),
+});
+
+/** Row returned by `POST /v1/tags` (201 on create, 200 if already exists). */
+export const TagRowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  createdAt: z.string(),
+});
+
+// ── Org activity (/orgs/:slug/activity) ──
+
+const OrgActivityWeeklyBucketSchema = z.object({
+  weekStart: z.string(),
+  count: z.number().int().min(0),
+  earliestVersion: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+});
+
+const OrgActivitySourceSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  releaseCount: z.number().int().min(0),
+  avgReleasesPerWeek: z.number(),
+  earliestVersion: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+  latestDate: z.string().nullable(),
+  weeklyBuckets: z.array(OrgActivityWeeklyBucketSchema),
+});
+
+/**
+ * Response shape for `GET /v1/orgs/:slug/activity`. Returns per-source
+ * weekly release buckets plus an aggregate rollup — used for timeline
+ * visualization in the web org detail page.
+ */
+export const OrgActivityResponseSchema = z.object({
+  org: z.object({ slug: z.string(), name: z.string() }),
+  range: z.object({ from: z.string(), to: z.string() }),
+  sources: z.array(OrgActivitySourceSchema),
+  aggregateWeekly: z.array(z.object({ weekStart: z.string(), count: z.number().int().min(0) })),
+});
+
+// ── Org heatmap (/orgs/:slug/heatmap) ──
+
+/**
+ * Response shape for `GET /v1/orgs/:slug/heatmap`. Returns daily release
+ * counts for the trailing 365 days — used for contribution-graph
+ * visualization in the web org detail page.
+ */
+export const OrgHeatmapResponseSchema = z.object({
+  org: z.object({ slug: z.string(), name: z.string() }),
+  range: z.object({ from: z.string(), to: z.string() }),
+  dailyCounts: z.array(z.object({ date: z.string(), count: z.number().int().min(0) })),
+  total: z.number().int().min(0),
+});
+
+// ── Org sparklines (/orgs/:slug/sparklines) ──
+
+const SparklineSourceSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  sparkline: z.array(z.number().int().min(0)).length(30),
+});
+
+/**
+ * Response shape for `GET /v1/orgs/:slug/sparklines`. Returns 30-day daily
+ * release counts per source and per product, plus an aggregate rollup.
+ */
+export const OrgSparklinesResponseSchema = z.object({
+  org: z.object({ slug: z.string(), name: z.string() }),
+  range: z.object({ from: z.string(), to: z.string() }),
+  aggregate: z.array(z.number().int().min(0)).length(30),
+  sources: z.array(SparklineSourceSchema),
+  products: z.array(SparklineSourceSchema),
+});
+
+// ── Org releases feed (/orgs/:slug/releases) ──
+
+/**
+ * Release feed item on `GET /v1/orgs/:slug/releases`. Extends `ReleaseItem`
+ * with a `source` block identifying the originating source within the org.
+ */
+export const OrgReleaseItemSchema = ReleaseItemSchema.extend({
+  source: z.object({ slug: z.string(), name: z.string(), type: z.string() }),
+});
+
+/** Cursor pagination shape for the org releases feed. */
+export const OrgFeedPaginationSchema = z.object({
+  nextCursor: z.string().nullable(),
+  limit: z.number().int().min(1),
+});
+
+/**
+ * Response shape for `GET /v1/orgs/:slug/releases`.
+ * Cursor-paginated; `nextCursor` is `null` when this is the last page.
+ */
+export const OrgReleasesFeedResponseSchema = z.object({
+  releases: z.array(OrgReleaseItemSchema),
+  pagination: OrgFeedPaginationSchema,
+});
+
+// ── Org recent releases (/orgs/:slug/recent-releases) ──
+
+/**
+ * Row returned by `GET /v1/orgs/:slug/recent-releases`. This is the full
+ * `releasesVisible` row with `sourceName` and `sourceSlug` joined from
+ * `sourcesVisible` — intended for summarization / grouping by agents.
+ * Many fields are nullable because they may not be populated at ingest time.
+ */
+export const OrgRecentReleaseItemSchema = z.object({
+  id: z.string(),
+  sourceId: z.string(),
+  version: z.string().nullable(),
+  type: z.string().optional(),
+  title: z.string(),
+  content: z.string(),
+  summary: z.string().nullable(),
+  titleGenerated: z.string().nullable().optional(),
+  titleShort: z.string().nullable().optional(),
+  url: z.string().nullable(),
+  contentHash: z.string().nullable(),
+  metadata: z.string().nullable(),
+  media: z.string().nullable(),
+  publishedAt: z.string().nullable(),
+  suppressed: z.number().optional(),
+  suppressedReason: z.string().nullable().optional(),
+  fetchedAt: z.string().optional(),
+  embeddedAt: z.string().nullable().optional(),
+  sourceName: z.string(),
+  sourceSlug: z.string(),
+});
+
+export const OrgRecentReleasesResponseSchema = z.array(OrgRecentReleaseItemSchema);
+
+// ── Org accounts mutation responses ──
+
+/** Response returned by `DELETE /v1/orgs/:slug/accounts/:platform/:handle`. */
+export const DeleteOrgAccountResponseSchema = z.object({
+  deleted: z.literal(true),
+});
+
 export const OrgDetailSchema = z.object({
   id: z.string().optional(),
   slug: z.string(),