notion-client-ruby 0.1.0

data/codegen/openapi.lock

@@ -0,0 +1 @@
+sha256: dee5763763b0b9fbad2aa8d5adb173ca350ec26dda557e658c5dbe9d2ea2f258

data/codegen/overrides.yml

@@ -0,0 +1,14 @@
+post-page:
+  required_body_params:
+    - parent
+  body_requirement_variants:
+    - - parent
+upload-file:
+  required_body_params:
+    - data
+    - filename
+    - content_type
+  body_requirement_variants:
+    - - data
+      - filename
+      - content_type

data/docs/design.md

@@ -0,0 +1,7 @@
+# Architecture
+
+The client is split into transport, middleware, generated endpoints, response objects, and optional ergonomics. The core uses only Ruby standard libraries.
+
+Requests flow through instrumentation, redacted logging, retry, token-bucket rate limiting, authentication, API-version compatibility, and JSON encoding before `Net::HTTP`. Endpoint declarations and coverage specs are generated from the vendored official OpenAPI document. Unknown response fields and object types remain accessible through `raw` and `[]`.
+
+Compatibility normalizes legacy `archived`, `after`, and `transcription` fields to the `2026-03-11` vocabulary. New endpoints remain reachable immediately through `Client#request` before a generated update is released.

data/docs/recipes/csv-import.md

@@ -0,0 +1,14 @@
+# CSV import
+
+```ruby
+require "csv"
+
+CSV.foreach("tasks.csv", headers: true) do |row|
+  client.pages.create(
+    parent: { data_source_id: data_source_id },
+    properties: row.to_h
+  )
+end
+```
+
+Property values are converted using the data source schema. Enable `strict: true` to reject unknown CSV headers before creating a page.

data/docs/recipes/oauth.md

@@ -0,0 +1,9 @@
+# OAuth
+
+```ruby
+oauth = Notion::OAuth::Client.new(client_id:, client_secret:, redirect_uri:)
+redirect_to oauth.authorize_url(state: session[:oauth_state])
+token = oauth.exchange(code: params[:code])
+```
+
+Validate `state` in the callback before exchanging the code. Store access and refresh tokens encrypted at rest.

data/docs/recipes/page-sync.md

@@ -0,0 +1,10 @@
+# Page synchronization
+
+Store each page's `id` and `last_edited_time`. On later runs, query only changed rows:
+
+```ruby
+client.data_sources.sync_since(data_source_id: id, time: last_sync)
+      .each_result { |page| upsert(page.id, page.raw) }
+```
+
+Webhook events are signals, not complete page snapshots; retrieve the page again before persisting it.

data/docs/recipes/pagination.md

@@ -0,0 +1,9 @@
+# Large queries
+
+```ruby
+client.data_sources.query(data_source_id: id, page_size: 100)
+      .each_result
+      .lazy
+      .take(1_000)
+      .each { |page| process(page) }
+```

data/docs/recipes/uploads.md

@@ -0,0 +1,9 @@
+# File uploads
+
+```ruby
+upload = client.upload_file(path: "report.pdf", content_type: "application/pdf")
+```
+
+Files over 20 MiB use the multipart API automatically. Pass `on_progress:` for progress notifications. External imports accept only HTTP(S) URLs.
+
+`client.import_file(url: ...)` waits for the asynchronous import by default. Pass `wait: false` to receive the pending upload immediately.

data/docs/recipes/webhooks.md

@@ -0,0 +1,28 @@
+# Webhooks
+
+```ruby
+use Notion::Webhooks::RackMiddleware, secret: ENV.fetch("NOTION_WEBHOOK_SECRET") do |event|
+  EventJob.perform_later(event.raw)
+end
+```
+
+The middleware verifies Notion's `X-Notion-Signature` raw-body HMAC in constant time. Initial verification-token requests are acknowledged automatically.
+
+The same middleware works in Sinatra:
+
+```ruby
+class WebhookApp < Sinatra::Base
+  use Notion::Webhooks::RackMiddleware, secret: ENV.fetch("NOTION_WEBHOOK_SECRET") do |event|
+    Events.process(event.raw)
+  end
+end
+```
+
+In Rails, add it to `config/application.rb`:
+
+```ruby
+config.middleware.use Notion::Webhooks::RackMiddleware,
+                      secret: ENV.fetch("NOTION_WEBHOOK_SECRET") do |event|
+  EventJob.perform_later(event.raw)
+end
+```

