notion_ruby_mapping 4.0.2 → 4.2.0

data/lib/notion_ruby_mapping/objects/file_object.rb

@@ -1,11 +1,19 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # TextObject
+  # Represents file information shared by file-based blocks and file properties.
+  #
+  # Use the owning block or property to update a file. This object is primarily
+  # intended for inspecting the current file representation.
   class FileObject
-    # @param [String] url
-    # @return [TextObject]
-    def initialize(url: nil, file_upload_object: nil, json: {})
+    # Creates a file representation.
+    #
+    # @param url [String, nil] external file URL
+    # @param file_upload_object [FileUploadObject, nil] uploaded file
+    # @param json [Hash, nil] file JSON returned by the Notion API
+    # @raise [ArgumentError] if no file source is provided
+    # @api private
+    def initialize(url: nil, file_upload_object: nil, json: nil)
       if url
         @type = "external"
         @url = url
@@ -17,49 +25,66 @@ module NotionRubyMapping
         @url = json[@type]["url"]
         @expiry_time = json[@type]["expiry_time"]
       else
-        raise StandardError, "FileObject requires url: or json:"
+        raise ArgumentError, "FileObject requires url:, file_upload_object:, or json:"
       end
-      @will_update = false
     end
-    attr_reader :will_update, :url, :type, :file_upload_object
+    # @return [String, nil] current file URL
+    attr_reader :url
 
-    # @param [FileObject, FileUploadObject, String] url_or_fuo_or_fo
-    # @return [FileObject] self or created FileObject
-    # @see https://www.notion.so/hkob/FileObject-6218c354e985423a90904f47a985be33#54b37c567e1d4dfcab06f6d8f8fd412e
-    def self.file_object(url_or_fuo_or_fo)
-      if url_or_fuo_or_fo.is_a? FileUploadObject
-        FileObject.new file_upload_object: url_or_fuo_or_fo
-      elsif url_or_fuo_or_fo.is_a? FileObject
-        url_or_fuo_or_fo
+    # @return [String] file type: `"external"`, `"file"`, or `"file_upload"`
+    attr_reader :type
+
+    # @return [FileUploadObject, nil] current file upload object
+    attr_reader :file_upload_object
+
+    # Converts a supported file value to a file object.
+    #
+    # @param value [String, FileUploadObject, FileObject]
+    #   external URL, uploaded file, or existing file object
+    # @return [FileObject] converted file object
+    # @api private
+    def self.file_object(value)
+      if value.is_a? FileUploadObject
+        FileObject.new file_upload_object: value
+      elsif value.is_a? FileObject
+        value
       else
-        FileObject.new url: url_or_fuo_or_fo
+        FileObject.new url: value
       end
     end
 
-    # @return [TrueClass, FalseClass] true if "type" is "external"
+    # Checks whether the file uses an external URL.
+    #
+    # @return [Boolean] true if the file type is `"external"`
     def external?
       @type == "external"
     end
 
-    # @param [FileUploadObject] fuo
-    def file_upload_object=(fuo)
-      @file_upload_object = fuo
+    # Replaces the current representation with an uploaded file.
+    #
+    # @param file_upload_object [FileUploadObject] uploaded file
+    # @api private
+    def file_upload_object=(file_upload_object)
+      @file_upload_object = file_upload_object
       @type = "file_upload"
       @url = nil
       @expiry_time = nil
-      @will_update = true
     end
 
-    # @param [String] url
-    # @see https://www.notion.so/hkob/FileObject-6218c354e985423a90904f47a985be33#6b841f75d0234a1aac93fb54348abb96
+    # Replaces the current representation with an external URL.
+    #
+    # @param url [String] external file URL
+    # @api private
     def url=(url)
       @url = url
       @type = "external"
       @expiry_time = nil
-      @will_update = true
     end
 
