microslop_one_drive 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 200bb46df7cd42f96b656faa27f97694ea62d82e9d3a53bf018e893cf7c4f76c
-  data.tar.gz: f62102a6873bf709511394512e5264788f2316fa85c8e7d45b21ac1243622c39
+  metadata.gz: 263180adfcfe1c3fd07687538f1deae87428df5c8470983fa301fc3348b3f49c
+  data.tar.gz: 9da219ccfd38a57a74a1aac65e945d4e87cdf1eff9c6737e20645cc170d1e0b9
 SHA512:
-  metadata.gz: 0a27663fc00bbacba006ac4ad99d3b110c7ca9dec5d57d1f6c97fc59faef2e52f4efae616b840a90876f17ff956f7cd617241f85dc37f28ddc8a367bf12e3a74
-  data.tar.gz: cd71efcf58b1b77fd4e583a266349b48c578f2f262352008f93380cc8d497c93fc71dbf4d3fdd015d2548ca78de21d61af476c59811621b0acf60bc1cfbe4d59
+  metadata.gz: 7224f1393f2e5421fd02741e0940f4511fb907d991bfab65d9be324c4ee7aeb8a3b6f71f7d5f56d863671318ae3a6f680bef9a696e1673a58fac6289bb7edd7a
+  data.tar.gz: 79a96850a6c4e1a90a156feffd8d5cb2dcf7df80370974766ace9a67e07aa02e75f618e368b432515160e635845475451ea4f556fda8662557f90507685ec256

data/README.md

@@ -16,7 +16,10 @@ gem "microslop_one_drive"
 
 ## Usage
 
-### Create a client
+Here's a quickstart showing listing drives, getting some files in a drive, and getting permissions for some files in
+a batched manner:
+
+### Creating a client
 
 ```rb
 access_token = "..." # Get an access token via OAuth 2.0
@@ -24,115 +27,71 @@ access_token = "..." # Get an access token via OAuth 2.0
 client = MicroslopOneDrive::Client.new(access_token)
 ```
 
-### Get the current user
-
-```rb
-me = client.me
-me.class # => MicroslopOneDrive::User
-me.email_address # => person@example.com
-me.display_name # => Example Person
-```
+### Listing Drives
 
