apick-api 4.1.0 → 4.2.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# 4.2.1
+
+- `youtubeSubtitle()` fails with guidance to use an original-language track when an auto-translated caption (`translated: true`) is refused; such calls are not charged. Examples now pick a manual or original-language track. YouTube requests interrupted by a server restart are retried automatically.
+- 자동 번역 자막(`translated: true`)을 받지 못하면 원어 자막을 쓰라는 안내와 함께 실패로 응답합니다(과금 없음). 예제는 수동·원어 자막을 고르도록 바꿨습니다. 서버 재시작으로 끊긴 유튜브 요청은 서버가 자동으로 다시 시도합니다.
+
+# 4.2.0
+
+- Add `amazonProduct`, `xProfile` and `xPost`, and collection jobs `createInstagramPostsJob`, `createInstagramCommentsJob`, `createTiktokSearchJob`, `createTiktokVideoJob`, `createTiktokCommentsJob`, `createAmazonReviewsJob` with `getScrapeJob` and `waitForScrapeJob`, all with typed results.
+- Collection jobs reserve `maxResults` × unit price and charge only the results actually returned; failures are fully refunded and results are kept for 72 hours.
+- 아마존 상품, X 프로필·게시물 조회와 인스타그램 게시물 목록·댓글, 틱톡 키워드 검색·영상·댓글, 아마존 리뷰 수집 작업 메서드, 작업 조회·대기 메서드와 결과 타입을 추가했습니다.
+- 수집 작업은 `maxResults` × 단가를 예약하고 실제 결과 건수만 차감합니다. 실패는 전액 환불, 결과는 72시간 보관합니다.
+
 # 4.1.0
 
 - Add YouTube methods: `youtubeSearch`, `youtubeChannel`, `youtubePlaylist`, `youtubeHashtag`, `youtubeFormats`, `youtubeComments`, `downloadYoutubeVideo` and `downloadYoutubeAudio`. Downloads return a download link valid for 1 hour and are billed as a base fee plus 2 points per 10MB.

package/README.md

@@ -78,7 +78,7 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `youtubeMetadata(url)` | 유튜브 영상 정보 / YouTube video metadata | JSON |
 | `youtubeThumbnail(url)` | 유튜브 썸네일 / YouTube thumbnail | JPG |
 | `youtubeSubtitleList(url)` | 유튜브 자막 언어 목록 / YouTube subtitle languages | JSON |
-| `youtubeSubtitle(url, lang, options)` | 유튜브 자막 다운로드 / YouTube subtitles | VTT·SRT·TXT |
+| `youtubeSubtitle(url, lang, options)` | 유튜브 자막 다운로드(원어 자막 권장) / YouTube subtitles (prefer original-language tracks) | VTT·SRT·TXT |
 | `youtubeSearch(query, options)` | 유튜브 검색(정렬·필터) / YouTube search with sort and filters | JSON |
 | `youtubeChannel(channel, options)` | 유튜브 채널 정보·탭 목록 / YouTube channel and tab items | JSON |
 | `youtubePlaylist(url, options)` | 유튜브 재생목록 / YouTube playlist | JSON |
@@ -90,6 +90,16 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `instagramProfile(usernameOrUrl)` | 인스타그램 공개 프로필 / Instagram public profile | JSON |
 | `instagramPost(url)` | 인스타그램 게시물·릴스 / Instagram post or reel | JSON |
 | `tiktokProfile(usernameOrUrl)` | 틱톡 공개 프로필 / TikTok public profile | JSON |