-    # @return [Hash]
+    # Builds the Notion API file JSON.
+    #
+    # @return [Hash{String => Object}] file JSON
+    # @api private
     def property_values_json
       if @type == "file_upload"
         {

data/lib/notion_ruby_mapping/objects/file_upload_object.rb

@@ -1,86 +1,132 @@
 # frozen_string_literal: true
 
-class FileUploadObject
-  MAX_SIZE = 10 * 1024 * 1024 # 10 MB
-  # @param [String] fname
-  def initialize(fname:, external_url: nil)
-    @fname = fname
-    if external_url
-      payload = {mode: "external_url", external_url: external_url, filename: fname}
-      create payload
-    else
-      raise StandardError, "FileUploadObject requires a valid file name: #{fname}" unless File.exist?(fname)
+module NotionRubyMapping
+  # Uploads a local or external file to Notion.
+  #
+  # Creating an instance starts the upload immediately. Large local files are
+  # split into multiple parts before being uploaded.
+  class FileUploadObject
+    # Maximum size of each upload part.
+    MAX_SIZE = 10 * 1024 * 1024
 
-      @file_size = File.size fname
-      @number_of_parts = (@file_size - 1) / MAX_SIZE + 1
-      payload = if @number_of_parts == 1
-                  {}
-                else
-                  {number_of_parts: @number_of_parts, mode: "multi_part",
-                   filename: File.basename(@fname)}
-                end
-      create payload
-      if @number_of_parts == 1
-        single_file_upload
+    # Creates and uploads a file.
+    #
+    # When +external_url+ is provided, +fname+ is used as the filename sent to
+    # Notion. Otherwise, +fname+ must point to an existing local file.
+    #
+    # @param fname [String] local file path or filename
+    # @param external_url [String, nil] URL of a file for Notion to import
+    # @raise [StandardError] if the local file does not exist
+    # @raise [ArgumentError] if the local file is empty
+    def initialize(fname:, external_url: nil)
+      @fname = fname
+      if external_url
+        payload = {mode: "external_url", external_url: external_url, filename: fname}
+        create payload
       else
-        @temp_files = FileUploadObject.split_to_small_files(@fname, MAX_SIZE)
-        @temp_files.each_with_index do |temp_file, i|
-          single_file_upload temp_file.path, i + 1
-          temp_file.close
-          temp_file.unlink
+        raise StandardError, "FileUploadObject requires a valid file name: #{fname}" unless File.exist?(fname)
+
+        @file_size = File.size fname
+        raise ArgumentError, "FileUploadObject requires a non-empty file: #{fname}" if @file_size.zero?
+
+        @number_of_parts = (@file_size - 1) / MAX_SIZE + 1
+        payload = if @number_of_parts == 1
+                    {}
+                  else
+                    {number_of_parts: @number_of_parts, mode: "multi_part",
+                     filename: File.basename(@fname)}
+                  end
+        create payload
+        if @number_of_parts == 1
+          single_file_upload
+        else
+          @temp_files = FileUploadObject.split_to_small_files(@fname, MAX_SIZE)
+          @temp_files.each_with_index do |temp_file, i|
+            single_file_upload temp_file.path, i + 1
+            temp_file.close
+            temp_file.unlink
+          end
+          NotionRubyMapping::NotionCache.instance.complete_a_file_upload_request @id
         end
-        NotionRubyMapping::NotionCache.instance.complete_a_file_upload_request @id
       end
     end
-  end
-  attr_reader :id, :fname, :status
+    # @return [String] file upload ID
+    attr_reader :id
 
-  # @return [FileUploadObject]
-  def create(payload)
-    nc = NotionRubyMapping::NotionCache.instance
-    response = nc.create_file_upload_request(payload)
-    @id = nc.hex_id response["id"]
-    @status = response["status"]
-  end
+    # @return [String] local file path or filename
+    attr_reader :fname
 
-  def reload
-    nc = NotionRubyMapping::NotionCache.instance
-    response = nc.file_upload_request @id
-    @status = response["status"]
-    self
-  end
+    # @return [String] last retrieved upload status
+    attr_reader :status
 
-  # @param [String] fname
-  # @param [Integer, NilClass] part_number
-  def single_file_upload(fname = @fname, part_number = 0)
-    if @number_of_parts > 1
-      options = {"part_number" => part_number}
-      status = "pending"
-    else
-      options = {}
-      status = "uploaded"
+    # Creates a file upload through the Notion API.
+    #
+    # @param payload [Hash] file upload creation payload
+    # @return [String] initial upload status
+    # @api private
+    def create(payload)
+      nc = NotionRubyMapping::NotionCache.instance
+      response = nc.create_file_upload_request(payload)
+      @id = nc.hex_id response["id"]
+      @status = response["status"]
     end
-    nc = NotionRubyMapping::NotionCache.instance
-    response = nc.send_file_upload_request fname, @id, options
-    return if nc.hex_id(response["id"]) == @id && response["status"] == status
 
-    raise StandardError, "File upload failed: #{response}"
-  end
+    # Reloads the current upload status from Notion.
+    #
+    # @return [FileUploadObject] self
+    def reload
+      nc = NotionRubyMapping::NotionCache.instance
+      response = nc.file_upload_request @id
+      @status = response["status"]
+      self
+    end
 
-  def self.split_to_small_files(org_file, max_size = MAX_SIZE)
-    raise StandardError, "File does not exist: #{org_file}" unless File.exist?(org_file)
+    # Uploads a local file or one part of a multipart upload.
+    #
+    # @param fname [String] path of the file to upload
+    # @param part_number [Integer] multipart part number
+    # @return [void]
+    # @raise [StandardError] if the upload response is invalid
+    # @api private
+    def single_file_upload(fname = @fname, part_number = 0)
+      if @number_of_parts > 1
+        options = {"part_number" => part_number}
+        status = "pending"
+      else
+        options = {}
+        status = "uploaded"
+      end
+      nc = NotionRubyMapping::NotionCache.instance
+      response = nc.send_file_upload_request fname, @id, options
+      return if nc.hex_id(response["id"]) == @id && response["status"] == status
+
+      raise StandardError, "File upload failed: #{response}"
+    end
+
+    # Splits a file into temporary files.
+    #
+    # The caller is responsible for closing and deleting the returned files.
+    #
+    # @param org_file [String] path of the original file
+    # @param max_size [Integer] maximum size of each part in bytes
+    # @return [Array<Tempfile>] temporary file parts
+    # @raise [StandardError] if the original file does not exist
+    # @api private
+    def self.split_to_small_files(org_file, max_size = MAX_SIZE)
+      raise StandardError, "File does not exist: #{org_file}" unless File.exist?(org_file)
 
-    temp_files = []
-    File.open(org_file, "rb") do |file|
-      until file.eof?
-        chunk = file.read(max_size)
-        temp_file = Tempfile.new("part_")
-        temp_file.binmode
-        temp_file.write(chunk)
-        temp_file.rewind
-        temp_files << temp_file
+      temp_files = []
+      File.open(org_file, "rb") do |file|
+        until file.eof?
+          chunk = file.read(max_size)
+          temp_file = Tempfile.new("part_")
+          temp_file.binmode
+          temp_file.write(chunk)
+          temp_file.rewind
+          temp_files << temp_file
+        end
       end
+      temp_files
     end
-    temp_files
   end
 end

data/lib/notion_ruby_mapping/properties/button_property.rb

@@ -9,13 +9,13 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Boolean, Hash, nil]
+    # @return [Hash, nil]
     def button
       @json
     end
 
     # @param [String, Symbol] name Property name
