forem-ruby 0.1.0.beta4 → 0.1.0.beta6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70aa093a419b454eae92eb74afdfddcea88acf77f0112c8d6d988874ec142b5c
-  data.tar.gz: 5e3ce2de3e9302ad7a2c0a05102af264288da4b0836c445c84fbf14d9fe4a7b8
+  metadata.gz: f3ad62af106cb7a2949a2a6516b34529e8ccb83b6dbe34d380c5a8c2090a5f84
+  data.tar.gz: 68b08dfc2b22d528009a25ac8ad5b56f117c474949287003bc3f1817e7caae31
 SHA512:
-  metadata.gz: 86e0016a62e3db3057028d61dd8fb23a29882b67e386a0446bca269eead5bfffa770be8fd67cb194868c43a7980d221255e31ac477a59f3561d7ff8b8bba37d2
-  data.tar.gz: f915cad693ab839f2f8afdacdc797aecfa4afd8a21ca499eb09f305a8f01289bd0296a891bd612f879f5ac27625469557a015639597f4704c8a3302c831bd245
+  metadata.gz: 73f6857ecc8e052613b7fb48efa691d9ab4d521a6a7db37b2a5ced7d86e21e5b2ad8a8d8d895407e713045c86ad4c58397d4b45b01648ac347aa9dc78a745d13
+  data.tar.gz: 5008eda4cff82e831d2aaf6fe09f3a60805bc09b44542c1b9cbe36ac0429a6b6fdcabe4cda1275d16b70f1b038a4fafc909a8fa286ebcd65a7a39f03905061b2

data/lib/forem/client.rb

@@ -295,5 +295,15 @@ module Forem
     # @example
     #   client.request_redirects.list
     def request_redirects;           @request_redirects ||= Services::RequestRedirectService.new(@requestor); end
+
+    # Access the Events API.
+    #
+    # @return [Services::EventService] the events service
+    # @see https://developers.forem.com/api/v1
+    #
+    # @example
+    #   client.events.list(type_of: "challenge")
+    #   client.events.retrieve(12)
+    def events;                      @events ||= Services::EventService.new(@requestor); end
   end
 end

data/lib/forem/errors.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module Forem
   # Base error class for all errors raised by the forem-ruby library.
   #
@@ -45,6 +47,28 @@ module Forem
       @code = code
       super(message)
     end
+
+    # The response body parsed as JSON.
+    #
+    # Useful when the API returns structured detail alongside an error. An empty
+    # or unparseable body yields +nil+.
+    #
+    # @return [Hash, Array, nil] the parsed body, or +nil+ when there is
+    #   nothing parseable to return.
+    #
+    # @example Reading a field the API returned with the error
+    #   begin
+    #     client.badge_achievements.create(user_id: 123, badge_id: 45)
+    #   rescue Forem::ConflictError => e
+    #     e.parsed_body&.dig("achievement_id")
+    #   end
+    def parsed_body
+      return @parsed_body if defined?(@parsed_body)
+
+      @parsed_body = (JSON.parse(http_body) if http_body && !http_body.empty?)
+    rescue JSON::ParserError
+      @parsed_body = nil
+    end
   end
 
   # Raised when the server responds with HTTP 401 Unauthorized.

data/lib/forem/resources/article.rb

@@ -43,8 +43,12 @@ module Forem
   # @option params [String] 'article.canonical_url' (nullable)
   # @option params [String] 'article.main_image' (nullable)
   # @option params [Integer] 'article.organization_id' (nullable)
+  # @option params [Integer] 'article.ai_disclosure_level' AI disclosure level (e.g. 0 for none, 1 for assisted, 2 for generated)
   #
-  # @example List published articles
+  # == Article Fields
+  #
+  # Additional response attributes include +ai_disclosure_level+, +ai_disclosure_label+,
+  # +cover_image+, +social_image+, +reading_time+, +positive_reactions_count+, etc.
   #   articles = client.articles.list(per_page: 10, tag: "ruby")
   #   articles.data.each { |a| puts a.title }
   #

data/lib/forem/resources/badge_achievement.rb

@@ -21,6 +21,7 @@ module Forem
   # - +rewarding_context_message+ (String) — Rendered from
   #   +rewarding_context_message_markdown+ by the API; not writable
   # - +include_default_description+ (Boolean) — Whether the badge description accompanies the message
+  # - +metadata+ (ForemObject) — Arbitrary key/value data supplied for context. Defaults to +{}+.
   # - +created_at+ / +updated_at+ (String) — ISO 8601 timestamps; not writable
   #
   # == Authentication
@@ -38,6 +39,13 @@ module Forem
   #   )
   #   puts achievement.id
   #
