forem-ruby 0.1.0.beta2 → 0.1.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25e286206f0f92f3a65e64399b43715cca4b70a7ff532ca17fd4ea8f6e68146b
-  data.tar.gz: 04af2856b16152eb19965634c9bc9356c603e17a24f8c829dd85a18f0240b769
+  metadata.gz: 70aa093a419b454eae92eb74afdfddcea88acf77f0112c8d6d988874ec142b5c
+  data.tar.gz: 5e3ce2de3e9302ad7a2c0a05102af264288da4b0836c445c84fbf14d9fe4a7b8
 SHA512:
-  metadata.gz: 9a8bb32085051edb5f430c54d97450cf8ad564750e0f2ca0689d6333072aaae95b4019fa7151ee7ff56727ae4bd2333ed103964c01aec816ff42e5ffaf1f958d
-  data.tar.gz: 71da89bed7aaa18d649850b029cd142ad81fdef3aeb25e2721c2266179f58c3a3f9d5bbd65d9e477905f2750f2bce625a60dedff1c1f972d2d1f2e6fff8e8f2f
+  metadata.gz: 86e0016a62e3db3057028d61dd8fb23a29882b67e386a0446bca269eead5bfffa770be8fd67cb194868c43a7980d221255e31ac477a59f3561d7ff8b8bba37d2
+  data.tar.gz: f915cad693ab839f2f8afdacdc797aecfa4afd8a21ca499eb09f305a8f01289bd0296a891bd612f879f5ac27625469557a015639597f4704c8a3302c831bd245

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/resources/admin_user.rb

@@ -132,18 +132,19 @@ module Forem
       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 settings [Hash] notification setting columns to write, e.g.
+    #   +{ email_newsletter: false, email_digest_periodic: false }+. Sent
+    #   verbatim under the +notification_setting+ wrapper; the server owns
+    #   which keys it accepts.
     # @param opts [Hash] per-request options.
     # @return [ForemObject] the updated notification setting.
-    def self.update_notification_settings(user_id, email_newsletter:, **opts)
+    def self.update_notification_settings(user_id, settings:, **opts)
       requestor = opts[:requestor]
       resp = request(
         :put,
         "#{resource_path}/#{user_id}/notification_settings",
-        { notification_setting: { email_newsletter: email_newsletter } },
+        { notification_setting: settings },
         opts
       )
       ForemObject.construct_from(resp.parsed_body, requestor: requestor)

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,55 @@
+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
+  # - +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 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/admin_user_service.rb

@@ -96,16 +96,15 @@ module Forem
         )
       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 settings [Hash] notification setting columns to write.
       # @param opts [Hash] per-request options.
       # @return [ForemObject] the updated notification setting.
-      def update_notification_settings(user_id, email_newsletter:, **opts)
+      def update_notification_settings(user_id, settings:, **opts)
         AdminUser.update_notification_settings(
           user_id,
-          email_newsletter: email_newsletter,
+          settings: settings,
           **opts_with_requestor(opts)
         )
       end

data/lib/forem/services/badge_achievement_service.rb

@@ -0,0 +1,95 @@
+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.
+      #
+      # @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)
+      # @param opts [Hash] per-request options
+      # @return [BadgeAchievement] the newly created achievement
+      # @raise [InvalidRequestError] on HTTP 422
+      #
+      # @example
+      #   client.badge_achievements.create(
+      #     user_id: 123,
+      #     badge_id: 45
+      #   )
+      #
+      # @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.beta2"
+  VERSION = "0.1.0.beta4"
 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.beta2
+  version: 0.1.0.beta4
 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