notion_ruby_mapping 4.0.2 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e126e6dda7027a42155522291389804d27f1a009894ab6a96b1e85e25ff4660
-  data.tar.gz: c97f3f01e37c33306334de9a5134326337cb55f711598b046c62387245924bec
+  metadata.gz: 4d8cbce3013176a87d6e023e5bbbd0b5ae6f5c43b437f50c3c6df468ce302d19
+  data.tar.gz: 0ea1f4d67320d4039a42eb156ba03a29595a4362c51a44f7541a874c735c257b
 SHA512:
-  metadata.gz: b05a1a095ac2892a1ea5b2a3d0b1283a524ad20eb0eb14fdc62df77dbb77437d1a890b114cb46fd3df0e3d0a92841e09803e4476f9d43783aab16faba7c1ceaa
-  data.tar.gz: e2164f5ad4f8805749b32e7a2355e21d638d29b5c7f2efa16e28a79b6659de37df89263ed4ebbca9f7a8a5f5ced209b9ba735fe949ffbf07e8ae786ee347a1f6
+  metadata.gz: 05a4e8f93a32115e06047aa0324879e63c5ec761d7b98e1cfc7c1df76033389705d1a25ca0b79a1b657dfb4df27b80fa4eeb0793ec21be359d3c2105cbe3f98c
+  data.tar.gz: cc86a8c085ed3da0b7905560c4f92ec8c627739480c3ee13a951f9b9c82bf0ec5cf042f0d888af7bc98a9ecaee788282d042b4de7961852c9cd3407ed8389ab6

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [4.1.0] - 2026-08-23
+
+### Removed
+
+- `Property#contents?`
+- `Property#assert_database_property`
+- `def_delegators :retrieve_page_property` and `extend Forwardable` in `Property`
+  (a workaround for the 2022-06-28 API version, made unnecessary by the 2022-08-31 update)
+
+### Changed
+
+- `Property.create_from_json` now raises a `StandardError` when the given JSON has no `type` key
+- Unsupported property types now raise a unified message:
+  `Unsupported property type: <type> (<name>). Please update notion_ruby_mapping.`
+- `Property#update_from_json` now assigns the value whenever the key exists,
+  so `false` and empty values are reflected correctly
+- `List#initialize` normalizes `query` to `Query.new` when `nil` is given
+- `assert_*` methods use positive conditions and a consistent
+  `Database or DataSource property` wording
+
 ## [0.1.0] - 2022-02-07
 
-- Initial release
+- Initial release

data/README.md

@@ -143,9 +143,11 @@ NotionRubyMapping.configuration { |c| c.notion_token = ENV["NOTION_API_TOKEN"] }
 
 ## 3. ChangeLog
 
-- 2027/7/14 [v4.0.2] Add clear method for DateProperty
-- 2027/5/4 [v4.0.1] Add retrieve / update / delete a comment
-- 2027/3/23 [v4.0.0] Add markdown support, headnig_4, toggle_heading_4, and position support for appending blocks
+- 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
+- 2026/3/23 [v4.0.0] Add markdown support, headnig_4, toggle_heading_4, and position support for appending blocks
 - 2026/1/25 [v3.0.6] add move page, list templates, and create child page to page
 - 2025/12/15 [v3.0.5] add AudioBlock
 - 2025/12/9 [v3.0.4] Fix the issue where page.parent could not be executed for pages with a data source as parent

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

@@ -26,7 +26,7 @@ module NotionRubyMapping
       when "template"
         @template = value
       end
-      @query = query
+      @query = query || Query.new
       @index = 0
       @has_content = true
     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/mermaid_data_source.rb

@@ -96,7 +96,7 @@ module NotionRubyMapping
 
         when "multi_select"
           if property
-            (options - (property.multi_select_options.map { |h| h["name"] })).each do |select_name|
+            (options - property.multi_select_options.map { |h| h["name"] }).each do |select_name|
               property.add_multi_select_option name: select_name, color: "default"
             end
           else
@@ -145,7 +145,7 @@ module NotionRubyMapping
           end
         when "select"
           if property
-            (options - (property.select_options.map { |h| h["name"] })).each do |select_name|
+            (options - property.select_options.map { |h| h["name"] }).each do |select_name|
               property.add_select_option name: select_name, color: "default"
             end
           else
@@ -165,7 +165,7 @@ module NotionRubyMapping
         property = ps.values_at(forward).first
         if property
           if reverse
-            if property.data_source_id == db_is && property.synced_property_name == reverse
+            if property.relation_data_source_id == db_is && property.synced_property_name == reverse
               relation_ds.add_property "relation", reverse
               relation_ds.finish_flag[reverse] = true
             else

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
@@ -79,6 +80,10 @@ module NotionRubyMapping
       map(&:text).join ""
     end
 
+    def clear
+      self.rich_text_objects = []
+    end
+
     # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>] text_info
     def rich_text_objects=(text_info)
       @will_update = true

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