forem-ruby 0.1.0.beta1

data/lib/forem/services/base_service.rb

@@ -0,0 +1,45 @@
+module Forem
+  module Services
+    # Abstract base class for all Forem API service objects.
+    #
+    # Each service wraps a specific area of the Forem API and delegates method
+    # calls to the corresponding model class, automatically injecting the
+    # client's {APIRequestor} so that the correct credentials and base URL are
+    # used for every request.
+    #
+    # Concrete subclasses (e.g. {ArticleService}, {UserService}) are accessed
+    # through the reader methods on {Client} and should not be instantiated
+    # directly.
+    #
+    # @abstract Subclass and add public methods that delegate to the
+    #   appropriate model class.
+    #
+    # @see Client
+    # @see https://developers.forem.com/api/v1
+    class BaseService
+      # Create a new service instance bound to the given requestor.
+      #
+      # @param requestor [APIRequestor] the HTTP requestor that carries the
+      #   client's configuration (API key, base URL, etc.)
+      # @return [BaseService] a new service instance
+      def initialize(requestor)
+        @requestor = requestor
+      end
+
+      private
+
+      # Merge the client's requestor into a per-request options hash.
+      #
+      # All service methods call this helper before forwarding opts to model
+      # class methods so that the model uses this client's requestor rather
+      # than the global one.
+      #
+      # @param opts [Hash] per-request options supplied by the caller
+      # @return [Hash] opts with the +:requestor+ key set to this service's
+      #   {APIRequestor}
+      def opts_with_requestor(opts)
+        opts.merge(requestor: @requestor)
+      end
+    end
+  end
+end

data/lib/forem/services/billboard_service.rb

