@buildinternet/releases-api-types 0.52.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@buildinternet/releases-core": "^0.30.0",
+    "@buildinternet/releases-core": "^0.31.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -21,6 +21,11 @@ import type {
   OpenRouterCatalogModelSchema,
   AiLaneModelsResponseSchema,
 } from "./schemas/ai-models.js";
+import type {
+  MarketingClassifierThresholdPutSchema,
+  MarketingFilteredSourceSchema,
+  MarketingClassifierStateSchema,
+} from "./schemas/marketing-classifier.js";
 import type {
   MediaItemSchema,
   PaginationSchema,
@@ -216,6 +221,12 @@ import type {
   FeedbackUpdateBodySchema,
   FeedbackDeleteResponseSchema,
 } from "./schemas/feedback.js";
+import type {
+  ClassificationSummarySchema,
+  ClassificationRecentResponseSchema,
+  ClassificationRecentItemSchema,
+} from "./schemas/classifications.js";
+import type { SemanticAlertSummarySchema } from "./schemas/semantic-alert-summary.js";
 import type {
   RecommendationNotifyAddedBodySchema,
   RecommendationNotifyAddedResultSchema,
@@ -304,6 +315,13 @@ export {
   OpenRouterCatalogModelSchema,
   AiLaneModelsResponseSchema,
 } from "./schemas/ai-models.js";
+export {
+  MarketingClassifierThresholdPutSchema,
+  MarketingFilteredSourceSchema,
+  MarketingClassifierStateSchema,
+  MARKETING_THRESHOLD_MIN,
+  MARKETING_THRESHOLD_MAX,
+} from "./schemas/marketing-classifier.js";
 export {
   OrgListItemSchema,
   OrgListResponseSchema,
@@ -551,6 +569,12 @@ export {
   FeedbackUpdateBodySchema,
   FeedbackDeleteResponseSchema,
 } from "./schemas/feedback.js";
+export {
+  ClassificationSummarySchema,
+  ClassificationRecentResponseSchema,
+  ClassificationRecentItemSchema,
+} from "./schemas/classifications.js";
+export { SemanticAlertSummarySchema } from "./schemas/semantic-alert-summary.js";
 export {
   RecommendationNotifyAddedBodySchema,
   RecommendationNotifyAddedResultSchema,
@@ -629,6 +653,10 @@ export type AiLaneState = z.infer<typeof AiLaneStateSchema>;
 export type OpenRouterCatalogModel = z.infer<typeof OpenRouterCatalogModelSchema>;
 export type AiLaneModelsResponse = z.infer<typeof AiLaneModelsResponseSchema>;
 
+export type MarketingClassifierThresholdPut = z.infer<typeof MarketingClassifierThresholdPutSchema>;
+export type MarketingFilteredSource = z.infer<typeof MarketingFilteredSourceSchema>;
+export type MarketingClassifierState = z.infer<typeof MarketingClassifierStateSchema>;
+
 // ── Stub tier (#1947) ──
 
 export type OrgStatus = z.infer<typeof OrgStatusSchema>;
@@ -1240,6 +1268,46 @@ export interface TestUserWebhookResponse {
   eventId: string;
 }
 
+// ── Workspace webhooks ──
+
+/** Workspace member role (Better Auth `member.role`, not `user.role`). */
+export type WorkspaceMemberRole = "owner" | "admin" | "member";
+
+/**
+ * A workspace-owned webhook subscription row (no signing secret). Workspace
+ * webhooks are org-scoped only; there is no workspace follows scope.
+ */
+export interface WorkspaceWebhookSubscription extends Omit<
+  UserWebhookSubscription,
+  "userId" | "scope"
+> {
+  workspaceId: string;
+  scope: "org";
+}
+
+/** List item returned by GET /v1/workspaces/:workspaceId/webhooks. */
+export interface WorkspaceWebhookListItem extends Omit<UserWebhookListItem, "scope"> {
+  workspaceId: string;
+  scope: "org";
+}
+
+/** GET /v1/workspaces/:workspaceId/webhooks response. */
+export interface WorkspaceWebhookListResponse {
+  subscriptions: WorkspaceWebhookListItem[];
+  /** The caller's role in the workspace. */
+  role: WorkspaceMemberRole;
+  /** True for owners and admins: create, edit, rotate, and delete. Members can view and test. */
+  canManage: boolean;
+}
+
+/** POST /v1/workspaces/:workspaceId/webhooks response — signing key shown once (omitted for slack/discord). */
+export interface CreateWorkspaceWebhookResponse
+  extends WorkspaceWebhookSubscription, UserWebhookDeliveryHealth {
+  orgSlug: string | null;
+  orgName: string | null;
+  signingKey?: string;
+}
+
 /** One Analytics Engine delivery-attempt row from GET …/webhooks/:id/deliveries. */
 export interface WebhookDeliveryRow {
   timestamp?: string;
@@ -1269,15 +1337,88 @@ export interface DigestPrefsRequest {
   cadence: DigestCadence;
 }
 
+// ── Semantic alerts (#2304 Phase 1) ──
+
+/** Hard cap on saved semantic alerts per account. Enforced on create. */
+export const SEMANTIC_ALERT_MAX_PER_USER = 5;
+
+/** Freeform interest text, after trim. User-private — never an analytics label. */
+export const SEMANTIC_ALERT_QUERY_MAX_CHARS = 500;
+
+/** Default selected-choice probability. Phase 2 matcher uses this unless overridden. */
+export const SEMANTIC_ALERT_THRESHOLD_DEFAULT = 0.8;
+
+export const SEMANTIC_ALERT_THRESHOLD_MIN = 0.5;
+export const SEMANTIC_ALERT_THRESHOLD_MAX = 1;
+
+/**
+ * v1 candidate pool. Matching (Phase 2) scores only releases that already hit
+ * the caller's follow graph. Not a per-alert setting.
+ */
+export const SEMANTIC_ALERT_CANDIDATE_POOL = "follows" as const;
+
+/** One saved semantic alert. Query text is returned only to the owning user. */
+export interface SemanticAlert {
+  id: string;
+  query: string;
+  enabled: boolean;
+  /** Inclusive match probability in [0.50, 1.00]. Default 0.80. */
+  threshold: number;
+  /** Stored preference. Phase 1 does not send email. */
+  deliverEmail: boolean;
+  /** Stored preference. Phase 1 does not send webhook deliveries. */
+  deliverWebhook: boolean;
+  /** Optional link to one of the caller's `/v1/me/webhooks` subscriptions. */
+  webhookSubscriptionId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Claimed-match activity for one alert (#2320). Counts are rows in
+ * `semantic_alert_matches` (notified matches only — below-threshold scores
+ * are not stored). Present on list and notifications-bootstrap rows.
+ */
+export interface SemanticAlertActivity {
+  /** Matches in the last 7 days. Included in `matches30d`. */
+  matches7d: number;
+  /** Matches in the last 30 days. */
+  matches30d: number;
+  /** Newest claim, or null when the alert has never matched. */
+  lastMatchedAt: string | null;
+  /** Newest claim's release, when that row still exists. */
+  lastMatch: {
+    releaseId: string;
+    title: string;
+    /** Canonical site path, `/release/rel_…`. */
+    path: string;
+  } | null;
+}
+
+/** A list row: the saved alert plus recent match activity. */
+export interface SemanticAlertListItem extends SemanticAlert {
+  activity: SemanticAlertActivity;
+}
+
+/** GET /v1/me/semantic-alerts. `candidatePool` is the locked v1 scope. */
+export interface SemanticAlertListResponse {
+  alerts: SemanticAlertListItem[];
+  candidatePool: typeof SEMANTIC_ALERT_CANDIDATE_POOL;
+  maxAlerts: number;
+}
+
 /**
  * GET /v1/me/settings/notifications — one-shot bootstrap for `/account/notifications`.
  * Composes digest cadence + feed token + webhook list so the settings page can
  * render with a single round-trip instead of three independent mounts.
+ * `semanticAlerts` is `null` when `semantic-alerts-enabled` is off (hide the
+ * section); an array, possibly empty, when the lane is on.
  */
 export interface NotificationSettingsResponse {
   cadence: DigestCadence;
   feedToken: FeedToken | null;
   webhooks: UserWebhookListItem[];
+  semanticAlerts: SemanticAlertListItem[] | null;
 }
 
 /**
@@ -1290,6 +1431,24 @@ export interface DeveloperSettingsResponse {
   apiKeys: UserApiKey[] | null;
 }
 
+/** GET /v1/me/workspaces — one row per workspace the caller belongs to. */
+export interface MeWorkspace {
+  /** Better Auth organization id. */
+  id: string;
+  name: string;
+  slug: string;
+  logo: string | null;
+  /** Workspace membership role (`member.role`, not `user.role`). */
+  role: WorkspaceMemberRole;
+  /** The caller's active workspace (see docs/architecture/workspaces.md). */
+  active: boolean;
+  createdAt: string;
+}
+
+export interface MeWorkspacesResponse {
+  workspaces: MeWorkspace[];
+}
+
 // ── Search ──
 
 export type SearchOrgHit = z.infer<typeof SearchOrgHitSchema>;
@@ -1755,6 +1914,13 @@ 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>;
+
+export type SemanticAlertSummary = z.infer<typeof SemanticAlertSummarySchema>;
+
 // ── Recommendations ──
 export type RecommendationNotifyAddedBody = z.infer<typeof RecommendationNotifyAddedBodySchema>;
 export type RecommendationNotifyAddedResult = z.infer<typeof RecommendationNotifyAddedResultSchema>;

package/src/schemas/classifications.ts

@@ -0,0 +1,109 @@
+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/marketing-classifier.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+export const MARKETING_THRESHOLD_MIN = 0.5;
+export const MARKETING_THRESHOLD_MAX = 0.99;
+
+/** PUT /v1/admin/marketing-classifier — set the suppression threshold. */
+export const MarketingClassifierThresholdPutSchema = z
+  .object({
+    threshold: z.number().min(MARKETING_THRESHOLD_MIN).max(MARKETING_THRESHOLD_MAX),
+  })
+  .strict();
+
+export const MarketingFilteredSourceSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: z.string(),
+  orgSlug: z.string().nullable(),
+  hint: z.string().nullable(),
+  recentReleaseCount: z.number(),
+});
+
+/** GET/PUT /v1/admin/marketing-classifier response. */
+export const MarketingClassifierStateSchema = z.object({
+  threshold: z.number(),
+  defaultThreshold: z.number(),
+  updatedAt: z.string().nullable(),
+  sources: z.array(MarketingFilteredSourceSchema),
+});

package/src/schemas/semantic-alert-summary.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/**
+ * Admin interest-alert quality (`GET /v1/admin/semantic-alerts/summary`).
+ * Decisions live in the classifications Analytics Engine dataset with
+ * `blob4 = semantic-alert`. This is the hydrated read model. Alert query
+ * text is not a field — it is not stored on the points.
+ */
+
+const ProbabilityBinSchema = z.object({
+  /** Inclusive. Width is 0.1. `0.8` is the start of the default-threshold bin. */
+  start: z.number(),
+  /** Exclusive, except the last bin (`0.9`–`1`) which includes `1`. */
+  end: z.number(),
+  count: z.number(),
+});
+
+const SemanticAlertDispositionCountsSchema = z.object({
+  matched: z.number(),
+  belowThreshold: z.number(),
+  failed: z.number(),
+});
+
+/**
+ * `GET /v1/admin/semantic-alerts/summary`.
+ *
+ * `scored` is matched + below threshold (a probability came back).
+ * `matchRate` is matched / scored, or null when nothing was scored.
+ * `failed` is fail-closed and stays out of the rate.
+ * Cost is not on these points; `meta.costLane` names the `ai_usage` lane.
+ */
+export const SemanticAlertSummarySchema = z.object({
+  after: z.string(),
+  before: z.string(),
+  bucket: z.enum(["hour", "day"]),
+  totals: SemanticAlertDispositionCountsSchema.extend({
+    scored: z.number(),
+    matchRate: z.number().nullable(),
+  }),
+  series: z.array(
+    SemanticAlertDispositionCountsSchema.extend({
+      t: z.string(),
+    }),
+  ),
+  failures: z.array(
+    z.object({
+      category: z.enum(["provider_error", "invalid_probability", "unknown"]),
+      count: z.number(),
+    }),
+  ),
+  probability: z.object({
+    /** Default alert threshold. Each point stores its own threshold separately. */
+    defaultThreshold: z.literal(0.8),
+    bins: z.array(ProbabilityBinSchema),
+    /** Sampled rows whose probability double is `< 0` (the absent sentinel). */
+    missing: z.number(),
+  }),
+  meta: z.object({
+    dataset: z.string(),
+    retentionDays: z.literal(90),
+    sampled: z.literal(true),
+    /** `ai_usage` lane that carries JEV cost. Not summed from these points. */
+    costLane: z.literal("semantic-alert-match"),
+  }),
+});