notion_to_md 2.5.1 → 3.0.0.beta1

data/lib/notion_to_md/database/builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  class Database
+    # === NotionToMd::Database::Builder
+    #
+    # Responsible for fetching and building all pages of a Notion database
+    # into {NotionToMd::Page} instances. Handles pagination via `has_more`
+    # and `next_cursor` automatically.
+    #
+    # @example Build pages for a database
+    #   notion_client = Notion::Client.new(token: ENV["NOTION_TOKEN"])
+    #   pages = NotionToMd::Database::Builder.call(
+    #     database_id: "xxxx-xxxx",
+    #     notion_client: notion_client,
+    #     filter: { property: "Year", number: { equals: 2023 } },
+    #     sorts: [{ property: "Title", direction: "ascending" }],
+    #     frontmatter: true
+    #   )
+    #
+    #   pages.each { |page| puts page.to_s }
+    #
+    # @see NotionToMd::Database
+    # @see NotionToMd::Page
+    class Builder
+      include Support::Pagination
+
+      class << self
+        # Build pages from a database.
+        #
+        # @param database_id [String] The Notion database ID.
+        # @param notion_client [Notion::Client] The Notion API client.
+        # @param filter [Hash, nil] Optional filter to pass to the Notion API.
+        # @param sorts [Array<Hash>, nil] Optional sort criteria.
+        # @param frontmatter [Boolean] Whether to include frontmatter in page Markdown output.
+        #
+        # @return [Array<NotionToMd::Page>] An array of page objects.
+        def call(database_id:, notion_client:, filter: nil, sorts: nil, frontmatter: false)
+          new(
+            database_id: database_id,
+            notion_client: notion_client,
+            filter: filter,
+            sorts: sorts,
+            frontmatter: frontmatter
+          ).call
+        end
+
+        # @!method build(...)
+        #   Alias of {.call}.
+        alias build call
+      end
+
+      # @return [String] The database ID.
+      attr_reader :database_id
+
+      # @return [Notion::Client] The Notion API client.
+      attr_reader :notion_client
+
+      # @return [Hash, nil] Filter criteria passed to Notion API.
+      attr_reader :filter
+
+      # @return [Array<Hash>, nil] Sort criteria passed to Notion API.
+      attr_reader :sorts
+
+      # @return [Hash] Options for building pages (e.g. `{ frontmatter: true }`).
+      attr_reader :page_options
+
+      # Initialize a new builder.
+      #
+      # @param database_id [String] The Notion database ID.
+      # @param notion_client [Notion::Client] The Notion API client.
+      # @param filter [Hash, nil] Optional filter to pass to the Notion API.
+      # @param sorts [Array<Hash>, nil] Optional sort criteria.
+      # @param frontmatter [Boolean] Whether to include frontmatter in page Markdown output.
+      def initialize(database_id:, notion_client:, filter: nil, sorts: nil, frontmatter: false)
+        @database_id = database_id
+        @notion_client = notion_client
+        @filter = filter
+        @sorts = sorts
+        @page_options = { frontmatter: frontmatter }
+      end
+
+      # Fetch and build all pages of the database.
+      #
+      # @return [Array<NotionToMd::Page>]
+      def call
+        fetch_pages.map do |page|
+          NotionToMd::Page.call(id: page.id, notion_client: notion_client, **page_options)
+        end
+      end
+
+      # Fetch all raw page records from the Notion database.
+      #
+      # @return [Array<Notion::Messages::Message>] Raw page messages from the Notion API.
+      def fetch_pages
+        params = {}
+
+        paginate do |cursor|
+          params = { database_id: database_id, filter: filter, sorts: sorts }.compact
+          params[:start_cursor] = cursor if cursor
+
+          notion_client.database_query(params)
+        end
+      end
+    end
+  end
+end

