@bfra.me/badge-config/lib/index.d.ts

TypeScript API for generating shields.io badge URLs with preset generators

/**
 * @module
 * This module contains type definitions for the @bfra.me/badge-config package.
 * It includes types for badge styles, colors, options, and results.
 */
/**
 * Defines the visual style of the badge.
 * @see https://shields.io/#style
 */
type BadgeStyle = 'flat' | 'flat-square' | 'plastic' | 'for-the-badge' | 'social';
/**
 * A set of named colors supported by shields.io for badges.
 */
type BadgeNamedColor = 'brightgreen' | 'green' | 'yellowgreen' | 'yellow' | 'orange' | 'red' | 'lightgrey' | 'blue' | 'purple' | 'pink' | 'black' | 'white';
/**
 * Represents a color for a badge, which can be a named color, a hex code, or an RGB value.
 */
type BadgeColor = BadgeNamedColor | `#${string}` | `rgb(${string})`;
/**
 * Defines the core configuration options for creating a badge.
 */
interface BadgeOptions {
    /**
     * The text displayed on the left side of the badge.
     * @example 'build'
     */
    label: string;
    /**
     * The text displayed on the right side of the badge.
     * @example 'passing'
     */
    message: string;
    /**
     * The color of the message part of the badge.
     * @default 'lightgrey'
     */
    color?: BadgeColor;
    /**
     * The color of the label part of the badge.
     */
    labelColor?: BadgeColor;
    /**
     * The visual style of the badge.
     * @default 'flat'
     */
    style?: BadgeStyle;
    /**
     * A logo from simple-icons to embed in the badge, or a data URI.
     * @see https://simpleicons.org/
     */
    logo?: string;
    /**
     * The color of the embedded logo.
     */
    logoColor?: BadgeColor;
    /**
     * The width of the embedded logo.
     */
    logoSize?: number | 'auto';
    /**
     * The number of seconds to cache the badge URL.
     * @see https://shields.io/docs/performance
     */
    cacheSeconds?: number;
}
/**
 * Represents the result of a badge generation operation.
 */
interface BadgeResult {
    /** The complete shields.io URL for the generated badge. */
    url: string;
    /** The SVG content of the badge, if fetched. */
    svg?: string;
}
/**
 * Custom error class for badge generation failures.
 */
declare class BadgeError extends Error {
    /** An optional error code for specific failure types. */
    readonly code?: string;
    /**
     * Creates a new BadgeError instance.
     * @param message - The error message.
     * @param code - An optional error code.
     */
    constructor(message: string, code?: string);
}
/**
 * Options for fetching the SVG content of a generated badge.
 */
interface FetchOptions {
    /**
     * If true, the SVG content of the badge will be fetched and included in the result.
     * @default false
     */
    fetchSvg?: boolean;
    /**
     * The timeout for the fetch request in milliseconds.
     * @default 5000
     */
    timeout?: number;
}

/**
 * @module
 * This module provides the core `createBadge` function for generating shields.io badge URLs.
 * It handles URL construction, parameter validation, and optional SVG fetching.
 */

/**
 * Creates a shields.io badge URL and optionally fetches the SVG content.
 *
 * This function constructs a URL based on the provided options, validates inputs,
 * and can fetch the resulting SVG image. It's the primary entry point for badge generation.
 *
 * @param options - The configuration for the badge, including label, message, and colors.
 * @param fetchOptions - Optional settings for fetching the SVG content, such as a timeout.
 * @returns A promise that resolves to a `BadgeResult` object containing the URL and optional SVG.
 * @throws {BadgeError} If required fields are missing or if fetching fails.
 *
 * @example
 * ```typescript
 * import { createBadge } from '@bfra.me/badge-config';
 *
 * const badge = await createBadge({
 *   label: 'build',
 *   message: 'passing',
 *   color: 'green',
 *   style: 'flat-square',
 * });
 *
 * console.log(badge.url);
 * // => https://img.shields.io/badge/build-passing-green?style=flat-square
 * ```
 */
declare function createBadge(options: BadgeOptions, fetchOptions?: FetchOptions): Promise<BadgeResult>;
/**
 * Creates a badge URL synchronously (without fetching SVG content)
 * @param options - Badge configuration options
 * @returns Badge URL string
 */
