threads-api 0.0.1.pre → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ddb297052b28cab7f6a56c010ede66c4a1ef818a8d0862da7fb365856f482b0
-  data.tar.gz: ed7000a484974ebb0dc2d66b87db2c59538f50f20616a54f64882f32c52523d5
+  metadata.gz: 422f4c1e70e0a2d5402d70646e6afd8fc095ff070b65e59f0acbf0afe4e66127
+  data.tar.gz: 421de26fc580b70c9bb76b4ef08adf040c97f94e92a7666acde6c42cbf9b1098
 SHA512:
-  metadata.gz: d4f1504a2956ab19bd2133fc780cb6f679c0a2ec7ddc3c58ba75e2af99f3f0cf5899067f2909b58f1483cb4d55a8d094b089e5a1347140b6275518efdf0e575c
-  data.tar.gz: 5e45860b0c861e477d5812fede1bdc4d1a0619cc30a0563442c6bd83001f73c7b29425f43665e8777f7439ffbb600fea6574a3893c54631a22050cdccd3cd81f
+  metadata.gz: 56d8bc23aa227e36406e1446159b13ea22317ea763dadb22aa25e07b17d7ae40eed568b16c614544035d33be72bb747af512a9ede63ad7fe4a03955fe7aab894
+  data.tar.gz: 6d1350e527061f18955d7cf4744a97e27ca5fcf65b3fc9515bdce8d7a18fe65e59f400a950e1023f251b295c8d2e68d986b6193e257a235e89d960c01c8316c9

data/README.md

