Class: Woods::Notion::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/woods/notion/client.rb

Overview

Thin wrapper around the Notion REST API (v2022-06-28).

Uses Net::HTTP (stdlib) for zero external dependencies. All requests are throttled through a RateLimiter to respect Notion’s 3 req/sec limit.

Examples:

client = Client.new(api_token: "secret_...")
client.create_page(database_id: "db-uuid", properties: { ... })
client.query_database(database_id: "db-uuid", filter: { ... })

Constant Summary collapse

BASE_URL =

rubocop:disable Metrics/ClassLength

'https://api.notion.com/v1'
NOTION_VERSION = 
'2022-06-28'
MAX_RETRIES = 
3
DEFAULT_TIMEOUT = 
30

Instance Method Summary collapse

Constructor Details

#initialize(api_token:, rate_limiter: RateLimiter.new) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_token (String) —

    Notion integration API token

  • rate_limiter (RateLimiter) (defaults to: RateLimiter.new) —

    Rate limiter instance (default: 3 req/sec)

Raises:

  • (ArgumentError) —

    if api_token is nil or empty



30
31
32
33
34
35
 
# File 'lib/woods/notion/client.rb', line 30

def initialize(api_token:, rate_limiter: RateLimiter.new)
  raise ArgumentError, 'api_token is required' if api_token.nil? || api_token.to_s.empty?

  @api_token = api_token
  @rate_limiter = rate_limiter
end

Instance Method Details

#create_page(database_id:, properties:, children: []) ⇒ Hash

Create a page in a Notion database.

Parameters:

  • database_id (String) —

    Target database UUID

  • properties (Hash) —

    Page properties in Notion API format

  • children (Array<Hash>) (defaults to: []) —

    Optional page content blocks

Returns:

  • (Hash) —

    Created page data



43
44
45
46
47
48
49
50
51
 
# File 'lib/woods/notion/client.rb', line 43

def create_page(database_id:, properties:, children: [])
  body = {
    parent: { database_id: database_id },
    properties: properties
  }
  body[:children] = children if children.any?

  request(:post, 'pages', body)
end

#find_page_by_title(database_id:, title:) ⇒ Hash?

Find a page by its title property value.

Parameters:

  • database_id (String) —

    Database UUID

  • title (String) —

    Title text to search for

Returns:

  • (Hash, nil) —

    First matching page or nil



106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/woods/notion/client.rb', line 106

def find_page_by_title(database_id:, title:)
  response = query_database(
    database_id: database_id,
    filter: {
      property: 'title',
      title: { equals: title }
    }
  )

  results = response['results'] || []
  results.first
end

#query_all(database_id:, filter: nil) ⇒ Array<Hash>

Query all pages from a database, auto-paginating.

Parameters:

  • database_id (String) —

    Database UUID

  • filter (Hash, nil) (defaults to: nil) —

    Notion filter object

Returns:

  • (Array<Hash>) —

    All matching pages



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/woods/notion/client.rb', line 81

def query_all(database_id:, filter: nil)
  all_results = []
  cursor = nil

  loop do
    body = {}
    body[:filter] = filter if filter
    body[:start_cursor] = cursor if cursor

    response = request(:post, "databases/#{database_id}/query", body)
    all_results.concat(response['results'] || [])

    break unless response['has_more']

    cursor = response['next_cursor']
  end

  all_results
end

#query_database(database_id:, filter: nil, sorts: nil) ⇒ Hash

Query a database with optional filter and sort.

Parameters:

  • database_id (String) —

    Database UUID

  • filter (Hash, nil) (defaults to: nil) —

    Notion filter object

  • sorts (Array<Hash>, nil) (defaults to: nil) —

    Notion sort objects

Returns:

  • (Hash) —

    Query results with ‘results’, ‘has_more’, ‘next_cursor’



68
69
70
71
72
73
74
 
# File 'lib/woods/notion/client.rb', line 68

def query_database(database_id:, filter: nil, sorts: nil)
  body = {}
  body[:filter] = filter if filter
  body[:sorts] = sorts if sorts

  request(:post, "databases/#{database_id}/query", body)
end

#update_page(page_id:, properties:) ⇒ Hash

Update an existing page’s properties.

Parameters:

  • page_id (String) —

    Page UUID to update

  • properties (Hash) —

    Properties to update

Returns:

  • (Hash) —

    Updated page data



58
59
60
 
# File 'lib/woods/notion/client.rb', line 58

def update_page(page_id:, properties:)
  request(:patch, "pages/#{page_id}", { properties: properties })
end