wikiwiki 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c94061d746d2242a2a78e735c43fa5fba37888231ba3a92e959aeafa5afaec3a
+  data.tar.gz: c9c3f4c74090aa044e10e48b72b03ad2a7b1b58713fec6e0447a871439153c05
+SHA512:
+  metadata.gz: 9bae7372d114df3f32f4f60d3ae1b4664ff3581c30ba0215e5d705de733063b2d12faaa92c557439f29b1e9b9707e9c3993400e738b672125365b7be24d401c1
+  data.tar.gz: f6e397e07040ba97328609f437a30a29be059c2df7c7051d78def34c204f6d5bf6005e618014893ffddcb36e20cc41db414eb1187435776a60217b2177c960ee

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+## [Unreleased]
+
+## [0.5.0] - 2025-10-31
+
+### Added
+
+- Initial release of Wikiwiki REST API client library
+- Support for password and API key authentication
+- Page operations: list, read, and update
+- Attachment operations: list, download, upload, and delete
+- Automatic rate limiting with configurable strategies (raise, wait, or no limit)
+- Full RBS type signatures for type safety
+- `Wiki#url` method to get the wiki URL as a frozen `URI::HTTPS` instance
+- Logging support for API requests and responses with configurable logger (default: Logger.new($stdout))
+  - Request/response URLs and status codes logged at INFO level
+  - HTTP headers logged at DEBUG level (with Authorization masked as "Bearer ***")
+  - Each log entry is prefixed with `[wiki-id]` for easy filtering
+  - Logger accessible via `Wiki#logger` and `API#logger` reader methods

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 OZAWA Sakuro
+
+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.ja.md

