react-social-detector/dist/index.d.ts

A comprehensive TypeScript library for detecting and validating social network URLs with React hooks support

import * as react from 'react';

/**
 * Social Network Pattern Configuration
 * Defines patterns and configurations for detecting social network platforms
 */
interface SocialNetworkPatternProps {
    readonly domains: readonly RegExp[];
    readonly baseUrl: string;
    readonly displayName: string;
    readonly exampleDomain: string;
    readonly allowSubdomains?: boolean;
    readonly usernamePrefix?: string;
    readonly urlPattern?: RegExp;
}
declare const SOCIAL_NETWORKS_PATTERNS: Record<string, SocialNetworkPatternProps>;
type SocialNetworkKey = keyof typeof SOCIAL_NETWORKS_PATTERNS;

/**
 * Result of social network detection
 */
interface ReactSocialDetectionResult {
    readonly platform: SocialNetworkKey | 'unknown';
    readonly isValid: boolean;
    readonly normalizedUrl?: string | undefined;
    readonly displayName?: string | undefined;
    readonly confidence: 'high' | 'medium' | 'low';
    readonly detectionMethod: 'pattern' | 'domain' | 'url_structure' | 'none';
    readonly metadata?: {
        readonly extractedUsername?: string | undefined;
        readonly originalInput: string;
        readonly processingTime?: number | undefined;
    };
}
/**
 * Configuration options for detection
 */
interface DetectionOptions {
    readonly strictMode?: boolean;
    readonly includeSubdomains?: boolean;
    readonly caseSensitive?: boolean;
    readonly extractMetadata?: boolean;
}
/**
 * Platform information for supported platforms
 */
interface PlatformInfo {
    readonly key: SocialNetworkKey;
    readonly displayName: string;
    readonly exampleDomain: string;
    readonly baseUrl: string;
}

/**
 * Main class for detecting social networks from URLs and domains
 */
declare class ReactSocialDetector {
    private readonly patterns;
    private readonly domainCache;
    constructor();
    /**
     * Detects social network from URL or domain
     */
    detect(input: string, username?: string, options?: DetectionOptions): ReactSocialDetectionResult;
    /**
     * Extracts username from social media URL
     */
    extractUsername(url: string, platform?: SocialNetworkKey): string | null;
    /**
     * Validates if URL matches expected platform
     */
    validatePlatform(url: string, expectedPlatform: SocialNetworkKey): boolean;
    /**
     * Gets all supported platforms with their information
     */
    getSupportedPlatforms(): PlatformInfo[];
    /**
     * Generates complete profile URL for a given platform and username
     */
    generateProfileUrl(platform: SocialNetworkKey, username: string): string | null;
    /**
     * Validates input and returns normalized version
     */
    private validateInput;
    /**
     * Detects by pattern matching (highest confidence)
     */
    private detectByPattern;
    /**
     * Detects by domain matching (medium confidence)
     */
    private detectByDomain;
    /**
     * Detects by URL structure patterns (lowest confidence)
     */
    private detectByUrlStructure;
    /**
     * Extracts username for specific platform
     */
    private extractUsernameForPlatform;
    /**
     * Sanitizes username by removing invalid characters
     */
    private sanitizeUsername;
    /**
     * Builds final result object
     */
    private buildResult;
    /**
     * Creates error result for invalid input
     */
    private createErrorResult;
    /**
     * Creates result for unknown platform
     */
    private createUnknownResult;
    /**
     * Maps confidence to detection method
     */
    private getDetectionMethod;
}
declare const reactSocialDetector: ReactSocialDetector;
declare function quickReactSocialDetector(input: string, username?: string, options?: DetectionOptions): ReactSocialDetectionResult;

/**
 * Props for the SocialIcon component.
 * @property platform - The supported social network platform key.
 * @property pathColor - The color of the icon path.
 * @property height - The height of the icon.
 * @property width - The width of the icon.
 * @property type - The type of icon, e.g., 'rounded'.
 * @property divProps - Additional props for the container div.
 * @property ariaLabel - ARIA label for accessibility.
 *
 * @example
 * <SocialIcon platform="instagram" pathColor="#ff0000" width={24} height={24} type="rounded" />
 * @example
 * <SocialIcon platform="unknown" ariaLabel="Unknown social icon" />
 *
 * @see {@link https://github.com/zeroskullx/react-social-detector/blob/main/examples/socialicon-examples.md}
 */
type SocialIconProps = {
    platform?: SocialNetworkKey | 'unknown';
    ariaLabel?: string;
    pathColor?: string;
    height?: string | number;
    width?: string | number;
    type?: 'rounded' | undefined;
    divProps?: {
        className?: string;
        backgroundColor?: string;
    };
};
declare const SocialIcon: react.ForwardRefExoticComponent<SocialIconProps & react.RefAttributes<HTMLDivElement>>;

