apparel-monster 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec51b45705597515cdba7a3c7cdeb39027d03ed466cda70bf887f81ed2be5c18
+  data.tar.gz: 7bc15557e9696d998630802c84154e31ccf4b518170359eca92b718c9b19e628
+SHA512:
+  metadata.gz: 854c9ae0a4e8109c0b659a47612651ce3c7476d72bbda8614b97533265434a888d3350c22bad5f1cec72c9a0fc800b57489dc5939413e46c203d48a1356b55eb
+  data.tar.gz: 55922bbf5d80e63d5a617b14cfa97c626d16ed645e3fef168418df63b38c27a29a64780ca304bf5b31e68e3270f0be0f4ab6d719d471fa8824eefab7bd12d96a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Lugassy
+
+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/exe/apparel-monster

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# apparel-monster — the store from a terminal.
+#
+# Identifies itself as ruby-cli rather than ruby-sdk, so the store can tell a
+# person poking at the API from an integration running in production. Same
+# client, one flag apart.
+#
+# Prints JSON unless --text is passed: the usual reader here is a script or an
+# agent, not a person.
+
+require "json"
+require "optparse"
+require_relative "../lib/apparel_monster"
+
+USAGE = <<~TEXT
+  apparel-monster #{ApparelMonster::VERSION} — agent commerce CLI for apparel.monster
+
+  USAGE
+    apparel-monster <command> [args] [flags]
+
+  COMMANDS
+    search <query>              Search the catalog
+    product <id...>             Full detail for product or variant ids
+    ask <question>              Natural-language search (NLWeb)
+    pricing                     Plans, limits and merchandise price ranges
+    buy <variant-id>            Mint an Apple Pay / Google Pay link for one variant
+    watch <variant-id> <price>  Watch a variant for a target price
+    watch-status <id>           Poll a price watch
+
+  FLAGS
+    --limit N         Results to return
+    --category PATH   Browse a category instead of searching
+    --sort SORT       relevance | cheapest | expensive | newest | name | popular
+    --base URL        Point at another origin
+    --text            Human-readable output instead of JSON
+    --stream          Stream results as they arrive (ask)
+
+  The API needs no credentials. This is a demo store: orders are placed against
+  a test gateway, nothing ships and no money moves.
+TEXT
+
+options = { base: ApparelMonster::DEFAULT_BASE }
+parser = OptionParser.new do |opts|
+  opts.on("--limit N", Integer) { |v| options[:limit] = v }
+  opts.on("--category PATH") { |v| options[:category] = v }
+  opts.on("--sort SORT") { |v| options[:sort] = v }
+  opts.on("--base URL") { |v| options[:base] = v }
+  opts.on("--text") { options[:text] = true }
+  opts.on("--stream") { options[:stream] = true }
+  opts.on("-h", "--help") { puts USAGE; exit 0 }
+  opts.on("--version") { puts ApparelMonster::VERSION; exit 0 }
+end
+
+args = parser.parse(ARGV)
+command = args.shift
+
+if command.nil? || command == "help"
+  puts USAGE
+  exit 0
+end
+
+# Just enough formatting to read a result without piping through jq.
+def humanise(data)
+  if data.is_a?(Hash) && data["products"].is_a?(Array)
+    return "No products matched. Try fewer words, or browse: apparel-monster search --category categories/men" if data["products"].empty?
+
+    return data["products"].map { |product|
+      prices = product.fetch("variants", []).map { |v| v["effective_price"] || v["price"] }.compact
+      sizes  = product.fetch("variants", []).map { |v| v.dig("options", "Size") }.compact.uniq
+      lines = [prices.any? ? format("%s  $%.2f", product["title"], prices.min) : product["title"]]
+      lines << "  #{product['category']}" if product["category"]
+      lines << "  sizes: #{sizes.join(', ')}" if sizes.any?
+      lines << "  #{product['url']}"
+      lines.join("\n")
+    }.join("\n\n")
+  end
+
+  if data.is_a?(Hash) && data["results"].is_a?(Array)
+    if data["results"].empty?
+      query = data.dig("_meta", "query")
+      return "No match for #{query.inspect}. /ask matches keywords, not meaning — try fewer words " \
+             '("coat" rather than "warm winter coat").'
+    end
+    return data["results"].map { |r| "#{r['name']}\n  #{r['description']}\n  #{r['url']}" }.join("\n\n")
+  end
+
+  JSON.pretty_generate(data)
+end
+
+def emit(data, options)
+  puts options[:text] ? humanise(data) : JSON.pretty_generate(data)
+end
+
+store = ApparelMonster::Client.new(base_url: options[:base], cli: true)
+
+begin
+  case command
+  when "search"
+    emit(store.search(args.join(" ").empty? ? nil : args.join(" "),
+                      limit: options[:limit], category: options[:category], sort: options[:sort]), options)
+
+  when "product"
+    abort "product needs at least one id" if args.empty?
+    emit(store.product(args), options)
+
+  when "ask"
+    abort "ask needs a question" if args.empty?
+    question = args.join(" ")
+    if options[:stream]
+      store.ask_stream(question, limit: options[:limit]) do |event, data|
+        next unless event == "result"
+
+        puts options[:text] ? "#{data['name']} — #{data['url']}" : JSON.generate(data)
+      end
+    else
+      emit(store.ask(question, limit: options[:limit]), options)
+    end
+
+  when "pricing"
+    # The prose document rather than an endpoint: it is the canonical answer to
+    # "what does this cost", and markdown reads fine here.
+    require "net/http"
+    uri = URI("#{store.base_url}/pricing.md")
+    request = Net::HTTP::Get.new(uri)
+    store.headers("text/markdown").each { |k, v| request[k] = v }
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+    puts http.request(request).body
+
+  when "buy"
+    abort "buy needs a variant id — get one from `apparel-monster search`" if args.empty?
+    result = store.wallet([{ "variant_id" => args.first, "quantity" => 1 }])
+    if options[:text]
+      puts "Open this to pay:\n  #{result['wallet_url']}"
+    else
+      emit(result, options)
+    end
+
+  when "watch"
+    abort "watch needs a variant id and a target price" if args.length < 2
+    result = store.watch_price(args[0], args[1].to_f)
+    if options[:text]
+      puts result["status"] == "already_met" ? "Already #{result['current_price']} — below your #{result['target_price']} target." : "Watching. Poll: #{result['poll_url']}"
+    else
+      emit(result, options)
+    end
+
+  when "watch-status"
+    abort "watch-status needs a watch id" if args.empty?
+    emit(store.price_watch(args.first), options)
+
+  else
+    warn "Unknown command: #{command}\n\n"
+    puts USAGE
+    exit 1
+  end
+rescue ApparelMonster::Error => e
+  # The API's own message already names the missing fields and the next call;
+  # repeating them here would only make it longer.
+  warn "#{e.code || 'error'}: #{e.message}"
+  exit 1
+end

