notion_to_md 2.5.1 → 3.0.0.beta2

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,114 @@
+# 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)
+        new(id: 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 Notion id database.
+    attr_reader :id
+
+    # @param jNotion::Client] The Notion API client.
+    attr_reader :notion_client
+
+    # @return [Hash] The database configuration options.
+    attr_reader :config
+
+    # @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 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.
+    def initialize(id:, notion_client:, filter:, sorts:, frontmatter: false)
+      @id = id
+      @notion_client = notion_client
+      @config = {
+        frontmatter: frontmatter,
+        filter: filter,
+        sorts: sorts
+      }
+    end
+
+    # Fetch database metadata and contained pages from the Notion API.
+    #
+    # This method populates the database's metadata and children by making API calls
+    # to retrieve the database structure and all pages contained within it, applying
+    # any configured filters and sorting criteria.
+    #
+    # @return [NotionToMd::Database] returns self to allow method chaining.
+    def call
+      @metadata = notion_client.database(database_id: id)
+      @children = Builder.call(
+        database_id: id,
+        notion_client: notion_client,
+        filter: config[:filter],
+        sorts: config[:sorts],
+        frontmatter: config[:frontmatter]
+      )
+      self
+    end
+
+    alias build call
+
+    # 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