ask-notion 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f2b7ca05f8f6271299178580e3660f4b5a014977845d79a21a442ba0dad5d33
+  data.tar.gz: 1fd261c3a9184fba6e88e372771a35f71aa33954b0dda99cbada5addd1a80d20
+SHA512:
+  metadata.gz: 8d3c5718162b896aed53f44118403c2d470372ce2e305eb7e88315d52885a8c7a1f324c09dfe9d72ad783e8e20957feeab91dfb96d534ba728a5a4cc48534c9a
+  data.tar.gz: b2ae58df4217e6658378a3d3f6ba3d52b9002950b7c1df664a3bdf177022f02c45582e34462543616de77ae31c412cd46310b72e0c0f6ba60f2026d4250fd26d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+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,70 @@
+# ask-notion
+
+Notion service context for the ask-rb ecosystem.
+
+Provides:
+- `Ask::Notion.client` — authenticated Notion API client
+- `Ask::Notion::DESCRIPTION` — context metadata for the system prompt
+- `Ask::Notion::Errors` — structured error knowledge for AI agents
+
+## Installation
+
+```ruby
+gem "ask-notion"
+```
+
+## Usage
+
+```ruby
+require "ask-notion"
+
+# Returns an authenticated Notion::Client
+client = Ask::Notion.client
+
+# Query a database
+results = client.database_query(database_id: "your-database-id")
+
+# Get a page
+page = client.page_retrieve(page_id: "your-page-id")
+
+# Create a page in a database
+client.page_create(
+  parent: { database_id: "your-database-id" },
+  properties: {
+    "Name" => { title: [{ text: { content: "New Task" } }] },
+    "Status" => { status: { name: "In Progress" } }
+  }
+)
+
+# Search across Notion
+results = client.search(query: "project notes")
+```
+
+## Auth Setup
+
+This gem uses `Ask::Auth` to resolve the `:notion_token` credential.
+
+1. Go to https://www.notion.so/my-integrations
+2. Create a new integration and copy the Internal Integration Secret
+3. Set the token in your environment:
+
+```bash
+export NOTION_TOKEN="ntn_your_integration_token"
+```
+
+Or add it to `~/.ask/credentials.yml`:
+
+```yaml
+notion_token: ntn_your_integration_token
+```
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/notion/client.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "notion-ruby-client"
+require "ask/auth"
+
+module Ask
+  module Notion
+    # 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+.
+    #
+    # The client inherits default configuration from +Notion::Config+:
+    # - +token+: resolved via Ask::Auth
+    # - +logger+: default logger
+    #
+    # @example
+    #   client = Ask::Notion.client
+    #   client.database_query(database_id: "abc123")
+    #
+    # @return [::Notion::Client] an authenticated client
+    # @raise [Ask::Auth::MissingCredential] if no Notion token is configured
+    # @raise [Ask::Auth::InvalidCredential] if the token is rejected (401)
+    def self.client
+      token = Ask::Auth.resolve(:notion_token)
+
+      ClientProxy.new(::Notion::Client.new(token: token))
+    end
+
+    # Proxies method calls to a +::Notion::Client+, converting authentication
+    # errors into +Ask::Auth::InvalidCredential+.
+    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
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/ask/notion/context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ask
+  module Notion
+    # Human-readable description of the Notion service context.
+    DESCRIPTION = "Notion — pages, databases, blocks, comments, users, search"
+
+    # Base URL for Notion API documentation.
+    DOCS_URL = "https://developers.notion.com/"
+
+    # URL for the Notion API reference.
+    API_REF_URL = "https://developers.notion.com/reference"
+
+    # URL for the Notion OpenAPI specification.
+    OPENAPI_URL = "https://developers.notion.com/.well-known/openapi.json"
+
+    # Credential name used with Ask::Auth.resolve.
+    AUTH_NAME = :notion_token
+
+    # Instructions for obtaining a Notion Internal Integration Token.
+    AUTH_HOW = "https://www.notion.so/my-integrations — create an integration and copy the 'Internal Integration Secret' (starts with 'ntn_' or 'secret_')"
+
+    # Gem name for the Notion API client.
+    GEM_NAME = "notion-ruby-client"
+
+    # Required gem version constraint.
+    GEM_VERSION = "~> 1.2"
+
+    # URL for notion-ruby-client library documentation.
+    GEM_DOCS = "https://www.rubydoc.info/gems/notion-ruby-client"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      client = Ask::Notion.client
+      client.database_query(database_id: "DB_ID")
+      client.page_retrieve(page_id: "PAGE_ID")
+      client.page_create(parent: { database_id: "DB_ID" }, properties: { "Name": { title: [{ text: { content: "New Page" } }] } })
+      client.page_update(page_id: "PAGE_ID", properties: { "Status": { status: { name: "Done" } } })
+      client.block_children_list(block_id: "BLOCK_ID")
+      client.append_block_children(block_id: "BLOCK_ID", children: [{ paragraph: { rich_text: [{ text: { content: "Hello!" } }] } }])
+      client.search(query: "project")
+    RUBY
+  end
+end