@@ -0,0 +1,91 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Billboards API.
+    #
+    # Billboards are display ads shown within Forem communities.
+    # Access via {Client#billboards}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   billboards = client.billboards.list
+    #   billboard  = client.billboards.retrieve(3)
+    #
+    # @see Billboard
+    # @see https://developers.forem.com/api/v1
+    class BillboardService < BaseService
+      # List all billboards (display ads).
+      #
+      # @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<Billboard>] list of billboards
+      #
+      # @example
+      #   client.billboards.list
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Billboard.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new billboard.
+      #
+      # @param params [Hash] billboard attributes
+      # @option params [String] :name internal name for the billboard
+      # @option params [String] :body_markdown ad body in Markdown / HTML
+      # @option params [String] :placement_area where to display the billboard
+      # @option params [Boolean] :published whether the billboard is live
+      # @option params [Integer] :organization_id organization this billboard
+      #   belongs to
+      # @param opts [Hash] per-request options
+      # @return [Billboard] the newly created billboard
+      #
+      # @example
+      #   client.billboards.create(
+      #     name: "Summer Promo",
+      #     body_markdown: "## Sale!\nUp to 50% off.",
+      #     placement_area: "sidebar_left",
+      #     published: true
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        Billboard.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single billboard by its numeric ID.
+      #
+      # @param id [Integer, String] the billboard ID
+      # @param opts [Hash] per-request options
+      # @return [Billboard] the billboard with the given ID
+      #
+      # @example
+      #   client.billboards.retrieve(3)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        Billboard.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Update an existing billboard.
+      #
+      # @param id [Integer, String] the billboard ID to update
+      # @param params [Hash] billboard attributes to change
+      # @option params [String] :name new internal name
+      # @option params [String] :body_markdown new body content
+      # @option params [Boolean] :published publish or unpublish the billboard
+      # @param opts [Hash] per-request options
+      # @return [Billboard] the updated billboard
+      #
+      # @example
+      #   client.billboards.update(3, published: false)
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        Billboard.update(id, params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/comment_service.rb

@@ -0,0 +1,51 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Comments API.
+    #
+    # Access via {Client#comments}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   comments = client.comments.list(a_id: 12345)
+    #   comment  = client.comments.retrieve("abc123")
+    #
+    # @see Comment
+    # @see https://developers.forem.com/api/v1#/operations/getCommentsByArticleId
+    class CommentService < BaseService
+      # List comments for an article or podcast episode.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :a_id article ID to fetch comments for
+      # @option params [Integer] :p_id podcast episode ID to fetch comments for
+      # @param opts [Hash] per-request options
+      # @return [Array<Comment>] top-level comments (with nested replies)
+      #
+      # @example Fetch comments for an article
+      #   client.comments.list(a_id: 12345)
+      #
+      # @example Fetch comments for a podcast episode
+      #   client.comments.list(p_id: 67)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getCommentsByArticleId
+      def list(params = {}, opts = {})
+        Comment.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single comment by its ID.
+      #
+      # @param id [String] the comment ID (alphanumeric string as returned by
+      #   the API)
+      # @param opts [Hash] per-request options
+      # @return [Comment] the comment with the given ID
+      #
+      # @example
+      #   client.comments.retrieve("abc123")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getCommentById
+      def retrieve(id, opts = {})
+        Comment.retrieve(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/concept_service.rb

@@ -0,0 +1,143 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Concepts API.
+    #
+    # Concepts are semantic, ML-generated categories: articles are classified
+    # under a concept when their embedding is close enough to the concept's
+    # anchor embedding. This service covers the public concept endpoints
+    # (+/api/concepts+); creating and deleting concepts is an admin-only
+    # operation exposed by {AdminConceptService}.
+    #
+    # Access via {Client#concepts}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   concepts = client.concepts.list(days: 30)
+    #   concept  = client.concepts.retrieve(concepts.first.id)
+    #   concept.daily_metrics.first.articles_count
+    #
+    # @see Concept
+    # @see https://developers.forem.com/api/v1
+    class ConceptService < BaseService
+      # List the concepts accessible to the authenticated user.
+      #
+      # Super admins see every concept; other users see only the concepts
+      # they have been granted access to. Each concept includes nested
+      # +daily_metrics+ covering the last +days+ days, newest 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, max: 100)
+      # @option params [Integer] :days number of days of activity to include
+      #   in +daily_metrics+ (default: 7, minimum: 1)
+      # @param opts [Hash] per-request options
+      # @return [Forem::ListObject<Concept>] paginated list of concepts
+      #
+      # @example
+      #   client.concepts.list(per_page: 20, days: 30)
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Concept.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single concept by its numeric ID.
+      #
+      # The response includes nested +daily_metrics+ for the last +days+ days
+      # and a +top_articles+ array with the concept's three highest-scoring
+      # articles.
+      #
+      # @param id [Integer, String] the concept ID
+      # @param params [Hash] query parameters
+      # @option params [Integer] :days number of days of activity to include
+      #   in +daily_metrics+ (default: 7, minimum: 1)
+      # @param opts [Hash] per-request options
+      # @return [Concept] the concept with the given ID
+      #
+      # @example
+      #   concept = client.concepts.retrieve(7)
+      #   concept.daily_metrics.map(&:popularity_score)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, params = {}, opts = {})
+        Concept.retrieve(id, params, opts_with_requestor(opts))
+      end
+
+      # Update an existing concept.
+      #
+      # Params are wrapped in the +concept+ key expected by the API, so they
+      # can be passed flat. Only +score+, +description+, and
+      # +similarity_threshold+ are permitted. Updating the description
+      # regenerates the concept's anchor embedding; updating the description
+      # or the similarity threshold re-classifies existing articles in the
+      # background.
+      #
+      # @param id [Integer, String] the concept ID to update
+      # @param params [Hash] concept attributes to change
+      # @option params [Float] :score new curation score
+      # @option params [String] :description new semantic description used to
+      #   regenerate the anchor embedding
+      # @option params [Float] :similarity_threshold new cosine distance
+      #   threshold (0.0–1.0)
+      # @param opts [Hash] per-request options
+      # @return [Concept] the updated concept
+      #
+      # @example
+      #   client.concepts.update(7, description: "Storage engines", score: 4.5)
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        Concept.update(id, params, opts_with_requestor(opts))
+      end
+
+      # List the published articles classified under a concept.
+      #
+      # Articles are ordered by semantic distance (closest first) with the
+      # article score as a tiebreaker, unless +sort+ is +"score"+.
+      #
+      # @param id [Integer, String] the concept ID
+      # @param params [Hash] query parameters
+      # @option params [String] :sort +"score"+ to sort by article score;
+      #   otherwise sorted by semantic distance
+      # @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<Forem::Article>] paginated list of articles
+      #
+      # @example
+      #   client.concepts.articles(7, sort: "score", per_page: 25)
+      #
+      # @see https://developers.forem.com/api/v1
+      def articles(id, params = {}, opts = {})
+        Concept.articles(id, params, opts_with_requestor(opts))
+      end
+
+      # Semantically search the concepts accessible to the caller.
+      #
+      # The query is embedded and compared against each concept's anchor
+      # embedding. Results come back closest-first, each with +distance+ and
+      # +similarity+ alongside the usual concept fields. This endpoint
+      # requires an API key and is not paginated.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :q (required) the search text
+      # @option params [Integer] :per_page number of concepts to return
+      #   (default: 10, max: 50)
+      # @option params [Float] :threshold optional maximum cosine distance
+      #   (0.0–2.0) for a concept to be included
+      # @param opts [Hash] per-request options
+      # @return [Array<Concept>] matching concepts, closest first
+      #
+      # @example
+      #   client.concepts.search(q: "vector databases", per_page: 5)
+      #
+      # @see https://developers.forem.com/api/v1
+      def search(params = {}, opts = {})
+        Concept.search(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/follow_service.rb

@@ -0,0 +1,61 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Follows API.
+    #
+    # Lists the tags the authenticated user follows, and follows users or
+    # organizations in bulk.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   followed_tags = client.follows.list
+    #   client.follows.create(user_ids: [42, 99])
+    #
+    # @see Follow
+    # @see https://developers.forem.com/api/v1#/operations/getFollowedTags
+    class FollowService < BaseService
+      # List tags followed 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
+      # @param opts [Hash] per-request options
+      # @return [Forem::ListObject<Forem::Follow>] paginated list of
+      #   followed tags for the current user.
+      #
+      # @example
+      #   client.follows.list
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getFollowedTags
+      def list(params = {}, opts = {})
+        Follow.list(params, opts_with_requestor(opts))
+      end
+
+      # Follow one or more users and/or organizations.
+      #
+      # The Forem API takes flat +user_ids+ and/or +organization_ids+
+      # arrays — not a wrapped +follows:+ key, despite the resource name.
+      # Tags are not followed through this endpoint.
+      #
+      # @param params [Hash] follow attributes
+      # @option params [Array<Integer>] :user_ids user IDs to follow
+      # @option params [Array<Integer>] :organization_ids org IDs to follow
+      # @param opts [Hash] per-request options
+      # @return [Forem::Follow] outcome object (e.g.
+      #   <tt>#<Forem::Follow {"outcome" => "followed 2 users"}></tt>).
+      #
+      # @example Follow users in bulk
+      #   client.follows.create(user_ids: [42, 99])
+      #
+      # @example Follow organizations
+      #   client.follows.create(organization_ids: [7])
+      #
+      # @example Combined
+      #   client.follows.create(user_ids: [42], organization_ids: [7])
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        Follow.create(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/follower_service.rb

@@ -0,0 +1,34 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Followers API.
+    #
+    # Lists the users who follow the authenticated user.
+    # Access via {Client#followers}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   followers = client.followers.list(per_page: 50)
+    #
+    # @see Follower
+    # @see https://developers.forem.com/api/v1#/operations/getFollowers
+    class FollowerService < BaseService
+      # List users who follow 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)
+      # @option params [String] :sort sort order ("created_at" for most recent first)
+      # @param opts [Hash] per-request options
+      # @return [Array<Follower>] list of followers for the authenticated user
+      #
+      # @example
+      #   client.followers.list(per_page: 100, sort: "created_at")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getFollowers
+      def list(params = {}, opts = {})
+        Follower.list(params, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/health_check_service.rb

@@ -0,0 +1,46 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Health Check API.
+    #
+    # In production these endpoints require the +health-check-token+
+    # header — pass +token:+ to each call. On localhost the token is
+    # bypassed by Forem core, so a local development instance accepts
+    # unauthenticated calls.
+    #
+    # @example Production
+    #   client.health_checks.app(token: ENV["FOREM_HEALTH_CHECK_TOKEN"])
+    #
+    # @example Local development (token not required for localhost)
+    #   client.health_checks.app
+    #
+    # @see HealthCheck
+    # @see https://developers.forem.com/api/v1
+    class HealthCheckService < BaseService
+      # Application-server health.
+      # @param token [String, nil] value for the +health-check-token+ header
+      #   (required in production; bypassed on localhost).
+      # @param opts [Hash] per-request options
+      # @return [Forem::ForemObject] response body, e.g.
+      #   <tt>{"message" => "App is up!"}</tt>
+      def app(token: nil, **opts)
+        HealthCheck.app(token: token, **opts_with_requestor(opts))
+      end
+
+      # Database connectivity & responsiveness.
+      # @param token [String, nil] value for the +health-check-token+ header.
+      # @param opts [Hash] per-request options
+      # @return [Forem::ForemObject]
+      def database(token: nil, **opts)
+        HealthCheck.database(token: token, **opts_with_requestor(opts))
+      end
+
+      # Cache (Redis) connectivity & responsiveness.
+      # @param token [String, nil] value for the +health-check-token+ header.
+      # @param opts [Hash] per-request options
+      # @return [Forem::ForemObject]
+      def cache(token: nil, **opts)
+        HealthCheck.cache(token: token, **opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/organization_service.rb

@@ -0,0 +1,103 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Organizations API.
+    #
+    # Access via {Client#organizations}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   orgs = client.organizations.list
+    #   org  = client.organizations.retrieve(7)
+    #
+    # @see Organization
+    # @see https://developers.forem.com/api/v1#/operations/getOrganizations
+    class OrganizationService < BaseService
+      # List all organizations.
+      #
+      # @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<Organization>] list of organizations
+      #
+      # @example
+      #   client.organizations.list(per_page: 25)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getOrganizations
+      def list(params = {}, opts = {})
+        Organization.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new organization.
+      #
+      # @param params [Hash] organization attributes
+      # @option params [String] :name display name of the organization
+      # @option params [String] :username unique username / slug
+      # @option params [String] :summary short description
+      # @option params [String] :url website URL
+      # @option params [String] :location location string
+      # @option params [String] :tech_stack technology stack description
+      # @param opts [Hash] per-request options
+      # @return [Organization] the newly created organization
+      #
+      # @example
+      #   client.organizations.create(
+      #     name: "Acme Corp",
+      #     username: "acme",
+      #     summary: "We make everything."
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1#/operations/createOrganization
+      def create(params = {}, opts = {})
+        Organization.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single organization by its numeric ID.
+      #
+      # @param id [Integer, String] the organization ID
+      # @param opts [Hash] per-request options
+      # @return [Organization] the organization with the given ID
+      #
+      # @example
+      #   client.organizations.retrieve(7)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/getOrganizationById
+      def retrieve(id, opts = {})
+        Organization.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Update an existing organization.
+      #
+      # @param id [Integer, String] the organization ID to update
+      # @param params [Hash] organization attributes to change
+      # @option params [String] :name new display name
+      # @option params [String] :summary new description
+      # @option params [String] :url new website URL
+      # @param opts [Hash] per-request options
+      # @return [Organization] the updated organization
+      #
+      # @example
+      #   client.organizations.update(7, summary: "Updated description.")
+      #
+      # @see https://developers.forem.com/api/v1#/operations/updateOrganization
+      def update(id, params = {}, opts = {})
+        Organization.update(id, params, opts_with_requestor(opts))
+      end
+
+      # Delete an organization.
+      #
+      # @param id [Integer, String] the organization ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success
+      #
+      # @example
+      #   client.organizations.delete(7)
+      #
+      # @see https://developers.forem.com/api/v1#/operations/deleteOrganization
+      def delete(id, opts = {})
+        Organization.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/page_service.rb

@@ -0,0 +1,107 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Pages API.
+    #
+    # Pages are static landing pages within a Forem community.
+    # Access via {Client#pages}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   pages = client.pages.list
+    #   page  = client.pages.retrieve(10)
+    #
+    # @see Page
+    # @see https://developers.forem.com/api/v1
+    class PageService < BaseService
+      # List all static pages.
+      #
+      # @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<Page>] list of static pages
+      #
+      # @example
+      #   client.pages.list
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Page.list(params, opts_with_requestor(opts))
+      end
+
+      # Create a new static page.
+      #
+      # @param params [Hash] page attributes
+      # @option params [String] :title page title
+      # @option params [String] :slug URL slug (must be unique)
+      # @option params [String] :body_markdown page body in Markdown
+      # @option params [String] :body_html page body in HTML (alternative to
+      #   Markdown)
+      # @option params [Boolean] :is_top_level_path whether the page is
+      #   accessible at the root path
+      # @option params [String] :description short description / meta tag
+      # @option params [String] :template page template name
+      # @param opts [Hash] per-request options
+      # @return [Page] the newly created page
+      #
+      # @example
+      #   client.pages.create(
+      #     title: "About Us",
+      #     slug: "about",
+      #     body_markdown: "## About\nWe are a community of developers."
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        Page.create(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single static page by its numeric ID.
+      #
+      # @param id [Integer, String] the page ID
+      # @param opts [Hash] per-request options
+      # @return [Page] the page with the given ID
+      #
+      # @example
+      #   client.pages.retrieve(10)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        Page.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Update an existing static page.
+      #
+      # @param id [Integer, String] the page ID to update
+      # @param params [Hash] page attributes to change
+      # @option params [String] :title new page title
+      # @option params [String] :body_markdown new body in Markdown
+      # @option params [String] :description new description
+      # @param opts [Hash] per-request options
+      # @return [Page] the updated page
+      #
+      # @example
+      #   client.pages.update(10, title: "About Our Community")
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        Page.update(id, params, opts_with_requestor(opts))
+      end
+
+      # Delete a static page.
+      #
+      # @param id [Integer, String] the page ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success
+      #
+      # @example
+      #   client.pages.delete(10)
+      #
+      # @see https://developers.forem.com/api/v1
+      def delete(id, opts = {})
+        Page.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end