data/lib/apparel_monster/version.rb

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

data/lib/apparel_monster.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "apparel_monster/version"
+
+# Apparel Monster SDK: a dependency-free client for the agent commerce API.
+#
+# No API key appears in this file and that is not an omission. search, product,
+# cart, checkout, wallet, price-watch, batch and /ask are anonymous. Only order
+# history (+track+) needs OAuth. If something asks you for an Apparel Monster
+# API key, it is not us.
+#
+# Standard library only — net/http, no faraday, no httparty — so installing
+# this pulls in nothing and it works inside an agent sandbox with no gem
+# server.
+#
+#   store = ApparelMonster::Client.new
+#   hit   = store.search("denim shirt", limit: 1)["products"].first
+#   store.add_to_cart(hit["variants"].first["id"])
+module ApparelMonster
+  DEFAULT_BASE = "https://apparel.monster"
+  API = "/api/v1"
+
+  # Raised for any non-2xx response.
+  #
+  # The interesting attribute is +missing+: the API answers a bad call by
+  # naming every field it needed and did not get, what else each one is
+  # accepted as, and an example value. That detail is folded into the message
+  # too, because the common case is a model reading +message+ and nothing else.
+  class Error < StandardError
+    attr_reader :status, :code, :missing, :next_call, :contract, :body, :url
+
+    def initialize(status, body, url)
+      @status = status
+      @body = body || {}
+      @code = @body["error"]
+      @missing = @body["missing"]
+      @next_call = @body["next_call"]
+      @contract = @body["contract"]
+      @url = url
+      super(describe)
+    end
+
+    private
+
+    def describe
+      parts = [@body["message"] || "Request failed with #{@status}"]
+
+      if @missing.is_a?(Array) && @missing.any?
+        described = @missing.map do |field|
+          names = (field["accepts"] || [field["field"]]).join(" or ")
+          "#{field['field']} (send as #{names}, e.g. #{field['example'].inspect})"
+        end
+        parts << "Missing: #{described.join('; ')}"
+      end
+
+      parts << "Next call: #{JSON.generate(@next_call)}" if @next_call
+
+      parts.join(" ")
+    end
+  end
+
+  # A client for one shopping session.
+  #
+  # Two things this does that a raw Net::HTTP call does not: it carries the
+  # session id the API mints on the first search (forgetting it is the usual
+  # way an integration ends up with four empty carts and no order), and it
+  # identifies itself so the store can attribute the resulting order to this
+  # SDK rather than to "some script".
+  class Client
+    attr_accessor :session_id, :access_token
+    attr_reader :base_url
+
+    # @param base_url [String] override the origin
+    # @param session_id [String, nil] resume an existing agent session
+    # @param access_token [String, nil] OAuth token, only needed by #track
+    # @param timeout [Numeric] seconds
+    # @param cli [Boolean] identify as the CLI rather than the library
+    def initialize(base_url: DEFAULT_BASE, session_id: nil, access_token: nil, timeout: 30, cli: false)
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @session_id = session_id
+      @access_token = access_token
+      @timeout = timeout
+      @client = cli ? "ruby-cli" : "ruby-sdk"
+    end
+
+    # ---- catalog -------------------------------------------------------
+
+    # Search the catalog, or browse it when +query+ is nil.
+    #
+    # Mints the session id every later call needs, so this is almost always the
+    # first call you make.
+    def search(query = nil, category: nil, sort: nil, limit: nil, page: nil)
+      post("/search", "query" => query, "category" => category, "sort" => sort, "limit" => limit, "page" => page)
+    end
+
+    # Full detail for product ids or variant ids, mixed freely.
+    def product(ids)
+      post("/product", "ids" => Array(ids).map(&:to_s))
+    end
+
+    # ---- cart ----------------------------------------------------------
+
+    # Add a VARIANT — not a product. A product with five sizes has five
+    # variants and five prices, and adding a product id is the most common
+    # mistake made against this API.
+    def add_to_cart(variant_id, quantity = 1)
+      post("/cart", "action" => "add", "variant_id" => variant_id, "quantity" => quantity)
+    end
+
+    def update_cart_item(variant_id, quantity)
+      post("/cart", "action" => "update", "variant_id" => variant_id, "quantity" => quantity)
+    end
+
+    def remove_from_cart(variant_id)
+      post("/cart", "action" => "remove", "variant_id" => variant_id)
+    end
+
+    def view_cart
+      post("/cart", "action" => "view")
+    end
+
+    # Set the email and address; returns the cart with +shipping_options+
+    # priced against it.
+    #
+    # Required: email (once), line_one, city, postal_code. A missing one raises
+    # ApparelMonster::Error naming all of them at once, with the aliases each
+    # is accepted under.
+    def set_billing(address = {})
+      post("/cart", stringify(address).merge("action" => "billing"))
+    end
+
+    def set_shipping(shipping_id, address = {})
+      post("/cart", stringify(address).merge("action" => "shipping", "shipping_id" => shipping_id))
+    end
+
+    def apply_coupon(code)
+      post("/cart", "action" => "coupon", "coupon_code" => code)
+    end
+
+    # Attach a payment token. The field is +token+ — not +payment_token+, not
+    # +card_token+. Demo store on a test gateway: any non-empty string is
+    # accepted and nothing is ever charged.
+    def set_payment(token)
+      post("/cart", "action" => "payment", "token" => token)
+    end
+
+    # ---- checkout ------------------------------------------------------
+
+    # Place the order. Idempotent per session.
+    def checkout(callback_url: nil)
+      post("/checkout", "callback_url" => callback_url)
+    end
+
+    # A hosted Apple Pay / Google Pay link, for when a human can tap.
+    #
+    # The shortcut past the whole cart flow: hand it variant ids and it returns
+    # a URL that collects the shopper's email, address and card on their own
+    # device, so your agent never handles any of them.
+    def wallet(items)
+      normalised = Array(items).map do |item|
+        item.is_a?(Hash) ? stringify(item) : { "variant_id" => item.to_s, "quantity" => 1 }
+      end
+      post("/wallet", "items" => normalised)
+    end
+
+    # Order status and shipments. The only call that needs OAuth.
+    def track(params = {})
+      post("/track", stringify(params))
+    end
+
+    # ---- price watch ---------------------------------------------------
+
+    # Be told when a variant reaches a target price. Answers 202 with a
+    # +poll_url+ and a +job_id+; a target at or above today's price is not
+    # queued at all and comes back +already_met+.
+    def watch_price(variant_id, target_price, callback_url: nil)
+      post("/price-watch",
+           "variant_id" => variant_id, "target_price" => target_price, "callback_url" => callback_url)
+    end
+
+    def price_watch(watch_id)
+      request(Net::HTTP::Get, "#{@base_url}#{API}/price-watch/#{URI.encode_www_form_component(watch_id)}")
+    end
+
+    # ---- batch ---------------------------------------------------------
+
+    # Up to 10 operations in one round trip, executed in order. Each result
+    # carries its own status: the batch answers 200 whenever it ran, even if
+    # everything inside it failed.
+    def batch(operations, stop_on_error: false)
+      raise ArgumentError, "batch takes at most 10 operations" if operations.length > 10
+
+      post("/batch", "operations" => operations, "stop_on_error" => stop_on_error)
+    end
+
+    # ---- natural language ----------------------------------------------
+
+    # Ask in plain language (NLWeb); returns schema.org Product items. There is
+    # no model behind it — it runs the same catalog search — which is why it
+    # returns nothing rather than inventing a product.
+    def ask(query, limit: nil)
+      params = { "query" => query }
+      params["limit"] = limit if limit
+      request(Net::HTTP::Get, "#{@base_url}/ask?#{URI.encode_www_form(params)}")
+    end
+
+    # The same question, streamed: yields [event, data] as +start+, one
+    # +result+ per hit, then +complete+.
+    def ask_stream(query, limit: nil)
+      return enum_for(:ask_stream, query, limit: limit) unless block_given?
+
+      params = { "query" => query, "streaming" => "true" }
+      params["limit"] = limit if limit
+      uri = URI("#{@base_url}/ask?#{URI.encode_www_form(params)}")
+
+      http(uri).request(get_request(uri, "text/event-stream")) do |response|
+        event = "message"
+        data = +""
+        response.read_body do |chunk|
+          chunk.each_line do |raw|
+            line = raw.chomp
+            if line.start_with?("event:")
+              event = line[6..].strip
+            elsif line.start_with?("data:")
+              data << line[5..].strip
+            elsif line.empty?
+              # A blank line terminates an SSE frame; anything before one is a
+              # partial frame and must not be yielded.
+              unless data.empty?
+                begin
+                  yield [event, JSON.parse(data)]
+                rescue JSON::ParserError
+                  nil
+                end
+              end
+              event = "message"
+              data = +""
+            end
+          end
+        end
+      end
+    end
+
+    # ---- plumbing ------------------------------------------------------
+
+    def headers(accept = "application/json")
+      suffix = @client == "ruby-cli" ? "-cli" : ""
+      result = {
+        "Content-Type" => "application/json",
+        "Accept" => accept,
+        # Two spellings of one fact: the User-Agent is what the edge sees
+        # without the application being involved, X-Agent-Client is what
+        # survives an environment that rewrites User-Agent.
+        "User-Agent" => "apparel-monster-ruby#{suffix}/#{VERSION} (+https://github.com/mluggy/apparel-monster-dev)",
+        "X-Agent-Client" => "#{@client}/#{VERSION}"
+      }
+      result["Authorization"] = "Bearer #{@access_token}" if @access_token
+      result
+    end
+
+    private
+
+    def stringify(hash)
+      (hash || {}).each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+
+    def with_session(body)
+      return body unless @session_id
+
+      { "session" => { "id" => @session_id } }.merge(body)
+    end
+
+    def post(path, body = {})
+      payload = with_session(body.reject { |_k, v| v.nil? })
+      request(Net::HTTP::Post, "#{@base_url}#{API}#{path}", JSON.generate(payload))
+    end
+
+    def http(uri)
+      client = Net::HTTP.new(uri.host, uri.port)
+      client.use_ssl = uri.scheme == "https"
+      client.open_timeout = @timeout
+      client.read_timeout = @timeout
+      client
+    end
+
+    def get_request(uri, accept)
+      Net::HTTP::Get.new(uri).tap { |r| headers(accept).each { |k, v| r[k] = v } }
+    end
+
+    def request(verb, url, body = nil)
+      uri = URI(url)
+      req = verb.new(uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body
+
+      response = http(uri).request(req)
+      parsed = begin
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+
+      raise Error.new(response.code.to_i, parsed, url) unless response.is_a?(Net::HTTPSuccess)
+
+      # The session arrives on the first search and is reused from then on.
+      if parsed.is_a?(Hash) && parsed.dig("session", "id")
+        @session_id = parsed["session"]["id"]
+      end
+
+      parsed
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: apparel-monster
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Michael Lugassy
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-09-16 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Search the catalog, build a cart, place an order, mint an Apple Pay / Google Pay
+  link, watch a price, or ask in natural language. No authentication: every call
+  except order history is anonymous. Standard library only, no runtime dependencies.
+  apparel.monster is a demo storefront — orders are placed against a test gateway
+  and nothing is ever fulfilled.
+email: 
+executables:
+- apparel-monster
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- exe/apparel-monster
+- lib/apparel_monster.rb
+- lib/apparel_monster/version.rb
+homepage: https://apparel.monster/developers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://apparel.monster/developers
+  source_code_uri: https://github.com/mluggy/apparel-monster-dev
+  bug_tracker_uri: https://github.com/mluggy/apparel-monster-dev/issues
+  documentation_uri: https://apparel.monster/developers
+  rubygems_mfa_required: 'false'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+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: SDK and CLI for the Apparel Monster agent commerce API.
+test_files: []