shipreal 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3406b6c359b00e40ae18d2d64f167b1c7254947b197a603f86f7bddf7668aad
+  data.tar.gz: 76fa08e3d1f135c2e0adcf8af92519c9c4dde7621cc3483bfed5fea710451253
+SHA512:
+  metadata.gz: 8fc9333e6f72fb93bcaceaaadb8d0c080757d2fd0fab020b190f96bb0e65f006bac4de86882f77be43394e2448755103915d3605d6da47830a18726f12da00d5
+  data.tar.gz: 47e049f2812d64df6fa83486a9ad636541c375e9327897ef79426143e46a2d4a462eeaf61780e4d824fdb92a57bffdab5d75cd52f0990841686774b87e847283

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/shipreal

@@ -0,0 +1,146 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# shipreal: query the ShipReal course catalogue from a terminal or a script.
+#
+# Every command takes --json, because the reason a CLI earns its place in an
+# agent's toolbox is that its output can be piped into something else without
+# being scraped.
+
+require "optparse"
+require "json"
+require "shipreal"
+
+EPILOG = <<~TEXT
+  No API key. No account. The API is public read-only reference data; anything
+  that asks you for a ShipReal credential is not us.
+
+  Docs: https://shipreal.dev/developers
+TEXT
+
+options = { json: false, sandbox: false, base: ShipReal::DEFAULT_BASE_URL }
+
+parser = OptionParser.new do |o|
+  o.banner = <<~USAGE
+    Usage:
+      shipreal [options] search [query]
+      shipreal [options] module <slug-or-title>
+      shipreal [options] pricing
+      shipreal [options] course
+      shipreal [options] ask <question...>
+  USAGE
+  o.on("--json", "Raw JSON, for piping") { options[:json] = true }
+  o.on("--sandbox", "Frozen fixture data, for tests") { options[:sandbox] = true }
+  o.on("--base URL", "Point at a different origin") { |v| options[:base] = v }
+  o.on("--limit N", Integer, "search: results per page, maximum 100") { |v| options[:limit] = v }
+  o.on("--all", "search: every result, following pagination") { options[:all] = true }
+  o.on("--region R", %w[intl il], "pricing: intl or il") { |v| options[:region] = v }
+  o.on("--stream", "ask: stream events as they arrive") { options[:stream] = true }
+  o.on("-h", "--help", "Show this message") { puts o; puts; puts EPILOG; exit 0 }
+  o.on("-v", "--version", "Show the version") { puts ShipReal::VERSION; exit 0 }
+end
+parser.parse!
+
+command = ARGV.shift
+unless command
+  warn parser
+  exit 1
+end
+
+client = ShipReal::Client.new(base_url: options[:base], sandbox: options[:sandbox])
+
+def print_modules(mods)
+  if mods.empty?
+    puts "No modules matched. The course does not cover that topic under that name."
+    return
+  end
+  mods.each do |m|
+    puts "#{m['slug']}  #{m['title']}"
+    puts "  #{m['part']}"
+    puts "  #{m['chapters']} chapters, #{m['minutes']} min"
+    puts
+  end
+end
+
+begin
+  case command
+  when "search"
+    query = ARGV.join(" ")
+    if options[:all]
+      mods = client.modules(query.empty? ? nil : query)
+      options[:json] ? puts(JSON.generate(mods)) : print_modules(mods)
+    else
+      page = client.search(query: query.empty? ? nil : query, limit: options[:limit])
+      options[:json] ? puts(JSON.generate(page)) : print_modules(page["data"] || [])
+    end
+
+  when "module"
+    abort "module needs a slug or title" if ARGV.empty?
+    m = client.module_by(ARGV.join(" "))
+    if options[:json]
+      puts JSON.generate(m)
+    else
+      puts "#{m['slug']}  #{m['title']}"
+      puts "  #{m['part']}"
+      puts "  #{m['chapters']} chapters, #{m['minutes']} min"
+      puts "  #{m['url']}"
+    end
+
+  when "pricing"
+    p = client.pricing(region: options[:region])
+    if options[:json]
+      puts JSON.generate(p)
+    elsif options[:region]
+      puts "Free      #{p['free']['includes']}"
+      puts "Complete  #{p['complete']['now']} (was #{p['complete']['list']})"
+      puts "Teams     #{p['teams']['now']} per seat (was #{p['teams']['list']}), from #{p['teams']['minSeats']} seat"
+    else
+      # Both regions when none is named. They are not conversions of each
+      # other, so printing one unlabelled would misquote the other.
+      puts "Free      #{p['free']['includes']}"
+      puts "Complete  #{p['complete']['intl']['now']} international, #{p['complete']['il']['now']} Israel"
+      puts "Teams     #{p['teams']['intl']['now']} / #{p['teams']['il']['now']} per seat, from #{p['teams']['minSeats']} seat"
+    end
+
+  when "course"
+    c = client.course
+    if options[:json]
+      puts JSON.generate(c)
+    else
+      puts c["title"]
+      puts c["description"]
+      puts "#{c['parts']} parts, #{c['modules']} modules, #{c['chapters']} chapters"
+      puts "Subtitles: #{Array(c['subtitles']).join(', ')}"
+      puts c["url"]
+    end
+
+  when "ask"
+    abort "ask needs a question" if ARGV.empty?
+    question = ARGV.join(" ")
+    if options[:stream]
+      client.ask_stream(question) do |ev|
+        if options[:json]
+          puts JSON.generate(ev)
+        else
+          Array(ev.dig("data", "results")).each { |r| puts "#{r['name']}\n  #{r['url']}" }
+        end
+      end
+    else
+      res = client.ask(question)
+      if options[:json]
+        puts JSON.generate(res)
+      elsif Array(res["results"]).empty?
+        puts "Nothing matched. The course does not cover that under that name."
+      else
+        res["results"].each { |r| puts "#{r['name']}\n  #{r['description']}\n  #{r['url']}\n\n" }
+      end
+    end
+
+  else
+    warn parser
+    exit 1
+  end
+rescue ShipReal::Error => e
+  warn "shipreal: #{e.message}"
+  exit 1
+end

