scavio 0.23.0 → 0.24.0

package/README.md

@@ -126,7 +126,7 @@ map.data.truncated;   // true when more URLs exist than `limit`
 // Crawl: start a job, then poll it (polling and cancelling are free).
 const job = await client.extract.crawl(
   { url: "https://example.com/docs", max_pages: 50, max_depth: 3, format: "markdown" },
-  { idempotencyKey: "docs-crawl-2026-10-12" }, // optional, sent as Idempotency-Key
+  { idempotencyKey: "docs-crawl-2026-10-12" }, // optional; one is generated when omitted
 );
 job.data.id;          // "crawl_..."
 job.data.status_url;
@@ -185,16 +185,21 @@ call. Results are kept for 3 days after the job finishes (`expires_at`), up to
 **`wait: true`.** `crawl()` and `batch()` poll the status endpoint every
 `pollInterval` ms (default 2,000) until the job is completed, failed or
 cancelled, then page through every cursor and return
-`{ data: { ...summary, results: [all], next_cursor: null } }`. If the job is
+`{ data: { ...summary, results: [all], next_cursor: null }, created: {...} }`,
+where `created` is the 202 job handle (including `webhook_secret`, which is
+only returned on creation), as in the Python SDK (since 0.23.1). If the job is
 still running after `waitTimeout` ms (default 10 minutes) they throw
 `ScavioJobTimeoutError`; the job keeps running and the error carries
 `jobId`, `jobType` and `statusUrl` so you can keep polling or cancel it. For
 big crawls, prefer a webhook or your own polling loop.
 
-**Retries and idempotency.** The SDK retries 429/5xx and network errors. Pass
-`idempotencyKey` when starting a job: repeating a POST with the same key within
-24 hours returns the original job, so a retried request never starts a second
-one.
+**Retries and idempotency.** The SDK retries 429/5xx and network errors.
+`crawl()` and `batch()` always send an `Idempotency-Key`: yours when you pass
+`idempotencyKey`, otherwise a random UUID generated for that call and reused on
+every retry of it (since 0.23.1). Repeating a POST with the same key within 24
+hours returns the original job, so a retried start never begins a second,
+billed one. Pass your own key to dedupe across calls or processes. Plain
+`extract()` and `map()` are not jobs and send no key.
 
 #### Completion webhooks
 
@@ -780,13 +785,16 @@ await client.tiktokShop.resolve({ url: "https://vt.tiktok.com/ZT2AHoGsE/" });
 
 ### Instagram
 
-Credit cost varies by endpoint, in three tiers:
+20 endpoints. Typical credit cost per call:
 
 | Credits | Methods |
 |---|---|
-| 2 | `userPosts` |
-| 8 | `post`, `commentReplies` |
-| 10 | `profile`, `userReels`, `userTagged`, `userStories`, `postComments`, `searchUsers`, `searchHashtags`, `userFollowers`, `userFollowings` |
+| 1 | `profile`, `musicPosts` (per page), `userReels`, `userTagged` (2 the first time a username is looked up) |
+| 2 | `userPosts`, `userStories`, `post`, `postComments`, `commentReplies`, `searchUsers`, `searchHashtags`, `userFollowers`, `userFollowings`, `userHighlights`, `highlightStories`, `searchReels`, `searchMusic`, `searchLocations`, `userSimilar`, `postLikers` |
+| 8 | `searchUsers` / `searchHashtags` when a `cursor` is sent |
+
+A request can cost up to 10 when it needs extra work; `credits_used` in the
+response is the exact charge.
 
 ```typescript
 // User profile
@@ -797,23 +805,33 @@ await client.instagram.userPosts({ username: "instagram", count: 12 });
 await client.instagram.userReels({ username: "instagram" });
 await client.instagram.userTagged({ username: "instagram" });
 
-// User stories
+// User stories, highlights and the stories saved in one highlight
 await client.instagram.userStories({ username: "instagram" });
+await client.instagram.userHighlights({ username: "natgeo" });
+await client.instagram.highlightStories({ highlight_id: "highlight:18149897764550869" });
 
-// Post detail (by url, media_id, or shortcode)
+// Post detail (by url, media_id, or shortcode) and who liked it
 await client.instagram.post({ shortcode: "DUajw4YkorV" });
+await client.instagram.postLikers({ shortcode: "DUajw4YkorV" });
 
 // Post comments and replies
 await client.instagram.postComments({ shortcode: "DUajw4YkorV", sort_order: "newest" });
 await client.instagram.commentReplies({ media_id: "123", comment_id: "456" });
 
-// Search
+// Search users, hashtags, Reels and places
 await client.instagram.searchUsers({ keyword: "justin" });
 await client.instagram.searchHashtags({ keyword: "fashion" });
+await client.instagram.searchReels({ keyword: "latte art" });
+await client.instagram.searchLocations({ keyword: "central park" });
+
+// Audio: find a track, then the Reels that use it
+await client.instagram.searchMusic({ keyword: "espresso" });
+await client.instagram.musicPosts({ music_id: "1747512212697470" });
 
-// Followers / followings
+// Followers / followings / similar accounts
 await client.instagram.userFollowers({ username: "instagram", count: 50 });
 await client.instagram.userFollowings({ username: "instagram" });
+await client.instagram.userSimilar({ username: "mrbeast" });
 ```
 
 ### Threads

package/dist/index.cjs

