ask-notion 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f2b7ca05f8f6271299178580e3660f4b5a014977845d79a21a442ba0dad5d33
-  data.tar.gz: 1fd261c3a9184fba6e88e372771a35f71aa33954b0dda99cbada5addd1a80d20
+  metadata.gz: 10fd8189426e5d6f0b2a48dceab879344e8875d6edd4d8e40a0c2b8926129047
+  data.tar.gz: dc4a9867f46503da940d6f1572c6b17a012478165ff373ef13b8c08d36425632
 SHA512:
-  metadata.gz: 8d3c5718162b896aed53f44118403c2d470372ce2e305eb7e88315d52885a8c7a1f324c09dfe9d72ad783e8e20957feeab91dfb96d534ba728a5a4cc48534c9a
-  data.tar.gz: b2ae58df4217e6658378a3d3f6ba3d52b9002950b7c1df664a3bdf177022f02c45582e34462543616de77ae31c412cd46310b72e0c0f6ba60f2026d4250fd26d
+  metadata.gz: 045c832fa42bc8b2e9e905210a8a50949458541343f192fd66f674c41d75f3621c1aae255ded8953afe4f06e6faa1b4008cc4ba15e534e8a8f6fe62da623253d
+  data.tar.gz: 9fd11d103a3267320d4f731bf180bfda4e0bb5b8cb7c03871634061ad83bc6e867e2685249af60672112a3dbd05ddfd26511fa42ef849a352baf53657ea16266

data/lib/ask/notion/client.rb

@@ -5,16 +5,22 @@ require "ask/auth"
 
 module Ask
   module Notion
+    # Default number of retries for transient failures.
+    DEFAULT_RETRIES = 3
+
     # Returns an authenticated Notion API client configured for an AI agent.
     #
     # Resolves the Notion token via +Ask::Auth.resolve(:notion_token)+ and
-    # wraps the client in a proxy that converts +Notion::Api::Errors::Unauthorized+
-    # into +Ask::Auth::InvalidCredential+.
+    # wraps the client in a proxy that converts authentication, timeout, and
+    # network errors into ask-rb equivalents.
     #
     # The client inherits default configuration from +Notion::Config+:
     # - +token+: resolved via Ask::Auth
     # - +logger+: default logger
     #
+    # Retries transient failures (rate limits, server errors) up to
+    # {DEFAULT_RETRIES} times with exponential backoff.
+    #
     # @example
     #   client = Ask::Notion.client
     #   client.database_query(database_id: "abc123")
@@ -28,17 +34,33 @@ module Ask
       ClientProxy.new(::Notion::Client.new(token: token))
     end
 
-    # Proxies method calls to a +::Notion::Client+, converting authentication
-    # errors into +Ask::Auth::InvalidCredential+.
+    # Proxies method calls to a +::Notion::Client+, converting authentication,
+    # timeout, and network errors into ask-rb exceptions with automatic retry
+    # for transient failures.
     class ClientProxy < BasicObject
       def initialize(client)
         @client = client
       end
 
       def method_missing(name, ...)
-        @client.public_send(name, ...)
-      rescue ::Notion::Api::Errors::Unauthorized
-        ::Kernel.raise ::Ask::Auth::InvalidCredential, :notion_token
+        retries = 0
+        begin
+          @client.public_send(name, ...)
+        rescue ::Notion::Api::Errors::Unauthorized
+          ::Kernel.raise ::Ask::Auth::InvalidCredential, :notion_token
+        rescue ::Notion::Api::Errors::TooManyRequests,
+               ::Notion::Api::Errors::UnavailableError,
+               ::Notion::Api::Errors::ServerError,
+               ::Timeout::Error,
+               ::Errno::ECONNREFUSED,
+               ::Errno::ECONNRESET
+          retries += 1
+          if retries <= ::Ask::Notion::DEFAULT_RETRIES
+            ::Kernel.sleep(2 ** retries * 0.1)
+            retry
+          end
+          ::Kernel.raise
+        end
       end
 
       def respond_to_missing?(name, include_private = false)

data/lib/ask/notion/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Notion
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

