forem-ruby 0.1.0.beta1

data/lib/forem/services/podcast_episode_service.rb

@@ -0,0 +1,34 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Podcast Episodes API.
+    #
+    # Access via {Client#podcast_episodes}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   episodes = client.podcast_episodes.list(username: "codenewbies")
+    #
+    # @see PodcastEpisode
+    # @see https://developers.forem.com/api/v1#/operations/getPodcastEpisodes
+    class PodcastEpisodeService < BaseService
+      # List podcast episodes.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page (max: 1000)
+      # @option params [String] :username filter episodes by the podcast owner's
+      #   username
+      # @param opts [Hash] per-request options
+      # @return [Array<PodcastEpisode>] list of podcast episodes
+      #
+      # @example
+      #   client.podcast_episodes.list(username: "codenewbies", per_page: 20)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getPodcastEpisodes
+      def list(params = {}, opts = {})
+        PodcastEpisode.list(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/profile_image_service.rb

@@ -0,0 +1,32 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Profile Images API.
+    #
+    # Retrieves profile image URLs for a given user or organization.
+    # Access via {Client#profile_images}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   image_info = client.profile_images.retrieve("jsmith")
+    #
+    # @see ProfileImage
+    # @see https://developers.forem.com/api/v1#/operations/getProfileImage
+    class ProfileImageService < BaseService
+      # Retrieve profile image details for a user or organization by username.
+      #
+      # @param username [String] the username of the user or organization
+      # @param opts [Hash] per-request options
+      # @return [ProfileImage] profile image data including the image URL
+      #
+      # @example
+      #   image = client.profile_images.retrieve("jsmith")
+      #   puts image.profile_image
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getProfileImage
+      def retrieve(username, opts = {})
+        ProfileImage.retrieve(username, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/reaction_service.rb

@@ -0,0 +1,72 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Reactions API.
+    #
+    # Reactions are emoji-based responses to articles, comments, and other
+    # reactable content (likes, unicorns, bookmarks, etc.).
+    # Access via {Client#reactions}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   client.reactions.create(reactable_type: "Article", reactable_id: 1, category: "like")
+    #   client.reactions.toggle(reactable_type: "Article", reactable_id: 1, category: "unicorn")
+    #
+    # @see Reaction
+    # @see https://developers.forem.com/api/v1
+    class ReactionService < BaseService
+      # Create a reaction on a reactable resource.
+      #
+      # @param params [Hash] reaction attributes
+      # @option params [String] :reactable_type the type of content to react to
+      #   ("Article", "Comment", or "User")
+      # @option params [Integer] :reactable_id the ID of the content to react to
+      # @option params [String] :category the reaction type ("like", "unicorn",
+      #   "exploding_head", "raised_hands", "fire", "thumbsdown", "vomit",
+      #   "readinglist")
+      # @param opts [Hash] per-request options
+      # @return [Reaction] the newly created reaction
+      #
+      # @example
+      #   client.reactions.create(
+      #     reactable_type: "Article",
+      #     reactable_id: 12345,
+      #     category: "unicorn"
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        Reaction.create(params, opts_with_requestor(opts))
+      end
+
+      # Toggle a reaction on a reactable resource.
+      #
+      # If the reaction already exists for the authenticated user it will be
+      # destroyed; otherwise a new reaction will be created.
+      #
+      # @param params [Hash] reaction attributes
+      # @option params [String] :reactable_type the type of content
+      #   ("Article", "Comment", or "User")
+      # @option params [Integer] :reactable_id the ID of the content
+      # @option params [String] :category the reaction type ("like", "unicorn",
+      #   "exploding_head", "raised_hands", "fire", "thumbsdown", "vomit",
+      #   "readinglist")
+      # @param opts [Hash] per-request options
+      # @return [Hash] a hash with a +:result+ key indicating "create" or
+      #   "destroy"
+      #
+      # @example
+      #   result = client.reactions.toggle(
+      #     reactable_type: "Article",
+      #     reactable_id: 12345,
+      #     category: "like"
+      #   )
+      #   puts result.result  # => "create" or "destroy"
+      #
+      # @see https://developers.forem.com/api/v1
+      def toggle(params = {}, opts = {})
+        Reaction.toggle(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/reading_list_service.rb

@@ -0,0 +1,35 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Reading List API.
+    #
+    # Lists articles the authenticated user has bookmarked for later reading.
+    # Access via {Client#reading_list}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   bookmarks = client.reading_list.list(page: 1, per_page: 20)
+    #
+    # @see ReadingList
+    # @see https://developers.forem.com/api/v1#/operations/getReadinglist
+    class ReadingListService < BaseService
+      # List articles in the authenticated user's reading list.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page (max: 1000)
+      # @option params [String] :status filter by bookmark status ("valid",
+      #   "invalid", "confirmed", "archived")
+      # @param opts [Hash] per-request options
+      # @return [Array<ReadingList>] bookmarked articles for the current user
+      #
+      # @example
+      #   client.reading_list.list(per_page: 50)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getReadinglist
+      def list(params = {}, opts = {})
+        ReadingList.list(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/recommended_articles_list_service.rb

@@ -0,0 +1,87 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Recommended Articles Lists API.
+    #
+    # Recommended articles lists are curated collections of articles surfaced
+    # to specific user segments.
+    # Access via {Client#recommended_articles_lists}. All methods inject the
+    # client's requestor automatically so no additional configuration is
+    # required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   lists = client.recommended_articles_lists.list
+    #   list  = client.recommended_articles_lists.retrieve(2)
+    #
+    # @see RecommendedArticlesList
+    # @see https://developers.forem.com/api/v1
+    class RecommendedArticlesListService < BaseService
+      # List all recommended articles lists.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page
+      # @param opts [Hash] per-request options
+      # @return [Array<RecommendedArticlesList>] all recommended articles lists
+      #
+      # @example
+      #   client.recommended_articles_lists.list
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        RecommendedArticlesList.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new recommended articles list.
+      #
+      # @param params [Hash] list attributes
+      # @option params [String] :name name of the list
+      # @option params [Integer] :segment_id the audience segment this list
+      #   targets
+      # @param opts [Hash] per-request options
+      # @return [RecommendedArticlesList] the newly created list
+      #
+      # @example
+      #   client.recommended_articles_lists.create(
+      #     name: "Top Ruby Articles",
+      #     segment_id: 5
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        RecommendedArticlesList.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single recommended articles list by its numeric ID.
+      #
+      # @param id [Integer, String] the list ID
+      # @param opts [Hash] per-request options
+      # @return [RecommendedArticlesList] the list with the given ID
+      #
+      # @example
+      #   client.recommended_articles_lists.retrieve(2)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        RecommendedArticlesList.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Update an existing recommended articles list.
+      #
+      # @param id [Integer, String] the list ID to update
+      # @param params [Hash] list attributes to change
+      # @option params [String] :name new name for the list
+      # @option params [Integer] :segment_id new target segment
+      # @param opts [Hash] per-request options
+      # @return [RecommendedArticlesList] the updated list
+      #
+      # @example
+      #   client.recommended_articles_lists.update(2, name: "Best Ruby Content")
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        RecommendedArticlesList.update(id, params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/request_redirect_service.rb

@@ -0,0 +1,118 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Admin Request Redirects API.
+    #
+    # Request redirects power organization custom domains: a request for
+    # +request_domain+ at path +original_url+ is redirected to
+    # +destination_url+. These endpoints require an API key with admin-level
+    # privileges. Access via {Client#request_redirects}. All methods inject
+    # the client's requestor automatically so no additional configuration is
+    # required.
+    #
+    # The underlying API requires create/update request bodies to be wrapped
+    # in a +request_redirect:+ key. This service accepts flat attribute
+    # hashes and wraps them for you, so callers never need to think about the
+    # wrapper.
+    #
+    # @example
+    #   client = Forem::Client.new("admin-api-key")
+    #   redirect = client.request_redirects.create(
+    #     original_url: "/old",
+    #     destination_url: "https://example.com/new",
+    #     request_domain: "example.com"
+    #   )
+    #
+    # @see RequestRedirect
+    # @see https://developers.forem.com/api/v1
+    class RequestRedirectService < BaseService
+      # List all request redirects, most recently created first.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page
+      #   (default: 50, maximum: 100)
+      # @param opts [Hash] per-request options
+      # @return [Forem::ListObject<RequestRedirect>] paginated list of request redirects
+      #
+      # @example
+      #   client.request_redirects.list(per_page: 25)
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        RequestRedirect.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single request redirect by its numeric ID.
+      #
+      # @param id [Integer, String] the request redirect ID
+      # @param opts [Hash] per-request options
+      # @return [RequestRedirect] the request redirect with the given ID
+      #
+      # @example
+      #   client.request_redirects.retrieve(7)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        RequestRedirect.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Create a new request redirect.
+      #
+      # @param params [Hash] request redirect attributes (flat — no
+      #   +request_redirect:+ wrapper needed, this method adds it for you)
+      # @option params [String] :original_url the incoming request path;
+      #   must start with +/+
+      # @option params [String] :destination_url the fully-qualified
+      #   HTTP/HTTPS URL to redirect to
+      # @option params [String] :request_domain the domain the redirect
+      #   applies to
+      # @param opts [Hash] per-request options
+      # @return [RequestRedirect] the newly created request redirect
+      #
+      # @example
+      #   client.request_redirects.create(
+      #     original_url: "/old",
+      #     destination_url: "https://example.com/new",
+      #     request_domain: "example.com"
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        RequestRedirect.create({ request_redirect: params }, opts_with_requestor(opts))
+      end
+
+      # Update an existing request redirect.
+      #
+      # @param id [Integer, String] the request redirect ID to update
+      # @param params [Hash] request redirect attributes to change (flat —
+      #   no +request_redirect:+ wrapper needed, this method adds it for you)
+      # @option params [String] :original_url new incoming request path
+      # @option params [String] :destination_url new destination URL
+      # @option params [String] :request_domain new request domain
+      # @param opts [Hash] per-request options
+      # @return [RequestRedirect] the updated request redirect
+      #
+      # @example
+      #   client.request_redirects.update(7, destination_url: "https://example.com/newer")
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        RequestRedirect.update(id, { request_redirect: params }, opts_with_requestor(opts))
+      end
+
+      # Delete a request redirect.
+      #
+      # @param id [Integer, String] the request redirect ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success (the API responds with 204 No Content)
+      #
+      # @example
+      #   client.request_redirects.delete(7)
+      #
+      # @see https://developers.forem.com/api/v1
+      def delete(id, opts = {})
+        RequestRedirect.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/segment_service.rb

@@ -0,0 +1,83 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Segments API.
+    #
+    # Segments are user-defined audience groups used for targeted content
+    # and billboard campaigns.
+    # Access via {Client#segments}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   segments = client.segments.list
+    #   segment  = client.segments.retrieve(5)
+    #
+    # @see Segment
+    # @see https://developers.forem.com/api/v1#/operations/getSegments
+    class SegmentService < BaseService
+      # List all audience segments.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page
+      # @param opts [Hash] per-request options
+      # @return [Forem::ListObject<Forem::Segment>] paginated list of segments
+      #
+      # @example
+      #   client.segments.list
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getSegments
+      def list(params = {}, opts = {})
+        Segment.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new audience segment.
+      #
+      # The Forem API does not accept any parameters on this endpoint —
+      # newly-created segments are always +type_of: "manual"+ and do not
+      # carry a name. Manage membership separately via {Segment#add_users}
+      # and {Segment#remove_users}.
+      #
+      # @param params [Hash] ignored by the API, kept for forward-compat
+      # @param opts [Hash] per-request options
+      # @return [Forem::Segment] the newly created (empty) segment
+      #
+      # @example
+      #   segment = client.segments.create
+      #   segment.add_users(user_ids: [101, 102])
+      #
+      # @see https://developers.forem.com/api/v1#/operations/createSegment
+      def create(params = {}, opts = {})
+        Segment.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single audience segment by its numeric ID.
+      #
+      # @param id [Integer, String] the segment ID
+      # @param opts [Hash] per-request options
+      # @return [Segment] the segment with the given ID
+      #
+      # @example
+      #   client.segments.retrieve(5)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        Segment.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Delete an audience segment.
+      #
+      # @param id [Integer, String] the segment ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success
+      #
+      # @example
+      #   client.segments.delete(5)
+      #
+      # @see https://developers.forem.com/api/v1
+      def delete(id, opts = {})
+        Segment.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/survey_service.rb

@@ -0,0 +1,48 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Surveys API.
+    #
+    # Surveys are questionnaires presented to community members.
+    # Access via {Client#surveys}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   surveys = client.surveys.list
+    #   survey  = client.surveys.retrieve(8)
+    #
+    # @see Survey
+    # @see https://developers.forem.com/api/v1#/operations/getSurveyByIdOrSlug
+    class SurveyService < BaseService
+      # List all surveys.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page
+      # @param opts [Hash] per-request options
+      # @return [Array<Survey>] list of surveys
+      #
+      # @example
+      #   client.surveys.list
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Survey.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single survey by its numeric ID.
+      #
+      # @param id [Integer, String] the survey ID
+      # @param opts [Hash] per-request options
+      # @return [Survey] the survey with the given ID
+      #
+      # @example
+      #   client.surveys.retrieve(8)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getSurveyByIdOrSlug
+      def retrieve(id, opts = {})
+        Survey.retrieve(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/tag_service.rb

@@ -0,0 +1,32 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Tags API.
+    #
+    # Access via {Client#tags}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   tags = client.tags.list(per_page: 50)
+    #
+    # @see Tag
+    # @see https://developers.forem.com/api/v1#/operations/getTags
+    class TagService < BaseService
+      # List tags used on the Forem instance, ordered by popularity.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page (max: 1000)
+      # @param opts [Hash] per-request options
+      # @return [Array<Tag>] list of tags ordered by article count
+      #
+      # @example
+      #   client.tags.list(per_page: 100)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getTags
+      def list(params = {}, opts = {})
+        Tag.list(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/trend_service.rb

@@ -0,0 +1,70 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Trends API.
+    #
+    # Trends are algorithmically-derived, "hot and recent" topic clusters made
+    # up of related articles. Access via {Client#trends}. All methods inject
+    # the client's requestor automatically so no additional configuration is
+    # required. Trends are read-only via the public API.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   trends = client.trends.list
+    #   trend  = client.trends.retrieve("ai-agents")
+    #   articles = client.trends.articles("ai-agents")
+    #
+    # @see Trend
+    # @see https://developers.forem.com/api/v1
+    class TrendService < BaseService
+      # List hot and recent trends.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page (default: 10)
+      # @param opts [Hash] per-request options
+      # @return [Forem::ListObject<Trend>] paginated list of trends
+      #
+      # @example
+      #   client.trends.list(per_page: 20)
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Trend.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single trend by its numeric ID or slug.
+      #
+      # @param id_or_slug [Integer, String] the trend's ID or slug
+      # @param opts [Hash] per-request options
+      # @return [Trend] the trend matching the given ID or slug
+      #
+      # @example
+      #   client.trends.retrieve("ai-agents")
+      #   client.trends.retrieve(3)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id_or_slug, opts = {})
+        Trend.retrieve(id_or_slug, opts_with_requestor(opts))
+      end
+
+      # List the articles belonging to a trend.
+      #
+      # @param id_or_slug [Integer, String] the trend's ID or slug
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page (default: 10)
+      # @option params [String] :sort +"score"+ to sort purely by article score;
+      #   omit for the default ordering (trend membership distance, then score)
+      # @param opts [Hash] per-request options
+      # @return [Array<Forem::Article>] articles associated with the trend
+      #
+      # @example
+      #   client.trends.articles("ai-agents", per_page: 5, sort: "score")
+      #
+      # @see https://developers.forem.com/api/v1
+      def articles(id_or_slug, params = {}, opts = {})
+        Trend.articles(id_or_slug, params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/user_service.rb

@@ -0,0 +1,61 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Users API.
+    #
+    # Access via {Client#users}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   me = client.users.me
+    #   user = client.users.retrieve(42)
+    #
+    # @see User
+    # @see https://developers.forem.com/api/v1#/operations/getUser
+    class UserService < BaseService
+      # Retrieve a single user by their numeric ID.
+      #
+      # @param id [Integer, String] the user ID, or the string "by_username"
+      #   combined with the +:username+ param
+      # @param opts [Hash] per-request options
+      # @return [User] the user with the given ID
+      #
+      # @example
+      #   client.users.retrieve(42)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getUser
+      def retrieve(id, opts = {})
+        User.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Retrieve the profile of the currently authenticated user.
+      #
+      # @param opts [Hash] per-request options
+      # @return [User] the authenticated user's profile
+      #
+      # @example
+      #   me = client.users.me
+      #   puts me.username
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getUserMe
+      def me(opts = {})
+        User.me(opts_with_requestor(opts))
+      end
+
+      # Search for users by name or username.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :term the search term
+      # @param opts [Hash] per-request options
+      # @return [Array<User>] users matching the search query
+      #
+      # @example
+      #   client.users.search(term: "jane")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/searchUser
+      def search(params = {}, opts = {})
+        User.search(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end