@buildinternet/releases-api-types 0.59.0 → 0.60.0

package/src/schemas/account-profile.ts

@@ -1,28 +0,0 @@
-import { z } from "zod";
-
-/** Response shared by user + workspace avatar upload routes. */
-export const UploadAvatarResponseSchema = z.object({
-  avatarUrl: z.string(),
-  key: z.string(),
-  width: z.number(),
-  height: z.number(),
-});
-
-export const WorkspaceProfileFieldsSchema = z.object({
-  websiteUrl: z.string().nullable(),
-  changelogUrl: z.string().nullable(),
-  githubHandle: z.string().nullable(),
-});
-
-/** Body for `PATCH /v1/workspaces/:workspaceId/profile`. */
-export const PatchWorkspaceProfileBodySchema = z.object({
-  websiteUrl: z.string().nullable().optional(),
-  changelogUrl: z.string().nullable().optional(),
-  githubHandle: z.string().nullable().optional(),
-});
-
-export const WorkspaceProfileResponseSchema = z.object({
-  workspaceId: z.string(),
-  logo: z.string().nullable(),
-  profile: WorkspaceProfileFieldsSchema,
-});

package/src/schemas/ai-models.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { AiLaneModelsPutSchema } from "./ai-models";
-
-describe("AiLaneModelsPutSchema", () => {
-  it("accepts a partial map", () => {
-    expect(
-      AiLaneModelsPutSchema.safeParse({
-        models: { summarize: "deepseek/deepseek-v4.1-flash" },
-      }).success,
-    ).toBe(true);
-  });
-
-  it("accepts null to clear an override", () => {
-    expect(AiLaneModelsPutSchema.safeParse({ models: { extract: null } }).success).toBe(true);
-  });
-
-  it("rejects an empty models object", () => {
-    expect(AiLaneModelsPutSchema.safeParse({ models: {} }).success).toBe(false);
-  });
-
-  it("rejects unknown keys", () => {
-    expect(
-      AiLaneModelsPutSchema.safeParse({
-        models: { summarize: "x" },
-        extra: true,
-      }).success,
-    ).toBe(false);
-  });
-});

package/src/schemas/classifications.ts

@@ -1,109 +0,0 @@
-import { z } from "zod";
-
-/**
- * Admin classification analytics (`GET /v1/admin/classifications/summary`
- * and `/recent`). Decisions live in Analytics Engine; these shapes are the
- * hydrated read model, not the positional point schema.
- */
-
-const ClassificationOriginSchema = z.enum(["ingest", "manual", "eval"]);
-const ClassificationOriginFilterSchema = z.enum(["ingest", "manual", "eval", "all"]);
-const ClassificationDispositionSchema = z.enum(["kept", "suppressed", "failed", "skipped"]);
-
-const ProbabilityBinSchema = z.object({
-  /** Inclusive. Width is 0.1. See `probability.threshold` for the current
-   *  effective suppression threshold and which bin it falls in. */
-  start: z.number(),
-  /** Exclusive, except the last bin (`0.9`–`1`) which includes `1`. */
-  end: z.number(),
-  count: z.number(),
-});
-
-const ProbabilityHistogramSchema = z.object({
-  bins: z.array(ProbabilityBinSchema),
-  /** Sampled rows whose double is `< 0` (the absent sentinel). */
-  missing: z.number(),
-});
-
-/** `GET /v1/admin/classifications/summary`. */
-export const ClassificationSummarySchema = z.object({
-  after: z.string(),
-  before: z.string(),
-  bucket: z.enum(["hour", "day"]),
-  origin: ClassificationOriginFilterSchema,
-  totals: z.object({
-    classified: z.number(),
-    kept: z.number(),
-    suppressed: z.number(),
-    failed: z.number(),
-    skipped: z.number(),
-    costUsd: z.number(),
-    /** `suppressed / (kept + suppressed)`, or null when the denominator is 0. */
-    suppressionRate: z.number().nullable(),
-  }),
-  series: z.array(
-    z.object({
-      t: z.string(),
-      kept: z.number(),
-      suppressed: z.number(),
-      failed: z.number(),
-      skipped: z.number(),
-    }),
-  ),
-  choices: z.array(z.object({ choice: z.string(), count: z.number() })),
-  choiceSeries: z.array(
-    z.object({
-      t: z.string(),
-      choices: z.record(z.string(), z.number()),
-    }),
-  ),
-  models: z.array(
-    z.object({
-      provider: z.string(),
-      model: z.string(),
-      count: z.number(),
-      costUsd: z.number(),
-    }),
-  ),
-  probability: z.object({
-    /** Current effective suppression threshold (operator override, else the
-     *  code default) — no longer a fixed literal now that it's editable via
-     *  `GET/PUT /v1/admin/marketing-classifier`. */
-    threshold: z.number(),
-    selected: ProbabilityHistogramSchema,
-    confidence: ProbabilityHistogramSchema,
-  }),
-  meta: z.object({
-    dataset: z.string(),
-    retentionDays: z.literal(90),
-    sampled: z.literal(true),
-  }),
-});
-
-/** One sampled decision from `GET /v1/admin/classifications/recent`. */
-export const ClassificationRecentItemSchema = z.object({
-  timestamp: z.string(),
-  origin: ClassificationOriginSchema,
-  sourceId: z.string().nullable(),
-  sourceName: z.string().nullable(),
-  sourceSlug: z.string().nullable(),
-  orgSlug: z.string().nullable(),
-  releaseId: z.string().nullable(),
-  releaseTitle: z.string().nullable(),
-  provider: z.string(),
-  model: z.string(),
-  choice: z.string(),
-  selectedChoiceProbability: z.number().nullable(),
-  providerConfidence: z.number().nullable(),
-  disposition: ClassificationDispositionSchema,
-  reason: z.string(),
-  failureCategory: z.string(),
-  costUsd: z.number().nullable(),
-  durationMs: z.number().nullable(),
-});
-
-/** `GET /v1/admin/classifications/recent` — newest sampled rows, not weighted. */
-export const ClassificationRecentResponseSchema = z.object({
-  items: z.array(ClassificationRecentItemSchema),
-  nextCursor: z.string().nullable(),
-});

