forem-ruby 0.1.0.beta3 → 0.1.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e948a4e3001066a9344c0609f3493a6c582b31fab01ff88dcc418e0dcc67c1c
-  data.tar.gz: ae8872806a2a55f49d4879561cf9bf5b993da167ec665a43c48390f3ced505cd
+  metadata.gz: 83797be860d88f26465e8497d17232bc764baa5c297fde6ff208e50f37fd5a94
+  data.tar.gz: 2997d86bd809479c4085c2d2308202a2b1938415d74d0350ca5b84da87f9101f
 SHA512:
-  metadata.gz: 3e2846154e8d12dbb1b78b3b7c46f44fc7b210c064429630af165164a59a45c5a336160d63c65cfa64fd9c3300e75a2ddb14eda607b7b660ba11fde557ae6628
-  data.tar.gz: 970dcc16e46767419612226f5ad6bd085e340e1617e99a5bf034685cebde22acbe5ac1b0abda6621160aeeed1b81b221f94c647626b1073e23538621937a1f46
+  metadata.gz: '095016c6e947721f81f23fbb63e82afb6c5f7b45a2253d83b6151d2f97977d097d1759e5a0fd9f13800f5607914e2a633a01485a8300502e090ee7be7a9760b1'
+  data.tar.gz: a7c39b213002376f16d5d06563759ee3cd03ac6ec54889f4bdf1ed9545d57a89334ecd93c2a00afe12549d1b54cd8ba64e0c9d1a87c4baabcf8359ad12c95fd6

data/lib/forem/client.rb

@@ -61,6 +61,26 @@ module Forem
     #   client.users.retrieve(42)
     def users;                       @users ||= Services::UserService.new(@requestor); end
 
+    # Access the Badges API.
+    #
+    # @return [Services::BadgeService] the badges service
+    # @see https://developers.forem.com/api/v1
+    #
+    # @example
+    #   client.badges.list(page: 1)
+    #   client.badges.retrieve(45)
+    def badges;                      @badges ||= Services::BadgeService.new(@requestor); end
+
+    # Access the Badge Achievements API.
+    #
+    # @return [Services::BadgeAchievementService] the badge achievements service
+    # @see https://developers.forem.com/api/v1
+    #
+    # @example
+    #   client.badge_achievements.create(user_id: 123, badge_id: 45)
+    #   client.badge_achievements.delete(9876)
+    def badge_achievements;          @badge_achievements ||= Services::BadgeAchievementService.new(@requestor); end
+
     # Access the Comments API.
     #
     # @return [Services::CommentService] the comments service

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/badge.rb

@@ -0,0 +1,61 @@
+module Forem
+  # Represents a badge that can be awarded to users on a Forem instance.
+  #
+  # Badges are awards that can be given to users. Badges support full CRUD
+  # operations.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/badges
+  #   - +Create+   — POST /api/badges
+  #   - +Retrieve+ — GET /api/badges/:id
+  #   - +Update+   — PUT /api/badges/:id
+  #   - +Delete+   — class- and instance-level delete (DELETE /api/badges/:id)
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # == Badge Fields
+  #
+  # - +id+ (Integer) — Assigned by the API; not writable
+  # - +title+ (String) — Badge title; unique across the instance
+  # - +slug+ (String) — Generated from +title+ by the API; not writable
+  # - +description+ (String) — Badge description
+  # - +badge_image+ (String) — Badge image URL; set on write with
+  #   +remote_badge_image_url+
+  # - +credits_awarded+ (Integer) — Credits granted alongside the badge
+  # - +allow_multiple_awards+ (Boolean) — Whether the badge can be awarded to the same user more than once
+  # - +created_at+ / +updated_at+ (String) — ISO 8601 timestamps; not writable
+  #
+  # == Authentication
+  #
+  # All badge endpoints require an admin API key, reads included.
+  #
+  # == Pagination
+  #
+  # +list+ returns a fixed 50 records per page.
+  #
+  # @example List every badge
+  #   page = 1
+  #   loop do
+  #     badges = client.badges.list(page: page)
+  #     break if badges.data.empty?
+  #     badges.data.each { |b| puts "#{b.id}: #{b.title}" }
+  #     page += 1
+  #   end
+  #
+  # @example Retrieve a badge by ID
+  #   badge = client.badges.retrieve(45)
+  #   puts badge.title
+  #
+  # @see BadgeAchievement
+  # @see https://developers.forem.com/api/v1
+  class Badge < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Delete
+    include APIOperations::Save
+
+    OBJECT_NAME = "badge"
+    RESOURCE_PATH = "/api/badges"
+  end
+end

data/lib/forem/resources/badge_achievement.rb

