notion_ruby_mapping 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 366fc4989968bff0fb71d9376b58d3e270fa3e7d91581d37ab75653ec06cb8e3
-  data.tar.gz: e36897b1704fafa277c1996459d148abac1fcf03d62d9e23a8ee67a7325e9a11
+  metadata.gz: 4d8cbce3013176a87d6e023e5bbbd0b5ae6f5c43b437f50c3c6df468ce302d19
+  data.tar.gz: 0ea1f4d67320d4039a42eb156ba03a29595a4362c51a44f7541a874c735c257b
 SHA512:
-  metadata.gz: 531c093bf3a67cf10dba9208c1321c6f3a8d35f808195167947f761563cc961e3bac59be090c70dc7bfdee1f453bba964d160f912ad035ebdc114d441541765d
-  data.tar.gz: 3e7f35ff1b8bbcfc51052f34cc873da0f4436175faced7ac12140c34d0dff4b91f83b555ea888483643d068485c43a23714b7186dd9b8b950d957759a7c347dc
+  metadata.gz: 05a4e8f93a32115e06047aa0324879e63c5ec761d7b98e1cfc7c1df76033389705d1a25ca0b79a1b657dfb4df27b80fa4eeb0793ec21be359d3c2105cbe3f98c
+  data.tar.gz: cc86a8c085ed3da0b7905560c4f92ec8c627739480c3ee13a951f9b9c82bf0ec5cf042f0d888af7bc98a9ecaee788282d042b4de7961852c9cd3407ed8389ab6

data/README.md

@@ -143,6 +143,7 @@ NotionRubyMapping.configuration { |c| c.notion_token = ENV["NOTION_API_TOKEN"] }
 
 ## 3. ChangeLog
 
+- 2026/9/7 [v4.2.0] Refactor file handling (move FileUploadObject into NotionRubyMapping, remove FileObject update tracking, and reject missing or empty file sources)
 - 2026/8/23 [v4.1.0] Refactor Property base class (remove def_delegators and contents?, raise for unsupported property type)
 - 2026/7/14 [v4.0.2] Add clear method for DateProperty
 - 2026/5/4 [v4.0.1] Add retrieve / update / delete a comment

data/lib/notion_ruby_mapping/blocks/block.rb

@@ -14,54 +14,10 @@ module NotionRubyMapping
     end
     attr_reader :can_have_children, :can_append, :type, :rich_text_array, :url, :caption, :color, :language
 
-    def self.type2class(type, has_children = false)
-      @type2class ||= {
-        false => {
-          audio: AudioBlock,
-          bookmark: BookmarkBlock,
-          breadcrumb: BreadcrumbBlock,
-          bulleted_list_item: BulletedListItemBlock,
-          callout: CalloutBlock,
-          child_database: ChildDatabaseBlock,
-          child_page: ChildPageBlock,
-          code: CodeBlock,
-          column: ColumnBlock,
-          column_list: ColumnListBlock,
-          divider: DividerBlock,
-          embed: EmbedBlock,
-          equation: EquationBlock,
-          file: FileBlock,
-          heading_1: Heading1Block,
-          heading_2: Heading2Block,
-          heading_3: Heading3Block,
-          heading_4: Heading4Block,
-          image: ImageBlock,
-          link_preview: LinkPreviewBlock,
-          link_to_page: LinkToPageBlock,
-          numbered_list_item: NumberedListItemBlock,
-          paragraph: ParagraphBlock,
-          pdf: PdfBlock,
-          quote: QuoteBlock,
-          synced_block: SyncedBlock,
-          table: TableBlock,
-          table_row: TableRowBlock,
-          table_of_contents: TableOfContentsBlock,
-          to_do: ToDoBlock,
-          toggle: ToggleBlock,
-          video: VideoBlock,
-        },
-        true => {
-          heading_1: ToggleHeading1Block,
-          heading_2: ToggleHeading2Block,
-          heading_3: ToggleHeading3Block,
-          heading_4: ToggleHeading4Block,
-        },
-      }
-      @klass = @type2class[has_children][type.to_sym] || @type2class[false][type.to_sym] || Block
-    end
-
     def self.decode_block(json)
