figshare_api_v2 0.9.8 → 0.9.9

data/lib/private_projects.rb

@@ -8,14 +8,32 @@ module Figshare
     # @param roles [String] Any combination of owner, collaborator, viewer separated by comma. Examples: "owner" or "owner,collaborator".
     # @param order [String] "published_date" Default, "modified_date", "views", "cites", "shares"
     # @param order_direction [String] "desc" Default, "asc"
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] {role, storage, url, published_date, id, title}
-    def list(storage: nil, roles: nil, order: 'published_date', order_direction: 'desc', impersonate: nil, &block)
+    # @yield [Array] [{role, storage, url, published_date, id, title}]
+    def list( storage: nil,
+              roles: nil,
+              order: 'published_date',
+              order_direction: 'desc',
+              page: nil,
+              page_size: nil,
+              offset: nil,
+              limit: nil,
+              impersonate: nil,
+              &block
+            )
       args = {}
       args['storage'] = storage unless storage.nil?
       args['roles'] = roles unless roles.nil?
       args['order'] = order unless order.nil?
       args['order_direction'] = order_direction unless order_direction.nil?
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       get_paginate(api_query: 'account/projects', args: args, &block)
     end
@@ -29,15 +47,19 @@ module Figshare
     # @param order [String] "published_date" Default, "modified_date", "views", "cites", "shares"
     # @param order_direction [String] "desc" Default, "asc"
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] {id, title, doi, handle, url, published_date}
+    # @yield [Hash] {id, title, url, role, storage, published_date}
     def search( search_for:,
                 institute: false,
                 group_id: nil,
-                impersonate: nil,
                 published_since: nil,
                 modified_since: nil,
                 order: 'published_date',
                 order_direction: 'desc',
+                page: nil,
+                page_size: nil,
+                offset: nil,
+                limit: nil,
+                impersonate: nil,
                 &block
               )
       args = { 'search_for' => search_for }
@@ -48,25 +70,31 @@ module Figshare
       args['modified_since'] = modified_since unless modified_since.nil?
       args['order'] = order unless order.nil?
       args['order_direction'] = order_direction unless order_direction.nil?
-      post(api_query: 'account/projects/search', args: args, &block)
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
+      post_paginate(api_query: 'account/projects/search', args: args, &block)
     end
 
     # Create a new project
     #
     # @param title [String]
     # @param description [String]
+    # #param group_id [Integer] Figshare group the project falls under.
     # @param funding [String]
     # @param funding_list [Array] [{id, title}, ... ]
-    # #param group_id [Integer] Figshare group the project falls under.
+    # @param custom_field_list [Array] [{name, value}, ... ]
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
     # @yield [Hash] { location }
-    def create(title:, description:, group_id:, funding: '', funding_list: [], impersonate: nil, &block)
+    def create(title:, description:, group_id:, funding: '', funding_list: [], custom_field_list: nil, impersonate: nil, &block)
       args = { 'title' => title,
                'description' => description,
                'group_id' => group_id,
                'funding' => funding,
                'funding_list' => funding_list
              }
+      args['custom_field_list'] = custom_field_list unless custom_field_list.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       post(api_query: 'account/projects', args: args, &block)
     end
@@ -99,14 +127,16 @@ module Figshare
     # @param description [String]
     # @param funding [String]
     # @param funding_list [Array] [{id, title}, ... ]
+    # @param custom_field_list [Array] [{name, value}, ... ]
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
     # @yield [Hash] { location }
-    def update(project_id:, title: nil, description: nil, funding: nil, funding_list: nil, impersonate: nil, &block)
+    def update(project_id:, title: nil, description: nil, funding: nil, funding_list: nil, custom_field_list: nil, impersonate: nil, &block)
       args = {}
       args['title'] = title unless title.nil?
       args['description'] = description unless description.nil?
       args['funding'] = funding unless funding.nil?
       args['funding_list'] = funding_list unless funding_list.nil?
+      args['custom_field_list'] = custom_field_list unless custom_field_list.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       put(api_query: "account/projects/#{project_id}", args: args, &block)
     end