-    # @param [Boolean, Hash] json
+    # @param [Hash, nil] json Button property object
     def initialize(name, will_update: false, base_type: "page", property_id: nil, property_cache: nil, json: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
                   property_cache: property_cache

data/lib/notion_ruby_mapping/properties/checkbox_property.rb

@@ -10,7 +10,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Boolean, Hash, nil]
+    # @return [Boolean, Hash] true/false for page property, schema hash for database/data_source property
     # @see https://www.notion.so/hkob/CheckboxProperty-ac1edbdb8e264af5ad1432b522b429fd#20da1bf0cbcc4d4eb22d9125386522c2
     def checkbox
       @json
@@ -18,7 +18,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [Boolean] flag
+    # @param [Boolean] flag Checkbox value. Use true or false.
     # @return [TrueClass, FalseClass] settled value
     # @see https://www.notion.so/hkob/CheckboxProperty-ac1edbdb8e264af5ad1432b522b429fd#f167c85c1d2d40dfb8b3b6ce582e0f15
     def checkbox=(flag)
@@ -39,7 +39,7 @@ module NotionRubyMapping
       @json = if database_or_data_source?
                 json || {}
               else
-                json || false
+                json.nil? ? false : json
               end
     end
 

data/lib/notion_ruby_mapping/properties/created_time_property.rb

@@ -9,7 +9,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Date, Hash]
+    # @return [String, Hash]
     # @see https://www.notion.so/hkob/CreatedTimeProperty-bb979ff02dc04efa9733da1003efa871#f1e80400878346c3a9ba8e32b824ed2b
     def created_time
       @json