data/lib/ask/notion/error_guide.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Ask
+  module Notion
+    # Structured error knowledge for AI agents working with the Notion API.
+    #
+    # Provides human-readable guidance for common HTTP status codes, rate
+    # limiting, pagination, and authentication errors encountered when
+    # using the Notion API via the notion-ruby-client gem.
+    module Errors
+      # Rate limit information.
+      #
+      # - Authenticated requests: 3 requests per second (burst), 90 requests per minute
+      #
+      # When rate-limited, the API returns 429 and raises
+      # +Notion::Api::Errors::TooManyRequests+. The agent should respect the
+      # Retry-After header and back off.
+      RATE_LIMIT = {
+        burst: "3 requests per second (per integration)",
+        sustained: "90 requests per minute (per integration)",
+        error_class: "Notion::Api::Errors::TooManyRequests",
+        action: "Respect the Retry-After header and wait before retrying. Use exponential backoff."
+      }.freeze
+
+      # Common HTTP status codes returned by the Notion API and how to handle them.
+      STATUS_CODES = {
+        200 => "OK — Request succeeded.",
+        201 => "Created — Resource was created successfully.",
+        204 => "No Content — Request succeeded, no response body.",
+        400 => "Bad Request — Request body is malformed. Check JSON structure and field types.",
+        401 => "Unauthorized — Integration token is missing, invalid, or revoked. Re-authenticate at https://www.notion.so/my-integrations.",
+        403 => "Forbidden — Integration lacks access to the requested resource. Share the page or database with the integration in Notion.",
+        404 => "Not Found — Resource does not exist or the integration does not have access to it.",
+        409 => "Conflict — Resource state conflict. The resource may have been updated by another request.",
+        412 => "Precondition Failed — Use the correct Notion-Version header (e.g., '2022-06-28').",
+        429 => "Too Many Requests — Rate limit exceeded. Respect Retry-After header.",
+        500 => "Internal Server Error — Notion server issue. Retry with backoff.",
+        502 => "Bad Gateway — Notion upstream issue. Retry with backoff.",
+        503 => "Service Unavailable — Notion is down for maintenance. Retry later."
+      }.freeze
+
+      # Pagination guidance for large result sets.
+      PAGINATION = {
+        cursor_based: "Notion uses cursor-based pagination. Supply a block to the client method to auto-paginate.",
+        page_size: "Maximum items per page is 100. The client uses this as the default.",
+        next_cursor: "Responses include a next_cursor key. Pass it as start_cursor in the next request.",
+        has_more: "Responses include a has_more boolean. When false, all results have been retrieved."
+      }.freeze
+
+      # Map of Notion exception classes to human-readable guidance.
+      EXCEPTIONS = {
+        "Notion::Api::Errors::Unauthorized" => {
+          message: "Your Notion integration token is invalid or has been revoked.",
+          action: "Generate a new token at https://www.notion.so/my-integrations. Tokens start with 'ntn_' or 'secret_'."
+        },
+        "Notion::Api::Errors::Forbidden" => {
+          message: "Your integration does not have access to this page or database.",
+          action: "In Notion, click 'Share' on the page/database and add your integration by name."
+        },
+        "Notion::Api::Errors::ObjectNotFound" => {
+          message: "The requested page, database, or block does not exist or is not shared with the integration.",
+          action: "Verify the ID is correct and that the resource is shared with your integration."
+        },
+        "Notion::Api::Errors::TooManyRequests" => {
+          message: "Notion API rate limit exceeded.",
+          action: "Check the Retry-After header, wait that many seconds, then retry. Limit: 3 req/s burst, 90 req/min sustained."
+        },
+        "Notion::Api::Errors::BadRequest" => {
+          message: "The request body is invalid or missing required fields.",
+          action: "Check the JSON structure, field names, and value types against the API reference at https://developers.notion.com/reference."
+        },
+        "Notion::Api::Errors::InvalidRequest" => {
+          message: "The request body failed validation against the Notion API schema.",
+          action: "Check required fields, property types, and data formats. Notion returns detailed error messages."
+        },
+        "Notion::Api::Errors::UnavailableError" => {
+          message: "Notion is temporarily unavailable or down for maintenance.",
+          action: "Retry with exponential backoff. If the issue persists, check https://status.notion.com."
+        },
+        "Notion::Api::Errors::TimeoutError" => {
+          message: "The request timed out.",
+          action: "Retry with exponential backoff. The Notion API may be experiencing high latency."
+        },
+        "Notion::Api::Errors::ParsingError" => {
+          message: "Failed to parse the Notion API response.",
+          action: "Retry the request. This is usually a transient issue."
+        },
+        "Notion::Api::Errors::ServerError" => {
+          message: "Notion encountered a server error.",
+          action: "Retry with exponential backoff. If the issue persists, check https://status.notion.com."
+        }
+      }.freeze
+
+      # Look up guidance for an exception class name.
+      #
+      # @param exception_class [String] The exception class name (e.g., "Notion::Api::Errors::ObjectNotFound")
+      # @return [Hash, nil] A hash with +:message+ and +:action+ keys, or nil if unknown
+      def self.for(exception_class)
+        EXCEPTIONS[exception_class]
+      end
+
+      # Describe an HTTP status code.
+      #
+      # @param code [Integer] HTTP status code
+      # @return [String, nil] Description of the status code
+      def self.status_code_description(code)
+        STATUS_CODES[code]
+      end
+    end
+  end
+end

data/lib/ask/notion/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Notion
+    VERSION = '0.1.0'
+  end
+end

data/lib/ask/notion.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+# empty — all components loaded via ask-notion.rb entry point

data/lib/ask-notion.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ask/notion/version"
+require_relative "ask/notion/context"
+require_relative "ask/notion/client"
+require_relative "ask/notion/error_guide"

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: ask-notion
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: notion-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides authenticated Notion client, context metadata, and error guide
+  for AI agents.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-notion.rb
+- lib/ask/notion.rb
+- lib/ask/notion/client.rb
+- lib/ask/notion/context.rb
+- lib/ask/notion/error_guide.rb
+- lib/ask/notion/version.rb
+homepage: https://github.com/ask-rb/ask-notion
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Notion service context for the ask-rb ecosystem
+test_files: []