+  # @example Award a badge with caller-supplied metadata
+  #   client.badge_achievements.create(
+  #     user_id: 123,
+  #     badge_id: 45,
+  #     metadata: { entitlement_id: "01a0…", source: "core" }
+  #   )
+  #
   # @example Revoke a badge
   #   client.badge_achievements.delete(9876)
   #

data/lib/forem/resources/comment.rb

@@ -17,6 +17,11 @@ module Forem
   # - +page+ (Integer) — Page number
   # - +per_page+ (Integer) — Items per page (default: 50)
   #
+  # == Comment Fields
+  #
+  # Comment objects expose attributes such as +id_code+, +created_at+, +body_html+,
+  # +ai_disclosure_level+, and +ai_disclosure_label+.
+  #
   # Returns threaded conversations with nested replies.
   #
   # @example List all comments for an article

data/lib/forem/resources/event.rb

@@ -0,0 +1,137 @@
+module Forem
+  # Represents an event on a Forem instance.
+  #
+  # Events can represent live streams, hackathons, takeovers, or community
+  # meetups. The API supports full CRUD operations, and the create endpoint
+  # behaves as an idempotent upsert when matching slugs or numeric IDs are
+  # provided.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/events (supports +type_of+ filtering)
+  #   - +Create+   — POST /api/events (idempotent upsert, admin privileges)
+  #   - +Retrieve+ — GET /api/events/:id_or_slug
+  #   - +Update+   — PUT /api/events/:id_or_slug (admin privileges)
+  #   - +Delete+   — class- and instance-level delete (DELETE /api/events/:id_or_slug, admin privileges)
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # == List Parameters
+  #
+  # When calling +Event.list+, the following query parameters are supported:
+  #
+  # - +type_of+ (String) — Filter by event type: +"live_stream"+, +"takeover"+, +"other"+, +"challenge"+
+  # - +page+ (Integer) — Page number (default: 1)
+  # - +per_page+ (Integer) — Items per page (default: 30, max: 1000)
+  #
+  # == Event Fields
+  #
+  # - +id+ (Integer) — Assigned by the API
+  # - +title+ (String, required) — Title of the event
+  # - +event_name_slug+ (String, required) — Lowercase slug identifier (e.g. +"hackrice"+)
+  # - +event_variation_slug+ (String, required) — Edition/season/year slug (e.g. +"13"+ or +"2026"+)
+  # - +description+ (String) — Markdown or plain text description
+  # - +full_details+ (String) — Comprehensive plain text / Markdown dump of all event details, agenda, and context notes
+  # - +start_time+ (String / ISO 8601, required) — Start timestamp
+  # - +end_time+ (String / ISO 8601, required) — End timestamp
+  # - +type_of+ (String) — One of: +"live_stream"+, +"takeover"+, +"other"+, +"challenge"+
+  # - +broadcast_config+ (String) — One of: +"no_broadcast"+, +"tagged_broadcast"+, +"global_broadcast"+
+  # - +primary_stream_url+ (String) — Video streaming URL (YouTube, Twitch, Streamyard)
+  # - +manual_broadcast_end+ (Boolean) — Whether broadcasting end is manually handled
+  # - +published+ (Boolean) — Whether the event is publicly listed
+  # - +elevated+ (Boolean) — Whether the event is featured/elevated
+  # - +bg_color_hex+ (String) — 6-digit hex background color code (e.g. +"#7C3AED"+)
+  # - +cover_image+ (String) — Uploaded cover image filename
+  # - +remote_cover_image_url+ (String) — Remote URL to fetch, crop, and store as cover image
+  # - +remove_cover_image+ (Boolean) — Flag to delete the existing cover image
+  # - +tag_list+ (String) — Comma-separated list of tags
+  # - +user_id+ (Integer) — ID of the host/creator user
+  # - +organization_id+ (Integer) — ID of the host organization
+  # - +page_id+ (Integer) — ID of an associated page
+  # - +delegate_to_page+ (Boolean) — Whether landing page links delegate directly to page
+  # - +data+ (Hash) — Structured metadata such as +location+, +format+, +external_registration_url+
+  # - +cover_image_url+ (String) — Public URL to the uploaded cover image
+  # - +social_image_url+ (String) — Public URL to the 1200x630 social card crop or default fallback
+  # - +background_hex_color+ (String) — Effective background hex color
+  # - +formatted_date_range+ (String) — Display-ready date range string (e.g. +"AUG 28 - 30"+)
+  # - +location+ (String) — Display location string (e.g. +"Everywhere, Worldwide"+)
+  # - +format+ (String) — Display format pill label (e.g. +"DIGITAL"+, +"IN-PERSON"+)
+  #
+  # @example List published events or filter by type_of
+  #   events = client.events.list(type_of: "challenge")
+  #   events.each { |e| puts "#{e.title} (#{e.formatted_date_range})" }
+  #
+  # @example Retrieve an event by numeric ID or slug
+  #   event = client.events.retrieve(12)
+  #   puts event.title
+  #
+  # @example Create or upsert an event
+  #   event = client.events.create(
+  #     title: "HackRice XIII",
+  #     event_name_slug: "hackrice",
+  #     event_variation_slug: "13",
+  #     start_time: "2026-09-11T10:00:00Z",
+  #     end_time: "2026-09-13T16:00:00Z",
+  #     type_of: "challenge",
+  #     full_details: "Full hackathon schedule, judging rubric, and prizes breakdown.",
+  #     published: true,
+  #     bg_color_hex: "#7C3AED",
+  #     remote_cover_image_url: "https://assets.example.com/banner.png",
+  #     data: {
+  #       location: "Houston, Texas, US",
+  #       format: "IN-PERSON",
+  #       external_registration_url: "https://hackrice.com"
+  #     }
+  #   )
+  #
+  # @example Delete an event
+  #   client.events.delete(12)
+  #
+  # @see https://developers.forem.com/api/v1
+  class Event < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Delete
+    include APIOperations::Save
+
+    OBJECT_NAME = "event"
+    RESOURCE_PATH = "/api/events"
+
+    # Create a new event or upsert by matching slugs.
+    #
+    # Automatically wraps flat parameters under the +:event+ key expected by the API.
+    #
+    # @param params [Hash] event parameters
+    # @param opts [Hash] per-request options
+    # @return [Event] the newly created event
+    def self.create(params = {}, opts = {})
+      payload = params.key?(:event) || params.key?("event") ? params : { event: params }
+      super(payload, opts)
+    end
+
+    # Update an existing event.
+    #
+    # Automatically wraps flat parameters under the +:event+ key expected by the API.
+    #
+    # @param id [Integer, String] event ID or slug
+    # @param params [Hash] attributes to update
+    # @param opts [Hash] per-request options
+    # @return [Event] the updated event
+    def self.update(id, params = {}, opts = {})
+      payload = params.key?(:event) || params.key?("event") ? params : { event: params }
+      super(id, payload, opts)
+    end
+
+    # Save this event instance via the API.
+    #
+    # Automatically wraps flat parameters under the +:event+ key expected by the API.
+    #
+    # @param params [Hash] attributes to update
+    # @param opts [Hash] per-request keyword options
+    # @return [Event] updated event instance
+    def save(params = {}, **opts)
+      payload = params.key?(:event) || params.key?("event") ? params : { event: params }
+      super(payload, **opts)
+    end
+  end
+end

