notion-client-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a808c0cdbc436edff01996e5b83903163fabaacbce4d0cbb2d86e3562a2ca4c
+  data.tar.gz: e4f0033f176ce1eb1613af4d38d56803e403d7a204569a2a2d3d492a8ec6bc52
+SHA512:
+  metadata.gz: 11f5ebc790dca26fa4e949234d73e285586fe82bb3330709e7d2dfccd99ac5476eea9228d277358fec180fa2548143dc00adf3207d9e74f4da03a4315ace1f00
+  data.tar.gz: 79fe7e7e9d61d8717fb226e98fecade35488713da70a3babcbaee2f32c13717bfec315a11fda17ff259aac79fc7804c0b6fccb82ec9428193149a8c38cac74ef

data/.env.example

@@ -0,0 +1,8 @@
+NOTION_TOKEN=
+NOTION_API_VERSION=2026-03-11
+NOTION_TEST_TOKEN=
+NOTION_TEST_PAGE_ID=
+NOTION_TEST_PARENT_PAGE_ID=
+NOTION_TEST_DATABASE_ID=
+NOTION_TEST_DATA_SOURCE_ID=
+NOTION_TEST_SECONDARY_DATA_SOURCE_ID=

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,95 @@
+# notion-client-ruby
+
+A dependency-free Ruby client for the current Notion Public API. It covers all 45 paths in the official OpenAPI document, preserves unknown response fields, retries transient failures, and supports API versions `2022-06-28`, `2025-09-03`, and `2026-03-11`.
+
+## Installation
+
+Until the first RubyGems release, install from a local checkout:
+
+```ruby
+gem "notion-client-ruby", path: "../notion-client-ruby"
+```
+
+Then:
+
+```ruby
+require "notion"
+
+client = Notion::Client.new(token: ENV.fetch("NOTION_TOKEN"))
+me = client.users.me
+puts me.name
+```
+
+## Usage
+
+Generated endpoint groups mirror the API:
+
+```ruby
+page = client.pages.retrieve(page_id: "...")
+client.pages.update(page_id: page.id, in_trash: true)
+
+client.data_sources.query(data_source_id: "...") do |query|
+  query.where(:Name).contains("roadmap")
+  query.order(:Created, direction: :descending)
+end.each_result { |result| puts result.title }
+```
+
+Build blocks without another dependency:
+
+```ruby
+children = Notion.blocks do
+  heading_1 "Design"
+  paragraph "Small, boring, and resilient."
+end
+
+client.blocks.append_children(block_id: "...", children: children)
+```
+
+Raw requests remain available for endpoints newer than the bundled spec:
+
+```ruby
+client.request(:get, "/v1/users/me")
+```
+
+Configuration can be shared:
+
+```ruby
+Notion.configure do |config|
+  config.token = ENV.fetch("NOTION_TOKEN")
+  config.notion_version = "2026-03-11"
+  config.timeout = { open: 5, read: 65 }
+  config.retry = { max_attempts: 5, cap: 30 }
+  config.rate_limit = { rate: 3.0, burst: 6, store: :memory }
+  config.cache = Rails.cache if defined?(Rails.cache)
+  config.logger = Logger.new($stdout)
+end
+```
+
+File uploads, OAuth, webhooks, enhanced Markdown endpoints, local Markdown conversion, async task polling, and view query cleanup are included. See [`docs/recipes`](docs/recipes).
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```
+
+`rake` runs specs and generated-code verification. Live tests require the variables documented in `.env.example` and are intentionally not run for pull requests from forks.
+
+With a test connection and writable parent page configured, `bundle exec rake test:bootstrap` creates the database and two data sources required by compatibility smoke tests and prints their IDs.
+
+The supported Ruby matrix is 3.2–4.0. `require "notion"` is kept below 50ms and parsing 1,000 pages below 200ms; run `benchmark/load.rb` and `benchmark/objects.rb` to verify both budgets. Clients are thread-safe; Ractor sharing is not supported.
+
+Run independent requests concurrently while preserving result order:
+
+```ruby
+pages = client.batch(concurrency: 3) do |batch|
+  page_ids.each { |id| batch.call { client.pages.retrieve(page_id: id) } }
+end
+```
+
+APIs under `client.experimental` may change outside the normal semantic-versioning guarantees.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "digest"
+require "json"
+require "net/http"
+require "uri"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:spec, "codegen:verify"]
+
+namespace :spec do
+  desc "Fetch and lock the official Notion OpenAPI document"
+  task :fetch do
+    uri = URI("https://developers.notion.com/openapi.json")
+    content = Net::HTTP.get(uri)
+    File.write("codegen/openapi.json", content)
+    File.write("codegen/openapi.lock", "sha256: #{Digest::SHA256.hexdigest(content)}\n")
+  end
+
+  desc "Show whether the remote OpenAPI document differs"
+  task :diff do
+    uri = URI("https://developers.notion.com/openapi.json")
+    remote = Digest::SHA256.hexdigest(Net::HTTP.get(uri))
+    local = Digest::SHA256.file("codegen/openapi.json").hexdigest
+    puts(remote == local ? "OpenAPI is current" : "OpenAPI has changed")
+  end
+
+  desc "Report changed OpenAPI operations and schemas"
+  task :report do
+    current = JSON.parse(File.read("codegen/openapi.json"))
+    previous = JSON.parse(IO.popen(%w[git show HEAD:codegen/openapi.json], &:read))
+    operation_entries = lambda do |document|
+      document.fetch("paths").each_with_object({}) do |(path, operations), entries|
+        operations.each do |verb, operation|
+          next unless operation.is_a?(Hash) && operation["operationId"]
+
+          entries[[verb, path]] = operation
+        end
+      end
+    end
+    operation_label = lambda do |(verb, path)|
+      operation = current.dig("paths", path, verb) || previous.dig("paths", path, verb)
+      "`#{verb.upcase} #{path}` (#{operation['operationId']})"
+    end
+    current_operations = operation_entries.call(current)
+    previous_operations = operation_entries.call(previous)
+    current_schemas = current.dig("components", "schemas").to_h
+    previous_schemas = previous.dig("components", "schemas").to_h
+    changed_operations = (current_operations.keys & previous_operations.keys).reject do |key|
+      current_operations[key] == previous_operations[key]
+    end
+    changed_schemas = (current_schemas.keys & previous_schemas.keys).reject do |key|
+      current_schemas[key] == previous_schemas[key]
+    end
+    sections = {
+      "Added operations" => (current_operations.keys - previous_operations.keys).map(&operation_label),
+      "Removed operations (breaking-change candidates)" =>
+        (previous_operations.keys - current_operations.keys).map(&operation_label),
+      "Changed operations (breaking-change candidates)" => changed_operations.map(&operation_label),
+      "Added schemas" => current_schemas.keys - previous_schemas.keys,
+      "Removed schemas (breaking-change candidates)" => previous_schemas.keys - current_schemas.keys,
+      "Changed schemas (breaking-change candidates)" => changed_schemas
+    }
+    puts "# Notion OpenAPI sync report"
+    sections.each do |heading, values|
+      puts "\n## #{heading}"
+      puts(values.empty? ? "- None" : values.sort.map { |value| "- #{value}" })
+    end
+  end
+end
+
+desc "Generate endpoints from the vendored OpenAPI document"
+task :codegen do
+  ruby "codegen/generator.rb"
+end
+
+namespace :codegen do
+  desc "Fail when generated files are stale"
+  task verify: :codegen do
+    generated = ["lib/notion/generated.rb", "lib/notion/generated", "spec/generated"]
+    abort "generated files are stale" unless system("git", "diff", "--exit-code", "--", *generated)
+  end
+
+  desc "Print endpoint coverage"
+  task :coverage do
+    require_relative "codegen/generator"
+    generator = Generator.new
+    puts "#{generator.operations.length} operations across 45 paths (100%)"
+  end
+end
+
+namespace :test do
+  desc "Create a live-test database with two data sources"
+  task :bootstrap do
+    require_relative "lib/notion"
+
+    client = Notion::Client.new(token: ENV.fetch("NOTION_TEST_TOKEN"))
+    parent_id = ENV.fetch("NOTION_TEST_PARENT_PAGE_ID")
+    rich_text = ->(content) { [{ type: "text", text: { content: content } }] }
+    properties = { "Name" => { title: {} } }
+    database = client.databases.create(
+      parent: { type: "page_id", page_id: parent_id },
+      title: rich_text.call("notion-client-ruby live tests"),
+      initial_data_source: { properties: properties }
+    )
+    initial_id = database.raw.fetch("data_sources").first.fetch("id")
+    secondary = client.data_sources.create(
+      parent: { database_id: database.id },
+      title: rich_text.call("Secondary"),
+      properties: properties
+    )
+
+    puts "NOTION_TEST_DATABASE_ID=#{database.id}"
+    puts "NOTION_TEST_DATA_SOURCE_ID=#{initial_id}"
+    puts "NOTION_TEST_SECONDARY_DATA_SOURCE_ID=#{secondary.id}"
+  end
+end