-      type2class(json["type"], json["has_children"]).new json: json
+      type = json["type"]
+      is_toggleable = !!(json[type] && json[type]["is_toggleable"])
+      type2class(type, is_toggleable).new json: json
     end
 
     # @see https://www.notion.so/hkob/Block-689ad4cbff50404d8a1baf67b6d6d78d#298916c7c379424682f39ff09ee38544
@@ -101,7 +57,7 @@ module NotionRubyMapping
 
     # @return [NotionRubyMapping::RichTextArray]
     def decode_block_caption
-      @caption = RichTextArray.new "caption", json: @json[type]["caption"] if @json[type]["caption"]
+      @caption = RichTextArray.new "caption", json: @json[type]["caption"] || []
     end
 
     # @return [String]
@@ -154,5 +110,52 @@ module NotionRubyMapping
       @color = color
       self
     end
+
+    def self.type2class(type, is_toggleable = false)
+      @type2class ||= {
+        false => {
+          audio: AudioBlock,
+          bookmark: BookmarkBlock,
+          breadcrumb: BreadcrumbBlock,
+          bulleted_list_item: BulletedListItemBlock,
+          callout: CalloutBlock,
+          child_database: ChildDatabaseBlock,
+          child_page: ChildPageBlock,
+          code: CodeBlock,
+          column: ColumnBlock,
+          column_list: ColumnListBlock,
+          divider: DividerBlock,
+          embed: EmbedBlock,
+          equation: EquationBlock,
+          file: FileBlock,
+          heading_1: Heading1Block,
+          heading_2: Heading2Block,
+          heading_3: Heading3Block,
+          heading_4: Heading4Block,
+          image: ImageBlock,
+          link_preview: LinkPreviewBlock,
+          link_to_page: LinkToPageBlock,
+          numbered_list_item: NumberedListItemBlock,
+          paragraph: ParagraphBlock,
+          pdf: PdfBlock,
+          quote: QuoteBlock,
+          synced_block: SyncedBlock,
+          table: TableBlock,
+          table_row: TableRowBlock,
+          table_of_contents: TableOfContentsBlock,
+          to_do: ToDoBlock,
+          toggle: ToggleBlock,
+          video: VideoBlock,
+        },
+        true => {
+          heading_1: ToggleHeading1Block,
+          heading_2: ToggleHeading2Block,
+          heading_3: ToggleHeading3Block,
+          heading_4: ToggleHeading4Block,
+        },
+      }
+      @type2class[is_toggleable][type.to_sym] || @type2class[false][type.to_sym] || Block
+    end
+    private_class_method :type2class
   end
 end

data/lib/notion_ruby_mapping/blocks/breadcrumb_block.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Notion block
+  # Notion breadcrumb block
   class BreadcrumbBlock < Block
-    # @return [String (frozen)]
+    # @return [String] block type
     def type
       "breadcrumb"
     end
 
-    # @param [Boolean] not_update false when update
-    # @return [Hash{String (frozen)->Hash}]
+    # @param [Boolean] not_update true for a full block payload; false for an update payload
+    # @return [Hash{String => Object}] block payload
     def block_json(not_update: true)
       ans = super
       ans[type] = {}

data/lib/notion_ruby_mapping/blocks/callout_block.rb

@@ -14,8 +14,13 @@ module NotionRubyMapping
       if @json
         decode_block_rich_text_array
         decode_color
+        @emoji = json[type]&.dig("icon", "emoji")&.then { |str| EmojiObject.new emoji: str }
+        @file_object = json[type]&.dig("icon")&.then { |file_json| FileObject.new json: file_json }
       else
         rich_text_array_and_color "rich_text", text_info, color
+        raise ArgumentError, "Specify either emoji or file_url." if emoji.nil? && file_url.nil?
+        raise ArgumentError, "Specify either emoji or file_url, not both." if !emoji.nil? && !file_url.nil?
+
         @emoji = EmojiObject.emoji_object emoji if emoji
         @file_object = FileObject.file_object file_url if file_url
         add_sub_blocks sub_blocks
