Class: Forem::Services::ArticleService

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

Overview

Service for interacting with the Forem Articles API.

Access via Client#articles. All methods inject the client's requestor automatically so no additional configuration is required.

Examples:

client = Forem::Client.new("your-api-key")
service = client.articles
service.list(per_page: 5, tag: "ruby")

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 = {}) ⇒ Article

Create a new article.

Examples:

client.articles.create(
  title: "Hello World",
  body_markdown: "# Hello\nThis is my first post.",
  published: true,
  tags: ["ruby", "beginners"]
)

Parameters:

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

    article attributes

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

    per-request options

Options Hash (params):

  • :title (String) —

    article title

  • :body_markdown (String) —

    article body in Markdown

  • :published (Boolean) —

    whether to publish immediately

  • :tags (Array<String>) —

    list of tag names

  • :series (String) —

    name of a series to add the article to

  • :canonical_url (String) —

    canonical URL override

  • :description (String) —

    article description / excerpt

Returns:

  • (Article) —

    the newly created article

See Also:



61
62
63
 
# File 'lib/forem/services/article_service.rb', line 61

def create(params = {}, opts = {})
  Article.create(params, opts_with_requestor(opts))
end

#latest(params = {}, opts = {}) ⇒ Array<Article>

List the most recently published articles.

Examples:

client.articles.latest(per_page: 20)

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (max: 1000)

Returns:

  • (Array<Article>) —

    latest published articles in chronological order

See Also:



174
175
176
 
# File 'lib/forem/services/article_service.rb', line 174

def latest(params = {}, opts = {})
  Article.latest(params, opts_with_requestor(opts))
end

#list(params = {}, opts = {}) ⇒ Array<Article>

List published articles.

Examples:

client.articles.list(tag: "ruby", per_page: 10)

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (max: 1000)

  • :tag (String) —

    filter by a single tag name

  • :tags (String) —

    comma-separated list of tags to include

  • :tags_exclude (String) —

    comma-separated list of tags to exclude

  • :username (String) —

    filter by author username

  • :state (String) —

    article state ("fresh", "rising", "all")

  • :top (Integer) —

    number of days back to look for top articles

  • :collection_id (String) —

    filter by collection ID

Returns:

  • (Array<Article>) —

    list of published articles

See Also:



35
36
37
 
# File 'lib/forem/services/article_service.rb', line 35

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

#me(params = {}, opts = {}) ⇒ Array<Article>

List articles authored by the authenticated user.

Examples:

client.articles.me(per_page: 30)

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (max: 1000)

Returns:

  • (Array<Article>) —

    articles belonging to the current user

See Also:



110
111
112
 
# File 'lib/forem/services/article_service.rb', line 110

def me(params = {}, opts = {})
  Article.me(params, opts_with_requestor(opts))
end

#me_all(params = {}, opts = {}) ⇒ Array<Article>

List all articles (published and unpublished) authored by the authenticated user.

Examples:

client.articles.me_all

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (max: 1000)

Returns:

  • (Array<Article>) —

    all articles belonging to the current user

See Also:



158
159
160
 
# File 'lib/forem/services/article_service.rb', line 158

def me_all(params = {}, opts = {})
  Article.me_all(params, opts_with_requestor(opts))
end

#me_published(params = {}, opts = {}) ⇒ Array<Article>

List published articles authored by the authenticated user.

Examples:

client.articles.me_published

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (max: 1000)

Returns:

  • (Array<Article>) —

    published articles belonging to the current user

See Also:



126
127
128
 
# File 'lib/forem/services/article_service.rb', line 126

def me_published(params = {}, opts = {})
  Article.me_published(params, opts_with_requestor(opts))
end

#me_unpublished(params = {}, opts = {}) ⇒ Array<Article>

List unpublished articles (drafts) authored by the authenticated user.

Examples:

client.articles.me_unpublished

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (max: 1000)

Returns:

  • (Array<Article>) —

    unpublished articles belonging to the current user

See Also:



142
143
144
 
# File 'lib/forem/services/article_service.rb', line 142

def me_unpublished(params = {}, opts = {})
  Article.me_unpublished(params, opts_with_requestor(opts))
end

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

Retrieve a single article by its numeric ID.

Examples:

client.articles.retrieve(12345)

Parameters:

  • id (Integer, String) —

    the article ID

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

    per-request options

Returns:

  • (Article) —

    the article with the given ID

See Also:



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

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

#retrieve_by_path(username, slug, opts = {}) ⇒ Article

Retrieve an article by its author username and slug.

Examples:

client.articles.retrieve_by_path("jsmith", "my-great-post")

Parameters:

  • username (String) —

    the author's username

  • slug (String) —

    the article slug

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

    per-request options

Returns:

  • (Article) —

    the matching article

See Also:



228
229
230
 
# File 'lib/forem/services/article_service.rb', line 228

def retrieve_by_path(username, slug, opts = {})
  Article.retrieve_by_path(username, slug, opts_with_requestor(opts))
end

#search(params = {}, opts = {}) ⇒ Array<Article>

Search articles by keyword.

Examples:

client.articles.search(q: "ruby on rails")

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :q (String) —

    the search term

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page

Returns:

  • (Array<Article>) —

    articles matching the search query

See Also:



191
192
193
 
# File 'lib/forem/services/article_service.rb', line 191

def search(params = {}, opts = {})
  Article.search(params, opts_with_requestor(opts))
end

#semantic_search(params = {}, opts = {}) ⇒ Array<Article>

Semantically search articles using Forem's embeddings-based search.

Unlike search (keyword matching), this finds articles whose meaning is close to the query text. Requires authentication.

Examples:

client.articles.semantic_search(q: "how to deploy rails apps")

Parameters:

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

    query parameters

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

    per-request options

Options Hash (params):

  • :q (String) —

    the search query text (required)

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 10, max: 50)

  • :threshold (Float) —

    optional cosine distance threshold (0.0-2.0)

Returns:

  • (Array<Article>) —

    articles matching the query, each exposing distance and similarity attributes

See Also:



213
214
215
 
# File 'lib/forem/services/article_service.rb', line 213

def semantic_search(params = {}, opts = {})
  Article.semantic_search(params, opts_with_requestor(opts))
end

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

Update an existing article.

Examples:

client.articles.update(12345, title: "Updated Title", published: true)

Parameters:

  • id (Integer, String) —

    the article ID to update

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

    article attributes to change

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

    per-request options

Options Hash (params):

  • :title (String) —

    new title

  • :body_markdown (String) —

    new body in Markdown

  • :published (Boolean) —

    publish or unpublish the article

  • :tags (Array<String>) —

    updated list of tag names

Returns:

  • (Article) —

    the updated article

See Also:



94
95
96
 
# File 'lib/forem/services/article_service.rb', line 94

def update(id, params = {}, opts = {})
  Article.update(id, params, opts_with_requestor(opts))
end