data/lib/notion_to_md/database.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  # === NotionToMd::Database
+  #
+  # Represents a Notion database and allows converting its pages
+  # into Markdown documents.
+  #
+  # A `Database` object encapsulates the database metadata and
+  # the collection of {NotionToMd::Page} children it contains.
+  #
+  # @example Convert a Notion database to Markdown
+  #   notion_client = Notion::Client.new(token: ENV["NOTION_TOKEN"])
+  #   db = NotionToMd::Database.call(id: "xxxx-xxxx", notion_client: notion_client, frontmatter: true)
+  #
+  #   db.to_s.each_with_index do |page_md, idx|
+  #     File.write("page_#{idx}.md", page_md)
+  #   end
+  #
+  # @see NotionToMd::Page
+  # @see NotionToMd::Database::Builder
+  class Database
+    include Support::MetadataProperties
+
+    class << self
+      # Build a new {Database} from the Notion API.
+      #
+      # @param id [String] The Notion database ID.
+      # @param notion_client [Notion::Client] The Notion API client.
+      # @param filter [Hash, nil] Optional filter criteria to pass to the Notion API.
+      # @param sorts [Array<Hash>, nil] Optional sort criteria.
+      # @param frontmatter [Boolean] Whether to include frontmatter in each page’s Markdown output.
+      #
+      # @return [NotionToMd::Database] a new database instance.
+      #
+      # @see .build
+      def call(id:, notion_client:, filter: nil, sorts: nil, frontmatter: false)
+        metadata = notion_client.database(database_id: id)
+        pages = Builder.call(
+          database_id: id,
+          notion_client: notion_client,
+          filter: filter,
+          sorts: sorts,
+          frontmatter: frontmatter
+        )
+
+        new(metadata: metadata, children: pages)
+      end
+
+      # @!method build(...)
+      #   Alias of {.call}.
+      alias build call
+    end
+
+    # @return [Object] The metadata associated with the database.
+    attr_reader :metadata
+
+    # @return [Array<NotionToMd::Page>] The pages contained in the database.
+    attr_reader :children
+
+    # @!method pages
+    #   Alias for {#children}.
+    alias pages children
+
+    # Initialize a new database representation.
+    #
+    # @param metadata [Object] The Notion database metadata.
+    # @param children [Array<NotionToMd::Page>] The pages belonging to the database.
+    def initialize(metadata:, children:)
+      @metadata = metadata
+      @children = children
+    end
+
+    # Convert all database pages into Markdown.
+    #
+    # @return [Array<String>] Markdown documents for each page in the database.
+    def to_s
+      pages.map(&:to_s)
+    end
+
+    # @!method to_md
+    #   Alias for {#to_s}.
+    alias to_md to_s
+  end
+end

data/lib/notion_to_md/logger.rb

@@ -6,6 +6,7 @@ class NotionToMd
 
     class << self
       extend Forwardable
+
       def_delegators :@logger, :debug, :info, :warn, :error, :fatal, :level, :level=
     end
   end

