@crawlkit-sh/sdk 1.0.2 → 1.1.0

package/dist/index.d.cts

@@ -892,6 +892,15 @@ interface AppStoreReviewsOptions {
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
+/**
+ * Options for fetching App Store app details
+ */
+interface AppStoreDetailOptions {
+    /** Language code (e.g., 'en', 'tr') */
+    lang?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
 /**
  * Parameters for the App Store reviews endpoint
  */
@@ -903,6 +912,15 @@ interface AppStoreReviewsParams {
     /** Options */
     options?: AppStoreReviewsOptions;
 }
+/**
+ * Parameters for the App Store detail endpoint
+ */
+interface AppStoreDetailParams {
+    /** App ID (numeric ID from App Store URL) or URL */
+    appId: string;
+    /** Options */
+    options?: AppStoreDetailOptions;
+}
 /**
  * App Store review
  */
@@ -932,10 +950,238 @@ interface AppStoreReviewsData {
     creditsUsed: number;
     creditsRemaining: number;
 }
+/**
+ * Data returned from the App Store detail endpoint
+ * Endpoint fields can vary, so this type keeps known common fields
+ * while allowing extra keys from the API.
+ */
+interface AppStoreDetailData {
+    appId?: string;
+    appName?: string;
+    developer?: string;
+    rating?: number;
+    ratingCount?: number;
+    reviewsCount?: number;
+    version?: string;
+    description?: string;
+    icon?: string;
+    screenshots?: string[];
+    timing?: {
+        total: number;
+    };
+    creditsUsed?: number;
+    creditsRemaining?: number;
+    [key: string]: unknown;
+}
 /**
  * Response from the App Store reviews endpoint
  */
 type AppStoreReviewsResponse = ApiSuccessResponse<AppStoreReviewsData>;
+/**
+ * Response from the App Store detail endpoint
+ */
+type AppStoreDetailResponse = ApiSuccessResponse<AppStoreDetailData>;
+
+/**
+ * Common options for TikTok crawl endpoints
+ */
+interface TikTokOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Parameters for scraping a TikTok profile
+ */
+interface TikTokProfileParams {
+    /** TikTok username (with or without @) */
+    username: string;
+    /** Options */
+    options?: TikTokOptions;
+}
+/**
+ * Parameters for scraping a TikTok post
+ */
+interface TikTokPostParams {
+    /** TikTok post URL */
+    url: string;
+    /** Options */
+    options?: TikTokOptions;
+}
+/**
+ * Parameters for listing TikTok posts
+ */
+interface TikTokPostsParams {
+    /** TikTok username (with or without @) */
+    username: string;
+    /** Pagination cursor from previous response */
+    cursor?: number;
+    /** Optional secUid from previous response to speed up pagination */
+    secUid?: string;
+    /** Options */
+    options?: TikTokOptions;
+}
+/**
+ * TikTok profile stats
+ */
+interface TikTokProfileStats {
+    followers: number;
+    following: number;
+    likes: number;
+    videos: number;
+    friends?: number;
+    digg?: number;
+}
+/**
+ * TikTok profile data
+ */
+interface TikTokProfile {
+    id: string;
+    secUid?: string | null;
+    username: string;
+    nickname?: string;
+    bio?: string;
+    bioLink?: string | null;
+    avatar?: string;
+    verified?: boolean;
+    privateAccount?: boolean;
+    isOrganization?: boolean;
+    commerceUser?: boolean;
+    category?: string | null;
+    language?: string | null;
+    region?: string | null;
+    createdAt?: string | null;
+    stats?: TikTokProfileStats;
+}
+/**
+ * TikTok post author
+ */
+interface TikTokPostAuthor {
+    id?: string | null;
+    username?: string | null;
+    nickname?: string | null;
+    avatar?: string | null;
+    verified?: boolean;
+}
+/**
+ * TikTok post music info
+ */
+interface TikTokPostMusic {
+    title?: string | null;
+    author?: string | null;
+    album?: string | null;
+    duration?: number | null;
+    coverUrl?: string | null;
+}
+/**
+ * TikTok post video info
+ */
+interface TikTokPostVideo {
+    duration?: number | null;
+    url?: string | null;
+    coverUrl?: string | null;
+    width?: number | null;
+    height?: number | null;
+}
+/**
+ * TikTok post image item
+ */
+interface TikTokPostImage {
+    index?: number;
+    url: string;
+    width?: number | null;
+    height?: number | null;
+}
+/**
+ * TikTok post stats
+ */
+interface TikTokPostStats {
+    plays?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    saves?: number;
+    reposts?: number;
+}
+/**
+ * TikTok hashtag
+ */
+interface TikTokHashtag {
+    id: string;
+    title: string;
+}
+/**
+ * TikTok post item
+ */
+interface TikTokPost {
+    id: string;
+    postUrl?: string | null;
+    description?: string;
+    createdAt?: string | null;
+    mediaType?: 'video' | 'image';
+    author?: TikTokPostAuthor;
+    music?: TikTokPostMusic;
+    video?: TikTokPostVideo;
+    images?: TikTokPostImage[];
+    stats?: TikTokPostStats;
+    hashtags?: TikTokHashtag[];
+    locationCreated?: string | null;
+    isAd?: boolean;
+}
+/**
+ * TikTok posts pagination data
+ */
+interface TikTokPostsPagination {
+    cursor?: string;
+    hasMore?: boolean;
+    total?: number;
+    secUid?: string | null;
+}
+/**
+ * Data returned from the TikTok profile endpoint
+ */
+interface TikTokProfileData {
+    profile: TikTokProfile;
+    timing: {
+        total: number;
+    };
+    creditsUsed: number;
+    creditsRemaining: number;
+}
+/**
+ * Data returned from the TikTok post endpoint
+ */
+interface TikTokPostData {
+    post: TikTokPost;
+    timing: {
+        total: number;
+    };
+    creditsUsed: number;
+    creditsRemaining: number;
+}
+/**
+ * Data returned from the TikTok posts endpoint
+ */
+interface TikTokPostsData {
+    posts: TikTokPost[];
+    pagination: TikTokPostsPagination;
+    timing: {
+        total: number;
+    };
+    creditsUsed: number;
+    creditsRemaining: number;
+}
+/**
+ * Response from the TikTok profile endpoint
+ */
+type TikTokProfileResponse = ApiSuccessResponse<TikTokProfileData>;
+/**
+ * Response from the TikTok post endpoint
+ */
+type TikTokPostResponse = ApiSuccessResponse<TikTokPostData>;
+/**
+ * Response from the TikTok posts endpoint
+ */
+type TikTokPostsResponse = ApiSuccessResponse<TikTokPostsData>;
 
 /**
  * LinkedIn scraping operations
@@ -1098,6 +1344,26 @@ declare class AppStoreResource extends BaseResource {
      * @costs 1 credit
      */
     playstoreDetail(params: PlayStoreDetailParams): Promise<PlayStoreDetailData>;
+    /**
+     * Fetch Apple App Store app details
+     *
+     * @param params - App detail parameters
+     * @returns App information including metadata, ratings, and media
+     * @throws {CrawlKitError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await crawlkit.appstore.appstoreDetail({
+     *   appId: '1492793493',
+     *   options: { lang: 'en' }
+     * });
+     * console.log(result.appName);
+     * console.log(result.rating);
+     * ```
+     *
+     * @costs 1 credit
+     */
+    appstoreDetail(params: AppStoreDetailParams): Promise<AppStoreDetailData>;
     /**
      * Fetch Apple App Store reviews for an app
      *
@@ -1129,6 +1395,77 @@ declare class AppStoreResource extends BaseResource {
     appstoreReviews(params: AppStoreReviewsParams): Promise<AppStoreReviewsData>;
 }
 
+/**
+ * TikTok scraping operations
+ * Provides profile, single content, and paginated content list scraping
+ */
+declare class TikTokResource extends BaseResource {
+    /**
+     * Scrape a TikTok profile
+     *
+     * @param params - Profile parameters (username)
+     * @returns Profile data including stats and metadata
+     * @throws {CrawlKitError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await crawlkit.tiktok.profile({
+     *   username: 'nike'
+     * });
+     * console.log(result.profile.username);
+     * console.log(result.profile.stats?.followers);
+     * ```
+     *
+     * @costs 1 credit
+     */
+    profile(params: TikTokProfileParams): Promise<TikTokProfileData>;
+    /**
+     * Scrape a single TikTok content item
+     *
+     * @param params - Post parameters (post URL)
+     * @returns Post details including author, media, stats, and hashtags
+     * @throws {CrawlKitError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await crawlkit.tiktok.content({
+     *   url: 'https://www.tiktok.com/@nike/video/1234567890'
+     * });
+     * console.log(result.post.id);
+     * console.log(result.post.video?.url);
+     * ```
+     *
+     * @costs 1 credit
+     */
+    content(params: TikTokPostParams): Promise<TikTokPostData>;
+    /**
+     * List TikTok content with cursor-based pagination
+     *
+     * @param params - Post list parameters (username and optional cursor/secUid)
+     * @returns A page of posts and pagination metadata
+     * @throws {CrawlKitError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const firstPage = await crawlkit.tiktok.posts({
+     *   username: 'nike'
+     * });
+     *
+     * if (firstPage.pagination.hasMore) {
+     *   const nextPage = await crawlkit.tiktok.posts({
+     *     username: 'nike',
+     *     cursor: Number(firstPage.pagination.cursor),
+     *     secUid: firstPage.pagination.secUid ?? undefined
+     *   });
+     *   console.log(nextPage.posts.length);
+     * }
+     * ```
+     *
+     * @costs 1 credit per page
+     */
+    posts(params: TikTokPostsParams): Promise<TikTokPostsData>;
+}
+
 /**
  * Configuration options for the CrawlKit client
  */
@@ -1184,6 +1521,10 @@ interface CrawlKitConfig {
  * const company = await crawlkit.linkedin.company({
  *   url: 'https://linkedin.com/company/openai'
  * });
+ *
+ * const profile = await crawlkit.tiktok.profile({
+ *   username: 'nike'
+ * });
  * ```
  */
 declare class CrawlKit {
@@ -1204,6 +1545,11 @@ declare class CrawlKit {
      * Provides Google Play Store and Apple App Store data
      */
     readonly appstore: AppStoreResource;
+    /**
+     * TikTok scraping operations
+     * Provides profile, content, and paginated posts scraping
+     */
+    readonly tiktok: TikTokResource;
     /**
      * Create a new CrawlKit client
      *
@@ -1413,4 +1759,4 @@ declare class NetworkError extends CrawlKitError {
  */
 declare function createErrorFromResponse(code: string, message: string, statusCode: number, creditsRefunded?: number, creditsRemaining?: number): CrawlKitError;
 
-export { type ActionResult, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AppStoreReview, type AppStoreReviewsData, type AppStoreReviewsOptions, type AppStoreReviewsParams, type AppStoreReviewsResponse, AuthenticationError, type BrowserAction, type ClickAction, CrawlKit, type CrawlKitConfig, CrawlKitError, type CrawlStats, type CreditInfo, type DataSafety, type Developer, type DeveloperReply, type ErrorCode, type EvaluateAction, type ExtractData, type ExtractOptions, type ExtractParams, type ExtractResponse, type InstagramAudioInfo, type InstagramBioLink, type InstagramCarouselItem, type InstagramContent, type InstagramContentData, type InstagramContentOptions, type InstagramContentOwner, type InstagramContentParams, type InstagramContentResponse, type InstagramDimensions, type InstagramPost, type InstagramProfile, type InstagramProfileData, type InstagramProfileOptions, type InstagramProfileParams, type InstagramProfileResponse, InsufficientCreditsError, type LinkedInCompany, type LinkedInCompanyData, type LinkedInCompanyOptions, type LinkedInCompanyParams, type LinkedInCompanyResponse, type LinkedInEmployee, type LinkedInJob, type LinkedInPersonData, type LinkedInPersonParams, type LinkedInPersonResponse, type LinkedInPersonResult, type LinkedInPost, type LinkedInSimilarCompany, NetworkError, NotFoundError, type PageLinks, type PageMetadata, type Pagination, type Permission, type PlayStoreDetailData, type PlayStoreDetailOptions, type PlayStoreDetailParams, type PlayStoreDetailResponse, type PlayStoreReview, type PlayStoreReviewsData, type PlayStoreReviewsOptions, type PlayStoreReviewsParams, type PlayStoreReviewsResponse, type PressAction, RateLimitError, type RatingDistribution, type ScrapeData, type ScrapeOptions, type ScrapeParams, type ScrapeResponse, type Screenshot, type ScreenshotData, type ScreenshotOptions, type ScreenshotParams, type ScreenshotResponse, type ScrollAction, type SearchData, type SearchOptions, type SearchParams, type SearchResponse, type SearchResult, type TimeRange, TimeoutError, type Timing, type TypeAction, ValidationError, type WaitAction, createErrorFromResponse };
+export { type ActionResult, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AppStoreDetailData, type AppStoreDetailOptions, type AppStoreDetailParams, type AppStoreDetailResponse, type AppStoreReview, type AppStoreReviewsData, type AppStoreReviewsOptions, type AppStoreReviewsParams, type AppStoreReviewsResponse, AuthenticationError, type BrowserAction, type ClickAction, CrawlKit, type CrawlKitConfig, CrawlKitError, type CrawlStats, type CreditInfo, type DataSafety, type Developer, type DeveloperReply, type ErrorCode, type EvaluateAction, type ExtractData, type ExtractOptions, type ExtractParams, type ExtractResponse, type InstagramAudioInfo, type InstagramBioLink, type InstagramCarouselItem, type InstagramContent, type InstagramContentData, type InstagramContentOptions, type InstagramContentOwner, type InstagramContentParams, type InstagramContentResponse, type InstagramDimensions, type InstagramPost, type InstagramProfile, type InstagramProfileData, type InstagramProfileOptions, type InstagramProfileParams, type InstagramProfileResponse, InsufficientCreditsError, type LinkedInCompany, type LinkedInCompanyData, type LinkedInCompanyOptions, type LinkedInCompanyParams, type LinkedInCompanyResponse, type LinkedInEmployee, type LinkedInJob, type LinkedInPersonData, type LinkedInPersonParams, type LinkedInPersonResponse, type LinkedInPersonResult, type LinkedInPost, type LinkedInSimilarCompany, NetworkError, NotFoundError, type PageLinks, type PageMetadata, type Pagination, type Permission, type PlayStoreDetailData, type PlayStoreDetailOptions, type PlayStoreDetailParams, type PlayStoreDetailResponse, type PlayStoreReview, type PlayStoreReviewsData, type PlayStoreReviewsOptions, type PlayStoreReviewsParams, type PlayStoreReviewsResponse, type PressAction, RateLimitError, type RatingDistribution, type ScrapeData, type ScrapeOptions, type ScrapeParams, type ScrapeResponse, type Screenshot, type ScreenshotData, type ScreenshotOptions, type ScreenshotParams, type ScreenshotResponse, type ScrollAction, type SearchData, type SearchOptions, type SearchParams, type SearchResponse, type SearchResult, type TikTokHashtag, type TikTokOptions, type TikTokPost, type TikTokPostAuthor, type TikTokPostData, type TikTokPostImage, type TikTokPostMusic, type TikTokPostParams, type TikTokPostResponse, type TikTokPostStats, type TikTokPostVideo, type TikTokPostsData, type TikTokPostsPagination, type TikTokPostsParams, type TikTokPostsResponse, type TikTokProfile, type TikTokProfileData, type TikTokProfileParams, type TikTokProfileResponse, type TikTokProfileStats, type TimeRange, TimeoutError, type Timing, type TypeAction, ValidationError, type WaitAction, createErrorFromResponse };