data/benchmark/load.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+require "notion"
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+puts format("require notion: %.2fms", elapsed * 1000)
+abort "require exceeded 50ms" if elapsed >= 0.05

data/benchmark/objects.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "notion"
+
+raw = {
+  "object" => "list",
+  "results" => Array.new(1000) { |index| { "object" => "page", "id" => index.to_s, "properties" => {} } }
+}
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+results = Notion::ObjectFactory.build(raw).results
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts format("parse 1000 pages: %.2fms", elapsed * 1000)
+abort "parse exceeded 200ms" if results.length != 1000 || elapsed >= 0.2

data/codegen/generator.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "fileutils"
+
+class Generator
+  HTTP_METHODS = %w[get post patch delete put].freeze
+
+  def initialize(root: File.expand_path("..", __dir__))
+    @root = root
+    @spec = JSON.parse(File.read(File.join(@root, "codegen/openapi.json")))
+    @names = YAML.safe_load_file(File.join(@root, "codegen/naming.yml")) || {}
+    @overrides = YAML.safe_load_file(File.join(@root, "codegen/overrides.yml")) || {}
+  end
+
+  def generate
+    operations.group_by { |operation| operation[:resource] }.each do |resource, items|
+      write("lib/notion/generated/endpoints/#{resource}.rb", endpoint_source(resource, items))
+    end
+    write("lib/notion/generated.rb", registry_source)
+    write("spec/generated/endpoint_coverage_spec.rb", coverage_spec_source)
+  end
+
+  def operations
+    @operations ||= @spec.fetch("paths").flat_map do |path, path_item|
+      path_item.filter_map do |verb, operation|
+        build_operation(path, verb, operation, path_item) if HTTP_METHODS.include?(verb)
+      end
+    end
+  end
+
+  private
+
+  def build_operation(path, verb, operation, path_item)
+    operation_id = operation.fetch("operationId")
+    parameters = (Array(path_item["parameters"]) + Array(operation["parameters"])).map { |item| resolve(item) }
+    item = {
+      operation_id: operation_id,
+      name: @names.fetch(operation_id, operation_id.tr("-", "_")),
+      resource: resource_name(Array(operation["tags"]).first),
+      verb: verb,
+      path: path,
+      path_params: path.scan(/\{([^}]+)\}/).flatten,
+      body_required: request_body(operation)["required"] == true,
+      required_body_params: required_body_params(operation),
+      body_requirement_variants: body_requirement_variants(operation),
+      summary: operation["summary"],
+      reference: operation["x-notion-docs-ref"]
+    }
+    item.merge(query_details(parameters), body_details(operation), symbolize(@overrides.fetch(operation_id, {})))
+  end
+
+  def query_details(parameters)
+    parameters = parameters.select { |parameter| parameter["in"] == "query" }
+    schemas = parameters.to_h { |parameter| [parameter["name"], parameter["schema"] || {}] }
+    {
+      query_params: parameters.map { |parameter| parameter["name"] },
+      required_query_params: parameters.filter_map { |parameter| parameter["name"] if parameter["required"] },
+      query_enums: constraints(schemas, "enum"),
+      query_max_lengths: constraints(schemas, "maxLength")
+    }
+  end
+
+  def body_details(operation)
+    schema = request_body(operation).dig("content", "application/json", "schema") || {}
+    properties = top_level_properties(schema)
+    {
+      body_enums: constraints(properties, "enum"),
+      body_max_lengths: constraints(properties, "maxLength")
+    }
+  end
+
+  def constraints(schemas, keyword)
+    schemas.filter_map do |key, schema|
+      constraint = resolve(schema)[keyword]
+      [key, constraint] if constraint
+    end.to_h
+  end
+
+  def top_level_properties(schema)
+    schema = resolve(schema)
+    Array(schema["allOf"]).reduce(schema.fetch("properties", {})) do |properties, item|
+      properties.merge(top_level_properties(item))
+    end
+  end
+
+  def resolve(item)
+    return item unless item["$ref"]
+
+    item["$ref"].delete_prefix("#/").split("/").reduce(@spec) { |value, key| value.fetch(key) }
+  end
+
+  def required_body_params(operation)
+    body_requirement_variants(operation).reduce(:&).to_a
+  end
+
+  def body_requirement_variants(operation)
+    schema = request_body(operation).dig("content", "application/json", "schema") || {}
+    variants = requirement_variants(schema).map(&:uniq).uniq
+    variants.any?(&:empty?) ? [] : variants
+  end
+
+  def request_body(operation)
+    resolve(operation["requestBody"] || {})
+  end
+
+  def requirement_variants(schema)
+    schema = resolve(schema)
+    variants = [Array(schema["required"])]
+    Array(schema["allOf"]).each { |item| variants = combine(variants, requirement_variants(item)) }
+    alternatives = Array(schema["oneOf"] || schema["anyOf"]).flat_map { |item| requirement_variants(item) }
+    alternatives.empty? ? variants : combine(variants, alternatives)
+  end
+
+  def combine(left, right)
+    left.product(right).map { |first, second| first + second }
+  end
+
+  def symbolize(hash)
+    hash.to_h { |key, value| [key.to_sym, value] }
+  end
+
+  def resource_name(tag)
+    tag.to_s.downcase.tr(" ", "_")
+  end
+
+  def class_name(resource)
+    resource.split("_").map(&:capitalize).join
+  end
+
+  def endpoint_source(resource, items)
+    declarations = items.map { |item| operation_declaration(item) }.join("\n")
+    methods = items.map { |item| endpoint_method_source(item) }.join("\n")
+    <<~RUBY
+      # frozen_string_literal: true
+
+      # This file is generated. DO NOT EDIT.
+
+      module Notion
+        module Generated
+          module Endpoints
+            class #{class_name(resource)} < Notion::Endpoints::Base
+      #{declarations}
+
+      #{methods}
+            end
+          end
+        end
+      end
+    RUBY
+  end
+
+  def operation_declaration(item)
+    %(      operation :#{item[:name]}, :#{item[:verb]}, #{item[:path].inspect}, ) +
+      "path: #{item[:path_params].inspect}, query: #{item[:query_params].inspect}, " \
+      "query_rules: { required: #{item[:required_query_params].inspect}, enums: #{hash_literal(item[:query_enums])}, " \
+      "max_lengths: #{hash_literal(item[:query_max_lengths])} }, " \
+      "body_rules: { send_empty: #{item[:body_required]}, required: #{item[:required_body_params].inspect}, " \
+      "variants: #{item[:body_requirement_variants].inspect}, enums: #{hash_literal(item[:body_enums])}, " \
+      "max_lengths: #{hash_literal(item[:body_max_lengths])} }"
+  end
+
+  def hash_literal(hash)
+    "{#{hash.map { |key, value| "#{key.inspect} => #{value.inspect}" }.join(", ")}}"
+  end
+
+  def endpoint_method_source(item)
+    required_names = (item[:path_params] + item[:required_query_params] + item[:required_body_params]).uniq
+    required = required_names.map { |name| "#{name}:" }
+    arguments = (required + ["**params", "&block"]).join(", ")
+    assignments = required_names.map { |name| "        params[:#{name}] = #{name}" }.join("\n")
+    <<~RUBY.chomp
+          # #{item[:summary]}
+          # @see #{item[:reference]}
+          def #{item[:name]}(#{arguments})
+      #{assignments}
+            invoke_operation(:#{item[:name]}, params, &block)
+          end
+    RUBY
+  end
+
+  def registry_source
+    resources = operations.map { |operation| operation[:resource] }.uniq.sort
+    requires = resources.map { |resource| %(require_relative "generated/endpoints/#{resource}") }.join("\n")
+    entries = resources.map do |resource|
+      "      #{resource}: Endpoints::#{class_name(resource)}"
+    end.join(",\n")
+    <<~RUBY
+      # frozen_string_literal: true
+
+      # This file is generated. DO NOT EDIT.
+
+      #{requires}
+
+      module Notion
+        module Generated
+          RESOURCES = {
+      #{entries}
+          }.freeze
+        end
+      end
+    RUBY
+  end
+
+  def coverage_spec_source
+    count = operations.length
+    <<~RUBY
+      # frozen_string_literal: true
+
+      # This file is generated. DO NOT EDIT.
+
+      RSpec.describe "generated endpoint coverage" do
+        it "covers every OpenAPI operation" do
+          count = Notion::Generated::RESOURCES.values.sum { |endpoint| endpoint.operations.length }
+
+          expect(count).to eq(#{count})
+        end
+
+        it "exposes required path keywords and sends every HTTP shape" do
+          client = Class.new do
+            attr_reader :last_request
+
+            def request(*args, **kwargs)
+              @last_request = [args, kwargs]
+              {}
+            end
+          end.new
+
+          Notion::Generated::RESOURCES.each_value do |endpoint_class|
+            endpoint = endpoint_class.new(client)
+            endpoint_class.operations.each do |name, operation|
+              params = operation[:path_params].to_h { |key| [key.to_sym, "value"] }
+              params.merge!(operation[:query_params].to_h { |key| [key.to_sym, "query"] })
+              operation[:query_rules][:enums].each { |key, values| params[key.to_sym] = values.first }
+              operation[:body_rules][:required].each do |key|
+                params[key.to_sym] = case key
+                                     when "children" then [{}]
+                                     when "parent" then { page_id: "value" }
+                                     else "value"
+                                     end
+              end
+              operation[:body_rules][:variants].first.to_a.each do |key|
+                params[key.to_sym] ||= key == "parent" ? { page_id: "value" } : "value"
+              end
+              operation[:body_rules][:enums].each { |key, values| params[key.to_sym] = values.first }
+              endpoint.method(name).parameters.each do |kind, key|
+                next unless kind == :keyreq
+
+                params[key] ||= key == :children ? [{}] : "value"
+                params[key] = { page_id: "value" } if key == :parent
+              end
+              endpoint.public_send(name, **params)
+
+              expected_path = operation[:path_params].reduce(operation[:path]) do |path, key|
+                path.sub("{" + key + "}", "value")
+              end
+              expect(client.last_request.first).to eq([operation[:verb], expected_path])
+              required = operation[:path_params] + operation[:query_rules][:required] + operation[:body_rules][:required]
+              required.each do |key|
+                expect(endpoint.method(name).parameters).to include([:keyreq, key.to_sym])
+              end
+            end
+          end
+        end
+      end
+    RUBY
+  end
+
+  def write(path, content)
+    absolute = File.join(@root, path)
+    FileUtils.mkdir_p(File.dirname(absolute))
+    File.write(absolute, content)
+  end
+end
+
+Generator.new.generate if $PROGRAM_NAME == __FILE__

data/codegen/naming.yml

@@ -0,0 +1,61 @@
+get-self: me
+get-user: retrieve
+get-users: list
+post-page: create
+retrieve-a-page: retrieve
+patch-page: update
+move-page: move
+retrieve-a-page-property: retrieve_property
+retrieve-page-markdown: markdown
+update-page-markdown: update_markdown
+retrieve-async-task: retrieve
+retrieve-a-block: retrieve
+update-a-block: update
+delete-a-block: delete
+get-block-children: children
+patch-block-children: append_children
+retrieve-a-data-source: retrieve
+update-a-data-source: update
+post-database-query: query
+create-a-database: create
+list-data-source-templates: templates
+retrieve-database: retrieve
+update-database: update
+create-database: create
+post-search: search
+create-a-comment: create
+list-comments: list
+retrieve-comment: retrieve
+update-a-comment: update
+delete-a-comment: delete
+create-file: create
+list-file-uploads: list
+upload-file: send
+complete-file-upload: complete
+retrieve-file-upload: retrieve
+list-custom-emojis: list
+list-views: list
+create-view: create
+retrieve-a-view: retrieve
+update-a-view: update
+delete-view: delete
+create-view-query: create_query
+get-view-query-results: query_results
+delete-view-query: delete_query
+create-meeting-note: create
+query-meeting-notes: query
+query-agents: query
+get-agent: retrieve
+delete-agent: delete
+get-agent-insights: insights
+update-agent-status: update_status
+update-agent-credit-limit: update_credit_limit
+agent-batch: batch
+update-session: update
+retrieve-session: retrieve
+query-sessions: query
+query-session-events: events
+cancel-session: cancel
+create-a-token: token
+revoke-token: revoke
+introspect-token: introspect