forem-ruby 0.1.0.beta1

data/lib/forem/resources/analytics.rb

@@ -0,0 +1,151 @@
+module Forem
+  # Provides access to analytics data for the authenticated user's content.
+  #
+  # All analytics endpoints require authentication. They return analytics for
+  # the calling user (or an organization, when +:organization_id+ is passed).
+  #
+  # The Analytics resource exposes four read-only reporting endpoints:
+  # cumulative totals, day-by-day historical data, yesterday's aggregates,
+  # and traffic referrer breakdowns.
+  #
+  # == Response shapes
+  #
+  # The Forem analytics endpoints don't all return the same kind of object,
+  # so this resource preserves each endpoint's natural shape rather than
+  # forcing them into a uniform list:
+  #
+  # * {.totals}     — single nested-stats object
+  # * {.historical} — +Hash+ keyed by +"YYYY-MM-DD"+ date string
+  # * {.past_day}   — +Hash+ keyed by +"YYYY-MM-DD"+ (typically 1–2 entries)
+  # * {.referrers}  — +Array+ of referrer objects (extracted from +domains+)
+  #
+  # @example Lifetime totals
+  #   totals = client.analytics.totals
+  #   puts totals.reactions.total   #=> 7
+  #   puts totals.page_views.total  #=> 7
+  #
+  # @example Historical data for a date range
+  #   history = client.analytics.historical(start: "2026-04-01", end: "2026-04-30")
+  #   history.each do |date, stats|
+  #     puts "#{date}: #{stats.page_views.total} views"
+  #   end
+  #
+  # @example Referrer breakdown
+  #   client.analytics.referrers.each { |r| puts "#{r.domain}: #{r.count}" }
+  #
+  # @see https://developers.forem.com/api/v1
+  class Analytics < APIResource
+    OBJECT_NAME = "analytics"
+    RESOURCE_PATH = "/api/analytics"
+
+    # Return cumulative analytics totals for the authenticated user (or org).
+    #
+    # The response groups totals into nested buckets — +comments+, +follows+,
+    # +reactions+, and +page_views+ — each with its own sub-fields. To read
+    # a count, navigate one level deeper than you might expect (e.g.
+    # +totals.reactions.total+, not +totals.reactions+).
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :article_id filter to a specific article
+    # @option params [Integer] :organization_id ID of the organization
+    # @param opts [Hash] per-request options
+    # @return [Forem::ForemObject] cumulative stats with nested sub-objects
+    # @example
+    #   totals = client.analytics.totals
+    #   puts totals.reactions.total          #=> 7
+    #   puts totals.reactions.like           #=> 2
+    #   puts totals.page_views.total         #=> 7
+    # @see https://developers.forem.com/api/v1
+    def self.totals(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/analytics/totals", params, opts)
+      Forem::ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    end
+
+    # Return day-by-day historical analytics for a given date range.
+    #
+    # The response is a +Hash+ keyed by the calendar date (+"YYYY-MM-DD"+).
+    # Each value is a stats object with the same nested shape as {.totals}.
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :start (required) start date in YYYY-MM-DD form.
+    # @option params [String] :end end date in YYYY-MM-DD form.
+    # @option params [String] :article_id filter to a specific article.
+    # @option params [Integer] :organization_id ID of the organization.
+    # @param opts [Hash] per-request options
+    # @return [Hash{String => Forem::ForemObject}] stats keyed by date.
+    # @example
+    #   history = client.analytics.historical(start: "2026-04-01", end: "2026-04-15")
+    #   history.each do |date, stats|
+    #     puts "#{date}: #{stats.page_views.total} views"
+    #   end
+    # @see https://developers.forem.com/api/v1
+    def self.historical(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/analytics/historical", params, opts)
+      grouped_by_day(resp.parsed_body, requestor)
+    end
+
+    # Return aggregated analytics for the previous calendar day(s).
+    #
+    # The response shape mirrors {.historical}: a +Hash+ keyed by date.
+    # Forem typically returns one or two entries (yesterday plus today's
+    # partial), so callers usually want either the most recent date or
+    # iteration with +#each+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :article_id filter to a specific article.
+    # @option params [Integer] :organization_id ID of the organization.
+    # @param opts [Hash] per-request options
+    # @return [Hash{String => Forem::ForemObject}] stats keyed by date.
+    # @example
+    #   stats = client.analytics.past_day
+    #   latest_date, latest_stats = stats.max_by { |date, _| date }
+    #   puts "#{latest_date}: #{latest_stats.page_views.total} views"
+    # @see https://developers.forem.com/api/v1
+    def self.past_day(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/analytics/past_day", params, opts)
+      grouped_by_day(resp.parsed_body, requestor)
+    end
+
+    # Return the breakdown of traffic referrers for the authenticated user's
+    # content.
+    #
+    # The endpoint wraps the data in a +{"domains" => [...]}+ envelope. This
+    # method unwraps that envelope and returns the inner array directly so
+    # callers can iterate without an extra hop.
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :start start date in YYYY-MM-DD form.
+    # @option params [String] :end end date in YYYY-MM-DD form.
+    # @option params [String] :article_id filter to a specific article.
+    # @option params [Integer] :organization_id ID of the organization.
+    # @param opts [Hash] per-request options
+    # @return [Array<Forem::ForemObject>] referrer objects with +domain+ and
+    #   +count+ fields.
+    # @example
+    #   client.analytics.referrers.each { |r| puts "#{r.domain}: #{r.count}" }
+    # @see https://developers.forem.com/api/v1
+    def self.referrers(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/analytics/referrers", params, opts)
+      body = resp.parsed_body
+      domains = body.is_a?(Hash) ? (body["domains"] || []) : []
+      domains.map { |item| Forem::ForemObject.construct_from(item, requestor: requestor) }
+    end
+
+    # Internal: convert the date-keyed response of historical/past_day into a
+    # Hash<String, ForemObject>. Preserves +nil+ stat values (which the API
+    # emits for some days) by converting them to an empty ForemObject.
+    #
+    # @api private
+    def self.grouped_by_day(body, requestor)
+      return {} unless body.is_a?(Hash)
+      body.each_with_object({}) do |(date, stats), out|
+        out[date] = Forem::ForemObject.construct_from(stats || {}, requestor: requestor)
+      end
+    end
+    private_class_method :grouped_by_day
+  end
+end

data/lib/forem/resources/article.rb

@@ -0,0 +1,256 @@
+require "cgi"
+
+module Forem
+  # Represents a Forem article (blog post).
+  #
+  # Articles are the core content type on Forem. They support full CRUD
+  # operations plus several custom endpoints for filtering by auth state,
+  # latest publication order, and full-text search.
+  #
+  # Available operations (via mixins):
+  #   - +List+   — GET /api/articles
+  #   - +Create+ — POST /api/articles
+  #   - +Retrieve+ — GET /api/articles/:id
+  #   - +Update+ — PUT /api/articles/:id
+  #   - +Save+   — instance-level save (create or update)
+  #
+  # == List Parameters
+  #
+  # When calling +Article.list+, the following query parameters are supported:
+  #
+  # - +tag+ (String) — Filter by tag; can combine with +top+
+  # - +tags+ (String) — Comma-separated tags; returns articles with ANY of these
+  # - +tags_exclude+ (String) — Comma-separated tags to exclude
+  # - +username+ (String) — Filter by user or organization username
+  # - +state+ (String) — One of: +"fresh"+, +"rising"+, +"all"+.
+  #   Note: +state=all+ only works combined with +username+ and returns up to 1000 items
+  # - +top+ (Integer) — Most popular articles in the last N days; can combine with +tag+
+  # - +collection_id+ (Integer) — Articles in a specific collection, ordered by publication date
+  # - +page+ (Integer) — Page number (default: 1)
+  # - +per_page+ (Integer) — Items per page (default: 30, max: 1000)
+  #
+  # == Create Parameters
+  #
+  # When calling +Article.create+, wrap all fields under the +:article+ key:
+  #
+  # @option params [Hash] :article the article payload
+  # @option params [String] 'article.title' (required)
+  # @option params [String] 'article.body_markdown' (required)
+  # @option params [String] 'article.description' (required)
+  # @option params [Boolean] 'article.published' (default: false)
+  # @option params [String] 'article.tags' comma-separated tags
+  # @option params [String] 'article.series' series name (nullable)
+  # @option params [String] 'article.canonical_url' (nullable)
+  # @option params [String] 'article.main_image' (nullable)
+  # @option params [Integer] 'article.organization_id' (nullable)
+  #
+  # @example List published articles
+  #   articles = client.articles.list(per_page: 10, tag: "ruby")
+  #   articles.data.each { |a| puts a.title }
+  #
+  # @example Create a new article
+  #   article = client.articles.create(
+  #     article: { title: "Hello World", body_markdown: "# Hello", published: false }
+  #   )
+  #
+  # @example Retrieve a single article by ID
+  #   article = client.articles.retrieve(12345)
+  #   puts article.title
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getArticles
+  # @see https://developers.forem.com/api/v1#/operations/createArticle
+  # @see https://developers.forem.com/api/v1#/operations/updateArticle
+  class Article < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Save
+
+    OBJECT_NAME = "article"
+    RESOURCE_PATH = "/api/articles"
+
+    # Unpublish this article, reverting it to draft status.
+    #
+    # Marks the article as draft. Keeps content, deletes notifications,
+    # preserves comments. Requires admin or moderator role.
+    #
+    # Sends a PUT request to +/api/articles/:id/unpublish+.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   article = client.articles.retrieve(42)
+    #   article.unpublish
+    # @see https://developers.forem.com/api/v1#/operations/unpublishArticle
+    def unpublish(opts = {})
+      request(:put, "#{resource_url}/unpublish", {}, opts)
+    end
+
+    # Return articles authored by the authenticated user (all statuses).
+    #
+    # Requires authentication. Returns articles in reverse chronological order,
+    # 30 per page.
+    #
+    # Sends a GET request to +/api/articles/me+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of the
+    #   authenticated user's articles
+    # @example
+    #   my_articles = client.articles.me(per_page: 5)
+    #   my_articles.each { |a| puts "#{a.id}: #{a.title}" }
+    # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+    def self.me(params = {}, opts = {})
+      paginated_list("/api/articles/me", params, opts)
+    end
+
+    # Return published articles authored by the authenticated user.
+    #
+    # Requires authentication. Returns articles in reverse chronological order,
+    # 30 per page.
+    #
+    # Sends a GET request to +/api/articles/me/published+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of the
+    #   authenticated user's published articles
+    # @example
+    #   published = client.articles.me_published(per_page: 20)
+    #   published.each { |a| puts a.title }
+    # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+    def self.me_published(params = {}, opts = {})
+      paginated_list("/api/articles/me/published", params, opts)
+    end
+
+    # Return unpublished (draft) articles authored by the authenticated user.
+    #
+    # Requires authentication. Returns articles in reverse chronological order,
+    # 30 per page.
+    #
+    # Sends a GET request to +/api/articles/me/unpublished+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of the
+    #   authenticated user's unpublished articles
+    # @example
+    #   drafts = client.articles.me_unpublished
+    #   drafts.each { |a| puts "Draft: #{a.title}" }
+    # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+    def self.me_unpublished(params = {}, opts = {})
+      paginated_list("/api/articles/me/unpublished", params, opts)
+    end
+
+    # Return all articles authored by the authenticated user regardless of status.
+    #
+    # Requires authentication. Returns articles in reverse chronological order,
+    # 30 per page.
+    #
+    # Sends a GET request to +/api/articles/me/all+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of all
+    #   articles (published + drafts) for the authenticated user
+    # @example
+    #   all = client.articles.me_all
+    #   all.auto_paging_each { |a| puts a.title }
+    # @see https://developers.forem.com/api/v1#/operations/getUserArticles
+    def self.me_all(params = {}, opts = {})
+      paginated_list("/api/articles/me/all", params, opts)
+    end
+
+    # Return the most recently published articles ordered by publication date.
+    #
+    # Sends a GET request to +/api/articles/latest+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of latest
+    #   published articles
+    # @example
+    #   latest = client.articles.latest(per_page: 5)
+    #   latest.each { |a| puts "#{a.published_at}: #{a.title}" }
+    # @see https://developers.forem.com/api/v1#/operations/getLatestArticles
+    def self.latest(params = {}, opts = {})
+      paginated_list("/api/articles/latest", params, opts)
+    end
+
+    # Search published articles by keyword.
+    #
+    # Sends a GET request to +/api/articles/search+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :q search query string
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of articles
+    #   matching the search query
+    # @example
+    #   results = client.articles.search(q: "ruby on rails")
+    #   results.each { |a| puts a.title }
+    # @see https://developers.forem.com/api/v1
+    def self.search(params = {}, opts = {})
+      paginated_list("/api/articles/search", params, opts)
+    end
+
+    # Semantically search published articles using Forem's embeddings-based search.
+    #
+    # Unlike +search+ (keyword matching), this endpoint finds articles whose
+    # meaning is close to the query text, using vector similarity. Requires
+    # authentication.
+    #
+    # Sends a GET request to +/api/articles/semantic_search+.
+    #
+    # @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) used
+    #   to filter out weakly-related results
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of articles
+    #   matching the query, ordered by relevance. Each article additionally
+    #   exposes +distance+ (cosine distance) and +similarity+ (1 - distance)
+    #   attributes.
+    # @example
+    #   results = client.articles.semantic_search(q: "how to deploy rails apps")
+    #   results.each { |a| puts "#{a.title} (#{a.similarity})" }
+    # @see https://developers.forem.com/api/v1
+    def self.semantic_search(params = {}, opts = {})
+      paginated_list("/api/articles/semantic_search", params, opts)
+    end
+
+    # Retrieve a single article by the author's username and the article's slug.
+    #
+    # Sends a GET request to +/api/articles/:username/:slug+.
+    #
+    # @param username [String] the author's Forem username
+    # @param slug [String] the article slug (the URL-friendly title segment)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::Article] the matching article
+    # @example
+    #   article = client.articles.retrieve_by_path("ben", "my-first-post")
+    #   puts article.title
+    # @see https://developers.forem.com/api/v1#/operations/getArticleByPath
+    def self.retrieve_by_path(username, slug, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/articles/#{CGI.escape(username)}/#{CGI.escape(slug)}", {}, opts)
+      construct_from(resp.parsed_body, requestor: requestor)
+    end
+  end
+end

data/lib/forem/resources/billboard.rb

@@ -0,0 +1,76 @@
+module Forem
+  # Represents a Forem billboard (display advertisement).
+  #
+  # Billboards are configurable ad units shown to readers on a Forem instance.
+  # They support full CRUD operations plus an +unpublish+ action that reverts
+  # a live billboard back to draft status. Managing billboards requires an
+  # admin API key.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/billboards
+  #   - +Create+   — POST /api/billboards
+  #   - +Retrieve+ — GET /api/billboards/:id
+  #   - +Update+   — PUT /api/billboards/:id
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # == Billboard Fields
+  #
+  # - +name+ (String) — Internal name to distinguish ads
+  # - +body_markdown+ (String, required) — The ad content in markdown
+  # - +approved+ (Boolean) — Must be both published AND approved to appear in rotation
+  # - +published+ (Boolean) — Must be both published AND approved to appear in rotation
+  # - +expires_at+ (String) — ISO 8601 timestamp; automatically unapproved after this time
+  # - +placement_area+ (String) — Which area of the site layout the ad appears in
+  # - +tag_list+ (String) — Tags on which the ad can display (blank = all tags)
+  # - +exclude_article_ids+ (String) — Comma-separated Article IDs where ad should NOT appear
+  # - +audience_segment_id+ (Integer) — Target a specific audience segment
+  # - +audience_segment_type+ (String) — Must match +audience_segment_id+ if both provided
+  # - +target_geolocations+ (Array) — ISO 3166-2 country/region codes (blank = all locations)
+  # - +display_to+ (String) — Limits which visitors see the ad
+  # - +type_of+ (String) — One of: +"in_house"+ (admin-created), +"community"+ (entity content), +"external"+ (everywhere)
+  #
+  # @example List all billboards
+  #   billboards = client.billboards.list
+  #   billboards.data.each { |b| puts "#{b.id}: #{b.name}" }
+  #
+  # @example Create a billboard (flat params — there is no +billboard:+ wrapper)
+  #   billboard = client.billboards.create(
+  #     name: "Summer Sale",
+  #     body_markdown: "**50% off** all plans!",
+  #     placement_area: "sidebar_left"
+  #   )
+  #
+  # @example Retrieve a billboard by ID
+  #   billboard = client.billboards.retrieve(7)
+  #   puts billboard.name
+  #
+  # @see https://developers.forem.com/api/v1
+  class Billboard < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Save
+
+    OBJECT_NAME = "billboard"
+    RESOURCE_PATH = "/api/billboards"
+
+    # Unpublish this billboard, reverting it to draft/inactive status.
+    #
+    # Marks the billboard as unpublished. A billboard must be both published
+    # AND approved to appear in rotation.
+    #
+    # Sends a PUT request to +/api/billboards/:id/unpublish+.
+    # Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   billboard = client.billboards.retrieve(7)
+    #   billboard.unpublish
+    # @see https://developers.forem.com/api/v1
+    def unpublish(opts = {})
+      request(:put, "#{resource_url}/unpublish", {}, opts)
+    end
+  end
+end

data/lib/forem/resources/comment.rb

@@ -0,0 +1,43 @@
+module Forem
+  # Represents a comment on a Forem article or podcast episode.
+  #
+  # Comments are threaded replies attached to articles or podcast episodes.
+  # They can be listed (optionally filtered by the parent content item) or
+  # retrieved individually by ID.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/comments  (pass +:a_id+ or +:p_id+ to filter)
+  #   - +Retrieve+ — GET /api/comments/:id  (returns comment tree rooted at that ID)
+  #
+  # == List Parameters
+  #
+  # Comments must be filtered by either article or podcast episode:
+  # - +a_id+ (String) — Article identifier (required if +p_id+ not provided)
+  # - +p_id+ (String) — Podcast Episode identifier (required if +a_id+ not provided)
+  # - +page+ (Integer) — Page number
+  # - +per_page+ (Integer) — Items per page (default: 50)
+  #
+  # Returns threaded conversations with nested replies.
+  #
+  # @example List all comments for an article
+  #   comments = client.comments.list(a_id: "some-article-id")
+  #   comments.data.each { |c| puts c.body_html }
+  #
+  # @example List comments for a podcast episode
+  #   comments = client.comments.list(p_id: "some-podcast-id")
+  #   comments.data.each { |c| puts c.body_html }
+  #
+  # @example Retrieve a comment tree by root comment ID
+  #   comment = client.comments.retrieve("abc123")
+  #   puts comment.body_html
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getCommentsByArticleId
+  # @see https://developers.forem.com/api/v1#/operations/getCommentById
+  class Comment < APIResource
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+
+    OBJECT_NAME = "comment"
+    RESOURCE_PATH = "/api/comments"
+  end
+end