data/lib/generators/notion/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Notion
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "notion.rb", "config/initializers/notion.rb"
+      end
+    end
+  end
+end

data/lib/generators/notion/templates/notion.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Notion.configure do |config|
+  config.token = ENV.fetch("NOTION_TOKEN")
+end

data/lib/notion/batch.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Notion
+  class Batch
+    def initialize(concurrency)
+      unless concurrency.is_a?(Integer) && concurrency.positive?
+        raise ArgumentError, "concurrency must be a positive integer"
+      end
+
+      @concurrency = concurrency
+      @jobs = []
+    end
+
+    def call(&job)
+      raise ArgumentError, "a job block is required" unless job
+
+      @jobs << job
+      self
+    end
+
+    def run
+      queue = Queue.new
+      @jobs.each_with_index { |job, index| queue << [index, job] }
+      results = Array.new(@jobs.length)
+      errors = Array.new(@jobs.length)
+      Array.new([@concurrency, @jobs.length].min) do
+        Thread.new do
+          while (entry = queue.pop(true))
+            index, job = entry
+            begin
+              results[index] = job.call
+            rescue StandardError => e
+              errors[index] = e
+            end
+          end
+        rescue ThreadError
+          nil
+        end
+      end.each(&:join)
+      raise errors.compact.first if errors.any?
+
+      results
+    end
+  end
+end