@@ -34,7 +39,7 @@ module NotionRubyMapping
       ans[type] = @rich_text_array.update_property_schema_json not_update
       ans[type]["color"] = @color
       ans[type]["icon"] = @emoji.property_values_json if @emoji
-      ans[type]["icon"] = @file_object.property_values_json if @file_object
+      ans[type]["icon"] = @file_object.property_values_json if @file_object && @file_object.url
       ans[type]["children"] = @sub_blocks.map(&:block_json) if @sub_blocks
       ans
     end

data/lib/notion_ruby_mapping/blocks/divider_block.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Notion block
+  # Notion divider block
   class DividerBlock < Block
-    # @param [Boolean] not_update false when update
-    # @return [Hash{String (frozen)->Hash}]
+    # @param [Boolean] not_update true for a full block payload; false for an update payload
+    # @return [Hash{String => Object}] block payload
     def block_json(not_update: true)
       ans = super
       ans[type] = {}
       ans
     end
 
-    # @return [String (frozen)]
+    # @return [String] block type
     def type
       "divider"
     end

data/lib/notion_ruby_mapping/blocks/equation_block.rb

@@ -3,7 +3,7 @@
 module NotionRubyMapping
   # Notion block
   class EquationBlock < Block
-    # @param [String, NotionRubyMapping::EquationObject] expression
+    # @param [String, NotionRubyMapping::EquationObject, nil] expression
     # @see https://www.notion.so/hkob/EquationBlock-df0f823dc5ac41b798052f161dd6540c#cfcd2ceb77194c0e915500b429e8b91b
     def initialize(expression = nil, json: nil, id: nil, parent: nil)
       super(json: json, id: id, parent: parent)
@@ -28,7 +28,7 @@ module NotionRubyMapping
       @equation_object&.expression
     end
 
-    # @param [String] new_expression
+    # @param [String, nil] new_expression
     # @see https://www.notion.so/hkob/EquationBlock-df0f823dc5ac41b798052f161dd6540c#f05e3b2c82914cea9f05e9e6644647e1
     def expression=(new_expression)
       @equation_object = EquationObject.equation_object new_expression

data/lib/notion_ruby_mapping/blocks/file_base_block.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Notion block
+  # Base class for blocks that contain a file and an optional caption.
+  #
+  # This class manages the file representation, caption, and update payload
+  # shared by file-based block types.
+  # @abstract Subclass and implement {#type}.
   class FileBaseBlock < Block
-    # @param [String, FileUploadObject, NilClass] url or file upload object
-    # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>, nil] caption
-    # @see https://www.notion.so/hkob/FileBlock-08f2aa6948364d00b92beacaac9a619c#ace53d2e6ff2404f937179ae1e966e98
-    # @see https://www.notion.so/hkob/ImageBlock-806b3d2a9a2c4bf5a5aca6e3fbc8a7e2#4cb790b8b5c847acab4341d55e4fa66a
+    # Creates a file-based block.
+    #
+    # @param url_or_fuo [String, FileUploadObject, FileObject, nil]
+    #   an external URL, a file upload object, or a file object
+    # @param caption [RichTextArray, String, Array<String>, RichTextObject,
+    #   Array<RichTextObject>, nil] caption content
+    # @param json [Hash, nil] block JSON returned by the Notion API
+    # @param id [String, nil] block ID
+    # @param parent [Page, Block, nil] parent object
     def initialize(url_or_fuo = nil, caption: [], json: nil, id: nil, parent: nil)
       super(json: json, id: id, parent: parent)
       if @json
@@ -19,12 +28,18 @@ module NotionRubyMapping
       end
     end
 
-    # @see https://www.notion.so/hkob/FileBlock-08f2aa6948364d00b92beacaac9a619c#158487a7e1644fae8778dcff59869356
-    # @see https://www.notion.so/hkob/ImageBlock-806b3d2a9a2c4bf5a5aca6e3fbc8a7e2#19a4aa3e06514bbe84be9d3b8a45a20f
-    attr_reader :caption, :file_object
+    # @return [RichTextArray] block caption
+    attr_reader :caption
 