@@ -115,7 +145,7 @@ module Figshare
     #
     # @param project_id [Integer] Figshare id of the project
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] Message
+    # @yield [Hash] {Message:}
     def publish(project_id:, impersonate: nil, &block)
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?
@@ -125,10 +155,25 @@ module Figshare
     # List projects notes
     #
     # @param project_id [Integer] Figshare id of the project
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] {id, user_id, abstract, user_name, created_date, modified_date}
-    def notes(project_id:, impersonate: nil, &block)
+    # @yield [Array] [{id:, user_id:, abstract:, user_name:, created_date:, modified_date:}]
+    def notes(  project_id:,
+                page: nil,
+                page_size: nil,
+                offset: nil,
+                limit: nil,
+                impersonate: nil,
+                &block
+             )
       args = {}
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       get_paginate(api_query: "account/projects/#{project_id}/notes", args: args, &block)
     end
@@ -161,8 +206,8 @@ module Figshare
     # @param project_id [Integer] Figshare id of the project
     # @param note_id [Integer] Figshare id of the note
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] { text }
-    def note_detail(impersonate: nil, &block)
+    # @yield [Hash] { text:, id:, user_id:, abstract:, user_name:, created_date:, modified_data: }
+    def note_detail(project_id:, note_id:, impersonate: nil, &block)
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?
       get(api_query: "account/projects/#{project_id}/notes/#{note_id}", args: args, &block)
@@ -180,10 +225,10 @@ module Figshare
       put(api_query: "account/projects/#{project_id}/notes/#{note_id}", args: args, &block)
     end
 
-    # Leave a project (Please note: project's owner cannot leave the project.)
+    # Leave a project (Note: project's owner cannot leave the project.)
     #
     # @param project_id [Integer] Figshare id of the project_id
-    def private_project_collaborators_leave(project_id:, impersonate: nil, &block)
+    def project_collaborators_leave(project_id:, impersonate: nil, &block)
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?
       post(api_query: "account/projects/#{project_id}/leave", args: args, &block)
@@ -193,7 +238,7 @@ module Figshare
     #
     # @param project_id [Integer] Figshare id of the project_id
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] { status, role_name, user_id, name }
+    # @yield [Array] [{ status:, role_name:, user_id:, name: }]
     def collaborators(project_id:, impersonate: nil, &block)
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?
@@ -203,23 +248,20 @@ module Figshare
     # Invite a new collaborators to the project
     #
     # @param project_id [Integer] Figshare id of the project_id
-    # @param role_name [String]
-    # @param user_id [Integer] Need user_id or email
-    # @param email [String] Used, if user_id is nil
+    # @param role_name [String] "viewer", ...
+    # @param user_id [Integer] Need user_id and/or email
+    # @param email [String] Need user_id and/or email
     # @param comment [String]
     # @yield [String] { message }
     def collaborator_invite(project_id:, role_name:, comment:, user_id: nil, email: nil, impersonate: nil, &block)
+      raise 'collaborator_invite(): Need a user_id or an email address' if user_id.nil? && email.nil?
+
       args = {
         'role_name' => role_name,
         'comment' => comment
       }
-      if ! user_id.nil?
-        args['user_id'] = user_id
-      elsif ! email.nil?
-        args['email'] = email
-      else
-        raise 'collaborator_invite(): Need a user_id or an email address'
-      end
+      args['user_id'] = user_id unless user_id.nil?
+      args['email'] = email unless email.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       collaborator = { 'role_name' => role_name, 'user_id' => user_id, 'email' => email, 'comment' => comment }
       post(api_query: "account/project/#{project_id}/collaborators", args: args, data: collaborator, &block)
@@ -231,6 +273,8 @@ module Figshare
     # @param user_id [Integer] Figshare id of a user in the project
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
     def collaborator_remove(project_id:, user_id:, impersonate: nil, &block)
+      raise 'collaborator_remove(): Need a user_id' if user_id.nil?
+
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?
       delete(api_query: "account/project/#{project_id}/collaborators/#{user_id}", args: args, &block)