@@ -0,0 +1,96 @@
+# Wikiwiki
+
+{file:README.md English version}
+
+[Wikiwiki](https://wikiwiki.jp/) REST API用のRubyクライアントライブラリです。
+
+## 概要
+
+このgemは、Wikiwikiのwikiをプログラムから操作するためのシンプルなインターフェースを提供します。ページ操作（一覧取得、読み取り、書き込み）と添付ファイル管理（一覧取得、アップロード、ダウンロード、削除）をサポートしています。
+
+## インストール
+
+アプリケーションのGemfileに以下の行を追加してください：
+
+```ruby
+gem "wikiwiki"
+```
+
+その後、以下を実行してください：
+
+```bash
+bundle install
+```
+
+または、直接インストールすることもできます：
+
+```bash
+gem install wikiwiki
+```
+
+## 認証
+
+APIを使用する前に、wikiの管理画面でREST APIアクセスを有効にしてください。
+
+### パスワード認証
+
+```ruby
+auth = Wikiwiki::Auth.password(password: "your_admin_password")
+```
+
+### APIキー認証
+
+```ruby
+auth = Wikiwiki::Auth.api_key(api_key_id: "your_api_key_id", secret: "your_secret")
+```
+
+## 使い方
+
+### 基本的な使用例
+
+```ruby
+require "wikiwiki"
+
+# 認証情報を使って初期化
+auth = Wikiwiki::Auth.password(password: "admin_password")
+wiki = Wikiwiki::Wiki.new(wiki_id: "your-wiki-id", auth:)
+
+# すべてのページ名の一覧を取得
+page_names = wiki.page_names
+# => ["FrontPage", "SideBar", ...]
+
+# ページを取得
+page = wiki.page(page_name: "FrontPage")
+puts page.source
+puts page.timestamp
+
+# ページを更新
+wiki.update_page(page_name: "TestPage", source: <<~SOURCE)
+  TITLE:Test
+  # Hello World
+SOURCE
+
+# 添付ファイル名の一覧を取得
+attachment_names = wiki.attachment_names(page_name: "FrontPage")
+
+# 添付ファイルをダウンロード
+attachment = wiki.attachment(page_name: "FrontPage", attachment_name: "logo.png")
+File.binwrite("logo.png", attachment.content)
+# 注意: attachment.nameをファイル名として使用する場合は、ディレクトリトラバーサル攻撃を防ぐために安全性を検証してください
+
+# 添付ファイルをアップロード
+content = File.binread("image.png")
+wiki.add_attachment(page_name: "FrontPage", attachment_name: "image.png", content:)
+
+# 添付ファイルを削除
+wiki.delete_attachment(page_name: "FrontPage", attachment_name: "image.png")
+```
+
+## リファレンス
+
+- [ページ操作API](https://z.wikiwiki.jp/wikiwiki-rest-api/topic/1)
+- [ファイル操作API](https://z.wikiwiki.jp/wikiwiki-rest-api/topic/3)
+
+## ライセンス
+
+このgemは[MITライセンス](https://opensource.org/licenses/MIT)の条件の下でオープンソースとして利用可能です。

data/README.md

@@ -0,0 +1,96 @@
+# Wikiwiki
+
+{file:README.ja.md 日本語版}
+
+A Ruby client library for the [Wikiwiki](https://wikiwiki.jp/) REST API.
+
+## Overview
+
+This gem provides a simple interface to interact with Wikiwiki wikis programmatically. It supports page operations (list, read, write) and attachment management (list, upload, download, delete).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "wikiwiki"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install wikiwiki
+```
+
+## Authentication
+
+Before using the API, enable REST API access in your wiki's admin panel.
+
+### Password Authentication
+
+```ruby
+auth = Wikiwiki::Auth.password(password: "your_admin_password")
+```
+
+### API Key Authentication
+
+```ruby
+auth = Wikiwiki::Auth.api_key(api_key_id: "your_api_key_id", secret: "your_secret")
+```
+
+## Usage
+
+### Basic Example
+
+```ruby
+require "wikiwiki"
+
+# Initialize with authentication
+auth = Wikiwiki::Auth.password(password: "admin_password")
+wiki = Wikiwiki::Wiki.new(wiki_id: "your-wiki-id", auth:)
+
+# List all page names
+page_names = wiki.page_names
+# => ["FrontPage", "SideBar", ...]
+
+# Read a page
+page = wiki.page(page_name: "FrontPage")
+puts page.source
+puts page.timestamp
+
+# Update a page
+wiki.update_page(page_name: "TestPage", source: <<~SOURCE)
+  TITLE:Test
+  # Hello World
+SOURCE
+
+# List attachment names
+attachment_names = wiki.attachment_names(page_name: "FrontPage")
+
+# Download an attachment
+attachment = wiki.attachment(page_name: "FrontPage", attachment_name: "logo.png")
+File.binwrite("logo.png", attachment.content)
+# Note: If using attachment.name as filename, validate it first to prevent directory traversal attacks
+
+# Upload an attachment
+content = File.binread("image.png")
+wiki.add_attachment(page_name: "FrontPage", attachment_name: "image.png", content:)
+
+# Delete an attachment
+wiki.delete_attachment(page_name: "FrontPage", attachment_name: "image.png")
+```
+
+## Reference
+
+- [Page Operations API](https://z.wikiwiki.jp/wikiwiki-rest-api/topic/1) (Japanese)
+- [File Operations API](https://z.wikiwiki.jp/wikiwiki-rest-api/topic/3) (Japanese)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/wikiwiki/api.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Wikiwiki
+  # Handles HTTP communication with the Wikiwiki REST API
+  #
+  # @example
+  #   auth = Wikiwiki::Auth.password(password: "secret")
+  #   api = Wikiwiki::API.new(wiki_id: "my-wiki", auth:)
+  #   pages = api.get_pages
+  class API
+    attr_reader :logger
+
+    BASE_URL = URI.parse("https://api.wikiwiki.jp").freeze
+    private_constant :BASE_URL
+
+    # Initialize a new API client and authenticate
+    #
+    # @param wiki_id [String] the wiki identifier
+    # @param auth [Auth::Password, Auth::ApiKey] authentication credentials
+    # @param logger [Logger] logger instance for request/response logging
+    # @param rate_limiter [RateLimiter] rate limiter instance (default: RateLimiter.default)
+    # @raise [Error] if authentication fails
+    def initialize(wiki_id:, auth:, logger:, rate_limiter: RateLimiter.default)
+      @wiki_id = wiki_id
+      @rate_limiter = rate_limiter
+      @logger = logger
+      @token = authenticate(auth)
+    end
+
+    # Get list of all pages
+    #
+    # @return [Hash] response with "pages" key containing array of page info
+    # @raise [Error] if request fails
+    def get_pages
+      uri = BASE_URL + "/#{wiki_id}/pages"
+      response = request(:get, uri)
+
+      parse_json_response(response)
+    end
+
+    # Get a specific page
+    #
+    # @param encoded_page_name [String] the URL-encoded page name
+    # @return [Hash] response with "page", "source", and "timestamp" keys
+    # @raise [Error] if request fails
+    def get_page(encoded_page_name:)
+      uri = BASE_URL + "/#{wiki_id}/page/#{encoded_page_name}"
+      response = request(:get, uri)
+
+      parse_json_response(response)
+    end
+
+    # Update a page
+    #
+    # @param encoded_page_name [String] the URL-encoded page name
+    # @param source [String] the page source content
+    # @return [void]
+    # @raise [Error] if request fails
+    def put_page(encoded_page_name:, source:)
+      uri = BASE_URL + "/#{wiki_id}/page/#{encoded_page_name}"
+      response = request(:put, uri, body: {"source" => source})
+
+      parse_json_response(response)
+    end
+
+    # Get list of attachments on a page
+    #
+    # @param encoded_page_name [String] the URL-encoded page name
+    # @return [Hash] response with "attachments" key containing hash of file info
+    # @raise [Error] if request fails
+    def get_attachments(encoded_page_name:)
+      uri = BASE_URL + "/#{wiki_id}/page/#{encoded_page_name}/attachments"
+      response = request(:get, uri)
+
+      parse_json_response(response)
+    end
+
+    # Get a specific attachment
+    #
+    # @param encoded_page_name [String] the URL-encoded page name
+    # @param encoded_attachment_name [String] the URL-encoded attachment file name
+    # @param rev [String, nil] optional MD5 hash for specific revision
+    # @return [Hash] file info with Base64-encoded "src" data
+    # @raise [Error] if request fails
+    def get_attachment(encoded_page_name:, encoded_attachment_name:, rev: nil)
+      uri = BASE_URL + "/#{wiki_id}/page/#{encoded_page_name}/attachment/#{encoded_attachment_name}"
+      uri.query = "rev=#{rev}" if rev
+      response = request(:get, uri)
+
+      parse_json_response(response)
+    end
+
+    # Upload an attachment to a page
+    #
+    # @param encoded_page_name [String] the URL-encoded page name
+    # @param attachment_name [String] the attachment file name (not URL-encoded; sent in JSON body)
+    # @param encoded_content [String] Base64-encoded file data
+    # @return [void]
+    # @raise [Error] if request fails
+    def put_attachment(encoded_page_name:, attachment_name:, encoded_content:)
+      uri = BASE_URL + "/#{wiki_id}/page/#{encoded_page_name}/attachment"
+      response = request(:put, uri, body: {"filename" => attachment_name, "data" => encoded_content})
+
+      parse_json_response(response)
+    end
+
+    # Delete an attachment from a page
+    #
+    # @param encoded_page_name [String] the URL-encoded page name
+    # @param encoded_attachment_name [String] the URL-encoded attachment file name
+    # @return [void]
+    # @raise [Error] if request fails
+    def delete_attachment(encoded_page_name:, encoded_attachment_name:)
+      uri = BASE_URL + "/#{wiki_id}/page/#{encoded_page_name}/attachment/#{encoded_attachment_name}"
+      response = request(:delete, uri)
+
+      parse_json_response(response)
+    end
+
+    # Authenticate with the Wikiwiki API
+    #
+    # @param auth [Auth::Password, Auth::ApiKey] authentication credentials
+    # @return [String] JWT token
+    # @raise [Error] if authentication fails
+    private def authenticate(auth)
+      uri = BASE_URL + "/#{wiki_id}/auth"
+      response = request(:post, uri, body: auth.to_h, authenticate: false)
+      data = parse_json_response(response)
+      data["token"]
+    end
+
+    # Parse JSON response
+    #
+    # @param response [Net::HTTPResponse] HTTP response
+    # @return [Hash] parsed response body
+    # @raise [AuthenticationError] if authentication fails (401)
+    # @raise [ResourceNotFoundError] if resource not found (404)
+    # @raise [ServerError] if server error (5xx)
+    # @raise [APIError] if other API request fails
+    private def parse_json_response(response)
+      unless response.is_a?(Net::HTTPSuccess)
+        message = "API request failed: #{response.code} #{response.message}"
+        case Integer(response.code, 10)
+        when 401
+          raise AuthenticationError, message
+        when 404
+          raise ResourceNotFoundError, message
+        when 500..599
+          raise ServerError, message
+        else
+          raise APIError, message
+        end
+      end
+
+      JSON.parse(response.body)
+    end
+
+    # Send HTTP request
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param uri [URI::HTTPS] request URI
+    # @param body [Hash, nil] request body (only for methods that permit body)
+    # @param authenticate [Boolean] whether to include authentication header
+    # @return [Net::HTTPResponse] HTTP response
+    private def request(method, uri, body: nil, authenticate: true)
+      @rate_limiter.acquire!
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request_class = Net::HTTP.const_get(method.capitalize)
+      request = request_class.new(uri.request_uri)
+
+      if request.request_body_permitted? && body
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+
+      request["Authorization"] = "Bearer #{token}" if authenticate
+
+      log_request(method, uri, request)
+      response = http.request(request)
+      log_response(response)
+
+      response
+    end
+
+    # Log HTTP request details
+    #
+    # @param method [Symbol] HTTP method
+    # @param uri [URI::HTTPS] request URI
+    # @param request [Net::HTTPRequest] HTTP request object
+    private def log_request(method, uri, request)
+      logger.info("[#{wiki_id}] API Request: #{method.upcase} #{uri}")
+
+      request.each_header do |key, value|
+        if key.casecmp("authorization").zero?
+          logger.debug("[#{wiki_id}]   #{key}: Bearer ***")
+        else
+          logger.debug("[#{wiki_id}]   #{key}: #{value}")
+        end
+      end
+    end
+
+    # Log HTTP response details
+    #
+    # @param response [Net::HTTPResponse] HTTP response object
+    private def log_response(response)
+      logger.info("[#{wiki_id}] API Response: #{response.code} #{response.message}")
+
+      response.each_header do |key, value|
+        logger.debug("[#{wiki_id}]   #{key}: #{value}")
+      end
+    end
+
+    private attr_reader :wiki_id, :token
+  end
+end

data/lib/wikiwiki/attachment.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  # Represents a file attachment on a wiki page
+  #
+  # @example
+  #   auth = Wikiwiki::Auth.password(password: "admin_password")
+  #   wiki = Wikiwiki::Wiki.new(wiki_id: "my-wiki", auth:)
+  #   page = wiki.page(page_name: "FrontPage")
+  #   attachment_names = wiki.attachment_names(page_name: "FrontPage")
+  #   attachment = wiki.attachment(page_name: "FrontPage", attachment_name: attachment_names.first)
+  #   attachment.name # => "logo.png"
+  #   attachment.size # => 12345
+  #   attachment.time # => 2022-01-01 00:00:00 +0900
+  #   attachment.content # => binary data (decoded)
+  Attachment = Data.define(:page_name, :name, :size, :time, :type, :content)
+
+  class Attachment
+    # Reopen the class to add YARD documentation for attributes
+
+    # @!attribute [r] page_name
+    #   @return [String] the page name this attachment belongs to
+
+    # @!attribute [r] name
+    #   @return [String] the attachment file name
+
+    # @!attribute [r] size
+    #   @return [Integer] the file size in bytes
+
+    # @!attribute [r] time
+    #   @return [Time] the upload time
+
+    # @!attribute [r] type
+    #   @return [String] the MIME type
+
+    # @!attribute [r] content
+    #   @return [String] the binary file content (decoded from Base64)
+  end
+end

data/lib/wikiwiki/auth/api_key.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  module Auth
+    # API key-based authentication credentials
+    #
+    # @example
+    #   auth = Wikiwiki::Auth::ApiKey.new(api_key_id: "key_id", secret: "secret")
+    #   auth.to_h # => {api_key_id: "key_id", secret: "secret"}
+    ApiKey = Data.define(:api_key_id, :secret)
+
+    class ApiKey
+      # Reopen the class to add YARD documentation for attributes
+
+      # @!attribute [r] api_key_id
+      #   @return [String] the API key ID
+
+      # @!attribute [r] secret
+      #   @return [String] the secret key
+    end
+  end
+end

data/lib/wikiwiki/auth/password.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  module Auth
+    # Password-based authentication credentials
+    #
+    # @example
+    #   auth = Wikiwiki::Auth::Password.new(password: "admin_password")
+    #   auth.to_h # => {password: "admin_password"}
+    Password = Data.define(:password)
+
+    class Password
+      # Reopen the class to add YARD documentation for attributes
+
+      # @!attribute [r] password
+      #   @return [String] the admin password
+    end
+  end
+end

data/lib/wikiwiki/auth.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  # Authentication credentials module
+  #
+  # Provides factory methods for creating authentication objects
+  module Auth
+    # Create password-based authentication credentials
+    #
+    # @param password [String] admin password
+    # @return [Password] password authentication object
+    def self.password(password:) = Password.new(password:)
+
+    # Create API key-based authentication credentials
+    #
+    # @param api_key_id [String] API key ID
+    # @param secret [String] secret key
+    # @return [ApiKey] API key authentication object
+    def self.api_key(api_key_id:, secret:) = ApiKey.new(api_key_id:, secret:)
+  end
+end

data/lib/wikiwiki/page.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  # Represents a wiki page
+  #
+  # @example
+  #   auth = Wikiwiki::Auth.password(password: "admin_password")
+  #   wiki = Wikiwiki::Wiki.new(wiki_id: "my-wiki", auth:)
+  #   page = wiki.page(page_name: "FrontPage")
+  #   page.name # => "FrontPage"
+  #   page.source # => "TITLE:FrontPage\n..."
+  #   page.timestamp # => 2022-01-01 00:00:00 +0900
+  Page = Data.define(:name, :source, :timestamp)
+
+  class Page
+    # Reopen the class to add YARD documentation for attributes
+
+    # @!attribute [r] name
+    #   @return [String] the page name
+
+    # @!attribute [r] source
+    #   @return [String] the page source content
+
+    # @!attribute [r] timestamp
+    #   @return [Time] the last update timestamp
+  end
+end