@@ -49,7 +49,126 @@ access_token = response.access_token
 expires_at = Time.now + response.expires_in
 ```
 
-Once you have a valid access token, whether it's short-lived or long-lived, you can use it to make requests to the Threads API.
+Once you have a valid access token, whether it's short-lived or long-lived, you can use it to make requests to the Threads API using a `Threads::API::Client`:
+
+```ruby
+client = Threads::API::Client.new(access_token)
+```
+
+## Reading Threads
+
+To read threads for a user:
+
+```ruby
+# List recent threads for a user.
+response = client.list_threads # Defaults to the authenticated user
+response = client.list_threads(user_id: "7770386109746442")
+
+# By default, the Threads API returns 25 threads at a time. You can paginate through them like so:
+next_page = client.list_threads(after: response.after_cursor) # or
+previous_page = client.list_threads(before: response.before_cursor)
+
+# Get a specific thread by ID.
+thread = client.get_thread("18050206876707110") # Defaults to the authenticated user
+thread = client.get_thread("18050206876707110", user_id: "7770386109746442")
+```
+
+`Threads::API::Client#list_threads` accepts the following options:
+
+* `user_id` - The ID of the user whose threads you want to read. Defaults to `"me"`, the authenticated user.
+* `fields` - An Array (or comma-separated String) of fields to include in the response. By default, all documented fields are requested. See the [Threads API documentation](https://developers.facebook.com/docs/threads/threads-media#fields) for a list of available fields.
+* `since` - An ISO 8601 date string. Only threads published after this date will be returned.
+* `until` - An ISO 8601 date string. Only threads published before this date will be returned.
+* `before` - A cursor string returned by a previous request for pagination.
+* `after` - A cursor string returned by a previous request for pagination.
+* `limit` - The number of threads to return. Defaults to `25`, with a maximum of `100`.
+
+`Threads::API::Client#get_thread` accepts only the `user_id` and `fields` options.
+
+## Reading profiles
+
+To get a user's profile:
+
+```ruby
+profile = client.get_profile("7770386109746442")
+```
+
+`Threads::API::Client#get_profile` accepts a `fields` option, which is an Array (or comma-separated String) of fields to include in the response. By default, all documented fields are requested. See the [Threads API documentation](https://developers.facebook.com/docs/threads/threads-profiles#fields) for a list of available fields.
+
+## Posting to Threads
+
+Posting to Threads is, at the very least, a two-step process. Threads requires that you first create a container for the media you want to post, then explicitly publishing that container as a thread. However, more steps are involved if you want to post multiple media items in a single thread.
+
+### Creating the Thread
+
+The first step in posting to Threads is to create a "media container", even if your post is text-only.
+
+```ruby
+# Create a text-only post
+client.create_thread(text: "Hello, world!")
+
+# Create a post with a photo or video
+client.create_thread(type: "IMAGE", image_url: "https://example.com/image.jpg", text: "Some optional text")
+client.create_thread(type: "VIDEO", video_url: "https://example.com/video.mp4", text: "Some optional text")
+
+# Reply to one of your own threads
+client.create_thread(text: "Hello, world!", reply_to_id: "18050206876707110")
+
+# Control who can reply to your thread. Defaults to "everyone".
+client.create_thread(text: "Hello, world!", reply_control: "accounts_you_follow") # or "mentioned_only"
+```
+
+### Publishing the Thread
+
+Once you've created a media container, you can publish it as a thread:
+
+```ruby
+pending_thread = client.create_thread(text: "Hello, world!")
+client.publish_thread(pending_thread.id)
+```
+
+According to Meta, you may need to wait before attempting to publish a thread, especially if the thread contains images or videos. They suggest checking the status of the pending thread before attempting to publish it:
+
+```ruby
+pending_thread = client.create_thread(text: "Hello, world!")
+pending_thread = client.get_thread_status(pending_thread.id)
+
+while pending_thread.in_progress?
+  # Wait a bit (they recommend checking only once per minute) and try again
+  sleep 60
+  pending_thread = client.get_thread_status(pending_thread.id)
+end
+
+if pending_thread.finished?
+  client.publish_thread(pending_thread.id)
+elsif pending_thread.errored?
+  # Handle the error
+else
+  # Unpublished threads expire after 24 hours.
+  pending_thread.expired?
+
+  # If you've already published the thread, the status will be "PUBLISHED".
+  pending_thread.published?
+end
+```
+
+### Posting multiple photos and/or videos
+
+Threads allows you to post a combination of up to 10 photos and/or videos in a single thread. To do so, you must first create a media container for each photo or video you want to post, then create a media container for the thread itself, and finally publish the thread.
+
+```ruby
+# Create carousel items for each photo or video you want to post
+image1 = client.create_carousel_item(type: "IMAGE", image_url: "https://example.com/image1.jpg")
+image2 = client.create_carousel_item(type: "IMAGE", image_url: "https://example.com/image2.jpg")
+video1 = client.create_carousel_item(type: "VIDEO", video_url: "https://example.com/video1.mp4")
+video2 = client.create_carousel_item(type: "VIDEO", video_url: "https://example.com/video2.mp4")
+
+# Create the media container for the thread itself
+pending_thread = client.create_carousel_thread(text: "Some optional text", children: [image1.id, image2.id, video1.id, video2.id])
+
+# Publish the thread
+client.publish_thread(pending_thread.id)
+```
 
 ## Contributing
 

data/lib/threads/api/client.rb

@@ -0,0 +1,142 @@
+require_relative "profile"
+require_relative "thread"
+
+module Threads
+  module API
+    class Client
+      PROFILE_FIELDS = %w[id username threads_profile_picture_url threads_biography]
+      POST_FIELDS = %w[
+        id
+        media_product_type
+        media_type
+        media_url
+        permalink
+        owner
+        username
+        text
+        timestamp
+        shortcode
+        thumbnail_url
+        children
+        is_quote_post
+      ]
+
+      def initialize(access_token)
+        @access_token = access_token
+      end
+
+      def get_profile(user_id = "me", fields: PROFILE_FIELDS)
+        params = {access_token: @access_token}
+        params[:fields] = Array(fields).join(",") if fields
+
+        response = connection.get(user_id, params)
+
+        Threads::API::Profile.new(response.body)
+      end
+
+      def list_threads(user_id: "me", **options)
+        params = options.slice(:since, :until, :before, :after, :limit).compact
+        params[:access_token] = @access_token
+
+        fields = if options.key?(:fields)
+          Array(options[:fields]).join(",")
+        else
+          POST_FIELDS.join(",")
+        end
+
+        params[:fields] = fields unless fields.empty?
+
+        response = connection.get("#{user_id}/threads", params)
+
+        Threads::API::Thread::List.new(response.body)
+      end
+
+      def get_thread(thread_id, fields: POST_FIELDS)
+        params = {access_token: @access_token}
+        params[:fields] = Array(fields).join(",") if fields
+
+        response = connection.get(thread_id, params)
+
+        Threads::API::Thread.new(response.body)
+      end
+
+      def create_thread(type: "TEXT", text: nil, image_url: nil, video_url: nil, reply_to_id: nil, reply_control: nil)
+        params = {access_token: @access_token, media_type: type, text: text}
+        params[:reply_to_id] = reply_to_id if reply_to_id
+        params[:reply_control] = reply_control if reply_control
+
+        case type
+        when "IMAGE"
+          params[:image_url] = image_url || raise(ArgumentError, "The `:image_url` option is required when the post's type is \"IMAGE\"")
+        when "VIDEO"
+          params[:video_url] = video_url || raise(ArgumentError, "The `:video_url` option is required when the post's type is \"VIDEO\"")
+        when "TEXT"
+          raise ArgumentError, "The `:text` option is required when the post's type is \"TEXT\"" if text.nil? || text.empty?
+        else
+          raise ArgumentError, "Invalid post type: #{type}. Must be one of: \"TEXT\", \"IMAGE\", or \"VIDEO\""
+        end
+
+        response = connection.post("me/threads", params)
+
+        Threads::API::UnpublishedThread.new(response.body)
+      end
+
+      def get_thread_status(thread_id)
+        response = connection.get(thread_id, {
+          access_token: @access_token,
+          fields: "id,status,error_message"
+        })
+
+        Threads::API::ThreadStatus.new(response.body)
+      end
+
+      def create_carousel_item(type:, image_url: nil, video_url: nil)
+        params = {access_token: @access_token, media_type: type, is_carousel_item: true}
+
+        case type
+        when "IMAGE"
+          params[:image_url] = image_url || raise(ArgumentError, "The `:image_url` option is required when the item's type is \"IMAGE\"")
+        when "VIDEO"
+          params[:video_url] = video_url || raise(ArgumentError, "The `:video_url` option is required when the item's type is \"VIDEO\"")
+        else
+          raise ArgumentError, "Invalid item type: #{type}. Must be \"IMAGE\" or \"VIDEO\""
+        end
+
+        response = connection.post("me/threads", params)
+
+        Threads::API::UnpublishedThread.new(response.body)
+      end
+
+      def create_carousel_thread(children:, text: nil, reply_to_id: nil, reply_control: nil)
+        params = {access_token: @access_token, media_type: "CAROUSEL", text: text}
+        params[:children] = Array(children).join(",")
+        params[:reply_to_id] = reply_to_id if reply_to_id
+        params[:reply_control] = reply_control if reply_control
+
+        raise ArgumentError, "At least one item must be present in the `:children` option" if params[:children].empty?
+
+        response = connection.post("me/threads", params)
+
+        Threads::API::UnpublishedThread.new(response.body)
+      end
+
+      def publish_thread(id)
+        response = connection.post("me/threads_publish", {access_token: @access_token, creation_id: id})
+
+        Threads::API::ThreadStatus.new(response.body)
+      end
+      alias_method :publish_carousel, :publish_thread
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: "https://graph.threads.net/v1.0/") do |f|
+          f.request :url_encoded
+
+          f.response :json
+          f.response :raise_error
+        end
+      end
+    end
+  end
+end

data/lib/threads/api/oauth2/client.rb

@@ -2,7 +2,7 @@ module Threads
   module API
     module OAuth2
       class Client
-        ShortLivedResponse = Struct.new(:access_token, :user_id)
+        ShortLivedResponse = Struct.new(:access_token, :user_id, :error_type, :error_message, :code)
         LongLivedResponse = Struct.new(:access_token, :token_type, :expires_in)
 
         def initialize(client_id:, client_secret:)
@@ -19,7 +19,7 @@ module Threads
             redirect_uri: redirect_uri
           })
 