@@ -0,0 +1,63 @@
+module Forem
+  # Represents a badge awarded to a specific user.
+  #
+  # Creating a badge achievement awards a badge; deleting one revokes it. There
+  # is no update endpoint.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/badge_achievements
+  #   - +Create+   — POST /api/badge_achievements
+  #   - +Retrieve+ — GET /api/badge_achievements/:id
+  #   - +Delete+   — class- and instance-level delete (DELETE /api/badge_achievements/:id)
+  #
+  # == BadgeAchievement Fields
+  #
+  # - +id+ (Integer) — Assigned by the API; not writable
+  # - +user_id+ (Integer) — The user the badge was awarded to
+  # - +badge_id+ (Integer) — The badge that was awarded
+  # - +rewarder_id+ (Integer) — The awarding user; not writable, so always
+  #   +null+ on achievements created through the API
+  # - +rewarding_context_message_markdown+ (String) — Message shown with the award, in markdown
+  # - +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
+  #
+  # All badge achievement endpoints require an admin API key, reads included.
+  #
+  # == Pagination
+  #
+  # +list+ returns a fixed 50 records per page.
+  #
+  # @example Award a badge
+  #   achievement = client.badge_achievements.create(
+  #     user_id: 123,
+  #     badge_id: 45
+  #   )
+  #   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)
+  #
+  # @see Badge
+  # @see https://developers.forem.com/api/v1
+  class BadgeAchievement < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    include APIOperations::Delete
+
+    OBJECT_NAME = "badge_achievement"
+    RESOURCE_PATH = "/api/badge_achievements"
+  end
+end

data/lib/forem/services/badge_achievement_service.rb

@@ -0,0 +1,110 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Badge Achievements API.
+    #
+    # A badge achievement is a badge awarded to a user; creating one awards the
+    # badge and deleting one revokes it. These endpoints require an API key with
+    # admin-level privileges.
+    #
+    # Access via {Client#badge_achievements}. All methods inject the client's
+    # requestor automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-admin-api-key")
+    #   client.badge_achievements.create(user_id: 123, badge_id: 45)
+    #
+    # @see BadgeAchievement
+    # @see BadgeService
+    # @see https://developers.forem.com/api/v1
+    class BadgeAchievementService < BaseService
+      # List badge achievements, most recently created first.
+      #
+      # Returns a fixed 50 records per page.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @param opts [Hash] per-request options
+      # @return [ListObject<BadgeAchievement>] a page of achievements
+      #
+      # @example
+      #   client.badge_achievements.list(page: 2)
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        BadgeAchievement.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single badge achievement by its numeric ID.
+      #
+      # @param id [Integer, String] the achievement ID
+      # @param opts [Hash] per-request options
+      # @return [BadgeAchievement] the achievement with the given ID
+      # @raise [NotFoundError] on HTTP 404
+      #
+      # @example
+      #   client.badge_achievements.retrieve(9876)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        BadgeAchievement.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # 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)
+      # @option params [String] :rewarding_context_message_markdown a message
+      #   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,
+      #     metadata: { entitlement_id: "01a0…" }
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        BadgeAchievement.create(
+          enveloped(:badge_achievement, params),
+          opts_with_requestor(opts),
+        )
+      end
+
+      # Revoke a badge by deleting the achievement.
+      #
+      # @param id [Integer, String] the achievement ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success
+      # @raise [NotFoundError] on HTTP 404
+      #
+      # @example
+      #   client.badge_achievements.delete(9876)
+      #
+      # @see https://developers.forem.com/api/v1
+      def delete(id, opts = {})
+        BadgeAchievement.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/badge_service.rb