+| `amazonProduct(urlOrAsin)` | 아마존 상품 정보 / Amazon product | JSON |
+| `xProfile(usernameOrUrl)` | X 공개 프로필·최근 게시물 / X public profile and recent posts | JSON |
+| `xPost(url)` | X 게시물 / X post | JSON |
+| `createInstagramPostsJob(usernameOrUrl, options)` | 인스타그램 게시물 목록 수집 접수(최대 100) / Instagram posts job | JSON |
+| `createInstagramCommentsJob(url, options)` | 인스타그램 댓글 수집 접수(최대 15) / Instagram comments job | JSON |
+| `createTiktokSearchJob(keyword, options)` | 틱톡 키워드 영상 검색 접수(최대 50) / TikTok keyword search job | JSON |
+| `createTiktokVideoJob(url, options)` | 틱톡 영상 정보 접수 / TikTok video job | JSON |
+| `createTiktokCommentsJob(url, options)` | 틱톡 댓글 수집 접수(최대 100) / TikTok comments job | JSON |
+| `createAmazonReviewsJob(urlOrAsin, options)` | 아마존 리뷰 수집 접수(최대 100) / Amazon reviews job | JSON |
+| `getScrapeJob(jobId)` / `waitForScrapeJob(jobId, options)` | 수집 작업 상태·결과(무료, 결과 건수로 정산) / Collection job status and results | JSON |
 | `createTtsJob(text, options)` | 한국어 내레이션 작업 접수 / Create TTS job | JSON |
 | `getTtsJob(jobId)` | TTS 작업 상태 / TTS job status | JSON |
 | `cancelTtsJob(jobId)` | 대기·생성 중 TTS 작업 취소 / Cancel waiting or processing TTS job | JSON |

package/docs/guide.en.md

@@ -82,6 +82,18 @@ Only public information from public accounts is returned. Lookups usually take 2
 const instagram = await client.instagramProfile('natgeo');
 const post = await client.instagramPost('https://www.instagram.com/p/DeHufcWDCjf/');
 const tiktok = await client.tiktokProfile('https://www.tiktok.com/@tiktok');
+const product = await client.amazonProduct('B0BDHWDR12');
+const x = await client.xProfile('NASA');
+```
+
+### Collection jobs (lists, comments, search, reviews)
+
+Products that collect many items return a `job_id` immediately. Submitting reserves `maxResults` × unit price; when you read the result, only the results actually returned are charged and the rest is refunded. Failed jobs and missing targets are fully refunded, and results are kept for 72 hours. Comment and review authors are public usernames only.
+
+```js
+const job = await client.createTiktokSearchJob('camping recipes', { maxResults: 10, idempotencyKey: 'camping-0001' });
+const done = await client.waitForScrapeJob(job.data.job_id); // every 10 s, up to 10 min
+console.log(done.data.status, done.data.charged_point, done.data.items);
 ```
 
 ## OCR
@@ -116,7 +128,9 @@ await screenshot.save('./example.jpeg');
 // Public YouTube videos: a video URL or the 11-character video ID
 const video = await client.youtubeMetadata('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
 const tracks = await client.youtubeSubtitleList(video.data.video_id);
-const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { format: 'srt' });
+// Auto-translated captions (translated=true) may be refused by YouTube, so pick a manual or original-language track.
+const track = tracks.data.subtitles[0] || tracks.data.automatic_captions.find(item => !item.translated);
+const subtitle = await client.youtubeSubtitle(video.data.video_id, track.lang, { format: 'srt' });
 await subtitle.save('./' + subtitle.filename);
 await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
 

package/docs/guide.ko.md

@@ -82,6 +82,18 @@ const rank = await client.googleRankCheck('주소 검색 API', 'apick.app'); //
 const instagram = await client.instagramProfile('natgeo');
 const post = await client.instagramPost('https://www.instagram.com/p/DeHufcWDCjf/');
 const tiktok = await client.tiktokProfile('https://www.tiktok.com/@tiktok');
+const product = await client.amazonProduct('B0BDHWDR12');
+const x = await client.xProfile('NASA');
+```
+
+### 수집 작업(목록·댓글·검색·리뷰)
+
+여러 건을 모으는 상품은 접수 즉시 `job_id` 를 돌려줍니다. 접수 때 `maxResults` × 단가를 예약하고, 결과를 받을 때 실제 결과 건수만 차감한 뒤 나머지는 돌려드립니다. 실패하거나 대상이 없으면 전액 환불되며 결과는 72시간 보관합니다. 댓글·리뷰 작성자는 공개 사용자명만 제공합니다.
+
+```js
+const job = await client.createTiktokSearchJob('캠핑 요리', { maxResults: 10, idempotencyKey: 'camping-0001' });
+const done = await client.waitForScrapeJob(job.data.job_id); // 기본 10초 간격, 최대 10분
+console.log(done.data.status, done.data.charged_point, done.data.items);
 ```
 
 ## OCR