-    # @param [Boolean] not_update false when update
-    # @return [Hash{String (frozen)->Hash}]
+    # @return [FileObject] current file representation
+    attr_reader :file_object
+
+    # Builds the block JSON representation.
+    #
+    # @param not_update [Boolean] true for a complete block payload;
+    #   false for an update payload
+    # @return [Hash{String => Object}] block JSON
+    # @api private
     def block_json(not_update: true)
       ans = super
       ans[type] = @file_object.property_values_json
@@ -32,27 +47,41 @@ module NotionRubyMapping
       ans
     end
 
-    # @return [String]
-    # @see https://www.notion.so/hkob/FileBlock-08f2aa6948364d00b92beacaac9a619c#d3e7d31b7b274955aa7603163867fa57
-    # @see https://www.notion.so/hkob/ImageBlock-806b3d2a9a2c4bf5a5aca6e3fbc8a7e2#01e1883119f14c5f9f7f6823793e72ec
+    # Returns the current file URL.
+    #
+    # A URL returned for a Notion-hosted file may expire.
+    #
+    # @return [String, nil] current file URL
     def url
       @file_object&.url
     end
 
-    # @param [String] url
-    # @see https://www.notion.so/hkob/FileBlock-08f2aa6948364d00b92beacaac9a619c#23497b8eb2214c45b3d5881796f984cb
-    # @see https://www.notion.so/hkob/ImageBlock-806b3d2a9a2c4bf5a5aca6e3fbc8a7e2#61598d260b6140f2a359f7d22ea2548a
+    # Replaces the current file with an external URL.
+    #
+    # Call {Block#save} to send the change to the Notion API.
+    #
+    # @param url [String] new external URL
     def url=(url)
       @file_object.url = url
       @payload.add_update_block_key "external"
     end
 
-    # @param [FileUploadObject] fuo
-    def file_upload_object=(fuo)
-      @file_object.file_upload_object = fuo
+    # Replaces the current file with an uploaded file.
+    #
+    # Call {Block#save} to send the change to the Notion API. After saving,
+    # the file is reconstructed as a Notion-hosted file.
+    #
+    # @param file_upload_object [FileUploadObject] uploaded file
+    def file_upload_object=(file_upload_object)
+      @file_object.file_upload_object = file_upload_object
       @payload.add_update_block_key "file_upload"
     end
 
+    # Reconstructs the file and caption from an API response.
+    #
+    # @param json [Hash] block JSON returned by the Notion API
+    # @return [void]
+    # @api private
     def update_file_object_from_json(json)
       @file_object = FileObject.new json: json[type]
       decode_block_caption

data/lib/notion_ruby_mapping/blocks/file_block.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Notion block
+  # Represents a Notion file block.
   class FileBlock < FileBaseBlock
-    # @return [String]
+    # Returns the Notion block type.
+    #
+    # @return [String] `"file"`
     def type
       "file"
     end

data/lib/notion_ruby_mapping/blocks/heading1_block.rb

@@ -5,7 +5,7 @@ module NotionRubyMapping
   class Heading1Block < TextSubBlockColorBaseBlock
     # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>, nil] text_info
     # @param [String] color
-    def initialize(text_info = nil, color: nil, json: nil, id: nil, parent: nil)
+    def initialize(text_info = nil, color: "default", json: nil, id: nil, parent: nil)
       super(text_info, color: color, json: json, id: id, parent: parent)
       @can_have_children = false
     end

data/lib/notion_ruby_mapping/blocks/heading2_block.rb

@@ -5,7 +5,7 @@ module NotionRubyMapping
   class Heading2Block < TextSubBlockColorBaseBlock
     # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>] text_info
     # @param [String] color
-    def initialize(text_info = nil, color: nil, json: nil, id: nil, parent: nil)
+    def initialize(text_info = nil, color: "default", json: nil, id: nil, parent: nil)
       super(text_info, color: color, json: json, id: id, parent: parent)
       @can_have_children = false
     end

data/lib/notion_ruby_mapping/blocks/heading3_block.rb

@@ -5,7 +5,7 @@ module NotionRubyMapping
   class Heading3Block < TextSubBlockColorBaseBlock
     # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>] text_info
     # @param [String] color
