figshare_api_v2 0.9.7 → 0.9.10

data/lib/institutions.rb

@@ -4,19 +4,30 @@ module Figshare
   class Institutions < Base
     # Upload hr file
     #
-    # @param hr_xml [String] See https://docs.figshare.com/#hr_feed_hr_feed_private_endpoint
+    # @param hr_xml_filename [String] Filename. See https://docs.figshare.com/#hr_feed_hr_feed_private_endpoint
     # @yield [Hash] { message:, data: null, errcode:}
-    def hr_upload(hr_xml:, &block)
-      put(api_query: 'institution/hrfeed/upload', data: hr_xml, content_type: 'multipart/form-data', &block)
+    def hr_upload(hr_xml_filename:, &block)
+      File.open(@file_name, 'rb') do |fin|
+        hr_xml = fin.read
+        args = { 'name' => 'hrfeed', 'filename' => hr_xml_filename }
+        post(api_query: 'institution/hrfeed/upload', args: args, data: hr_xml, content_type: 'multipart/form-data', &block)
+      end
     end
 
-    # Get the institional account details
+    # Get the institional account's details (not a person's account details)
     #
-    # @yield [Hash]
+    # @yield [Hash] {id:, name: "institute"}
     def account(&block)
       get(api_query: 'account/institution', &block)
     end
 
+    # Get the institional account embargo options (IP Ranges)
+    #
+    # @yield [Array] list of embargo ip ranges [ {id:, type: ip_range, ip_name: Figshare_IP_Range} ]
+    def account_embargo_options(&block)
+      get(api_query: 'account/institution/embargo_options', &block)
+    end
+
     # Requests a list of private institute articles
     #
     # @param status [Integer] Only return items with this status
@@ -26,6 +37,10 @@ module Figshare
     # @param item_type [String] Matches this item_type. See Figshare API docs for list (https://docs.figshare.com/#articles_list)
     # @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, group_id, url, url_public_html, url_public_api, url_private_htm,
     #                url_private_api, published_date, timeline {...}, thumb, defined_type, defined_name }
     def private_articles( status: nil,
@@ -35,6 +50,10 @@ module Figshare
                           resource_doi: nil,
                           order: 'published_date',
                           order_direction: 'desc',
+                          page: nil,
+                          page_size: nil,
+                          offset: nil,
+                          limit: nil,
                           &block
                         )
       args = {}
@@ -45,6 +64,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: 'account/institution/articles', args: args, &block)
     end
 
@@ -58,42 +81,116 @@ module Figshare
       args = {}
       args['resource_id'] = resource_id unless resource_id.nil?
       args['filename'] = filename unless filename.nil?
-      get(api_query: 'institutions/{@institute_id}/articles/filter-by', args: args, &block)
+      get(api_query: "institutions/#{@institute_id}/articles/filter-by", args: args, &block)
+    end
+
+    # Get an institute group's custom fields
+    #
+    # @param group_id [Integer] Figshare group_id
+    # @yield [Array] [ {id:, name: field_name, field_type: text } ]
+    def group_custom_fields(group_id: nil, &block )
+      args = {}
+      args['group_id'] = group_id unless group_id.nil?
+      get(api_query: 'account/institution/custom_fields', args: args, &block)
+    end
+
+    # Set institute group's custom fields, from a CSV file
+    #
+    # @param custom_field_id [Integer] Figshare group_id
+    # @param filename [Integer] Figshare group_id
+    # @yield [Hash] {code: 200, message: ok } ]
+    def group_set_custom_fields(custom_field_id:, filename: )
+      File.open(filename, 'rb') do |fin|
+        custom_fields_csv = fin.read
+        args = { 'name' => 'external_file', 'filename' => filename }
+        post(api_query: "account/institution/custom_fields/#{custom_field_id}/items/upload", args: args, data: custom_fields_csv, content_type: 'multipart/form-data', &block)
+      end
     end
 
     # Get institution categories (including parent Categories)
     #