@@ -116,7 +128,9 @@ await screenshot.save('./example.jpeg');
 // 유튜브 공개 영상: 영상 주소 또는 11자리 영상 ID
 const video = await client.youtubeMetadata('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
 const tracks = await client.youtubeSubtitleList(video.data.video_id);
-const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { format: 'srt' });
+// 자동 번역 자막(translated=true)은 유튜브 제한으로 받지 못할 수 있어 수동 자막이나 원어 자동 자막을 고른다.
+const track = tracks.data.subtitles[0] || tracks.data.automatic_captions.find(item => !item.translated);
+const subtitle = await client.youtubeSubtitle(video.data.video_id, track.lang, { format: 'srt' });
 await subtitle.save('./' + subtitle.filename);
 await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",

package/src/index.cjs

@@ -44,6 +44,10 @@ const SERVICE_DEFINITIONS = Object.freeze({
 	instagramProfile: { endpoint: '/rest/instagram_profile', timeoutMs: 110_000, output: 'json' },
 	instagramPost: { endpoint: '/rest/instagram_post', timeoutMs: 110_000, output: 'json' },
 	tiktokProfile: { endpoint: '/rest/tiktok_profile', timeoutMs: 110_000, output: 'json' },
+	amazonProduct: { endpoint: '/rest/amazon_product', timeoutMs: 110_000, output: 'json' },
+	xProfile: { endpoint: '/rest/x_profile', timeoutMs: 110_000, output: 'json' },
+	xPost: { endpoint: '/rest/x_post', timeoutMs: 110_000, output: 'json' },
+	getScrapeJob: { endpoint: '/rest/scrape_jobs', timeoutMs: 35_000, output: 'json' },
 	screenshot: { endpoint: '/rest/url_screenshot', timeoutMs: 75_000, output: 'binary', filename: 'screenshot.jpeg' },
 	youtubeMetadata: { endpoint: '/rest/youtube_metadata', timeoutMs: 60_000, output: 'json' },
 	youtubeThumbnail: { endpoint: '/rest/youtube_thumbnail', timeoutMs: 60_000, output: 'binary', filename: 'thumbnail.jpg' },
@@ -93,6 +97,29 @@ function profileInput(value) {
 	return /^https?:\/\//i.test(text) ? { url: text } : { username: text.replace(/^@/, '') };
 }
 
+// 아마존 상품 입력: 주소면 url, 10자리 ASIN 이면 asin 으로 보낸다.
+function amazonInput(value) {
+	const text = requiredString('urlOrAsin', value, 2048);
+	return /^https?:\/\//i.test(text) ? { url: text } : { asin: text.toUpperCase() };
+}
+
+const SCRAPE_JOB_PRODUCTS = Object.freeze({ instagram_posts: 100, instagram_comments: 15, tiktok_search: 50, tiktok_video: 1, tiktok_comments: 100, amazon_reviews: 100 });
+
+// 수집 작업 공통 옵션: maxResults(상품별 상한), idempotencyKey(응답을 못 받아 다시 보낼 때 같은 접수로 처리).
+function scrapeJobOptions(product, payload, options) {
+	const config = options || {};
+	if (config.maxResults !== undefined && SCRAPE_JOB_PRODUCTS[product] > 1) {
+		const max = Number(config.maxResults);
+		if (!Number.isInteger(max) || max < 1 || max > SCRAPE_JOB_PRODUCTS[product]) throw new RangeError(`maxResults must be an integer from 1 to ${SCRAPE_JOB_PRODUCTS[product]}.`);
+		payload.max_results = max;
+	}
+	if (config.idempotencyKey !== undefined) {
+		if (typeof config.idempotencyKey !== 'string' || !/^[A-Za-z0-9_.:-]{8,128}$/.test(config.idempotencyKey)) throw new TypeError('idempotencyKey must be 8-128 characters of letters, digits, and . _ : -');
+		payload.idempotency_key = config.idempotencyKey;
+	}
+	return payload;
+}
+
 function requiredString(name, value, maxLength) {
 	if (typeof value !== 'string' || !value.trim()) {
 		throw new TypeError(`${name} must be a non-empty string.`);
@@ -639,6 +666,68 @@ class ApickClient {
 		return this._call('tiktokProfile', profileInput(usernameOrUrl));
 	}
 
+	// 상품 주소(/dp/ASIN) 또는 10자리 ASIN(미국 아마존).
+	amazonProduct(urlOrAsin) {
+		return this._call('amazonProduct', amazonInput(urlOrAsin));
+	}
+
+	xProfile(usernameOrUrl) {
+		return this._call('xProfile', profileInput(usernameOrUrl));
+	}
+
+	xPost(url) {
+		return this._call('xPost', { url: requiredString('url', url, 2048) });
+	}
+
+	// 수집 작업: 접수 즉시 job_id 를 돌려준다. maxResults × 단가를 예약하고 결과를 받을 때 실제 건수만 차감한다.
+	_createScrapeJob(product, payload, options) {
+		return this._call('getScrapeJob', scrapeJobOptions(product, payload, options), null, { endpoint: '/rest/' + product + '/jobs', json: true });
+	}
+
+	createInstagramPostsJob(usernameOrUrl, options) {
+		return this._createScrapeJob('instagram_posts', profileInput(usernameOrUrl), options);
+	}
+
+	createInstagramCommentsJob(url, options) {
+		return this._createScrapeJob('instagram_comments', { url: requiredString('url', url, 2048) }, options);
+	}
+
+	createTiktokSearchJob(keyword, options) {
+		return this._createScrapeJob('tiktok_search', { keyword: requiredString('keyword', keyword, 100) }, options);
+	}
+
+	createTiktokVideoJob(url, options) {
+		return this._createScrapeJob('tiktok_video', { url: requiredString('url', url, 2048) }, options);
+	}
+
+	createTiktokCommentsJob(url, options) {
+		return this._createScrapeJob('tiktok_comments', { url: requiredString('url', url, 2048) }, options);
+	}
+
+	createAmazonReviewsJob(urlOrAsin, options) {
+		return this._createScrapeJob('amazon_reviews', amazonInput(urlOrAsin), options);
+	}
+
+	// 상태·결과 조회(무료). 끝난 작업은 실제 결과 건수로 정산돼 있다.
+	getScrapeJob(jobId) {
+		if (typeof jobId !== 'string' || !/^[a-f0-9]{32}$/.test(jobId)) throw new TypeError('jobId must be a 32-character job ID.');
+		return this._call('getScrapeJob', null, null, { endpoint: '/rest/scrape_jobs/' + jobId, method: 'GET', timeoutMs: 70_000 });
+	}
+
+	// completed 또는 failed 가 될 때까지 조회한다. 기본 10초 간격, 최대 10분.
+	async waitForScrapeJob(jobId, options) {
+		const config = options || {};
+		const intervalMs = Math.max(3_000, positiveInteger('intervalMs', config.intervalMs, 10_000));
+		const deadline = Date.now() + positiveInteger('timeoutMs', config.timeoutMs, 600_000);
+		for (;;) {
+			const result = await this.getScrapeJob(jobId);
+			const status = result && result.data && result.data.status;
+			if (status === 'completed' || status === 'failed') return result;
+			if (Date.now() + intervalMs > deadline) throw new ApickApiError('Scrape job did not finish in time.', { code: 'APICK_TIMEOUT' });
+			await new Promise((resolve) => setTimeout(resolve, intervalMs));
+		}
+	}
+
 	screenshot(url) {
 		return this._call('screenshot', { url: normalizeUrl(url) });
 	}

package/src/index.d.ts

@@ -79,6 +79,148 @@ export interface RankCheck {
 	readonly unchecked_ranks: readonly string[];
 }
 
+export interface AmazonProduct {
+	readonly asin: string;
+	readonly url: string;
+	readonly title: string;
+	readonly brand: string;
+	readonly price: number | null;
+	readonly original_price: number | null;
+	readonly currency: string;
+	readonly rating: number | null;
+	readonly reviews_count: number | null;
+	readonly availability: string;
+	readonly is_available: boolean;
+	readonly bought_past_month: number | null;
+	readonly seller_name: string;
+	readonly categories: readonly string[];
+	readonly features: readonly string[];
+	readonly customers_say: string;
+	readonly image_url: string;
+	readonly image_urls: readonly string[];
+	readonly date_first_available: string;
+	readonly model_number: string;
+}
+
+export interface XPostSummary {
+	readonly post_id: string;
+	readonly url: string;
+	readonly text: string;
+	readonly posted_at: string;
+	readonly likes: number | null;
+	readonly reposts: number | null;
+	readonly replies: number | null;
+	readonly views: number | null;
+	readonly hashtags: readonly string[];
+}
+
+export interface XProfile {
+	readonly username: string;
+	readonly name: string;
+	readonly biography: string;
+	readonly followers: number | null;
+	readonly following: number | null;
+	readonly posts_count: number | null;
+	readonly is_verified: boolean;
+	readonly is_business_account: boolean;
+	readonly is_government_account: boolean;
+	readonly location: string;
+	readonly website: string;
+	readonly joined_at: string;
+	readonly profile_image_url: string;
+	readonly banner_image_url: string;
+	readonly profile_url: string;
+	readonly recent_posts: readonly XPostSummary[];
+}
+
+export interface XPost {
+	readonly post_id: string;
+	readonly url: string;
+	readonly username: string;
+	readonly name: string;
+	readonly text: string;
+	readonly posted_at: string;
+	readonly likes: number | null;
+	readonly reposts: number | null;
+	readonly replies: number | null;
+	readonly quotes: number | null;
+	readonly views: number | null;
+	readonly bookmarks: number | null;
+	readonly hashtags: readonly string[];
+	readonly is_repost: boolean;
+	readonly photo_urls: readonly string[];
+	readonly video_urls: readonly string[];
+	readonly author: { readonly followers: number | null; readonly is_verified: boolean };
+}
+
+export interface TiktokVideo {
+	readonly video_id: string;
+	readonly url: string;
+	readonly username: string;
+	readonly description: string;
+	readonly posted_at: string;
+	readonly views: number | null;
+	readonly likes: number | null;
+	readonly comments: number | null;
+	readonly shares: number | null;
+	readonly saves: number | null;
+	readonly duration_sec: number | null;
+	readonly hashtags: readonly string[];
+	readonly region: string;
+	readonly cover_image_url: string;
+	readonly author: { readonly followers: number | null; readonly is_verified: boolean };
+}
+
+/** 댓글 작성자는 공개 사용자명만 제공한다. */
+export interface SocialComment {
+	readonly comment_id: string;
+	readonly username: string;
+	readonly text: string;
+	readonly posted_at: string;
+	readonly likes: number | null;
+	readonly replies: number | null;
+}
+
+export interface AmazonReview {
+	readonly review_id: string;
+	readonly rating: number | null;
+	readonly title: string;
+	readonly text: string;
+	readonly author: string;
+	readonly posted_at: string;
+	readonly country: string;
+	readonly is_verified_purchase: boolean;
+	readonly helpful_count: number | null;
+	readonly variant: string;
+}
+
+export type ScrapeJobProduct = "instagram_posts" | "instagram_comments" | "tiktok_search" | "tiktok_video" | "tiktok_comments" | "amazon_reviews";
+
+export interface ScrapeJobOptions {
+	/** 최대 결과 수. 이 수 × 단가를 예약하고 실제 결과 건수만 차감한다(instagram_comments 15, tiktok_search 50, 그 밖 100). */
+	readonly maxResults?: number;
+	/** 응답을 못 받아 다시 보낼 때 같은 접수로 처리할 키(8~128자). */
+	readonly idempotencyKey?: string;
+}
+
+export interface ScrapeJob<T = unknown> {
+	readonly job_id: string;
+	readonly product: ScrapeJobProduct;
+	readonly status: "waiting" | "processing" | "completed" | "failed";
+	readonly max_results: number;
+	readonly unit_point: number;
+	readonly reserved_point: number;
+	readonly charged_point: number;
+	readonly result_count: number;
+	readonly created_at: string;
+	readonly completed_at: string | null;
+	/** 결과 보관 기한(완료 후 72시간). */
+	readonly result_expires_at?: string;
+	readonly result_expired?: boolean;
+	readonly items?: readonly T[];
+	readonly error?: { readonly code: string; readonly message: string };
+}
+
 export interface InstagramProfile {
 	readonly username: string;
 	readonly full_name: string;
@@ -313,6 +455,7 @@ export interface YoutubeMetadata {
 	age_limit: number | null; chapters: YoutubeChapter[]; thumbnail: string | null; thumbnails: YoutubeThumbnail[];
 	subtitle_languages: string[]; automatic_caption_count: number;
 }
+/** translated=true 인 자동 번역 자막은 유튜브 제한으로 받지 못할 수 있다. 수동 자막이나 원어 자동 자막을 권장한다. */
 export interface YoutubeSubtitleTrack { lang: string; name: string | null; auto: boolean; formats: string[]; translated?: boolean; }
 export interface YoutubeSubtitleList {
 	video_id: string; title: string | null; original_language: string | null;
@@ -472,6 +615,17 @@ export class ApickClient {
 	instagramProfile(usernameOrUrl: string): Promise<ApickResult<InstagramProfile>>;
 	instagramPost(url: string): Promise<ApickResult<InstagramPost>>;
 	tiktokProfile(usernameOrUrl: string): Promise<ApickResult<TiktokProfile>>;
+	amazonProduct(urlOrAsin: string): Promise<ApickResult<AmazonProduct>>;
+	xProfile(usernameOrUrl: string): Promise<ApickResult<XProfile>>;
+	xPost(url: string): Promise<ApickResult<XPost>>;
+	createInstagramPostsJob(usernameOrUrl: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<InstagramPost>>>;
+	createInstagramCommentsJob(url: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<SocialComment>>>;
+	createTiktokSearchJob(keyword: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<TiktokVideo>>>;
+	createTiktokVideoJob(url: string, options?: Pick<ScrapeJobOptions, "idempotencyKey">): Promise<ApickResult<ScrapeJob<TiktokVideo>>>;
+	createTiktokCommentsJob(url: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<SocialComment>>>;
+	createAmazonReviewsJob(urlOrAsin: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<AmazonReview>>>;
+	getScrapeJob<T = unknown>(jobId: string): Promise<ApickResult<ScrapeJob<T>>>;
+	waitForScrapeJob<T = unknown>(jobId: string, options?: { intervalMs?: number; timeoutMs?: number }): Promise<ApickResult<ScrapeJob<T>>>;
 	screenshot(url: string): Promise<ApickBinaryResult>;
 	youtubeMetadata(url: string): Promise<ApickResult<YoutubeMetadata>>;
 	youtubeThumbnail(url: string): Promise<ApickBinaryResult>;