-          ShortLivedResponse.new(*response.body.values_at("access_token", "user_id"))
+          ShortLivedResponse.new(*response.body.values_at("access_token", "user_id", "error_type", "error_message", "code"))
         end
 
         def exchange_access_token(access_token)

data/lib/threads/api/profile.rb

@@ -0,0 +1,18 @@
+require "time"
+
+module Threads
+  module API
+    class Profile
+      attr_reader :id, :username, :profile_picture_url, :biography
+
+      def initialize(json)
+        @id = json["id"]
+        @username = json["username"]
+        @profile_picture_url = json["profile_picture_url"]
+        @biography = json["biography"]
+      end
+
+      alias_method :bio, :biography
+    end
+  end
+end

data/lib/threads/api/thread.rb

@@ -0,0 +1,82 @@
+require "time"
+
+module Threads
+  module API
+    class Thread
+      class List
+        attr_reader :threads, :before, :after
+
+        def initialize(json)
+          @threads = json["data"].map { |t| Threads::API::Thread.new(t) }
+
+          @before = json.dig("paging", "cursors", "before")
+          @after = json.dig("paging", "cursors", "after")
+        end
+      end
+
+      attr_reader :id, :type, :media_url, :permalink, :user_id, :username, :text, :timestamp, :created_at, :shortcode, :video_thumbnail_url, :children
+
+      def initialize(json)
+        @id = json["id"]
+        @type = json["media_type"]
+        @permalink = json["permalink"]
+        @shortcode = json["shortcode"]
+        @text = json["text"]
+        @media_url = json["media_url"]
+        @video_thumbnail_url = json["thumbnail_url"]
+        @user_id = json.dig("owner", "id")
+        @username = json["username"]
+        @is_quote_post = json["is_quote_post"]
+
+        @timestamp = json["timestamp"]
+        @created_at = Time.iso8601(@timestamp) if @timestamp
+
+        children = Array(json["children"])
+        @children = children.map { |c| Thread.new(c) } if children.any?
+      end
+
+      def quote_post?
+        @is_quote_post
+      end
+    end
+
+    class UnpublishedThread
+      attr_reader :id
+
+      def initialize(json)
+        @id = json["id"]
+      end
+    end
+
+    class ThreadStatus < UnpublishedThread
+      attr_reader :status, :error_message
+
+      def initialize(json)
+        super
+
+        @status = json["status"]
+        @error_message = json["error_message"]
+      end
+
+      def in_progress?
+        @status == "IN_PROGRESS"
+      end
+
+      def finished?
+        @status == "FINISHED"
+      end
+
+      def published?
+        @status == "PUBLISHED"
+      end
+
+      def errored?
+        @status == "ERROR"
+      end
+
+      def expired?
+        @status == "EXPIRED"
+      end
+    end
+  end
+end

data/lib/threads/api/version.rb

@@ -2,6 +2,6 @@
 
 module Threads
   module API
-    VERSION = "0.0.1.pre"
+    VERSION = "0.2.0"
   end
 end

data/lib/threads/api.rb

@@ -2,5 +2,6 @@
 
 require "faraday"
 
+require_relative "api/client"
 require_relative "api/oauth2/client"
 require_relative "api/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: threads-api
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre
+  version: 0.2.0
 platform: ruby
 authors:
 - David Celis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-19 00:00:00.000000000 Z
+date: 2024-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -37,7 +37,10 @@ files:
 - README.md
 - Rakefile
 - lib/threads/api.rb
+- lib/threads/api/client.rb
 - lib/threads/api/oauth2/client.rb
+- lib/threads/api/profile.rb
+- lib/threads/api/thread.rb
 - lib/threads/api/version.rb
 homepage: https://github.com/davidcelis/threads-api
 licenses: