scrape_creators 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c214fa7c8b7b56a2483d3432420003745f73747e8391100312168466f9f03c7b
-  data.tar.gz: 0ec20deecab206e3ba0f54707abbfee7e624485d5f7954311bdb34552b207f40
+  metadata.gz: 36ed3616d4e59159e3241d2a07b743ad39aa63ac4adf93e63c7f51fbd0e8f173
+  data.tar.gz: 946bcdd67f4f3e9d5b53819c5c15ace2a56a148871ed58844479349507d8ac09
 SHA512:
-  metadata.gz: f15f5722980fca1ccb48a32e1d62927324ae944c81132cc3210f2a35d12209033ef244804c988a9f4b3924c28f78c9ddca63bf66e29dd0e24e9477195ad95aed
-  data.tar.gz: 20aadfbd40d3362a8d6fbbe52223fb1bb4baafdaec99406e9a9bbe477e8ab1fd40b29bf7279fdfc813a88c3126237a5bd598bf7ccf2db5c0adb133e7c79d4c66
+  metadata.gz: 27340bf2224cccfc9c5b10041e844e2f202765f34faa5d632f9fd04e7e00b1ea22ccbdcba49ee367af7fad54200618fc108c9ae9b202ac14df93713892c34574
+  data.tar.gz: 8b4fa602579a360b37af6f80847fe923fa3afb6fb165af8862afd2a81d796ebec4bff0068c2ba2c2781b71d26314669b04ddc4d0d29065fc3068b0e424d9d09a

data/README.md