@@ -0,0 +1,117 @@
+module Forem
+  module Services
+    # Service for interacting with the Forem Badges API.
+    #
+    # Badges are awards that can be given to users. These endpoints require
+    # an API key with admin-level privileges.
+    #
+    # Access via {Client#badges}. All methods inject the client's requestor
+    # automatically so no additional configuration is required.
+    #
+    # @example
+    #   client = Forem::Client.new("your-admin-api-key")
+    #   badges = client.badges.list
+    #   badge  = client.badges.retrieve(45)
+    #
+    # @see Badge
+    # @see BadgeAchievementService for awarding a badge to a user
+    # @see https://developers.forem.com/api/v1
+    class BadgeService < BaseService
+      # List badges, most recently created first.
+      #
+      # Returns a fixed 50 records per page.
+      #
+      # @param params [Hash] query parameters
+      # @option params [Integer] :page page number (default: 1)
+      # @param opts [Hash] per-request options
+      # @return [ListObject<Badge>] a page of badges
+      #
+      # @example
+      #   client.badges.list(page: 2)
+      #
+      # @see https://developers.forem.com/api/v1
+      def list(params = {}, opts = {})
+        Badge.list(params, opts_with_requestor(opts))
+      end
+
+      # Retrieve a single badge by its numeric ID.
+      #
+      # @param id [Integer, String] the badge ID
+      # @param opts [Hash] per-request options
+      # @return [Badge] the badge with the given ID
+      # @raise [NotFoundError] on HTTP 404
+      #
+      # @example
+      #   client.badges.retrieve(45)
+      #
+      # @see https://developers.forem.com/api/v1
+      def retrieve(id, opts = {})
+        Badge.retrieve(id, opts_with_requestor(opts))
+      end
+
+      # Create a new badge.
+      #
+      # @param params [Hash] badge attributes
+      # @option params [String] :title badge title (must be unique)
+      # @option params [String] :description badge description
+      # @option params [String] :remote_badge_image_url URL to fetch the badge
+      #   image from
+      # @option params [Integer] :credits_awarded credits granted alongside the
+      #   badge (default 0)
+      # @option params [Boolean] :allow_multiple_awards whether the badge can
+      #   be awarded to the same user more than once (default false)
+      # @param opts [Hash] per-request options
+      # @return [Badge] the newly created badge
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors)
+      #
+      # @example
+      #   client.badges.create(
+      #     title: "Forem Contributor",
+      #     description: "Contributed an article",
+      #     remote_badge_image_url: "https://example.com/badge.png"
+      #   )
+      #
+      # @see https://developers.forem.com/api/v1
+      def create(params = {}, opts = {})
+        Badge.create(enveloped(:badge, params), opts_with_requestor(opts))
+      end
+
+      # Update an existing badge.
+      #
+      # @param id [Integer, String] the badge ID to update
+      # @param params [Hash] badge attributes to change
+      # @option params [String] :title new title
+      # @option params [String] :description new description
+      # @option params [Integer] :credits_awarded new credit amount
+      # @option params [Boolean] :allow_multiple_awards new multiple-award
+      #   setting
+      # @param opts [Hash] per-request options
+      # @return [Badge] the updated badge
+      # @raise [NotFoundError] on HTTP 404
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors)
+      #
+      # @example
+      #   client.badges.update(45, description: "Updated description")
+      #
+      # @see https://developers.forem.com/api/v1
+      def update(id, params = {}, opts = {})
+        Badge.update(id, enveloped(:badge, params), opts_with_requestor(opts))
+      end
+
+      # Delete a badge.
+      #
+      # @param id [Integer, String] the badge ID to delete
+      # @param opts [Hash] per-request options
+      # @return [nil] returns nil on success
+      # @raise [NotFoundError] on HTTP 404
+      #
+      # @example
+      #   client.badges.delete(45)
+      #
+      # @see https://developers.forem.com/api/v1
+      def delete(id, opts = {})
+        Badge.delete(id, opts_with_requestor(opts))
+      end
+    end
+  end
+end

data/lib/forem/services/base_service.rb

@@ -40,6 +40,26 @@ module Forem
       def opts_with_requestor(opts)
         opts.merge(requestor: @requestor)
       end
+
+      # Wrap flat attributes in the envelope key an endpoint expects.
+      #
+      # Some write endpoints expect a nested body
+      # (<tt>{ badge: { title: "..." } }</tt>). This lets service methods take
+      # flat attributes and nest them on the caller's behalf. Params that are
+      # already enveloped are passed through untouched, so both call styles
+      # work.
+      #
+      # @param key [Symbol] the envelope key (e.g. +:badge+)
+      # @param params [Hash] attributes, flat or already enveloped
+      # @return [Hash] the enveloped params
+      #
+      # @example
+      #   enveloped(:badge, title: "Top 7")   #=> { badge: { title: "Top 7" } }
+      def enveloped(key, params)
+        return params if params.key?(key) || params.key?(key.to_s)
+
+        { key => params }
+      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.beta3"
+  VERSION = "0.1.0.beta5"
 end

data/lib/forem.rb

@@ -16,6 +16,8 @@ require "forem/api_operations/save"
 require "forem/api_resource"
 require "forem/api_requestor"
 require "forem/resources/article"
+require "forem/resources/badge"
+require "forem/resources/badge_achievement"
 require "forem/resources/user"
 require "forem/resources/comment"
 require "forem/resources/organization"
@@ -42,6 +44,8 @@ require "forem/resources/admin_concept"
 require "forem/resources/request_redirect"
 require "forem/services/base_service"
 require "forem/services/article_service"
+require "forem/services/badge_service"
+require "forem/services/badge_achievement_service"
 require "forem/services/user_service"
 require "forem/services/comment_service"
 require "forem/services/organization_service"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forem-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta3
+  version: 0.1.0.beta5
 platform: ruby
 authors:
 - Forem
@@ -38,6 +38,8 @@ files:
 - lib/forem/resources/agent_session.rb
 - lib/forem/resources/analytics.rb
 - lib/forem/resources/article.rb
+- lib/forem/resources/badge.rb
+- lib/forem/resources/badge_achievement.rb
 - lib/forem/resources/billboard.rb
 - lib/forem/resources/comment.rb
 - lib/forem/resources/concept.rb
@@ -63,6 +65,8 @@ files:
 - lib/forem/services/agent_session_service.rb
 - lib/forem/services/analytics_service.rb
 - lib/forem/services/article_service.rb
+- lib/forem/services/badge_achievement_service.rb
+- lib/forem/services/badge_service.rb
 - lib/forem/services/base_service.rb
 - lib/forem/services/billboard_service.rb
 - lib/forem/services/comment_service.rb