forem-ruby 0.1.0.beta1

data/lib/forem/list_object.rb

@@ -0,0 +1,171 @@
+module Forem
+  # Wraps a paginated list of API resources returned by collection endpoints.
+  #
+  # {ListObject} implements +Enumerable+ so the current page's items can be
+  # iterated with the standard Ruby collection methods. Use
+  # {#auto_paging_each} to transparently iterate across all pages without
+  # managing pagination manually.
+  #
+  # Two paging modes are supported:
+  #
+  # * *page-based* (default) — uses +page+/+per_page+ query params. Created
+  #   by {APIOperations::List#list} and the +paginated_list+ helper on
+  #   {APIResource}.
+  # * *cursor-based* — uses an +after+-style cursor (e.g. survey poll
+  #   endpoints). Created by the +cursor_list+ helper on {APIResource}.
+  #
+  # In both modes the public surface is the same: {#data}, {#has_more?},
+  # {#each}, {#next_page}, {#auto_paging_each}.
+  #
+  # @example Iterating the current page
+  #   articles = client.articles.list(per_page: 5)
+  #   articles.each { |a| puts a.title }
+  #
+  # @example Iterating all pages automatically
+  #   client.articles.list(per_page: 30).auto_paging_each do |article|
+  #     puts article.title
+  #   end
+  class ListObject
+    include Enumerable
+
+    # @return [Array<ForemObject>] the resource objects on the current page.
+    attr_reader :data
+
+    # @return [Integer, nil] the 1-based current page number for page-based
+    #   pagination, or +nil+ for cursor-based pagination.
+    attr_reader :current_page
+
+    # @return [Integer] the maximum number of items per page requested.
+    attr_reader :per_page
+
+    # @return [Hash] the non-pagination filter parameters used to build this
+    #   list (e.g. +{ tag: "ruby" }+). These are forwarded when fetching
+    #   subsequent pages.
+    attr_reader :filters
+
+    # @return [Class] the resource class used to construct items.
+    attr_reader :resource_class
+
+    # @return [APIRequestor, nil] the requestor that produced this list and
+    #   that will be re-used for fetching additional pages.
+    attr_reader :requestor
+
+    # Create a new ListObject.
+    #
+    # @param data [Array<ForemObject>] the resource objects for this page.
+    # @param per_page [Integer] the page size requested.
+    # @param resource_class [Class] the resource class for this collection.
+    # @param filters [Hash] the non-pagination query parameters.
+    # @param requestor [APIRequestor, nil] the requestor used to fetch the
+    #   current page; reused for subsequent pages.
+    # @param current_page [Integer, nil] the 1-based current page number, or
+    #   +nil+ for cursor-based pagination.
+    # @param fetcher [Proc, nil] optional callable invoked with
+    #   <tt>(direction, current_list, extra_params)</tt> to fetch the next or
+    #   previous page. Used by custom-path or cursor-based endpoints. When
+    #   +nil+, page-based pagination falls back to
+    #   <tt>resource_class.list(...)</tt>.
+    # @return [ListObject]
+    def initialize(data:, per_page:, resource_class:, filters:, requestor:, current_page: nil, fetcher: nil)
+      @data = data
+      @current_page = current_page
+      @per_page = per_page
+      @resource_class = resource_class
+      @filters = filters
+      @requestor = requestor
+      @fetcher = fetcher
+    end
+
+    # Return whether more pages of results may exist after this one.
+    #
+    # Inferred by checking whether the current page returned exactly
+    # {#per_page} items.
+    #
+    # @return [Boolean]
+    def has_more?
+      @data.length == @per_page && @data.length > 0
+    end
+
+    # Iterate over the resource objects on the current page.
+    #
+    # @yield [ForemObject] each resource object on the current page.
+    # @return [Enumerator] if no block is given.
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # Indexed access to the underlying page data.
+    # @param idx [Integer] zero-based item index within the current page.
+    # @return [ForemObject, nil]
+    def [](idx)
+      @data[idx]
+    end
+
+    # @return [Integer] the number of items on the current page.
+    def length
+      @data.length
+    end
+    alias_method :size, :length
+
+    # @return [Boolean] whether the current page contains zero items.
+    def empty?
+      @data.empty?
+    end
+
+    # Iterate over every resource across all pages, automatically fetching
+    # subsequent pages as needed. Stops when {#has_more?} is false or
+    # {#next_page} returns +nil+.
+    #
+    # @yield [ForemObject] each resource object across all pages.
+    # @return [void]
+    def auto_paging_each(&block)
+      page = self
+      loop do
+        page.each(&block)
+        break unless page.has_more?
+        page = page.next_page
+        break unless page
+      end
+    end
+
+    # Fetch the next page of results.
+    #
+    # Returns +nil+ when {#has_more?} is +false+ or when the fetcher signals
+    # there is no further page.
+    #
+    # @param params [Hash] additional parameters merged on top of {#filters}.
+    # @return [ListObject, nil]
+    def next_page(params = {})
+      return nil unless has_more?
+      if @fetcher
+        @fetcher.call(:next, self, params)
+      else
+        fetch_page(@current_page + 1, params)
+      end
+    end
+
+    # Fetch the previous page of results.
+    #
+    # Page-based: returns +nil+ when already on page 1.
+    # Cursor-based: returns +nil+ (cursor pagination is forward-only).
+    #
+    # @param params [Hash] additional parameters merged on top of {#filters}.
+    # @return [ListObject, nil]
+    def previous_page(params = {})
+      if @fetcher
+        @fetcher.call(:previous, self, params)
+      else
+        return nil if @current_page.nil? || @current_page <= 1
+        fetch_page(@current_page - 1, params)
+      end
+    end
+
+    private
+
+    def fetch_page(page_num, extra_params = {})
+      params = @filters.merge(page: page_num, per_page: @per_page).merge(extra_params)
+      opts = @requestor ? { requestor: @requestor } : {}
+      @resource_class.list(params, opts)
+    end
+  end
+end