-    # @yield [Hash] { parent_id, id, title }
+    # @yield [Array] [ { parent_id: 1, id: 11, title: "Anatomy", path:"/450/1024/6532", source_id: "300204", taxonomy_id: 4 } ]
     def categories(&block)
       get(api_query: 'account/categories', &block)
     end
 
     # Get the groups for which the account has administrative privileges (assigned and inherited).
     #
-    # @yield [Hash] { id, name, resource_id, parent_id, association_criteria }
+    # @yield [Array] [ { id: 1, name: "Materials", resource_id: "string", parent_id: 0, association_criteria: "IT" } ]
     def groups(&block)
       get(api_query: 'account/groups', &block)
     end
 
+    # Get the institional account group's embargo options (IP Ranges)
+    #
+    # @param group_id [Integer]
+    # @yield [Array] list of embargo ip ranges [ {id:, type: ip_range, ip_name: Figshare_IP_Range} ]
+    def group_embargo_options(group_id:, &block)
+      get(api_query: "account/institution/groups/#{group_id}/embargo_options", &block)
+    end
+
     # Get the roles available for groups and the institution group.
     #
-    # @yield [Hash] { id, name, category, description }
+    # @yield [Array] [ { id:, name:, category:, description: } ]
     def roles(&block)
       get(api_query: 'account/roles', &block)
     end
 
     # Get the accounts for which the account has administrative privileges (assigned and inherited).
+    # Accounts are returned in account id order, and there is a 9000 user upper limit. See id_gte.
     #
     # @param is_active [Boolean] user account is active
     # @param institution_user_id [String] As set in the HR upload
     # @param email [String] as set in the HR upload
-    # @yield [Hash] { id, first_name, last_name, institution_id, email, active, institution_user_id }
-    def accounts(is_active: nil, institution_user_id: nil, email: nil, &block)
+    # @param id_lte [Integer] ID is <= Introduced to get around the buffer limit of 9000 users
+    # @param id_gte [Integer] ID is >= Introduced to get around the buffer limit of 9000 users
+    # @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:, first_name:, last_name:, institution_id:, email:, active:, institution_user_id:, quota:, used_quota:, user_id:, orcid_id: }]
+    def accounts( is_active: nil,
+                  institution_user_id: nil,
+                  email: nil,
+                  id_lte: nil,
+                  id_gte: nil,
+                  page: nil,
+                  page_size: nil,
+                  offset: nil,
+                  limit: nil,
+                  cursor_pagination: true,
+                  &block
+                )
       args = {}
       args['is_active'] = is_active unless is_active.nil?
       args['institution_user_id'] = institution_user_id unless institution_user_id.nil?
       args['email'] = email unless email.nil?
-      get_paginate(api_query: 'account/institution/accounts', args: args, &block)
+      args['id_lte'] = id_lte unless id_lte.nil?
+      args['id_gte'] = id_gte unless id_gte.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?
+      if cursor_pagination
+        highest_id_gte = 0
+        args['id_lte'] = nil
+        args['page_size'] = 100
+        loop do
+          count = 0
+          args['page'] = 1
+          args['id_gte'] = highest_id_gte + 1
+          get_paginate(api_query: 'account/institution/accounts', args: args, once_only: true) do |account|
+            next if account.nil? || account['id'].nil?
+
+            count += 1
+            highest_id_gte = account['id'].to_i if highest_id_gte < account['id'].to_i
+            yield account
+          end
+          break if count < 100 # Didn't reach the page_size limit.
+        end
+      else # Do it the old broken way (Pagination only works for the first 9000 entries)
+        get_paginate(api_query: 'account/institution/accounts', args: args, &block)
+      end
     end
 
     # Create new Institution Account
@@ -106,7 +203,16 @@ module Figshare
     # @param symplectic_user_id [string]
     # @param quota [Integer] Figshare user quota
     # @param is_active [Boolean]
-    def account_create(email:, first_name:, last_name:, group_id:, institution_user_id: nil, symplectic_user_id: nil, quota: nil, is_active: true, &block)
+    def account_create( email:,
+                        first_name:,
+                        last_name:,
+                        group_id:,
+                        institution_user_id: nil,
+                        symplectic_user_id: nil,
+                        quota: nil,
+                        is_active: true,
+                        &block
+                      )
       args = {}
       args['email'] = email unless email.nil?
       args['first_name'] = first_name unless first_name.nil?
