spooky 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5305d1096b3ab7ae0add591dad425ae012cb2105b3a7a0d64691352c28d7c5
-  data.tar.gz: 576d6d09c71cdc9cd6aba580d3386b80e750f314a9a2509cd49e60401dea76f3
+  metadata.gz: a7b33039d9c8c5fc23d9cd5bd0d9f4b378b587695ebe3af8f0f5e23308f71bc7
+  data.tar.gz: ec4b539ae09724a1a95b7f42a8e2662bc6246172173827c27bfb8c75805f762c
 SHA512:
-  metadata.gz: a8eaf6a4cabc7d44952a84eefbb7d821451d8ac9863c52240de3c10f2da1424ae3065001855b3a4df37ac110144cc71a5f468b46d1d600465c3560f8cbb89ee9
-  data.tar.gz: 32621bc47059575a6f909b2b3ac6e2be2332aa7218a234243db9a615d08e0d5ea33038458234f47816a0a71bf2fe016e65d30f312138582afab157d3bcfd8603
+  metadata.gz: '08bb92cc697e8ad5d80851658d595df20fb3844ca62eba13fcb3f99f8237054166fd114954f6d2b2c47fababd5922c6d24a6bed001f68da578a895590b74d7ac'
+  data.tar.gz: 5b2161ec5915e1c9f71796c1b362f290bf9742813c7a444dfb1e90eb73339315d5d01dc655f5a9454a638b9f136abbae8e812a727ecc6897b0a731dbdeadf846

data/README.md

@@ -47,33 +47,66 @@ client = Spooky::Client.new
 ```
 ### Fetching Posts
 
-Spooky operates primarily on posts.
+Spooky operates primarily on posts. Methods that return a collection also return a pagination object, if there is one.
 
 #### Get all posts
-`posts = client.posts`
+```ruby
+posts, pagination = client.posts
+```
 
-Returns an array of `Spooky::Post`s.
+Returns an array of `Spooky::Post`s and a pagination meta hash.
 
 #### Get all posts and include tags and authors
-`posts = client.posts(tags: true, authors: true)`
+```ruby
+posts, pagination = client.posts(tags: true, authors: true)
+```
 
-Returns an array of `Spooky::Post`s with `Spooky::Tag`s and `Spooky::Author`s where appropriate.
+Returns an array of `Spooky::Post`s with `Spooky::Tag`s and `Spooky::Author`s where appropriate and a pagination meta hash.
 
 #### Get a post by ID or slug
 
-`post = client.post_by(id: 'abc123')`
+```ruby
+post = client.post_by(id: 'abc123')
+```
 
-`post = client.post_by(slug: 'this-is-a-slug')`
+```ruby
+post = client.post_by(slug: 'this-is-a-slug')
+```
 
 Both return a `Spooky::Post`.
 
 #### Get posts with a filter applied
 
-Filtering accepts simple hashes as conditions or NQL strings for more complex filters.
+Filtering accepts simple hashes as conditions or [NQL strings for more complex filters](https://ghost.org/docs/api/v3/content/#syntax-reference).
 
-`featured_posts = client.posts(filter: { featured: true })`
+```ruby
+featured_posts, pagination = client.posts(filter: { featured: true })
+```
 
-`welcome_posts = client.posts(filter: "title:Welcome")`
+```ruby
+welcome_posts, pagination = client.posts(filter: "title:Welcome")
+```
+
+You can exclude a post using NQL operators, note the `-`:
+
+```ruby
+posts_without_welcome, pagination = client.posts(tags: true, filter: "title:-Welcome")
+```
+
+### Pagination
+
+If applicable, Spooky will return the pagination meta hash directly from Ghost. It looks like this:
+
+```ruby
+{
+    "page" => 1,
+    "limit" => 3,
+    "pages" => 3,
+    "total" => 7,
+    "next" => 2,
+    "prev" => nil
+}
+```
 
 ## Development
 

data/lib/spooky/client.rb

@@ -21,20 +21,23 @@ module Spooky
         @error = response["errors"]
         false
       else
-        response[resource.split("/").first]
+        collection = response[resource.split("/").first]
+        pagination = response.dig("meta", "pagination")
+
+        [collection, pagination]
       end
     end
 
     def fetch(resource, options = {})
       resource_name = resource.split("/").first
-      response = fetch_json(resource, options)
+      response, pagination = fetch_json(resource, options)
 
       resource_class = "Spooky::#{resource_name.singularize.classify}".constantize
 
-      response.present? && response.map { |attrs| resource_class.send(:new, attrs) }
+      response.present? && [response.map { |attrs| resource_class.send(:new, attrs) }, pagination]
     end
 
-    def posts(tags: false, authors: false, filter: false)
+    def posts(tags: false, authors: false, filter: false, page: false, limit: false)
       inc = []
       inc << "tags" if tags
       inc << "authors" if authors
@@ -42,13 +45,8 @@ module Spooky
       options = {}
       options[:include] = inc if inc.present?
 
-      if filter.present?
-        if filter.is_a?(Hash)
-          options[:filter] = filter.map { |k, v| "#{k}:#{v}" }.join
-        else
-          options[:filter] = filter
-        end
-      end
+      options = apply_filter(options, filter)
+      options = apply_pagination(options, { page: page, limit: limit })
 
       fetch("posts", options)
     end
@@ -62,14 +60,35 @@ module Spooky
       options[:include] = inc if inc.present?
 
       if id.present?
-        response = fetch("posts/#{id}", options)
+        response, _ = fetch("posts/#{id}", options)
         response.present? && response.first
       elsif slug.present?
-        response = fetch("posts/slug/#{slug}", options)
+        response, _ = fetch("posts/slug/#{slug}", options)
         response.present? && response.first
       else
         false
       end
     end
+
+    private
+
+    def apply_filter(options, filter)
+      if filter.present?
+        if filter.is_a?(Hash)
+          options[:filter] = filter.map { |k, v| "#{k}:#{v}" }.join("+")
+        else
+          options[:filter] = filter
+        end
+      end
+
+      options
+    end
+
+    def apply_pagination(options, pagination)
+      options[:page] = pagination[:page] if pagination[:page]
+      options[:limit] = pagination[:limit] if pagination[:limit]
+
+      options
+    end
   end
 end

data/lib/spooky/version.rb

@@ -1,3 +1,3 @@
 module Spooky
-  VERSION = "1.0.0".freeze
+  VERSION = "1.1.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spooky
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Georges Gabereau