declare function createBadgeUrl(options: BadgeOptions): string;

/**
 * @module
 * This module provides a preset generator for creating build status badges.
 * It simplifies the creation of badges for common CI/CD states like success, failure, and pending.
 */

/**
 * Defines the possible states for a build status badge.
 */
type BuildStatus = 'success' | 'failure' | 'pending' | 'error' | 'cancelled' | 'skipped' | 'unknown';
/**
 * Configuration options for creating a build status badge.
 */
interface BuildStatusOptions {
    /** The current status of the build. */
    status: BuildStatus;
    /** The text for the left side of the badge. @default 'build' */
    label?: string;
    /** The visual style of the badge. */
    style?: BadgeStyle;
    /** Overrides the default color for the status. */
    color?: BadgeColor;
    /** A logo to embed in the badge. */
    logo?: string;
    /** The color of the embedded logo. */
    logoColor?: BadgeColor;
    /** The number of seconds to cache the badge URL. */
    cacheSeconds?: number;
}
/**
 * Generates the configuration for a build status badge.
 *
 * @param options - The build status configuration.
 * @returns Badge options that can be passed to the `createBadge` function.
 *
 * @example
 * ```typescript
 * import { buildStatus } from '@bfra.me/badge-config/generators';
 * import { createBadge } from '@bfra.me/badge-config';
 *
 * // Generate a success badge
 * const successOptions = buildStatus({ status: 'success' });
 * const successBadge = await createBadge(successOptions);
 * console.log(successBadge.url);
 * // => https://img.shields.io/badge/build-passing-brightgreen
 *
 * // Generate a failing badge with a custom label
 * const failureOptions = buildStatus({ status: 'failure', label: 'tests' });
 * const failureBadge = await createBadge(failureOptions);
 * console.log(failureBadge.url);
 * // => https://img.shields.io/badge/tests-failing-red
 * ```
 */
declare function buildStatus(options: BuildStatusOptions): BadgeOptions;

/**
 * @module
 * This module provides a preset generator for creating code coverage badges.
 * It dynamically sets the badge color based on the coverage percentage.
 */

/**
 * Defines the percentage thresholds for determining the badge color for coverage.
 */
interface CoverageThresholds {
    /** Threshold for 'excellent' coverage. @default 90 */
    excellent?: number;
    /** Threshold for 'good' coverage. @default 80 */
    good?: number;
    /** Threshold for 'moderate' coverage. @default 60 */
    moderate?: number;
    /** Threshold for 'poor' coverage. @default 40 */
    poor?: number;
}
/**
 * Configuration options for creating a coverage badge.
 */
interface CoverageOptions {
    /** The code coverage percentage (0-100). */
    percentage: number;
    /** The text for the left side of the badge. @default 'coverage' */
    label?: string;
    /** The visual style of the badge. */
    style?: BadgeStyle;
    /** Overrides the default dynamic color. */
    color?: BadgeColor;
    /** Custom thresholds for determining the badge color. */
    thresholds?: CoverageThresholds;
    /** A logo to embed in the badge. */
    logo?: string;
    /** The color of the embedded logo. */
    logoColor?: BadgeColor;
    /** The number of seconds to cache the badge URL. */
    cacheSeconds?: number;
}
/**
 * Generates the configuration for a code coverage badge.
 *
 * The color of the badge is determined by the coverage percentage, but can be overridden.
 *
 * @param options - The coverage configuration.
 * @returns Badge options that can be passed to the `createBadge` function.
 *
 * @example
 * ```typescript
 * import { coverage } from '@bfra.me/badge-config/generators';
 * import { createBadge } from '@bfra.me/badge-config';
 *
 * // Generate a badge for 85% coverage
 * const highCoverageOptions = coverage({ percentage: 85 });
 * const highCoverageBadge = await createBadge(highCoverageOptions);
 * console.log(highCoverageBadge.url);
 * // => https://img.shields.io/badge/coverage-85%25-green
 *
 * // Generate a badge for 55% coverage with a custom label
 * const lowCoverageOptions = coverage({ percentage: 55, label: 'unit tests' });
 * const lowCoverageBadge = await createBadge(lowCoverageOptions);
 * console.log(lowCoverageBadge.url);
 * // => https://img.shields.io/badge/unit%20tests-55%25-yellow
 * ```
 */
