forem-ruby 0.1.0.beta1

data/lib/forem/resources/video.rb

@@ -0,0 +1,28 @@
+module Forem
+  # Represents an article with an associated video on a Forem instance.
+  #
+  # Video articles are a special content type where the primary content is a
+  # video rather than text. The public API supports listing video articles,
+  # returned ordered by publication date.
+  #
+  # Returns published articles with video, ordered by descending popularity.
+  # Default: 24 per page.
+  #
+  # Available operations (via mixins):
+  #   - +List+ — GET /api/videos
+  #
+  # @example List video articles
+  #   videos = client.videos.list(per_page: 10)
+  #   videos.data.each { |v| puts v.title }
+  #
+  # @example Iterate over all video articles using auto-pagination
+  #   client.videos.list.auto_paging_each { |v| puts "#{v.title}: #{v.video_source_url}" }
+  #
+  # @see https://developers.forem.com/api/v1#/operations/videos
+  class Video < APIResource
+    extend APIOperations::List
+
+    OBJECT_NAME = "video"
+    RESOURCE_PATH = "/api/videos"
+  end
+end

data/lib/forem/services/admin_concept_service.rb

@@ -0,0 +1,138 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Admin Concepts API.
+    #
+    # Provides full CRUD over concepts — the curated topics Forem uses to
+    # classify articles and comments — plus the +trigger_lookback+ action that
+    # re-runs classification over older content. Every endpoint requires an API
+    # key with super admin privileges; regular user keys receive HTTP 401.
+    #
+    # Access via {Client#admin_concepts}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("admin-api-key")
+    #   concept = client.admin_concepts.create(name: "Machine Learning")
+    #   client.admin_concepts.trigger_lookback(concept.id, days: 90)
+    #
+    # @see AdminConcept
+    # @see Forem::Concept
+    # @see https://developers.forem.com/api/v1
+    class AdminConceptService < BaseService
+      # List concepts, ordered by name.
+      #
+      # Returns a trimmed projection of each concept: +id+, +name+, +slug+,
+      # +description+, +parent_id+, +similarity_threshold+,
+      # +max_lookback_days+, +created_at+, and +updated_at+.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page results per page (default: 50, max: 100)
+      # @param opts [Hash] per-request options
+      # @return [ListObject] the current page of {AdminConcept} records
+      #
+      # @example
+      #   client.admin_concepts.list(per_page: 100)
+      def list(params = {}, opts = {})
+        AdminConcept.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single concept by ID.
+      #
+      # Returns the full concept record, unlike {#list} which returns a
+      # trimmed projection.
+      #
+      # @param id [Integer, String] the concept ID
+      # @param opts [Hash] per-request options
+      # @return [AdminConcept] the requested concept
+      # @raise [NotFoundError] if no concept has that ID
+      #
+      # @example
+      #   client.admin_concepts.retrieve(7)
+      def retrieve(id, opts = {})
+        AdminConcept.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Create a new concept.
+      #
+      # Attributes are sent wrapped in a +concept+ object for you. The API
+      # generates the slug, and generates a description and the anchor
+      # embedding from +name+, so only +name+ is required.
+      #
+      # @param params [Hash] concept attributes
+      # @option params [String] :name the concept name, max 100 chars (required)
+      # @option params [String] :description human-readable description
+      # @option params [Integer] :parent_id ID of the parent concept
+      # @option params [Float] :similarity_threshold classification cutoff (0.0–1.0)
+      # @option params [Float] :score ranking score for the concept
+      # @param opts [Hash] per-request options
+      # @return [AdminConcept] the newly created concept
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors)
+      #
+      # @example
+      #   client.admin_concepts.create(
+      #     name: "Machine Learning",
+      #     description: "Posts about ML and AI",
+      #     similarity_threshold: 0.8
+      #   )
+      def create(params = {}, opts = {})
+        AdminConcept.create(params, opts_with_requestor(opts))
+      end
+
+      # Update an existing concept.
+      #
+      # Attributes are sent wrapped in a +concept+ object for you. Only
+      # +name+, +description+, +parent_id+, +similarity_threshold+, and
+      # +score+ are writable; +slug+ and +max_lookback_days+ are ignored.
+      # Changing +name+ or +description+ regenerates the anchor embedding.
+      #
+      # @param id [Integer, String] the concept ID
+      # @param params [Hash] attributes to change (see {#create})
+      # @param opts [Hash] per-request options
+      # @return [AdminConcept] the updated concept
+      # @raise [NotFoundError] if no concept has that ID
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors)
+      #
+      # @example
+      #   client.admin_concepts.update(7, similarity_threshold: 0.9)
+      def update(id, params = {}, opts = {})
+        AdminConcept.update(id, params, opts_with_requestor(opts))
+      end
+
+      # Delete a concept.
+      #
+      # The API responds with HTTP 204 and no body on success.
+      #
+      # @param id [Integer, String] the concept ID
+      # @param opts [Hash] per-request options
+      # @return [AdminConcept, nil] +nil+ for the usual empty response
+      # @raise [NotFoundError] if no concept has that ID
+      #
+      # @example
+      #   client.admin_concepts.delete(7)
+      def delete(id, opts = {})
+        AdminConcept.delete(id, opts_with_requestor(opts))
+      end
+
+      # Queue a classification lookback for a concept.
+      #
+      # Enqueues a background job that classifies records from the last
+      # +days+ days. The value must be positive and strictly greater than the
+      # concept's current +max_lookback_days+, otherwise the API responds with
+      # HTTP 422.
+      #
+      # @param id [Integer, String] the concept ID
+      # @param params [Hash] request body
+      # @option params [Integer] :days how many days back to classify (required)
+      # @param opts [Hash] per-request options
+      # @return [ForemObject] an object carrying a +message+
+      # @raise [InvalidRequestError] on HTTP 422 when +days+ is out of range
+      #
+      # @example
+      #   client.admin_concepts.trigger_lookback(7, days: 90).message
+      def trigger_lookback(id, params = {}, opts = {})
+        AdminConcept.trigger_lookback(id, params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/admin_user_service.rb

@@ -0,0 +1,114 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Admin Users API.
+    #
+    # Provides administrative operations on user accounts. These endpoints
+    # require an API key with admin-level privileges.
+    # Access via {Client#admin_users}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("admin-api-key")
+    #   user = client.admin_users.create(
+    #     email: "newuser@example.com",
+    #     name: "New User"
+    #   )
+    #
+    # @see AdminUser
+    # @see https://developers.forem.com/api/v1#/operations/postAdminUsersCreate
+    class AdminUserService < BaseService
+      # Invite a new user to the Forem instance.
+      #
+      # Creates a user account and sends them an invitation email.
+      # Requires admin privileges.
+      #
+      # @param params [Hash] user attributes
+      # @option params [String] :email the new user's email address (required)
+      # @option params [String] :name display name for the new user
+      # @option params [String] :username desired username (generated if omitted)
+      # @param opts [Hash] per-request options
+      # @return [AdminUser] the newly created user record
+      #
+      # @example
+      #   client.admin_users.create(
+      #     email: "jane@example.com",
+      #     name: "Jane Doe"
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1#/operations/postAdminUsersCreate
+      def create(params = {}, opts = {})
+        AdminUser.create(params, opts_with_requestor(opts))
+      end
+
+      # Link an external identity to a user.
+      #
+      # @param user_id [Integer, String] the Forem user ID.
+      # @param provider [String] the identity provider name.
+      # @param uid [String] the provider's stable user identifier.
+      # @param opts [Hash] per-request options.
+      # @return [ForemObject] the linked identity.
+      def link_identity(user_id, provider:, uid:, **opts)
+        AdminUser.link_identity(
+          user_id,
+          provider: provider,
+          uid: uid,
+          **opts_with_requestor(opts)
+        )
+      end
+
+      # Submit multiple external identity links in one request.
+      #
+      # @param provider [String] the identity provider shared by the identities.
+      # @param identities [Array<Hash>] identity hashes containing +user_id+ and
+      #   +uid+.
+      # @param opts [Hash] per-request options.
+      # @return [Array<ForemObject>] per-item results containing +user_id+,
+      #   +status+, and an +error_code+ when that item fails.
+      def bulk_link_identities(provider:, identities:, **opts)
+        AdminUser.bulk_link_identities(
+          provider: provider,
+          identities: identities,
+          **opts_with_requestor(opts)
+        )
+      end
+
+      # List a user's linked external identities.
+      #
+      # @param user_id [Integer, String] the Forem user ID.
+      # @param opts [Hash] per-request options.
+      # @return [Array<ForemObject>] the user's linked identities.
+      def identities(user_id, **opts)
+        AdminUser.identities(user_id, **opts_with_requestor(opts))
+      end
+
+      # Unlink an external identity from a user.
+      #
+      # @param user_id [Integer, String] the Forem user ID.
+      # @param identity_id [Integer, String] the linked identity ID.
+      # @param opts [Hash] per-request options.
+      # @return [ForemObject, nil] the unlinked identity, or +nil+ for an empty
+      #   response.
+      def unlink_identity(user_id, identity_id, **opts)
+        AdminUser.unlink_identity(
+          user_id,
+          identity_id,
+          **opts_with_requestor(opts)
+        )
+      end
+
+      # Update the email newsletter notification setting for a user.
+      #
+      # @param user_id [Integer, String] the Forem user ID.
+      # @param email_newsletter [Boolean] whether newsletter email is enabled.
+      # @param opts [Hash] per-request options.
+      # @return [ForemObject] the updated notification setting.
+      def update_notification_settings(user_id, email_newsletter:, **opts)
+        AdminUser.update_notification_settings(
+          user_id,
+          email_newsletter: email_newsletter,
+          **opts_with_requestor(opts)
+        )
+      end
+    end
+  end
+end

data/lib/forem/services/agent_session_service.rb

@@ -0,0 +1,87 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Agent Sessions API.
+    #
+    # Agent sessions enable automated or AI-driven interactions with the Forem
+    # platform. The presign endpoint provides a pre-signed URL for uploading
+    # assets associated with a session.
+    # Access via {Client#agent_sessions}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   sessions = client.agent_sessions.list
+    #   session  = client.agent_sessions.create(name: "My Agent")
+    #
+    # @see AgentSession
+    # @see https://developers.forem.com/api/v1#/operations/getAgentSessions
+    class AgentSessionService < BaseService
+      # List all agent sessions.
+      #
+      # @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<AgentSession>] list of agent sessions
+      #
+      # @example
+      #   client.agent_sessions.list
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getAgentSessions
+      def list(params = {}, opts = {})
+        AgentSession.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new agent session.
+      #
+      # @param params [Hash] session attributes
+      # @option params [String] :name display name for the session
+      # @param opts [Hash] per-request options
+      # @return [AgentSession] the newly created agent session
+      #
+      # @example
+      #   session = client.agent_sessions.create(name: "Content Generation Bot")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/createAgentSession
+      def create(params = {}, opts = {})
+        AgentSession.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single agent session by its numeric ID.
+      #
+      # @param id [Integer, String] the session ID
+      # @param opts [Hash] per-request options
+      # @return [AgentSession] the session with the given ID
+      #
+      # @example
+      #   client.agent_sessions.retrieve(14)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getAgentSessionById
+      def retrieve(id, opts = {})
+        AgentSession.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Obtain a pre-signed URL for uploading a file associated with an agent
+      # session.
+      #
+      # @param params [Hash] presign request parameters
+      # @option params [String] :filename name of the file to upload
+      # @option params [String] :mime_type MIME type of the file
+      # @param opts [Hash] per-request options
+      # @return [AgentSession] object containing the pre-signed upload URL and
+      #   related metadata
+      #
+      # @example
+      #   presign_data = client.agent_sessions.presign(
+      #     filename: "image.png",
+      #     mime_type: "image/png"
+      #   )
+      #   puts presign_data.upload_url
+      #
+      # @see https://developers.forem.com/api/v1
+      def presign(params = {}, opts = {})
+        AgentSession.presign(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/analytics_service.rb

@@ -0,0 +1,93 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Analytics API.
+    #
+    # Provides engagement and traffic data for articles and organizations.
+    # Access via {Client#analytics}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   totals = client.analytics.totals(username: "jsmith")
+    #   daily  = client.analytics.historical(username: "jsmith", start: "2024-01-01")
+    #
+    # @see Analytics
+    # @see https://developers.forem.com/api/v1
+    class AnalyticsService < BaseService
+      # Retrieve total engagement metrics for a user or organization.
+      #
+      # Returns all-time totals for page views, reactions, comments, and
+      # follows.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :username filter metrics by author username
+      # @option params [String] :organization_id filter metrics by organization
+      #   ID
+      # @param opts [Hash] per-request options
+      # @return [Analytics] total engagement metrics
+      #
+      # @example
+      #   client.analytics.totals(username: "jsmith")
+      #
+      # @see https://developers.forem.com/api/v1
+      def totals(params = {}, opts = {})
+        Analytics.totals(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve historical engagement metrics broken down by day.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :username filter by author username
+      # @option params [String] :organization_id filter by organization ID
+      # @option params [String] :start start date in ISO 8601 format
+      #   (e.g. "2024-01-01")
+      # @option params [String] :end end date in ISO 8601 format
+      # @param opts [Hash] per-request options
+      # @return [Array<Analytics>] daily breakdown of engagement metrics
+      #
+      # @example
+      #   client.analytics.historical(
+      #     username: "jsmith",
+      #     start: "2024-01-01",
+      #     end: "2024-03-31"
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def historical(params = {}, opts = {})
+        Analytics.historical(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve engagement metrics for the past 24 hours.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :username filter by author username
+      # @option params [String] :organization_id filter by organization ID
+      # @param opts [Hash] per-request options
+      # @return [Analytics] metrics for the past day
+      #
+      # @example
+      #   client.analytics.past_day(username: "jsmith")
+      #
+      # @see https://developers.forem.com/api/v1
+      def past_day(params = {}, opts = {})
+        Analytics.past_day(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve referrer traffic data for a user or organization's content.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :username filter by author username
+      # @option params [String] :organization_id filter by organization ID
+      # @param opts [Hash] per-request options
+      # @return [Array<Analytics>] referrer breakdown showing traffic sources
+      #
+      # @example
+      #   client.analytics.referrers(username: "jsmith")
+      #
+      # @see https://developers.forem.com/api/v1
+      def referrers(params = {}, opts = {})
+        Analytics.referrers(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/article_service.rb

@@ -0,0 +1,233 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Articles API.
+    #
+    # Access via {Client#articles}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   service = client.articles
+    #   service.list(per_page: 5, tag: "ruby")
+    #
+    # @see Article
+    # @see https://developers.forem.com/api/v1#/operations/getArticles
+    class ArticleService < BaseService
+      # List published articles.
+      #
+      # @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] :tag filter by a single tag name
+      # @option params [String] :tags comma-separated list of tags to include
+      # @option params [String] :tags_exclude comma-separated list of tags to exclude
+      # @option params [String] :username filter by author username
+      # @option params [String] :state article state ("fresh", "rising", "all")
+      # @option params [Integer] :top number of days back to look for top articles
+      # @option params [String] :collection_id filter by collection ID
+      # @param opts [Hash] per-request options
+      # @return [Array<Article>] list of published articles
+      #
+      # @example
+      #   client.articles.list(tag: "ruby", per_page: 10)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getArticles
+      def list(params = {}, opts = {})
+        Article.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new article.
+      #
+      # @param params [Hash] article attributes
+      # @option params [String] :title article title
+      # @option params [String] :body_markdown article body in Markdown
+      # @option params [Boolean] :published whether to publish immediately
+      # @option params [Array<String>] :tags list of tag names
+      # @option params [String] :series name of a series to add the article to
+      # @option params [String] :canonical_url canonical URL override
+      # @option params [String] :description article description / excerpt
+      # @param opts [Hash] per-request options
+      # @return [Article] the newly created article
+      #
+      # @example
+      #   client.articles.create(
+      #     title: "Hello World",
+      #     body_markdown: "# Hello\nThis is my first post.",
+      #     published: true,
+      #     tags: ["ruby", "beginners"]
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1#/operations/createArticle
+      def create(params = {}, opts = {})
+        Article.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single article by its numeric ID.
+      #
+      # @param id [Integer, String] the article ID
+      # @param opts [Hash] per-request options
+      # @return [Article] the article with the given ID
+      #
+      # @example
+      #   client.articles.retrieve(12345)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getArticleById
+      def retrieve(id, opts = {})
+        Article.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Update an existing article.
+      #
+      # @param id [Integer, String] the article ID to update
+      # @param params [Hash] article attributes to change
+      # @option params [String] :title new title
+      # @option params [String] :body_markdown new body in Markdown
+      # @option params [Boolean] :published publish or unpublish the article
+      # @option params [Array<String>] :tags updated list of tag names
+      # @param opts [Hash] per-request options
+      # @return [Article] the updated article
+      #
+      # @example
+      #   client.articles.update(12345, title: "Updated Title", published: true)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/updateArticle
+      def update(id, params = {}, opts = {})
+        Article.update(id, params, opts_with_requestor(opts))
+      end
+
+      # List articles authored by the authenticated user.
+      #
+      # @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<Article>] articles belonging to the current user
+      #
+      # @example
+      #   client.articles.me(per_page: 30)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+      def me(params = {}, opts = {})
+        Article.me(params, opts_with_requestor(opts))
+      end
+
+      # List published articles authored by the authenticated user.
+      #
+      # @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<Article>] published articles belonging to the current user
+      #
+      # @example
+      #   client.articles.me_published
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+      def me_published(params = {}, opts = {})
+        Article.me_published(params, opts_with_requestor(opts))
+      end
+
+      # List unpublished articles (drafts) authored by the authenticated user.
+      #
+      # @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<Article>] unpublished articles belonging to the current user
+      #
+      # @example
+      #   client.articles.me_unpublished
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+      def me_unpublished(params = {}, opts = {})
+        Article.me_unpublished(params, opts_with_requestor(opts))
+      end
+
+      # List all articles (published and unpublished) authored by the authenticated user.
+      #
+      # @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<Article>] all articles belonging to the current user
+      #
+      # @example
+      #   client.articles.me_all
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+      def me_all(params = {}, opts = {})
+        Article.me_all(params, opts_with_requestor(opts))
+      end
+
+      # List the most recently published articles.
+      #
+      # @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<Article>] latest published articles in chronological order
+      #
+      # @example
+      #   client.articles.latest(per_page: 20)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getLatestArticles
+      def latest(params = {}, opts = {})
+        Article.latest(params, opts_with_requestor(opts))
+      end
+
+      # Search articles by keyword.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :q the search term
+      # @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<Article>] articles matching the search query
+      #
+      # @example
+      #   client.articles.search(q: "ruby on rails")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/searchArticles
+      def search(params = {}, opts = {})
+        Article.search(params, opts_with_requestor(opts))
+      end
+
+      # Semantically search articles using Forem's embeddings-based search.
+      #
+      # Unlike +search+ (keyword matching), this finds articles whose meaning
+      # is close to the query text. Requires authentication.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :q the search query text (required)
+      # @option params [Integer] :page page number (default: 1)
+      # @option params [Integer] :per_page number of results per page (default: 10, max: 50)
+      # @option params [Float] :threshold optional cosine distance threshold (0.0-2.0)
+      # @param opts [Hash] per-request options
+      # @return [Array<Article>] articles matching the query, each exposing
+      #   +distance+ and +similarity+ attributes
+      #
+      # @example
+      #   client.articles.semantic_search(q: "how to deploy rails apps")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/semanticSearchArticles
+      def semantic_search(params = {}, opts = {})
+        Article.semantic_search(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve an article by its author username and slug.
+      #
+      # @param username [String] the author's username
+      # @param slug [String] the article slug
+      # @param opts [Hash] per-request options
+      # @return [Article] the matching article
+      #
+      # @example
+      #   client.articles.retrieve_by_path("jsmith", "my-great-post")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getArticleByPath
+      def retrieve_by_path(username, slug, opts = {})
+        Article.retrieve_by_path(username, slug, opts_with_requestor(opts))
+      end
+    end
+  end
+end