Class: Forem::Services::BadgeAchievementService

Inherits:
BaseService
  • Object
show all
Defined in:
lib/forem/services/badge_achievement_service.rb

Overview

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.

Examples:

client = Forem::Client.new("your-admin-api-key")
client.badge_achievements.create(user_id: 123, badge_id: 45)

See Also:

Instance Method Summary collapse

Methods inherited from BaseService

#initialize

Constructor Details

This class inherits a constructor from Forem::Services::BaseService

Instance Method Details

#create(params = {}, opts = {}) ⇒ BadgeAchievement

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

Examples:

client.badge_achievements.create(
  user_id: 123,
  badge_id: 45,
  metadata: { entitlement_id: "01a0…" }
)

Parameters:

  • params (Hash) (defaults to: {}) —

    achievement attributes

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :user_id (Integer) —

    the user ID (required)

  • :badge_id (Integer) —

    the badge ID (required)

  • :rewarding_context_message_markdown (String) —

    a message shown with the award

  • :include_default_description (Boolean) —

    whether to show the badge's own description alongside the message (default true)

  • :metadata (Hash) —

    arbitrary key/value data stored with the achievement for context

Returns:

Raises:

See Also:



87
88
89
90
91
92
 
# File 'lib/forem/services/badge_achievement_service.rb', line 87

def create(params = {}, opts = {})
  BadgeAchievement.create(
    enveloped(:badge_achievement, params),
    opts_with_requestor(opts),
  )
end

#delete(id, opts = {}) ⇒ nil

Revoke a badge by deleting the achievement.

Examples:

client.badge_achievements.delete(9876)

Parameters:

  • id (Integer, String) —

    the achievement ID to delete

  • opts (Hash) (defaults to: {}) —

    per-request options

Returns:

  • (nil) —

    returns nil on success

Raises:

See Also:



105
106
107
 
# File 'lib/forem/services/badge_achievement_service.rb', line 105

def delete(id, opts = {})
  BadgeAchievement.delete(id, opts_with_requestor(opts))
end

#list(params = {}, opts = {}) ⇒ ListObject<BadgeAchievement>

List badge achievements, most recently created first.

Returns a fixed 50 records per page.

Examples:

client.badge_achievements.list(page: 2)

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

Returns:

See Also:



33
34
35
 
# File 'lib/forem/services/badge_achievement_service.rb', line 33

def list(params = {}, opts = {})
  BadgeAchievement.list(params, opts_with_requestor(opts))
end

#retrieve(id, opts = {}) ⇒ BadgeAchievement

Retrieve a single badge achievement by its numeric ID.

Examples:

client.badge_achievements.retrieve(9876)

Parameters:

  • id (Integer, String) —

    the achievement ID

  • opts (Hash) (defaults to: {}) —

    per-request options

Returns:

Raises:

See Also:



48
49
50
 
# File 'lib/forem/services/badge_achievement_service.rb', line 48

def retrieve(id, opts = {})
  BadgeAchievement.retrieve(id, opts_with_requestor(opts))
end