scavio 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -624,6 +624,169 @@ declare class TikTokNamespace {
     userFollowings(options: TikTokUserFollowingsOptions): Promise<Record<string, unknown>>;
 }
 
+/** Marketplace regions served by suggestions, product, reviews, and shop products. */
+type TikTokShopRegion = "US" | "GB" | "SG" | "MY" | "PH" | "TH" | "VN" | "ID";
+/** Marketplace regions served by category listings. */
+type TikTokShopListingRegion = "US" | "GB";
+/** Review ordering: 'relevant' is text-complete and image-heavy, 'recent' is fresher but text-sparse. */
+type TikTokShopReviewSort = "relevant" | "recent";
+interface TikTokShopSearchOptions {
+    /** Search query (1-200 characters). US catalog only. */
+    search: string;
+    /** Opaque cursor from a prior response's next_cursor. */
+    cursor?: string;
+    [key: string]: unknown;
+}
+interface TikTokShopSuggestionsOptions {
+    /** Partial query to expand (1-100 characters). */
+    search: string;
+    /** Marketplace region (default 'US'). */
+    region?: TikTokShopRegion;
+    [key: string]: unknown;
+}
+interface TikTokShopProductOptions {
+    /** TikTok Shop product id (6-25 digits). */
+    product_id: string;
+    /** Marketplace region (default 'US'). */
+    region?: TikTokShopRegion;
+    [key: string]: unknown;
+}
+interface TikTokShopProductReviewsOptions {
+    /** TikTok Shop product id (6-25 digits). */
+    product_id: string;
+    /** 1-based page number (1-500, default 1). */
+    page?: number;
+    /** Reviews per page (1-200, default 20). */
+    page_size?: number;
+    /** 'relevant' (default) is text-complete and image-heavy; 'recent' is fresher but far more text-sparse. */
+    sort?: TikTokShopReviewSort;
+    /** Only reviews with this star rating (1-5). */
+    rating?: number;
+    /** Only reviews with a photo or video (default false). */
+    has_media?: boolean;
+    /** Only verified purchases (default false). */
+    verified_only?: boolean;
+    /** Marketplace region (default 'US'). */
+    region?: TikTokShopRegion;
+    [key: string]: unknown;
+}
+interface TikTokShopCategoryProductsOptions {
+    /** Category id from tiktokShop.categories(); level 1 or 2 both work. */
+    category_id: string;
+    /** Opaque cursor from a prior response's next_cursor. */
+    cursor?: string;
+    /** Marketplace region, 'US' or 'GB' only (default 'US'). */
+    region?: TikTokShopListingRegion;
+    [key: string]: unknown;
+}
+interface TikTokShopShopProductsOptions {
+    /** TikTok Shop seller id (also called seller_id elsewhere on TikTok). */
+    shop_id: string;
+    /** Opaque cursor from a prior response's next_cursor. */
+    cursor?: string;
+    /** Marketplace region (default 'US'). */
+    region?: TikTokShopRegion;
+    [key: string]: unknown;
+}
+interface TikTokShopResolveOptions {
+    /** A TikTok Shop product or store URL, affiliate share link, or vt.tiktok.com short link. */
+    url: string;
+    [key: string]: unknown;
+}
+declare class TikTokShopNamespace {
+    private client;
+    constructor(client: Scavio);
+    /**
+     * Search TikTok Shop products by keyword (US catalog), up to 30 per page with
+     * exact prices, ratings, and shop details. Paginate with next_cursor and dedupe
+     * by product_id across pages.
+     *
+     * This is one of the three endpoints that return exact prices; tiktokShop.product()
+     * does not return a price. A product_id returned here is not guaranteed to resolve
+     * on tiktokShop.product() - only about 44% do.
+     */
+    search(options: TikTokShopSearchOptions): Promise<Record<string, unknown>>;
+    /**
+     * Keyword autocomplete and expansion for a partial query, across 8 marketplace
+     * regions. Suggestions are not guaranteed prefix matches: a misspelling returns
+     * typo corrections, and results can include brand and shop names.
+     */
+    searchSuggestions(options: TikTokShopSuggestionsOptions): Promise<Record<string, unknown>>;
+    /**
+     * Full product detail: description, images, variants with stock, shipping, shop
+     * profile, category path, and top reviews.
+     *
+     * Two limits worth knowing before you build on this:
+     *
+     * 1. It resolves only about 44% of the product ids returned by tiktokShop.search().
+     *    Upstream has no detail data for the rest, so an HTTP 404 is a normal outcome,
+     *    not an error. Skip the item rather than retrying - retries do not help and no
+     *    other region carries it. Search to product is not a reliable pipeline.
+     *
+     *    This method throws `NotFoundError` on that 404 (there is no `data` field in
+     *    the response body to test), so a loop over search ids must catch it or it
+     *    dies on the first miss:
+     *
+     *    ```ts
+     *    import { NotFoundError } from "scavio";
+     *
+     *    for (const productId of productIds) {
+     *      try {
+     *        const detail = await client.tiktokShop.product({ product_id: productId });
+     *      } catch (e) {
+     *        if (e instanceof NotFoundError) continue; // no detail upstream; skip
+     *        throw e;
+     *      }
+     *    }
+     *    ```
+     *
+     *    tiktokShop.productReviews() often works for ids product() cannot resolve: of
+     *    8 such ids tested, 8 returned HTTP 200 and 7 carried at least one review, so
+     *    it is a useful fallback source of product detail.
+     * 2. It does NOT return a price. Upstream masks the price on the product page.
+     *    Exact prices come from tiktokShop.search(), tiktokShop.shopProducts(), and
+     *    tiktokShop.categoryProducts().
+     */
+    product(options: TikTokShopProductOptions): Promise<Record<string, unknown>>;
+    /**
+     * Paginated product reviews with text, images, star histogram, and
+     * verified-purchase flags, up to 200 per call. total_reviews drifts between calls
+     * and must not be used to compute a page count; page with has_more instead.
+     */
+    productReviews(options: TikTokShopProductReviewsOptions): Promise<Record<string, unknown>>;
+    /**
+     * The global TikTok Shop category tree: 28 top-level categories, 240 nodes, two
+     * levels deep. Category ids are identical in every region and names are always
+     * English.
+     */
+    categories(): Promise<Record<string, unknown>>;
+    /**
+     * Products listed under a category id from tiktokShop.categories(), with exact
+     * prices. Page size is inconsistent upstream (15 to 20 per page), so always
+     * paginate with next_cursor rather than assuming a fixed page size. Category
+     * listings are shallow: after a few pages the source stops returning new products
+     * and has_more turns false, which is the end of the listing rather than an error.
+     */
+    categoryProducts(options: TikTokShopCategoryProductsOptions): Promise<Record<string, unknown>>;
+    /**
+     * A shop's product catalog, 30 per page, with exact prices. Shop follower count,
+     * location, and shop-level rating are not available here; call
+     * tiktokShop.product() for the full shop profile.
+     */
+    shopProducts(options: TikTokShopShopProductsOptions): Promise<Record<string, unknown>>;
+    /**
+     * Resolve any TikTok Shop URL or share link to a product_id or shop_id, ready to
+     * pass to the other methods. Accepts canonical product and store pages,
+     * tiktok.com/view links, affiliate share links, and vt.tiktok.com short links.
+     */
+    resolve(options: TikTokShopResolveOptions): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Instagram endpoints (/api/v1/instagram). Credit cost varies by endpoint:
+ * `userPosts` costs 2 credits, every other endpoint costs 8.
+ * See https://scavio.dev/docs/instagram-api.
+ */
 interface InstagramProfileOptions {
     /** Instagram username (without the @). */
     username?: string;
@@ -987,150 +1150,125 @@ declare class XNamespace {
     trending(options?: XTrendingOptions): Promise<Record<string, unknown>>;
 }
 
+/** A member reference: a vanity handle, or a full profile URL. */
 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. */
+    /** Public identifier (vanity handle), e.g. "williamhgates". */
     username?: string;
+    /** Full LinkedIn profile URL, as an alternative to username. */
+    url?: 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;
+/** A company reference: a universal name (slug), or a full company URL. */
+interface LinkedInCompanyOptions {
+    /** Company universal name (slug), e.g. "microsoft". */
+    company?: string;
+    /** Full LinkedIn company URL, as an alternative to company. */
+    url?: string;
     [key: string]: unknown;
 }
-interface LinkedInPersonContactOptions {
-    /** Public identifier (vanity handle). */
-    username: string;
+/** @deprecated Use {@link LinkedInPersonOptions}. */
+type LinkedInPersonRefOptions = LinkedInPersonOptions;
+/** @deprecated Use {@link LinkedInPersonOptions}. */
+type LinkedInPersonPostsOptions = LinkedInPersonOptions;
+/** @deprecated Use {@link LinkedInCompanyOptions}. */
+type LinkedInCompanyPostsOptions = LinkedInCompanyOptions;
+interface LinkedInSearchJobsOptions {
+    /** Search keyword. */
+    search: string;
+    /** Geographic filter; omit to search everywhere. */
+    location?: string;
     [key: string]: unknown;
 }
-interface LinkedInCompanyOptions {
-    /** Company universal name (slug) or LinkedIn company URL. */
-    company: string;
+interface LinkedInJobOptions {
+    /** Job listing id. */
+    job_id?: string;
+    /** Full LinkedIn job URL, as an alternative to job_id. */
+    url?: 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;
+interface LinkedInPostOptions {
+    /** Post id or activity urn. */
+    post_id?: string;
+    /** Full LinkedIn post URL, as an alternative to post_id. */
+    url?: string;
+    [key: string]: unknown;
+}
+interface LinkedInPostCommentsOptions extends LinkedInPostOptions {
+    /** 1-based page number, 10 comments per page. */
+    page?: number;
+}
+/** @deprecated Retired upstream; always returns HTTP 410. */
+interface LinkedInPersonContactOptions {
+    username?: string;
     [key: string]: unknown;
 }
+/** @deprecated Retired upstream; always returns HTTP 410. */
 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;
 }
+/** @deprecated Retired upstream; always returns HTTP 410. */
 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;
 }
+/** @deprecated Retired upstream; always returns HTTP 410. */
 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";
+    search?: string;
     [key: string]: unknown;
 }
 declare class LinkedInNamespace {
     private client;
     constructor(client: Scavio);
+    /** Full profile: about text, experience, education, honours and links. */
     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>>;
+    /** The about-only slice of the profile payload. */
+    personAbout(options: LinkedInPersonOptions): Promise<Record<string, unknown>>;
+    /** Recent posts, up to 50. Upstream exposes no further pages. */
+    personPosts(options: LinkedInPersonOptions): Promise<Record<string, unknown>>;
+    /** Company profile, including locations and featured employees. */
     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>>;
+    /** Recent company posts, up to 50. Upstream exposes no further pages. */
+    companyPosts(options: LinkedInCompanyOptions): Promise<Record<string, unknown>>;
+    /** Job search. Upstream rotates its result set, so repeat calls differ. */
     searchJobs(options: LinkedInSearchJobsOptions): Promise<Record<string, unknown>>;
-    searchPosts(options: LinkedInSearchPostsOptions): Promise<Record<string, unknown>>;
+    /** Full detail for one job listing, including the hiring company. */
     job(options: LinkedInJobOptions): Promise<Record<string, unknown>>;
+    /** Full detail for one post, including its top visible comments. */
     post(options: LinkedInPostOptions): Promise<Record<string, unknown>>;
+    /** Comments with their replies, 10 per page. */
     postComments(options: LinkedInPostCommentsOptions): Promise<Record<string, unknown>>;
+    /**
+     * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+     * never billed.
+     */
+    personContact(options: LinkedInPersonContactOptions): Promise<Record<string, unknown>>;
+    /**
+     * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+     * never billed. `company()` returns `featured_employees`, a small sample of
+     * staff profiles.
+     */
+    companyPeople(options: LinkedInCompanyRefOptions): Promise<Record<string, unknown>>;
+    /**
+     * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+     * never billed. Use `searchJobs()` with the company name as the search term.
+     */
+    companyJobs(options: LinkedInCompanyRefOptions): Promise<Record<string, unknown>>;
+    /**
+     * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+     * never billed.
+     */
+    searchPeople(options: LinkedInSearchPeopleOptions): Promise<Record<string, unknown>>;
+    /**
+     * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+     * never billed.
+     */
+    searchPosts(options: LinkedInSearchPostsOptions): Promise<Record<string, unknown>>;
 }
 
 interface ScavioConfig {
@@ -1152,6 +1290,7 @@ declare class Scavio {
     readonly youtube: YouTubeNamespace;
     readonly reddit: RedditNamespace;
     readonly tiktok: TikTokNamespace;
+    readonly tiktokShop: TikTokShopNamespace;
     readonly instagram: InstagramNamespace;
     readonly x: XNamespace;
     readonly linkedin: LinkedInNamespace;
@@ -1214,4 +1353,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, 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 WalmartProductOptions, type WalmartSearchOptions, type XSearchOptions, type XTrendingOptions, type XTweetCommentsOptions, type XTweetOptions, type XTweetRetweetersOptions, type XUserFeedOptions, type XUserOptions, 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 };
+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 TikTokShopCategoryProductsOptions, type TikTokShopListingRegion, type TikTokShopProductOptions, type TikTokShopProductReviewsOptions, type TikTokShopRegion, type TikTokShopResolveOptions, type TikTokShopReviewSort, type TikTokShopSearchOptions, type TikTokShopShopProductsOptions, type TikTokShopSuggestionsOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type WalmartProductOptions, type WalmartSearchOptions, type XSearchOptions, type XTrendingOptions, type XTweetCommentsOptions, type XTweetOptions, type XTweetRetweetersOptions, type XUserFeedOptions, type XUserOptions, 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 };