data/lib/notion_to_md/metadata_type.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  # === NotionToMd::MetadataType
+  #
+  # Utility class responsible for extracting and sanitizing values
+  # from Notion database/page property objects. Each class method
+  # corresponds to a Notion property type and returns a normalized
+  # Ruby value suitable for use in YAML frontmatter or Markdown.
+  #
+  # This class is typically used indirectly via
+  # {NotionToMd::Support::MetadataProperties}.
+  #
+  # @example Extract a multi-select property
+  #   prop = { multi_select: [{ name: "Action" }, { name: "Drama" }] }
+  #   NotionToMd::MetadataType.multi_select(prop)
+  #   # => ["Action", "Drama"]
+  #
+  # @example Extract a date property
+  #   prop = { date: { start: "2024-01-01T00:00:00Z" } }
+  #   NotionToMd::MetadataType.date(prop)
+  #   # => 2024-01-01 00:00:00 +0000
+  #
+  # @see NotionToMd::Support::YamlSanitizer
+  class MetadataType
+    class << self
+      include Support::YamlSanitizer
+
+      # Extract file URL.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def file(prop)
+        prop.dig(:file, :url)
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract external file URL.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def external(prop)
+        prop.dig(:external, :url)
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract emoji character.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def emoji(prop)
+        prop[:emoji]
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract multi-select values as names.
+      # @param prop [Hash]
+      # @return [Array<String>, nil]
+      def multi_select(prop)
+        prop[:multi_select].map { |sel| sel[:name] }
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract selected option name.
+      # Escapes YAML-sensitive characters.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def select(prop)
+        escape_frontmatter_value(prop.dig(:select, :name))
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract people names.
+      # @param prop [Hash]
+      # @return [Array<String>, nil]
+      def people(prop)
+        prop[:people].map { |sel| sel[:name] }
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract file or external URLs from files list.
+      # @param prop [Hash]
+      # @return [Array<String>, nil]
+      def files(prop)
+        prop[:files].map { |f| file(f) || external(f) }
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract phone number.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def phone_number(prop)
+        prop[:phone_number]
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract number.
+      # @param prop [Hash]
+      # @return [Numeric, nil]
+      def number(prop)
+        prop[:number]
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract email.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def email(prop)
+        prop[:email]
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract checkbox (as string "true"/"false").
+      # @param prop [Hash]
+      # @return [String, nil]
+      def checkbox(prop)
+        prop[:checkbox]&.to_s
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract date value.
+      # Converts strings to {Time}, {Date} to {Time}, leaves Time unchanged.
+      # End date and time zone are not supported.
+      #
+      # @param prop [Hash]
+      # @return [Time, String, nil] Parsed start date, raw value, or nil.
+      def date(prop)
+        date = prop.dig(:date, :start)
+
+        case date
+        when Date
+          date.to_time
+        when String
+          Time.parse(date)
+        else
+          date # Time or nil
+        end
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract URL.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def url(prop)
+        prop[:url]
+      rescue NoMethodError
+        nil
+      end
+
+      # Extract rich text as plain string, escaped for YAML if necessary.
+      # @param prop [Hash]
+      # @return [String, nil]
+      def rich_text(prop)
+        text = prop[:rich_text].map { |text| text[:plain_text] }.join
+        text.blank? ? nil : escape_frontmatter_value(text)
+      rescue NoMethodError
+        nil
+      end
+    end
+  end
+end