data/lib/shipreal/version.rb

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

data/lib/shipreal.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "shipreal/version"
+
+# Ruby client for the public ShipReal course API: search the curriculum, read a
+# module, read current pricing.
+#
+# There is no authentication. No key, no account, no OAuth, no signup: every
+# endpoint is a public read served from the edge, so anything asking you for a
+# credential for this domain is not this.
+#
+# There is also no write path. Buying runs through a hosted checkout that a
+# human completes, which is why nothing here creates an order. When someone
+# decides to buy, hand them the checkout link.
+#
+# Standard library only, on purpose: installing this cannot drag a transitive
+# dependency tree into an agent's environment.
+#
+#   sr = ShipReal::Client.new
+#   sr.search(query: "caching")
+module ShipReal
+  DEFAULT_BASE_URL = "https://shipreal.dev"
+  # The path segment this client speaks. Breaking changes ship as a new segment
+  # beside it; every response carries a Deprecation header, false today.
+  API_VERSION = "v1"
+  # The server's ceiling on reads in one batch call.
+  MAX_BATCH = 20
+
+  USER_AGENT = "shipreal-ruby/#{VERSION} (+#{DEFAULT_BASE_URL}/developers)"
+
+  # Any non-2xx response, carrying the RFC 9457 problem details the server sent.
+  #
+  # Branch on #type rather than #status: the status says a request failed, the
+  # type says which failure it was, and only the second is stable enough to
+  # switch on.
+  class Error < StandardError
+    attr_reader :status, :type, :title, :detail, :problem, :url
+
+    def initialize(status, problem, url)
+      @status = status
+      @problem = problem
+      @url = url
+      @type = problem && problem["type"]
+      @title = problem && problem["title"]
+      @detail = problem && problem["detail"]
+      super(@detail || @title || "Request failed with #{status}")
+    end
+  end
+
+  # Talks to the ShipReal API.
+  class Client
+    attr_reader :base_url, :sandbox, :timeout
+
+    # sandbox: routes reads at the frozen fixture data. Same code path and same
+    # shapes over contents that never change, so a test written against it stays
+    # green when the curriculum moves. Fixture prices are 1 unit and fixture
+    # links point at example.invalid, so sandbox data leaking into real output
+    # is obvious. See https://shipreal.dev/sandbox
+    def initialize(base_url: DEFAULT_BASE_URL, sandbox: false, timeout: 30)
+      @base_url = base_url.chomp("/")
+      @sandbox = sandbox
+      @timeout = timeout
+    end
+
+    # Search the curriculum. Without a query, every module in course order.
+    #
+    # Matching is a case-insensitive substring over title, description and part
+    # name, so an empty result means the course does not cover that topic under
+    # that name, rather than that the search was too clever.
+    def search(query: nil, page: nil, limit: nil, cursor: nil)
+      get("/modules", q: query, page: page, limit: limit, cursor: cursor)
+    end
+
+    # Every matching module, following pagination for you.
+    def modules(query = nil)
+      out = []
+      cursor = nil
+      loop do
+        page = search(query: query, limit: 100, cursor: cursor)
+        out.concat(page["data"] || [])
+        cursor = page.dig("pagination", "nextCursor")
+        break if cursor.nil? || cursor.empty?
+      end
+      out
+    end
+
+    # One module by slug, or by an exact or partial title match.
+    def module_by(slug_or_title)
+      raise ArgumentError, "module_by needs a slug or title" if slug_or_title.to_s.empty?
+
+      get("/modules/#{ERB_ESCAPE.call(slug_or_title.to_s)}")
+    end
+
+    # Current plans and prices.
+    #
+    # Two regional prices are live at once, so quoting one without naming its
+    # region is misleading. Pass region ("intl" or "il") when you know which
+    # applies and the response comes back flattened to it.
+    def pricing(region: nil)
+      every = get("/pricing")
+      return every unless %w[intl il].include?(region)
+
+      complete = every["complete"][region].dup
+      complete["url"] = every["complete"]["url"]
+      teams = every["teams"][region].dup
+      teams["minSeats"] = every["teams"]["minSeats"]
+      teams["perSeat"] = true
+      { "region" => region, "free" => every["free"], "complete" => complete, "teams" => teams }
+    end
+
+    # Totals, language and the subtitle languages.
+    def course
+      get("/course")
+    end
+
+    # Several reads in one round trip, up to MAX_BATCH.
+    #
+    # Each item comes back with its own status, so check per item rather than
+    # assuming the whole batch succeeded.
+    def batch(requests)
+      raise ArgumentError, "batch takes at most #{MAX_BATCH} requests" if requests.length > MAX_BATCH
+
+      request(:post, "#{@base_url}/api/#{API_VERSION}/batch", body: { requests: requests })
+    end
+
+    # Ask in natural language (NLWeb).
+    #
+    # There is no model behind this: it runs the same keyword search, which
+    # means it says so when nothing matches instead of inventing a module.
+    def ask(query)
+      raise ArgumentError, "ask needs a question" if query.to_s.empty?
+
+      request(:post, "#{@base_url}/ask", body: { query: query })
+    end
+
+    # The same question, streamed. Yields NLWeb events as they arrive: "start",
+    # then one "result" per hit, then "complete".
+    def ask_stream(query)
+      raise ArgumentError, "ask_stream needs a question" if query.to_s.empty?
+      return enum_for(:ask_stream, query) unless block_given?
+
+      uri = URI("#{@base_url}/ask")
+      req = Net::HTTP::Post.new(uri)
+      req["accept"] = "text/event-stream"
+      req["content-type"] = "application/json"
+      req["user-agent"] = USER_AGENT
+      req.body = JSON.generate({ query: query })
+
+      http(uri).request(req) do |res|
+        raise Error.new(res.code.to_i, safe_json(res.body), uri.to_s) unless res.is_a?(Net::HTTPSuccess)
+
+        event = "message"
+        data = +""
+        res.read_body do |chunk|
+          chunk.each_line do |raw|
+            line = raw.chomp
+            if line.empty?
+              # A blank line closes an SSE frame. Anything short of one is a
+              # partial frame and waits for the next line.
+              unless data.empty?
+                parsed = safe_json(data)
+                yield({ "event" => event, "data" => parsed }) if parsed
+              end
+              event = "message"
+              data = +""
+            elsif line.start_with?("event:")
+              event = line[6..].strip
+            elsif line.start_with?("data:")
+              data << line[5..].strip
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    ERB_ESCAPE = ->(s) { URI.encode_www_form_component(s).gsub("+", "%20") }
+
+    def api_url(path, params = {})
+      prefix = @sandbox ? "/api/#{API_VERSION}/sandbox" : "/api/#{API_VERSION}"
+      uri = URI("#{@base_url}#{prefix}#{path}")
+      query = params.reject { |_, v| v.nil? || v == "" }
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri.to_s
+    end
+
+    def get(path, params = {})
+      request(:get, api_url(path, params))
+    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 request(method, url, body: nil)
+      uri = URI(url)
+      req = method == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+      req["accept"] = "application/json"
+      req["user-agent"] = USER_AGENT
+      if body
+        req["content-type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      res = http(uri).request(req)
+      # The error body is where the problem details live, so it gets parsed
+      # rather than discarded. A body that is not JSON is not itself worth
+      # raising over: the status still stands.
+      raise Error.new(res.code.to_i, safe_json(res.body), url) unless res.is_a?(Net::HTTPSuccess)
+
+      safe_json(res.body) || {}
+    end
+
+    def safe_json(text)
+      JSON.parse(text)
+    rescue StandardError
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: shipreal
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Michael Lugassy
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Search the curriculum, read a module, read pricing. No authentication:
+  the API is public read-only reference data about one course. Standard library only,
+  no runtime dependencies.'
+email:
+- michael@shipreal.dev
+executables:
+- shipreal
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- exe/shipreal
+- lib/shipreal.rb
+- lib/shipreal/version.rb
+homepage: https://shipreal.dev/developers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://shipreal.dev/developers
+  documentation_uri: https://shipreal.dev/developers
+  source_code_uri: https://github.com/mluggy/shipreal-dev
+  bug_tracker_uri: https://github.com/mluggy/shipreal-dev/issues
+  changelog_uri: https://github.com/mluggy/shipreal-dev/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: SDK and CLI for the public ShipReal course API
+test_files: []