dev_ruby 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c97ff734180da46570fffd2b2cbf21b6c4b43ab1fb776a9c5bc6961581286dd6
-  data.tar.gz: bd6d656db14a79f310e2428aeecc3df77382488879c1fec011045334284124ef
+  metadata.gz: 7a1c4336ef269ff3bdbee4f7ebeeaa9f591bdc107ae3a2a6d295bf23bbdec604
+  data.tar.gz: 755974cc241a6dddc39e1b28e45089302a0016aa46fa1c043a4ad8ae2e55556c
 SHA512:
-  metadata.gz: 24293c5d54863cf0743d08117a071ebe5f52bcd2cc5807fb428b390c85ffb0f8bb32b0c1ff035e519bfaf6f1cb3147dc17f21dc13a7e258d31740f9de0414688
-  data.tar.gz: 68fdd8fac1d3211556cd7c79a5389acd4e240e30ee68f82c218c08fffb322b93302d27126680aed885a9c1e07d8b313d24d54ef25bf231ee6aa2082e5862a04c
+  metadata.gz: be5cf753eb9bad7ce3e031c0644cc6ee3e187d2a818df27af8277dcbd41c89e849ec95ceb12f4a4cc3fb51b08e6f299afc3ce89d7cde2959cd712c00f1a90452
+  data.tar.gz: 0b6ed0bf05b1d630f79c96406db09219d6641ba2124256fec0d43426eaecafd1049b7def8f6f45495791ce3af958361357837b8d9de3d856b552916a88f99b6c

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 2.7
   NewCops: disable
   SuggestExtensions: false
 

data/Gemfile

@@ -10,3 +10,15 @@ gem 'rake', '~> 13.0'
 gem 'minitest', '~> 5.0'
 
 gem 'rubocop', '~> 1.21'
+
+# HTTP/REST API client library [https://github.com/lostisland/faraday]
+gem 'faraday', '~> 2.2'
+
+# Common monads for Ruby [https://github.com/dry-rb/dry-monads]
+gem 'dry-monads', '~> 1.4'
+
+# Pretty print Ruby objects with proper indentation and colors [https://github.com/awesome-print/awesome_print]
+gem 'awesome_print'
+
+# A mixin to add configuration functionality to your classes [https://github.com/dry-rb/dry-configurable]
+gem 'dry-configurable', '~> 0.15.0'

data/Gemfile.lock

@@ -1,12 +1,26 @@
 PATH
   remote: .
   specs:
-    dev_ruby (0.1.0)
+    dev_ruby (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    awesome_print (1.9.2)
+    concurrent-ruby (1.1.10)
+    dry-configurable (0.15.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.6)
+    dry-core (0.7.1)
+      concurrent-ruby (~> 1.0)
+    dry-monads (1.4.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.7)
+    faraday (2.3.0)
+      faraday-net_http (~> 2.0)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (2.0.2)
     minitest (5.15.0)
     parallel (1.22.1)
     parser (3.1.2.0)
@@ -27,13 +41,18 @@ GEM
     rubocop-ast (1.17.0)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
     unicode-display_width (2.1.0)
 
 PLATFORMS
   arm64-darwin-21
 
 DEPENDENCIES
+  awesome_print
   dev_ruby!
+  dry-configurable (~> 0.15.0)
+  dry-monads (~> 1.4)
+  faraday (~> 2.2)
   minitest (~> 5.0)
   rake (~> 13.0)
   rubocop (~> 1.21)

data/README.md

@@ -2,7 +2,7 @@
 ![test](https://github.com/nejdetkadir/dev-ruby/actions/workflows/test.yml/badge.svg?branch=main)
 ![rubocop](https://github.com/nejdetkadir/dev-ruby/actions/workflows/rubocop.yml/badge.svg?branch=main)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
-![Ruby Version](https://img.shields.io/badge/ruby_version->=_2.6.0-blue.svg)
+![Ruby Version](https://img.shields.io/badge/ruby_version->=_2.7.0-blue.svg)
 
 # DevRuby
 Ruby bindings for DEV API
@@ -11,7 +11,7 @@ Ruby bindings for DEV API
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'dev_ruby'
+gem 'dev_ruby', github: 'nejdetkadir/dev-ruby', branch: 'main'
 ```
 
 And then execute:
@@ -22,8 +22,259 @@ Or install it yourself as:
 
     $ gem install dev_ruby
 
+## Configuration
+```ruby
+DevRuby.configure do |config|
+  config.logger = ::Logger.new($stdout).tap { |d| d.level = Logger::DEBUG }
+  config.log_api_bodies = true
+  config.per_page = 20
+end
+```
+
 ## Usage
-TODO: Write usage instructions here
+To access the API, you'll need to create a DevRuby::Client and pass in your API key. You can find your API key at [https://developers.forem.com/api](https://developers.forem.com/api)
+
+```ruby
+client = DevRuby::Client.new(api_key: ENV['DEV_API_KEY'])
+```
+The client then gives you access to each of the resources.
+
+## Resources
+The gem maps as closely as we can to the DEV API so you can easily convert API examples to gem code.
+
+Responses are returning as objects like `DevRuby::Objects::Article` with using [dry-monads](https://github.com/dry-rb/dry-monads) gem for easly error handling. Having types like `DevRuby::Objects::Article` is handy for understanding what type of object you're working with. They're built using OpenStruct so you can easily access data in a Ruby-ish way.
+
+```ruby
+# Sample request with dry-monads
+
+client = DevRuby::Client.new(api_key: ENV['DEV_API_KEY'])
+
+operation = client.articles.create(title: 'My Article',
+                                   body: 'This is my article')
+
+if operation.success?
+  article = operation.success
+
+  puts 'Article created successfully'
+  puts "Article ID: #{article.id}"
+end
+
+if operation.failure?
+  errors = operation.failure
+
+  puts 'Article creation failed'
+  puts "Error: #{errors}"
+end
+
+operation.value! # Returns the article if successful or return error if not successful
+```
+
+## Pagination
+Some endpoints return pages of results. The result object will have a data key to access the results, as well as metadata like next_page and prev_page for retrieving the next and previous pages. You may also specify the
+
+```ruby
+collection = client.articles.published.value!
+#=> DevRuby::Collection
+
+collection.data
+#=> [#<DevRuby::Objects::Article>, #<DevRuby::Objects::Article>]
+
+collection.data.count
+#=> 3
+
+collection.next_page
+#=> "3"
+
+collection.prev_page
+#=> "1"
+
+# Retrieve the next page
+client.articles.published(per_page: 100, page: collection.next_page)
+#=> DevRuby::Collection
+```
+
+## Articles
+```ruby
+# This endpoint allows the client to retrieve a list of articles.
+# By default it will return featured, published articles ordered by descending popularity.
+collection = client.articles.published.value! # per_page is optional, defaults to 20.
+#=> DevRuby::Collection
+
+# This endpoint allows the client to create a new article.
+article = client.articles.create(title: 'Hello, World!',
+                                  published: true,
+                                  body_markdown: 'Hello DEV, this is my first post',
+                                  tags: %w[discuss help],
+                                  series: 'Hello series').value!
+#=> DevRuby::Objects::Article
+
+# This endpoint allows the client to retrieve a list of articles. ordered by descending publish date.
+collection = client.articles.latest_published.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a single published article given its id.
+article = client.articles.find('123456').value!
+#=> DevRuby::Objects::Article
+
+# This endpoint allows the client to update an existing article.
+article = client.articles.update(id: '123456',
+                                 title: 'Hello, World!').value!
+#=> DevRuby::Objects::Article
+
+# This endpoint allows the client to retrieve a single published article given its path.
+article = client.articles.find_by_path(username: 'nejdetkadir', slug: 'hello-world').value!
+#=> DevRuby::Objects::Article
+
+# This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user.
+# Published articles will be in reverse chronological publication order.
+collection = client.articles.me.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user.
+# Published articles will be in reverse chronological publication order
+collection = client.articles.me_published.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of unpublished articles on behalf of an authenticated user.
+# Unpublished articles will be in reverse chronological creation order.
+collection = client.articles.me_unpublished.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of all articles on behalf of an authenticated user.
+# It will return both published and unpublished articles with pagination.
+# Unpublished articles will be at the top of the list in reverse chronological creation order. Published articles will follow in reverse chronological publication order
+collection = client.articles.me_all.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of articles that are uploaded with a video.
+# It will only return published video articles ordered by descending popularity.
+collection = client.articles.videos.value!
+#=> DevRuby::Collection
+```
+
+## Comments
+```ruby
+# This endpoint allows the client to retrieve all comments belonging to an article or podcast episode as threaded conversations.
+# It will return the all top level comments with their nested comments as threads. See the format specification for further details.
+collection = client.comments.all.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a comment as well as his descendants comments.
+# It will return the required comment (the root) with its nested descendants as a thread.
+# See the format specification for further details.
+comment = client.comments.find('123456').value!
+#=> DevRuby::Objects::Comment
+```
+
+## Follows
+```ruby
+# This endpoint allows the client to retrieve a list of the tags they follow.
+collection = client.follows.followed_tags.value!
+#=> DevRuby::Collection
+```
+
+## Followers
+```ruby
+# This endpoint allows the client to retrieve a list of the followers they have.
+collection = client.followers.all.value!
+#=> DevRuby::Collection
+```
+
+## Listings
+```ruby
+# This endpoint allows the client to retrieve a list of listings.
+# By default it will return published listings ordered by descending freshness.
+collection = client.listings.published.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to create a new listing.
+# The user creating the listing or the organization on which behalf the user is creating for need to have enough credits for this operation to be successful. The server will prioritize the organization's credits over the user's credits.
+listing = client.listings.create(title: 'ACME Conference',
+                                 body_markdown: 'Awesome conference',
+                                 category: 'cfp',
+                                 tags: %w[events]).value!
+#=> DevRuby::Objects::Listing
+
+# This endpoint allows the client to retrieve a list of listings belonging to the specified category.
+# By default it will return published listings ordered by descending freshness.
+collection = client.listings.published_by_category(category: 'cfp').value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a single listing given its id.
+# An unpublished listing is only accessible if authentication is supplied and it belongs to the authenticated user.
+listing = client.listings.find('123456').value!
+#=> DevRuby::Objects::Listing
+
+# This endpoint allows the client to update an existing listing.
+article = client.listings.update(id: '123456', action: 'bump').value!
+#=> DevRuby::Objects::Listing
+```
+
+## Organizations
+```ruby
+# This endpoint allows the client to retrieve a single organization by their username.
+organization = client.organizations.find_by_username('nejdetkadir').value!
+#=> DevRuby::Objects::Organization
+
+# This endpoint allows the client to retrieve a list of users belonging to the organization
+collection = client.organizations.all_users_by_username(username: 'nejdetkadir').value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of listings belonging to the organization
+collection = client.organizations.all_listings_by_username(username: 'nejdetkadir').value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of Articles belonging to the organization 
+collection = client.organizations.all_articles_by_username(username: 'nejdetkadir').value!
+#=> DevRuby::Collection
+```
+
+## Podcast Episodes
+```ruby
+# This endpoint allows the client to retrieve a list of podcast episodes.
+collection = client.podcast_episodes.published.value!
+#=> DevRuby::Collection
+```
+
+## Readinglists
+```ruby
+# This endpoint allows the client to retrieve a list of readinglist reactions along with the related article for the authenticated user.
+# Reading list will be in reverse chronological order base on the creation of the reaction.
+collection = client.readinglists.all.value!
+#=> DevRuby::Collection
+```
+
+## Tags
+```ruby
+# This endpoint allows the client to retrieve a list of tags that can be used to tag articles.
+# It will return tags ordered by popularity.
+collection = client.tags.all.value!
+#=> DevRuby::Collection
+
+# This endpoint allows the client to retrieve a list of the tags they follow.
+collection = client.tags.followed_tags.value!
+#=> DevRuby::Collection
+```
+
+## Users
+```ruby
+# This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user.
+user = client.users.me.value!
+#=> DevRuby::Objects::User
+
+# This endpoint allows the client to retrieve a single user, either by id or by the user's username
+user = client.users.find('123456').value!
+#=> DevRuby::Objects::User
+
+invitation = client.users.invite_user(email: 'user@example.com', name: 'string').value!
+#=> true
+```
+
+## Profile Images
+```ruby
+profile_image = client.profile_images.find_by_username('nejdetkadir').value!
+#=> DevRuby::Objects::ProfileImage
+```
 
 ## Development
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/dev_ruby.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = spec.summary
   spec.homepage = 'https://github.com/nejdetkadir/dev-ruby'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 2.6.0'
+  spec.required_ruby_version = '>= 2.7.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage

data/lib/dev_ruby/client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DevRuby
+  class Client
+    BASE_URL = 'https://dev.to/api'
+    AUTHORIZATION_KEY = 'api-key'
+
+    attr_reader :api_key, :adapter
+
+    def initialize(api_key:, adapter: Faraday.default_adapter, stubs: nil)
+      @api_key = api_key
+      @adapter = adapter
+      @stubs = stubs # Test stubs for requests
+    end
+
+    def articles
+      DevRuby::Resources::ArticlesResource.new(self)
+    end
+
+    def comments
+      DevRuby::Resources::CommentsResource.new(self)
+    end
+
+    def follows
+      DevRuby::Resources::FollowsResource.new(self)
+    end
+
+    def followers
+      DevRuby::Resources::FollowersResource.new(self)
+    end
+
+    def listings
+      DevRuby::Resources::ListingsResource.new(self)
+    end
+
+    def organizations
+      DevRuby::Resources::OrganizationsResource.new(self)
+    end
+
+    def podcast_episodes
+      DevRuby::Resources::PodcastEpisodesResource.new(self)
+    end
+
+    def readinglist
+      DevRuby::Resources::ReadinglistsResource.new(self)
+    end
+
+    def tags
+      DevRuby::Resources::TagsResource.new(self)
+    end
+
+    def users
+      DevRuby::Resources::UsersResource.new(self)
+    end
+
+    def profile_images
+      DevRuby::Resources::ProfileImagesResource.new(self)
+    end
+
+    # rubocop:disable Layout/LineLength
+    def connection
+      @connection ||= Faraday.new(BASE_URL) do |conn|
+        conn.headers[AUTHORIZATION_KEY] = api_key
+        conn.request :json
+        conn.response :json, content_type: 'application/json'
+        conn.response :logger, DevRuby.logger, body: true, bodies: { request: true, response: true } if DevRuby.log_api_bodies
+        conn.adapter adapter, @stubs
+      end
+    end
+    # rubocop:enable Layout/LineLength
+  end
+end

data/lib/dev_ruby/collection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DevRuby
+  class Collection
+    attr_reader :page, :per_page, :next_page, :prev_page, :data
+
+    def self.from_response(response:, type:, params:)
+      new(data: response.body.map { |attrs| type.new(attrs) },
+          page: params[:page],
+          per_page: params[:per_page])
+    end
+
+    def initialize(data:, page:, per_page:)
+      @data = data
+      @page = page
+      @per_page = per_page
+      @next_page = data.count.positive? ? (page + 1) : nil
+      @prev_page = page.positive? ? (page - 1) : nil
+    end
+  end
+end

data/lib/dev_ruby/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DevRuby
+  class Error < StandardError; end
+end

data/lib/dev_ruby/helpers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DevRuby
+  class Helpers
+    class << self
+      def expected_response?(response, expected_status)
+        response.status == expected_status
+      end
+    end
+  end
+end

data/lib/dev_ruby/objects/article.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Article < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/base_object.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+module DevRuby
+  module Objects
+    class BaseObject < OpenStruct
+      def initialize(attributes)
+        super to_ostruct(attributes)
+      end
+
+      def to_ostruct(obj)
+        case obj
+        when Hash
+          OpenStruct.new(obj.transform_values { |val| to_ostruct(val) })
+        when Array
+          obj.map { |o| to_ostruct(o) }
+        else # Assumed to be a primitive value
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/dev_ruby/objects/comment.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Comment < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Error < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/follower.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Follower < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/listing.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Listing < BaseObject
+      CATEGORIES = %w[
+        cfp forhire collabs education jobs mentors
+        products mentees forsale events misc
+      ].freeze
+    end
+  end
+end

data/lib/dev_ruby/objects/organization.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Organization < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/podcast_episode.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class PodcastEpisode < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/profile_image.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class ProfileImage < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/tag.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class Tag < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/user.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class User < BaseObject
+    end
+  end
+end

data/lib/dev_ruby/objects/video_article.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DevRuby
+  module Objects
+    class VideoArticle < BaseObject
+    end
+  end
+end