myrr-rb 0.3.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04e28d3ea019ce0843c0684022d231d322d388978188c9f798413d23b09643e0
+  data.tar.gz: 45f322be3df1e70288624705437ad0cbf3fcdcd2f8202df25f9273a44ae36705
+SHA512:
+  metadata.gz: 3a0ba5768933e2d7fccd0dd221cabed252de5a51d5d89e3c3f094bc8e49fbddc61c3cd27db09cccbe65d6921fb34a1ec11db430cfa7c3a2603898d36ab38be49
+  data.tar.gz: db56d11806c24413d92c08b96f1c15d188dabfa078e61630129da50194e3a1fd3f5bea73e46c6250eab11aaeae6be4e625c981b153e799bc55181d16710247a7

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+## [0.3.3] — 2026-06-02
+
+### Fixed
+
+- **Front-matter deduplication.** The middleware no longer double-inserts
+  front-matter when inline front-matter is present in the body: the
+  Rails path strips any inline front-matter from the body and merges it
+  with the auto-detected metadata (inline wins per key), and the
+  non-Rails path reads inline front-matter straight from the body.
+
+## [0.3.2] — 2026-06-02
+
+### Added
+
+- **Inline YAML front-matter in .md.erb views.** `Myrr::Port::Metadata`
+  now reads the current action's .md.erb template source for YAML
+  front-matter and merges it over auto-detected metadata — the view
+  wins for overlapping keys (title, description), auto-detection fills
+  in the rest. `token_count` remains middleware-computed only.
+
+# Changelog
+
+## [0.3.1] — 2026-06-02
+
+### Fixed
+
+- **Front-matter is always present.** Every markdown response now includes
+  YAML front-matter with at least `token_count`. Previously front-matter
+  was omitted when no title/description metadata was available. `token_count`
+  is a computed field the gem always knows — it should never be missing.
+
+## [0.3.0] — 2026-06-02
+
+### Added
+
+- **YAML front-matter auto-injection.** When a page has metadata (title,
+  description), `Myrr::Port::Middleware` prepends standard YAML front-matter
+  to every markdown response. Agents get structured metadata inline.
+
+- **`Myrr::Port::Metadata` concern.** Auto-included into every controller by
+  the railtie. Detects title/description from common Rails conventions:
+  `@myrr_title`, `@page_title`, `@title`, `content_for(:title)`, and
+  `Current.meta_tags`. Zero configuration.
+
+- **Front-matter fields.** `title` and `description` are developer-overridable
+  via the detection chain. `token_count` is always computed from the final
+  body and cannot be overridden.
+
+### Changed
+
+- **`Myrr::Port::Middleware`** now reads `env["myrr.metadata"]` and prepends
+  YAML front-matter wrapped in `---` delimiters when present. The token
+  count is recomputed after adding front-matter so `X-Token-Count` and the
+  body's `token_count` are always self-consistent.
+
+### Fixed
+
+- **Metadata concern handles missing `Current`.** The detection chain
+  safely skips `Current.meta_tags` when the `Current` singleton isn't
+  defined (most Rails apps).
+
+## [0.2.0] — 2026-06-01
+
+### Added
+- test/dummy/ Rails app — full integration test suite
+- examples/rails/ — copyable Rails 8.1 example
+- examples/rack/ — standalone Rack example
+- CHANGELOG.md — all releases documented
+
+## [0.1.1] — 2026-06-01
+
+### Fixed
+- X-Token-Count hardcoded, not configurable
+- lib/myrr-rb.rb entry point for Bundler auto-require
+
+## [0.1.0] — 2026-06-01
+Initial public release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Myrr Labs
+
+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 @@
+# Myrr — Agent-friendly content for your Rails app
+
+**myrr-rb** is the Ruby/Rails client for [Myrr](https://myrrlabs.com), a protocol that makes web content natively accessible to AI agents.
+
+## Myrr Port
+
+Myrr Port is the default, zero-configuration mode of myrr-rb. It adds agent-friendly markdown responses to your Rails app without a Go server, a database, or any configuration.
+
+### What it does
+
+- Counts tokens on every `text/markdown` response
+- Adds an `X-Token-Count` header so agents know the size of your content
+- Works alongside normal HTML — browsers see HTML, agents see markdown
+
+### How it works
+
+Rails 8.1 ships native markdown support: `format.md` in `respond_to`, `.md.erb` template resolution, and content negotiation via `Accept: text/markdown`, `.md` extension, or `?format=md`. Myrr Port defers entirely to Rails for this — we just count the tokens.
+
+For pre-Rails-8.1 apps, the `text/markdown` MIME type is registered automatically.
+
+### Getting started
+
+1. Add the gem to your Gemfile:
+
+```ruby
+gem "myrr-rb"
+```
+
+2. Run the installer:
+
+```bash
+rails generate myrr:install
+```
+
+3. Create markdown views alongside your HTML views. For example, if you have `app/views/articles/show.html.erb`, create `app/views/articles/show.md.erb`:
+
+```markdown
+# <%= @article.title %>
+
+<%= @article.body %>
+```
+
+4. Add `format.md` to your controller's `respond_to` block:
+
+```ruby
+def show
+  @article = Article.find(params[:id])
+  respond_to do |format|
+    format.html
+    format.md
+  end
+end
+```
+
+5. An agent requesting with `Accept: text/markdown` now receives:
+
+```
+Content-Type: text/markdown
+X-Token-Count: 142
+```
+
+No configuration needed. Everything works out of the box.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/generators/myrr/install/install_generator.rb

@@ -0,0 +1,20 @@
+require "rails/generators"
+
+module Myrr
+  module Generators
+    # Rails generator that creates the myrr-rb initializer.
+    #
+    # @example
+    #   rails generate myrr:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Myrr initializer for token counting on markdown responses."
+
+      # Create config/initializers/myrr.rb
+      def create_initializer
+        template "initializer.rb", "config/initializers/myrr.rb"
+      end
+    end
+  end
+end

data/lib/generators/myrr/install/templates/initializer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Myrr Port — Agent-friendly content for your Rails app
+#
+# Out of the box, myrr-rb counts tokens on every text/markdown response
+# and adds an X-Token-Count header. No Go server, no database, no
+# configuration required.
+#
+# For full documentation, see https://myrrlabs.com/docs
+
+# No configuration is needed — everything works out of the box.
+# This file exists so you know where to put future opt-in options.

data/lib/myrr/bridge.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Myrr
+  module Bridge
+    Error = Class.new(::StandardError)
+    SellerNotApproved = Class.new(Error)
+    BudgetExceeded = Class.new(Error)
+    InsufficientFunds = Class.new(Error)
+    NoPaymentMethod = Class.new(Error)
+
+    # Resolve a 402 Payment Required by auto-paying and retrying.
+    #
+    # Calls the bridge endpoint on the agent's protocol server.
+    #
+    # @param agent_did [String] The agent's did:myrr: identifier
+    # @param seller_url [String] Base URL of the seller's protocol server
+    # @param seller_did [String] The seller's did:myrr: identifier
+    # @param payment_required [Hash] The 402 response body
+    # @param retry_method [String] HTTP method for the retry
+    # @param retry_path [String] Path to retry
+    # @param retry_headers [Hash, nil] Additional headers for the retry
+    # @return [Hash] The seller's response ({ "status_code" => 200, "body" => "..." })
+    # @raise [Myrr::Bridge::SellerNotApproved]
+    # @raise [Myrr::Bridge::BudgetExceeded]
+    # @raise [Myrr::Bridge::NoPaymentMethod]
+    def self.resolve(agent_did:, seller_url:, seller_did:, payment_required:, retry_method:, retry_path:, retry_headers: nil)
+      config = ::Myrr.config
+      server_url = config.protocol_server_url
+      api_key = config.site_api_key
+
+      uri = URI.join(server_url, "/v1/pay/resolve")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = config.open_timeout || 5
+      http.read_timeout = config.read_timeout || 30
+      http.use_ssl = (uri.scheme == "https")
+
+      payload = {
+        agent_did: agent_did,
+        seller_url: seller_url,
+        seller_did: seller_did,
+        payment_required: payment_required,
+        retry: {
+          method: retry_method,
+          path: retry_path,
+          headers: retry_headers || {}
+        }
+      }
+
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{api_key}" if api_key
+      request.body = payload.to_json
+
+      response = http.request(request)
+      data = JSON.parse(response.body)
+
+      # Map HTTP status to bridge errors
+      case response.code.to_i
+      when 200..299
+        # Check for error payload in body (some bridge errors come as 200 with error field)
+        if data.is_a?(Hash)
+          case data["error"]
+          when "seller_not_approved"
+            raise SellerNotApproved, "Seller #{data["seller_did"]} is not approved"
+          when "budget_exceeded"
+            raise BudgetExceeded, "Budget exceeded: #{data["reason"]} (limit=#{data["limit"]}, current=#{data["current"]})"
+          when "no_payment_method"
+            raise NoPaymentMethod, data["message"]
+          end
+        end
+        data
+      when 400
+        if data["error"] == "no_payment_method"
+          raise NoPaymentMethod, data["message"]
+        end
+        raise Error, data["error"] || "Bad request"
+      when 402
+        raise InsufficientFunds, data["error"] || "Insufficient funds"
+      when 403
+        if data["error"] == "seller_not_approved"
+          raise SellerNotApproved, "Seller #{data["seller_did"]} is not approved"
+        elsif data["error"] == "budget_exceeded"
+          raise BudgetExceeded, "Budget exceeded: #{data["reason"]} (limit=#{data["limit"]}, current=#{data["current"]})"
+        end
+        raise Error, data["error"] || "Forbidden"
+      else
+        raise Error, data["error"] || "HTTP #{response.code}"
+      end
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response"
+    end
+  end
+end

data/lib/myrr/budget.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Myrr
+  # Budget represents spending limit rules for an agent.
+  #
+  # @example
+  #   Myrr::Budget.set(
+  #     agent_did: "did:myrr:abc123",
+  #     daily_max_cents: 100_00,
+  #     monthly_max_cents: 500_00,
+  #     allowed_merchant_categories: ["data_services", "api_services"]
+  #   )
+  #
+  #   budget = Myrr::Budget.for_agent("did:myrr:abc123")
+  class Budget
+    attr_reader :id, :agent_did, :per_transaction_max, :topup_per_transaction_max,
+                :daily_max, :monthly_max, :allowed_merchant_categories,
+                :created_at, :updated_at
+
+    # @param attrs [Hash] Budget attributes from the API
+    def initialize(attrs)
+      @id = attrs["id"]
+      @agent_did = attrs["agent_did"]
+      @per_transaction_max = attrs["per_transaction_max"]
+      @topup_per_transaction_max = attrs["topup_per_transaction_max"]
+      @daily_max = attrs["daily_max"]
+      @monthly_max = attrs["monthly_max"]
+      @allowed_merchant_categories = attrs["allowed_merchant_categories"]
+      @created_at = attrs["created_at"]
+      @updated_at = attrs["updated_at"]
+    end
+
+    # Create or update budget for an agent.
+    #
+    # @param agent_did [String] The did:myrr: identifier
+    # @param per_transaction_max_cents [Integer, nil] Max per transaction
+    # @param topup_per_transaction_max_cents [Integer, nil] Max per top-up
+    # @param daily_max_cents [Integer, nil] Max per day
+    # @param monthly_max_cents [Integer, nil] Max per month
+    # @param allowed_merchant_categories [Array<String>, nil] Allowed MCCs
+    # @return [Myrr::Budget]
+    def self.set(agent_did:, per_transaction_max_cents: nil, topup_per_transaction_max_cents: nil,
+                 daily_max_cents: nil, monthly_max_cents: nil, allowed_merchant_categories: nil)
+      body = { agent_did: agent_did }
+      body[:per_transaction_max] = per_transaction_max_cents if per_transaction_max_cents
+      body[:topup_per_transaction_max] = topup_per_transaction_max_cents if topup_per_transaction_max_cents
+      body[:daily_max] = daily_max_cents if daily_max_cents
+      body[:monthly_max] = monthly_max_cents if monthly_max_cents
+      body[:allowed_merchant_categories] = allowed_merchant_categories if allowed_merchant_categories
+
+      resp = Myrr.client.send(:post, "/v1/budgets", body)
+      new(resp)
+    end
+
+    # Get budget for an agent.
+    #
+    # @param agent_did [String] The did:myrr: identifier
+    # @return [Myrr::Budget, nil] Returns nil if no budget has been set
+    def self.for_agent(agent_did)
+      resp = Myrr.client.send(:get, "/v1/budgets/agent/#{agent_did}")
+      new(resp)
+    rescue Myrr::Error => e
+      raise unless e.message.include?("agent_not_found")
+      nil
+    end
+  end
+end

data/lib/myrr/card.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Myrr
+  # Virtual card issued to a wallet.
+  #
+  # Card numbers, expiry, and CVC are returned ONLY at creation time.
+  # Subsequent lookups return last4 only.
+  class Card
+    attr_reader :id, :wallet_id, :last4, :brand, :status, :controls,
+                :number, :expiry, :cvc, :created_at, :updated_at
+
+    # @param attrs [Hash] Card attributes from the API
+    def initialize(attrs)
+      @id = attrs["id"]
+      @wallet_id = attrs["wallet_id"]
+      @last4 = attrs["last4"]
+      @brand = attrs["brand"] || "visa"
+      @status = attrs["status"]
+      @controls = attrs["controls"]
+      @number = attrs["number"]
+      @expiry = attrs["expiry"]
+      @cvc = attrs["cvc"]
+      @created_at = attrs["created_at"]
+      @updated_at = attrs["updated_at"]
+    end
+
+    # Freeze this card (no new authorizations).
+    def freeze!
+      resp = client.post("/v1/wallets/#{wallet_id}/cards/#{id}/freeze", {})
+      @status = resp["status"]
+      self
+    end
+
+    # Unfreeze this card.
+    def unfreeze!
+      resp = client.post("/v1/wallets/#{wallet_id}/cards/#{id}/unfreeze", {})
+      @status = resp["status"]
+      self
+    end
+
+    # Permanently cancel this card.
+    def cancel!
+      resp = client.delete("/v1/wallets/#{wallet_id}/cards/#{id}")
+      @status = resp["status"]
+      self
+    end
+
+    private
+
+    def client
+      Myrr.client
+    end
+  end
+end

data/lib/myrr/client.rb

@@ -0,0 +1,158 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Myrr
+  # Client for the Myrr protocol server API.
+  #
+  # Wraps the register, challenge, verify, revoke, and lookup endpoints.
+  # Also provides generic +post+, +get+, and +delete+ methods for resource clients.
+  #
+  # @example
+  #   client = Myrr::Client.new(server_url: "http://localhost:8080", api_key: "sk-...")
+  #   result = client.register(public_key: hex_pub_key)
+  #   result = client.verify(did_key)
+  class Client
+    # @param server_url [String] Base URL of the protocol server
+    # @param api_key [String, nil] API key for authenticated operations
+    # @param open_timeout [Integer] HTTP open timeout in seconds
+    # @param read_timeout [Integer] HTTP read timeout in seconds
+    def initialize(server_url:, api_key: nil, open_timeout: 5, read_timeout: 10)
+      @server_url = server_url.chomp("/")
+      @api_key = api_key
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Register a new agent identity.
+    #
+    # @param public_key [String] Hex-encoded Ed25519 public key
+    # @param owner [Hash, nil] Optional owner info (+type+ and +value+)
+    # @return [Hash] Response with +id+, +did_key+, +status+, +created_at+
+    # @raise [Myrr::Error] On server error
+    def register(public_key:, owner: nil)
+      body = { public_key: public_key }
+      body[:owner] = owner if owner
+      post("/v1/identities/register", body)
+    end
+
+    # Get a challenge nonce for the given identity.
+    #
+    # @param did_key [String] The did:myrr: identifier
+    # @return [String] Challenge nonce
+    # @raise [Myrr::Error] On server error or if identity not found
+    def challenge(did_key)
+      resp = post("/v1/identities/challenge", { id: did_key })
+      resp["challenge"]
+    end
+
+    # Verify an agent's identity. Performs a status check via the protocol server.
+    #
+    # Returns a hash with +did_key+, +status+, and optional +owner+.
+    # Returns nil if the identity is not found.
+    #
+    # @param did_key [String] The did:myrr: identifier
+    # @return [Hash, nil] Agent info or nil
+    def verify(did_key)
+      challenge(did_key)
+      { "did_key" => did_key, "status" => "active" }
+    rescue Error => e
+      if e.message.include?("not_found") || e.message.include?("revoked")
+        nil
+      else
+        raise
+      end
+    end
+
+    # Revoke an agent identity.
+    #
+    # @param did_key [String] The did:myrr: identifier
+    # @return [Hash] Response with +status+, +did_key+, +revoked_at+
+    # @raise [Myrr::Error] On server error
+    def revoke(did_key)
+      post("/v1/identities/revoke", { id: did_key }, authenticated: true)
+    end
+
+    # Look up identities by owner.
+    #
+    # @param owner_type [String] Owner type (e.g., "email")
+    # @param owner_value [String] Owner value (e.g., "user@example.com")
+    # @return [Array<Hash>] List of matching identities
+    def lookup_by_owner(owner_type:, owner_value:)
+      get("/v1/identities", owner_type: owner_type, owner_value: owner_value)
+    end
+
+    # Send a POST request to the protocol server.
+    #
+    # @param path [String] API path (e.g., "/v1/wallets")
+    # @param body [Hash] Request body
+    # @param authenticated [Boolean] Whether to include the API key
+    # @return [Hash] Parsed JSON response
+    def post(path, body, authenticated: false)
+      uri = URI("#{@server_url}#{path}")
+      http = build_http(uri)
+
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@api_key}" if authenticated && @api_key
+      request.body = JSON.generate(body)
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    # Send a GET request to the protocol server.
+    #
+    # @param path [String] API path (e.g., "/v1/wallets")
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed JSON response
+    def get(path, **params)
+      uri = URI("#{@server_url}#{path}")
+      uri.query = URI.encode_www_form(params) if params.any?
+
+      http = build_http(uri)
+      request = Net::HTTP::Get.new(uri)
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    # Send a DELETE request to the protocol server.
+    #
+    # @param path [String] API path
+    # @return [Hash] Parsed JSON response
+    def delete(path)
+      uri = URI("#{@server_url}#{path}")
+      http = build_http(uri)
+      request = Net::HTTP::Delete.new(uri)
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    private
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http.use_ssl = (uri.scheme == "https")
+      http
+    end
+
+    def handle_response(response)
+      case response
+      when Net::HTTPCreated, Net::HTTPOK
+        body = response.body
+        body && !body.empty? ? JSON.parse(body) : {}
+      when Net::HTTPNotFound
+        raise Error, "not_found: #{response.body}"
+      when Net::HTTPTooManyRequests
+        raise Error, "rate_limit_exceeded: #{response.body}"
+      else
+        error = JSON.parse(response.body) rescue { "error" => "unknown", "message" => response.body }
+        raise Error, "#{error["error"]}: #{error["message"]}"
+      end
+    end
+  end
+end