@@ -232,7 +232,7 @@ function parseRetryAfter(header) {
 var BASE_URL = "https://api.scavio.dev";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = true ? "0.23.0" : "0.0.0";
+var SDK_VERSION = true ? "0.24.0" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -812,42 +812,86 @@ var InstagramNamespace = class {
     this.client = client;
   }
   client;
+  /** Get a user profile by username or user_id. 1 credit. */
   async profile(options) {
     return this.client._post("/api/v1/instagram/profile", options);
   }
+  /** Get a user's posts, about 12 per page; page with `data.pagination_token`. 2 credits per page. */
   async userPosts(options) {
     return this.client._post("/api/v1/instagram/user/posts", options);
   }
+  /** Get a user's Reels. 1 credit (2 the first time a username is looked up). */
   async userReels(options) {
     return this.client._post("/api/v1/instagram/user/reels", options);
   }
+  /** Get posts a user is tagged in. 1 credit (2 the first time a username is looked up). */
   async userTagged(options) {
     return this.client._post("/api/v1/instagram/user/tagged", options);
   }
+  /** Get a user's active stories. 2 credits. */
   async userStories(options) {
     return this.client._post("/api/v1/instagram/user/stories", options);
   }
+  /** Get a single post by url, media_id or shortcode. 2 credits. */
   async post(options) {
     return this.client._post("/api/v1/instagram/post", options);
   }
+  /** Get comments on a post; page with `next_min_id`. 2 credits per page. */
   async postComments(options) {
     return this.client._post("/api/v1/instagram/post/comments", options);
   }
+  /** Get replies to a comment. 2 credits. */
   async commentReplies(options) {
     return this.client._post("/api/v1/instagram/post/comments/replies", options);
   }
+  /** Search users by keyword. 2 credits; 8 when a `cursor` is sent. */
   async searchUsers(options) {
     return this.client._post("/api/v1/instagram/search/users", options);
   }
+  /** Search hashtags by keyword. 2 credits; 8 when a `cursor` is sent. */
   async searchHashtags(options) {
     return this.client._post("/api/v1/instagram/search/hashtags", options);
   }
+  /** Get a user's followers; page with `next_max_id`. 2 credits per page. */
   async userFollowers(options) {
     return this.client._post("/api/v1/instagram/user/followers", options);
   }
+  /** Get the accounts a user follows; page with `next_max_id`. 2 credits per page. */
   async userFollowings(options) {
     return this.client._post("/api/v1/instagram/user/followings", options);
   }
+  /** List a user's story highlights (id, title, cover, item count). 2 credits. */
+  async userHighlights(options) {
+    return this.client._post("/api/v1/instagram/user/highlights", options);
+  }
+  /** Get every story saved in one highlight, with media URLs. 2 credits. */
+  async highlightStories(options) {
+    return this.client._post("/api/v1/instagram/highlight/stories", options);
+  }
+  /** Search Reels by keyword; page with `pagination_token`. 2 credits per page. */
+  async searchReels(options) {
+    return this.client._post("/api/v1/instagram/search/reels", options);
+  }
+  /** Search audio tracks by song or artist; returns the id `musicPosts` takes. 2 credits. */
+  async searchMusic(options) {
+    return this.client._post("/api/v1/instagram/search/music", options);
+  }
+  /** Get the Reels that use an audio track, plus its total reel count. 1 credit per page. */
+  async musicPosts(options) {
+    return this.client._post("/api/v1/instagram/music/posts", options);
+  }
+  /** Search places by name (id, name, address, coordinates). 2 credits. */
+  async searchLocations(options) {
+    return this.client._post("/api/v1/instagram/search/locations", options);
+  }
+  /** Get accounts similar to a user. Most creator accounts have them; some brand accounts return none. 2 credits. */
+  async userSimilar(options) {
+    return this.client._post("/api/v1/instagram/user/similar", options);
+  }
+  /** Get accounts that liked a post (up to about 1,000) and its total like count. 2 credits. */
+  async postLikers(options) {
+    return this.client._post("/api/v1/instagram/post/likers", options);
+  }
 };
 
 // src/namespaces/walmart.ts
@@ -2999,6 +3043,12 @@ var COLLECT_PAGE_SIZE = 100;
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function randomUUID() {
+  const g = globalThis;
+  if (typeof g.crypto?.randomUUID === "function") return g.crypto.randomUUID();
+  const nodeCrypto = await import("crypto");
+  return nodeCrypto.randomUUID();
+}
 var ExtractNamespace = class {
   constructor(client) {
     this.client = client;
@@ -3038,14 +3088,15 @@ var ExtractNamespace = class {
     return this.cancel("batch", id);
   }
   async start(type, body, request2) {
-    const headers = request2.idempotencyKey ? { "Idempotency-Key": request2.idempotencyKey } : void 0;
+    const headers = { "Idempotency-Key": request2.idempotencyKey ?? await randomUUID() };
     const created = await this.client._post(
       `/api/v1/extract/${type}`,
       body,
       headers
     );
     if (!request2.wait) return created;
-    return this.waitFor(type, created.data.id, created.data.status_url, request2);
+    const done = await this.waitFor(type, created.data.id, created.data.status_url, request2);
+    return { ...done, created: created.data };
   }
   async status(type, id, query = {}) {
     return await this.client._get(`/api/v1/extract/${type}/${encodeURIComponent(id)}`, {