@buildinternet/releases-api-types 0.52.0 → 0.52.1

package/package.json

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

@@ -216,6 +216,11 @@ import type {
   FeedbackUpdateBodySchema,
   FeedbackDeleteResponseSchema,
 } from "./schemas/feedback.js";
+import type {
+  ClassificationSummarySchema,
+  ClassificationRecentResponseSchema,
+  ClassificationRecentItemSchema,
+} from "./schemas/classifications.js";
 import type {
   RecommendationNotifyAddedBodySchema,
   RecommendationNotifyAddedResultSchema,
@@ -551,6 +556,11 @@ export {
   FeedbackUpdateBodySchema,
   FeedbackDeleteResponseSchema,
 } from "./schemas/feedback.js";
+export {
+  ClassificationSummarySchema,
+  ClassificationRecentResponseSchema,
+  ClassificationRecentItemSchema,
+} from "./schemas/classifications.js";
 export {
   RecommendationNotifyAddedBodySchema,
   RecommendationNotifyAddedResultSchema,
@@ -1755,6 +1765,11 @@ export type FeedbackListResponse = z.infer<typeof FeedbackListResponseSchema>;
 export type FeedbackUpdateBody = z.infer<typeof FeedbackUpdateBodySchema>;
 export type FeedbackDeleteResponse = z.infer<typeof FeedbackDeleteResponseSchema>;
 
+// ── Classification analytics ──
+export type ClassificationSummary = z.infer<typeof ClassificationSummarySchema>;
+export type ClassificationRecentResponse = z.infer<typeof ClassificationRecentResponseSchema>;
+export type ClassificationRecentItem = z.infer<typeof ClassificationRecentItemSchema>;
+
 // ── Recommendations ──
 export type RecommendationNotifyAddedBody = z.infer<typeof RecommendationNotifyAddedBodySchema>;
 export type RecommendationNotifyAddedResult = z.infer<typeof RecommendationNotifyAddedResultSchema>;

package/src/schemas/classifications.ts

@@ -0,0 +1,105 @@
+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. `0.8` is the start of the threshold bin. */
+  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({
+    threshold: z.literal(0.8),
+    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(),
+});