data/lib/myrr/configuration.rb

@@ -0,0 +1,58 @@
+module Myrr
+  # Configuration for the myrr-rb gem.
+  #
+  # In its default (Port) state the gem requires zero configuration.
+  # Token counting on +text/markdown+ responses and the
+  # +X-Token-Count+ header are active out of the box.
+  #
+  # Additional attributes exist for the opt-in identity and pay layers
+  # (not auto-loaded — require explicitly).
+  class Configuration
+    # --- Identity-layer attributes (opt-in, not auto-loaded) ---
+
+    # URL of the Myrr protocol server (e.g. "http://localhost:8080").
+    # Required when using the identity or pay layers.
+    # @return [String, nil]
+    attr_accessor :protocol_server_url
+
+    # API key for authenticating with the protocol server.
+    # @return [String, nil]
+    attr_accessor :site_api_key
+
+    # Optional lambda that replaces protocol server calls for identity
+    # verification. Receives a +did:myrr:+ string, returns a hash with
+    # +did_key+, +status+, and optional +owner+, or nil.
+    # @return [Proc, nil]
+    attr_accessor :identity_adapter
+
+    # When true (default), requests proceed when identity verification
+    # fails (logging a warning). When false, returns 502 Bad Gateway.
+    # @return [Boolean]
+    attr_accessor :fail_open
+
+    # When true, the identity middleware auto-selects +:md+ format when
+    # an agent is detected and no explicit format is set.
+    # Default is false (port mode does not negotiate format).
+    # @return [Boolean]
+    attr_accessor :auto_format_md
+
+    # HTTP open timeout in seconds.
+    # @return [Integer]
+    attr_accessor :open_timeout
+
+    # HTTP read timeout in seconds.
+    # @return [Integer]
+    attr_accessor :read_timeout
+
+    def initialize
+      # Identity-layer defaults (nil / conservative — opt-in only)
+      @protocol_server_url = nil
+      @site_api_key = nil
+      @identity_adapter = nil
+      @fail_open = true
+      @auto_format_md = false
+      @open_timeout = 5
+      @read_timeout = 10
+    end
+  end
+end