waves-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba842c75819ad196345a640bb058aaa398b5ed6ada2e7610ff15d080b0613d1b
+  data.tar.gz: 6ea6b97c6b33a6503dc9921761b23fb86d9a0851a307294d248134259038c00f
+SHA512:
+  metadata.gz: 273137f5386f5fa57d420644e1c0e083f98d658957995023434ce8ae0acecf4897785e65319c72d3ef44e2d3d562c90a634a2b02879cd8a76575755b90a359e1
+  data.tar.gz: 64d920b54c4e272d2a334c51844aa912478e37e6e988f9bb982106262387beec817030c688882225c06c82285c08fa06cdd3a98e10e447c69c5eb21fb3797b5d

data/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Local Setup
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Copy `.env.example` to `.env` if you want to run live API verification locally.
+
+## Testing Policy
+
+- `.env` is for local development only and must never be committed.
+- Use `WAVES_API_TOKEN` from `.env` for opt-in live verification only.
+- Raw VCR recordings belong in `spec/cassettes/local/` and must stay untracked.
+- Committed fixtures and example cassettes must be sanitized.
+- Do not commit real meeting titles, summaries, snippets, notes, transcripts, or signed media URLs.
+
+## Live Verification Workflow
+
+1. Copy `.env.example` to `.env`.
+2. Set `WAVES_API_TOKEN` in `.env`.
+3. Run `WAVES_LIVE=1 bundle exec rspec spec/waves/live/client_live_spec.rb`.
+4. If you want to record local cassettes for the entire live suite, run `WAVES_LIVE=1 WAVES_RECORD_LIVE=1 bundle exec rspec spec/waves/live/client_live_spec.rb`.
+5. Keep any raw recordings in `spec/cassettes/local/`.
+6. Optionally set `WAVES_SESSION_ID` and `WAVES_SEARCH_QUERY` in `.env` if you want deterministic session and search coverage.
+7. Convert any useful example into a sanitized fixture under `spec/fixtures/waves/` or a scrubbed cassette under `spec/cassettes/examples/`.
+8. Commit only sanitized artifacts.
+
+## Sanitization Checklist
+
+- Replace tokens and `Authorization` headers.
+- Replace real meeting titles, snippets, summaries, notes, and transcript text.
+- Replace signed or temporary media URLs.
+- Replace participant emails and other personal identifiers.
+
+The helper patterns in [spec/support/sanitizer.rb](/Users/avi/Development/code/waves-rubygem-cli-api/spec/support/sanitizer.rb) are intended to make that scrubbing repeatable, but contributors are still responsible for reviewing the final artifact before committing it.

data/README.md