data/lib/notion/blocks/builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Notion
+  module Blocks
+    class Builder
+      ANNOTATIONS = %i[bold italic strikethrough underline code color].freeze
+
+      attr_reader :blocks
+
+      def initialize
+        @blocks = []
+      end
+
+      def method_missing(type, content = nil, **options, &block)
+        children = self.class.build(&block) if block
+        annotations = options.slice(*ANNOTATIONS)
+        payload = options.except(*ANNOTATIONS).merge("rich_text" => rich_text(content, annotations))
+        payload["children"] = children if children
+        @blocks << { "object" => "block", "type" => type.to_s, type.to_s => payload.compact }
+        self
+      end
+
+      def respond_to_missing?(_name, _include_private = false) = true
+
+      def self.build(&)
+        builder = new
+        builder.instance_eval(&)
+        builder.blocks
+      end
+
+      private
+
+      def rich_text(content, annotations)
+        return content if content.is_a?(Array)
+        return [] if content.nil?
+
+        segments(content.to_s, annotations).map do |segment|
+          item = { "type" => "text", "text" => { "content" => segment } }
+          item["annotations"] = annotation_values(segment, annotations) unless annotations.empty?
+          item
+        end
+      end
+
+      def segments(text, annotations)
+        marked = annotations.values.grep(Array).flatten.map(&:to_s)
+        marked.empty? ? [text] : text.split(/(#{Regexp.union(marked)})/).reject(&:empty?)
+      end
+
+      def annotation_values(segment, annotations)
+        annotations.to_h do |name, value|
+          enabled = value.is_a?(Array) ? value.map(&:to_s).include?(segment) : value
+          [name.to_s, enabled]
+        end
+      end
+    end
+  end
+end

data/lib/notion/blocks/chunker.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Notion
+  module Blocks
+    class Chunker
+      MAX_CHILDREN = 100
+      MAX_BYTES = 500_000
+      MAX_BLOCKS = 1000
+
+      def initialize(children, on_oversize: :split)
+        raise ArgumentError, "on_oversize must be :split or :raise" unless %i[split raise].include?(on_oversize)
+
+        @on_oversize = on_oversize
+        @children = transform(children)
+      end
+
+      def chunks
+        @children.each_with_object([[]]) do |child, groups|
+          raise ValidationError, "a block exceeds the 500KB request limit" if bytes([child]) > MAX_BYTES
+          raise ValidationError, "a block tree exceeds the 1000 block limit" if block_count(child) > MAX_BLOCKS
+
+          groups << [] if full?(groups.last, child)
+          groups.last << child
+        end.reject(&:empty?)
+      end
+
+      private
+
+      def bytes(children)
+        JSON.generate(children: children).bytesize
+      end
+
+      def full?(group, child)
+        group.length >= MAX_CHILDREN || bytes(group + [child]) > MAX_BYTES ||
+          block_count(group) + block_count(child) > MAX_BLOCKS
+      end
+
+      def transform(value)
+        case value
+        when Hash then value.to_h { |key, item| [key, transform(item)] }
+        when Array then value.flat_map { |item| rich_text_item?(item) ? split_item(item) : [transform(item)] }
+        else value
+        end
+      end
+
+      def rich_text_item?(value)
+        value.is_a?(Hash) && value.dig("text", "content").is_a?(String)
+      end
+
+      def split_item(item)
+        text = item.dig("text", "content")
+        raise ValidationError, "rich text exceeds 2000 characters" if @on_oversize == :raise && text.length > 2000
+
+        text.scan(/.{1,2000}/m).map do |content|
+          transform(item.merge("text" => item.fetch("text").merge("content" => content)))
+        end
+      end
+
+      def block_count(value)
+        case value
+        when Hash then (value["object"] == "block" ? 1 : 0) + value.values.sum { |item| block_count(item) }
+        when Array then value.sum { |item| block_count(item) }
+        else 0
+        end
+      end
+    end
+  end
+end

data/lib/notion/blocks.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "blocks/builder"
+require_relative "blocks/chunker"

data/lib/notion/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "transport/net_http_adapter"
+require_relative "compat"
+require_relative "middleware"
+require_relative "objects"
+require_relative "pagination/cursor_paginator"
+require_relative "query"
+require_relative "blocks"
+require_relative "batch"
+require_relative "resolver"
+require_relative "multipart"
+require_relative "file_uploader"
+require_relative "experimental"
+require_relative "endpoints/base"
+require_relative "generated"
+require_relative "endpoints/blocks"
+require_relative "endpoints/data_sources"
+require_relative "endpoints/pages"
+require_relative "endpoints/file_uploads"
+require_relative "endpoints/async_tasks"
+require_relative "endpoints/views"
+
+module Notion
+  class Client
+    attr_reader :config
+
+    def initialize(base_url: "https://api.notion.com", **options)
+      @config = Notion.configuration.merge(**options)
+      @config.betas = @config.betas.dup.freeze
+      @config.freeze
+      adapter = @config.adapter
+      adapter = nil if adapter == :net_http
+      adapter ||= Transport::NetHTTPAdapter.new(@config, base_url: base_url)
+      @app = Middleware::Stack.build(adapter, @config)
+      @endpoints = {}
+      @endpoints_mutex = Mutex.new
+      @resolver = Resolver.new(self)
+      @file_uploader = FileUploader.new(self)
+      @schema_cache = {}
+      @schema_mutex = Mutex.new
+    end
+
+    def request(method, path, query: {}, headers: {}, body: nil, idempotent: nil)
+      method = method.to_sym
+      raise ArgumentError, "path must start with /" unless path.start_with?("/")
+
+      response = @app.call(
+        Transport::Request.new(
+          verb: method,
+          path: path,
+          query: query.compact,
+          headers: headers.transform_keys { |key| key.to_s.downcase },
+          body: body,
+          idempotent: idempotent.nil? ? %i[get delete].include?(method) : idempotent
+        )
+      )
+      raise APIError.from_response(response) unless response.status.between?(200, 299)
+
+      ObjectFactory.build(response.body)
+    end
+
+    def inspect
+      "#<#{self.class} notion_version=#{config.notion_version.inspect}>"
+    end
+
+    Generated::RESOURCES.each_key do |resource|
+      define_method(resource) { endpoint(resource) }
+    end
+
+    def search(**params, &)
+      endpoint(:search).search(**params, &)
+    end
+
+    def resolve_data_source(database_id:, name: nil)
+      @resolver.resolve(database_id, name: name)
+    end
+
+    def query(id, name: nil, **params, &)
+      return data_sources.query(data_source_id: id, **params, &) if config.notion_version == "2022-06-28"
+
+      data_source_id = resolve_data_source(database_id: id, name: name)
+      data_sources.query(data_source_id: data_source_id, **params, &)
+    rescue ObjectNotFoundError
+      data_sources.query(data_source_id: id, **params, &)
+    end
+
+    def upload_file(**)
+      @file_uploader.upload(**)
+    end
+
+    def import_file(**)
+      @file_uploader.import(**)
+    end
+
+    def batch(concurrency: 3)
+      raise ArgumentError, "a batch block is required" unless block_given?
+
+      jobs = Batch.new(concurrency)
+      yield jobs
+      jobs.run
+    end
+
+    def experimental
+      @endpoints_mutex.synchronize { @experimental ||= Experimental.new(self) }
+    end
+
+    def schema_for(data_source_id)
+      cache_key = "notion:schema:#{data_source_id}"
+      external = config.cache&.read(cache_key)
+      return external if external
+
+      @schema_mutex.synchronize do
+        @schema_cache[data_source_id] ||= begin
+          schema = data_sources.retrieve(data_source_id: data_source_id).raw.fetch("properties", {})
+          config.cache&.write(cache_key, schema, expires_in: 900)
+          schema
+        end
+      end
+    end
+
+    def clear_schema_cache(data_source_id = nil)
+      config.cache&.delete("notion:schema:#{data_source_id}") if data_source_id
+      @schema_mutex.synchronize do
+        data_source_id ? @schema_cache.delete(data_source_id) : @schema_cache.clear
+      end
+    end
+
+    private
+
+    def endpoint(resource)
+      @endpoints_mutex.synchronize do
+        @endpoints[resource] ||= Generated::RESOURCES.fetch(resource).new(self)
+      end
+    end
+  end
+end

data/lib/notion/compat/legacy.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "notion"
+
+module Notion
+  class Client
+    alias modern_search search
+
+    def database_query(database_id:, **params, &)
+      deprecate(:database_query, "query")
+      query(database_id, **params, &)
+    end
+
+    def database(database_id:)
+      deprecate(:database, "databases.retrieve")
+      databases.retrieve(database_id: database_id)
+    end
+
+    def page(page_id:)
+      deprecate(:page, "pages.retrieve")
+      pages.retrieve(page_id: page_id)
+    end
+
+    def create_page(**params)
+      deprecate(:create_page, "pages.create")
+      pages.create(**params)
+    end
+
+    def block_children(block_id:, **params)
+      deprecate(:block_children, "blocks.children")
+      blocks.children(block_id: block_id, **params)
+    end
+
+    def search(**params, &block)
+      result = modern_search(**params)
+      return result unless block
+
+      result.each_result(&block)
+    end
+
+    private
+
+    def deprecate(old_name, replacement)
+      warn "Notion::Client##{old_name} is deprecated; use #{replacement}", uplevel: 2
+    end
+  end
+end

data/lib/notion/compat.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Notion
+  module Compat
+    module_function
+
+    def request(version, request)
+      reject_unsupported!(version, request.path)
+      return request if version == "2026-03-11"
+
+      path = request.path
+      path = path.sub(%r{\A/v1/data_sources(?=/|\z)}, "/v1/databases") if version == "2022-06-28"
+      request.with(path: path, body: downgrade(request.body, version))
+    end
+
+    def response(version, response)
+      return response if version == "2026-03-11" || !response.body.is_a?(Hash)
+
+      response.with(body: normalize(response.body, version))
+    end
+
+    def downgrade(value, version)
+      case value
+      when Array then value.map { |item| downgrade(item, version) }
+      when Hash then value.to_h { |key, item| downgrade_pair(key, item, version) }
+      else value
+      end
+    end
+
+    def downgrade_pair(key, item, version)
+      reject_meeting_notes!(key, item, version)
+      if key.to_s == "position" && item.is_a?(Hash) && item["type"] == "after_block"
+        return ["after", item.dig("after_block", "id")]
+      end
+
+      new_key = downgrade_key(key, version)
+      new_item = downgrade_value(key, item, version)
+      [new_key, new_item]
+    end
+
+    def reject_meeting_notes!(key, item, version)
+      meeting_notes = key.to_s == "meeting_notes" || (key.to_s == "type" && item == "meeting_notes")
+      return unless version == "2022-06-28" && meeting_notes
+
+      raise UnsupportedInVersionError, "meeting_notes is unavailable in Notion API #{version}"
+    end
+
+    def downgrade_value(key, item, version)
+      return "transcription" if key.to_s == "type" && item == "meeting_notes"
+
+      downgrade(item, version)
+    end
+
+    def downgrade_key(key, version)
+      key = key.to_s
+      return "archived" if key == "in_trash"
+      return "transcription" if version == "2025-09-03" && key == "meeting_notes"
+      return "database_id" if version == "2022-06-28" && key == "data_source_id"
+
+      key
+    end
+
+    def normalize(value, version)
+      value.each_with_object({}) do |(key, item), result|
+        new_key = { "archived" => "in_trash", "transcription" => "meeting_notes" }.fetch(key, key)
+        new_key = "data_source_id" if version == "2022-06-28" && new_key == "database_id"
+        result[new_key] = if key == "type" && item == "transcription"
+                            "meeting_notes"
+                          else
+                            normalize_value(item, version)
+                          end
+      end
+    end
+
+    def normalize_value(item, version)
+      case item
+      when Hash then normalize(item, version)
+      when Array then item.map { |entry| normalize_value(entry, version) }
+      else item
+      end
+    end
+
+    def reject_unsupported!(version, path)
+      return if version == "2026-03-11"
+
+      unsupported = path.match?(%r{\A/v1/(views|agents|sessions)(?=/|\z)}) || path.end_with?("/markdown")
+      unsupported ||= path.match?(%r{\A/v1/blocks/meeting_notes(?=/|\z)})
+      unsupported ||= version == "2022-06-28" && path.match?(%r{\A/v1/data_sources/[^/]+/templates})
+      return unless unsupported
+
+      raise UnsupportedInVersionError, "#{path} is unavailable in Notion API #{version}"
+    end
+  end
+end

data/lib/notion/config.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Notion
+  class ConfigurationError < StandardError; end
+
+  class Config
+    API_VERSIONS = %w[2022-06-28 2025-09-03 2026-03-11].freeze
+
+    attr_accessor :token, :notion_version, :betas, :open_timeout, :read_timeout,
+                  :max_attempts, :retry_cap, :rate, :burst, :logger, :log_level,
+                  :user_agent, :ca_file, :proxy, :strict, :adapter, :token_store,
+                  :token_key, :oauth_client, :auto_refresh, :cache, :rate_limit_store
+
+    def initialize
+      @token = ENV.fetch("NOTION_TOKEN", nil)
+      @notion_version = ENV.fetch("NOTION_API_VERSION", "2026-03-11")
+      @betas = []
+      @open_timeout = 5
+      @read_timeout = 65
+      @max_attempts = 5
+      @retry_cap = 30
+      @rate = 3.0
+      @burst = 6
+      @log_level = :info
+      @user_agent = "notion-client-ruby/#{Notion::VERSION} (ruby/#{RUBY_VERSION})"
+      @strict = false
+      @token_key = :default
+      @auto_refresh = false
+    end
+
+    def timeout=(values)
+      self.open_timeout = values.fetch(:open, open_timeout)
+      self.read_timeout = values.fetch(:read, read_timeout)
+    end
+
+    def retry=(values)
+      self.max_attempts = values.fetch(:max_attempts, max_attempts)
+      self.retry_cap = values.fetch(:cap, retry_cap)
+    end
+
+    def rate_limit=(values)
+      self.rate = values.fetch(:rate, rate)
+      self.burst = values.fetch(:burst, burst)
+      self.rate_limit_store = values[:store] == :memory ? nil : values[:store] if values.key?(:store)
+    end
+
+    def validate!(require_token: false)
+      raise ConfigurationError, "token is required" if require_token && blank?(@token) && !@token_store
+      unless API_VERSIONS.include?(@notion_version)
+        raise ConfigurationError, "unsupported Notion API version: #{@notion_version}"
+      end
+
+      positive_values.each do |name, value|
+        raise ConfigurationError, "#{name} must be positive" unless value.to_f.positive?
+      end
+
+      self
+    end
+
+    def merge(**options)
+      copy = dup
+      options.each do |name, value|
+        writer = "#{name}="
+        raise ConfigurationError, "unknown option: #{name}" unless copy.respond_to?(writer)
+
+        copy.public_send(writer, value)
+      end
+      copy.validate!
+    end
+
+    private
+
+    def positive_values
+      {
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout,
+        max_attempts: @max_attempts,
+        retry_cap: @retry_cap,
+        rate: @rate,
+        burst: @burst
+      }
+    end
+
+    def blank?(value)
+      value.nil? || value.empty?
+    end
+  end
+end