scavio 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -410,6 +410,10 @@ declare class GoogleNamespace {
     trending(options: GoogleTrendingOptions): Promise<Record<string, unknown>>;
 }
 
+/** Comment / feed sort orders. */
+type RedditSort = "HOT" | "NEW" | "TOP" | "BEST" | "CONTROVERSIAL";
+/** Subreddit feed sort orders. */
+type RedditFeedSort = "BEST" | "HOT" | "NEW" | "TOP" | "CONTROVERSIAL" | "RISING";
 interface RedditSearchOptions {
     /** Search query (1-500 characters). */
     query: string;
@@ -421,16 +425,84 @@ interface RedditSearchOptions {
     cursor?: string;
     [key: string]: unknown;
 }
+interface RedditSearchSuggestionsOptions {
+    /** Search query (1-500 characters). */
+    query: string;
+    [key: string]: unknown;
+}
 interface RedditPostOptions {
+    /** Post fullname (t3_...) or bare id. */
+    post_id?: string;
     /** Full Reddit post URL. */
-    url: string;
+    url?: string;
+    [key: string]: unknown;
+}
+interface RedditPostCommentsOptions {
+    /** Post fullname (t3_...). */
+    post_id: string;
+    /** Comment sort order (default 'TOP'). */
+    sort?: RedditSort;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface RedditCommentRepliesOptions {
+    /** Post fullname (t3_...). */
+    post_id: string;
+    /** reply_cursor from a comment in the comments endpoint. */
+    cursor: string;
+    /** Comment sort order (default 'TOP'). */
+    sort?: RedditSort;
+    [key: string]: unknown;
+}
+interface RedditSubredditOptions {
+    /** Subreddit name (without r/). */
+    subreddit: string;
+    [key: string]: unknown;
+}
+interface RedditSubredditPostsOptions {
+    /** Subreddit name (without r/). */
+    subreddit: string;
+    /** Feed sort order (default 'HOT'). */
+    sort?: RedditFeedSort;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface RedditUserOptions {
+    /** Redditor username (without u/). */
+    username: string;
+    [key: string]: unknown;
+}
+interface RedditUserFeedOptions {
+    /** Redditor username (without u/). */
+    username: string;
+    /** Sort order (default 'NEW'). */
+    sort?: RedditSort;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface RedditPopularOptions {
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
     [key: string]: unknown;
 }
 declare class RedditNamespace {
     private client;
     constructor(client: Scavio);
     search(options: RedditSearchOptions): Promise<Record<string, unknown>>;
+    searchSuggestions(options: RedditSearchSuggestionsOptions): Promise<Record<string, unknown>>;
     post(options: RedditPostOptions): Promise<Record<string, unknown>>;
+    postComments(options: RedditPostCommentsOptions): Promise<Record<string, unknown>>;
+    commentReplies(options: RedditCommentRepliesOptions): Promise<Record<string, unknown>>;
+    subreddit(options: RedditSubredditOptions): Promise<Record<string, unknown>>;
+    subredditPosts(options: RedditSubredditPostsOptions): Promise<Record<string, unknown>>;
+    user(options: RedditUserOptions): Promise<Record<string, unknown>>;
+    userPosts(options: RedditUserFeedOptions): Promise<Record<string, unknown>>;
+    userComments(options: RedditUserFeedOptions): Promise<Record<string, unknown>>;
+    popular(options?: RedditPopularOptions): Promise<Record<string, unknown>>;
+    trending(): Promise<Record<string, unknown>>;
 }
 
 interface TikTokProfileOptions {
@@ -692,11 +764,18 @@ interface YouTubeSearchOptions {
     /** Filter by upload date. */
     upload_date?: "last_hour" | "today" | "this_week" | "this_month" | "this_year";
     /** Filter by result type. */
-    type?: "video" | "channel" | "playlist";
+    type?: "video" | "channel" | "playlist" | "movie";
     /** short (<4 min), medium (4-20 min), long (>20 min). */
     duration?: "short" | "medium" | "long";
     /** Sort order. */
     sort_by?: "relevance" | "date" | "view_count" | "rating";
+    /**
+     * Feature filters, e.g. ["hd", "4k", "subtitles", "creative_commons",
+     * "live", "360", "3d", "hdr", "vr180"].
+     */
+    features?: string[];
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
     /** HD videos only. */
     hd?: boolean;
     /** Videos with subtitles/CC only. */
@@ -719,8 +798,107 @@ interface YouTubeSearchOptions {
     video_3d?: boolean;
     [key: string]: unknown;
 }
+interface YouTubeShortsOptions {
+    /** Search query (1-500 characters). Sent to the API as 'search'. */
+    query: string;
+    /** Sort order. */
+    sort_by?: "relevance" | "date" | "view_count" | "rating";
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeSuggestionsOptions {
+    /** Search query (1-500 characters). Sent to the API as 'search'. */
+    query: string;
+    /** Language code for suggestions (default 'en'). */
+    language?: string;
+    /** Region code for suggestions (default 'US'). */
+    region?: string;
+    [key: string]: unknown;
+}
+interface YouTubeVideoOptions {
+    /** YouTube video id (e.g. 'dQw4w9WgXcQ') or a full watch URL. */
+    video_id: string;
+    [key: string]: unknown;
+}
+/** @deprecated Use YouTubeVideoOptions with youtube.video(). */
 interface YouTubeMetadataOptions {
-    /** YouTube video id (e.g. 'dQw4w9WgXcQ'). */
+    /** YouTube video id (e.g. 'dQw4w9WgXcQ') or a full watch URL. */
+    video_id: string;
+    [key: string]: unknown;
+}
+interface YouTubeCommentsOptions {
+    /** YouTube video id or a full watch URL. */
+    video_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeCommentRepliesOptions {
+    /** YouTube video id or a full watch URL. */
+    video_id: string;
+    /** Reply cursor from a parent comment's 'reply_cursor'. */
+    reply_cursor: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeTranscriptOptions {
+    /** YouTube video id or a full watch URL. */
+    video_id: string;
+    /** Caption language code (default 'en'). */
+    language?: string;
+    /** 'text' for plain transcript, 'srt' for timed subtitles (default 'text'). */
+    format?: "text" | "srt";
+    [key: string]: unknown;
+}
+interface YouTubeRelatedOptions {
+    /** YouTube video id or a full watch URL. */
+    video_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeChannelSearchOptions {
+    /** Search query (1-500 characters). Sent to the API as 'search'. */
+    query: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeChannelOptions {
+    /** YouTube channel id, @handle, or channel URL. */
+    channel_id: string;
+    [key: string]: unknown;
+}
+interface YouTubeChannelVideosOptions {
+    /** YouTube channel id. */
+    channel_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeChannelShortsOptions {
+    /** YouTube channel id. */
+    channel_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeChannelCommunityOptions {
+    /** YouTube channel id. */
+    channel_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface YouTubeChannelResolveOptions {
+    /** A channel @handle or channel URL to resolve to a channel id. */
+    channel: string;
+    [key: string]: unknown;
+}
+interface YouTubeStreamsOptions {
+    /** YouTube video id or a full watch URL. */
     video_id: string;
     [key: string]: unknown;
 }
@@ -728,7 +906,231 @@ declare class YouTubeNamespace {
     private client;
     constructor(client: Scavio);
     search(options: YouTubeSearchOptions): Promise<Record<string, unknown>>;
+    shorts(options: YouTubeShortsOptions): Promise<Record<string, unknown>>;
+    suggestions(options: YouTubeSuggestionsOptions): Promise<Record<string, unknown>>;
+    video(options: YouTubeVideoOptions): Promise<Record<string, unknown>>;
+    /** @deprecated Use youtube.video(). Alias kept for backward compatibility. */
     metadata(options: YouTubeMetadataOptions): Promise<Record<string, unknown>>;
+    comments(options: YouTubeCommentsOptions): Promise<Record<string, unknown>>;
+    commentReplies(options: YouTubeCommentRepliesOptions): Promise<Record<string, unknown>>;
+    transcript(options: YouTubeTranscriptOptions): Promise<Record<string, unknown>>;
+    related(options: YouTubeRelatedOptions): Promise<Record<string, unknown>>;
+    channelSearch(options: YouTubeChannelSearchOptions): Promise<Record<string, unknown>>;
+    channel(options: YouTubeChannelOptions): Promise<Record<string, unknown>>;
+    channelVideos(options: YouTubeChannelVideosOptions): Promise<Record<string, unknown>>;
+    channelShorts(options: YouTubeChannelShortsOptions): Promise<Record<string, unknown>>;
+    channelCommunity(options: YouTubeChannelCommunityOptions): Promise<Record<string, unknown>>;
+    channelResolve(options: YouTubeChannelResolveOptions): Promise<Record<string, unknown>>;
+    streams(options: YouTubeStreamsOptions): Promise<Record<string, unknown>>;
+}
+
+interface TwitterSearchOptions {
+    /** Search query (1-500 characters). */
+    search: string;
+    /** Result category (default 'Top'). */
+    search_type?: "Top" | "Latest" | "People" | "Photos" | "Videos";
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface TwitterTweetOptions {
+    /** Tweet id. */
+    tweet_id: string;
+    [key: string]: unknown;
+}
+interface TwitterTweetCommentsOptions {
+    /** Tweet id. */
+    tweet_id: string;
+    /** 'top' (ranked) or 'latest' (chronological); default 'top'. */
+    rank?: "top" | "latest";
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface TwitterTweetRetweetersOptions {
+    /** Tweet id. */
+    tweet_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface TwitterUserOptions {
+    /** A Twitter handle (without the @). */
+    screen_name: string;
+    [key: string]: unknown;
+}
+interface TwitterUserFeedOptions {
+    /** A Twitter handle (without the @). */
+    screen_name: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface TwitterTrendingOptions {
+    /** Country name (default 'UnitedStates'). */
+    country?: string;
+    [key: string]: unknown;
+}
+declare class TwitterNamespace {
+    private client;
+    constructor(client: Scavio);
+    search(options: TwitterSearchOptions): Promise<Record<string, unknown>>;
+    tweet(options: TwitterTweetOptions): Promise<Record<string, unknown>>;
+    tweetComments(options: TwitterTweetCommentsOptions): Promise<Record<string, unknown>>;
+    tweetRetweeters(options: TwitterTweetRetweetersOptions): Promise<Record<string, unknown>>;
+    user(options: TwitterUserOptions): Promise<Record<string, unknown>>;
+    userTweets(options: TwitterUserFeedOptions): Promise<Record<string, unknown>>;
+    userReplies(options: TwitterUserFeedOptions): Promise<Record<string, unknown>>;
+    userMedia(options: TwitterUserFeedOptions): Promise<Record<string, unknown>>;
+    userFollowers(options: TwitterUserFeedOptions): Promise<Record<string, unknown>>;
+    userFollowings(options: TwitterUserFeedOptions): Promise<Record<string, unknown>>;
+    trending(options?: TwitterTrendingOptions): Promise<Record<string, unknown>>;
+}
+
+interface LinkedInPersonOptions {
+    /** Public identifier (vanity handle). */
+    username: string;
+    /** Include the experiences section (default true server-side). */
+    include_experiences?: boolean;
+    /** Include the educations section (default true server-side). */
+    include_educations?: boolean;
+    /** Include the skills section (default true server-side). */
+    include_skills?: boolean;
+    /** Include the certifications section (default true server-side). */
+    include_certifications?: boolean;
+    /** Include follower and connection counts (default true server-side). */
+    include_follower_and_connection?: boolean;
+    [key: string]: unknown;
+}
+interface LinkedInPersonRefOptions {
+    /** Member urn. */
+    urn?: string;
+    /** Public identifier; resolved to a urn if urn is omitted. */
+    username?: string;
+    [key: string]: unknown;
+}
+interface LinkedInPersonPostsOptions {
+    /** Member urn. */
+    urn?: string;
+    /** Public identifier; resolved to a urn if urn is omitted. */
+    username?: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface LinkedInPersonContactOptions {
+    /** Public identifier (vanity handle). */
+    username: string;
+    [key: string]: unknown;
+}
+interface LinkedInCompanyOptions {
+    /** Company universal name (slug) or LinkedIn company URL. */
+    company: string;
+    [key: string]: unknown;
+}
+interface LinkedInCompanyPostsOptions {
+    /** Company universal name (slug) or LinkedIn company URL. */
+    company: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    /** Results per page (1-100). */
+    count?: number;
+    [key: string]: unknown;
+}
+interface LinkedInCompanyRefOptions {
+    /** Numeric company id. */
+    company_id?: string;
+    /** Company slug/url; resolved to a company_id if company_id is omitted. */
+    company?: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface LinkedInSearchPeopleOptions {
+    /** Name to search for. */
+    search?: string;
+    /** Job title filter. */
+    title?: string;
+    /** Company filter. */
+    company?: string;
+    /** School filter. */
+    school?: string;
+    /** A geo name or id to filter by. */
+    location?: string;
+    /** Page cursor (page number). */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface LinkedInSearchJobsOptions {
+    /** Search query (1-500 characters). */
+    search: string;
+    /** Page cursor (page number). */
+    cursor?: string;
+    /** Date-posted filter. */
+    date_posted?: string;
+    /** Geo code to filter by. */
+    geocode?: string;
+    /** Experience level filter. */
+    experience_level?: string;
+    /** Remote filter. */
+    remote?: string;
+    /** Job type filter. */
+    job_type?: string;
+    [key: string]: unknown;
+}
+interface LinkedInSearchPostsOptions {
+    /** Search query (1-500 characters). */
+    search: string;
+    /** Page cursor (page number). */
+    cursor?: string;
+    /** Date-posted filter. */
+    date_posted?: string;
+    /** Sort order. */
+    sort_by?: string;
+    /** Content type filter. */
+    content_type?: string;
+    [key: string]: unknown;
+}
+interface LinkedInJobOptions {
+    /** Job listing id. */
+    job_id: string;
+    /** Include the required-skills section. */
+    include_skills?: boolean;
+    [key: string]: unknown;
+}
+interface LinkedInPostOptions {
+    /** Post id or activity urn. */
+    post_id: string;
+    [key: string]: unknown;
+}
+interface LinkedInPostCommentsOptions {
+    /** Post id or activity urn. */
+    post_id: string;
+    /** Pagination cursor from a prior response. */
+    cursor?: string;
+    /** Comment sort order. */
+    sort_order?: "relevance" | "recent";
+    /** Post type. */
+    post_type?: "activity" | "ugc";
+    [key: string]: unknown;
+}
+declare class LinkedInNamespace {
+    private client;
+    constructor(client: Scavio);
+    person(options: LinkedInPersonOptions): Promise<Record<string, unknown>>;
+    personAbout(options: LinkedInPersonRefOptions): Promise<Record<string, unknown>>;
+    personPosts(options: LinkedInPersonPostsOptions): Promise<Record<string, unknown>>;
+    personContact(options: LinkedInPersonContactOptions): Promise<Record<string, unknown>>;
+    company(options: LinkedInCompanyOptions): Promise<Record<string, unknown>>;
+    companyPosts(options: LinkedInCompanyPostsOptions): Promise<Record<string, unknown>>;
+    companyPeople(options: LinkedInCompanyRefOptions): Promise<Record<string, unknown>>;
+    companyJobs(options: LinkedInCompanyRefOptions): Promise<Record<string, unknown>>;
+    searchPeople(options: LinkedInSearchPeopleOptions): Promise<Record<string, unknown>>;
+    searchJobs(options: LinkedInSearchJobsOptions): Promise<Record<string, unknown>>;
+    searchPosts(options: LinkedInSearchPostsOptions): Promise<Record<string, unknown>>;
+    job(options: LinkedInJobOptions): Promise<Record<string, unknown>>;
+    post(options: LinkedInPostOptions): Promise<Record<string, unknown>>;
+    postComments(options: LinkedInPostCommentsOptions): Promise<Record<string, unknown>>;
 }
 
 interface ScavioConfig {
@@ -751,6 +1153,8 @@ declare class Scavio {
     readonly reddit: RedditNamespace;
     readonly tiktok: TikTokNamespace;
     readonly instagram: InstagramNamespace;
+    readonly twitter: TwitterNamespace;
+    readonly linkedin: LinkedInNamespace;
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
@@ -810,4 +1214,4 @@ declare class ScavioAPIError extends ScavioError {
     constructor(statusCode: number, message: string, responseBody?: Record<string, unknown>);
 }
 
-export { type AmazonProductOptions, type AmazonSearchOptions, BadRequestError, type GoogleAiModeOptions, type GoogleFlightsOptions, type GoogleHotelsDetailOptions, type GoogleHotelsOptions, type GoogleMapsPlaceOptions, type GoogleMapsReviewsOptions, type GoogleMapsSearchOptions, type GoogleNewsOptions, type GoogleSearchOptions, type GoogleShoppingOptions, type GoogleShoppingProductOptions, type GoogleShoppingStoresOptions, type GoogleTrendingOptions, type GoogleTrendsOptions, type InstagramCommentRepliesOptions, type InstagramFollowOptions, type InstagramPostCommentsOptions, type InstagramPostOptions, type InstagramProfileOptions, type InstagramSearchOptions, type InstagramStoriesOptions, type InstagramUserFeedOptions, InsufficientCreditsError, InvalidAPIKeyError, MissingAPIKeyError, NotFoundError, RateLimitError, type RedditPostOptions, type RedditSearchOptions, Scavio, ScavioAPIError, type ScavioConfig, ScavioConnectionError, ScavioError, ScavioTimeoutError, type TikTokCommentRepliesOptions, type TikTokHashtagOptions, type TikTokHashtagVideosOptions, type TikTokProfileOptions, type TikTokSearchUsersOptions, type TikTokSearchVideosOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type WalmartProductOptions, type WalmartSearchOptions, type YouTubeMetadataOptions, type YouTubeSearchOptions };
+export { type AmazonProductOptions, type AmazonSearchOptions, BadRequestError, type GoogleAiModeOptions, type GoogleFlightsOptions, type GoogleHotelsDetailOptions, type GoogleHotelsOptions, type GoogleMapsPlaceOptions, type GoogleMapsReviewsOptions, type GoogleMapsSearchOptions, type GoogleNewsOptions, type GoogleSearchOptions, type GoogleShoppingOptions, type GoogleShoppingProductOptions, type GoogleShoppingStoresOptions, type GoogleTrendingOptions, type GoogleTrendsOptions, type InstagramCommentRepliesOptions, type InstagramFollowOptions, type InstagramPostCommentsOptions, type InstagramPostOptions, type InstagramProfileOptions, type InstagramSearchOptions, type InstagramStoriesOptions, type InstagramUserFeedOptions, InsufficientCreditsError, InvalidAPIKeyError, type LinkedInCompanyOptions, type LinkedInCompanyPostsOptions, type LinkedInCompanyRefOptions, type LinkedInJobOptions, type LinkedInPersonContactOptions, type LinkedInPersonOptions, type LinkedInPersonPostsOptions, type LinkedInPersonRefOptions, type LinkedInPostCommentsOptions, type LinkedInPostOptions, type LinkedInSearchJobsOptions, type LinkedInSearchPeopleOptions, type LinkedInSearchPostsOptions, MissingAPIKeyError, NotFoundError, RateLimitError, type RedditCommentRepliesOptions, type RedditFeedSort, type RedditPopularOptions, type RedditPostCommentsOptions, type RedditPostOptions, type RedditSearchOptions, type RedditSearchSuggestionsOptions, type RedditSort, type RedditSubredditOptions, type RedditSubredditPostsOptions, type RedditUserFeedOptions, type RedditUserOptions, Scavio, ScavioAPIError, type ScavioConfig, ScavioConnectionError, ScavioError, ScavioTimeoutError, type TikTokCommentRepliesOptions, type TikTokHashtagOptions, type TikTokHashtagVideosOptions, type TikTokProfileOptions, type TikTokSearchUsersOptions, type TikTokSearchVideosOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type TwitterSearchOptions, type TwitterTrendingOptions, type TwitterTweetCommentsOptions, type TwitterTweetOptions, type TwitterTweetRetweetersOptions, type TwitterUserFeedOptions, type TwitterUserOptions, type WalmartProductOptions, type WalmartSearchOptions, type YouTubeChannelCommunityOptions, type YouTubeChannelOptions, type YouTubeChannelResolveOptions, type YouTubeChannelSearchOptions, type YouTubeChannelShortsOptions, type YouTubeChannelVideosOptions, type YouTubeCommentRepliesOptions, type YouTubeCommentsOptions, type YouTubeMetadataOptions, type YouTubeRelatedOptions, type YouTubeSearchOptions, type YouTubeShortsOptions, type YouTubeStreamsOptions, type YouTubeSuggestionsOptions, type YouTubeTranscriptOptions, type YouTubeVideoOptions };