data/lib/notion_to_md/page/builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  class Page
+    # === NotionToMd::Page::Builder
+    #
+    # Builds a tree of Notion blocks for a given block (or page) ID by
+    # fetching children from the Notion API and recursively traversing
+    # blocks that are allowed to contain nested children.
+    #
+    # @example Build all blocks for a page
+    #   notion = Notion::Client.new(token: ENV["NOTION_TOKEN"])
+    #   blocks = NotionToMd::Page::Builder.call(block_id: "xxxx-xxxx", notion_client: notion)
+    #   blocks # => [NotionToMd::Blocks::Block, ...]
+    #
+    # @see NotionToMd::Blocks::Factory
+    # @see NotionToMd::Blocks::Normalizer
+    class Builder
+      include Support::Pagination
+
+      # Block types allowed to have nested blocks (children).
+      #
+      # @return [Array<Symbol>]
+      BLOCKS_WITH_PERMITTED_CHILDREN = %i[
+        bulleted_list_item
+        numbered_list_item
+        paragraph
+        to_do
+        table
+      ].freeze
+
+      class << self
+        # Build the block tree from a starting block ID.
+        #
+        # @param block_id [String] The Notion block (or page) ID to expand.
+        # @param notion_client [Notion::Client] Initialized Notion client.
+        #
+        # @return [Array<NotionToMd::Blocks::Block>] Normalized, possibly nested blocks.
+        #
+        # @see .build
+        def call(block_id:, notion_client:)
+          new(block_id: block_id, notion_client: notion_client).call
+        end
+
+        # @!method build(...)
+        #   Alias of {.call}.
+        alias build call
+      end
+
+      # @return [String] The root block (or page) ID to expand.
+      attr_reader :block_id
+
+      # @return [Notion::Client] The Notion API client.
+      attr_reader :notion_client
+
+      # Create a new builder.
+      #
+      # @param block_id [String] The Notion block (or page) ID to expand.
+      # @param notion_client [Notion::Client] Initialized Notion client.
+      def initialize(block_id:, notion_client:)
+        @block_id = block_id
+        @notion_client = notion_client
+      end
+
+      # Fetch, build, and normalize the full block tree.
+      #
+      # Recursively expands children for block types listed in
+      # {BLOCKS_WITH_PERMITTED_CHILDREN}. Uses {#fetch_blocks} to page through
+      # results via `has_more` / `next_cursor`.
+      #
+      # @return [Array<NotionToMd::Blocks::Block>] Normalized blocks ready for rendering.
+      def call
+        notion_blocks = fetch_blocks
+        blocks = notion_blocks.map do |block|
+          children = if permitted_children_for?(block: block)
+                       self.class.call(block_id: block.id, notion_client: notion_client)
+                     else
+                       []
+                     end
+          Blocks::Factory.build(block: block, children: children)
+        end
+
+        Blocks::Normalizer.call(blocks: blocks)
+      end
+
+      # Whether a block can have (and actually has) children to be traversed.
+      #
+      # @param block [Notion::Messages::Message] A Notion block message.
+      #
+      # @return [Boolean] True if the block type allows children and `has_children` is truthy.
+      def permitted_children_for?(block:)
+        BLOCKS_WITH_PERMITTED_CHILDREN.include?(block.type.to_sym) && block.has_children
+      end
+
+      # Fetch all direct children for {#block_id}, handling Notion pagination.
+      #
+      # @note This method loops until `has_more` is false, following `next_cursor`.
+      #
+      # @return [Array<Notion::Messages::Message>] Raw Notion block messages.
+      def fetch_blocks
+        params = {}
+
+        paginate do |cursor|
+          params[:block_id] = block_id
+          params[:start_cursor] = cursor if cursor
+
+          notion_client.block_children(params)
+        end
+      end
+    end
+  end
+end

data/lib/notion_to_md/page.rb

@@ -3,135 +3,89 @@
 class NotionToMd
   # === NotionToMd::Page
   #
-  # This class is responsible for representing a Notion page.
+  # Represents a Notion page and allows conversion to Markdown.
+  #
+  # A `Page` object encapsulates the page metadata, its content blocks,
+  # and optionally the frontmatter section.
+  #
+  # @example Convert a Notion page to Markdown
+  #   notion_client = Notion::Client.new(token: ENV["NOTION_TOKEN"])
+  #   page = NotionToMd::Page.call(id: "xxxx-xxxx", notion_client: notion_client, frontmatter: true)
+  #   File.write("page.md", page.to_s)
+  #
   class Page
-    include Helpers::YamlSanitizer
-
-    attr_reader :page, :blocks
-
-    def initialize(page:, blocks:)
-      @page = page
-      @blocks = blocks
-    end
-
-    def title
-      title_list = page.dig(:properties, :Name, :title) || page.dig(:properties, :title, :title)
-      title_list.inject('') do |acc, slug|
-        acc + slug[:plain_text]
+    include Support::MetadataProperties
+    include Support::Frontmatter
+
+    class << self
+      # Build a new {Page} from the Notion API.
+      #
+      # @param id [String] The Notion page ID.
+      # @param notion_client [Notion::Client] The Notion API client.
+      # @param frontmatter [Boolean] Whether to include frontmatter in the output.
+      #
+      # @return [NotionToMd::Page] a new page instance.
+      #
+      # @see .build
+      def call(id:, notion_client:, frontmatter: false)
+        metadata = notion_client.page(page_id: id)
+        blocks = Builder.call(block_id: id, notion_client: notion_client)
+
+        new(metadata: metadata, children: blocks, frontmatter: frontmatter)
       end
-    end
-
-    def cover
-      PageProperty.external(page[:cover]) || PageProperty.file(page[:cover])
-    end
 