data/lib/notion_ruby_mapping/properties/email_property.rb

@@ -13,14 +13,14 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [String, Hash]
+    # @return [String, Hash, nil] email address for page properties, empty hash for database/data source properties
     def email
       @json
     end
 
     ## Page property only methods
 
-    # @param [String] email
+    # @param [String, nil] email
     def email=(email)
       assert_page_property __method__
       @will_update = true
@@ -35,7 +35,7 @@ module NotionRubyMapping
     def initialize(name, will_update: false, base_type: "page", json: nil, property_id: nil, property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
                   property_cache: property_cache
-      @json = json || {}
+      @json = database_or_data_source? ? {} : json
     end
 
     # @return [Hash]

data/lib/notion_ruby_mapping/properties/files_property.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Select property
+  # Files property
   class FilesProperty < Property
     include IsEmptyIsNotEmpty
     TYPE = "files"
@@ -12,6 +12,14 @@ module NotionRubyMapping
 
     ## Page property only methods
 
+    # Removes all files from the property.
+    #
+    # This method replaces the files array with an empty array.
+    def clear
+      assert_page_property __method__
+      self.files = []
+    end
+
     def files=(files = [])
       assert_page_property __method__
       @will_update = true
@@ -22,7 +30,7 @@ module NotionRubyMapping
     def file_names=(file_names = [])
       array_file_names = Array(file_names)
       unless @files.length == array_file_names.length
-        raise StandardError,
+        raise ArgumentError,
               "files and file_names must be the same sizes."
       end
 
@@ -75,19 +83,5 @@ module NotionRubyMapping
       @will_update = false
       self
     end
-
-    protected
-
-    # @param [String] url
-    # @return [Hash]
-    def url_to_hash(url)
-      {
-        "name" => url,
-        "type" => "external",
-        "external" => {
-          "url" => url,
-        },
-      }
-    end
   end
 end

data/lib/notion_ruby_mapping/properties/last_edited_by_property.rb

@@ -33,7 +33,6 @@ module NotionRubyMapping
                 UserObject.new user_id: user_id, json: json
               end
     end
-    attr_reader :user
 
     # @param [Hash] json
     def update_from_json(json)

data/lib/notion_ruby_mapping/properties/last_edited_time_property.rb

@@ -9,7 +9,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Date, Hash]
+    # @return [String, Hash]
     # @see https://www.notion.so/hkob/LastEditedTimeProperty-5058fd594f6748a48fd4db52535f4c18#a7b568bf997c44d49cdbe4bfbf29824e
     def last_edited_time
       @json

data/lib/notion_ruby_mapping/properties/multi_property.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # MultiSelect property
+  # Base class for multi-value properties
   class MultiProperty < Property
     include ContainsDoesNotContain
     include IsEmptyIsNotEmpty

data/lib/notion_ruby_mapping/properties/multi_select_property.rb

@@ -9,12 +9,12 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Array, Hash]
+    # @return [Array<Hash>, Hash] raw multi_select array for page property, or multi_select schema object for database/data_source property
     def multi_select
       @json
     end
 
-    # @return [Array]
+    # @return [Array<String>] selected option names for page property, or schema option names for database/data_source property
     def multi_select_names
       mshs = @base_type == "page" ? @json : @json["options"]
       mshs.map { |h| h["name"] }
@@ -24,30 +24,30 @@ module NotionRubyMapping
 
     # @param [String] name
     # @param [String] color
-    # @return [Array] added array
+    # @return [Array<Hash>] updated multi_select options
     # @see https://www.notion.so/hkob/MultiSelectProperty-b90bba1c55d540ba97131bb013d4ca74#bcac830b00e04cb6bf7dbbb110d95667
     def add_multi_select_option(name:, color:)
       edit_multi_select_options << {"name" => name, "color" => color}
     end
 
-    # @return [Array] copyed multi select options
+    # @return [Array<Hash>] editable multi_select options
     def edit_multi_select_options
       assert_database_or_data_source_property __method__
       @will_update = true
       @json["options"] ||= []
     end
 
-    # @return [Array]
+    # @return [Array<Hash>] schema multi_select options
     # @see https://www.notion.so/hkob/MultiSelectProperty-b90bba1c55d540ba97131bb013d4ca74#5ff6ec299cf64049bde2416f61b30fa9
     def multi_select_options
