ai2web 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8142d4c3ef57f6bb7ba24a60b478f4cab0e981c1acf0613f6ace7fe81b69a0a4
-  data.tar.gz: c1ddfcec49f61c4ac55299ce2dfba7467c742faf48d65c7559e581ee4d467eb1
+  metadata.gz: 892b44b396f60be4ebd7af6bca0c19be6b1c3d8fdbdd2a66b2ed9235915c8690
+  data.tar.gz: a6705de41a0928bdddcf5787b13b72b53f0d45b6e47c4805deff898e5c650fad
 SHA512:
-  metadata.gz: 82e19660de9ef91eb1a7167038ec9cb15db553d726936380e768305fcdb736cae9598445954d3433cc4915e05b677e977132002cbad2786a30ddfa26fc991177
-  data.tar.gz: dbb147055be31d20c74aab55c6bee8c21dc6f0d6d6574f76a6e0ef35cf0b1280737527b151b14622dfb372032c68407086e215ee036630ca5805a81ca3b03937
+  metadata.gz: 675f6db1358bf674c7579b27db5b5ca46f4e44be3cd76abacf793f4e10a25ef4f2b83fff596bf8bd65010476004c6c3e7b629e31344e6b8ee47de50fca91c1d6
+  data.tar.gz: df4a693934c5e3838a2e016034a79d4ca838295a0842d77117fbd52ba1fe17551ac50791e9dc156c4830a896633bd31a12802d58f0b14901cad6b6b24673eb3d

data/README.md

@@ -9,6 +9,8 @@
 
 # AI2Web Ruby SDK (`ai2web`)
 
