kodeco 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92f1b3f3a2c07ef7de80d5e2bcf2e7dd6989cd5baa29c56d085ea8fe61294e66
-  data.tar.gz: 75794675c957b94474ece30dfaebb15c2c28f3b0798208b48242aa7989fb1e94
+  metadata.gz: 917b9f6e09b0d724f94ff27f1596cba5c870545dc6a1199a0ebb31cd7a68d114
+  data.tar.gz: c9e3e16f779d27b3353e42593cb37abf181f9e3d1459b60dc79cef5d1b20d48d
 SHA512:
-  metadata.gz: 95eac6af137ca2809784e1adc765a4143a54bf7f0891236f105810645b5296de87c08367012c72a304361dd96a82940aa31efe85bb2036eaf58a029f7bcf1a6b
-  data.tar.gz: 846d4357394ca12d042e4cf57476975866289452a0f3b74f764d0300e5503a0657e5efd45646ed155a531a4e1db39ddce6d39ebebfae2ed2650e078922232212
+  metadata.gz: a5812db82c6f20d0bb3346fd4dd501149a58f382235038b6b274b78e7bae1329cdad77791469d0f83743ac6ad55022037c06eb363ec7a4c8f0bb3b8bf01d3ed3
+  data.tar.gz: 105c668ab4fc503d874401e048f6cec51e5732e7df7673f91e9cf2c6e43992486fa065310b1e842213ab45b642f8a311a60cc9f7f54be25d9c8d07a27c1dfc7d

data/README.md

@@ -22,6 +22,10 @@ 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
+kodeco shortlinks list [query] [--page N]
+kodeco shortlinks show <slug>
+kodeco shortlinks create <url> [--channels a,b] [--campaign NAME]
+kodeco shortlinks update <slug> --active=true|false
 ```
 
 `user` shows guardpost's customer summary, with kerching's and carolus's
@@ -31,10 +35,19 @@ exits 5 after printing the rest. `orders`, `order`, `subscription` and
 `flags:read`. With `--json`, commands print the response's `data`, plus `meta`
 for lists.
 
+`shortlinks` manages carolus's kod.eco short links. `list` and `show` need
+`shortlinks:read`, which `login` asks for by default. `create` and `update`
+need `shortlinks:write`, which it never asks for by default; without it they
+print the `kodeco login --scopes` line to run, and send nothing. `show` and
+`update` take a slug or a short URL. Team members see and change only their
+own links. Admins see every link and the fuller click counts, and can use
+`--channels` (keys from carolus's `config/short_link_channels.yml`, such as
+`twitter`) and `--campaign`, which needs `--channels`.
+
 `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`. Scopes other than `flags:read` need a grant from a guardpost
+flags:read shortlinks:read`. Scopes other than `flags:read` need a grant from a guardpost
 admin. A login gets whichever of the requested scopes you hold, and `login`
 lists any that weren't granted; a grant added later needs a fresh
 `kodeco login`.
@@ -45,7 +58,8 @@ 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": ...}}`.
+  `{"error": {"code": ..., "message": ...}}`. When an app refuses a value,
+  the error also has `details`, with each field's problems.
 * `--debug`: logs each request's method, URL and status to stderr. Tokens are
   never printed or logged.
 
@@ -55,7 +69,7 @@ Every command takes:
 | ---- | ------- |
 | 0 | OK |
 | 1 | Error |
-| 2 | Usage error |
+| 2 | Usage error, or a value the app refused |
 | 3 | Not logged in, or authentication failed |
 | 4 | Not found |
 | 5 | An upstream app is unavailable |
@@ -79,10 +93,12 @@ processes share one refresh rather than revoking each other's session.
 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.
+1. Bump `Periscope::VERSION` in `lib/periscope/version.rb`, in a PR.
+2. Merge the release PR to `trunk`.
+3. Publish a GitHub release tagged `v<version>` on `trunk`. The Release
+   workflow checks that the tag matches `Periscope::VERSION`, runs the tests,
+   then builds and pushes the gem. To re-run a failed publish, run the
+   workflow by hand with the tag.
 
 ## Development
 

data/lib/periscope/cli.rb

@@ -9,6 +9,7 @@ module Periscope
     include Commands::User
     include Commands::Kerching
     include Commands::Flags
+    include Commands::Shortlinks
 
     USAGE = <<~TEXT
       Usage: kodeco <command> [options]
@@ -24,12 +25,18 @@ module Periscope
         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