-      assert_data_source_property __method__
+      assert_database_or_data_source_property __method__
       @json["options"] || []
     end
 
     ## Page property only methods
 
-    # @param [Hash] multi_select
-    # @return [Array, nil] settled array
+    # @param [String, Array<String>, nil] multi_select selected option name or names
+    # @return [Array<Hash>] settled array
     def multi_select=(multi_select)
       assert_page_property __method__
       @will_update = true
@@ -59,8 +59,8 @@ module NotionRubyMapping
     ## Common methods
 
     # @param [String, Symbol] name
-    # @param [Hash] json
-    # @param [Array<String>, String] multi_select
+    # @param [Hash, nil] json
+    # @param [String, Array<String>, nil] multi_select selected option name or names (optional)
     def initialize(name, will_update: false, base_type: "page", json: nil, multi_select: nil,
                    property_id: nil, property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
@@ -89,7 +89,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @return [Hash] created json
+    # @return [Hash] page property values payload
     def property_values_json
       assert_page_property __method__
       {

data/lib/notion_ruby_mapping/properties/number_property.rb

@@ -38,8 +38,8 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [Numeric] num
-    # @return [Numeric] settled number
+    # @param [Numeric, nil] num Number value. nil clears the value.
+    # @return [Numeric, nil] settled number
     # @see https://www.notion.so/hkob/NumberProperty-964ebc1948074d7ca8340187aa352d40#a3f28cc7029046878dfd694b5b33e8d8
     def number=(num)
       assert_page_property __method__

data/lib/notion_ruby_mapping/properties/people_property.rb

@@ -9,7 +9,15 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Array, Hash]
+    # Returns the people assigned to this property.
+    #
+    # For a page property, this returns an array of UserObject instances.
+    # For a database or data source property, this returns the schema payload.
+    #
+    # Do not modify the returned array directly. Use `people=` or `add_person`
+    # to update the property.
+    #
+    # @return [Array<UserObject>, Hash]
     # @see https://www.notion.so/hkob/PeopleProperty-144355d25f0e4feba9ae39fe28ca6ae7#7e3e56c2080d4834902cfa0223e807e5
     def people
       @json
@@ -17,8 +25,13 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [String, NotionRubyMapping::UserObject] user_id_or_uo
-    # @return [Array<UserObject>]
+    # Adds a person to this people property.
+    #
+    # This method marks the property as changed.
+    # This method does not remove duplicate users.
+    #
+    # @param [String, UserObject] user_id_or_uo user ID or user object to add
+    # @return [Array<UserObject>] updated people
     # @see https://www.notion.so/hkob/PeopleProperty-144355d25f0e4feba9ae39fe28ca6ae7#26344b145a254cc58dd845780e0a26ea
     def add_person(user_id_or_uo)
       assert_page_property __method__
@@ -26,8 +39,14 @@ module NotionRubyMapping
       @json << UserObject.user_object(user_id_or_uo)
     end
 
-    # @param [Hash] people
-    # @return [Array, nil] replaced array
+    # Replaces all people in this property.
+    #
+    # Passing nil or an empty array clears the people property.
+    # This method marks the property as changed.
+    #
+    # @param [String, UserObject, Array<String>, Array<UserObject>, nil] people
+    #   user ID, user object, array of them, or nil
+    # @return [Array<UserObject>] replaced people
     # @see https://www.notion.so/hkob/PeopleProperty-144355d25f0e4feba9ae39fe28ca6ae7#815acfef9a664e3e8915fb31b8fefc42
     def people=(people)
       assert_page_property __method__

data/lib/notion_ruby_mapping/properties/phone_number_property.rb

@@ -13,7 +13,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [String, Hash, nil] phone number (Page), {} (Database)
+    # @return [String, Hash, nil] phone number for page properties, empty hash for database/data source properties
     # @see https://www.notion.so/hkob/PhoneNumberProperty-5df14aaa938c4888aecd53ab6752d2e6#40bceda04fe04c64b932d6a1ed180eaa
     def phone_number
       @json
@@ -21,7 +21,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [String] phone_number
+    # @param [String, nil] phone_number
     # @see https://www.notion.so/hkob/PhoneNumberProperty-5df14aaa938c4888aecd53ab6752d2e6#dc7e00e0558d40f79ca5cade1fccef29
     def phone_number=(phone_number)
       assert_page_property __method__