-    def initialize(text_info = nil, color: nil, json: nil, id: nil, parent: nil)
+    def initialize(text_info = nil, color: "default", json: nil, id: nil, parent: nil)
       super(text_info, color: color, json: json, id: id, parent: parent)
       @can_have_children = false
     end

data/lib/notion_ruby_mapping/blocks/heading4_block.rb

@@ -5,7 +5,7 @@ module NotionRubyMapping
   class Heading4Block < TextSubBlockColorBaseBlock
     # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>] text_info
     # @param [String] color
-    def initialize(text_info = nil, color: nil, json: nil, id: nil, parent: nil)
+    def initialize(text_info = nil, color: "default", json: nil, id: nil, parent: nil)
       super(text_info, color: color, json: json, id: id, parent: parent)
       @can_have_children = false
     end

data/lib/notion_ruby_mapping/blocks/table_of_contents_block.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Notion block
-  # @param [String] color
+  # Notion table of contents block
   class TableOfContentsBlock < Block
+    # @param [String] color block color
     def initialize(color = "default", json: nil, id: nil, parent: nil)
       super(json: json, id: id, parent: parent)
       if @json
@@ -13,18 +13,19 @@ module NotionRubyMapping
       end
     end
 
+    # @param [String] new_color new block color
     def color=(new_color)
       @color = new_color
       @payload.add_update_block_key "color"
     end
 
-    # @return [String (frozen)]
+    # @return [String] block type
     def type
       "table_of_contents"
     end
 
-    # @param [Boolean] not_update false when update
-    # @return [Hash{String (frozen)->Hash}]
+    # @param [Boolean] not_update true for a full block payload; false for an update payload
+    # @return [Hash{String => Object}] block payload
     def block_json(not_update: true)
       ans = super
       ans[type] = {"color" => @color}

data/lib/notion_ruby_mapping/controllers/rich_text_array.rb

@@ -19,13 +19,14 @@ module NotionRubyMapping
                            end
       @will_update = will_update
     end
+    attr_reader :rich_text_objects
     attr_writer :will_update
 
     def self.rich_text_array(key, text_objects = nil)
       if text_objects.nil?
         RichTextArray.new key
       elsif text_objects.is_a? RichTextArray
-        text_objects
+        RichTextArray.new key, text_objects: text_objects.rich_text_objects
       else
         RichTextArray.new key, text_objects: text_objects
       end

data/lib/notion_ruby_mapping/objects/equation_object.rb

@@ -3,16 +3,17 @@
 module NotionRubyMapping
   # EquationObject
   class EquationObject < RichTextObject
-    # @param [String] expression
-    # @return [TextObject]
+    # @param [String, nil] expression
+    # @return [EquationObject]
     def initialize(expression, options = {})
+      expression ||= ""
       super "equation", {"plain_text" => expression}.merge(options)
       @expression = expression
       @will_update = false
     end
     attr_reader :will_update, :expression
 
-    # @param [EquationObject, String] uo
+    # @param [EquationObject, String, nil] expression_or_eo
     # @return [EquationObject] self or created EquationObject
     # @see https://www.notion.so/hkob/EquationObject-cd50126fce544ad5bb76463a4269859b#45b0b0810d8647a1968a5e4293920aeb
     def self.equation_object(expression_or_eo)
@@ -23,9 +24,10 @@ module NotionRubyMapping
       end
     end
 
-    # @param [String] expression
+    # @param [String, nil] expression
     # @see https://www.notion.so/hkob/EquationObject-cd50126fce544ad5bb76463a4269859b#155800e2c69d4676a2d74572ed8f0de8
     def expression=(expression)
+      expression ||= ""
       @expression = expression
       @options["plain_text"] = expression
       @will_update = true

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/property.rb

@@ -168,7 +168,7 @@ module NotionRubyMapping
       @json = json[type]
     end
 
-    # @return [Symbol] property type
+    # @return [String] property type
     def type
       self.class::TYPE
     end

data/lib/notion_ruby_mapping/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  VERSION = "4.1.0"
+  VERSION = "4.2.0"
   NOTION_VERSION = "2026-03-11"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: notion_ruby_mapping
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Hiroyuki KOBAYASHI