+        shortlinks list [query] [--page N]     List kod.eco short links
+        shortlinks show <slug>                 Show one short link and its clicks
+        shortlinks create <url> [--channels a,b] [--campaign NAME]
+                                               Make short links to a kodeco.com URL
+        shortlinks update <slug> --active=true|false
+                                               Turn a short link on or off
 
       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
+    COMMANDS = %w[login logout whoami user orders order subscription problems flags shortlinks].freeze
     LOGOUT_NOTE = "guardpost has no revoke endpoint, so the server session lasts up to 7 days " \
                   "unless an admin revokes it."
 
@@ -104,7 +111,7 @@ module Periscope
     end
 
     # Parses the remaining arguments and returns the options; commands that
-    # take positional arguments pass positional: n.
+    # take positional arguments pass positional: n, or a Range.
     def parse_options(positional: 0)
       opts = {}
       parser = OptionParser.new
@@ -112,15 +119,14 @@ module Periscope
       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
+      unless Array(positional).include?(rest.size)
+        raise UsageError, "Expected #{positional} argument(s), got #{rest.size}"
+      end
 
-      opts[:args] = rest
-      opts
+      opts.merge(args: rest)
     end
 
-    def emit(data)
-      @stdout.puts(@json ? JSON.generate(data) : yield)
-    end
+    def emit(data) = @stdout.puts(@json ? JSON.generate(data) : yield)
 
     def usage(status)
       (status.zero? ? @stdout : @stderr).puts(USAGE)
@@ -129,7 +135,7 @@ module Periscope
 
     def fail_with(error)
       if @json
-        @stderr.puts(JSON.generate(error: { code: error.code, message: error.message }))
+        @stderr.puts(JSON.generate(error: { code: error.code, message: error.message, details: error.details }.compact))
       else
         @stderr.puts("kodeco: #{error.message}")
       end

data/lib/periscope/client.rb

@@ -18,6 +18,10 @@ module Periscope
       handle(app, scope, @http.post_json(url(app, path), payload, auth(app)))
     end
 
+    def patch_json(app, path, payload, scope: nil)
+      handle(app, scope, @http.patch_json(url(app, path), payload, auth(app)))
+    end
+
     private
 
     def url(app, path) = "#{@config.url(app)}#{path}"
@@ -32,11 +36,20 @@ module Periscope
       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 422 then raise refused(app, message, res)
       when 500.. then raise UnavailableError, "#{app} unavailable (#{message})"
       end
       raise Error.new(message, code: res.error_code || "error")
     end
 
+    # A value the app refused, with each field's problems in the message.
+    def refused(app, message, res)
+      details = res.error_details
+      fields = details.map { |field, problems| "#{field}: #{Array(problems).join(', ')}" } if details.is_a?(Hash)
+      message = "#{message} (#{fields.join('; ')})" if fields&.any?
+      UsageError.new("#{app} refused: #{message}", code: res.error_code || "validation_failed", details: details)
+    end
+
     def forbidden(app, scope, message)
       return "#{app} refused: #{message}" unless scope
 