declare function coverage(options: CoverageOptions): BadgeOptions;

/**
 * @module
 * This module provides a preset generator for creating software license badges.
 * It includes a database of common licenses and assigns colors based on license category.
 */

/**
 * Defines categories for software licenses, each with an associated default color.
 */
type LicenseCategory = 'permissive' | 'copyleft' | 'creative-commons' | 'proprietary' | 'custom';
/**
 * Configuration options for creating a license badge.
 */
interface LicenseOptions {
    /** The SPDX identifier of the license (e.g., 'MIT', 'Apache-2.0'). */
    license: string;
    /** The text for the left side of the badge. @default 'license' */
    label?: string;
    /** The visual style of the badge. */
    style?: BadgeStyle;
    /** Overrides the default color for the license category. */
    color?: BadgeColor;
    /** Overrides the auto-detected license category. */
    category?: LicenseCategory;
    /** A custom URL for the license details. */
    url?: string;
    /** A logo to embed in the badge. */
    logo?: string;
    /** The color of the embedded logo. */
    logoColor?: BadgeColor;
    /** The number of seconds to cache the badge URL. */
    cacheSeconds?: number;
}
/**
 * Generate badge options for license information
 *
 * @param options - License configuration
 * @returns Badge options for use with createBadge
 *
 * @example
 * ```typescript
 * // Common license
 * const badgeOptions = license({ license: 'MIT' })
 * const badge = createBadge(badgeOptions)
 *
 * // Custom license with category
 * const badgeOptions = license({
 *   license: 'Custom Commercial',
 *   category: 'proprietary',
 *   label: 'license'
 * })
 *
 * // License with URL
 * const badgeOptions = license({
 *   license: 'Apache-2.0',
 *   url: 'https://example.com/license'
 * })
 * ```
 */
declare function license(options: LicenseOptions): BadgeOptions;

/**
 * @module
 * This module provides a preset generator for creating social media badges,
 * such as GitHub stars, forks, and followers.
 */

/**
 * Defines the supported types of social media badges.
 */
type SocialBadgeType = 'stars' | 'forks' | 'watchers' | 'issues' | 'followers' | 'downloads';
/**
 * Configuration options for creating a social media badge.
 */
interface SocialBadgeOptions {
    /** The type of social badge to create. */
    type: SocialBadgeType;
    /** The repository name in 'owner/repo' format (required for most GitHub badges). */
    repository?: string;
    /** The user or organization name (required for followers). */
    user?: string;
    /** The name of the package (required for downloads). */
    packageName?: string;
    /** A custom count to display, overriding any fetched value. */
    count?: number;
    /** Overrides the default label for the badge type. */
    label?: string;
    /** The visual style of the badge. */
    style?: BadgeStyle;
    /** Overrides the default color for the badge type. */
    color?: BadgeColor;
    /** Overrides the default logo for the badge type. */
    logo?: string;
    /** The color of the embedded logo. */
    logoColor?: BadgeColor;
    /** The number of seconds to cache the badge URL. */
    cacheSeconds?: number;
}
/**
 * Generates the configuration for a social media badge.
 *
 * @param options - The social badge configuration.
 * @returns Badge options that can be passed to the `createBadge` function.
 *
 * @example
 * ```typescript
 * import { social } from '@bfra.me/badge-config/generators';
 * import { createBadge } from '@bfra.me/badge-config';
 *
 * // Generate a GitHub stars badge
 * const starsOptions = social({ type: 'stars', repository: 'bfra-me/works' });
 * const starsBadge = await createBadge(starsOptions);
 * console.log(starsBadge.url);
 * // => https://img.shields.io/github/stars/bfra-me/works?style=social
 *
 * // Generate a followers badge with a custom count
 * const followersOptions = social({ type: 'followers', user: 'marcusrbrown', count: 1234 });
 * const followersBadge = await createBadge(followersOptions);
 * console.log(followersBadge.url);
 * // => https://img.shields.io/badge/followers-1.2k-blue?logo=github
 * ```
 */
declare function social(options: SocialBadgeOptions): BadgeOptions;

/**
 * @module
 * This module provides a preset generator for creating version badges.
 * It supports versions from various sources like npm, Git, and custom strings.
 */