@@ -239,10 +283,25 @@ module Figshare
     # Return details of list of articles for a specific project
     #
     # @param project_id [Integer] Figshare id of the project
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] See Figshare API Doc
-    def articles(project_id:, impersonate: nil, &block)
+    # @yield [Array] See Figshare API Doc
+    def articles( project_id:,
+                  page: nil,
+                  page_size: nil,
+                  offset: nil,
+                  limit: nil,
+                  impersonate: nil,
+                  &block
+                )
       args = {}
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       get_paginate(api_query: "account/projects/#{project_id}/articles", args: args, &block)
     end
@@ -250,10 +309,27 @@ module Figshare
     # Create a new Article and associate it with this project
     #
     # @param project_id [Integer] Figshare id of the project
+    # @param article_record [Hash] See docs.figshare.com
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] { location }
-    def article_create(project_id:, impersonate: nil, &block)
-      args = {}
+    # @yield [Hash] { entity_id:, location:, warnings: [ "string" ] }
+    def article_create( project_id:,
+                        article_record: nil,
+                        page: nil,
+                        page_size: nil,
+                        offset: nil,
+                        limit: nil,
+                        impersonate: nil,
+                        &block
+                      )
+      args = { 'article' => article_record }
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       args['impersonate'] = impersonate unless impersonate.nil?
       # Figshare Docs say this should be post_paginate, but that makes no sense. Will have to test
       post_paginate(api_query: "account/projects/#{project_id}/articles", args: args, &block)
@@ -275,7 +351,7 @@ module Figshare
     # @param project_id [Integer] Figshare id of the project
     # @param article_id [Integer] Figshare id of the article
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] See Fishare API docs for article hash
+    # @yield [Hash] See docs.figshare.com for article hash
     def article_detail(project_id:, article_id:, impersonate: nil, &block)
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?
@@ -287,7 +363,7 @@ module Figshare
     # @param project_id [Integer] Figshare id of the project
     # @param article_id [Integer] Figshare id of the article
     # @param impersonate [Integer] Figshare account_id of the user we are making this call on behalf of
-    # @yield [Hash] See Fishare API docs for article hash
+    # @yield [Array] See docs.figshare.com for article hash
     def artilce_files(project_id:, article_id:, impersonate: nil, &block)
       args = {}
       args['impersonate'] = impersonate unless impersonate.nil?

data/lib/public_articles.rb

@@ -14,7 +14,11 @@ module Figshare
     # @param handle [String] Matches this handle
     # @param order [String] "published_date" Default, "modified_date", "views", "cites", "shares"
     # @param order_direction [String] "desc" Default, "asc"
-    # @yield [Hash] {id, title, doi, handle, url, published_date}
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
+    # @yield [Array] [{id, title, doi, handle, url, published_date,...}] see docs.figshare.com
     def list( institute: false,
               group_id: nil,
               published_since: nil,
@@ -25,11 +29,15 @@ module Figshare
               handle: nil,
               order: 'published_date',
               order_direction: 'desc',
+              page: nil,
+              page_size: nil,
+              offset: nil,
+              limit: nil,
               &block
             )
       args = {}
       args['institution'] = @institute_id unless institute.nil?
-      args['group_id'] = group_id unless group_id.nil?
+      args['group_id'] = group_id unless group_id.nil?  # Not sure if this should be 'group' or 'group_id'. API has conflicting info
       args['item_type'] = item_type unless item_type.nil?
       args['resource_doi'] = resource_doi unless resource_doi.nil?
       args['doi'] = doi unless doi.nil?
@@ -38,6 +46,10 @@ module Figshare
       args['modified_since'] = modified_since unless modified_since.nil?
       args['order'] = order unless order.nil?
       args['order_direction'] = order_direction unless order_direction.nil?
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       get_paginate(api_query: 'articles', args: args, &block)
     end
 
@@ -127,7 +139,7 @@ module Figshare
     # @param article_id [Integer] Figshare id of the article
     # @param file_id [Integer] Figshare id of the file
     # @yield [Hash] See figshare api docs