data/lib/periscope/commands/shortlinks.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Periscope
+  module Commands
+    # kodeco shortlinks list, show, create and update: carolus's kod.eco short links.
+    module Shortlinks
+      SUBCOMMANDS = %w[list show create update].freeze
+      PATH = "/api/v2/short_links"
+      SLUG = /\A[a-z2-9]{5}\z/
+      UTM_HEADERS = %w[SOURCE MEDIUM CAMPAIGN].freeze
+      LIST_HEADERS = ["SHORT URL", "ACTIVE", "CLICKS", "7D", "BOTS", *UTM_HEADERS, "DESTINATION"].freeze
+      TEAM_NOTE = "Short links are for the Kodeco team, and only admins can see or change other people's links " \
+                  "or use --channels and --campaign."
+      RETRY_NOTE = "It may have been applied; running the same command again is safe."
+
+      private
+
+      def cmd_shortlinks
+        subcommand = @argv.shift
+        raise UsageError, "Usage: kodeco shortlinks #{SUBCOMMANDS.join('|')}" unless SUBCOMMANDS.include?(subcommand)
+
+        send(:"shortlinks_#{subcommand}")
+      end
+
+      def shortlinks_list
+        opts = parse_options(positional: 0..1) { |parser, o| page_option(parser, o) }
+        path = "#{PATH}#{query(q: opts[:args].first, page: opts[:page])}"
+        body = carolus("shortlinks:read") { client.get("carolus", path) }
+        rows = body["data"].map do |link|
+          [link["short_url"], link["active"] ? "yes" : "no", link["clicks"], link["clicks_7d"], link["bot_clicks"],
+           *ShortLinkText.utm(link), link["destination_url"]]
+        end
+        emit(body.slice("data", "meta")) { "#{Format.table(LIST_HEADERS, rows)}\n#{pages(body)}" }
+      end
+
+      def shortlinks_show
+        slug = slug_arg(parse_options(positional: 1))
+        link = carolus("shortlinks:read", slug: slug) { client.get("carolus", "#{PATH}/#{slug}") }["data"]
+        emit(link) { ShortLinkText.new(link).to_s }
+      end
+
+      def shortlinks_create
+        opts = parse_options(positional: 1) do |parser, o|
+          parser.on("--channels LIST", Array) { |v| o[:channels] = channels(v) }
+          parser.on("--campaign NAME") { |v| o[:campaign] = v }
+        end
+        raise UsageError, "--campaign needs --channels: carolus uses it only for channel links" if
+          opts[:campaign] && !opts[:channels]
+
+        payload = { destination_url: opts[:args].first, channels: opts[:channels], utm_campaign: opts[:campaign] }
+        links = carolus("shortlinks:write", write: true) { client.post_json("carolus", PATH, payload.compact) }["data"]
+        emit(links) { create_text(links) }
+      end
+
+      def shortlinks_update
+        opts = parse_options(positional: 1) { |parser, o| parser.on("--active BOOL", TrueClass) { |v| o[:active] = v } }
+        slug = slug_arg(opts)
+        raise UsageError, "update needs --active=true or --active=false" if opts[:active].nil?
+
+        link = carolus("shortlinks:write", slug: slug, write: true) do
+          client.patch_json("carolus", "#{PATH}/#{slug}", { active: opts[:active] })
+        end["data"]
+        emit(link) { ShortLinkText.new(link).updated }
+      end
+
+      def create_text(links)
+        rows = links.map { |l| [l["created"] ? "created" : "existing", l["short_url"], *ShortLinkText.utm(l)] }
+        created = links.count { |link| link["created"] }
+        "#{Format.table(['STATUS', 'SHORT URL', *UTM_HEADERS], rows)}\n" \
+          "#{created} created, #{links.size - created} already existed"
+      end
+
+      def channels(list)
+        list = list.compact.reject(&:empty?)
+        raise UsageError, "--channels needs at least one channel" if list.empty?
+
+        list
+      end
+
+      # A slug, or a short URL on any host: the last path segment, lowercased.
+      def slug_arg(opts)
+        slug = opts[:args].first.split("/").last.to_s.downcase
+        raise UsageError, "#{opts[:args].first} isn't a short link slug or URL" unless slug.match?(SLUG)
+
+        slug
+      end
+
+      # Checks the login's scope before sending anything, then makes carolus's
+      # refusals say what they mean for short links.
+      def carolus(scope, slug: nil, write: false)
+        require_scope(scope)
+        yield
+      rescue AuthError => e
+        raise unless e.code == "forbidden"
+
+        raise AuthError.new("#{e.message.delete_suffix('.')}. #{TEAM_NOTE}", code: "forbidden")
+      rescue NotFoundError
+        raise unless slug
+
+        raise NotFoundError, "No short link #{slug}"
+      rescue UnavailableError => e
+        raise unless write
+
+        raise UnavailableError, "#{e.message}. #{RETRY_NOTE}"
+      end
+
+      # A new login replaces the stored one, so the suggested line keeps the scopes it has.
+      def require_scope(scope)
+        credentials = store.read or raise AuthError, "Not logged in. Run kodeco login."
+        held = credentials["scope"].to_s.split
+        return if held.include?(scope)
+
+        raise AuthError.new("This needs the #{scope} scope, which your login doesn't have. " \
+                            "Run: kodeco login --scopes \"#{[*held, scope].join(' ')}\"", code: "missing_scope")
+      end
+    end
+  end
+end

data/lib/periscope/errors.rb

@@ -3,11 +3,12 @@
 module Periscope
   # Each error carries the exit code the CLI returns for it.
   class Error < StandardError
-    attr_reader :code
+    attr_reader :code, :details
 
-    def initialize(message, code: default_code)
+    def initialize(message, code: default_code, details: nil)
       super(message)
       @code = code
+      @details = details unless details.respond_to?(:empty?) && details.empty?
     end
 
     def exit_code = 1

data/lib/periscope/http.rb

@@ -22,6 +22,11 @@ module Periscope
         error = body["error"]
         error.is_a?(Hash) ? error["message"] : body["error_description"]
       end