interface UseReactSocialDetectorOptions extends DetectionOptions {
    readonly debounceMs?: number;
    readonly autoDetect?: boolean;
}
interface UseReactSocialDetectorReturn {
    readonly result: ReactSocialDetectionResult | null;
    readonly isDetecting: boolean;
    readonly error: string | null;
    readonly detect: (input: string, username?: string) => Promise<ReactSocialDetectionResult>;
    readonly clear: () => void;
    readonly extractUsername: (url: string, platform?: SocialNetworkKey) => string | null;
    readonly validatePlatform: (url: string, expectedPlatform: SocialNetworkKey) => boolean;
    readonly supportedPlatforms: readonly PlatformInfo[];
    readonly generateProfileUrl: (platform: SocialNetworkKey, username: string) => string | null;
}
interface UseBulkDetectionOptions extends DetectionOptions {
    readonly maxConcurrent?: number;
}
interface BulkDetectionItem {
    readonly id: string;
    readonly input: string;
    readonly username?: string;
}
interface BulkDetectionResult extends BulkDetectionItem {
    readonly result: ReactSocialDetectionResult;
    readonly error?: string;
}
interface UseBulkReactSocialDetectorReturn {
    readonly results: readonly BulkDetectionResult[];
    readonly isDetecting: boolean;
    readonly progress: {
        readonly completed: number;
        readonly total: number;
    };
    readonly detectBulk: (items: readonly BulkDetectionItem[]) => Promise<readonly BulkDetectionResult[]>;
    readonly clear: () => void;
}

/**
 * React hook for bulk social network detection with concurrency control
 */
declare function useBulkReactSocialDetector(options?: UseBulkDetectionOptions): UseBulkReactSocialDetectorReturn;

/**
 * React hook for social network detection with debouncing and error handling
 */
declare function useReactSocialDetector(options?: UseReactSocialDetectorOptions): UseReactSocialDetectorReturn;

declare const socialNetworkUtils: {
    /**
     * Check if a platform is supported
     */
    readonly isPlatformSupported: (platform: string) => platform is SocialNetworkKey;
    /**
     * Get platform display name
     */
    readonly getPlatformDisplayName: (platform: SocialNetworkKey) => string;
    /**
     * Get platform example domain
     */
    readonly getPlatformExampleDomain: (platform: SocialNetworkKey) => string;
    /**
     * Get all platform keys
     */
    readonly getAllPlatformKeys: () => SocialNetworkKey[];
    /**
     * Get all supported platforms with details
     */
    readonly getAllPlatforms: () => PlatformInfo[];
    /**
     * Normalize URL for comparison
     */
    readonly normalizeUrl: (url: string) => string;
    /**
     * Extract domain from URL
     */
    readonly extractDomain: (url: string) => string | null;
    /**
     * Validate username format for platform
     */
    readonly validateUsername: (username: string, platform: SocialNetworkKey) => boolean;
    /**
     * Generate profile URL for platform and username
     */
    readonly generateProfileUrl: (platform: SocialNetworkKey, username: string) => string | null;
};

declare const _default: {
    readonly ReactSocialDetector: typeof ReactSocialDetector;
    readonly reactSocialDetector: ReactSocialDetector;
    readonly quickReactSocialDetector: typeof quickReactSocialDetector;
    readonly socialNetworkUtils: {
        readonly isPlatformSupported: (platform: string) => platform is SocialNetworkKey;
        readonly getPlatformDisplayName: (platform: SocialNetworkKey) => string;
        readonly getPlatformExampleDomain: (platform: SocialNetworkKey) => string;
        readonly getAllPlatformKeys: () => SocialNetworkKey[];
        readonly getAllPlatforms: () => PlatformInfo[];
        readonly normalizeUrl: (url: string) => string;
        readonly extractDomain: (url: string) => string | null;
        readonly validateUsername: (username: string, platform: SocialNetworkKey) => boolean;
        readonly generateProfileUrl: (platform: SocialNetworkKey, username: string) => string | null;
    };
};

export { ReactSocialDetector, SocialIcon, _default as default, quickReactSocialDetector, reactSocialDetector, socialNetworkUtils, useBulkReactSocialDetector, useReactSocialDetector };
export type { BulkDetectionItem, BulkDetectionResult, DetectionOptions, PlatformInfo, ReactSocialDetectionResult, SocialNetworkKey, SocialNetworkPatternProps, UseBulkDetectionOptions, UseBulkReactSocialDetectorReturn, UseReactSocialDetectorOptions, UseReactSocialDetectorReturn };