data/lib/forem/services/badge_achievement_service.rb

@@ -51,6 +51,16 @@ module Forem
 
       # Award a badge to a user.
       #
+      # If the badge cannot be awarded more than once and the user already holds
+      # it, this raises {ConflictError} (HTTP 409). The response carries
+      # +achievement_id+, the id of the award that blocked the request.
+      #
+      #   begin
+      #     client.badge_achievements.create(user_id: 123, badge_id: 45)
+      #   rescue Forem::ConflictError => e
+      #     existing_id = e.parsed_body&.dig("achievement_id")
+      #   end
+      #
       # @param params [Hash] achievement attributes
       # @option params [Integer] :user_id the user ID (required)
       # @option params [Integer] :badge_id the badge ID (required)
@@ -58,14 +68,19 @@ module Forem
       #   shown with the award
       # @option params [Boolean] :include_default_description whether to show
       #   the badge's own description alongside the message (default true)
+      # @option params [Hash] :metadata arbitrary key/value data stored with the
+      #   achievement for context
       # @param opts [Hash] per-request options
       # @return [BadgeAchievement] the newly created achievement
+      # @raise [ConflictError] on HTTP 409 when the user already holds a badge
+      #   that cannot be awarded more than once
       # @raise [InvalidRequestError] on HTTP 422
       #
       # @example
       #   client.badge_achievements.create(
       #     user_id: 123,
-      #     badge_id: 45
+      #     badge_id: 45,
+      #     metadata: { entitlement_id: "01a0…" }
       #   )
       #
       # @see https://developers.forem.com/api/v1

data/lib/forem/services/event_service.rb