+
+      def error_details
+        error = body["error"]
+        error["details"] if error.is_a?(Hash)
+      end
     end
 
     NETWORK_ERRORS = [SocketError, SystemCallError, IOError, Timeout::Error,
@@ -44,6 +49,10 @@ module Periscope
       request(Net::HTTP::Post, url, headers, JSON.generate(payload), "application/json")
     end
 
+    def patch_json(url, payload, headers = {})
+      request(Net::HTTP::Patch, url, headers, JSON.generate(payload), "application/json")
+    end
+
     private
 
     def request(klass, url, headers, body = nil, content_type = nil)

data/lib/periscope/login.rb

@@ -3,7 +3,7 @@
 module Periscope
   # The OAuth device-code flow against guardpost.
   class Login
-    DEFAULT_SCOPES = "users:read support:read orders:read learning:read flags:read"
+    DEFAULT_SCOPES = "users:read support:read orders:read learning:read flags:read shortlinks: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."
 

data/lib/periscope/short_link_text.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Periscope
+  # Renders one of carolus's short links for people. Admins get extra click
+  # counts and the daily and bot sections; team members get neither.
+  class ShortLinkText
+    INACTIVE = "is now inactive. Visitors go to the kodeco.com home page."
+
+    # The UTM source, medium and campaign, with empty values as nil so tables print "-".
+    def self.utm(link)
+      %w[utm_source utm_medium utm_campaign].map { |key| link[key].to_s.empty? ? nil : link[key] }
+    end
+
+    def initialize(link)
+      @link = link
+    end
+
+    def to_s
+      ["#{@link['short_url']} (#{@link['active'] ? 'active' : 'inactive'})", *fields, *daily, *bots].join("\n")
+    end
+
+    # After a PATCH, which sends neither daily clicks nor bots.
+    def updated
+      ["#{@link['short_url']} #{@link['active'] ? 'is now active.' : INACTIVE}", *fields].join("\n")
+    end
+
+    private
+
+    def fields
+      [["Destination", @link["destination_url"]], ["Full URL", @link["full_destination_url"]], ["UTM", utm],
+       ["Created", "#{@link['created_at']} by #{@link['created_by'] || '-'}"], ["Updated", @link["updated_at"]],
+       ["Clicks", clicks]].map do |label, value|
+        format("  %-13<label>s%<value>s", label: "#{label}:", value: value.nil? ? "-" : value)
+      end
+    end
+
+    def utm
+      values = self.class.utm(@link)
+      values.all?(&:nil?) ? "none" : values.map { |v| v || "-" }.join(" / ")
+    end
+
+    def clicks
+      extra = { "7 days" => "clicks_7d", "30 days" => "clicks_30d", "bots" => "bot_clicks" }
+              .filter_map { |label, key| "#{label} #{@link[key]}" if @link.key?(key) }
+      extra.empty? ? @link["clicks"].to_s : "#{@link['clicks']} (#{extra.join(', ')})"
+    end
+
+    def daily
+      return [] unless @link.key?("daily_clicks")
+
+      rows = Array(@link["daily_clicks"]).last(14).map { |day| [day["date"], day["clicks"]] }
+      ["", "Daily clicks, last 14 days", Format.table(%w[DATE CLICKS], rows)]
+    end
+
+    def bots
+      return [] unless @link.key?("bot_breakdown")
+
+      rows = Array(@link["bot_breakdown"]).map { |bot| [bot["name"], bot["clicks"]] }
+      ["", "Bots", Format.table(%w[NAME CLICKS], rows)]
+    end
+  end
+end

data/lib/periscope/version.rb

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

data/lib/periscope.rb

@@ -11,7 +11,9 @@ require_relative "periscope/login"
 require_relative "periscope/user_lookup"
 require_relative "periscope/user_summary"
 require_relative "periscope/format"
+require_relative "periscope/short_link_text"
 require_relative "periscope/commands/user"
 require_relative "periscope/commands/kerching"
 require_relative "periscope/commands/flags"
+require_relative "periscope/commands/shortlinks"
 require_relative "periscope/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kodeco
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Kodeco
@@ -22,6 +22,7 @@ files:
 - lib/periscope/client.rb
 - lib/periscope/commands/flags.rb
 - lib/periscope/commands/kerching.rb
+- lib/periscope/commands/shortlinks.rb
 - lib/periscope/commands/user.rb
 - lib/periscope/config.rb
 - lib/periscope/credential_store.rb
@@ -30,6 +31,7 @@ files:
 - lib/periscope/http.rb
 - lib/periscope/login.rb
 - lib/periscope/session.rb
+- lib/periscope/short_link_text.rb
 - lib/periscope/user_lookup.rb
 - lib/periscope/user_summary.rb
 - lib/periscope/version.rb