Class: Forem::Services::BadgeService

Inherits:
BaseService show all
Defined in:
lib/forem/services/badge_service.rb

Overview

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.

Examples:

client = Forem::Client.new("your-admin-api-key")
badges = client.badges.list
badge  = client.badges.retrieve(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 = {}) ⇒ Badge

Create a new badge.

Examples:

client.badges.create(
  title: "Forem Contributor",
  description: "Contributed an article",
  remote_badge_image_url: "https://example.com/badge.png"
)

Parameters:

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

    badge attributes

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

    per-request options

Options Hash (params):

  • :title (String) —

    badge title (must be unique)

  • :description (String) —

    badge description

  • :remote_badge_image_url (String) —

    URL to fetch the badge image from

  • :credits_awarded (Integer) —

    credits granted alongside the badge (default 0)

  • :allow_multiple_awards (Boolean) —

    whether the badge can be awarded to the same user more than once (default false)

Returns:

  • (Badge) —

    the newly created badge

Raises:

See Also:



75
76
77
 
# File 'lib/forem/services/badge_service.rb', line 75

def create(params = {}, opts = {})
  Badge.create(enveloped(:badge, params), opts_with_requestor(opts))
end

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

Delete a badge.

Examples:

client.badges.delete(45)

Parameters:

  • id (Integer, String) —

    the badge ID to delete

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

    per-request options

Returns:

  • (nil) —

    returns nil on success

Raises:

See Also:



112
113
114
 
# File 'lib/forem/services/badge_service.rb', line 112

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

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

List badges, most recently created first.

Returns a fixed 50 records per page.

Examples:

client.badges.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_service.rb', line 33

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

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

Retrieve a single badge by its numeric ID.

Examples:

client.badges.retrieve(45)

Parameters:

  • id (Integer, String) —

    the badge ID

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

    per-request options

Returns:

  • (Badge) —

    the badge with the given ID

Raises:

See Also:



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

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

#update(id, params = {}, opts = {}) ⇒ Badge

Update an existing badge.

Examples:

client.badges.update(45, description: "Updated description")

Parameters:

  • id (Integer, String) —

    the badge ID to update

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

    badge attributes to change

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

    per-request options

Options Hash (params):

  • :title (String) —

    new title

  • :description (String) —

    new description

  • :credits_awarded (Integer) —

    new credit amount

  • :allow_multiple_awards (Boolean) —

    new multiple-award setting

Returns:

  • (Badge) —

    the updated badge

Raises:

See Also:



97
98
99
 
# File 'lib/forem/services/badge_service.rb', line 97

def update(id, params = {}, opts = {})
  Badge.update(id, enveloped(:badge, params), opts_with_requestor(opts))
end