-### Get a list of the user's Drives
+Note: Microsoft will return all Drives a user has access to. Some of these seem to be for internal Microsoft use only
+(they're things like face scans, AI metadata, and other really terrifying and disgusting things). You can use the
+`drive_exists?()` method to check if it's a real drive you can interact with.
 
 ```rb
 drive_list = client.drives
+drive_list.drives.size # => 2
 
-drive_list.class # => MicroslopOneDrive::DriveList
-drive_list.next_page? # => false
-drive_list.drives # => [MicroslopOneDrive::Drive, ...]
-
-drive = drive_list.drives.first
-drive.class # => MicroslopOneDrive::Drive
-drive.identifier # => "0f0**********42"
-drive.name # => "OneDrive"
-drive.url # => "https://my.microsoftpersonalcontent.com/..."
-drive.drive_type # => "personal"
-drive.created_at
-drive.updated_at
+drive = drive_list.drives[1]
+drive.name # => OneDrive
+drive.id # => "0f0**********42"
+
+client.drive_exists?(drive.id) # => true (it's a real Drive)
 ```
 
-### Get a single Drive
+### Listing Drive Items (Folders and Files)
 
 ```rb
-drive = client.drive(drive_id: "0f097********a42")
+page1 = client.delta(drive_id: drive.id)
+page1.items.size # => 200
+
+page1.next_page? # => true
+page2 = client.delta(drive_id: drive.id, token: page1.next_token)
+page2.items.size # => 14
+page2.next_page? # => false
 
-drive.class # => MicroslopOneDrive::Drive
-drive.identifier # => "0f097********a42"
-drive.name # => "OneDrive"
-drive.url # => "https://my.microsoftpersonalcontent.com/personal/..."
-drive.drive_type # => "personal"
+delta_token = page2.delta_token # Save this somewhere and use as "token" in the next client.delta() call so ensure you
+# only get new changes, and don't list the whole drive from the beginning again.
 ```
 
-### Get a delta of changes to a Drive
+### Get Permissions for a single Drive Item
 
 ```rb
-# Initial delta (all current items + token for later)
-drive_item_list = client.delta(drive_id: "0f097********a42")
-
-drive_item_list.class # => MicroslopOneDrive::DriveItemList
-drive_item_list.items # => [MicroslopOneDrive::DriveItem, ...]
+drive_item_list = client.delta(drive_id: drive.id)
+shared_items = drive_item_list.items.select(&:shared?)
 
-drive_item_list.next_page? # => true if more pages
-drive_item_list.next_token # => use with delta(drive_id:, token:) for next page
-drive_item_list.delta_link # => URL for incremental sync (when no next_page?)
-drive_item_list.delta_token # => use with delta(drive_id:, token:) for incremental sync
+example_item = shared_items.first
 
-# Next page (if next_page? was true)
-client.delta(drive_id: "0f097********a42", token: drive_item_list.next_token)
+permission_list = client.permissions(item_id: example_item.id)
+permission = permission_list.first
 
-# Incremental sync (only changes since last delta)
-client.delta(drive_id: "0f097********a42", token: saved_delta_token)
+permission.role # => "write"
+permission.audience.type # => "user"
+permission.audience.id # => "person@example.com"
+permission.audience.display_name # => "Example Person"
+permission.audience.email_address # => "person@example.com"
 ```
 
-Delta items have parent/child set: `item.parent`, `item.children`, and `item.path` (e.g. `"root:/folder/subfolder/file.txt"`).
+### Get Permissions for multiple Drive Items
 
-### Get a DriveItem (file or folder)
+Instead of calling `client.permissions(...)` for each item -- which would make N API calls for N items -- we use
+Microsoft Graph API [batch](https://learn.microsoft.com/en-us/graph/json-batching?tabs=http) feature.
 
 ```rb
-item = client.drive_item(item_id: "F0**********42!sa466********************1479272d27")
-
-item.class # => MicroslopOneDrive::DriveItem
-item.name # => "Getting started with OneDrive.pdf"
-item.identifier # => "F0**********42!sa466********************1479272d27"
-item.url # => "https://onedrive.live.com?cid=..."
-item.file? # => true
-item.folder? # => false
-item.mime_type # => "application/pdf"
-item.size # => 1053417
-item.created_at # => 2026-02-19 07:35:52 UTC
-item.updated_at # => 2026-02-19 07:35:52 UTC
-item.parent_identifier # => "F0**********42!sea8cc6b********************5c639"
-item.deleted? # => false
-item.shared? # => true if the item has sharing info
-item.path # => "root:/Documents/Getting started with OneDrive.pdf" (from delta only; nil for single item)
-item.is_root? # => true for root folder
-```
+drive_item_list = client.delta(drive_id: drive.id)
+shared_items = drive_item_list.items.select(&:shared?)
 
-### Check if a DriveItem exists
+permission_batch = client.batch_permissions(item_ids: shared_items.map(&:id))
 
-```rb
-client.item_exists?(item_id: "F0**********42!sa466********************1479272d27") # => true
-client.item_exists?(item_id: "F0**********42!not-an-item-id") # => false
+# Under the hood, this will batch the shared_items into batches of 20 (the max Microsoft allows on their batch endpoint)
+# and returns an aggregated result.
 ```
 
-### Get permissions for a DriveItem
-
-```rb
-permission_list = client.permissions(item_id: "F0**********42!sa466********************1479272d27")
-permission_list.class # => MicroslopOneDrive::PermissionList
-permission_list.permissions # => [MicroslopOneDrive::Permission, ...]
-
-permission = permission_list.permissions.first
-permission.role # => "write" or "owner" etc.
-permission.audience.type # => "user" or "anyone"
-permission.audience.identifier # => email for user, "anyone_with_the_link" for link
-permission.audience.display_name # => "Amy Smith"
-permission.audience.email_address # => "amy@example.com" (nil for "anyone with the link")
-```
-
-Returns an empty permission list if the item does not exist (404).
-
 ## Contributing
 
 ### Setup

data/lib/microslop_one_drive/audience.rb

@@ -1,10 +1,10 @@
 module MicroslopOneDrive
   class Audience
-    attr_reader :type, :identifier, :display_name, :email_address
+    attr_reader :type, :id, :display_name, :email_address
 
-    def initialize(type:, identifier:, display_name:, email_address: nil)
+    def initialize(type:, id:, display_name:, email_address: nil)
       @type = type
-      @identifier = identifier
+      @id = id
       @display_name = display_name
       @email_address = email_address
     end
@@ -23,7 +23,7 @@ module MicroslopOneDrive
     def self.from_site_user(site_user)
       new(
         type: "user",
-        identifier: site_user.fetch("email"),
+        id: site_user.fetch("email"),
         display_name: site_user.fetch("displayName"),
         email_address: site_user.fetch("email")
       )

data/lib/microslop_one_drive/batch_response.rb

@@ -0,0 +1,13 @@
+module MicroslopOneDrive
+  class BatchResponse
+    attr_reader :responses
+
+    def initialize
+      @responses = []
+    end
+
+    def add_response(response)
+      @responses << response
+    end
+  end
+end

data/lib/microslop_one_drive/client.rb

@@ -1,6 +1,7 @@
 module MicroslopOneDrive
   class Client
     BASE_URL = "https://graph.microsoft.com/v1.0".freeze
+    BATCH_REQUEST_LIMIT = 20.freeze
 
     def initialize(access_token)
       @access_token = access_token
@@ -99,20 +100,75 @@ module MicroslopOneDrive
     def permissions(item_id:)
       response = get(path: "me/drive/items/#{item_id}/permissions", query: {})
 
-      return MicroslopOneDrive::PermissionList.new("value" => []) if response.code == 404
+      if response.code == 404
+        return MicroslopOneDrive::PermissionList.new(drive_item_id: item_id, parsed_response: { "value" => [] })
+      end
 
       handle_error(response) unless response.success?
-      MicroslopOneDrive::PermissionList.new(response.parsed_response)
+
+      MicroslopOneDrive::PermissionList.new(drive_item_id: item_id, parsed_response: response.parsed_response)
+    end
+
+    # Gets the permissions for multiple Drive Items.
+    #
+    # Uses the batch Microsoft Graph API to make multiple API calls in batches of 20 (the max Microsoft allows on their
+    # batch endpoint).
+    #
+    # See: https://learn.microsoft.com/en-us/graph/json-batching
+    #
+    # @param item_ids [Array<String>] The IDs of the Drive Items to get the permissions of.
+    #
+    # @return [Array<MicroslopOneDrive::Permission>]
+    def batch_permissions(item_ids:)
+      requests = item_ids.map { |item_id| { id: item_id, method: "GET", url: "/me/drive/items/#{item_id}/permissions" } }
+      batch_response = batch(requests: requests)
+      successful_responses = batch_response.responses.select(&:success?)
+
+      permission_lists = successful_responses.map do |response|
+        MicroslopOneDrive::PermissionList.new(drive_item_id: response.id, parsed_response: response.body)
+      end
+
+      permission_lists.flat_map(&:permissions)
+    end
+
+    # Makes a batch request to the Microsoft Graph API.
+    #
+    # @param requests [Array<Hash>] The requests to make. Each request should be a hash with the following keys:
+    #   - id: The ID of the request.
+    #   - method: The HTTP method to use for the request.
+    #   - url: The URL to make the request to.
+    #
+    # Note: Microsoft allows a maximum of 20 requests per batch. If you pass more than 20 requests, the client will
+    # make multiple batch requests to Microsoft. This might make this a slow method.
+    #
+    # @return [MicroslopOneDrive::BatchResponse]
+    def batch(requests:)
+      batch_response = MicroslopOneDrive::BatchResponse.new
+
+      # No requests, so simply return an empty batch response:
+      return batch_response if requests.empty?
+
+      batches = requests.each_slice(BATCH_REQUEST_LIMIT).to_a
+      batches.each do |batch|
+        response = post(path: "$batch", body: { requests: batch })
+        handle_error(response) unless response.success?
+        new_responses = response.parsed_response.fetch("responses", [])
+        new_responses.each do |new_response_hash|
+          batch_response.add_response(MicroslopOneDrive::Response.new(new_response_hash))
+        end
+      end
+
+      batch_response
     end
 
     private
 
     def get(path:, query: {})
-      response = HTTParty.get("#{BASE_URL}/#{path}", headers: @headers, query: query)
-
-      @debug_response_writer&.call(path, response.parsed_response)
+      HTTParty.get("#{BASE_URL}/#{path}", headers: @headers, query: query)
+    end
 
-      response
+    def post(path:, body:)
+      HTTParty.post("#{BASE_URL}/#{path}", headers: @headers, body: body)
     end
 
     def handle_error(response)

data/lib/microslop_one_drive/drive.rb

@@ -1,11 +1,11 @@
 module MicroslopOneDrive
   class Drive
-    attr_reader :identifier, :name, :url, :drive_type, :created_at, :updated_at
+    attr_reader :id, :name, :url, :drive_type, :created_at, :updated_at
 
     def initialize(drive_hash)
       @drive_hash = drive_hash
 
-      @identifier = drive_hash.fetch("id", nil)
+      @id = drive_hash.fetch("id", nil)
       @name = drive_hash.fetch("name", nil)
       @url = drive_hash.fetch("webUrl", nil)
       @drive_type = drive_hash.fetch("driveType", nil)

data/lib/microslop_one_drive/drive_item.rb

@@ -2,14 +2,14 @@ module MicroslopOneDrive
   class DriveItem
     DIRECTORY_MIME_TYPE = "inode/directory".freeze
 
-    attr_reader :identifier,
+    attr_reader :id,
                 :name,
                 :created_at,
                 :updated_at,
                 :url,
                 :size,
                 :file_or_folder,
-                :parent_identifier,
+                :parent_id,
                 :mime_type,
                 :parent,
                 :children,
@@ -19,7 +19,7 @@ module MicroslopOneDrive
     def initialize(item_hash)
       @item_hash = item_hash
 
-      @identifier = @item_hash.fetch("id", nil)
+      @id = @item_hash.fetch("id", nil)
       @name = @item_hash.fetch("name", nil)
       @url = @item_hash.fetch("webUrl", nil)
       @size = @item_hash.fetch("size", nil)
@@ -35,7 +35,7 @@ module MicroslopOneDrive
         @mime_type = DIRECTORY_MIME_TYPE
       end
 
-      @parent_identifier = @item_hash.dig("parentReference", "id")
+      @parent_id = @item_hash.dig("parentReference", "id")
 
       @deleted = @item_hash.dig("deleted", "state") == "deleted"
 

data/lib/microslop_one_drive/drive_item_list.rb

@@ -21,8 +21,8 @@ module MicroslopOneDrive
 
     def set_parent_and_child_relationships(items)
       items.each do |item|
-        next if item.parent_identifier.nil?
-        parent = items.find { it.identifier == item.parent_identifier }
+        next if item.parent_id.nil?
+        parent = items.find { it.id == item.parent_id }
         next if parent.nil?
 
         item.set_parent(parent)

data/lib/microslop_one_drive/list_response.rb

@@ -1,10 +1,12 @@
 module MicroslopOneDrive
   class ListResponse
-    attr_reader :next_link, :next_token, :delta_link, :delta_token
+    attr_reader :next_link, :next_token, :delta_link, :delta_token, :context
 
     def initialize(response_hash)
       @response_hash = response_hash
 
+      @context = response_hash.fetch("@odata.context", nil)
+
       @next_link = response_hash.fetch("@odata.nextLink", nil)
       @next_token = @next_link.split("?token=").last if @next_link && !@next_link.empty?
 

data/lib/microslop_one_drive/permission.rb

@@ -1,9 +1,10 @@
 module MicroslopOneDrive
   class Permission
-    attr_reader :identifier, :role, :audience
+    attr_reader :id, :drive_item_id, :role, :audience
 
-    def initialize(identifier:, role:, audience:)
-      @identifier = identifier
+    def initialize(id:, drive_item_id:, role:, audience:)
+      @id = id
+      @drive_item_id = drive_item_id
       @role = role
       @audience = audience
     end

data/lib/microslop_one_drive/permission_list.rb

@@ -2,24 +2,28 @@ module MicroslopOneDrive
   class PermissionList < ListResponse
     attr_reader :permissions
 
-    def initialize(parsed_response)
+    def initialize(drive_item_id:, parsed_response: )
       super(parsed_response)
 
+      @drive_item_id = drive_item_id
       @parsed_response = parsed_response
-      @permissions = build_permissions
+      @permissions = build_permissions(@drive_item_id, @parsed_response)
     end
 
     private
 
-    def build_permissions
-      value_list = @parsed_response.is_a?(Array) ? @parsed_response : @parsed_response.fetch("value", [])
-      permission_batches = value_list.map { MicroslopOneDrive::PermissionBatch.new(it) }
+    def build_permissions(drive_item_id, parsed_response)
+      value_list = parsed_response.is_a?(Array) ? parsed_response : parsed_response.fetch("value", [])
+
+      permission_sets = value_list.map do
+        MicroslopOneDrive::PermissionSet.new(drive_item_id: drive_item_id, parsed_response: it)
+      end
 
       # At this stage, the permissions could contain multiple Audiences for the same Permission.
       # This is because OneDrive can return multiple permissions for the same thing.
       # For example, a file shared with one person and a public link will return in a single permission object.
-      # We therefore need to "explode" the permissions into multiple permissions, one for each Audience.
-      permission_batches.flat_map(&:to_permissions)
+      # We therefore need to "explode" the permission sets into multiple permissions, one for each Audience.
+      permission_sets.flat_map(&:to_permissions)
     end
   end
 end

data/lib/microslop_one_drive/{permission_batch.rb → permission_set.rb}

@@ -1,17 +1,18 @@
 module MicroslopOneDrive
-  class PermissionBatch
-    attr_reader :identifier, :role, :audiences
+  class PermissionSet
+    attr_reader :id, :role, :audiences
 
-    def initialize(parsed_response)
+    def initialize(drive_item_id:, parsed_response:)
       @parsed_response = parsed_response
 
-      @identifier = @parsed_response.fetch("id", nil)
+      @drive_item_id = drive_item_id
+      @id = @parsed_response.fetch("id", nil)
       @role = build_role
       @audiences = build_audiences
     end
 
     def to_permissions
-      @audiences.map { Permission.new(identifier: @identifier, role: @role, audience: it) }
+      @audiences.map { Permission.new(id: @id, drive_item_id: @drive_item_id, role: @role, audience: it) }
     end
 
     private
@@ -50,7 +51,7 @@ module MicroslopOneDrive
       [
         Audience.new(
           type: "anyone",
-          identifier: "anyone_with_the_link",
+          id: "anyone_with_the_link",
           display_name: "Anyone with the link",
           email_address: nil
         )

data/lib/microslop_one_drive/response.rb

@@ -0,0 +1,16 @@
+module MicroslopOneDrive
+  class Response
+    attr_reader :id, :status, :headers, :body
+
+    def initialize(response_hash)
+      @id = response_hash.fetch("id")
+      @status = response_hash.fetch("status")
+      @headers = response_hash.fetch("headers")
+      @body = response_hash.fetch("body")
+    end
+
+    def success?
+      @status.between?(200, 299)
+    end
+  end
+end

data/lib/microslop_one_drive/version.rb

@@ -1,3 +1,3 @@
 module MicroslopOneDrive
-  VERSION = "1.2.0"
+  VERSION = "2.0.0"
 end

data/lib/microslop_one_drive.rb

@@ -11,7 +11,9 @@ require_relative "microslop_one_drive/drive"
 require_relative "microslop_one_drive/drive_item"
 require_relative "microslop_one_drive/drive_item_list"
 require_relative "microslop_one_drive/permission_list"
-require_relative "microslop_one_drive/permission_batch"
+require_relative "microslop_one_drive/permission_set"
 require_relative "microslop_one_drive/permission"
 require_relative "microslop_one_drive/audience"
+require_relative "microslop_one_drive/batch_response"
+require_relative "microslop_one_drive/response"
 require_relative "microslop_one_drive/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microslop_one_drive
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Bradley Marques
@@ -90,6 +90,7 @@ files:
 - README.md
 - lib/microslop_one_drive.rb
 - lib/microslop_one_drive/audience.rb
+- lib/microslop_one_drive/batch_response.rb
 - lib/microslop_one_drive/client.rb
 - lib/microslop_one_drive/drive.rb
 - lib/microslop_one_drive/drive_item.rb
@@ -98,8 +99,9 @@ files:
 - lib/microslop_one_drive/errors/client_error.rb
 - lib/microslop_one_drive/list_response.rb
 - lib/microslop_one_drive/permission.rb
-- lib/microslop_one_drive/permission_batch.rb
 - lib/microslop_one_drive/permission_list.rb
+- lib/microslop_one_drive/permission_set.rb
+- lib/microslop_one_drive/response.rb
 - lib/microslop_one_drive/user.rb
 - lib/microslop_one_drive/utils.rb
 - lib/microslop_one_drive/version.rb