@@ -0,0 +1,94 @@
+# Waves Ruby
+
+Ruby API client and CLI for the Wave API.
+
+## CLI
+
+Available commands:
+
+```bash
+waves login
+waves account
+waves list
+waves search "meeting content"
+waves show SESSION_ID
+waves transcript SESSION_ID
+```
+
+Use `--json` on any read command for machine-readable output:
+
+```bash
+waves list --json
+waves account --json
+```
+
+You can provide credentials with `--token`, `WAVES_API_TOKEN`, or a token saved locally by `waves login`.
+
+## Ruby API
+
+```ruby
+client = Waves::Client.new(token: ENV.fetch("WAVES_API_TOKEN"))
+
+client.account
+client.list_sessions(limit: 10)
+client.search_sessions(query: "roadmap")
+client.session("session_123")
+client.transcript("session_123")
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+## Live API Verification
+
+Copy `.env.example` to `.env` and set a real token:
+
+```bash
+cp .env.example .env
+```
+
+Then set:
+
+```bash
+WAVES_API_TOKEN=your_wave_api_token
+```
+
+Live specs are opt-in and skipped by default. Run them locally with:
+
+```bash
+WAVES_LIVE=1 bundle exec rspec spec/waves/live/client_live_spec.rb
+```
+
+That exercises the current live coverage for:
+
+- `account`
+- `list_sessions`
+- `stats`
+- `session`
+- `transcript`
+- `search_sessions`
+
+`session`, `transcript`, and `search_sessions` auto-discover test inputs from your first listed session. You can make them deterministic by setting `WAVES_SESSION_ID` and `WAVES_SEARCH_QUERY` in `.env`.
+
+To record local-only cassettes for every live example in the gitignored directory:
+
+```bash
+WAVES_LIVE=1 WAVES_RECORD_LIVE=1 bundle exec rspec spec/waves/live/client_live_spec.rb
+```
+
+Those recordings stay under `spec/cassettes/local/` and must not be committed. If you want to keep an example response in the repo, convert it into a sanitized fixture under `spec/fixtures/waves/` or a scrubbed example cassette under `spec/cassettes/examples/`.
+
+Use the sanitization patterns in [spec/support/sanitizer.rb](/Users/avi/Development/code/waves-rubygem-cli-api/spec/support/sanitizer.rb) before committing any captured API data.
+
+See [CONTRIBUTING.md](/Users/avi/Development/code/waves-rubygem-cli-api/CONTRIBUTING.md) for the full policy.

data/exe/waves

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/waves"
+
+exit Waves::CLI.start(ARGV)

data/lib/waves/cli/app.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "optparse"
+
+module Waves
+  module CLI
+    class CommandError < StandardError; end
+
+    class App
+      COMMANDS = %w[login account list search show transcript].freeze
+
+      def initialize(argv:, stdin:, stdout:, stderr:, env:, config:, client_class:)
+        @argv = argv.dup
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @env = env
+        @config = config
+        @client_class = client_class
+        @formatter = Formatter.new(stdout: stdout)
+      end
+
+      def start
+        options, args = parse_global_options(@argv)
+        command = args.shift
+
+        return print_help if command.nil?
+        return print_help(args.first) if command == "help"
+        return print_help(command) if options[:help]
+
+        dispatch(command, args, options)
+      rescue OptionParser::ParseError, CommandError, Waves::Error => error
+        print_error(error, json: options&.fetch(:json, false) || false)
+      end
+
+      private
+
+      def parse_global_options(argv)
+        options = {
+          help: false,
+          json: false,
+          token: nil
+        }
+
+        parser = OptionParser.new do |opts|
+          opts.on("--json") { options[:json] = true }
+          opts.on("--token TOKEN") { |token| options[:token] = token }
+          opts.on("-h", "--help") { options[:help] = true }
+        end
+
+        args = argv.dup
+        parser.permute!(args)
+
+        [options, args]
+      end
+
+      def dispatch(command, args, options)
+        case command
+        when "login"
+          run_login(args, options)
+        when "account"
+          ensure_no_arguments!("account", args)
+          render_payload(fetch_client(options).account, options) { |payload| @formatter.print_account(payload) }
+        when "list"
+          ensure_no_arguments!("list", args)
+          render_payload(fetch_client(options).list_sessions, options) { |payload| @formatter.print_list(payload) }
+        when "search"
+          run_search(args, options)
+        when "show"
+          run_show(args, options)
+        when "transcript"
+          run_transcript(args, options)
+        else
+          raise CommandError, "Unknown command: #{command}"
+        end
+      end
+
+      def run_login(args, options)
+        ensure_no_arguments!("login", args)
+
+        token = normalize_token(options[:token]) || normalize_token(prompt_for_token)
+        raise CommandError, "Token cannot be empty" if token.to_s.empty?
+
+        @config.save_token(token)
+
+        payload = {
+          "config_path" => @config.config_path,
+          "message" => "Token saved"
+        }
+
+        render_payload(payload, options) do
+          @stdout.puts "Saved Wave API token to #{@config.config_path}"
+        end
+      end
+
+      def run_search(args, options)
+        query = args.join(" ").strip
+        raise CommandError, "Usage: waves search QUERY" if query.empty?
+
+        render_payload(fetch_client(options).search_sessions(query: query), options) do |payload|
+          @formatter.print_search(payload)
+        end
+      end
+
+      def run_show(args, options)
+        session_id = require_single_argument!("show", "SESSION_ID", args)
+
+        render_payload(fetch_client(options).session(session_id), options) do |payload|
+          @formatter.print_session(payload)
+        end
+      end
+
+      def run_transcript(args, options)
+        session_id = require_single_argument!("transcript", "SESSION_ID", args)
+
+        render_payload(fetch_client(options).transcript(session_id), options) do |payload|
+          @formatter.print_transcript(payload)
+        end
+      end
+
+      def fetch_client(options)
+        @client_class.new(token: resolve_token(options[:token]))
+      end
+
+      def resolve_token(explicit_token)
+        normalize_token(explicit_token) ||
+          normalize_token(@env["WAVES_API_TOKEN"]) ||
+          normalize_token(@config.stored_token)
+      end
+
+      def render_payload(payload, options)
+        if options[:json]
+          @formatter.print_json(payload)
+        else
+          yield payload
+        end
+
+        0
+      end
+
+      def print_error(error, json:)
+        if json
+          @stderr.puts JSON.pretty_generate(
+            "error" => {
+              "message" => error.message,
+              "type" => error.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+            }
+          )
+        else
+          @stderr.puts "Error: #{error.message}"
+          @stderr.puts
+          @stderr.puts help_text if error.is_a?(CommandError) && error.message.start_with?("Unknown command:")
+        end
+
+        1
+      end
+
+      def print_help(command = nil)
+        text = command ? help_text(command) : help_text
+
+        if text.nil?
+          @stderr.puts "Error: Unknown command: #{command}"
+          @stderr.puts
+          @stderr.puts help_text
+          return 1
+        end
+
+        @stdout.puts text
+        0
+      end
+
+      def help_text(command = nil)
+        return top_level_help if command.nil?
+
+        {
+          "login" => "Usage: waves login [--token TOKEN] [--json]",
+          "account" => "Usage: waves account [--token TOKEN] [--json]",
+          "list" => "Usage: waves list [--token TOKEN] [--json]",
+          "search" => "Usage: waves search QUERY [--token TOKEN] [--json]",
+          "show" => "Usage: waves show SESSION_ID [--token TOKEN] [--json]",
+          "transcript" => "Usage: waves transcript SESSION_ID [--token TOKEN] [--json]"
+        }[command]
+      end
+
+      def top_level_help
+        <<~TEXT
+          Usage: waves COMMAND [options]
+
+          Commands:
+            login
+            account
+            list
+            search QUERY
+            show SESSION_ID
+            transcript SESSION_ID
+
+          Global options:
+            --json
+            --token TOKEN
+            -h, --help
+        TEXT
+      end
+
+      def ensure_no_arguments!(command, args)
+        return if args.empty?
+
+        raise CommandError, help_text(command)
+      end
+
+      def require_single_argument!(command, argument_name, args)
+        return args.first if args.length == 1 && !args.first.to_s.empty?
+
+        raise CommandError, "Usage: waves #{command} #{argument_name}"
+      end
+
+      def prompt_for_token
+        @stderr.print "Wave API token: "
+
+        token = if @stdin.respond_to?(:noecho) && @stdin.tty?
+          @stdin.noecho(&:gets)
+        else
+          @stdin.gets
+        end
+
+        @stderr.puts if @stdin.tty?
+        token
+      end
+
+      def normalize_token(token)
+        value = token.to_s.strip
+        return if value.empty?
+
+        value
+      end
+    end
+  end
+end

data/lib/waves/cli/formatter.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Waves
+  module CLI
+    class Formatter
+      def initialize(stdout:)
+        @stdout = stdout
+      end
+
+      def print_json(payload)
+        @stdout.puts JSON.pretty_generate(payload)
+      end
+
+      def print_account(account)
+        print_record(account)
+      end
+
+      def print_list(response)
+        sessions = Array(response["sessions"])
+
+        if sessions.empty?
+          @stdout.puts "No sessions found"
+          return
+        end
+
+        print_collection(sessions)
+
+        return if response["next_cursor"].to_s.empty?
+
+        @stdout.puts
+        @stdout.puts "Next cursor: #{response["next_cursor"]}"
+      end
+
+      def print_search(response)
+        results = Array(response["results"])
+
+        if results.empty?
+          @stdout.puts "No results found"
+          return
+        end
+
+        print_collection(results, include_snippet: true)
+      end
+
+      def print_session(session)
+        print_record(session)
+      end
+
+      def print_transcript(response)
+        transcript = response["transcript"]
+
+        case transcript
+        when String
+          @stdout.puts transcript
+        when Array
+          transcript.each do |entry|
+            @stdout.puts transcript_line(entry)
+          end
+        else
+          print_record(response)
+        end
+      end
+
+      private
+
+      def print_collection(records, include_snippet: false)
+        records.each_with_index do |record, index|
+          @stdout.puts summary_line(record)
+
+          detail = detail_line(record)
+          @stdout.puts "  #{detail}" unless detail.nil?
+
+          if include_snippet && !record["snippet"].to_s.empty?
+            @stdout.puts "  #{record["snippet"]}"
+          end
+
+          @stdout.puts unless index == records.length - 1
+        end
+      end
+
+      def print_record(record)
+        record.each do |key, value|
+          label = humanize_key(key)
+
+          case value
+          when Hash, Array
+            @stdout.puts "#{label}:"
+            JSON.pretty_generate(value).each_line do |line|
+              @stdout.puts "  #{line.rstrip}"
+            end
+          when String
+            if value.include?("\n")
+              @stdout.puts "#{label}:"
+              value.each_line do |line|
+                @stdout.puts "  #{line.rstrip}"
+              end
+            else
+              @stdout.puts "#{label}: #{value}"
+            end
+          else
+            @stdout.puts "#{label}: #{value}"
+          end
+        end
+      end
+
+      def summary_line(record)
+        identifier = record["id"] || "(no id)"
+        title = record["title"] || record["name"]
+
+        return identifier if title.to_s.empty?
+
+        "#{identifier}  #{title}"
+      end
+
+      def detail_line(record)
+        details = []
+        details << record["type"]
+        details << record["status"]
+        details << record["created_at"]
+        details << record["started_at"]
+        details << record["updated_at"]
+        details << "#{record["duration_seconds"]}s" if record["duration_seconds"]
+        details.reject! { |value| value.to_s.empty? }
+
+        return if details.empty?
+
+        details.join("  ")
+      end
+
+      def transcript_line(entry)
+        return entry unless entry.is_a?(Hash)
+
+        prefix = [entry["speaker"], entry["timestamp"]].reject { |value| value.to_s.empty? }.join(" @ ")
+        text = entry["text"].to_s
+
+        return text if prefix.empty?
+        return prefix if text.empty?
+
+        "#{prefix}: #{text}"
+      end
+
+      def humanize_key(key)
+        key.to_s.split("_").map(&:capitalize).join(" ")
+      end
+    end
+  end
+end

data/lib/waves/cli.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "cli/formatter"
+require_relative "cli/app"
+
+module Waves
+  module CLI
+    module_function
+
+    def start(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV, config: Waves::Config, client_class: Waves::Client)
+      App.new(
+        argv: argv,
+        stdin: stdin,
+        stdout: stdout,
+        stderr: stderr,
+        env: env,
+        config: config,
+        client_class: client_class
+      ).start
+    end
+  end
+end

data/lib/waves/client.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module Waves
+  class Client
+    include HTTParty
+
+    base_uri "https://api.wave.co/v1"
+
+    def initialize(token: nil, timeout: Waves.timeout)
+      @token = token || Config.token
+      @timeout = timeout
+
+      raise InvalidConfigError, "Missing Wave API token" if @token.to_s.empty?
+    end
+
+    def list_sessions(limit: nil, cursor: nil, since: nil, type: nil)
+      request(:get, "/sessions", query: {
+        limit: limit,
+        cursor: cursor,
+        since: since,
+        type: type
+      })
+    end
+
+    def session(id)
+      request(:get, "/sessions/#{id}")
+    end
+
+    def search_sessions(query:, limit: nil)
+      request(:post, "/sessions/search", body: {
+        query: query,
+        limit: limit
+      })
+    end
+
+    def transcript(id)
+      request(:get, "/sessions/#{id}/transcript")
+    end
+
+    def stats(since: nil, until_time: nil, until_: nil)
+      request(:get, "/sessions/stats", query: {
+        since: since,
+        until: until_time || until_
+      })
+    end
+
+    def account
+      request(:get, "/account")
+    end
+
+    private
+
+    def request(method, path, query: nil, body: nil)
+      options = {
+        headers: headers,
+        timeout: @timeout
+      }
+      options[:query] = Request.compact_hash(query) if query
+      options[:body] = JSON.generate(Request.compact_hash(body)) if body
+
+      response = self.class.public_send(method, path, options)
+      parse_response(response)
+    rescue SocketError, HTTParty::Error, Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+      raise ConnectionError, e.message
+    end
+
+    def parse_response(response)
+      parsed = parse_body(response)
+      return parsed if response.success?
+
+      error = parsed.is_a?(Hash) ? parsed["error"] || {} : {}
+      message = error["message"] || response.body
+
+      case response.code.to_i
+      when 401
+        raise AuthenticationError, message
+      when 403
+        raise AuthorizationError, message
+      when 404
+        raise NotFoundError, message
+      when 429
+        raise RateLimitError, message
+      else
+        raise APIError, message
+      end
+    end
+
+    def parse_body(response)
+      return {} if response.body.to_s.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def headers
+      {
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{@token}",
+        "Content-Type" => "application/json"
+      }
+    end
+  end
+end

data/lib/waves/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Waves
+  module Config
+    module_function
+
+    def config_dir
+      File.join(Dir.home, ".config", "waves")
+    end
+
+    def config_path
+      File.join(config_dir, "config.json")
+    end
+
+    def token
+      ENV["WAVES_API_TOKEN"] || stored_token
+    end
+
+    def stored_token
+      load["token"]
+    end
+
+    def save_token(token)
+      raise ArgumentError, "token is required" if token.to_s.empty?
+
+      FileUtils.mkdir_p(config_dir)
+      File.write(config_path, JSON.pretty_generate("token" => token))
+      File.chmod(0o600, config_path)
+    end
+
+    def clear
+      File.delete(config_path) if File.exist?(config_path)
+    end
+
+    def load
+      return {} unless File.exist?(config_path)
+
+      JSON.parse(File.read(config_path))
+    rescue JSON::ParserError
+      raise InvalidConfigError, "Invalid config file at #{config_path}"
+    end
+  end
+end

data/lib/waves/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Waves
+  class Error < StandardError; end
+  class InvalidConfigError < Error; end
+  class AuthenticationError < Error; end
+  class AuthorizationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class APIError < Error; end
+  class ConnectionError < Error; end
+end

data/lib/waves/request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Waves
+  module Request
+    module_function
+
+    def compact_hash(hash)
+      hash.each_with_object({}) do |(key, value), compacted|
+        compacted[key] = value unless value.nil?
+      end
+    end
+  end
+end

data/lib/waves/version.rb

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

data/lib/waves.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require_relative "waves/config"
+require_relative "waves/errors"
+require_relative "waves/request"
+require_relative "waves/version"
+require_relative "waves/client"
+require_relative "waves/cli"
+
+module Waves
+  class << self
+    attr_accessor :timeout
+  end
+
+  self.timeout = 10
+end

data/waves-ruby.gemspec

@@ -0,0 +1,23 @@
+require_relative "lib/waves/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "waves-ruby"
+  spec.version = Waves::VERSION
+  spec.authors = ["Avi Flombaum"]
+  spec.email = ["git@avi.nyc"]
+  spec.summary = "Ruby API client and CLI for the Wave API"
+  spec.description = "A small Ruby API client and CLI for working with the Wave API."
+  spec.homepage = "https://github.com/aviflombaum/waves-gems"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases/tag/v#{spec.version}"
+
+  spec.files = Dir["*.md", "*.gemspec", "exe/*", "lib/**/*.rb"]
+  spec.bindir = "exe"
+  spec.executables = ["waves"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "httparty"
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: waves-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Avi Flombaum
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A small Ruby API client and CLI for working with the Wave API.
+email:
+- git@avi.nyc
+executables:
+- waves
+extensions: []
+extra_rdoc_files: []
+files:
+- CONTRIBUTING.md
+- README.md
+- exe/waves
+- lib/waves.rb
+- lib/waves/cli.rb
+- lib/waves/cli/app.rb
+- lib/waves/cli/formatter.rb
+- lib/waves/client.rb
+- lib/waves/config.rb
+- lib/waves/errors.rb
+- lib/waves/request.rb
+- lib/waves/version.rb
+- waves-ruby.gemspec
+homepage: https://github.com/aviflombaum/waves-gems
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/aviflombaum/waves-gems
+  changelog_uri: https://github.com/aviflombaum/waves-gems/releases/tag/v0.1.0
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby API client and CLI for the Wave API
+test_files: []