coolhand 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48857d802183f91a163c82c3e1dd89ce34ac7a8f1f3d1079c5ae6d5d594ad300
-  data.tar.gz: a852465d5b9dced73580eff8c81f45093a97c48c79a66579cff27c2dbedc7cbe
+  metadata.gz: 301fa9e603334f3c6b5349755239cdf06418b9b78f1fae3de44abc352b8f1828
+  data.tar.gz: 0b687769a058ff206f50deaf46ad1e28909e7f4e4229d217ad5b36b7350ff9ce
 SHA512:
-  metadata.gz: 0d4e6bc5e9ef29365afaba5b9c4a4edbadb552f77268adfe27ac6276f23cd44e4c75fe6df85b1ddef8bdf25d99d88204a46a127dcce7c3a2183edc09e5019508
-  data.tar.gz: ee192c55d280b47abc3f6a9af7f2ddd48d4966493955cee5614557feeea2d87d71a28c16f488fee4dc9fddd916b88fc9ee98621e058e3ad0de80431fc6bd871c
+  metadata.gz: 9a4653638e2362853b90baf55bc1df97f73ee1144357524c61be21798b58fcffe383d9bbde1b9cb33ac7c9d07064377eff681667be8ed2a341103cdb06ab42ff
+  data.tar.gz: 464a1d38d383ebf98f3f42b9f60fccfe65d13fcc3a1ea45d5df0c7fc1f26aad721a9b2650f1c41277a09dbf5a92a24f32f2223f961c9940de592fecf54d1057d

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-21
+
+### Added
+- **Read the Coolhand help center** ([#164](https://github.com/Coolhand-Labs/coolhand-ruby/pull/164)) — `Coolhand.public_content_service` wraps the read-only help center endpoints: `search_help_articles(query:, category:, page:, per_page:)` returns a `Coolhand::HelpArticleSearchResult` (`articles`, `pagination`), `get_help_article(slug)` returns one article with its markdown `body` and `toc`, and `list_help_categories` lists the sections. Unlike every other read service it needs **no API key**: with none configured no `X-API-Key` header is sent (anonymous callers are limited to 30 requests per minute per IP), and a configured `config.api_key` is sent and lifts the limit. Like the other read methods, these raise `Coolhand::Error` / `Coolhand::HttpError` rather than logging and returning `nil`. See [Reading the Help Center](docs/help-center.md).
+
+### Security
+- `LoggerService#forward_webhook` now redacts credentials (userinfo and sensitive query parameters such as `token=`) in a caller-supplied `url:` before logging it, the same way intercepted request URLs are. **Migration note:** if you pass a `url:` containing such values, they now appear as `[REDACTED]` in Coolhand.
+
 ## [0.9.0] - 2026-10-18
 
 ### Added

data/README.md

@@ -118,6 +118,24 @@ Coolhand.log_service.search_logs(order: 'cost_desc', min_cost: 1.0, per: 10, **w
 
 See [Reading Workloads →](docs/workload-search.md) and [Reading Logs →](docs/log-search.md).
 
+## Reading the Help Center
+
+`Coolhand.public_content_service` reads the Coolhand help center (the same pages as coolhandlabs.com/help and /updates) with **no API key required**:
+
+```ruby
+require 'coolhand'
+
+help_center = Coolhand.public_content_service
+
+result = help_center.search_help_articles(query: 'match rate', per_page: 5)
+article = help_center.get_help_article(result.articles.first[:slug]) # full markdown :body
+categories = help_center.list_help_categories
+```
+
+Anonymous callers are limited to 30 requests per minute per IP. If `config.api_key` is set it is sent and lifts the limit; a key the server rejects raises a 401 `Coolhand::HttpError`. These are read methods, so they **raise** where the write methods log and return `nil`.
+
+See [Reading the Help Center →](docs/help-center.md) for parameters, the category filter and errors.
+
 ## Linking Feedback to an Optimization
 
 Attach feedback to an optimization as evidence, one at a time or in bulk. These require your **private** API key and **raise** `Coolhand::Error` on failure (`Coolhand::HttpError` for non-2xx responses).
@@ -488,7 +506,7 @@ The monitor handles errors gracefully:
 - Failed API logging attempts are logged to console but don't interrupt your application
 - Invalid API keys will be reported but won't crash your app
 - Network issues are handled with appropriate error messages
-- The read methods (`search_templates`, `get_template`, `search_workloads`, `search_logs`, `get_log`), the feedback-link methods and the `upsert` methods are the exception — they raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses); see [Reading Templates →](docs/template-search.md), [Reading Workloads →](docs/workload-search.md), [Reading Logs →](docs/log-search.md), [Linking Feedback →](docs/feedback-links.md) and [Declared Workloads →](docs/declared_workloads.md)
+- The read methods (`search_templates`, `get_template`, `search_workloads`, `search_logs`, `get_log`, `search_help_articles`, `get_help_article`, `list_help_categories`), the feedback-link methods and the `upsert` methods are the exception — they raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses); see [Reading Templates →](docs/template-search.md), [Reading Workloads →](docs/workload-search.md), [Reading Logs →](docs/log-search.md), [Linking Feedback →](docs/feedback-links.md) and [Declared Workloads →](docs/declared_workloads.md)
 
 ## Documentation
 
@@ -497,6 +515,7 @@ The monitor handles errors gracefully:
 - **[Reading Templates](docs/template-search.md)** — Search LLM request templates and fetch a single one, prompt patterns included, using the private API key
 - **[Reading Workloads](docs/workload-search.md)** — List workloads with optional cost and performance metrics over a rolling or explicit time window
 - **[Reading Logs](docs/log-search.md)** — Search logs with per-log cost, filter and sort by cost, and fetch one log with its cost breakdown
+- **[Reading the Help Center](docs/help-center.md)** — Search and read Coolhand's help center articles and list its sections, with no API key required
 - **[Linking Feedback](docs/feedback-links.md)** — Link feedback to an optimization as evidence, singly or in bulk, using the private API key
 - **[Declared Workloads](docs/declared_workloads.md)** — Declare the workload and template of captured LLM calls with `Coolhand.with_context`, and create or rename them with `upsert`
 - **[Anthropic Integration](docs/anthropic.md)** — Official and community Anthropic Ruby gems, streaming, dual gem handling, and troubleshooting

data/docs/help-center.md

@@ -0,0 +1,120 @@
+# Reading the Help Center
+
+`Coolhand::PublicContentService` reads Coolhand's help center: the articles served at
+`coolhandlabs.com/help/:slug` and the posts at `/updates/:slug`. "Help center" is the user-facing name;
+on the wire the resource is `public_content` (`GET /api/v2/public_content`, `/:slug` and `/categories`).
+It is read-only. Creating, updating and archiving articles is Coolhand-internal and not wrapped.
+
+**Auth:** none required. Unlike every other service, no API key is needed:
+
+```ruby
+require "coolhand"
+
+help_center = Coolhand.public_content_service # works with Coolhand.configure never called
+```
+
+- No key configured: no `X-API-Key` header is sent, and the calls work. Anonymous callers are limited to
+  **30 requests per minute per IP**; beyond that the server answers `429`.
+- A configured `config.api_key` is sent as `X-API-Key` and callers with a valid key are not rate limited.
+  This gem reads the key from configuration only, not from the environment.
+- A key the server does not recognise is a `401` (`{"error":"Invalid API key."}`) even though the endpoint is
+  public. It is raised, not retried anonymously.
+
+## `search_help_articles`
+
+```ruby
+result = help_center.search_help_articles(query: "match rate", category: "feedback-and-prompts", per_page: 10)
+
+result.articles.each { |a| puts "#{a[:title]}: #{a[:search_headline]}" }
+result.pagination.total_count
+```
+
+### Keywords
+
+All optional.
+
+| keyword | type | notes |
+|---|---|---|
+| `query` | String | Relevance search (Postgres full text, the same as the website's). Supports quoted phrases, `-exclusions` and `or`. Omit for a full listing. A blank string counts as omitted. |
+| `category` | String | Restrict to one section by slug (see `list_help_categories`). A blank string counts as omitted. |
+| `page` | Integer | 1-based. |
+| `per_page` | Integer | Default 25, max 100, both enforced server-side. |
+
+The endpoint has no `category` parameter. `category` is sent in its structured form instead, which also
+moves the relevance search to a different key; the plain `q=...` string and the `q[...]` form cannot be
+mixed:
+
+| `query` | `category` | Sent |
+|---|---|---|
+| set | unset | `q=<query>` |
+| unset | set | `q[help_category_slug_eq]=<category>` |
+| set | set | `q[help_category_slug_eq]=<category>&q[full_text]=<query>` |
+
+### Return value
+
+A `Coolhand::HelpArticleSearchResult` with `articles` (an Array of Symbol-keyed Hashes) and `pagination`.
+Each article is a summary; the markdown `:body` is omitted from lists:
+
+```ruby
+{
+  slug: "what-is-feedback-match-rate",
+  title: "What is feedback match rate?",
+  answer: "Match rate is the share of ...",       # String or nil
+  article_kind: "concept",   # reference | concept | how_to | troubleshooting | faq_answer | release_note
+  tags: ["feedback", "matching"],
+  category: "feedback-and-prompts",               # section slug
+  url: "https://coolhandlabs.com/help/what-is-feedback-match-rate",
+  markdown_url: "https://coolhandlabs.com/help/what-is-feedback-match-rate.md",
+  reading_time_minutes: 10,                       # Integer or nil
+  search_headline: "<mark>Match</mark> rate ...", # nil on a plain listing
+  published_at: "2026-08-30T13:57:52Z",           # String or nil
+  updated_content_at: "2026-08-30T13:57:52Z"      # String or nil
+}
+```
+
+`:search_headline` is the matching passage with `<mark>` tags around the matched terms, so you can see
+why something matched without fetching the body.
+
+`pagination` is a `Coolhand::Pagination`, the same as the other read methods, built from the `X-Page`,
+`X-Per-Page`, `X-Total-Count` and `X-Total-Pages` response headers (`current_page`, `per_page`,
+`total_count`, `total_pages`, `has_next_page`, `has_prev_page`).
+
+## `get_help_article(slug)`
+
+```ruby
+article = help_center.get_help_article("what-is-feedback-match-rate")
+article[:body] # full markdown
+article[:toc]  # [{ id:, text:, level:, children: }]
+```
+
+Returns a Hash: the summary fields minus `:search_headline`, plus `:body` (full markdown), `:noindex`
+(Boolean) and `:toc` (the heading structure, h3s nested under their h2). The slug is escaped as a single
+path segment. Raises `Coolhand::Error` before any request if `slug` is blank or a bare `.`/`..`. An unknown
+or unpublished slug raises `Coolhand::HttpError` with `status` 404.
+
+## `list_help_categories`
+
+```ruby
+help_center.list_help_categories
+# [{ slug: "providers", name: "Provider guides", description: "...", url_prefix: "/help", allowed_tags: nil }, ...]
+```
+
+Returns an Array of Hashes: `:slug` (the `category` filter above), `:name`, `:description`, `:url_prefix`
+(`/help` or `/updates`) and `:allowed_tags` (the only tags the section accepts; `nil` means any tag).
+
+## Errors
+
+These are read methods, so they raise where the logging writes log and return `nil`. A network failure or
+a non-JSON body raises `Coolhand::Error`. A non-2xx response raises `Coolhand::HttpError`, whose `status`
+holds the HTTP status code and `body` the (truncated) response body: `401` for an invalid key, `404` for an
+unknown slug, `429` when the anonymous rate limit is exceeded.
+
+## Verifying against a live server
+
+`spec/live/coolhand_public_content_live_spec.rb` runs against a real server with no key:
+
+```bash
+COOLHAND_SPEC_LIVE_BASE_URL=http://127.0.0.1:3000/api bundle exec rspec spec/live/coolhand_public_content_live_spec.rb
+```
+
+It makes about nine anonymous requests, so running it repeatedly within a minute can hit the `429`.

data/lib/coolhand/logger_service.rb

@@ -24,7 +24,7 @@ module Coolhand
         id: options[:id] || SecureRandom.uuid,
         timestamp: options[:timestamp] || Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ"),
         method: options[:method] || "POST",
-        url: options[:url] || build_webhook_url(source, event_type),
+        url: BaseInterceptor.sanitize_url(options[:url] || build_webhook_url(source, event_type)),
         headers: sanitize_headers(headers),
         request_body: clean_webhook_body(webhook_body, source),
         response_body: options[:response_body],

data/lib/coolhand/public_content_service.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+require_relative "pagination"
+require_relative "read_query"
+
+module Coolhand
+  # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
+  HelpArticleSearchResult = Struct.new(:articles, :pagination, keyword_init: true)
+
+  # Read-only access to the Coolhand help center: the `public_content` endpoints (`GET /api/v2/public_content`,
+  # `/:slug` and `/categories`), the same pages served at `/help/:slug` and `/updates/:slug`. Create, update and
+  # archive are Coolhand-internal and not wrapped.
+  #
+  # Unlike every other service this one needs no API key. A configured `api_key` is sent as `X-API-Key` and lifts
+  # the anonymous limit of 30 requests per minute per IP (429 beyond); with none, no key header is sent. A key the
+  # server rejects raises a 401 {Coolhand::HttpError}; it is not retried anonymously. See docs/help-center.md.
+  class PublicContentService < ApiService
+    include ReadQuery
+
+    ERROR_NOUN = "Help center"
+    BLANK_SLUG_MESSAGE = "get_help_article: slug must be a non-empty string"
+
+    def initialize
+      super("v2/public_content")
+    end
+
+    # Relevance search with `query`, a full listing without. `category` filters to one section slug; the
+    # endpoint has no such parameter, so it is sent as `q[help_category_slug_eq]` and `query` moves to
+    # `q[full_text]` (the plain `q` string and the `q[...]` form cannot be mixed). A blank `query` or
+    # `category` counts as omitted. Returns a {HelpArticleSearchResult}; raises {Coolhand::HttpError} on a
+    # non-2xx response.
+    def search_help_articles(query: nil, category: nil, page: nil, per_page: nil)
+      params = { **search_params(query, category), page: page, per_page: per_page }.compact
+
+      fetch_list(params, HelpArticleSearchResult, :articles, page: page, per: per_page)
+    end
+
+    # One published article with its markdown `body`, `noindex` and `toc`. Raises {Coolhand::Error} before any
+    # request for a blank slug, and {Coolhand::HttpError} (404) for an unknown or unpublished one.
+    def get_help_article(slug)
+      get_json(resource_url(slug, BLANK_SLUG_MESSAGE), ERROR_NOUN)
+    end
+
+    # Every section an article can be filed under, with its `url_prefix` and `allowed_tags`.
+    def list_help_categories
+      get_json(URI.parse("#{api_endpoint}/categories"), ERROR_NOUN)
+    end
+
+    protected
+
+    def api_key_required?
+      false
+    end
+
+    private
+
+    def search_params(query, category)
+      query = nil if omitted?(query)
+      return { q: query } if omitted?(category)
+
+      { "q[help_category_slug_eq]": category, "q[full_text]": query }
+    end
+
+    def omitted?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/coolhand/read_requests.rb

@@ -29,7 +29,9 @@ module Coolhand
 
     # Also returns the response, for endpoints that carry pagination in headers rather than the body.
     def get_json_with_headers(url, noun)
-      raise Error, "#{noun} request failed: an API key is required" unless Coolhand.required_field?(api_key)
+      if api_key_required? && !Coolhand.required_field?(api_key)
+        raise Error, "#{noun} request failed: an API key is required"
+      end
 
       response = perform_get(url, noun)
 
@@ -38,6 +40,11 @@ module Coolhand
       [parse_json_body(response.body, noun), response]
     end
 
+    # Overridden by services over public endpoints, which work anonymously and send the key only if set.
+    def api_key_required?
+      true
+    end
+
     private
 
     def perform_get(url, noun)
@@ -45,7 +52,9 @@ module Coolhand
       http = build_http(uri)
 
       request = Net::HTTP::Get.new(uri.request_uri)
-      apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
+      headers = { "Accept" => "application/json" }
+      headers["X-API-Key"] = api_key if Coolhand.required_field?(api_key)
+      apply_headers(request, headers)
 
       # Net::HTTP does not follow redirects, so a 3xx raises rather than replaying the API key at
       # an unapproved host. without_capture is the same recursion guard send_request uses.

data/lib/coolhand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coolhand
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/coolhand.rb

@@ -22,6 +22,7 @@ require_relative "coolhand/feedback_service"
 require_relative "coolhand/template_service"
 require_relative "coolhand/optimization_feedback_link_service"
 require_relative "coolhand/workload_service"
+require_relative "coolhand/public_content_service"
 require_relative "coolhand/log_service"
 require_relative "coolhand/webhook_interceptor"
 # Only when Rails is already loaded; the gem has no Rails dependency.
@@ -147,6 +148,12 @@ module Coolhand
       LogService.new
     end
 
+    # Creates a new PublicContentService, for reading the Coolhand help center. Needs no API key; a
+    # configured one is sent and lifts the anonymous rate limit.
+    def public_content_service
+      PublicContentService.new
+    end
+
     # Creates a new OptimizationFeedbackLinkService instance, for linking feedback to an
     # optimization as evidence. Needs the private API key.
     def optimization_feedback_link_service

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -51,6 +51,7 @@ files:
 - docs/elevenlabs.md
 - docs/feedback-links.md
 - docs/feedback.md
+- docs/help-center.md
 - docs/log-search.md
 - docs/openai.md
 - docs/template-search.md
@@ -77,6 +78,7 @@ files:
 - lib/coolhand/open_ai/webhook_validator.rb
 - lib/coolhand/optimization_feedback_link_service.rb
 - lib/coolhand/pagination.rb
+- lib/coolhand/public_content_service.rb
 - lib/coolhand/rails_auto_declare.rb
 - lib/coolhand/railtie.rb
 - lib/coolhand/read_query.rb