data/lib/forem/resources/admin_concept.rb

@@ -0,0 +1,169 @@
+module Forem
+  # Represents a Concept managed through the admin-only Concepts API.
+  #
+  # Concepts are curated topics that Forem uses to classify articles and
+  # comments via embedding similarity. The admin endpoints under
+  # +/api/admin/concepts+ expose full CRUD over those records plus a
+  # +trigger_lookback+ action that re-runs classification over older content.
+  # Every endpoint requires an API key belonging to a super admin — a regular
+  # user key receives HTTP 401.
+  #
+  # Read-only access to the public concept endpoints lives on
+  # {Forem::Concept}; this resource is strictly the administrative surface.
+  #
+  # Available operations:
+  #   - +List+             — GET /api/admin/concepts
+  #   - +Retrieve+         — GET /api/admin/concepts/:id
+  #   - +create+           — POST /api/admin/concepts
+  #   - +update+           — PUT /api/admin/concepts/:id
+  #   - +Delete+           — DELETE /api/admin/concepts/:id
+  #   - +trigger_lookback+ — POST /api/admin/concepts/:id/trigger_lookback
+  #
+  # == Concept Fields
+  #
+  # - +id+ (Integer) — Unique identifier
+  # - +name+ (String, required) — Display name, max 100 characters
+  # - +slug+ (String) — Generated from +name+ by the API; not writable
+  # - +description+ (String) — Generated from +name+ when omitted on create
+  # - +parent_id+ (Integer) — Optional parent concept, forming a hierarchy
+  # - +similarity_threshold+ (Float) — Cosine similarity cutoff between +0.0+
+  #   and +1.0+ used when classifying records (may be +null+)
+  # - +score+ (Float) — Ranking score for the concept
+  # - +max_lookback_days+ (Integer) — How far back classification has already
+  #   been run; read-only (set by +trigger_lookback+, never by create/update)
+  # - +created_at+ / +updated_at+ (String) — ISO 8601 timestamps
+  #
+  # The list endpoint returns a trimmed projection (+id+, +name+, +slug+,
+  # +description+, +parent_id+, +similarity_threshold+, +max_lookback_days+,
+  # +created_at+, +updated_at+) ordered by +name+, while the show endpoint
+  # returns the full record.
+  #
+  # == Writable attributes
+  #
+  # Only +name+, +description+, +parent_id+, +similarity_threshold+, and
+  # +score+ are permitted on create and update. Any other attribute (notably
+  # +slug+ and +max_lookback_days+) is silently ignored by the API. Attributes
+  # are sent wrapped in a +concept+ object, which this resource does for you.
+  #
+  # @example List concepts
+  #   concepts = client.admin_concepts.list(per_page: 100)
+  #   concepts.each { |c| puts "#{c.id}: #{c.name}" }
+  #
+  # @example Create a concept (flat params — the +concept:+ wrapper is added)
+  #   concept = client.admin_concepts.create(
+  #     name: "Machine Learning",
+  #     description: "Posts about ML and AI",
+  #     similarity_threshold: 0.8
+  #   )
+  #
+  # @see Forem::Concept
+  # @see https://developers.forem.com/api/v1
+  class AdminConcept < APIResource
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    include APIOperations::Delete
+
+    OBJECT_NAME = "admin_concept"
+    RESOURCE_PATH = "/api/admin/concepts"
+
+    # Create a new concept.
+    #
+    # Sends a +POST+ to +/api/admin/concepts+ with the attributes wrapped in a
+    # +concept+ object. The API generates the slug, and generates the
+    # description and anchor embedding from +name+ before saving, so creation
+    # only requires a name.
+    #
+    # @param params [Hash] concept attributes, either flat or already wrapped
+    #   in +:concept+.
+    # @option params [String] :name (required) the concept name (max 100 chars)
+    # @option params [String] :description human-readable description
+    # @option params [Integer] :parent_id ID of the parent concept
+    # @option params [Float] :similarity_threshold cutoff between 0.0 and 1.0
+    # @option params [Float] :score ranking score for the concept
+    # @param opts [Hash] per-request options.
+    # @option opts [String] :api_key override the API key for this request.
+    # @option opts [APIRequestor] :requestor a custom requestor to use.
+    # @return [AdminConcept] the created concept (HTTP 201).
+    # @raise [InvalidRequestError] on HTTP 422 (validation errors).
+    def self.create(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:post, resource_path, wrap_params(params), opts)
+      construct_from(resp.parsed_body, requestor: requestor)
+    end
+
+    # Update an existing concept.
+    #
+    # Sends a +PUT+ to +/api/admin/concepts/:id+ with the attributes wrapped
+    # in a +concept+ object. Changing +name+ or +description+ causes the API
+    # to regenerate the concept's anchor embedding.
+    #
+    # @param id [Integer, String] the concept ID.
+    # @param params [Hash] attributes to change, either flat or already
+    #   wrapped in +:concept+. Same permitted keys as {.create}.
+    # @param opts [Hash] per-request options.
+    # @return [AdminConcept] the updated concept.
+    # @raise [NotFoundError] on HTTP 404.
+    # @raise [InvalidRequestError] on HTTP 422 (validation errors).
+    def self.update(id, params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:put, "#{resource_path}/#{id}", wrap_params(params), opts)
+      construct_from(resp.parsed_body, requestor: requestor)
+    end
+
+    # Queue a classification lookback for a concept.
+    #
+    # Sends a +POST+ to +/api/admin/concepts/:id/trigger_lookback+, enqueueing
+    # a background job that classifies records published within the last
+    # +days+ days. The requested +days+ 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 (required) how many days back to classify.
+    # @param opts [Hash] per-request options.
+    # @return [ForemObject] an object carrying a +message+ describing the
+    #   queued lookback.
+    # @raise [InvalidRequestError] on HTTP 422 when +days+ is not greater than
+    #   both zero and the concept's +max_lookback_days+.
+    #
+    # @example
+    #   client.admin_concepts.trigger_lookback(7, days: 40).message
+    def self.trigger_lookback(id, params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:post, "#{resource_path}/#{id}/trigger_lookback", params, opts)
+      ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    end
+
+    # Wrap flat attributes in the +concept+ object the API expects.
+    #
+    # Params that already carry a +:concept+ (or +"concept"+) key are passed
+    # through untouched.
+    #
+    # @param params [Hash] the caller-supplied attributes.
+    # @return [Hash] params wrapped in +concept+.
+    def self.wrap_params(params)
+      return params if params.key?(:concept) || params.key?("concept")
+
+      { concept: params }
+    end
+    private_class_method :wrap_params
+
+    # Queue a classification lookback for this concept instance.
+    #
+    # @param days [Integer] how many days back to classify. Must be positive
+    #   and greater than this concept's +max_lookback_days+.
+    # @param opts [Hash] per-request options.
+    # @return [ForemObject] an object carrying a +message+.
+    # @raise [InvalidRequestError] if the instance has no +id+, or on HTTP 422.
+    #
+    # @example
+    #   concept = client.admin_concepts.retrieve(7)
+    #   concept.trigger_lookback(90)
+    def trigger_lookback(days, opts = {})
+      requestor = opts[:requestor] || @requestor
+      resp = request(:post, "#{resource_url}/trigger_lookback", { days: days }, opts)
+      ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    end
+  end
+end