@@ -116,11 +222,12 @@ module Figshare
       args['symplectic_user_id'] = symplectic_user_id unless symplectic_user_id.nil?
       args['quota'] = quota unless quota.nil?
       args['is_active'] = is_active unless is_active.nil?
-      post(api_query: "account/institution/accounts/#{account_id}", args: args, &block)
+      post(api_query: 'account/institution/accounts', args: args, &block)
     end
 
     # Update Institution Account
     #
+    # @param account_id [Integer] Whose account
     # @param email [String]
     # @param first_name [String]
     # @param last_name [String]
@@ -129,7 +236,17 @@ module Figshare
     # @param symplectic_user_id [string]
     # @param quota [Integer] Figshare user quota
     # @param is_active [Boolean]
-    def account_update(email:, first_name:, last_name:, group_id:, institution_user_id: nil, symplectic_user_id: nil, quota: nil, is_active: true, &block)
+    def account_update( account_id:,
+                        email: nil,
+                        first_name: nil,
+                        last_name: nil,
+                        group_id: nil,
+                        institution_user_id: nil,
+                        symplectic_user_id: nil,
+                        quota: nil,
+                        is_active: true,
+                        &block
+                      )
       args = {}
       args['email'] = email unless email.nil?
       args['first_name'] = first_name unless first_name.nil?
@@ -142,7 +259,7 @@ module Figshare
       put(api_query: "account/institution/accounts/#{account_id}", args: args, &block)
     end
 
-    # Get institution Account Group Roles
+    # Get institution Account Group Roles for an account
     #
     # @param account_id [Integer] Figshare user account id
     # @yield [Hash] { role_id [ { category, id, name }, ... ], ... }
@@ -153,7 +270,7 @@ module Figshare
     # Add Institution Account Group Roles
     #
     # @param account_id [Integer] Figshare user account id
-    # @param body [Hash] see figshare api docs
+    # @param body [Hash] see figshare api cryptic docs  { "2": [ 2, 7], "3": [7,9] }. Array of roles, per group
     def group_roles_add(account_id:, body:, &block)
       post(api_query: "account/institution/roles/#{account_id}", args: body, &block)
     end
@@ -163,12 +280,9 @@ module Figshare
     # @param account_id [Integer] Figshare user account id
     # @param role_id [Integer] Figshare role id
     # @param group_id [Integer] Figshare group id
-    def group_role_delete( role_id, group_id, account_id:, &block)
+    def group_role_delete( account_id:, role_id:, group_id:, &block)
       args = {}
-      args['account_id'] = account_id unless account_id.nil?
-      args['role_id'] = role_id unless role_id.nil?
-      args['group_id'] = group_id unless group_id.nil?
-      delete(api_query: 'account/institution/roles/{account_id}', args: args, &block)
+      delete(api_query: "account/institution/roles/#{account_id}/#{group_id}/#{role_id}", args: args, &block)
     end
 
     # Get the accounts for which the account has administrative privileges (assigned and inherited).
@@ -176,14 +290,31 @@ module Figshare
     # @param is_active [Boolean] user account is active
     # @param institution_user_id [String] As set in the HR upload
     # @param email [String] as set in the HR upload
-    # @yield [Hash] {id, first_name, last_name, institution_id, email, active, institution_user_id}
-    def account_search(search_for: nil, is_active: nil, institution_user_id: nil, email: nil, &block)
+    # @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, first_name, last_name, institution_id, email, active, institution_user_id, quota, used_quota, user_id, orcid_id}
+    def account_search( search_for: nil,
+                        is_active: nil,
+                        institution_user_id: nil,
+                        email: nil,
+                        page: nil,
+                        page_size: nil,
+                        offset: nil,
+                        limit: nil,
+                        &block
+                      )
       args = {}
       args['search_for'] = search_for unless search_for.nil?
       args['is_active'] = is_active unless is_active.nil?
       args['institution_user_id'] = institution_user_id unless institution_user_id.nil?
       args['email'] = email unless email.nil?