@@ -7,7 +7,7 @@ A zero-dependency Ruby client for the [Scrape Creators API](https://docs.scrapec
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'scrape_creators', '0.2.0'
+gem 'scrape_creators', '0.6.0'
 ```
 
 And then execute:
@@ -40,6 +40,39 @@ scraper = ScrapeCreators::Client.new
 posts = scraper.posts("zuck")
 ```
 
+### Fetch TikTok Profile Videos
+
+```ruby
+posts = scraper.posts("zuck", source: 'tiktok')
+```
+
+### Fetch YouTube Channel Shorts
+
+```ruby
+posts = scraper.posts("zuck", source: 'youtube')
+```
+
+### Cursor-based pagination
+
+All three platforms support cursor-based pagination. By default `posts` returns the first page only. Pass `pages:` to fetch more (e.g. `5` for the first five pages of a creator's feed):
+
+```ruby
+posts = scraper.posts("zuck", pages: 5)                    # Instagram
+posts = scraper.posts("zuck", source: 'tiktok', pages: 5)   # TikTok
+posts = scraper.posts("zuck", source: 'youtube', pages: 5) # YouTube Shorts
+```
+
+If you need finer control, `posts_page` returns `{ items:, cursor:, has_more: }` so you can page through the full timeline yourself:
+
+```ruby
+page = scraper.posts_page("zuck", source: 'tiktok')
+loop do
+  page[:items].each { |item| puts item['desc'] }
+  break unless page[:has_more] && page[:cursor]
+  page = scraper.posts_page("zuck", source: 'tiktok', cursor: page[:cursor])
+end
+```
+
 ### Fetch Instagram Post / Reel Info
 
 ```ruby
@@ -50,16 +83,6 @@ info = scraper.post("https://www.instagram.com/p/DKSMEpKRd6h/", download_media:
 
 ```ruby
 comments = scraper.comments("https://www.instagram.com/p/DKSMEpKRd6h/")
-
-page = scraper.comments_page("https://www.instagram.com/p/DKSMEpKRd6h/")
-page[:comments]
-page[:cursor]
-page[:has_more]
-
-next_page = scraper.comments_page(
-  "https://www.instagram.com/p/DKSMEpKRd6h/",
-  cursor: page[:cursor]
-)
 ```
 
 ## License

data/lib/scrape_creators/client.rb

@@ -57,49 +57,62 @@ module ScrapeCreators
 
     def posts(handle, options = {})
       source = (options[:source] || 'instagram').to_s
-      params = { handle: handle }.merge(options.reject { |k, _| k.to_s == 'source' })
-      posts_url = posts_url_for(source: source)
-      res = get(posts_url, params)
-      key = posts_key_for(source: source)
-      res.is_a?(Hash) ? (res[key] || []) : []
-    end
-
-    def post(url_or_code, options = {})
-      source = (options[:source] || 'instagram').to_s
-      url = normalize_url(url_or_code)
-      post_url = post_url_for(source: source)
-      params = { url: url }.merge(options.reject { |k, _| k.to_s == 'source' })
-      get(post_url, params)
-    end
+      pages = options[:pages] || options[:max_pages] || 1
+      all_items = []
+      cursor = nil
+      has_more = true
+
+      pages.to_i.times do
+        break unless has_more
+
+        page = posts_page(handle, options.merge(cursor: cursor))
+        items = Array(page[:items])
+        all_items.concat(items)
+        cursor = page[:cursor]
+        has_more = page[:has_more] && !cursor.to_s.empty? && !items.empty?
+      end
 
-    def comments(url_or_code, options = {})
-      comments_page(url_or_code, options)[:comments]
+      all_items
     end
 
-    def comments_page(url_or_code, options = {})
+    def posts_page(handle, options = {})
       source = (options[:source] || 'instagram').to_s
-      url = normalize_url(url_or_code)
-      extra = options.reject { |k, _| %w[source cursor continuationToken continuation_token].include?(k.to_s) }
-      params = { url: url }.merge(extra)
-      cursor = options[:cursor] || options['cursor'] || options[:continuationToken] || options['continuationToken'] || options[:continuation_token]
+      params = { handle: handle }
+      cursor = options[:cursor] || options['cursor']
       if cursor && !cursor.to_s.empty?
-        if source == YOUTUBE
-          params[:continuationToken] = cursor
-        else
-          params[:cursor] = cursor
-        end
+        params[posts_cursor_param_for(source:)] = cursor
       end
+      extra = options.reject { |k, _| %w[source cursor max_pages pages].include?(k.to_s) }
+      params.merge!(extra)
 
-      res = get(comments_url_for(source: source), params)
-      comments = res.is_a?(Hash) ? (res['comments'] || []) : []
-      next_cursor = next_comments_cursor(res, source)
+      res = get(posts_url_for(source:), params)
+      key = posts_key_for(source:)
+      items = res.is_a?(Hash) ? (res[key] || []) : []
+      next_cursor = next_posts_cursor(res, source)
       {
-        comments: comments,
+        items: items,
         cursor: next_cursor,
-        has_more: comments_has_more?(res, source, next_cursor)
+        has_more: posts_has_more?(res, source, next_cursor)
       }
     end
 
+    def post(url_or_code, options = {})
+      url = normalize_url(url_or_code)
+      source = options.dig(:source) || 'instagram'
+      post_url = post_url_for(source:)
+      params = { url: url }.merge(options)
+      get(post_url, params)
+    end
+
+    def comments(url_or_code, options = {})
+      url = normalize_url(url_or_code)
+      params = { url: url }.merge(options)
+      source = options.dig(:source) || 'instagram'
+      comments_url = comments_url_for(source:)
+      res = get(comments_url, params)
+      res.is_a?(Hash) ? (res["comments"] || []) : []
+    end
+
     def get(endpoint, params = {}, options = {})
       request(endpoint, method: :get, params: params, options: options)
     end
@@ -140,23 +153,33 @@ module ScrapeCreators
 
     private
 
-    def next_comments_cursor(res, source)
+    def posts_cursor_param_for(source:)
+      case source.to_s
+      when TIKTOK then 'max_cursor'
+      when INSTAGRAM then 'next_max_id'
+      when YOUTUBE then 'continuationToken'
+      else 'cursor'
+      end
+    end
+
+    def next_posts_cursor(res, source)
       return nil unless res.is_a?(Hash)
 
-      cursor = if source == YOUTUBE
-                 res['continuationToken']
-               else
-                 res['cursor']
+      cursor = case source.to_s
+               when TIKTOK then res['max_cursor']
+               when INSTAGRAM then res['next_max_id']
+               when YOUTUBE then res['continuationToken'] || res['continuation_token']
+               else res['cursor']
                end
-      return nil if cursor.nil? || cursor.to_s.empty?
+      return nil if cursor.nil? || cursor.to_s.empty? || cursor.to_s == '0'
 
       cursor
     end
 
-    def comments_has_more?(res, source, next_cursor)
+    def posts_has_more?(res, source, next_cursor)
       return false unless res.is_a?(Hash)
 
-      if source == TIKTOK
+      if source.to_s == TIKTOK
         res['has_more'].to_i == 1
       else
         !next_cursor.nil?

data/lib/scrape_creators/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ScrapeCreators
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scrape_creators
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - swlkr