data/lib/forem/resources/admin_user.rb

@@ -0,0 +1,152 @@
+module Forem
+  # Provides admin-level user creation and synchronization for a Forem
+  # instance.
+  #
+  # Requires super_admin privileges. Sends an invitation email to the
+  # provided email address.
+  #
+  # AdminUser exposes the privileged user-creation endpoint under
+  # +/api/admin/users+ (postAdminUsersCreate). Unlike the regular User
+  # resource, this resource is scoped to admin operations and requires an
+  # admin API key to use. General retrieval and moderation of existing users
+  # remains on {Forem::User}; identity and notification synchronization lives
+  # here.
+  #
+  # Available operations (via mixins):
+  #   - +Create+ — POST /api/admin/users
+  #   - +link_identity+ — POST /api/admin/users/:user_id/identities
+  #   - +bulk_link_identities+ — POST /api/admin/users/identities/bulk
+  #   - +identities+ — GET /api/admin/users/:user_id/identities
+  #   - +unlink_identity+ — DELETE /api/admin/users/:user_id/identities/:id
+  #   - +update_notification_settings+ — PUT notification settings for a user
+  #
+  # @!method self.create(params = {}, opts = {})
+  #   Invite a new user by email (postAdminUsersCreate).
+  #
+  #   Requires super_admin privileges. Sends an invitation email to the
+  #   provided email address. The endpoint takes flat params — there is
+  #   no +user:+ wrapper.
+  #
+  #   The Forem API generates the username from the email address, so
+  #   passing +:username+ has no effect. Optional invite-customization
+  #   parameters are also accepted: +:custom_invite_subject+,
+  #   +:custom_invite_message+, +:custom_invite_footnote+.
+  #
+  #   The response body is intentionally empty (HTTP 200) — there is no
+  #   created-user record returned.
+  #
+  #   @param params [Hash] request body
+  #   @option params [String] :email (required) the email address to invite
+  #   @option params [String] :name the user's display name
+  #   @option params [String] :custom_invite_subject override the invite subject line
+  #   @option params [String] :custom_invite_message override the invite body
+  #   @option params [String] :custom_invite_footnote override the invite footer
+  #   @param opts [Hash] per-request options
+  #   @return [Forem::AdminUser] an empty record (the API returns no body)
+  #
+  # @example Create a new user as an admin (flat params)
+  #   client.admin_users.create(
+  #     email: "alice@example.com",
+  #     name: "Alice Example"
+  #   )
+  #
+  # @see Forem::User
+  # @see https://developers.forem.com/api/v1
+  class AdminUser < APIResource
+    extend APIOperations::Create
+
+    OBJECT_NAME = "admin_user"
+    RESOURCE_PATH = "/api/admin/users"
+
+    # Link an external provider 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 self.link_identity(user_id, provider:, uid:, **opts)
+      requestor = opts[:requestor]
+      resp = request(
+        :post,
+        "#{resource_path}/#{user_id}/identities",
+        { provider: provider, uid: uid },
+        opts
+      )
+      ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    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 self.bulk_link_identities(provider:, identities:, **opts)
+      requestor = opts[:requestor]
+      resp = request(
+        :post,
+        "#{resource_path}/identities/bulk",
+        { provider: provider, identities: identities },
+        opts
+      )
+      results = resp.parsed_body["results"] || []
+      results.map do |result|
+        ForemObject.construct_from(result, requestor: requestor)
+      end
+    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 self.identities(user_id, **opts)
+      requestor = opts[:requestor]
+      resp = request(:get, "#{resource_path}/#{user_id}/identities", {}, opts)
+      identities = resp.parsed_body["identities"] || []
+      identities.map do |identity|
+        ForemObject.construct_from(identity, requestor: requestor)
+      end
+    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 when returned by the
+    #   API, otherwise +nil+ for an empty response.
+    def self.unlink_identity(user_id, identity_id, **opts)
+      requestor = opts[:requestor]
+      resp = request(
+        :delete,
+        "#{resource_path}/#{user_id}/identities/#{identity_id}",
+        {},
+        opts
+      )
+      return nil unless resp.parsed_body
+
+      ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    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 self.update_notification_settings(user_id, email_newsletter:, **opts)
+      requestor = opts[:requestor]
+      resp = request(
+        :put,
+        "#{resource_path}/#{user_id}/notification_settings",
+        { notification_setting: { email_newsletter: email_newsletter } },
+        opts
+      )
+      ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    end
+  end
+end