-      post(api_query: 'account/institution/accounts/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/institution/accounts/search', args: args, &block)
     end
 
     # Get institution user information using the account_id
@@ -198,13 +329,23 @@ module Figshare
     #
     # @param group_id [Integer] Figshare group ID
     # @param article_id [Integer] Figshare article ID
-    # @param status [String] pending, approved, rejected, closed
+    # @param status [String] One of: pending, approved, rejected, closed
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @yield [Hash] {id, group_id, account_id, assigned_to, article_id, version, comment_count, status, created_date. modified_date }
-    def curation_review(group_id: nil, article_id: nil, status: nil, &block)
+    def curation_review(  group_id: nil,
+                          article_id: nil,
+                          status: nil,
+                          offset: nil,
+                          limit: nil,
+                          &block
+                       )
       args = {}
       args['group_id'] = group_id unless group_id.nil?
       args['article_id'] = article_id unless article_id.nil?
       args['status'] = status unless status.nil?
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
       # Odd one, as has offset,limit not page,page_size
       get_paginate(api_query: 'account/institution/reviews', args: args, by_offset: true, &block)
     end
@@ -220,10 +361,15 @@ module Figshare
     # Get a certain curation review's comments.
     #
     # @param curation_id [Integer] Figshare curation ID
+    # @param offset [Numeric] offset is 0 based.  Offset and Limit go together
+    # @param limit [Numeric]
     # @yield [Hash] { id, account_id, type, text}
-    def curation_review_comments(curation_id:, &block)
+    def curation_review_comments(curation_id:, offset: nil, limit: nil, &block)
       # Odd one, as has offset,limit not page,page_size.
-      get_paginate(api_query: "account/institution/reviews/#{curation_id}/comments", by_offset: true, &block)
+      args = {}
+      args['offset'] = offset unless offset.nil?
+      args['limit'] = limit unless limit.nil?
+      get_paginate(api_query: "account/institution/review/#{curation_id}/comments", args: args, by_offset: true, &block)
     end
 
     # Add a new comment to the review.
@@ -231,8 +377,7 @@ module Figshare
     # @param curation_id [Integer] Figshare curation ID
     # @param comment [String] Comment text
     def curation_review_comments_update(curation_id:, comment:, &block)
-      # Odd one, as has offset,limit not page,page_size.
-      post(api_query: "account/institution/reviews/#{curation_id}/comments", args: { 'text' => comment }, &block)
+      post(api_query: "account/institution/review/#{curation_id}/comments", args: { 'text' => comment }, &block)
     end
   end
 end

data/lib/other.rb

@@ -2,10 +2,18 @@ module Figshare
   # Misc Figshare API calls that they have classified as Other.
   #
   class Other < Base
+    # Fetch item types
+    #
+    # @param group_id [Integer]
+    # @yield [Array] [{id: 0, name:, string_id:, icon:, public_description:, is_selectable: , url_name: } ]
+    def item_types(group_id:, &block)
+      get(api_query: 'item_types', args: { 'group_id' => group_id }, &block)
+    end
+
     # Search from funding records
     #
     # @param search_for [String] string to search for
-    # @yield [Hash] {id, title, grant_code, funder_name, is_user_defined, url}
+    # @yield [Array] [{id, title, grant_code, funder_name, is_user_defined, url}]
     def search_funding(search_for:, &block)
       post(api_query: 'account/funding/search', args: { 'search_for' => search_for }, &block)
     end
@@ -21,21 +29,21 @@ module Figshare
 
     # Get public categories
     #
-    # @yield [Hash] {parent_id, id, title}
+    # @yield [Array] [{parent_id:, id:, title:, path:, source_id:, taxonomy_id:}]
     def public_categories
       get(api_query: 'categories', &block)
     end
 
     # Get public licenses
     #
-    # @yield [Hash] {value, name, url}
+    # @yield [Array] [{value:, name:, url:}]
     def public_licenses
       get(api_query: 'licenses', &block)
     end
 
     # Get private licenses
     #
-    # @yield [Hash] {value, name, url}
+    # @yield [Array] [{value:, name:, url:}]
     def private_account_licenses
       get(api_query: 'account/licenses', &block)
     end