+[![AI2Web on Launchpadly - Product of the Week (Gold)](https://launchpadly.co/embed/badges/startup/ai2web.svg?variant=product-week-gold)](https://launchpadly.co/startup/ai2web?ref=badge)
+
 [![CI](https://github.com/ai2web-foundation/ai2web-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/ai2web-foundation/ai2web-ruby/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/ai2web)](https://rubygems.org/gems/ai2web)
 

data/lib/ai2web/ap2.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "digest"
+require "base64"
+require "json"
+require "securerandom"
+
+module Ai2Web
+  # AP2 (Agent Payments Protocol, Google - v0.2.0) merchant primitives.
+  #
+  # AP2 is mandate-based: the merchant prices a buyer agent's Intent Mandate as a CartContents
+  # (a W3C PaymentRequest, amounts in decimal major units) and digitally signs it into a
+  # CartMandate - a short-lived guarantee of items and price - then settles a user-signed Payment
+  # Mandate. This module provides the reusable, app-agnostic core: build the mandate objects, sign
+  # a CartContents as an RS256 JWT (cart_hash over the canonical contents), publish the public key
+  # as a JWKS, verify a Cart Mandate, and parse a Payment Mandate. Signing uses the OpenSSL
+  # standard library, so the SDK keeps zero third-party dependencies.
+  module Ap2
+    EXTENSION_URI = "https://github.com/google-agentic-commerce/ap2/v1"
+    VERSION = "0.2.0"
+    DEFAULT_TTL = 900
+
+    module_function
+
+    # The transports.ap2 advertisement to merge into a manifest.
+    def transport(overrides = {})
+      {
+        "enabled" => true,
+        "version" => VERSION,
+        "extension" => EXTENSION_URI,
+        "agent_card" => "/ai2w/ap2/agent-card",
+        "cart" => "/ai2w/ap2/cart",
+        "payment" => "/ai2w/ap2/payment",
+        "jwks" => "/ai2w/ap2/jwks"
+      }.merge(overrides.each_with_object({}) { |(k, v), o| o[k.to_s] = v })
+    end
+
+    # Build an AP2 IntentMandate (classic v0.2.0 shape).
+    def intent_mandate(description, merchants: nil, skus: nil, items: nil, requires_refundability: false,
+                       user_cart_confirmation_required: true, expires_in: DEFAULT_TTL, now: nil)
+      ts = now || Time.now.to_i
+      m = {
+        "natural_language_description" => description,
+        "intent_expiry" => iso(ts + expires_in),
+        "user_cart_confirmation_required" => user_cart_confirmation_required
+      }
+      m["merchants"] = merchants if merchants && !merchants.empty?
+      m["skus"] = skus if skus && !skus.empty?
+      m["items"] = items if items && !items.empty?
+      m["requires_refundability"] = true if requires_refundability
+      m
+    end
+
+    # AP2 PaymentCurrencyAmount: decimal major units, ISO 4217.
+    def amount(value, currency)
+      { "currency" => currency.upcase, "value" => value.round(2) }
+    end
+
+    # Build a CartContents (W3C PaymentRequest) from line items. Each item is
+    # { label:, unit_amount:, quantity: 1 } (string or symbol keys).
+    def cart_contents(items, currency, merchant_name, id: nil, payment_details_id: nil, expires_in: DEFAULT_TTL, now: nil)
+      ts = now || Time.now.to_i
+      display = []
+      total = 0.0
+      items.each do |it|
+        qty = [(it[:quantity] || it["quantity"] || 1).to_i, 1].max
+        unit = (it[:unit_amount] || it["unit_amount"] || it[:amount] || it["amount"] || 0).to_f
+        line = unit * qty
+        label = (it[:label] || it["label"] || "Item").to_s
+        label = "#{label} x#{qty}" if qty > 1
+        display << { "label" => label, "amount" => amount(line, currency) }
+        total += line
+      end
+      {
+        "id" => id || "cart_#{SecureRandom.hex(10)}",
+        "user_cart_confirmation_required" => true,
+        "payment_request" => {
+          "method_data" => [{ "supported_methods" => "card", "data" => {} }],
+          "details" => {
+            "id" => payment_details_id || "pr_#{SecureRandom.hex(10)}",
+            "display_items" => display,
+            "total" => { "label" => "Total", "amount" => amount(total, currency) }
+          },
+          "options" => { "request_shipping" => true }
+        },
+        "cart_expiry" => iso(ts + expires_in),
+        "merchant_name" => merchant_name
+      }
+    end
+
+    # The merchant_authorization JWT (RS256) over the canonical CartContents.
+    def sign_cart(contents, private_key_pem, kid: nil, iss: nil, aud: "ap2-network", expires_in: DEFAULT_TTL, now: nil)
+      key = OpenSSL::PKey::RSA.new(private_key_pem)
+      ts = now || Time.now.to_i
+      header = { "alg" => "RS256", "typ" => "JWT", "kid" => kid || kid_of(key) }
+      claims = {
+        "iss" => iss || contents["merchant_name"] || "",
+        "sub" => contents["id"] || "",
+        "aud" => aud,
+        "iat" => ts,
+        "exp" => ts + expires_in,
+        "jti" => SecureRandom.hex(12),
+        "cart_hash" => b64url(Digest::SHA256.digest(canonical(contents)))
+      }
+      signing_input = "#{b64url(canonical(header))}.#{b64url(canonical(claims))}"
+      sig = key.sign(OpenSSL::Digest.new("SHA256"), signing_input)
+      "#{signing_input}.#{b64url(sig)}"
+    end
+
+    # Sign CartContents into a CartMandate (contents + merchant_authorization).
+    def cart_mandate(contents, private_key_pem, **opts)
+      { "contents" => contents, "merchant_authorization" => sign_cart(contents, private_key_pem, **opts) }
+    end
+
+    # JWKS publishing the cart-signing public key, for verifiers.
+    def jwks(private_key_pem, kid: nil)
+      key = OpenSSL::PKey::RSA.new(private_key_pem)
+      pub = key.public_key
+      {
+        "keys" => [{
+          "kty" => "RSA",
+          "use" => "sig",
+          "alg" => "RS256",
+          "kid" => kid || kid_of(key),
+          "n" => b64url(pub.n.to_s(2)),
+          "e" => b64url(pub.e.to_s(2))
+        }]
+      }
+    end
+
+    # Verify a CartMandate's signature (against a public or private PEM) and its cart_hash binding,
+    # and that it has not expired.
+    def verify_cart_mandate(mandate, key_pem)
+      parts = mandate["merchant_authorization"].to_s.split(".")
+      return false unless parts.length == 3
+
+      key = begin
+        OpenSSL::PKey::RSA.new(key_pem)
+      rescue StandardError
+        return false
+      end
+      sig = begin
+        b64url_decode(parts[2])
+      rescue StandardError
+        return false
+      end
+      return false unless key.verify(OpenSSL::Digest.new("SHA256"), sig, "#{parts[0]}.#{parts[1]}")
+
+      claims = begin
+        JSON.parse(b64url_decode(parts[1]))
+      rescue StandardError
+        return false
+      end
+      ch = claims["cart_hash"].to_s
+      return false if ch.empty?
+      return false if claims["exp"] && Time.now.to_i > claims["exp"].to_i
+
+      expected = b64url(Digest::SHA256.digest(canonical(mandate["contents"] || {})))
+      ch == expected
+    end
+
+    # Extract the salient fields of a PaymentMandate for settlement.
+    def payment_details(payment_mandate)
+      c = payment_mandate["payment_mandate_contents"] || {}
+      resp = c["payment_response"] || {}
+      total = c["payment_details_total"] || {}
+      {
+        "payment_mandate_id" => c["payment_mandate_id"],
+        "payment_details_id" => c["payment_details_id"],
+        "total" => total["amount"],
+        "method" => resp["method_name"],
+        "payer_email" => resp["payer_email"],
+        "payer_name" => resp["payer_name"]
+      }
+    end
+
+    # --- helpers ---
+
+    # JCS (RFC 8785) canonicalisation, so a cart_hash is byte-identical across every SDK: object
+    # keys sorted, no whitespace, minimal string escaping, integers without a decimal point,
+    # currency amounts as a short decimal.
+    def canonical(value)
+      case value
+      when nil then "null"
+      when true then "true"
+      when false then "false"
+      when Integer then value.to_s
+      when Float then jcs_number(value)
+      when String then jcs_string(value)
+      when Array then "[#{value.map { |e| canonical(e) }.join(',')}]"
+      when Hash
+        pairs = value.map { |k, v| [k.to_s, v] }.sort_by { |k, _| k }
+        "{#{pairs.map { |k, v| "#{jcs_string(k)}:#{canonical(v)}" }.join(',')}}"
+      else "null"
+      end
+    end
+
+    def jcs_number(x)
+      return x.to_i.to_s if x == x.to_i && x.abs < 1e15
+
+      format("%.2f", x).sub(/0+\z/, "").sub(/\.\z/, "")
+    end
+
+    def jcs_string(str)
+      out = +'"'
+      str.each_char do |ch|
+        o = ch.ord
+        if ch == '"'
+          out << '\\"'
+        elsif ch == "\\"
+          out << "\\\\"
+        elsif o == 0x08 then out << "\\b"
+        elsif o == 0x09 then out << "\\t"
+        elsif o == 0x0A then out << "\\n"
+        elsif o == 0x0C then out << "\\f"
+        elsif o == 0x0D then out << "\\r"
+        elsif o < 0x20 then out << format("\\u%04x", o)
+        else out << ch
+        end
+      end
+      out << '"'
+      out
+    end
+
+    def b64url(bin)
+      Base64.urlsafe_encode64(bin, padding: false)
+    end
+
+    def b64url_decode(str)
+      Base64.urlsafe_decode64(str + ("=" * ((4 - (str.length % 4)) % 4)))
+    end
+
+    def iso(timestamp)
+      Time.at(timestamp).utc.strftime("%Y-%m-%dT%H:%M:%S+00:00")
+    end
+
+    def kid_of(key)
+      pub = key.public_key
+      Digest::SHA256.hexdigest(pub.n.to_s(2) + pub.e.to_s(2))[0, 16]
+    end
+  end
+end

data/lib/ai2web/nlweb.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Ai2Web
+  # NLWeb (nlweb.ai) interop primitives.
+  #
+  # NLWeb turns a site's content into a natural-language, schema.org-flavoured query endpoint (its
+  # `ask` API). These helpers let an AI2Web site advertise an NLWeb surface in its manifest and
+  # serve a minimal, NLWeb-compatible `ask` response over its own content, so agents that speak
+  # NLWeb can query the site without it deploying the full NLWeb stack.
+  #
+  # The search itself is application-specific (a pure toolkit): the app finds the matching content
+  # items and passes them in; #ask_response shapes them into NLWeb's result envelope (list mode,
+  # schema.org Item results; pass an answer for generate mode). NLWeb defines no discovery file, so
+  # #transport is an AI2Web convention pointing at the site's `/ask` (and `/mcp`) URLs.
+  module Nlweb
+    VERSION = "0.55"
+    DEFAULT_ASK = "/ai2w/nlweb/ask"
+    DEFAULT_MCP = "/ai2w/nlweb/mcp"
+
+    module_function
+
+    # The transports.nlweb advertisement to merge into a manifest.
+    def transport(overrides = {})
+      {
+        "enabled" => true,
+        "version" => VERSION,
+        "ask" => DEFAULT_ASK,
+        "mcp" => DEFAULT_MCP,
+        "modes" => ["list"]
+      }.merge(overrides.each_with_object({}) { |(k, v), o| o[k.to_s] = v })
+    end
+
+    # Wrap one content item into an NLWeb result Item.
+    def item(content, site: nil, site_url: nil)
+      c = stringify(content)
+      schema = c["schema_object"].is_a?(Hash) ? c["schema_object"] : schema_object(c)
+      {
+        "@type" => "Item",
+        "url" => (c["url"] || "").to_s,
+        "name" => (c["name"] || c["title"] || "").to_s,
+        "site" => (c["site"] || site || "").to_s,
+        "siteUrl" => (c["siteUrl"] || site_url || "").to_s,
+        "score" => c.key?("score") ? c["score"].to_i : 100,
+        "description" => (c["description"] || "").to_s,
+        "schema_object" => schema
+      }
+    end
+
+    # Build a minimal buffered NLWeb ask response (list mode) from matched content items.
+    def ask_response(query, items, site: nil, site_url: nil, query_id: nil, answer: nil)
+      results = items.map { |it| item(it.is_a?(Hash) ? it : {}, site: site, site_url: site_url) }
+      resp = {
+        "query" => query,
+        "query_id" => query_id || "q_#{SecureRandom.hex(8)}",
+        "message_type" => "result",
+        "results" => results
+      }
+      resp["answer"] = { "@type" => "GeneratedAnswer", "answer" => answer.to_s, "items" => results } if answer && !answer.to_s.empty?
+      resp
+    end
+
+    def schema_object(content)
+      c = stringify(content)
+      obj = { "@type" => (c["type"] || "Thing").to_s }
+      name = c["name"] || c["title"]
+      obj["name"] = name if name
+      obj["url"] = c["url"] if c["url"]
+      obj["description"] = c["description"] if c["description"]
+      obj
+    end
+
+    def stringify(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), o| o[k.to_s] = v }
+    end
+  end
+end

data/lib/ai2web/version.rb

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

data/lib/ai2web.rb

@@ -21,3 +21,5 @@ require_relative "ai2web/negotiator"
 require_relative "ai2web/export"
 require_relative "ai2web/manifest"
 require_relative "ai2web/server"
+require_relative "ai2web/ap2"
+require_relative "ai2web/nlweb"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ai2web
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - AI2Web Foundation
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies: []
 description: The Ruby implementation of the AI2Web protocol - describe your website
   once and make it understandable and actionable to any AI agent. Fluent manifest
@@ -24,9 +24,11 @@ files:
 - LICENSE
 - README.md
 - lib/ai2web.rb
+- lib/ai2web/ap2.rb
 - lib/ai2web/export.rb
 - lib/ai2web/manifest.rb
 - lib/ai2web/negotiator.rb
+- lib/ai2web/nlweb.rb
 - lib/ai2web/safety.rb
 - lib/ai2web/schema.rb
 - lib/ai2web/server.rb