kodeco 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a8113bf48c09c6754ee161ccd1568779c99d1d873f943b31cb4c4901e9bd474
+  data.tar.gz: f3ec99a38bbb68e90fc594d7702d1ddad0b3a916c3768d47e706b328f960ca07
+SHA512:
+  metadata.gz: 4a2ca478260ec6f8475be66981d8ae253dd6da00b2c3f23b249039332da5b355a18dc1783f99cd259e78264fd0fe898aabd5ac07f1a4ee8eef5631c63c042f27
+  data.tar.gz: b36b0bfb1eb73c2db436102551a85736a7825ab18803641177a1b0d2a061ad784a75c38d3e9d7a406bfec916e972134f6b82a1bc60d44781c3bbbc49cdc6f315

data/README.md

@@ -0,0 +1,90 @@
+# periscope
+
+The `kodeco` command-line tool for Kodeco's API v2, for developers and agents.
+
+## Install
+
+Requires Ruby 3.3 or later and has no runtime dependencies.
+
+```sh
+gem install kodeco
+```
+
+## Commands
+
+```sh
+kodeco login [--scopes "a b"] [--no-browser]
+kodeco logout
+kodeco whoami [--app guardpost|kerching|carolus]
+kodeco user <email|rwuuid>
+kodeco orders <email|rwuuid> [--page N]
+kodeco order <id>
+kodeco subscription <email|rwuuid>
+kodeco problems [--kind overdue|stuck_in_preauth|invoice_overdue|expiry_missed] [--page N]
+kodeco flags --app guardpost|kerching|carolus
+```
+
+`user` shows guardpost's customer summary, with kerching's and carolus's
+sections. A section that couldn't be fetched is marked `!!` and the command
+exits 5 after printing the rest. `orders`, `order`, `subscription` and
+`problems` read kerching and need the `orders:read` scope; `flags` needs
+`flags:read`. With `--json`, commands print the response's `data`, plus `meta`
+for lists.
+
+`login` uses guardpost's device-code flow: it prints a code and a link to
+approve it, and opens the link in a browser when run in a terminal. The
+default scopes are `users:read support:read orders:read learning:read
+flags:read`. If you lack a grant for one of them, approval fails; run
+`kodeco login --scopes "..."` and leave it out.
+
+`logout` deletes the local credentials. guardpost has no revoke endpoint, so
+the server session lasts up to 7 days unless an admin revokes it.
+
+Every command takes:
+
+* `--json`: stdout is exactly one JSON document, and errors go to stderr as
+  `{"error": {"code": ..., "message": ...}}`.
+* `--debug`: logs each request's method, URL and status to stderr. Tokens are
+  never printed or logged.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | OK |
+| 1 | Error |
+| 2 | Usage error |
+| 3 | Not logged in, or authentication failed |
+| 4 | Not found |
+| 5 | An upstream app is unavailable |
+
+## Configuration
+
+Production is the default. To point an app elsewhere, set
+`KODECO_GUARDPOST_URL`, `KODECO_KERCHING_URL` or `KODECO_CAROLUS_URL`.
+
+Credentials live in `${XDG_CONFIG_HOME:-~/.config}/kodeco/credentials.json`
+(directory 0700, file 0600), with one entry per guardpost URL, so logging in
+to another guardpost never replaces your production login. The CLI refuses to
+read the file if its permissions are wider than 0600.
+
+Access tokens are refreshed automatically when they're within a minute of
+expiring. Refreshes are serialised with a lock file, so concurrent `kodeco`
+processes share one refresh rather than revoking each other's session.
+
+## Releasing
+
+The gem is published to rubygems.org as `kodeco`, with Trusted Publishing, so
+no API key is stored anywhere.
+
+1. Bump `Periscope::VERSION` in `lib/periscope/version.rb`.
+2. Merge to `trunk`.
+3. Run the Release workflow by hand on `trunk`. It runs the tests, tags
+   `v<version>` and publishes the gem.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake   # tests and RuboCop
+```

data/exe/kodeco

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "periscope"
+
+exit Periscope::CLI.new(ARGV).run

data/lib/kodeco.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# The gem is published as kodeco; its code lives under Periscope.
+require_relative "periscope"

data/lib/periscope/cli.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "rbconfig"
+
+module Periscope
+  class CLI
+    include Commands::User
+    include Commands::Kerching
+    include Commands::Flags
+
+    USAGE = <<~TEXT
+      Usage: kodeco <command> [options]
+
+      Commands:
+        login [--scopes "a b"] [--no-browser]  Log in with guardpost's device-code flow
+        logout                                 Delete the local credentials
+        whoami [--app guardpost|kerching|carolus]
+                                               Show who an app takes you to be
+        user <email|rwuuid>                    Show guardpost's customer summary
+        orders <email|rwuuid> [--page N]       List a user's kerching orders
+        order <id>                             Show one kerching order
+        subscription <email|rwuuid>            Show a user's kerching subscription
+        problems [--kind KIND] [--page N]      List kerching orders that need attention
+        flags --app guardpost|kerching|carolus Show an app's feature flags
+
+      Every command takes --json (one JSON document on stdout, errors as JSON
+      on stderr) and --debug (logs each request's method, URL and status).
+    TEXT
+
+    COMMANDS = %w[login logout whoami user orders order subscription problems flags].freeze
+    LOGOUT_NOTE = "guardpost has no revoke endpoint, so the server session lasts up to 7 days " \
+                  "unless an admin revokes it."
+
+    def initialize(argv, env: ENV, stdout: $stdout, stderr: $stderr, login_options: {})
+      @argv = argv.dup
+      @env = env
+      @stdout = stdout
+      @stderr = stderr
+      @login_options = login_options
+      @json = @argv.include?("--json")
+      @debug = @argv.include?("--debug")
+    end
+
+    def run
+      command = @argv.shift
+      return usage(command.nil? ? 2 : 0) if command.nil? || %w[help --help -h].include?(command)
+      raise UsageError, "Unknown command #{command}. Run kodeco --help." unless COMMANDS.include?(command)
+
+      send(:"cmd_#{command}")
+      0
+    rescue OptionParser::ParseError => e
+      fail_with(UsageError.new(e.message))
+    rescue Error => e
+      fail_with(e)
+    rescue Interrupt
+      fail_with(Error.new("Interrupted"))
+    end
+
+    private
+
+    def cmd_login
+      opts = parse_options do |parser, o|
+        parser.on("--scopes SCOPES") { |v| o[:scopes] = v }
+        parser.on("--[no-]browser") { |v| o[:browser] = v }
+      end
+      opener = method(:open_browser) if @stdout.tty? && opts.fetch(:browser, true)
+      login = Login.new(config: config, store: store, http: http, out: @json ? @stderr : @stdout,
+                        opener: opener, **@login_options)
+      credentials = login.call(opts[:scopes] || Login::DEFAULT_SCOPES)
+      result = { "logged_in" => true, "scope" => credentials["scope"], "apps" => credentials["access_tokens"].keys }
+      emit(result) { "Logged in to #{config.url('guardpost')} with scope: #{credentials['scope']}" }
+    end
+
+    def cmd_logout
+      parse_options
+      deleted = store.with_lock { store.delete }
+      emit({ "logged_out" => true, "had_credentials" => !deleted.nil?, "note" => LOGOUT_NOTE }) do
+        deleted ? "Logged out locally. #{LOGOUT_NOTE}" : "Not logged in; there was nothing to delete."
+      end
+    end
+
+    def cmd_whoami
+      opts = parse_options { |parser, o| parser.on("--app APP", Config::APPS) { |v| o[:app] = v } }
+      data = client.get(opts[:app] || "guardpost", "/api/v2/whoami")["data"] || {}
+      emit(data) { "type:   #{data['type']}\nid:     #{data['id']}\nscopes: #{Array(data['scopes']).join(' ')}" }
+    end
+
+    # Parses the remaining arguments and returns the options; commands that
+    # take positional arguments pass positional: n.
+    def parse_options(positional: 0)
+      opts = {}
+      parser = OptionParser.new
+      parser.on("--json")
+      parser.on("--debug")
+      yield parser, opts if block_given?
+      rest = parser.parse(@argv)
+      raise UsageError, "Expected #{positional} argument(s), got #{rest.size}" unless rest.size == positional
+
+      opts[:args] = rest
+      opts
+    end
+
+    def emit(data)
+      @stdout.puts(@json ? JSON.generate(data) : yield)
+    end
+
+    def usage(status)
+      (status.zero? ? @stdout : @stderr).puts(USAGE)
+      status
+    end
+
+    def fail_with(error)
+      if @json
+        @stderr.puts(JSON.generate(error: { code: error.code, message: error.message }))
+      else
+        @stderr.puts("kodeco: #{error.message}")
+      end
+      error.exit_code
+    end
+
+    def open_browser(url)
+      command = RbConfig::CONFIG["host_os"].include?("darwin") ? "open" : "xdg-open"
+      system(command, url, out: File::NULL, err: File::NULL)
+    end
+
+    def config = @config ||= Config.new(@env)
+    def http = @http ||= Http.new(debug: @debug, log: @stderr)
+    def store = @store ||= CredentialStore.new(config.config_dir, config.url("guardpost"))
+    def session = @session ||= Session.new(config: config, store: store, http: http)
+    def client = @client ||= Client.new(config: config, session: session, http: http)
+  end
+end

data/lib/periscope/client.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Periscope
+  # Authenticated API v2 calls. Each app gets only its own token.
+  class Client
+    def initialize(config:, session:, http:)
+      @config = config
+      @session = session
+      @http = http
+    end
+
+    # scope names the scope the endpoint needs, so a 403 can say which is missing.
+    def get(app, path, scope: nil)
+      handle(app, scope, @http.get(url(app, path), auth(app)))
+    end
+
+    def post_json(app, path, payload, scope: nil)
+      handle(app, scope, @http.post_json(url(app, path), payload, auth(app)))
+    end
+
+    private
+
+    def url(app, path) = "#{@config.url(app)}#{path}"
+
+    def auth(app) = { "Authorization" => "Bearer #{@session.token_for(app)}" }
+
+    def handle(app, scope, res)
+      return res.body if res.ok?
+
+      message = res.error_message || "HTTP #{res.status}"
+      case res.status
+      when 401 then raise AuthError.new("#{app} rejected the token: #{message}. Run kodeco login.", code: "auth_failed")
+      when 403 then raise AuthError.new(forbidden(app, scope, message), code: "forbidden")
+      when 404 then raise NotFoundError, message
+      when 500.. then raise UnavailableError, "#{app} unavailable (#{message})"
+      end
+      raise Error.new(message, code: res.error_code || "error")
+    end
+
+    def forbidden(app, scope, message)
+      return "#{app} refused: #{message}" unless scope
+
+      "#{app} refused: #{message}. This needs the #{scope} scope; run kodeco login --scopes with it included."
+    end
+  end
+end

data/lib/periscope/commands/flags.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Periscope
+  module Commands
+    # kodeco flags --app APP
+    module Flags
+      private
+
+      def cmd_flags
+        opts = parse_options { |parser, o| parser.on("--app APP", Config::APPS) { |v| o[:app] = v } }
+        raise UsageError, "flags needs --app #{Config::APPS.join('|')}" unless opts[:app]
+
+        flags = client.get(opts[:app], "/api/v2/flags", scope: "flags:read")["data"] || {}
+        emit(flags) { flags.map { |source, values| flag_source(source, values) }.join("\n\n") }
+      end
+
+      def flag_source(source, values)
+        lines = values.map do |name, value|
+          source == "flipper" ? [name, flipper_state(value)] : [name, Format.value(value)]
+        end
+        "#{source}\n#{Format.table(%w[NAME VALUE], lines).gsub(/^/, '  ')}"
+      end
+
+      def flipper_state(feature)
+        return feature["state"] unless feature["state"] == "conditional"
+
+        gates = []
+        gates << "groups: #{feature['groups'].join(', ')}" if feature["groups"]&.any?
+        gates << "#{feature['percentage_of_actors']}% of actors" if feature["percentage_of_actors"].to_f.positive?
+        gates << "#{feature['percentage_of_time']}% of the time" if feature["percentage_of_time"].to_f.positive?
+        gates << "#{feature['actors_count']} actors" if feature["actors_count"].to_i.positive?
+        "conditional (#{gates.join('; ')})"
+      end
+    end
+  end
+end

data/lib/periscope/commands/kerching.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Periscope
+  module Commands
+    # kodeco orders, order, subscription and problems: kerching's read endpoints.
+    module Kerching
+      PROBLEM_KINDS = %w[overdue stuck_in_preauth invoice_overdue expiry_missed].freeze
+
+      private
+
+      def cmd_orders
+        opts = parse_options(positional: 1) { |parser, o| page_option(parser, o) }
+        rwuuid = UserLookup.rwuuid(client, opts[:args].first)
+        body = kerching("/api/v2/users/#{rwuuid}/orders#{query(page: opts[:page])}")
+        rows = body["data"].map do |o|
+          [o["id"], Format.date(o["created_at"]), o["state"], Format.products(o["products"]),
+           Format.date(o["end_date"])]
+        end
+        emit(body.slice("data", "meta")) { "#{Format.table(%w[ID CREATED STATE PRODUCTS ENDS], rows)}\n#{pages(body)}" }
+      end
+
+      def cmd_order
+        opts = parse_options(positional: 1)
+        id = opts[:args].first
+        raise UsageError, "Order id must be a number" unless id.match?(/\A\d+\z/)
+
+        order = kerching("/api/v2/orders/#{id}")["data"]
+        emit(order) { order_text(order) }
+      end
+
+      def cmd_subscription
+        opts = parse_options(positional: 1)
+        rwuuid = UserLookup.rwuuid(client, opts[:args].first)
+        sub = kerching("/api/v2/users/#{rwuuid}/subscription")["data"]
+        emit(sub) { subscription_text(sub) }
+      end
+
+      def cmd_problems
+        opts = parse_options do |parser, o|
+          page_option(parser, o)
+          parser.on("--kind KIND", PROBLEM_KINDS) { |v| o[:kind] = v }
+        end
+        body = kerching("/api/v2/orders/problems#{query(kind: opts[:kind], page: opts[:page])}")
+        counts = (body.dig("meta", "counts") || {}).map { |kind, n| "#{kind}: #{n}" }.join("  ")
+        rows = Format.table(%w[KIND SINCE ORDER RWUUID PRODUCTS HELD], body["data"].map { |o| problem_row(o) })
+        emit(body.slice("data", "meta")) { "#{counts}\n\n#{rows}\n#{pages(body)}" }
+      end
+
+      def problem_row(order)
+        [order["kind"], Format.date(order["since"]), order["id"], order.dig("user", "rwuuid"),
+         Format.products(order["products"]), ("held" if order["held"])]
+      end
+
+      def pages(body) = Format.pages(body["meta"] || {})
+
+      def kerching(path) = client.get("kerching", path, scope: "orders:read")
+
+      def page_option(parser, opts)
+        parser.on("--page N", Integer) do |n|
+          raise UsageError, "--page must be 1 or more" if n < 1
+
+          opts[:page] = n
+        end
+      end
+
+      def query(params)
+        params = params.compact
+        params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+      end
+
+      def order_text(order)
+        history = order["history"].map { |h| [h["created_at"], h["to_state"]] }
+        transactions = order["transactions"].map do |t|
+          [t["id"], t["created_at"], t["currency"], t["sale_gross"], t["earnings"]]
+        end
+        [order_header(order), "", "History", Format.table(%w[AT STATE], history),
+         "", "Transactions", Format.table(%w[ID AT CURRENCY GROSS EARNINGS], transactions),
+         "", "Invoice", invoice_text(order["invoice"])].join("\n")
+      end
+
+      def order_header(order)
+        ["Order ##{order['id']} (#{order['state']}#{', held' if order['held']})",
+         "  Created:  #{order['created_at']}", "  Ends:     #{order['end_date'] || '-'}",
+         "  Provider: #{order['external_provider']}, #{order['payment_method']}",
+         "  Price:    #{order['original_price'] || '-'}#{" (coupon #{order['coupon']})" if order['coupon']}",
+         "  User:     #{order.dig('user', 'rwuuid') || '-'}",
+         "  Products: #{Format.products(order['products'])}"].join("\n")
+      end
+
+      def invoice_text(invoice)
+        return "(none)" unless invoice
+
+        "##{invoice['id']} #{invoice['state']}, #{invoice['amount']} #{invoice['currency']}, " \
+          "PO #{invoice['purchase_order_number'] || '-'}, reconciled #{invoice['reconciled_at'] || 'no'}"
+      end
+
+      def subscription_text(sub)
+        history = sub["history"].map { |h| [h["created_at"], h["action"], h["from_sku"], h["to_sku"]] }
+        cancellations = sub["cancellations"].map { |c| [c["created_at"], c["survey_outcome"], c["cancellation"]] }
+        ["Status: #{sub['status']}", "Order:  #{subscription_order(sub['order'])}",
+         "", "History", Format.table(%w[AT ACTION FROM TO], history),
+         "", "Cancellations", Format.table(%w[AT OUTCOME REASON], cancellations)].join("\n")
+      end
+
+      def subscription_order(order)
+        return "none" unless order
+
+        product = order["product"] || {}
+        "##{order['id']} #{order['state']}, #{product['name'] || '-'} (#{product['billing_interval'] || '-'}), " \
+          "ends #{order['end_date'] || '-'}#{', via team' if order['via_team']}"
+      end
+    end
+  end
+end

data/lib/periscope/commands/user.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Periscope
+  module Commands
+    # kodeco user <email|rwuuid>
+    module User
+      private
+
+      def cmd_user
+        opts = parse_options(positional: 1)
+        rwuuid = UserLookup.rwuuid(client, opts[:args].first)
+        data = client.get("guardpost", "/api/v2/users/#{rwuuid}/summary", scope: "support:read")["data"] || {}
+        summary = UserSummary.new(data)
+        emit(data) { summary.to_s }
+        down = summary.unavailable
+        raise UnavailableError, "#{down.join(' and ')} unavailable; showing the rest of the summary" if down.any?
+      end
+    end
+  end
+end

data/lib/periscope/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Periscope
+  class Config
+    DEFAULT_URLS = {
+      "guardpost" => "https://accounts.kodeco.com",
+      "kerching" => "https://store.kodeco.com",
+      "carolus" => "https://www.kodeco.com"
+    }.freeze
+
+    APPS = DEFAULT_URLS.keys.freeze
+
+    def initialize(env = ENV)
+      @env = env
+    end
+
+    def url(app)
+      raise UsageError, "Unknown app #{app}; use one of #{APPS.join(', ')}" unless APPS.include?(app)
+
+      override = @env["KODECO_#{app.upcase}_URL"]
+      (override.nil? || override.empty? ? DEFAULT_URLS[app] : override).chomp("/")
+    end
+
+    def config_dir
+      base = @env["XDG_CONFIG_HOME"]
+      base = File.join(Dir.home, ".config") if base.nil? || base.empty?
+      File.join(base, "kodeco")
+    end
+  end
+end

data/lib/periscope/credential_store.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Periscope
+  # credentials.json holds one entry per guardpost URL, so a staging login
+  # never overwrites a production one. Callers hold #with_lock around writes.
+  class CredentialStore
+    attr_reader :path
+
+    def initialize(dir, key)
+      @dir = dir
+      @key = key
+      @path = File.join(dir, "credentials.json")
+    end
+
+    def read
+      all[@key]
+    end
+
+    def write(entry)
+      save(all.merge(@key => entry))
+    end
+
+    # Returns the deleted entry, or nil if there wasn't one.
+    def delete
+      entries = all
+      deleted = entries.delete(@key) or return
+
+      entries.empty? ? File.delete(@path) : save(entries)
+      deleted
+    end
+
+    def with_lock
+      ensure_dir
+      File.open(File.join(@dir, "credentials.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    private
+
+    def all
+      return {} unless File.exist?(@path)
+
+      mode = File.stat(@path).mode & 0o777
+      if mode.anybits?(0o077)
+        raise Error, format("%<path>s has permissions %<mode>04o, wider than 0600. Fix it with: chmod 600 %<path>s",
+                            path: @path, mode: mode)
+      end
+
+      JSON.parse(File.read(@path))
+    rescue JSON::ParserError
+      raise Error, "#{@path} isn't valid JSON. Delete it and run kodeco login."
+    end
+
+    def save(entries)
+      ensure_dir
+      tmp = "#{@path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+      File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |f|
+        f.write(JSON.pretty_generate(entries))
+        f.fsync
+      end
+      File.rename(tmp, @path)
+    ensure
+      FileUtils.rm_f(tmp) if tmp
+    end
+
+    def ensure_dir
+      FileUtils.mkdir_p(@dir)
+      File.chmod(0o700, @dir)
+    end
+  end
+end

data/lib/periscope/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Periscope
+  # Each error carries the exit code the CLI returns for it.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code: default_code)
+      super(message)
+      @code = code
+    end
+
+    def exit_code = 1
+    def default_code = "error"
+  end
+
+  class UsageError < Error
+    def exit_code = 2
+    def default_code = "usage"
+  end
+
+  class AuthError < Error
+    def exit_code = 3
+    def default_code = "not_logged_in"
+  end
+
+  class NotFoundError < Error
+    def exit_code = 4
+    def default_code = "not_found"
+  end
+
+  class UnavailableError < Error
+    def exit_code = 5
+    def default_code = "unavailable"
+  end
+end

data/lib/periscope/format.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Periscope
+  # Plain-text helpers for the human-readable output.
+  module Format
+    module_function
+
+    def table(headers, rows)
+      return "(none)" if rows.empty?
+
+      cells = [headers, *rows].map { |row| row.map { |cell| (cell || "-").to_s } }
+      widths = cells.transpose.map { |column| column.map(&:length).max }
+      cells.map { |row| line(row, widths) }.join("\n")
+    end
+
+    def line(row, widths) = row.zip(widths).map { |cell, width| cell.ljust(width) }.join("  ").rstrip
+
+    def pages(meta)
+      per_page = [meta["per_page"].to_i, 1].max
+      "page #{meta['page'] || 1} of #{[(meta['total'].to_i + per_page - 1) / per_page, 1].max} " \
+        "(#{meta['total'].to_i} total)"
+    end
+
+    def date(value) = value&.slice(0, 10)
+
+    def products(products) = Array(products).map { |p| p["name"] }.join(", ")
+
+    def value(value) = value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value.to_s
+  end
+end

data/lib/periscope/http.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Periscope
+  # A thin Net::HTTP wrapper. With debug on it logs method, URL and status,
+  # never headers or bodies, so tokens stay out of the log.
+  class Http
+    Response = Struct.new(:status, :body, :retry_after) do
+      def ok? = status.between?(200, 299)
+
+      # OAuth errors are {error, error_description}; other API v2 errors are
+      # {error: {code, message}}.
+      def error_code
+        error = body["error"]
+        error.is_a?(Hash) ? error["code"] : error
+      end
+
+      def error_message
+        error = body["error"]
+        error.is_a?(Hash) ? error["message"] : body["error_description"]
+      end
+    end
+
+    NETWORK_ERRORS = [SocketError, SystemCallError, IOError, Timeout::Error,
+                      Net::HTTPBadResponse, OpenSSL::SSL::SSLError].freeze
+
+    def initialize(debug: false, log: $stderr)
+      @debug = debug
+      @log = log
+    end
+
+    def get(url, headers = {})
+      request(Net::HTTP::Get, url, headers)
+    end
+
+    def post_form(url, params, headers = {})
+      request(Net::HTTP::Post, url, headers, URI.encode_www_form(params), "application/x-www-form-urlencoded")
+    end
+
+    def post_json(url, payload, headers = {})
+      request(Net::HTTP::Post, url, headers, JSON.generate(payload), "application/json")
+    end
+
+    private
+
+    def request(klass, url, headers, body = nil, content_type = nil)
+      uri = URI(url)
+      req = build(klass, uri, headers, body, content_type)
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                open_timeout: 10, read_timeout: 30) { |h| h.request(req) }
+      log("#{req.method} #{uri} #{res.code}")
+      Response.new(res.code.to_i, parse(res.body), res["Retry-After"])
+    rescue *NETWORK_ERRORS => e
+      unavailable(req, uri, e)
+    end
+
+    def unavailable(req, uri, error)
+      log("#{req&.method} #{uri} failed: #{error.class}")
+      raise UnavailableError, "#{uri.host} unavailable (#{error.class.name.split('::').last})"
+    end
+
+    def build(klass, uri, headers, body, content_type)
+      req = klass.new(uri)
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "kodeco/#{VERSION}"
+      headers.each { |k, v| req[k] = v }
+      if body
+        req.body = body
+        req["Content-Type"] = content_type
+      end
+      req
+    end
+
+    def parse(body)
+      parsed = body.nil? || body.empty? ? {} : JSON.parse(body)
+      parsed.is_a?(Hash) ? parsed : { "data" => parsed }
+    rescue JSON::ParserError
+      {}
+    end
+
+    def log(line)
+      @log.puts(line) if @debug
+    end
+  end
+end

data/lib/periscope/login.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Periscope
+  # The OAuth device-code flow against guardpost.
+  class Login
+    DEFAULT_SCOPES = "users:read support:read orders:read learning:read flags:read"
+    DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+    SCOPE_HINT = "If you lack a grant for one of the scopes, retry with --scopes and leave it out."
+
+    def initialize(config:, store:, http:, out:, opener: nil, sleeper: ->(s) { sleep(s) }, clock: -> { Time.now })
+      @base = config.url("guardpost")
+      @store = store
+      @http = http
+      @out = out
+      @opener = opener
+      @sleeper = sleeper
+      @clock = clock
+    end
+
+    def call(scopes = DEFAULT_SCOPES)
+      device = start(scopes)
+      @out.puts "To log in, visit #{device['verification_uri_complete']}"
+      @out.puts "and confirm the code #{device['user_code']}."
+      @opener&.call(device["verification_uri_complete"])
+      credentials = Session.credentials_from(poll(device), now: @clock.call)
+      @store.with_lock { @store.write(credentials) }
+      credentials
+    end
+
+    private
+
+    def start(scopes)
+      res = @http.post_form("#{@base}/api/v2/auth/device", scope: scopes)
+      return res.body if res.ok?
+
+      raise UsageError.new("#{res.error_message || 'Invalid scope'}. #{SCOPE_HINT}", code: "invalid_scope") if
+        res.error_code == "invalid_scope"
+
+      raise_common(res)
+    end
+
+    def poll(device)
+      interval = (device["interval"] || 5).to_i
+      loop do
+        @sleeper.call(interval)
+        res = @http.post_form("#{@base}/api/v2/auth/token", grant_type: DEVICE_GRANT,
+                                                            device_code: device["device_code"])
+        return res.body if res.ok?
+        next @sleeper.call(res.retry_after.to_i) if res.status == 429
+
+        case res.error_code
+        when "authorization_pending" then next
+        when "slow_down" then interval += 5
+        else raise_poll_error(res)
+        end
+      end
+    end
+
+    def raise_poll_error(res)
+      case res.error_code
+      when "expired_token"
+        raise AuthError.new("The code expired before it was approved. Run kodeco login again.", code: "expired_token")
+      when "access_denied"
+        raise AuthError.new("Login wasn't approved. #{SCOPE_HINT}", code: "access_denied")
+      when "invalid_grant"
+        raise AuthError.new("The login code is no longer valid. Run kodeco login again.", code: "invalid_grant")
+      end
+      raise_common(res)
+    end
+
+    def raise_common(res)
+      if res.status >= 500 || res.error_code == "temporarily_unavailable"
+        raise UnavailableError, "guardpost unavailable (#{res.error_message || res.status})"
+      end
+
+      raise Error.new("Login failed: #{res.error_message || res.error_code || res.status}",
+                      code: res.error_code || "error")
+    end
+  end
+end

data/lib/periscope/session.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Periscope
+  # Hands out per-app access tokens, refreshing them when they're close to
+  # expiry. guardpost rotates the refresh token on every refresh, and
+  # presenting a rotated one revokes the session, so refreshes are serialised
+  # across processes with a flock and the file is re-read once it's held.
+  class Session
+    REFRESH_MARGIN = 60
+    TOKEN_PATH = "/api/v2/auth/token"
+
+    def self.credentials_from(body, now: Time.now)
+      expires_at = now.to_i + body.fetch("expires_in").to_i
+      {
+        "access_tokens" => body.fetch("access_tokens").transform_values do |token|
+          { "token" => token, "expires_at" => expires_at }
+        end,
+        "refresh_token" => body.fetch("refresh_token"),
+        "scope" => body["scope"]
+      }
+    end
+
+    def initialize(config:, store:, http:, clock: -> { Time.now })
+      @config = config
+      @store = store
+      @http = http
+      @clock = clock
+    end
+
+    def token_for(app)
+      credentials = @store.read or raise AuthError, "Not logged in. Run kodeco login."
+      return token(credentials, app) if fresh?(credentials, app)
+
+      @store.with_lock do
+        credentials = @store.read or raise AuthError, "Not logged in. Run kodeco login."
+        credentials = refresh(credentials) unless fresh?(credentials, app)
+        token(credentials, app)
+      end
+    end
+
+    private
+
+    def fresh?(credentials, app)
+      expires_at = credentials.dig("access_tokens", app, "expires_at")
+      expires_at.nil? || expires_at.to_i - REFRESH_MARGIN > @clock.call.to_i
+    end
+
+    def token(credentials, app)
+      credentials.dig("access_tokens", app, "token") or
+        raise AuthError.new("Your login has no token for #{app}. Run kodeco login again.", code: "auth_failed")
+    end
+
+    def refresh(credentials)
+      res = @http.post_form("#{@config.url('guardpost')}#{TOKEN_PATH}",
+                            grant_type: "refresh_token", refresh_token: credentials["refresh_token"])
+      if res.ok?
+        refreshed = self.class.credentials_from(res.body, now: @clock.call)
+        @store.write(refreshed)
+        return refreshed
+      end
+
+      raise_refresh_error(res)
+    end
+
+    def raise_refresh_error(res)
+      case res.error_code
+      when "invalid_grant"
+        @store.delete
+        raise AuthError.new("Your session has ended. Run kodeco login again.", code: "auth_failed")
+      when "temporarily_unavailable"
+        raise UnavailableError, "guardpost unavailable (#{res.error_message || res.status})"
+      end
+      raise UnavailableError, "guardpost unavailable (#{res.status})" if res.status >= 500
+
+      raise Error, "Token refresh failed: #{res.error_message || res.error_code || res.status}"
+    end
+  end
+end

data/lib/periscope/user_lookup.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Periscope
+  # Resolves an <email|rwuuid> argument to an rwuuid.
+  module UserLookup
+    def self.rwuuid(client, arg)
+      rwuuid = if arg.include?("@")
+                 data = client.post_json("guardpost", "/api/v2/users/lookup", { email: arg }, scope: "users:read")
+                 Array(data["data"]).first&.fetch("rwuuid") or raise NotFoundError, "No user with that email"
+               else
+                 arg
+               end
+      URI.encode_www_form_component(rwuuid)
+    end
+  end
+end

data/lib/periscope/user_summary.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Periscope
+  # Renders guardpost's customer summary for people. kerching and carolus
+  # sections carry a status; carolus's list items are rendered tolerantly
+  # because their shapes are carolus's own.
+  class UserSummary
+    REMOTE = %w[kerching carolus].freeze
+
+    def initialize(data)
+      @data = data
+    end
+
+    def unavailable
+      REMOTE.select { |app| @data.dig(app, "status") == "unavailable" }
+    end
+
+    def to_s
+      [guardpost, *REMOTE.map { |app| remote(app) }].join("\n\n")
+    end
+
+    private
+
+    def guardpost
+      user = @data["guardpost"] || {}
+      lines = ["guardpost"]
+      lines.concat(fields(user))
+      lines.concat(list("Recent email problems", user["email_problems"]) do |p|
+        "#{p['log_type']} at #{p['created_at']}"
+      end)
+      lines.concat(list("Impersonations", user["impersonations"]) do |i|
+        "by #{i['impersonator_id']} at #{i['created_at']}: #{i['reason']}"
+      end)
+      lines.join("\n")
+    end
+
+    def fields(user)
+      sessions = user["sessions"] || {}
+      [
+        ["Name", user["name"]], ["Email", user["email"]], ["Username", user["username"]],
+        ["rwuuid", user["rwuuid"]], ["Access level", user["access_level"]], ["Created at", user["created_at"]],
+        ["Last signed in", user["last_logged_in"] || "never"],
+        ["Confirmed", user["confirmed_at"] ? "yes, #{user['confirmed_at']}" : "no"],
+        ["Consent up to date", yes_no(user.dig("consent", "up_to_date"))],
+        ["Teams", teams(user["memberships"])],
+        ["Active sessions", "#{sessions['active_count'] || 0} (last active #{sessions['last_active_at'] || 'never'})"]
+      ].map { |label, value| format("  %-19<label>s %<value>s", label: "#{label}:", value: value.nil? ? "-" : value) }
+    end
+
+    def teams(memberships)
+      return "none" if memberships.nil? || memberships.empty?
+
+      memberships.map { |m| [m["team_name"] || "team #{m['team_id']}", m["title"]].compact.join(", ") }.join("; ")
+    end
+
+    def remote(app)
+      section = @data[app] || {}
+      case section["status"]
+      when "ok" then [app, *send(:"#{app}_lines", section["data"] || {})].join("\n")
+      when "none" then "#{app}\n  No record in #{app}"
+      else "#{app}\n  !! #{app} unavailable (#{section['error'] || 'error'})"
+      end
+    end
+
+    def kerching_lines(data)
+      sub = data["subscription"] || {}
+      order = sub["order"]
+      lines = ["  Subscription:       #{sub['status'] || '-'}"]
+      if order
+        lines << "  Order:              ##{order['id']} #{order['state']}, #{order.dig('product', 'name') || '-'}, " \
+                 "ends #{order['end_date'] || '-'}"
+      end
+      lines + list("Owned products", data["ownerships"], all: true) do |o|
+        "#{o.dig('product', 'name')} (#{o.dig('product', 'sku')})"
+      end
+    end
+
+    def carolus_lines(data)
+      progress = data["progress"] || {}
+      watching = data["watching"] || {}
+      minutes = (watching["seconds_last_30_days"] || 0).to_i / 60
+      ["  Progress:           #{progress['in_progress_count'] || 0} in progress, " \
+       "#{progress['finished_count'] || 0} finished",
+       "  Watching:           #{minutes} min in the last 30 days, last on #{watching['last_watched_on'] || 'never'}"] +
+        list("Recent content", progress["recent"], all: true) { |item| describe(item) } +
+        list("Playback errors", data["playback_errors"]) { |item| describe(item) }
+    end
+
+    # A heading and one line per item; empty lists are left out unless all: true.
+    def list(heading, items, all: false, &)
+      items = Array(items)
+      return [] if items.empty? && !all
+      return ["  #{heading}: none"] if items.empty?
+
+      ["  #{heading}:", *items.map { |item| "    - #{yield(item)}" }]
+    end
+
+    def describe(item)
+      return item.to_s unless item.is_a?(Hash)
+
+      item.values_at("title", "name", "content_name").compact.first || JSON.generate(item)
+    end
+
+    def yes_no(value) = { true => "yes", false => "no" }[value]
+  end
+end

data/lib/periscope/version.rb

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

data/lib/periscope.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "periscope/version"
+require_relative "periscope/errors"
+require_relative "periscope/config"
+require_relative "periscope/http"
+require_relative "periscope/credential_store"
+require_relative "periscope/session"
+require_relative "periscope/client"
+require_relative "periscope/login"
+require_relative "periscope/user_lookup"
+require_relative "periscope/user_summary"
+require_relative "periscope/format"
+require_relative "periscope/commands/user"
+require_relative "periscope/commands/kerching"
+require_relative "periscope/commands/flags"
+require_relative "periscope/cli"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: kodeco
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kodeco
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables:
+- kodeco
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/kodeco
+- lib/kodeco.rb
+- lib/periscope.rb
+- lib/periscope/cli.rb
+- lib/periscope/client.rb
+- lib/periscope/commands/flags.rb
+- lib/periscope/commands/kerching.rb
+- lib/periscope/commands/user.rb
+- lib/periscope/config.rb
+- lib/periscope/credential_store.rb
+- lib/periscope/errors.rb
+- lib/periscope/format.rb
+- lib/periscope/http.rb
+- lib/periscope/login.rb
+- lib/periscope/session.rb
+- lib/periscope/user_lookup.rb
+- lib/periscope/user_summary.rb
+- lib/periscope/version.rb
+homepage: https://github.com/razeware/periscope
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: The kodeco command-line tool for Kodeco's API v2
+test_files: []