@pipeline-builder/pipeline-data 4.1.15 → 4.1.17

package/lib/api/public-directory.d.ts

@@ -0,0 +1,281 @@
+export type DirectoryTrustTier = 'official' | 'verified' | 'community' | 'unverified';
+export type DirectoryIconKind = 'vendor' | 'uploaded' | 'monogram' | 'category';
+export type DirectorySort = 'relevance' | 'rating' | 'installs' | 'updated' | 'name' | 'health';
+export declare const DIRECTORY_SORTS: readonly DirectorySort[];
+/** Per-component health scores: `{ score: 0..1 | null (missing), weight }`. */
+export type DirectoryHealthBreakdown = Record<string, {
+    score: number | null;
+    weight: number;
+}>;
+export declare const DIRECTORY_TIERS: readonly DirectoryTrustTier[];
+/** Minimum `word_similarity(query, name)` for a fuzzy name match (typo tolerance). */
+export declare const FUZZY_NAME_THRESHOLD = 0.3;
+/** Max query length accepted (longer is truncated, never an error). */
+export declare const DIRECTORY_MAX_QUERY_LENGTH = 100;
+export declare const DIRECTORY_DEFAULT_LIMIT = 24;
+export declare const DIRECTORY_MAX_LIMIT = 60;
+export interface DirectorySearchParams {
+    q?: string;
+    category?: string;
+    tier?: DirectoryTrustTier;
+    license?: string;
+    computeType?: string;
+    needsSecrets?: boolean;
+    minRating?: number;
+    sort?: DirectorySort;
+    cursor?: string;
+    limit?: number;
+}
+export interface DirectoryListingCard {
+    publisher: {
+        handle: string;
+        displayName: string;
+        tier: DirectoryTrustTier;
+    };
+    name: string;
+    summary: string;
+    category: string;
+    keywords: string[];
+    latestVersion: string;
+    license: string;
+    iconUrl: string | null;
+    iconKind: DirectoryIconKind;
+    iconKey: string | null;
+    iconHex: string | null;
+    iconBadge: string | null;
+    rating: {
+        score: number;
+        count: number;
+    } | null;
+    installCount: number;
+    /** 0–100 health score; null when fewer than three components are known. */
+    healthScore: number | null;
+    updatedAt: string;
+    state: 'listed' | 'unmaintained';
+    highlight?: {
+        name?: string;
+        summary?: string;
+    };
+}
+export interface DirectorySearchResult {
+    items: DirectoryListingCard[];
+    facets: {
+        category: Record<string, number>;
+        tier: Record<string, number>;
+        license: Record<string, number>;
+        computeType: Record<string, number>;
+        needsSecrets: {
+            true: number;
+            false: number;
+        };
+    };
+    total: number;
+    nextCursor: string | null;
+}
+export interface DirectoryCategorySummary {
+    id: string;
+    count: number;
+    top: DirectoryListingCard[];
+}
+export interface DirectoryListingVersion {
+    version: string;
+    publishedAt: string;
+    breaking: boolean;
+    deprecated: boolean;
+    deprecationMessage: string | null;
+    yanked: boolean;
+    changelog: string | null;
+    vulnCritical: number | null;
+    vulnHigh: number | null;
+    scannedAt: string | null;
+    /** Ids of the published advisories whose range covers this version. */
+    advisoryIds: string[];
+}
+export interface DirectoryListingDetail extends DirectoryListingCard {
+    readmeHtml: string | null;
+    description: string;
+    homepageUrl: string | null;
+    sourceUrl: string | null;
+    versions: DirectoryListingVersion[];
+    configuration: {
+        secrets: {
+            name: string;
+            required: boolean;
+            description: string;
+        }[];
+        requiredMetadata: string[];
+        requiredVars: string[];
+        computeType: string;
+        primaryOutputDirectory: string | null;
+        networkEgress: string[];
+        pluginType: string;
+    };
+    supplyChain: {
+        signed: boolean;
+        digest: string | null;
+        imageSource: string | null;
+        scannedAt: string | null;
+        vulnCritical: number | null;
+        vulnHigh: number | null;
+        sbomUrl: string | null;
+    };
+    advisories: {
+        id: string;
+        severity: string;
+        summary: string;
+        affectedRange: string;
+        fixedVersion: string | null;
+        publishedAt: string;
+        /** Server-sanitized HTML (the stored render of the details markdown). */
+        detailsHtml: string | null;
+        cveIds: string[];
+    }[];
+    ratingDistribution: Record<'1' | '2' | '3' | '4' | '5', number> | null;
+    /** The Bayesian rating over reviews of the last two minor versions. */
+    recentRating: number | null;
+    activeOrgCount: number | null;
+    /** Per-component health scores behind {@link DirectoryListingCard.healthScore}. */
+    healthBreakdown: DirectoryHealthBreakdown | null;
+    /** 30-day runtime success rate (0..1), or null with no runs. */
+    successRate30d: number | null;
+}
+export type ReviewSort = 'helpful' | 'recent' | 'highest' | 'lowest';
+export declare const REVIEW_SORTS: readonly ReviewSort[];
+export declare const REVIEWS_DEFAULT_LIMIT = 10;
+export declare const REVIEWS_MAX_LIMIT = 50;
+export interface PublicReviewReply {
+    bodyHtml: string;
+    publisherDisplayName: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One published review as the directory shows it: display name only, never an org. */
+export interface PublicReviewItem {
+    id: string;
+    rating: number;
+    title: string | null;
+    bodyHtml: string | null;
+    version: string | null;
+    /** Null once the author's account was deleted (the review is anonymized). */
+    author: {
+        displayName: string;
+    } | null;
+    verifiedUse: boolean;
+    helpfulCount: number;
+    edited: boolean;
+    createdAt: string;
+    updatedAt: string;
+    reply: PublicReviewReply | null;
+}
+export interface PublicReviewPage {
+    reviews: PublicReviewItem[];
+    total: number;
+    nextCursor: string | null;
+}
+export interface PublicReviewQuery {
+    sort?: ReviewSort;
+    /** Only reviews with exactly this many stars. */
+    rating?: number;
+    cursor?: string;
+    limit?: number;
+}
+/** A `public_listings` row as the raw queries return it (snake_case). */
+export interface PublicListingRow {
+    id: string;
+    publisher_handle: string;
+    publisher_display_name: string;
+    publisher_tier: DirectoryTrustTier;
+    name: string;
+    category: string;
+    summary: string | null;
+    description: string | null;
+    readme_html: string | null;
+    license: string | null;
+    homepage_url: string | null;
+    source_url: string | null;
+    icon: {
+        key: string;
+        badge?: string;
+    } | null;
+    uploaded_icon: {
+        key256: string;
+        key64: string;
+    } | null;
+    keywords: string[] | null;
+    latest_version: string | null;
+    updated_at: Date | string;
+    rating_bayes: number | string | null;
+    rating_count: number | string;
+    rating_dist: Record<string, number> | null;
+    recent_rating?: number | string | null;
+    install_count: number | string;
+    active_org_count: number | string | null;
+    health_score?: number | string | null;
+    health_breakdown?: DirectoryHealthBreakdown | null;
+    success_rate_30d?: number | string | null;
+    state: 'listed' | 'unmaintained';
+}
+/**
+ * The icon fallback chain: uploaded (if the tier may upload) → curated
+ * vendor key (Official, and Verified publishers for marks they own — ownership
+ * is checked when the icon is approved) → monogram. Community and anonymous
+ * listings can never show a curated vendor mark.
+ */
+export declare function resolveListingIcon(row: Pick<PublicListingRow, 'publisher_tier' | 'icon' | 'uploaded_icon'>): Pick<DirectoryListingCard, 'iconKind' | 'iconUrl' | 'iconKey' | 'iconBadge' | 'iconHex'>;
+export declare function toListingCard(row: PublicListingRow): DirectoryListingCard;
+/** Normalize the user's query: collapse whitespace, cap the length. */
+export declare function normalizeQuery(q: string | undefined): string;
+/**
+ * Wrap matched terms in `<mark>`. The frontend renders everything except the
+ * `<mark>` markers as TEXT (never HTML), so the source text is not escaped here.
+ * Returns undefined when nothing matched (the card then renders plain text).
+ */
+export declare function highlightText(text: string, q: string): string | undefined;
+/** Opaque cursor: an offset, base64url-encoded so clients don't depend on it. */
+export declare function encodeOffsetCursor(offset: number): string;
+export declare function decodeOffsetCursor(cursor: string | undefined): number;
+/** Search the directory: one page of cards, facet counts, total and next cursor. */
+export declare function searchPublicListings(params: DirectorySearchParams): Promise<DirectorySearchResult>;
+/** Every category with its live count and its top listings (by rating, then installs). */
+export declare function listPublicCategories(topPerCategory?: number): Promise<DirectoryCategorySummary[]>;
+/**
+ * One listing's page data, or null when it isn't public (unknown, suspended,
+ * transferred, paused by its publisher — or its publisher is suspended).
+ */
+export declare function getPublicListing(publisherHandle: string, name: string): Promise<DirectoryListingDetail | null>;
+/** One listed version's public image identity (for the SBOM download), or null. */
+export declare function getPublicListedVersion(publisherHandle: string, name: string, version: string): Promise<{
+    imageRepository: string;
+    imageDigest: string;
+} | null>;
+type ReviewRow = {
+    id: string;
+    version: string | null;
+    rating: number | string;
+    title: string | null;
+    body_html: string | null;
+    author_display_name: string | null;
+    verified_use: boolean;
+    helpful_count: number | string;
+    edited: boolean;
+    created_at: Date | string;
+    updated_at: Date | string;
+    publisher_display_name: string;
+    reply_body_html: string | null;
+    reply_created_at: Date | string | null;
+    reply_updated_at: Date | string | null;
+    total: number | string;
+};
+export declare function toPublicReview(row: Omit<ReviewRow, 'total'>): PublicReviewItem;
+/**
+ * One page of a listing's published reviews (the directory's Reviews tab), or null
+ * when the listing isn't public. Held and removed reviews never reach the view.
+ */
+export declare function listPublicReviews(publisherHandle: string, name: string, query?: PublicReviewQuery): Promise<PublicReviewPage | null>;
+/** Every public listing's URL parts + last update, for the sitemap. */
+export declare function listPublicListingsForSitemap(max?: number): Promise<{
+    publisher: string;
+    name: string;
+    updatedAt: string;
+}[]>;
+export {};