data/lib/forem/resources/agent_session.rb

@@ -0,0 +1,110 @@
+module Forem
+  # Represents an agent session used for AI-assisted content workflows on Forem.
+  #
+  # Agent sessions are coding conversation transcripts from CLI tools like
+  # Claude Code and other AI coding assistants.
+  #
+  # A presign step generates upload credentials before session data is
+  # submitted. After creation, the raw asset URL for the session can be
+  # retrieved via the +raw_url+ instance method.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/agent_sessions     (getAgentSessions)
+  #   - +Create+   — POST /api/agent_sessions    (createAgentSession)
+  #   - +Retrieve+ — GET /api/agent_sessions/:id (getAgentSessionById)
+  #
+  # == AgentSession Fields
+  #
+  # - +id+ (Integer)
+  # - +slug+ (String) — URL-friendly identifier
+  # - +title+ (String)
+  # - +tool_name+ (String) — Tool that produced the session
+  # - +total_messages+ (Integer)
+  # - +published+ (Boolean)
+  # - +url+ (String) — Public URL for the session
+  #
+  # @example Get presigned upload credentials before creating a session
+  #   presign = client.agent_sessions.presign(filename: "session.json", mime_type: "application/json")
+  #   puts presign.presigned_url
+  #
+  # @example Create a new agent session (flat params — no +agent_session:+ wrapper)
+  #   session = client.agent_sessions.create(
+  #     title: "My Session",
+  #     curated_data: curated_json,
+  #     tool_name: "claude_code"
+  #   )
+  #
+  # @example Retrieve the raw asset URL for an existing session
+  #   session = client.agent_sessions.retrieve(99)
+  #   puts session.raw_url.raw_url
+  #
+  # @see https://developers.forem.com/api/v1
+  class AgentSession < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+
+    OBJECT_NAME = "agent_session"
+    RESOURCE_PATH = "/api/agent_sessions"
+
+    # @!method self.create(params = {}, opts = {})
+    #   Create a new agent session (createAgentSession).
+    #
+    #   Sends a POST request to +/api/agent_sessions+.
+    #
+    #   @param params [Hash] request body
+    #   @option params [String] :title Title for the session (auto-generated if omitted)
+    #   @option params [String] :curated_data JSON string of curated session data with messages array and metadata
+    #   @option params [String] :s3_key S3 key for raw file (from presign endpoint)
+    #   @option params [String] :tool_name One of: +"claude_code"+, +"codex"+, +"gemini_cli"+, +"github_copilot"+, +"pi"+
+    #   @param opts [Hash] per-request options (e.g., +:api_key+)
+    #   @return [Forem::AgentSession] the newly-created session
+
+    # @!method self.retrieve(id, opts = {})
+    #   Retrieve an agent session by ID or slug (getAgentSessionById).
+    #
+    #   The +id+ parameter can be a numeric ID or a slug string
+    #   (e.g., +'my-session-abc123'+).
+    #
+    #   Sends a GET request to +/api/agent_sessions/:id+.
+    #
+    #   @param id [Integer, String] numeric ID or slug of the session
+    #   @param opts [Hash] per-request options (e.g., +:api_key+)
+    #   @return [Forem::AgentSession] the matching session
+
+    # Obtain presigned upload credentials for a new agent session asset.
+    #
+    # Sends a POST request to +/api/agent_sessions/presign+. The returned
+    # object contains a signed upload URL and any required form fields needed
+    # to upload the session file directly to object storage.
+    #
+    # @param params [Hash] request body
+    # @option params [String] :filename the intended filename for the upload
+    # @option params [String] :mime_type MIME type of the file being uploaded
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ForemObject] presign response containing upload URL and credentials
+    # @example
+    #   presign = client.agent_sessions.presign(filename: "output.json", mime_type: "application/json")
+    #   puts presign.upload_url
+    # @see https://developers.forem.com/api/v1
+    def self.presign(params = {}, opts = {})
+      resp = request(:post, "/api/agent_sessions/presign", params, opts)
+      Forem::ForemObject.construct_from(resp.parsed_body)
+    end
+
+    # Return the raw asset URL associated with this agent session.
+    #
+    # Sends a GET request to +/api/agent_sessions/:id/raw_url+.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ForemObject] object containing the +url+ field with the raw asset URL
+    # @example
+    #   session = client.agent_sessions.retrieve(99)
+    #   puts session.raw_url.url
+    # @see https://developers.forem.com/api/v1
+    def raw_url(opts = {})
+      resp = request(:get, "#{resource_url}/raw_url", {}, opts)
+      Forem::ForemObject.construct_from(resp.parsed_body)
+    end
+  end
+end