data/lib/ask/skills/notion.use_notion/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: notion.use_notion
+description: How to navigate the Notion API with notion-ruby-client — discover endpoints, handle auth, pagination, and errors
+---
+
+Use this skill when you need to interact with Notion — reading/writing pages and
+databases, managing blocks, searching, or updating properties.
+
+## Step 1: Get the Client
+
+```ruby
+client = Ask::Notion.client
+```
+
+This returns an authenticated `Notion::Client`. It expects a valid Notion
+Internal Integration Token resolved via `Ask::Auth.resolve(:notion_token)`.
+
+If you get an auth error, read `Ask::Notion::Context::AUTH_HOW` for token setup.
+
+## Step 2: Explore the Context
+
+The gem ships with structured context you should reference:
+
+```ruby
+Ask::Notion::Context::DOCS_URL     # Notion developer docs
+Ask::Notion::Context::API_REF_URL  # Notion API reference
+Ask::Notion::Context::GEM_DOCS     # notion-ruby-client docs
+Ask::Notion::Context::QUICK_START  # Copy-paste examples
+```
+
+The `QUICK_START` constant has examples for database queries, page CRUD, block
+children, and search.
+
+## Step 3: Discover Available Methods
+
+Use code tools to explore the available client methods:
+
+```ruby
+Code.new.call(code: "
+  client = Ask::Notion.client
+  puts client.methods(false).sort.join(\"\\n\")
+")
+```
+
+Common Notion API calls:
+- `client.database_query(database_id:, filter:, sorts:)` — query a database
+- `client.database_retrieve(database_id:)` — get database schema
+- `client.page_retrieve(page_id:)` — read a page
+- `client.page_create(parent:, properties:)` — create a page
+- `client.page_update(page_id:, properties:)` — update page properties
+- `client.block_children_list(block_id:)` — list page blocks
+- `client.append_block_children(block_id:, children:)` — add blocks
+- `client.search(query:)` — search across pages and databases
+
+For method details, read the client source:
+```ruby
+Grep.new.call(pattern: "def database_query", path: "$GEM_PATH/notion-ruby-client-*/lib")
+```
+
+## Step 4: Property Formatting (Most Common Pitfall)
+
+Notion properties are complex. Before creating or updating, always check the
+database schema first:
+
+```ruby
+db = client.database_retrieve(database_id: "YOUR_DB_ID")
+db.properties.each do |name, prop|
+  puts "#{name}: #{prop.type}"
+end
+```
+
+Property values follow this format pattern:
+```ruby
+{
+  "Name": { title: [{ text: { content: "Page Title" } }] },
+  "Status": { status: { name: "Done" } },
+  "Date": { date: { start: "2026-01-01" } },
+  "Select": { select: { name: "Option" } },
+  "Multi-select": { multi_select: [{ name: "Tag1" }] },
+  "Number": { number: 42 },
+  "Checkbox": { checkbox: true },
+  "Email": { email: "user@example.com" },
+  "URL": { url: "https://example.com" },
+  "Relation": { relation: [{ id: "RELATED_PAGE_ID" }] }
+}
+```
+
+The `notion-ruby-client` gem does minimal conversion — you pass raw hashes.
+For reference, see `Ask::Notion::Context::API_REF_URL`.
+
+## Step 5: Authentication & Common Errors
+
+For detailed error guidance, use:
+
+```ruby
+Ask::Notion::Errors.for("Notion::Api::Errors::Forbidden")
+Ask::Notion::Errors.status_code_description(403)
+Ask::Notion::Errors::PAGINATION
+```
+
+Common scenarios:
+- **403 Forbidden**: Integration hasn't been shared with the page/database →
+  click "Share" in Notion and add your integration by name
+- **404 Not Found**: Wrong ID or not shared → verify the page ID and sharing
+- **400 Bad Request**: Property values have wrong types → check the schema first
+- **429 Too Many Requests**: Rate limited (3 req/s burst, 90 req/min)
+
+## Step 6: Pagination
+
+Notion uses cursor-based pagination. The `notion-ruby-client` gem accepts
+a block to auto-paginate:
+
+```ruby
+client.database_query(database_id: "DB_ID") do |page|
+  puts page.results.map { |r| r.id }
+end
+```
+
+Or manual pagination:
+```ruby
+response = client.database_query(database_id: "DB_ID", start_cursor: cursor, page_size: 100)
+cursor = response.next_cursor
+# Pass cursor as start_cursor in next request
+```
+
+## Step 7: Fallback Strategy
+
+If the client doesn't have a method for what you need:
+1. Check `Ask::Notion::Context::DOCS_URL` for the API endpoint
+2. Notion's API is a REST API — you can use Faraday for any endpoint
+3. Use `client.request(method:, path:, body:)` for custom requests

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-notion
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -95,6 +95,7 @@ files:
 - lib/ask/notion/context.rb
 - lib/ask/notion/error_guide.rb
 - lib/ask/notion/version.rb
+- lib/ask/skills/notion.use_notion/SKILL.md
 homepage: https://github.com/ask-rb/ask-notion
 licenses:
 - MIT