forem-ruby 0.1.0.beta4 → 0.1.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70aa093a419b454eae92eb74afdfddcea88acf77f0112c8d6d988874ec142b5c
-  data.tar.gz: 5e3ce2de3e9302ad7a2c0a05102af264288da4b0836c445c84fbf14d9fe4a7b8
+  metadata.gz: 83797be860d88f26465e8497d17232bc764baa5c297fde6ff208e50f37fd5a94
+  data.tar.gz: 2997d86bd809479c4085c2d2308202a2b1938415d74d0350ca5b84da87f9101f
 SHA512:
-  metadata.gz: 86e0016a62e3db3057028d61dd8fb23a29882b67e386a0446bca269eead5bfffa770be8fd67cb194868c43a7980d221255e31ac477a59f3561d7ff8b8bba37d2
-  data.tar.gz: f915cad693ab839f2f8afdacdc797aecfa4afd8a21ca499eb09f305a8f01289bd0296a891bd612f879f5ac27625469557a015639597f4704c8a3302c831bd245
+  metadata.gz: '095016c6e947721f81f23fbb63e82afb6c5f7b45a2253d83b6151d2f97977d097d1759e5a0fd9f13800f5607914e2a633a01485a8300502e090ee7be7a9760b1'
+  data.tar.gz: a7c39b213002376f16d5d06563759ee3cd03ac6ec54889f4bdf1ed9545d57a89334ecd93c2a00afe12549d1b54cd8ba64e0c9d1a87c4baabcf8359ad12c95fd6

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_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/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/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.beta5"
 end

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.beta5
 platform: ruby
 authors:
 - Forem