@buildinternet/releases-api-types 0.58.3 → 0.60.0

package/dist/schemas/search.js

@@ -0,0 +1,258 @@
+import { z } from "zod";
+import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
+import { AppStoreSourceInfoSchema, ImportanceScoreSchema, MediaItemSchema, OrgStatusSchema, ReleaseThumbnailSchema, ReleaseTypeSchema, VideoSourceInfoSchema, } from "./shared.js";
+import { SourceTypeSchema } from "./sources.js";
+import { LookupStatusSchema } from "./lookups.js";
+import { CollectionMemberSchema } from "./collections.js";
+/**
+ * Org hit on the unified `/v1/search` response. The list is built either
+ * from `searchOrgs` LIKE matches or, when `?domain=` resolves, from a
+ * single-row "scoped org" projection — both produce the same wire shape.
+ *
+ * `category` is loose (`z.string().nullable()`) rather than the canonical
+ * `CategorySchema` enum because the scoped-org projection passes the raw
+ * DB column through without going through `resolveCategoryInput`; legacy
+ * rows may carry deprecated slugs that haven't been migrated yet. Tighten
+ * once #689 (category overlay backfill) lands across the prod data set.
+ */
+export const SearchOrgHitSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    domain: z.string().nullable(),
+    avatarUrl: z.string().nullable(),
+    category: z.string().nullable(),
+    /**
+     * Org tier (#1947/#2034). Optional for mid-deploy tolerance; absent ⇒
+     * `"tracked"`. Lets search render the icon-only stub marker (#2031 parity).
+     */
+    status: OrgStatusSchema.optional(),
+    /**
+     * Org-level alternate domains (product-scoped aliases excluded, sorted),
+     * for the `+N` hover on the origin domain — the anti-impersonation anchor
+     * mirrored from the catalog row (#2031/#2034). Optional; absent ⇒ none.
+     */
+    aliasDomains: z.array(z.string()).optional(),
+});
+/**
+ * Unified catalog entry — either a product row or a standalone source
+ * presented as product-shaped. `entryType` discriminates between the two
+ * row shapes (`"product"` vs `"source"`). `kind` carries the entity
+ * taxonomy (platform/sdk/mobile/…). `entryType` (not `type`) because
+ * source rows already carry `type: github|scrape|feed|agent` on the wire.
+ */
+export const SearchCatalogHitSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    orgSlug: z.string().nullable(),
+    orgName: z.string().nullable(),
+    /** Owning org's avatar URL, for a small inline byline avatar. Products have
+     *  no avatar of their own, so the web row anchors on the org's instead. */
+    orgAvatarUrl: z.string().nullable().optional(),
+    // Loose `z.string().nullable()` rather than the canonical `CategorySchema`
+    // enum because `foldSourcesIntoCatalog` and the catalog-search handlers
+    // pass `s.productCategory` / `o.category` through without validating
+    // against `resolveCategoryInput`. Legacy rows may carry deprecated slugs
+    // that haven't been migrated yet. Tighten once #689 (category overlay
+    // backfill) lands across the prod data set.
+    category: z.string().nullable(),
+    entryType: z.enum(["product", "source"]),
+    kind: z.enum(KIND_VALUES).nullable().optional(),
+    sourceSlug: z.string().optional(),
+    sourceType: SourceTypeSchema.optional(),
+});
+export const SearchSourceHitSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    type: SourceTypeSchema,
+    orgSlug: z.string().nullable(),
+    orgName: z.string().nullable(),
+    productSlug: z.string().nullable(),
+    stars: z.number().int().min(0).nullable().optional(),
+});
+export const SearchReleaseHitSchema = z.object({
+    id: z.string(),
+    sourceSlug: z.string(),
+    sourceName: z.string(),
+    // Loose `z.string()` rather than `SourceTypeSchema` because the
+    // release-hit hydration path reads `sources.type` straight from the DB
+    // without re-validating; legacy rows occasionally drift from the
+    // canonical four-value set. Used by the web byline icon.
+    sourceType: z.string().optional(),
+    /**
+     * App Store platform + icon for `type: "appstore"` sources, null/absent
+     * otherwise. Powers the compact app-update treatment on the search card. #1206
+     */
+    appStore: AppStoreSourceInfoSchema.nullable().optional(),
+    /**
+     * Video provider tag for `type: "video"` sources, absent otherwise. Powers
+     * the thumbnail-forward video row on search cards. #video
+     */
+    video: VideoSourceInfoSchema.nullable().optional(),
+    orgSlug: z.string().nullable(),
+    orgName: z.string().nullable().optional(),
+    /** Owning product slug — present when the source belongs to a product. Lets
+     *  the web byline link to the product page instead of the source. */
+    productSlug: z.string().nullable().optional(),
+    version: z.string().nullable(),
+    title: z.string(),
+    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
+     * `apps/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.
+     */
+    importance: ImportanceScoreSchema,
+    /**
+     * Full markdown body. Omitted on list hits by default (summary + media
+     * cover the card/snippet surfaces). Opt in with `?include_content=true`
+     * on `/v1/search`. Fetch full body via `GET /v1/releases/:id` otherwise.
+     */
+    content: z.string().optional(),
+    media: z.array(MediaItemSchema).optional(),
+    publishedAt: z.string().nullable(),
+    // Hybrid fusion score; absent on pure-lexical results.
+    score: z.number().optional(),
+    type: ReleaseTypeSchema.optional(),
+    coverageCount: z.number().int().min(0).optional(),
+});
+/**
+ * Collection hit on the unified `/v1/search` response. Two origins are folded
+ * into the same wire shape via the `via` discriminator:
+ *
+ * - `direct`  — the collection itself matched (name/description via LIKE in
+ *               every mode, plus vector match in hybrid/semantic mode).
+ * - `member`  — the collection was surfaced because one of the orgs that
+ *               *did* match the query is a member of it; `matchedOrgSlugs`
+ *               carries the subset of result-set org slugs that triggered
+ *               the rollup so the UI can render an "includes X, Y" hint.
+ *
+ * `direct` rows always sort ahead of `member` rows; ties break on
+ * `score` then `memberCount`. Slugs are unique across the array — a
+ * direct hit that's also a member rollup keeps only the `direct` row
+ * with `matchedOrgSlugs` carried over.
+ */
+export const SearchCollectionHitSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    memberCount: z.number().int().min(0),
+    via: z.enum(["direct", "member"]),
+    /** Hybrid/semantic fusion score; absent on pure-lexical hits. */
+    score: z.number().optional(),
+    /** Result-set org slugs that triggered this rollup. Always present on `via=member`. */
+    matchedOrgSlugs: z.array(z.string()).optional(),
+    /**
+     * A small org preview (capped at 3) for an inline avatar facepile on the
+     * search card, mirroring the collections list page. Org-kind only — search's
+     * `memberCount` counts orgs, so the facepile and its "+N more" stay
+     * consistent. Attached after hit merge; optional on the wire so older workers
+     * mid-rollout don't trip the schema.
+     */
+    previewMembers: z.array(CollectionMemberSchema).optional(),
+});
+/**
+ * Heading-aware CHANGELOG.md slice returned by hybrid / semantic search.
+ * Clients can deep-link to
+ * `/<orgSlug>/<sourceSlug>/changelog?offset=<offset>#chunk` to read the
+ * surrounding file content (the web `chunkDeepLink` builder; falls back to
+ * the `/source/<sourceSlug>` redirect shim when `orgSlug` is null).
+ */
+export const SearchChunkHitSchema = z.object({
+    sourceSlug: z.string(),
+    sourceName: z.string(),
+    orgSlug: z.string().nullable(),
+    orgName: z.string().nullable().optional(),
+    filePath: z.string(),
+    offset: z.number().int().min(0),
+    length: z.number().int().min(0),
+    heading: z.string().nullable(),
+    snippet: z.string(),
+    score: z.number(),
+});
+/**
+ * Slim wire payload embedded in a search response when the query is a
+ * GitHub `org/repo` coordinate and no existing entity matched. Reuses
+ * `LookupStatusSchema` from `./lookups.js` rather than redefining — the
+ * thick `POST /v1/lookups` response and the slim search-embedded payload
+ * share the same status set.
+ */
+export const LookupResultPayloadSchema = z.object({
+    status: LookupStatusSchema,
+    source: z
+        .object({
+        id: z.string(),
+        slug: z.string(),
+        name: z.string(),
+        url: z.string(),
+        discovery: z.enum(["curated", "agent", "on_demand"]),
+        stars: z.number().int().min(0).nullable().optional(),
+    })
+        .optional(),
+    releases: z
+        .array(z.object({
+        id: z.string(),
+        version: z.string().nullable(),
+        title: z.string(),
+        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(),
+    // Unambiguous "did you mean" rail; null when the org segment matches
+    // multiple curated orgs or none.
+    relatedOrg: 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(),
+});
+export const UnifiedSearchResponseSchema = z.object({
+    query: z.string(),
+    // Normalized `?domain=` echo + resolution outcome. Both absent when no
+    // domain filter was applied.
+    domain: z.string().optional(),
+    domainStatus: z.enum(["matched", "not_found"]).optional(),
+    // `?org=` echo (the resolved slug on a match, the raw value on a miss) +
+    // resolution outcome. Both absent when no org filter was applied.
+    org: z.string().optional(),
+    orgStatus: z.enum(["matched", "not_found"]).optional(),
+    // Normalized `?category=` echo. Present only when a category filter was
+    // applied; the resolved canonical slug (aliases are folded to canonical).
+    // `categoryStatus` is always `matched` because an unknown category is a 400,
+    // not an empty envelope — categories are a fixed enum, unlike collections.
+    category: z.string().optional(),
+    categoryStatus: z.enum(["matched"]).optional(),
+    // Normalized `?collection=` echo + resolution outcome. `not_found` when the
+    // slug matched no collection (empty envelope, mirroring `domainStatus`).
+    collection: z.string().optional(),
+    collectionStatus: z.enum(["matched", "not_found"]).optional(),
+    orgs: z.array(SearchOrgHitSchema),
+    catalog: z.array(SearchCatalogHitSchema),
+    sources: z.array(SearchSourceHitSchema),
+    releases: z.array(SearchReleaseHitSchema),
+    /**
+     * Curated collections matching the query, either directly (name/description
+     * match or vector hit) or via member rollup (one of the result orgs is in
+     * the collection). Optional on the wire so older workers mid-rollout don't
+     * trip the schema check; clients should treat missing and `[]` identically.
+     */
+    collections: z.array(SearchCollectionHitSchema).optional(),
+    chunks: z.array(SearchChunkHitSchema).optional(),
+    mode: z.enum(["lexical", "semantic", "hybrid"]).optional(),
+    degraded: z.boolean().optional(),
+    degradedReason: z.string().optional(),
+    lookup: LookupResultPayloadSchema.nullable().optional(),
+});

package/dist/schemas/semantic-alert-summary.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/**
+ * `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 declare const SemanticAlertSummarySchema: z.ZodObject<{
+    after: z.ZodString;
+    before: z.ZodString;
+    bucket: z.ZodEnum<{
+        day: "day";
+        hour: "hour";
+    }>;
+    totals: z.ZodObject<{
+        matched: z.ZodNumber;
+        belowThreshold: z.ZodNumber;
+        failed: z.ZodNumber;
+        scored: z.ZodNumber;
+        matchRate: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    series: z.ZodArray<z.ZodObject<{
+        matched: z.ZodNumber;
+        belowThreshold: z.ZodNumber;
+        failed: z.ZodNumber;
+        t: z.ZodString;
+    }, z.core.$strip>>;
+    failures: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            invalid_probability: "invalid_probability";
+            provider_error: "provider_error";
+            unknown: "unknown";
+        }>;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    probability: z.ZodObject<{
+        defaultThreshold: z.ZodLiteral<0.8>;
+        bins: z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+        missing: z.ZodNumber;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        dataset: z.ZodString;
+        retentionDays: z.ZodLiteral<90>;
+        sampled: z.ZodLiteral<true>;
+        costLane: z.ZodLiteral<"semantic-alert-match">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+//# sourceMappingURL=semantic-alert-summary.d.ts.map

package/dist/schemas/semantic-alert-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-alert-summary.d.ts","sourceRoot":"","sources":["../../src/schemas/semantic-alert-summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCrC,CAAC"}

package/dist/schemas/semantic-alert-summary.js

@@ -0,0 +1,57 @@
+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/dist/schemas/semantic-alerts.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+/** Semantic alerts (#2304): saved interests matched against followed releases. */
+/** Hard cap on saved semantic alerts per account. Enforced on create. */
+export declare const SEMANTIC_ALERT_MAX_PER_USER = 5;
+/** Freeform interest text, after trim. User-private — never an analytics label. */
+export declare const SEMANTIC_ALERT_QUERY_MAX_CHARS = 500;
+/** Default selected-choice probability, used unless an alert overrides it. */
+export declare const SEMANTIC_ALERT_THRESHOLD_DEFAULT = 0.8;
+export declare const SEMANTIC_ALERT_THRESHOLD_MIN = 0.5;
+export declare const SEMANTIC_ALERT_THRESHOLD_MAX = 1;
+/**
+ * v1 candidate pool. Matching scores only releases that already hit
+ * the caller's follow graph. Not a per-alert setting.
+ */
+export declare const SEMANTIC_ALERT_CANDIDATE_POOL: "follows";
+/**
+ * POST /v1/me/semantic-alerts body. Documentation shape: the handler parses
+ * each field itself. Omitted `enabled` defaults to true, `threshold` to
+ * {@link SEMANTIC_ALERT_THRESHOLD_DEFAULT}, `deliverEmail` to true and
+ * `deliverWebhook` to false.
+ */
+export declare const SemanticAlertCreateBodySchema: z.ZodObject<{
+    query: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    deliverEmail: z.ZodOptional<z.ZodBoolean>;
+    deliverWebhook: z.ZodOptional<z.ZodBoolean>;
+    webhookSubscriptionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type SemanticAlertCreateBody = z.infer<typeof SemanticAlertCreateBodySchema>;
+/** PATCH /v1/me/semantic-alerts/:id body — any subset of the create fields. */
+export declare const SemanticAlertUpdateBodySchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    threshold: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    deliverEmail: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    deliverWebhook: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    webhookSubscriptionId: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+}, z.core.$strip>;
+export type SemanticAlertUpdateBody = z.infer<typeof SemanticAlertUpdateBodySchema>;
+//# sourceMappingURL=semantic-alerts.d.ts.map

package/dist/schemas/semantic-alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-alerts.d.ts","sourceRoot":"","sources":["../../src/schemas/semantic-alerts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kFAAkF;AAElF,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,mFAAmF;AACnF,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,8EAA8E;AAC9E,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAG,SAAkB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B;;;;;;;iBAkBxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B;;;;;;;iBAA0C,CAAC;AACrF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}

package/dist/schemas/semantic-alerts.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+/** Semantic alerts (#2304): saved interests matched against followed releases. */
+/** 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, used unless an alert overrides it. */
+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 scores only releases that already hit
+ * the caller's follow graph. Not a per-alert setting.
+ */
+export const SEMANTIC_ALERT_CANDIDATE_POOL = "follows";
+/**
+ * POST /v1/me/semantic-alerts body. Documentation shape: the handler parses
+ * each field itself. Omitted `enabled` defaults to true, `threshold` to
+ * {@link SEMANTIC_ALERT_THRESHOLD_DEFAULT}, `deliverEmail` to true and
+ * `deliverWebhook` to false.
+ */
+export const SemanticAlertCreateBodySchema = z.object({
+    query: z
+        .string()
+        .max(SEMANTIC_ALERT_QUERY_MAX_CHARS)
+        .describe("Freeform interest. Trimmed. User-private."),
+    enabled: z.boolean().optional(),
+    threshold: z
+        .number()
+        .min(SEMANTIC_ALERT_THRESHOLD_MIN)
+        .max(SEMANTIC_ALERT_THRESHOLD_MAX)
+        .optional(),
+    deliverEmail: z.boolean().optional(),
+    deliverWebhook: z.boolean().optional(),
+    webhookSubscriptionId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("One of the caller's webhook subscriptions. `null` clears the link on update."),
+});
+/** PATCH /v1/me/semantic-alerts/:id body — any subset of the create fields. */
+export const SemanticAlertUpdateBodySchema = SemanticAlertCreateBodySchema.partial();