-    def file_detail(article_id:, file_id:)
+    def file_detail(article_id:, file_id:, &block)
       get(api_query: "articles/#{article_id}/files/#{file_id}", &block)
     end
   end

data/lib/public_collections.rb

@@ -13,6 +13,10 @@ module Figshare
     # @param handle [String] Matches this handle
     # @param order [String] "published_date" Default, "modified_date", "views", "cites", "shares"
     # @param order_direction [String] "desc" Default, "asc"
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @yield [Hash] {id, title, doi, handle, url, published_date}
     def list( institution: false,
               group_id: nil,
@@ -23,6 +27,10 @@ module Figshare
               handle: nil,
               order: 'published_date',
               order_direction: 'desc',
+              page: nil,
+              page_size: nil,
+              offset: nil,
+              limit: nil,
               &block
             )
       args = {}
@@ -35,6 +43,10 @@ module Figshare
       args['modified_since'] = modified_since unless modified_since.nil?
       args['order'] = order unless order.nil?
       args['order_direction'] = order_direction unless order_direction.nil?
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       get_paginate(api_query: 'collections', args: args, &block)
     end
 
@@ -97,6 +109,10 @@ module Figshare
     #
     # @param collection_id [Integer] Figshare id of the collection
     # @param version_id [Integer] Figshare id of the collection's version
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @yield [Hash] See figshare api docs
     def version_detail(collection_id:, version_id:, &block)
       get(api_query: "collections/#{collection_id}/versions/#{version_id}", &block)
@@ -106,8 +122,19 @@ module Figshare
     #
     # @param collection_id [Integer] Figshare id of the collection
     # @yield [Hash] {id, title, doi, handle, url, published_date}
-    def articles(collection_id:, &block)
-      get_paginate(api_query: "collections/#{collection_id}/articles", &block)
+    def articles( collection_id:,
+                  page: nil,
+                  page_size: nil,
+                  offset: nil,
+                  limit: nil,
+                  &block
+                )
+      args = {}
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
+      get_paginate(api_query: "collections/#{collection_id}/articles", args: args, &block)
     end
   end
 end

data/lib/public_projects.rb

@@ -9,14 +9,32 @@ module Figshare
     # @param published_since [Time] Return results if published after this time
     # @param order [String] "published_date" Default, "modified_date", "views", "cites", "shares"
     # @param order_direction [String] "desc" Default, "asc"
+    # @param page [Numeric] Pages start at 1. Page and Page size go together
+    # @param page_size [Numeric]
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @yield [Hash] {url, published_date, id, title}
-    def list(institute: false, group_id: nil, published_since: nil, order: 'published_date', order_direction: 'desc', &block)
+    def list( institute: false,
+              group_id: nil,
+              published_since: nil,
+              order: 'published_date',
+              order_direction: 'desc',
+              page: nil,
+              page_size: nil,
+              offset: nil,
+              limit: nil,
+              &block
+            )
       args = {}
       args['institution'] = @institute_id unless institute.nil?
       args['group'] = group_id unless group_id.nil?
       args['published_since'] = published_since unless published_since.nil?
       args['order'] = order unless order.nil?
       args['order_direction'] = order_direction unless order_direction.nil?
+      args['page'] = page unless page.nil?
+      args['page_size'] = page_size unless page_size.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       get_paginate(api_query: 'projects', args: args, &block)
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: figshare_api_v2
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 0.9.9
 platform: ruby
 authors:
 - Rob Burrowes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-02 00:00:00.000000000 Z
+date: 2022-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: wikk_json
@@ -80,7 +80,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.23'
-description: Figshare version 2 API.
+description: |-
+  Figshare version 2 API.
+
+  Actually the second version of the version 2 APIs. Lots of changes have been made by Figshare, mostly expanding what is returned from the API calls, but they also added some fields. Looks mostly backwards compatible.
 email:
 - r.burrowes@auckland.ac.nz
 executables: []
@@ -136,5 +139,5 @@ requirements: []
 rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
-summary: Figshare version 2 API.
+summary: Figshare version 2 API
 test_files: []