-    def icon
-      PageProperty.emoji(page[:icon]) || PageProperty.external(page[:icon]) || PageProperty.file(page[:icon])
+      # @!method build(...)
+      #   Alias of {.call}.
+      alias build call
     end
 
-    def id
-      page[:id]
-    end
-
-    def created_time
-      page['created_time']
-    end
-
-    def created_by_object
-      page.dig(:created_by, :object)
-    end
+    # @return [Object] The metadata associated with the page.
+    attr_reader :metadata
 
-    def created_by_id
-      page.dig(:created_by, :id)
-    end
+    # @return [Array<#to_md>] The list of child blocks belonging to the page.
+    attr_reader :children
 
-    def last_edited_time
-      page['last_edited_time']
-    end
+    # @!method blocks
+    #   Alias for {#children}.
+    alias blocks children
 
-    def last_edited_by_object
-      page.dig(:last_edited_by, :object)
-    end
-
-    def last_edited_by_id
-      page.dig(:last_edited_by, :id)
-    end
-
-    def url
-      page[:url]
-    end
-
-    def archived
-      page[:archived]
+    # Initialize a new Page.
+    #
+    # @param metadata [Object] The Notion page metadata.
+    # @param children [Array<#to_md>] The block children belonging to the page.
+    # @param frontmatter [Boolean] Whether to include frontmatter in the Markdown output.
+    def initialize(metadata:, children:, frontmatter: false)
+      @metadata = metadata
+      @children = children
+      @config = { frontmatter: frontmatter }
     end
 
+    # Render the body of the page (Markdown representation of its blocks).
+    #
+    # @return [String] The Markdown content of the page.
     def body
       @body ||= blocks.map(&:to_md).compact.join
     end
 
-    def frontmatter
-      @frontmatter ||= <<~CONTENT
-        ---
-        #{props.to_a.map do |k, v|
-            "#{k}: #{v}"
-          end.join("\n")}
-        ---
-      CONTENT
-    end
-
-    def props
-      @props ||= custom_props.deep_merge(default_props)
+    # Whether the page includes frontmatter.
+    #
+    # @return [Boolean]
+    def frontmatter?
+      @config[:frontmatter]
     end
 
-    def custom_props
-      @custom_props ||= filtered_custom_properties
+    # Render the page as a Markdown string, including optional frontmatter.
+    #
+    # @return [String] The Markdown document.
+    def to_s
+      <<~MD
+        #{frontmatter if frontmatter?}
+        #{body}
+      MD
     end
 
-    # rubocop:disable Metrics/MethodLength
-    def default_props
-      @default_props ||= {
-        'id' => id,
-        'title' => escape_frontmatter_value(title),
-        'created_time' => created_time,
-        'cover' => cover,
-        'icon' => icon,
-        'last_edited_time' => last_edited_time,
-        'archived' => archived,
-        'created_by_object' => created_by_object,
-        'created_by_id' => created_by_id,
-        'last_edited_by_object' => last_edited_by_object,
-        'last_edited_by_id' => last_edited_by_id
-      }
-    end
-    # rubocop:enable Metrics/MethodLength
-
-    # This class is kept for retro compatibility reasons.
-    # Use instead the PageProperty class.
-    class CustomProperty < PageProperty
-    end
-
-    private
-
-    def filtered_custom_properties
-      build_custom_properties.reject { |_k, v| v.presence.nil? }
-    end
-
-    def build_custom_properties
-      page.properties.each_with_object({}) do |(name, value), memo|
-        type = value.type
-        next unless valid_custom_property_type?(type)
-
-        key = name.parameterize.underscore
-        memo[key] = build_custom_property(type, value)
-      end
-    end
-
-    def valid_custom_property_type?(type)
-      CustomProperty.respond_to?(type.to_sym)
-    end
-
-    def build_custom_property(type, value)
-      CustomProperty.send(type, value)
-    end
+    # @!method to_md
+    #   Alias for {#to_s}.
+    alias to_md to_s
   end
 end