package/src/schemas/collections.ts

@@ -1,346 +0,0 @@
-import { z } from "zod";
-import { ImportanceScoreSchema, ReleaseCompositionSchema, 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(),
-});
-
-/**
- * Org context attached to a product member so the chip can render the parent
- * org's avatar / handle. Subset of `CollectionMemberOrg` — description is
- * intentionally omitted because the byline comes from the product itself.
- */
-export const ProductParentOrgSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  domain: z.string().nullable(),
-  avatarUrl: z.string().nullable(),
-  githubHandle: z.string().nullable(),
-});
-
-/**
- * One product as it appears inside a collection. Carries the parent org block
- * so the chip can render the org's avatar (products don't have their own).
- */
-export const CollectionMemberProductSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  description: z.string().nullable(),
-  org: ProductParentOrgSchema,
-});
-
-/**
- * Mixed-kind member entry. `kind` discriminates: `org` carries the org block at
- * the top level; `product` carries the product fields plus a `org` parent block.
- * Used by `GET /v1/collections/:slug` (`members` field) and the new
- * `previewMembers` on `GET /v1/collections`.
- */
-export const CollectionMemberSchema = z.discriminatedUnion("kind", [
-  CollectionMemberOrgSchema.extend({ kind: z.literal("org") }),
-  CollectionMemberProductSchema.extend({ kind: z.literal("product") }),
-]);
-
-/**
- * Row on `GET /v1/collections`. `previewMembers` (the new mixed-kind preview)
- * is the first few visible members so the list page can render inline avatars
- * without a second round trip. `previewOrgs` is the legacy org-only preview,
- * retained for back-compat — clients should migrate to `previewMembers`.
- */
-export const CollectionListItemSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  description: z.string().nullable(),
-  memberCount: z.number().int().min(0),
-  /** Whether the collection is promoted on the homepage. Filterable via `?featured=1`. */
-  isFeatured: z.boolean(),
-  /** Mixed-kind preview (org + product). Cap matches `previewOrgs`. */
-  previewMembers: z.array(CollectionMemberSchema).optional(),
-  /** Legacy org-only preview. Populated with the org-kind subset of `previewMembers`. */
-  previewOrgs: z.array(CollectionMemberOrgSchema).optional(),
-});
-
-export const CollectionListResponseSchema = z.array(CollectionListItemSchema);
-
-/**
- * Returned by `GET /v1/collections/:slug`.
- *
- * `members` is the mixed-kind canonical list. `orgs` is the legacy org-only
- * field, populated with the org-kind subset of `members` for back-compat —
- * new clients should consume `members`.
- */
-export const CollectionDetailSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  description: z.string().nullable(),
-  /** Whether the collection is promoted on the homepage. */
-  isFeatured: z.boolean(),
-  /** Per-collection enable toggle for the nightly daily-summary generation. */
-  dailySummaryEnabled: z.boolean(),
-  /** Whether the collection generates weekly digests (gates the email-subscribe toggle). */
-  weeklyDigestEnabled: z.boolean(),
-  members: z.array(CollectionMemberSchema),
-  /** @deprecated Use `members`. Org-only subset, kept for back-compat. */
-  orgs: z.array(CollectionMemberOrgSchema),
-});
-
-/**
- * Cross-member 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(),
-  /**
-   * 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`. */
-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(),
-  isFeatured: z.boolean(),
-  /** Per-collection enable toggle for the nightly daily-summary generation. */
-  dailySummaryEnabled: z.boolean(),
-  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(),
-  /** Promote / demote the collection on the homepage. */
-  isFeatured: z.boolean().optional(),
-  /** Enable or disable the nightly daily-summary generation for this collection. */
-  dailySummaryEnabled: z.boolean().optional(),
-  /** Enable or disable the nightly weekly-digest generation for this collection (on by default for new collections). */
-  weeklyDigestEnabled: z.boolean().optional(),
-});
-
-/**
- * One member entry accepted by the member-write endpoints.
- *
- * Exactly one of `orgId` / `orgSlug` / `productId` / `productSlug` must be
- * present. When both an id and a slug are supplied for the same kind, the id
- * wins. Mixing kinds (e.g. `orgId` + `productSlug`) is rejected by the handler.
- *
- * Product slug is resolved within an org — supply either `productId`
- * (`prod_…`, globally unique) or pair `productSlug` with `orgSlug`/`orgId`.
- * `productSlug` alone is rejected.
- */
-export const CollectionMemberInputSchema = z.object({
-  orgId: z.string().optional(),
-  orgSlug: z.string().optional(),
-  productId: z.string().optional(),
-  productSlug: 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. The field is still named `orgs` for back-compat — it accepts
- * any `CollectionMemberInput`, org or product.
- */
-export const ReplaceCollectionMembersRequestSchema = z.object({
-  orgs: z.array(CollectionMemberInputSchema),
-});
-
-/**
- * Resolved member returned by `PUT /v1/collections/:slug/members` and `POST
- * /v1/collections/:slug/members`. `kind` discriminates which id field is
- * populated. `orgId` is also set on legacy callers that only used org
- * membership — for clean dispatch, dispatch on `kind`.
- */
-export const ResolvedCollectionMemberSchema = z.object({
-  kind: z.enum(["org", "product"]),
-  orgId: z.string().optional(),
-  productId: z.string().optional(),
-  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`. `orgId` stays populated
- * for org-kind members so existing CLI callers don't break; `kind` +
- * `productId` are the canonical fields for new code.
- */
-export const AddCollectionMemberResponseSchema = z.object({
-  collectionSlug: z.string(),
-  kind: z.enum(["org", "product"]),
-  orgId: z.string().optional(),
-  productId: z.string().optional(),
-  position: z.number().int(),
-});
-
-/** One daily summary row returned by `GET /v1/collections/:slug/daily-summaries`. */
-export const CollectionDailySummarySchema = z.object({
-  /** Eastern calendar day, YYYY-MM-DD. */
-  date: z.string(),
-  title: z.string(),
-  summary: z.string(),
-  takeaways: z.array(z.string()),
-  releaseCount: z.number().int().nonnegative(),
-});
-
-/** Response envelope for `GET /v1/collections/:slug/daily-summaries`. */
-export const CollectionDailySummariesResponseSchema = z.object({
-  summaries: z.array(CollectionDailySummarySchema),
-});
-
-// ── Weekly digests ────────────────────────────────────────────────
-
-/** List row on `GET /v1/collections/:slug/digests` — newest-first, no body. */
-export const CollectionWeeklyDigestListItemSchema = z.object({
-  id: z.string(),
-  /** ET Monday starting the covered week, YYYY-MM-DD. */
-  weekStart: z.string(),
-  title: z.string(),
-  intro: z.string(),
-  releaseCount: z.number().int().nonnegative(),
-  generatedAt: z.string(),
-});
-
-/** Cursor pagination shape matches the other paginated list surfaces. */
-export const CollectionWeeklyDigestsResponseSchema = z.object({
-  digests: z.array(CollectionWeeklyDigestListItemSchema),
-  pagination: CollectionFeedPaginationSchema,
-});
-
-/** Minimal, server-resolved release info for a digest's "Releases covered" list. */
-export const DigestCoveredReleaseSchema = z.object({
-  id: z.string(),
-  title: z.string(),
-  /** Internal `/release/*` path — fallback link only (see `url`). */
-  path: z.string(),
-  /** Upstream source URL. Primary link target when http(s); optional for older servers. */
-  url: z.string().nullable().optional(),
-  org: z.object({
-    slug: z.string(),
-    name: z.string(),
-    avatarUrl: z.string().nullable().optional(),
-    githubHandle: z.string().nullable().optional(),
-  }),
-  /** Product the release's source belongs to, when it has one. */
-  product: z.object({ slug: z.string(), name: z.string() }).nullable().optional(),
-  /**
-   * AI-scored importance 1–5. Null when unscored; optional for older
-   * servers. Cheap to project on the existing hydrate — powers the flame
-   * marker on the collapsed "Releases covered" list.
-   */
-  importance: ImportanceScoreSchema,
-  /**
-   * Per-category item counts from the AI release-content pass. Null when the
-   * row hasn't been summarized; optional for older servers. Powers the
-   * digest page's week-at-a-glance treemap.
-   */
-  composition: ReleaseCompositionSchema.nullable().optional(),
-  /**
-   * ISO publish timestamp, as stored. Null when the source gave none;
-   * optional for older servers. A date-only source is stored at exactly
-   * `T00:00:00.000Z`. Powers the digest week replay's day placement.
-   */
-  publishedAt: z.string().nullable().optional(),
-});
-
-/** One `###` section of a digest body, parsed server-side. */
-export const DigestSectionSchema = z.object({
-  heading: z.string(),
-  /** Slug the digest page renders as the heading's `id` — link target `#anchor`. */
-  anchor: z.string(),
-  /** First sentence of the section, plain text. */
-  lede: z.string(),
-  /** Cited release ids in first-seen order; resolve against the detail's `releases`. */
-  releaseIds: z.array(z.string()),
-  /**
-   * The section's cited releases, resolved server-side in `releaseIds` order.
-   * Ids that no longer resolve are dropped, so `releases.length` can be less
-   * than `releaseIds.length`. Optional for older servers.
-   */
-  releases: z.array(DigestCoveredReleaseSchema).optional(),
-});
-
-/** Full row returned by `GET /v1/collections/:slug/digests/:weekStart` and
- *  `GET /v1/collections/:slug/digests/latest`. */
-export const CollectionWeeklyDigestDetailSchema = z.object({
-  id: z.string(),
-  weekStart: z.string(),
-  title: z.string(),
-  intro: z.string(),
-  body: z.string(),
-  releaseIds: z.array(z.string()),
-  releaseCount: z.number().int().nonnegative(),
-  generatedAt: z.string(),
-  /** Server-resolved minimal release info for every id in `releaseIds` that
-   *  still resolves — a release deleted/suppressed after generation is
-   *  dropped rather than surfaced as a dead link. */
-  releases: z.array(DigestCoveredReleaseSchema),
-  /** Parsed `###` sections. Optional for older servers. */
-  sections: z.array(DigestSectionSchema).optional(),
-});

package/src/schemas/datasets.ts

@@ -1,31 +0,0 @@
-import { z } from "zod";
-
-export const DatasetDescriptionSchema = z.object({
-  name: z.string().trim().min(1).max(200),
-  description: z.string().trim().min(50).max(5000),
-});
-
-/** Stored under source.metadata.dataset. Null removes the override. */
-export const SourceDatasetSettingsSchema = DatasetDescriptionSchema.partial()
-  .extend({
-    enabled: z.boolean().optional(),
-  })
-  .strict();
-export type SourceDatasetSettings = z.infer<typeof SourceDatasetSettingsSchema>;
-export type DatasetDescription = z.infer<typeof DatasetDescriptionSchema>;
-export interface AdminDatasetSource {
-  id: string;
-  slug: string;
-  name: string;
-  orgSlug: string | null;
-  orgName: string | null;
-  defaultEnabled: boolean;
-  settings: SourceDatasetSettings | null;
-  effective: DatasetDescription | null;
-  blockedReasons: string[];
-}
-export interface AdminDatasetsResponse {
-  sources: AdminDatasetSource[];
-  pagination: { page: number; limit: number; hasMore: boolean };
-  query: string;
-}

package/src/schemas/errors.test.ts

@@ -1,55 +0,0 @@
-import { expect, test } from "bun:test";
-import { ERROR_TYPES } from "@buildinternet/releases-core/errors";
-import { errorEnvelopeSchema, decodeApiError, isApiError } from "./errors";
-
-test("a valid envelope parses", () => {
-  const ok = errorEnvelopeSchema.safeParse({
-    error: { code: "not_found", type: "not_found", message: "Nope" },
-  });
-  expect(ok.success).toBe(true);
-});
-
-test("malformed envelopes reject", () => {
-  expect(errorEnvelopeSchema.safeParse({}).success).toBe(false);
-  expect(
-    errorEnvelopeSchema.safeParse({
-      error: { code: 1, type: "not_found", message: "x" },
-    }).success,
-  ).toBe(false);
-});
-
-test("schema type enum matches the core union (anti-drift invariant 2)", () => {
-  const options = errorEnvelopeSchema.shape.error.shape.type.options;
-  expect([...options].sort()).toEqual([...ERROR_TYPES].sort());
-});
-
-test("decodeApiError normalizes an unknown type to internal, preserves unknown code", () => {
-  const decoded = decodeApiError({
-    error: { code: "brand_new_code", type: "teapot", message: "?" },
-  });
-  expect(decoded.type).toBe("internal");
-  expect(decoded.code).toBe("brand_new_code");
-});
-
-test("decodeApiError degrades a malformed body without throwing", () => {
-  expect(decodeApiError(null)).toEqual({
-    code: "internal_error",
-    type: "internal",
-    message: "Unknown error",
-  });
-});
-
-test("decodeApiError carries details through when present", () => {
-  const decoded = decodeApiError({
-    error: { code: "not_found", type: "not_found", message: "x", details: { id: "src_1" } },
-  });
-  expect(decoded.details).toEqual({ id: "src_1" });
-});
-
-test("isApiError matches shape and optional code", () => {
-  const body = { error: { code: "not_found", type: "not_found", message: "x" } };
-  expect(isApiError(body)).toBe(true);
-  expect(isApiError(body, "not_found")).toBe(true);
-  expect(isApiError(body, "conflict")).toBe(false);
-  expect(isApiError({ nope: true })).toBe(false);
-});

package/src/schemas/errors.ts

@@ -1,81 +0,0 @@
-import { z } from "zod";
-import { ERROR_TYPES, type ErrorType, type ErrorCode } from "@buildinternet/releases-core/errors";
-
-/**
- * The one on-the-wire error shape. `type` is constrained (documents the
- * contract, powers OpenAPI); `code` is an open string so a new server code an
- * older client doesn't recognize still parses. The throwable hierarchy in
- * `@releases/lib/releases-error` serializes to this via `toWire()`.
- */
-export const errorEnvelopeSchema = z
-  .object({
-    error: z.object({
-      code: z
-        .string()
-        .describe(
-          "Stable, specific machine code (e.g. `not_found`, `rate_limited`). Never reworded once shipped, but open-ended — branch defensively on codes you don't recognize.",
-        ),
-      type: z
-        .enum(ERROR_TYPES)
-        .describe(
-          "Coarse category from a fixed set; determines the HTTP status. Safe to switch on.",
-        ),
-      message: z.string().describe("Human-readable explanation. May change; do not parse."),
-      details: z
-        .unknown()
-        .optional()
-        .describe(
-          "Optional structured context carried by select codes (e.g. `database_not_initialized`).",
-        ),
-    }),
-  })
-  .describe(
-    "Standardized error response — every non-2xx response uses this shape. Switch on `error.type` (fixed set → HTTP status) or match `error.code` (specific, stable). See https://releases.sh/docs/api/errors.",
-  );
-
-export type ErrorEnvelope = z.infer<typeof errorEnvelopeSchema>;
-
-/**
- * Lenient variant used ONLY for decode: `type` is left open so an unknown
- * category (older client, newer server) does not reject.
- */
-const lenientEnvelopeSchema = z.object({
-  error: z.object({
-    code: z.string(),
-    type: z.string(),
-    message: z.string(),
-    details: z.unknown().optional(),
-  }),
-});
-
-export interface DecodedApiError {
-  code: string;
-  type: ErrorType;
-  message: string;
-  details?: unknown;
-}
-
-/**
- * Parse an API error body into a typed, normalized shape. Forward-compatible: a
- * malformed body or an unknown `type` degrades to `internal` and never throws.
- */
-export function decodeApiError(body: unknown): DecodedApiError {
-  const parsed = lenientEnvelopeSchema.safeParse(body);
-  if (!parsed.success) {
-    return { code: "internal_error", type: "internal", message: "Unknown error" };
-  }
-  const { code, type, message, details } = parsed.data.error;
-  const normalizedType: ErrorType = (ERROR_TYPES as readonly string[]).includes(type)
-    ? (type as ErrorType)
-    : "internal";
-  return details === undefined
-    ? { code, type: normalizedType, message }
-    : { code, type: normalizedType, message, details };
-}
-
-/** True if `body` is an API error envelope; if `code` is given, also matches it. */
-export function isApiError(body: unknown, code?: ErrorCode): boolean {
-  const parsed = lenientEnvelopeSchema.safeParse(body);
-  if (!parsed.success) return false;
-  return code === undefined || parsed.data.error.code === code;
-}