@lineai/linkedin-api/index.d.ts

Professional LinkedIn API client with TypeScript support, entity classes, and developer-friendly features. Perfect for AI coders, recruiting, lead generation, market research, and content analysis. Includes comprehensive JSDoc, helper constants (LOCATIONS

declare class LinkedInAPI {
  /**
   * Create a new LinkedIn API client instance
   * @param rapidApiKey Your RapidAPI key for LinkedIn Data API
   * @param rapidApiHost Optional custom RapidAPI host (defaults to linkedin-data-api.p.rapidapi.com)
   * @example
   * ```typescript
   * import LinkedInAPI from '@lineai/linkedin-api';
   * const api = new LinkedInAPI('your-rapidapi-key');
   * ```
   */
  constructor(rapidApiKey: string, rapidApiHost?: string);

  /**
   * Search for LinkedIn profiles with advanced filtering options
   * @param params Search parameters for profile discovery
   * @returns Promise resolving to search results with profile items and pagination
   * @throws {LinkedInError} When search parameters are invalid or API request fails
   * @example
   * ```typescript
   * import { LOCATIONS } from '@lineai/linkedin-api';
   *
   * // Basic search
   * const results = await api.searchProfiles({
   *   keywords: 'software engineer'
   * });
   *
   * // Advanced search with location and company filters
   * const filteredResults = await api.searchProfiles({
   *   keywords: 'product manager',
   *   geo: [LOCATIONS.US.SAN_FRANCISCO],
   *   company: 'Google',
   *   start: '0' // Pagination
   * });
   *
   * console.log(`Found ${results.total} profiles`);
   * results.items.forEach(profile => {
   *   console.log(profile.getFullName(), profile.getHeadline());
   * });
   * ```
   */
  searchProfiles(params: ProfileSearchParams): Promise<ProfileSearchResult>;

  /**
   * Get comprehensive profile data for a LinkedIn user
   * @param username LinkedIn username (extracted from profile URL, e.g., 'satyanadella')
   * @returns Promise resolving to complete profile data with helper methods
   * @throws {NotFoundError} When profile doesn't exist or is private
   * @throws {LinkedInError} When API request fails
   * @example
   * ```typescript
   * // Get profile by username
   * const profile = await api.getProfile('satyanadella');
   *
   * // Access profile data using helper methods
   * console.log(profile.getFullName());              // "Satya Nadella"
   * console.log(profile.getHeadline());              // "CEO at Microsoft"
   * console.log(profile.getCurrentPosition()?.title); // "CEO"
   * console.log(profile.getLinkedInUrl());           // Full LinkedIn URL
   *
   * // Access arrays safely
   * const positions = profile.getAllPositions();
   * const education = profile.getEducation();
   * const skills = profile.getSkills();
   *
   * // Access raw data if needed
   * console.log(profile.raw.id);
   * ```
   */
  getProfile(username: string): Promise<LinkedInProfile>;

  /**
   * Search for LinkedIn companies with filtering options
   * @param params Search parameters for company discovery
   * @returns Promise resolving to search results with company items and pagination
   * @throws {LinkedInError} When search parameters are invalid or API request fails
   * @example
   * ```typescript
   * import { INDUSTRIES, COMPANY_SIZES } from '@lineai/linkedin-api';
   *
   * // Basic company search
   * const companies = await api.searchCompanies({
   *   keyword: 'artificial intelligence'
   * });
   *
   * // Advanced search with filters
   * const techCompanies = await api.searchCompanies({
   *   keyword: 'startup',
   *   industries: [INDUSTRIES.TECHNOLOGY],
   *   companySizes: [COMPANY_SIZES.LARGE, COMPANY_SIZES.ENTERPRISE],
   *   hasJobs: true
   * });
   *
   * // Process results
   * companies.items.forEach(company => {
   *   console.log(company.getName(), company.getTagline());
   * });
   * ```
   */
  searchCompanies(params: CompanySearchParams): Promise<CompanySearchResult>;

  /**
   * Get comprehensive company data for a LinkedIn company
   * @param username Company username (from company URL, e.g., 'microsoft')
   * @returns Promise resolving to complete company data with helper methods
   * @throws {NotFoundError} When company doesn't exist or is private
   * @throws {LinkedInError} When API request fails
   * @example
   * ```typescript
   * // Get company by username
   * const company = await api.getCompany('microsoft');
   *
   * // Access company data using helper methods
   * console.log(company.getName());                  // "Microsoft"
   * console.log(company.getEmployeeCount());         // 220000
   * console.log(company.getFollowerCount());         // 25000000
   * console.log(company.getLinkedInUrl());           // Full LinkedIn URL
   *
   * // Access detailed information
   * const headquarters = company.getHeadquarters();
   * const industries = company.getIndustries();
   * const specialties = company.getSpecialties();
   *
   * console.log(`HQ: ${headquarters?.city}, ${headquarters?.country}`);
   * ```
   */
  getCompany(username: string): Promise<LinkedInCompany>;

  /**
   * Search for LinkedIn posts with advanced filtering
   * @param params Search parameters for post discovery
   * @returns Promise resolving to search results with post items and pagination
   * @throws {LinkedInError} When search parameters are invalid or API request fails
   * @example
   * ```typescript
   * // Search recent posts by keyword
   * const posts = await api.searchPosts({
   *   keyword: 'machine learning',
   *   sortBy: 'date_posted',
   *   datePosted: 'past-week'
   * });
   *
   * // Search posts by specific author
   * const authorPosts = await api.searchPosts({
   *   keyword: 'leadership',
   *   fromMember: ['satyanadella']
   * });
   *
   * // Process results
   * posts.items.forEach(post => {
   *   console.log(post.getAuthorName(), post.getText().substring(0, 100));
   * });
   * ```
   */
  searchPosts(params: PostSearchParams): Promise<PostSearchResult>;

  /**
   * Get comprehensive post data for a LinkedIn post
   * @param postId Post ID or URN identifier
   * @returns Promise resolving to complete post data with engagement metrics
   * @throws {NotFoundError} When post doesn't exist or is private
   * @throws {LinkedInError} When API request fails
   * @example
   * ```typescript
   * // Get post by ID
   * const post = await api.getPost('6789123456789');
   *
   * // Access post content and metrics
   * console.log(post.getText());                     // Post content
   * console.log(post.getLikeCount());                // 1250
   * console.log(post.getCommentsCount());            // 89
   * console.log(post.getTotalEngagement());          // Combined engagement
   *
   * // Access author information
   * const author = post.getAuthor();
   * console.log(`Posted by: ${author.firstName} ${author.lastName}`);
   *
   * // Check post type and media
   * if (post.hasVideo()) {
   *   const video = post.getVideo();
   *   console.log(`Video duration: ${video?.duration}s`);
   * }
   * ```
   */
  getPost(postId: string): Promise<LinkedInPost>;

  /**
   * Call any LinkedIn API endpoint directly for advanced usage
   * @param endpointName Name of the endpoint from ENDPOINTS constant
   * @param params Parameters object for the endpoint
   * @returns Promise resolving to raw API response
   * @throws {Error} When endpoint name is unknown
   * @throws {LinkedInError} When required parameters are missing or API request fails
   * @example
   * ```typescript
   * // Call endpoint directly
   * const response = await api.callEndpoint('get_profile_posts', {
   *   username: 'satyanadella',
   *   start: '0'
   * });
   *
   * console.log(response.data);
   * console.log(response.rateLimit.remaining);
   * ```
   */
  callEndpoint(endpointName: string, params?: any): Promise<ApiResponse<any>>;

  /**
   * Get complete documentation for all available endpoints
   * @returns Object containing endpoint configurations and examples
   * @example
   * ```typescript
   * const docs = api.getEndpointDocumentation();
   * console.log(docs.search_people.description);
   * console.log(docs.search_people.parameters.required);
   * ```
   */
  getEndpointDocumentation(): EndpointDocumentation;

  /**
   * Get list of all available endpoint names
   * @returns Array of endpoint names
   * @example
   * ```typescript
   * const endpoints = api.listEndpoints();
   * console.log(endpoints); // ['search_people', 'get_profile_data', ...]
   * ```
   */
  listEndpoints(): string[];

  /**
   * Validate parameters for a specific endpoint before making request
   * @param endpointName Name of the endpoint to validate against
   * @param params Parameters object to validate
   * @returns Validation result with details about missing or extra parameters
   * @example
   * ```typescript
   * const validation = api.validateParameters('search_people', {
   *   keywords: 'engineer'
   * });
   *
   * if (!validation.valid) {
   *   console.log('Missing required params:', validation.missingRequired);
   * }
   * ```
   */
  validateParameters(endpointName: string, params: any): ValidationResult;

  /**
   * Clear all cached data to force fresh API calls
   * @example
   * ```typescript
   * api.clearCache(); // Clears all cached profiles, companies, etc.
   * ```
   */
  clearCache(): void;

  /**
   * Enable debug mode to log API response structures (helpful for debugging null items)
   * @param enabled Whether to enable debug logging
   * @example
   * ```typescript
   * api.setDebugMode(true); // Enable debug logging
   * const results = await api.searchProfiles({ keywords: 'test' });
   * // Will log the response structure to help identify data format issues
   * ```
   */
  setDebugMode(enabled: boolean): void;

  /**
   * Enable or disable caching (enabled by default)
   */
  enableCache: boolean;

  /**
   * Cache timeout in milliseconds (default: 5 minutes)
   */
  cacheTimeout: number;
}

// Branded Types for Type Safety
type LocationId = number & { __brand: 'LocationId' };
type CompanyId = string & { __brand: 'CompanyId' };
type IndustryId = number & { __brand: 'IndustryId' };
type PostUrn = string & { __brand: 'PostUrn' };
type ProfileUrn = string & { __brand: 'ProfileUrn' };
type CompanySize = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I';

// Search Parameters with detailed documentation
interface ProfileSearchParams {
  /**
   * Keywords to search for in profiles (names, headlines, etc.)
   * @example "software engineer", "product manager", "ceo"
   */
  keywords?: string;

  /**
   * Page number for pagination (1, 2, 3, etc.)
   * @default 1
   */
  page?: number;

  /**
   * Location IDs to filter by (use LOCATIONS constants)
   * Can be array of LocationIds or comma-separated string
   * @example [LOCATIONS.US.SAN_FRANCISCO, LOCATIONS.US.NEW_YORK]
   * @example "103644278,101165590"
   */
  geo?: LocationId[] | string;

  /**
   * School/University ID to filter by
   */
  schoolId?: string;

  /**
   * First name to search for
   */
  firstName?: string;

  /**
   * Last name to search for
   */
  lastName?: string;

  /**
   * Keywords related to school/education
   */
  keywordSchool?: string;

  /**
   * Keywords related to job title
   */
  keywordTitle?: string;

  /**
   * Company name to filter by
   * @example "Google", "Microsoft", "Apple"
   */
  company?: string;

  /**
   * Auto retry with different start positions if insufficient items returned (due to private profiles)
   * @default true
   */
  autoRetryForPrivateProfiles?: boolean;

  /**
   * Maximum retry attempts for private profiles
   * @default 5
   */
  maxRetries?: number;

  /**
   * Minimum number of items desired - will retry until this threshold is met
   * @default 1
   * @example 10 // Retry until at least 10 profiles found
   * @example 0 // Disable retries completely
   */
  minItems?: number;
}

interface CompanySearchParams {
  /**
   * Keywords to search for in company names/descriptions
   * @example "artificial intelligence", "fintech", "startup"
   */
  keyword?: string;

  /**
   * Location IDs to filter by (use LOCATIONS constants)
   * @example [LOCATIONS.US.SAN_FRANCISCO]
   */
  locations?: LocationId[];

  /**
   * Industry IDs to filter by (use INDUSTRIES constants)
   * @example [INDUSTRIES.TECHNOLOGY, INDUSTRIES.FINANCIAL_SERVICES]
   */
  industries?: IndustryId[];

  /**
   * Company size categories (use COMPANY_SIZES constants)
   * @example [COMPANY_SIZES.LARGE, COMPANY_SIZES.ENTERPRISE]
   */
  companySizes?: CompanySize[];

  /**
   * Filter to companies that are actively hiring
   * @default false
   */
  hasJobs?: boolean;

  /**
   * Page number for pagination (1, 2, 3, etc.)
   * @default 1
   */
  page?: number;

  /**
   * Auto retry with different pages if insufficient items returned (due to private companies)
   * @default true
   */
  autoRetryForPrivateProfiles?: boolean;

  /**
   * Maximum retry attempts for private companies
   * @default 5
   */
  maxRetries?: number;

  /**
   * Minimum number of items desired - will retry until this threshold is met
   * @default 1
   * @example 10 // Retry until at least 10 companies found
   * @example 0 // Disable retries completely
   */
  minItems?: number;
}

interface PostSearchParams {
  /**
   * Required keywords to search for in post content
   * @example "machine learning", "startup", "leadership"
   */
  keyword: string;

  /**
   * Sort order for results
   * @default "relevance"
   */
  sortBy?: 'date_posted' | 'relevance';

  /**
   * Time filter for post publication date
   * @example "past-24h", "past-week", "past-month"
   */
  datePosted?: string;

  /**
   * Page number for pagination (1, 2, 3, etc.)
   * @default 1
   */
  page?: number;

  /**
   * Filter by content type
   */
  contentType?: string;

  /**
   * Filter posts from specific members (usernames)
   * @example ["satyanadella", "jeffweiner08"]
   */
  fromMember?: string[];

  /**
   * Filter posts that mention specific members
   */
  mentionsMember?: string[];

  /**
   * Filter posts from specific companies (company IDs)
   */
  fromCompany?: CompanyId[];

  /**
   * Filter posts that mention specific organizations
   */
  mentionsOrganization?: CompanyId[];

  /**
   * Filter posts by author's industry
   */
  authorIndustry?: IndustryId[];

  /**
   * Filter posts by author's company
   */
  authorCompany?: CompanyId[];

  /**
   * Filter posts by author's job title
   * @example "CEO", "CTO", "Product Manager"
   */
  authorTitle?: string;

  /**
   * Auto retry with different pages if insufficient items returned
   * @default true
   */
  autoRetryForPrivateProfiles?: boolean;

  /**
   * Maximum retry attempts
   * @default 5
   */
  maxRetries?: number;

  /**
   * Minimum number of items desired - will retry until this threshold is met
   * @default 1
   * @example 10 // Retry until at least 10 posts found
   * @example 0 // Disable retries completely
   */
  minItems?: number;
}

// Search Results
declare class ProfileSearchResult {
  // readonly data: ProfileSearchData;
  readonly params: ProfileSearchParams;
  readonly total: number;
  readonly items: ProfileSearchItemData[];
  hasNextPage(): boolean;
  getNextPage(): Promise<ProfileSearchResult>;
}

declare class CompanySearchResult {
  // readonly data: CompanySearchData;
  readonly params: CompanySearchParams;
  readonly total: number;
  readonly items: CompanySearchItemData[];
  hasNextPage(): boolean;
  getNextPage(): Promise<CompanySearchResult>;
}

declare class PostSearchResult {
  // readonly data: PostSearchData;
  readonly params: PostSearchParams;
  readonly total: number;
  readonly items: PostSearchItemData[];
  hasNextPage(): boolean;
  getNextPage(): Promise<PostSearchResult>;
}

// Full Entities
declare class LinkedInProfile {
  readonly raw: ProfileData;

  getId(): number;
  getUrn(): ProfileUrn;
  getUsername(): string;
  getFirstName(): string;
  getLastName(): string;
  getFullName(): string;
  getHeadline(): string;
  getSummary(): string;
  getLinkedInUrl(): string;

  isTopVoice(): boolean;
  isCreator(): boolean;
  isPremium(): boolean;

  getProfilePictureUrl(size?: 'small' | 'medium' | 'large'): string;
  getBackgroundImageUrl(): string | null;

  getLocation(): {
    country: string;
    city: string;
    full: string;
    countryCode: string;
  };

  getCurrentPosition(): Position | null;
  getAllPositions(): Position[];
  getEducation(): Education[];
  getSkills(): Skill[];
  getSkillsWithEndorsements(): Skill[];
}

declare class LinkedInCompany {
  readonly raw: CompanyData;

  getId(): CompanyId;
  getName(): string;
  getUniversalName(): string;
  getLinkedInUrl(): string;
  getTagline(): string;
  getDescription(): string;
  getWebsite(): string;
  getPhone(): string;

  getEmployeeCount(): number;
  getFollowerCount(): number;
  getStaffCountRange(): string;

  getLogoUrl(size?: 'small' | 'medium' | 'large'): string;
  getCoverImageUrl(): string | null;

  getHeadquarters(): CompanyLocation | null;
  getAllLocations(): CompanyLocation[];

  getIndustries(): string[];
  getSpecialties(): string[];
  getFounded(): number | null;

  isVerified(): boolean;
  isClaimed(): boolean;
}

declare class LinkedInPost {
  readonly raw: PostData;

  getUrn(): PostUrn;
  getText(): string;
  getLinkedInUrl(): string;
  getShareUrl(): string;

  getPostedAt(): Date;
  getPostedDateTimestamp(): number;

  getTotalEngagement(): number;
  getTotalReactionCount(): number;
  getLikeCount(): number;
  getCommentsCount(): number;
  getRepostsCount(): number;

  getAuthor(): PostAuthor;
  getCompany(): any;

  hasVideo(): boolean;
  hasArticle(): boolean;
  hasDocument(): boolean;
  isPoll(): boolean;
  isRepost(): boolean;
  isBrandPartnership(): boolean;

  getVideo(): PostVideo | null;
  getArticle(): PostArticle | null;
}

// Data Types
interface ProfileData {
  id: number;
  urn: string;
  username: string;
  firstName: string;
  lastName: string;
  isTopVoice: boolean;
  isCreator: boolean;
  isPremium: boolean;
  profilePicture: string;
  backgroundImage: ImageInfo[];
  summary: string;
  headline: string;
  geo: GeoInfo;
  educations: Education[];
  position: Position[];
  fullPositions: Position[];
  skills: Skill[];
  projects: any;
  supportedLocales: LocaleInfo[];
  multiLocaleFirstName: Record<string, string>;
  multiLocaleLastName: Record<string, string>;
  multiLocaleHeadline: Record<string, string>;
}

interface CompanyData {
  id: string;
  name: string;
  universalName: string;
  linkedinUrl: string;
  tagline: string;
  description: string;
  type: string;
  phone: string;
  Images: {
    logo: string;
    cover: string;
  };
  isClaimable: boolean;
  backgroundCoverImages: ImageInfo[];
  logos: LogoInfo[];
  staffCount: number;
  headquarter: CompanyLocation;
  locations: CompanyLocation[];
  industries: string[];
  specialities: string[];
  website: string;
  founded: number | null;
  callToAction: CallToAction;
  followerCount: number;
  staffCountRange: string;
  crunchbaseUrl: string;
  fundingData: FundingData;
  featuredCustomers: any;
  pageVerification: {
    verified: boolean;
    lastModifiedAt: number;
  };
}

interface PostData {
  isBrandPartnership: boolean;
  text: string;
  totalReactionCount: number;
  likeCount: number;
  appreciationCount: number;
  empathyCount: number;
  praiseCount: number;
  commentsCount: number;
  repostsCount: number;
  shareUrl: string;
  postedAt: string;
  postedDate: string;
  postedDateTimestamp: number;
  urn: string;
  shareUrn: string;
  author: PostAuthor;
  company: any;
  document: any;
  celebration: any;
  poll: any;
  article: PostArticle;
  entity: any;
  video?: PostVideo;
  resharedPost?: any;
}

// Supporting Types
interface Position {
  companyId: number;
  companyName: string;
  companyUsername: string;
  companyURL: string;
  companyLogo: string;
  companyIndustry: string;
  companyStaffCountRange: string;
  title: string;
  multiLocaleTitle: Record<string, string>;
  multiLocaleCompanyName: Record<string, string>;
  location: string;
  description: string;
  employmentType: string;
  start: DateInfo;
  end: DateInfo;
}

interface Education {
  start: DateInfo;
  end: DateInfo;
  fieldOfStudy: string;
  degree: string;
  grade: string;
  schoolName: string;
  description: string;
  activities: string;
  url: string;
  schoolId: string;
  logo: LogoInfo[];
}

interface Skill {
  name: string;
  passedSkillAssessment: boolean;
  endorsementsCount: number;
}

interface DateInfo {
  year: number;
  month: number;
  day: number;
}

interface GeoInfo {
  country: string;
  city: string;
  full: string;
  countryCode: string;
}

interface ImageInfo {
  url: string;
  width: number;
  height: number;
}

interface LogoInfo {
  url: string;
  width: number;
  height: number;
}

interface LocaleInfo {
  country: string;
  language: string;
}

interface CompanyLocation {
  countryCode: string;
  geographicArea: string;
  country: string;
  city: string;
  postalCode?: string;
  headquarter: boolean;
  line1: string;
}

interface CallToAction {
  type: string;
  displayText: string;
  visible: boolean;
  callToActionMessage: any;
  url: string;
}

interface FundingData {
  updatedAt: string;
  updatedDate: string;
  numFundingRounds: number;
  lastFundingRound: {
    investorsCrunchbaseUrl: string;
    leadInvestors: Array<{
      name: string;
      investorCrunchbaseUrl: string;
    }>;
    fundingRoundCrunchbaseUrl: string;
    fundingType: string;
    moneyRaised: {
      currencyCode: string;
      amount: string;
    };
    numOtherInvestors: number;
    announcedOn: DateInfo;
  };
}

interface PostAuthor {
  id: number;
  firstName: string;
  lastName: string;
  headline: string;
  username: string;
  url: string;
  profilePictures: ImageInfo[];
  urn: string;
}

interface PostSearchItemAuthorData {
  fullName: string;
  headline: string;
  username: string;
  url: string;
  profilePictures: ImageInfo[];
  urn: string;
  type: 'user';
}

interface PostVideo {
  url: string;
  poster: string;
  duration: number;
  thumbnails: any;
  video: any;
}

interface PostArticle {
  title: string;
  subtitle: string;
  link: string;
  newsletter: any;
}

// API Response Types
interface ApiResponse<T> {
  success: boolean;
  endpoint: string;
  data: T;
  status: number;
  headers: any;
  rateLimit: {
    remaining: string;
    reset: Date;
  };
}

// RapidAPI Search Response Types (what the API actually returns)
interface RapidApiProfileSearchResponse {
  success: boolean;
  message: string;
  data: {
    total: number;
    items: ProfileSearchItemData[];
  };
}

interface RapidApiCompanySearchResponse {
  success: boolean;
  message: string;
  data: {
    items: CompanySearchItemData[];
    total: number;
    totalPages: number;
    currentPage: number;
  };
}

interface RapidApiPostSearchResponse {
  success: boolean;
  message: string;
  data: {
    total: number;
    count: number;
    items: PostSearchItemData[];
  };
}

// RapidAPI Individual Get Response Types (direct data without wrapper)
interface RapidApiProfileGetResponse extends ProfileData {
  // Profile get response is direct data without success/message wrapper
}

interface RapidApiCompanyGetResponse extends CompanyData {
  // Company get response is direct data without success/message wrapper
}

interface RapidApiPostGetResponse extends PostData {
  // Post get response is direct data without success/message wrapper
}

// Search Item Data Types (raw data from RapidAPI responses)
interface ProfileSearchItemData {
  fullName: string;
  headline: string;
  summary: string;
  profilePicture: string;
  location: string;
  profileURL: string;
  username: string;
}

interface CompanySearchItemData {
  id: number;
  name: string;
  username: string;
  tagline?: string;
  logo: ImageInfo[];
  linkedinURL: string;
  staffCountRange: any;
}

interface PostSearchItemData {
  urn: string;
  url: string;
  text: string;
  postedAt: string;
  postedDate: string;
  postedDateTimestamp: number;
  reposted: boolean;
  author: PostSearchItemAuthorData;
  socialActivityCountsInsight: any;
  resharedPost?: any;
  video?: any;
  entity?: any;
  article?: any;
  object?: any;
}

// Unified Result Class Data Interfaces (consumer-facing, abstracted from RapidAPI oddities)
interface ProfileSearchData {
  items: ProfileSearchItemData[];
  total: number;
}

interface CompanySearchData {
  items: CompanySearchItemData[];
  total: number;
}

interface PostSearchData {
  items: PostSearchItemData[];
  total: number;
}

interface EndpointDocumentation {
  [endpointName: string]: {
    path: string;
    method: string;
    description: string;
    parameters: {
      required: string[];
      optional: string[];
    };
    example_params: any;
  };
}

// Validation Result
interface ValidationResult {
  /** Whether all required parameters are present */
  valid: boolean;
  /** Array of missing required parameter names */
  missingRequired: string[];
  /** Array of unrecognized parameter names */
  extraParams: string[];
  /** Endpoint configuration object */
  endpoint: any;
}

// Error Types with detailed documentation
/**
 * Base error class for all LinkedIn API related errors
 * @example
 * ```typescript
 * try {
 *   await api.getProfile('username');
 * } catch (error) {
 *   if (error instanceof LinkedInError) {
 *     console.log('LinkedIn API Error:', error.message);
 *     console.log('Error Code:', error.code);
 *   }
 * }
 * ```
 */
declare class LinkedInError extends Error {
  /** Error code identifying the type of error */
  code: string;
  constructor(message: string, code: string);
}

/**
 * Error thrown when API rate limits are exceeded
 * Contains retry information for proper backoff handling
 * @example
 * ```typescript
 * try {
 *   await api.searchProfiles({ keywords: 'test' });
 * } catch (error) {
 *   if (error instanceof RateLimitError) {
 *     console.log(`Rate limited. Retry after: ${error.retryAfter}`);
 *     // Wait until retry time before making more requests
 *     const waitTime = error.retryAfter.getTime() - Date.now();
 *     if (waitTime > 0) {
 *       await new Promise(resolve => setTimeout(resolve, waitTime));
 *     }
 *   }
 * }
 * ```
 */
declare class RateLimitError extends LinkedInError {
  /** Date/time when requests can resume (null if not provided) */
  retryAfter: Date | null;
  constructor(message: string, headers: any);
}

/**
 * Error thrown when requested resource is not found or inaccessible
 * Common causes: private profiles, deleted content, invalid usernames
 * @example
 * ```typescript
 * try {
 *   await api.getProfile('nonexistent-user');
 * } catch (error) {
 *   if (error instanceof NotFoundError) {
 *     console.log('Profile not found or private');
 *     // Handle gracefully - maybe skip this profile or mark as unavailable
 *   }
 * }
 * ```
 */
declare class NotFoundError extends LinkedInError {
  constructor(message: string);
}

/**
 * Error thrown when network requests fail
 * Contains the original error for debugging purposes
 * @example
 * ```typescript
 * try {
 *   await api.getProfile('user');
 * } catch (error) {
 *   if (error instanceof NetworkError) {
 *     console.log('Network error:', error.originalError.message);
 *     // Implement retry logic or fallback
 *   }
 * }
 * ```
 */
declare class NetworkError extends LinkedInError {
  /** Original error that caused the network failure */
  originalError: any;
  constructor(message: string, originalError: any);
}

// Helper Constants with detailed documentation

/**
 * Geographic location IDs for use in search filters
 * Use these constants instead of raw location IDs for better maintainability
 * @example
 * ```typescript
 * import { LOCATIONS } from '@lineai/linkedin-api';
 *
 * // Search in specific cities
 * const results = await api.searchProfiles({
 *   keywords: 'engineer',
 *   geo: [LOCATIONS.US.SAN_FRANCISCO, LOCATIONS.US.NEW_YORK]
 * });
 *
 * // Search across entire US
 * const usResults = await api.searchProfiles({
 *   keywords: 'ceo',
 *   geo: [LOCATIONS.US.ALL]
 * });
 * ```
 */
declare const LOCATIONS: {
  US: {
    /** All United States - broadest US filter */
    ALL: LocationId;
    /** New York City, NY */
    NEW_YORK: LocationId;
    /** San Francisco Bay Area, CA */
    SAN_FRANCISCO: LocationId;
    /** Los Angeles, CA */
    LOS_ANGELES: LocationId;
    /** Chicago, IL */
    CHICAGO: LocationId;
    /** Boston, MA */
    BOSTON: LocationId;
    /** Seattle, WA */
    SEATTLE: LocationId;
    /** Austin, TX */
    AUSTIN: LocationId;
    /** Denver, CO */
    DENVER: LocationId;
    /** Miami, FL */
    MIAMI: LocationId;
  };
};

/**
 * Company size categories for filtering company searches
 * Based on employee count ranges
 * @example
 * ```typescript
 * import { COMPANY_SIZES } from '@lineai/linkedin-api';
 *
 * // Search for large companies
 * const largeCompanies = await api.searchCompanies({
 *   keyword: 'technology',
 *   companySizes: [COMPANY_SIZES.LARGE, COMPANY_SIZES.ENTERPRISE]
 * });
 *
 * // Search all company sizes
 * const allCompanies = await api.searchCompanies({
 *   keyword: 'startup',
 *   companySizes: COMPANY_SIZES.ALL
 * });
 * ```
 */
declare const COMPANY_SIZES: {
  /** Self-employed (1 employee) */
  SELF_EMPLOYED: 'A';
  /** 2-10 employees */
  TINY: 'B';
  /** 11-50 employees */
  SMALL: 'C';
  /** 51-200 employees */
  MEDIUM: 'D';
  /** 201-500 employees */
  LARGE: 'E';
  /** 501-1000 employees */
  XLARGE: 'F';
  /** 1001-5000 employees */
  ENTERPRISE: 'G';
  /** 5001-10000 employees */
  MASSIVE: 'H';
  /** 10000+ employees */
  MEGA: 'I';
  /** Array containing all company size options */
  ALL: CompanySize[];
};

/**
 * Industry category IDs for filtering company and profile searches
 * @example
 * ```typescript
 * import { INDUSTRIES } from '@lineai/linkedin-api';
 *
 * // Search for tech companies
 * const techCompanies = await api.searchCompanies({
 *   keyword: 'artificial intelligence',
 *   industries: [INDUSTRIES.TECHNOLOGY]
 * });
 *
 * // Search for profiles in multiple industries
 * const profiles = await api.searchProfiles({
 *   keywords: 'product manager',
 *   // Add industry filter through company search first
 * });
 * ```
 */
declare const INDUSTRIES: {
  /** Technology and software companies */
  TECHNOLOGY: IndustryId;
  /** Banking, finance, and insurance */
  FINANCIAL_SERVICES: IndustryId;
  /** Healthcare and medical services */
  HEALTHCARE: IndustryId;
  /** Retail and consumer goods */
  RETAIL: IndustryId;
  /** Manufacturing and production */
  MANUFACTURING: IndustryId;
  /** Education and training */
  EDUCATION: IndustryId;
  /** Construction and engineering */
  CONSTRUCTION: IndustryId;
  /** Real estate and property */
  REAL_ESTATE: IndustryId;
  /** Entertainment and media */
  ENTERTAINMENT: IndustryId;
  /** Consulting and professional services */
  CONSULTING: IndustryId;
};

// Helper Functions with detailed documentation

/**
 * Validate if a username meets LinkedIn's format requirements
 * Checks for alphanumeric characters and hyphens, 3-100 characters long
 * @param username The username to validate
 * @returns True if the username format is valid
 * @example
 * ```typescript
 * import { isValidUsername } from '@lineai/linkedin-api';
 *
 * console.log(isValidUsername('john-doe'));     // true
 * console.log(isValidUsername('john@doe'));     // false - contains @
 * console.log(isValidUsername('ab'));          // false - too short
 * console.log(isValidUsername('valid-user123')); // true
 * ```
 */
declare function isValidUsername(username: string): boolean;

/**
 * Extract username from a LinkedIn profile URL
 * Supports various LinkedIn URL formats
 * @param url LinkedIn profile URL (full or partial)
 * @returns The extracted username or null if not found
 * @example
 * ```typescript
 * import { extractUsername } from '@lineai/linkedin-api';
 *
 * // Various URL formats supported
 * console.log(extractUsername('https://linkedin.com/in/john-doe'));        // 'john-doe'
 * console.log(extractUsername('https://www.linkedin.com/in/jane-smith/'));  // 'jane-smith'
 * console.log(extractUsername('linkedin.com/in/ceo-example'));             // 'ceo-example'
 * console.log(extractUsername('https://example.com'));                     // null
 *
 * // Use with getProfile
 * const username = extractUsername(someLinkedInUrl);
 * if (username) {
 *   const profile = await api.getProfile(username);
 * }
 * ```
 */
declare function extractUsername(url: string): string | null;

// Constants with documentation

/**
 * Default profile picture URL used when a profile has no custom picture
 * @example
 * ```typescript
 * import { DEFAULT_PROFILE_PICTURE } from '@lineai/linkedin-api';
 *
 * const profile = await api.getProfile('username');
 * const profilePic = profile.getProfilePictureUrl() || DEFAULT_PROFILE_PICTURE;
 * ```
 */
declare const DEFAULT_PROFILE_PICTURE: string;

/**
 * Complete endpoint definitions for all available LinkedIn API endpoints
 * Contains path, method, parameters, and examples for each endpoint
 * @example
 * ```typescript
 * import { ENDPOINTS } from '@lineai/linkedin-api';
 *
 * // Explore available endpoints
 * console.log(Object.keys(ENDPOINTS));
 *
 * // Get endpoint details
 * const profileEndpoint = ENDPOINTS.get_profile_data;
 * console.log(profileEndpoint.description);
 * console.log(profileEndpoint.parameters.required); // ['username']
 * console.log(profileEndpoint.example_params);
 * ```
 */
declare const ENDPOINTS: EndpointDocumentation;

// Pure ESM Exports
export default LinkedInAPI;

export {
  LinkedInAPI,
  LOCATIONS,
  COMPANY_SIZES,
  INDUSTRIES,
  ENDPOINTS,
  DEFAULT_PROFILE_PICTURE,
  isValidUsername,
  extractUsername,
  LinkedInError,
  RateLimitError,
  NotFoundError,
  NetworkError,
  LinkedInProfile,
  LinkedInCompany,
  LinkedInPost,
  ProfileSearchResult,
  CompanySearchResult,
  PostSearchResult,
};

export type {
  LocationId,
  CompanyId,
  IndustryId,
  PostUrn,
  ProfileUrn,
  CompanySize,
  ProfileSearchParams,
  CompanySearchParams,
  PostSearchParams,
  ValidationResult,
  ProfileData,
  CompanyData,
  PostData,
  Position,
  Education,
  Skill,
  DateInfo,
  GeoInfo,
  ImageInfo,
  LogoInfo,
  LocaleInfo,
  CompanyLocation,
  CallToAction,
  FundingData,
  PostAuthor,
  PostSearchItemAuthorData,
  PostVideo,
  PostArticle,
  ApiResponse,
  EndpointDocumentation,
  ProfileSearchItemData,
  CompanySearchItemData,
  PostSearchItemData,
};