@@ -0,0 +1,121 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Events API.
+    #
+    # Events represent live streams, hackathons, takeovers, or community
+    # meetups. Access via {Client#events}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-api-key")
+    #   events = client.events.list(type_of: "challenge")
+    #   event  = client.events.retrieve(10)
+    #
+    # @see Event
+    # @see https://developers.forem.com/api/v1
+    class EventService < BaseService
+      # List all events.
+      #
+      # @param params [Hash] query parameters
+      # @option params [String] :type_of filter by event type (e.g. "live_stream", "takeover", "other", "challenge")
+      # @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<Event>] list of events
+      #
+      # @example
+      #   client.events.list
+      #   client.events.list(type_of: "challenge")
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Event.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single event by its numeric ID or slug.
+      #
+      # @param id [Integer, String] the event ID or slug
+      # @param opts [Hash] per-request options
+      # @return [Event] the event with the given ID
+      #
+      # @example
+      #   client.events.retrieve(10)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        Event.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Create a new event or upsert by matching slugs / ID.
+      #
+      # Accepts flat attribute hashes or nested under +:event+.
+      #
+      # @param params [Hash] event attributes
+      # @option params [String] :title event title (required)
+      # @option params [String] :event_name_slug lowercase slug identifier (required)
+      # @option params [String] :event_variation_slug edition/season/year slug (required)
+      # @option params [String] :start_time ISO 8601 start timestamp (required)
+      # @option params [String] :end_time ISO 8601 end timestamp (required)
+      # @option params [String] :type_of event type ("live_stream", "takeover", "other", "challenge")
+      # @option params [String] :description Markdown or plain text description
+      # @option params [String] :full_details comprehensive plain text / Markdown details dump
+      # @option params [String] :primary_stream_url streaming URL
+      # @option params [Boolean] :published whether the event is publicly listed
+      # @option params [String] :bg_color_hex hex background color code
+      # @option params [String] :remote_cover_image_url remote URL to fetch cover image
+      # @option params [Integer] :organization_id host organization ID
+      # @option params [String] :tag_list comma-separated tags
+      # @option params [Hash] :data structured metadata
+      # @param opts [Hash] per-request options
+      # @return [Event] the newly created event
+      #
+      # @example
+      #   client.events.create(
+      #     title: "Hackathon 2026",
+      #     event_name_slug: "hackathon",
+      #     event_variation_slug: "2026",
+      #     start_time: "2026-09-01T09:00:00Z",
+      #     end_time: "2026-09-03T18:00:00Z",
+      #     type_of: "challenge",
+      #     full_details: "Complete schedule and prize information for agent context",
+      #     published: true
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        Event.create(params, opts_with_requestor(opts))
+      end
+
+      # Update an existing event.
+      #
+      # Accepts flat attribute hashes or nested under +:event+.
+      #
+      # @param id [Integer, String] the event ID to update
+      # @param params [Hash] event attributes to change
+      # @param opts [Hash] per-request options
+      # @return [Event] the updated event
+      #
+      # @example
+      #   client.events.update(10, title: "Updated Hackathon 2026")
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        Event.update(id, params, opts_with_requestor(opts))
+      end
+
+      # Delete an event.
+      #
+      # @param id [Integer, String] the event ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success
+      #
+      # @example
+      #   client.events.delete(10)
+      #
+      # @see https://developers.forem.com/api/v1
+      def delete(id, opts = {})
+        Event.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/version.rb

@@ -1,4 +1,4 @@
 module Forem
   # The current version of the forem-ruby gem.
-  VERSION = "0.1.0.beta4"
+  VERSION = "0.1.0.beta6"
 end

data/lib/forem.rb

@@ -42,6 +42,7 @@ require "forem/resources/trend"
 require "forem/resources/concept"
 require "forem/resources/admin_concept"
 require "forem/resources/request_redirect"
+require "forem/resources/event"
 require "forem/services/base_service"
 require "forem/services/article_service"
 require "forem/services/badge_service"
@@ -70,6 +71,7 @@ require "forem/services/trend_service"
 require "forem/services/concept_service"
 require "forem/services/admin_concept_service"
 require "forem/services/request_redirect_service"
+require "forem/services/event_service"
 require "forem/client"
 
 # Top-level namespace for the forem-ruby gem.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forem-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta4
+  version: 0.1.0.beta6
 platform: ruby
 authors:
 - Forem
@@ -43,6 +43,7 @@ files:
 - lib/forem/resources/billboard.rb
 - lib/forem/resources/comment.rb
 - lib/forem/resources/concept.rb
+- lib/forem/resources/event.rb
 - lib/forem/resources/follow.rb
 - lib/forem/resources/follower.rb
 - lib/forem/resources/health_check.rb
@@ -71,6 +72,7 @@ files:
 - lib/forem/services/billboard_service.rb
 - lib/forem/services/comment_service.rb
 - lib/forem/services/concept_service.rb
+- lib/forem/services/event_service.rb
 - lib/forem/services/follow_service.rb
 - lib/forem/services/follower_service.rb
 - lib/forem/services/health_check_service.rb