sudhanva 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bbe82330602c646a93171c209c60239fc9ada05a2f6ec12595f0f18c8daff762
+  data.tar.gz: 8b1a707ca41396832b107df893fa08032832663b63610a4c9fc26ed16f306960
+SHA512:
+  metadata.gz: d2c6bcddb7efe2d5671a28ca756f6cd0dc4e72c534bd61266ae1aebdca98e2e9628814fd534483f78b0aba3bba111d8873a1852232c4752bd4c88ce7c62e264b
+  data.tar.gz: 5edcb475d5f20bca97689cf312afa7242818d17e0858f6af9da75c21c2482cda3df7fc51a6eaab752cfbf55531d0f25d3b954699392f1a44e3f697699ead225d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sudhanva Narayana
+
+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,68 @@
+# sudhanva for Ruby
+
+Minimal, dependency-free Ruby client for the public
+[sudhanva.me API](https://sudhanva.me/openapi.json). It retrieves published profile and article
+metadata, performs bounded batch reads, searches the published site, and creates or polls temporary
+profile-insight jobs.
+
+The API is public and requires no credentials. Do not send private data.
+
+## Install
+
+```bash
+gem install sudhanva
+```
+
+Or add it to a `Gemfile`:
+
+```ruby
+gem "sudhanva", "~> 0.1"
+```
+
+## Use
+
+```ruby
+require "sudhanva"
+
+client = Sudhanva::Client.new
+
+profile = client.profile
+posts = client.posts(limit: 5, tag: "kubernetes")
+article = client.post("making-your-site-agent-friendly")
+
+job = client.create_profile_insight(
+  audience: "hiring-manager",
+  focus: ["production-ml", "inference"],
+  idempotency_key: "my-workflow-2026-08-23"
+)
+result = client.wait_for_profile_insight(job["job_id"])
+```
+
+All methods return decoded JSON hashes. Non-success responses raise `Sudhanva::APIError` with
+`status`, `code`, and the decoded response body.
+
+## API coverage
+
+- `profile`
+- `posts` and `post`
+- `batch`
+- `create_profile_insight`, `profile_insight`, and `wait_for_profile_insight`
+- `ask` for NLWeb conversational search
+
+The client follows the stable `/api/v1` contract. See the
+[developer documentation](https://sudhanva.me/developers/sdks/) and
+[versioning policy](https://sudhanva.me/developers/versioning/).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+gem build sudhanva.gemspec
+```
+
+The test suite uses an injected transport and never calls production.
+
+## License
+
+MIT

data/lib/sudhanva/client.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Sudhanva
+  Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+  class APIError < StandardError
+    attr_reader :status, :code, :body
+
+    def initialize(status:, code:, message:, body:)
+      super("#{status} #{code}: #{message}")
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+
+  class Client
+    DEFAULT_BASE_URL = "https://sudhanva.me/api/v1"
+    USER_AGENT = "sudhanva-ruby/#{VERSION}"
+
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: 10, transport: nil)
+      raise ArgumentError, "timeout must be positive" unless timeout.positive?
+
+      @base_url = base_url.sub(%r{/+\z}, "")
+      parsed = URI.parse(@base_url)
+      unless %w[http https].include?(parsed.scheme) && parsed.host
+        raise ArgumentError, "base_url must be an absolute HTTP(S) URL"
+      end
+
+      @site_url = "#{parsed.scheme}://#{parsed.host}#{":#{parsed.port}" unless parsed.default_port == parsed.port}"
+      @timeout = timeout
+      @transport = transport || method(:default_transport)
+    end
+
+    def profile(locale: "en")
+      request("GET", "/profile", query: { locale: locale })
+    end
+
+    def posts(limit: 20, tag: nil, cursor: nil)
+      raise ArgumentError, "limit must be between 1 and 100" unless (1..100).cover?(limit)
+
+      request("GET", "/posts", query: { limit: limit, tag: tag, cursor: cursor })
+    end
+
+    def post(slug)
+      raise ArgumentError, "slug is required" if slug.to_s.empty?
+
+      request("GET", "/posts/#{URI.encode_www_form_component(slug)}")
+    end
+
+    def batch(operations)
+      raise ArgumentError, "operations must contain between 1 and 20 items" unless (1..20).cover?(operations.length)
+
+      request("POST", "/batch", json: { operations: operations })
+    end
+
+    def create_profile_insight(audience:, idempotency_key:, focus: nil)
+      raise ArgumentError, "idempotency_key is required" if idempotency_key.to_s.empty?
+
+      payload = { audience: audience }
+      payload[:focus] = focus if focus
+      request(
+        "POST",
+        "/profile-insights",
+        headers: { "Idempotency-Key" => idempotency_key },
+        json: payload
+      )
+    end
+
+    def profile_insight(job_id)
+      raise ArgumentError, "job_id is required" if job_id.to_s.empty?
+
+      request("GET", "/profile-insights/#{URI.encode_www_form_component(job_id)}")
+    end
+
+    def wait_for_profile_insight(job_id, timeout: 30, poll_interval: 1)
+      unless timeout.positive? && poll_interval >= 0
+        raise ArgumentError, "timeout must be positive and poll_interval cannot be negative"
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        job = profile_insight(job_id)
+        return job if %w[succeeded failed].include?(job["status"])
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          raise Timeout::Error, "profile insight #{job_id} did not finish within #{timeout}s"
+        end
+
+        sleep(poll_interval)
+      end
+    end
+
+    def ask(text, limit: 10, mode: "list")
+      raise ArgumentError, "text is required" if text.to_s.empty?
+      raise ArgumentError, "limit must be between 1 and 20" unless (1..20).cover?(limit)
+
+      request(
+        "POST",
+        "/ask",
+        base: @site_url,
+        json: {
+          query: { text: text, site: @site_url, limit: limit },
+          prefer: { streaming: false, response_format: "conversational_search", mode: mode },
+          meta: { version: "0.55" }
+        }
+      )
+    end
+
+    private
+
+    def request(method, path, query: {}, headers: {}, json: nil, base: @base_url)
+      uri = URI.parse("#{base.sub(%r{/+\z}, "")}/#{path.sub(%r{\A/+}, "")}")
+      query = query.reject { |_, value| value.nil? }
+      uri.query = URI.encode_www_form(query) unless query.empty?
+
+      request_headers = { "Accept" => "application/json", "User-Agent" => USER_AGENT }.merge(headers)
+      body = nil
+      if json
+        request_headers["Content-Type"] = "application/json"
+        body = JSON.generate(json)
+      end
+
+      response = @transport.call(method, uri, request_headers, body, @timeout)
+      payload = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      unless response.status.between?(200, 299)
+        error = payload.fetch("error", payload)
+        code = error.fetch("code", payload.fetch("code", "api_error"))
+        message = error.fetch("message", payload.fetch("message", "Request failed"))
+        raise APIError.new(status: response.status, code: code, message: message, body: payload)
+      end
+
+      raise APIError.new(status: response.status, code: "invalid_response", message: "API returned a non-object response", body: payload) unless payload.is_a?(Hash)
+
+      payload
+    rescue JSON::ParserError => error
+      raise APIError.new(status: response&.status || 0, code: "invalid_response", message: "API returned invalid JSON", body: nil), cause: error
+    end
+
+    def default_transport(method, uri, headers, body, timeout)
+      request_class = method == "POST" ? Net::HTTP::Post : Net::HTTP::Get
+      http_request = request_class.new(uri, headers)
+      http_request.body = body if body
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      result = http.request(http_request)
+      Response.new(status: result.code.to_i, headers: result.to_hash, body: result.body.to_s)
+    end
+  end
+end

data/lib/sudhanva/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sudhanva
+  VERSION = "0.1.0"
+end

data/lib/sudhanva.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "sudhanva/version"
+require_relative "sudhanva/client"

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: sudhanva
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sudhanva Narayana
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-24 00:00:00.000000000 Z
+dependencies: []
+description: A dependency-free client for published profile data, articles, search,
+  batch reads, and profile-insight jobs.
+email:
+- nsudhanva@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sudhanva.rb
+- lib/sudhanva/client.rb
+- lib/sudhanva/version.rb
+homepage: https://sudhanva.me
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://sudhanva.me
+  source_code_uri: https://github.com/nsudhanva/sudhanva-ruby
+  documentation_uri: https://sudhanva.me/developers/sdks/
+  bug_tracker_uri: https://github.com/nsudhanva/sudhanva-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Minimal Ruby client for the public sudhanva.me API.
+test_files: []