@buildinternet/releases-api-types 0.52.1 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.52.1",
+  "version": "0.54.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,
@@ -221,6 +226,7 @@ import type {
   ClassificationRecentResponseSchema,
   ClassificationRecentItemSchema,
 } from "./schemas/classifications.js";
+import type { SemanticAlertSummarySchema } from "./schemas/semantic-alert-summary.js";
 import type {
   RecommendationNotifyAddedBodySchema,
   RecommendationNotifyAddedResultSchema,
@@ -269,6 +275,7 @@ import type {
   CollectionWeeklyDigestListItemSchema,
   CollectionWeeklyDigestsResponseSchema,
   DigestCoveredReleaseSchema,
+  DigestSectionSchema,
   CollectionWeeklyDigestDetailSchema,
 } from "./schemas/collections.js";
 import type {
@@ -309,6 +316,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,
@@ -561,6 +575,7 @@ export {
   ClassificationRecentResponseSchema,
   ClassificationRecentItemSchema,
 } from "./schemas/classifications.js";
+export { SemanticAlertSummarySchema } from "./schemas/semantic-alert-summary.js";
 export {
   RecommendationNotifyAddedBodySchema,
   RecommendationNotifyAddedResultSchema,
@@ -611,6 +626,7 @@ export {
   CollectionWeeklyDigestListItemSchema,
   CollectionWeeklyDigestsResponseSchema,
   DigestCoveredReleaseSchema,
+  DigestSectionSchema,
   CollectionWeeklyDigestDetailSchema,
 } from "./schemas/collections.js";
 export {
@@ -639,6 +655,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>;
@@ -1250,6 +1270,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;
@@ -1279,15 +1339,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;
 }
 
 /**
@@ -1300,6 +1433,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>;
@@ -1657,6 +1808,7 @@ export type CollectionDailySummariesResponse = z.infer<
 export type CollectionWeeklyDigestListItem = z.infer<typeof CollectionWeeklyDigestListItemSchema>;
 export type CollectionWeeklyDigestsResponse = z.infer<typeof CollectionWeeklyDigestsResponseSchema>;
 export type DigestCoveredRelease = z.infer<typeof DigestCoveredReleaseSchema>;
+export type DigestSection = z.infer<typeof DigestSectionSchema>;
 export type CollectionWeeklyDigestDetail = z.infer<typeof CollectionWeeklyDigestDetailSchema>;
 
 // ── Releases (enriched) ──
@@ -1770,6 +1922,8 @@ 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

@@ -11,7 +11,8 @@ const ClassificationOriginFilterSchema = z.enum(["ingest", "manual", "eval", "al
 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. */
+  /** 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(),
@@ -65,7 +66,10 @@ export const ClassificationSummarySchema = z.object({
     }),
   ),
   probability: z.object({
-    threshold: z.literal(0.8),
+    /** 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,
   }),

package/src/schemas/collections.ts

@@ -273,8 +273,18 @@ export const CollectionWeeklyDigestsResponseSchema = z.object({
 export const DigestCoveredReleaseSchema = z.object({
   id: z.string(),
   title: z.string(),
+  /** Internal `/release/*` path — fallback link only (see `url`). */
   path: z.string(),
-  org: z.object({ slug: z.string(), name: 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
@@ -283,6 +293,17 @@ export const DigestCoveredReleaseSchema = z.object({
   importance: ImportanceScoreSchema,
 });
 
+/** 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()),
+});
+
 /** Full row returned by `GET /v1/collections/:slug/digests/:weekStart`. */
 export const CollectionWeeklyDigestDetailSchema = z.object({
   id: z.string(),
@@ -297,4 +318,6 @@ export const CollectionWeeklyDigestDetailSchema = z.object({
    *  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/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/search.ts

@@ -110,6 +110,14 @@ export const SearchReleaseHitSchema = z.object({
   summary: z.string(),
   titleGenerated: z.string().nullable().optional(),
   titleShort: z.string().nullable().optional(),
+  /**
+   * The release's upstream source URL, when it has one. Lets the web link
+   * search/lookup hits straight to the original page instead of the
+   * noindexed `/release/<id>` stub — see `releaseLinkProps()` in
+   * `web/src/lib/release-link.ts`. Optional for older servers / mid-deploy
+   * pin tolerance.
+   */
+  url: z.string().nullable().optional(),
   /**
    * AI-scored importance 1–5 (5=landmark, 1=housekeeping). Null when
    * unscored; optional for older servers / mid-deploy pin tolerance.
@@ -213,6 +221,9 @@ export const LookupResultPayloadSchema = z.object({
         publishedAt: z.string().nullable(),
         /** First image/gif thumbnail; null when the release has none. */
         thumbnail: ReleaseThumbnailSchema.nullable().optional(),
+        /** The release's upstream source URL, when it has one. See
+         *  `SearchReleaseHitSchema.url`. */
+        url: z.string().nullable().optional(),
       }),
     )
     .optional(),

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

package/src/schemas/shared.ts

@@ -206,8 +206,9 @@ export const OverviewCitationSchema = z.object({
   releaseId: z.string().nullable().optional(),
   /**
    * Canonical web URL of the on-registry release page for this source, when
-   * `releaseId` resolved (#1934). The Sources footer links here (internal,
-   * crawlable) in preference to the external `sourceUrl`.
+   * `releaseId` resolved (#1934). Kept for machine consumers; the web Sources
+   * footer links `sourceUrl` (the #2218 link policy — `/release/*` pages are
+   * noindexed).
    */
   releaseWebUrl: z.string().nullable().optional(),
   /**