/**
 * Defines the source of the version information.
 */
type VersionSource = 'npm' | 'git' | 'github' | 'custom';
/**
 * Configuration options for creating a version badge.
 */
interface VersionOptions {
    /** The version string to display (e.g., '1.2.3'). */
    version: string;
    /** The source of the version information. @default 'custom' */
    source?: VersionSource;
    /** The name of the package (required for 'npm' source). */
    packageName?: string;
    /** The repository name in 'owner/repo' format (for 'git' or 'github' source). */
    repository?: string;
    /** The text for the left side of the badge. */
    label?: string;
    /** The visual style of the badge. */
    style?: BadgeStyle;
    /** Overrides the default color for the version source. */
    color?: BadgeColor;
    /** A logo to embed in the badge. */
    logo?: string;
    /** The color of the embedded logo. */
    logoColor?: BadgeColor;
    /** The number of seconds to cache the badge URL. */
    cacheSeconds?: number;
}
/**
 * Generates the configuration for a version badge.
 *
 * @param options - The version configuration.
 * @returns Badge options that can be passed to the `createBadge` function.
 *
 * @example
 * ```typescript
 * import { version } from '@bfra.me/badge-config/generators';
 * import { createBadge } from '@bfra.me/badge-config';
 *
 * // Generate a badge for an npm package version
 * const npmOptions = version({ version: '1.2.3', source: 'npm', packageName: 'react' });
 * const npmBadge = await createBadge(npmOptions);
 * console.log(npmBadge.url);
 * // => https://img.shields.io/badge/npm-1.2.3-red
 *
 * // Generate a badge for a Git tag
 * const gitOptions = version({ version: 'v2.0.1', source: 'git' });
 * const gitBadge = await createBadge(gitOptions);
 * console.log(gitBadge.url);
 * // => https://img.shields.io/badge/version-v2.0.1-blue
 * ```
 */
declare function version(options: VersionOptions): BadgeOptions;

/**
 * @module
 * This module contains utility functions for the @bfra.me/badge-config package.
 * It provides helpers for encoding text, validating inputs, and sanitizing data.
 */

/**
 * Encodes a string for use in a shields.io badge URL.
 * It handles special characters and shields.io-specific escaping.
 *
 * @param text - The text to encode.
 * @returns The encoded and escaped text.
 * @throws {BadgeError} If the input is not a string.
 */
declare function encodeText(text: string): string;
/**
 * Validates and normalizes a badge color string.
 * It supports named colors, hex codes, and RGB values.
 *
 * @param color - The color to validate.
 * @returns The normalized and encoded color string.
 * @throws {BadgeError} If the color format is invalid.
 */
declare function validateColor(color: BadgeColor): string;
/**
 * Validates the `cacheSeconds` value to ensure it's a non-negative integer.
 *
 * @param cacheSeconds - The cache duration in seconds.
 * @returns The validated cache duration.
 * @throws {BadgeError} If the value is not a non-negative integer.
 */
declare function validateCacheSeconds(cacheSeconds: number): number;
/**
 * Validates the `logoSize` value to ensure it's a positive integer or 'auto'.
 *
 * @param logoSize - The size of the logo.
 * @returns The validated logo size as a string.
 * @throws {BadgeError} If the value is invalid.
 */
declare function validateLogoSize(logoSize: number | 'auto'): string;
/**
 * Sanitizes user-provided strings to prevent URL injection attacks
 * by removing potentially harmful characters.
 *
 * @param input - The string to sanitize.
 * @returns The sanitized string.
 * @throws {BadgeError} If the input is not a string.
 */
declare function sanitizeInput(input: string): string;

export { type BadgeColor, BadgeError, type BadgeNamedColor, type BadgeOptions, type BadgeResult, type BadgeStyle, type BuildStatus, type BuildStatusOptions, type CoverageOptions, type CoverageThresholds, type FetchOptions, type LicenseCategory, type LicenseOptions, type SocialBadgeOptions, type SocialBadgeType, type VersionOptions, type VersionSource, buildStatus, coverage, createBadge, createBadgeUrl, encodeText, license, sanitizeInput, social, validateCacheSeconds, validateColor, validateLogoSize, version };