w3c_api 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/w3c_api

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'w3c_api'
+
+W3cApi::Cli.start(ARGV)

data/lib/w3c_api/cli.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'commands/specification'
+require_relative 'commands/group'
+require_relative 'commands/user'
+require_relative 'commands/translation'
+require_relative 'commands/ecosystem'
+require_relative 'commands/series'
+require_relative 'commands/affiliation'
+require_relative 'commands/participation'
+
+module W3cApi
+    # Main CLI class that registers all subcommands
+    class Cli < Thor
+      # Register subcommands
+      desc 'specification SUBCOMMAND ...ARGS', 'Work with W3C specifications'
+      subcommand 'specification', Commands::Specification
+
+      desc 'group SUBCOMMAND ...ARGS', 'Work with W3C groups'
+      subcommand 'group', Commands::Group
+
+      desc 'user SUBCOMMAND ...ARGS', 'Work with W3C users'
+      subcommand 'user', Commands::User
+
+      desc 'translation SUBCOMMAND ...ARGS', 'Work with W3C translations'
+      subcommand 'translation', Commands::Translation
+
+      desc 'ecosystem SUBCOMMAND ...ARGS', 'Work with W3C ecosystems'
+      subcommand 'ecosystem', Commands::Ecosystem
+
+      desc 'series SUBCOMMAND ...ARGS', 'Work with W3C specification series'
+      subcommand 'series', Commands::Series
+
+      desc 'affiliation SUBCOMMAND ...ARGS', 'Work with W3C affiliations'
+      subcommand 'affiliation', Commands::Affiliation
+
+      desc 'participation SUBCOMMAND ...ARGS', 'Work with W3C participations'
+      subcommand 'participation', Commands::Participation
+    end
+end

data/lib/w3c_api/client.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/follow_redirects'
+require 'json'
+
+module W3cApi
+  class Error < StandardError; end
+  class NotFoundError < Error; end
+  class UnauthorizedError < Error; end
+  class BadRequestError < Error; end
+  class ServerError < Error; end
+
+  class Client
+    API_ENDPOINT = 'https://api.w3.org'
+
+    attr_reader :last_response
+
+    def initialize(options = {})
+      @api_endpoint = options[:api_endpoint] || API_ENDPOINT
+      @connection = create_connection
+      @params_default = { page: 1, items: 3000 }
+      @debug = !ENV['DEBUG_API'].nil?
+    end
+
+    # Specification methods
+
+    def specifications(options = {})
+      response = get('specifications', options.merge(@params_default))
+      Models::Specifications.from_response(response['_links']['specifications'])
+    end
+
+    def specification(shortname, options = {})
+      response = get("specifications/#{shortname}", options)
+      Models::Specification.from_response(response)
+    end
+
+    def specification_versions(shortname, options = {})
+      response = get("specifications/#{shortname}/versions", options)
+      Models::SpecVersions.from_response(response['_links']['version-history'])
+    end
+
+    def specification_version(shortname, version, options = {})
+      response = get("specifications/#{shortname}/versions/#{version}", options)
+      Models::SpecVersion.from_response(response)
+    end
+
+    def specifications_by_status(status, options = {})
+      response = get("specifications-by-status/#{status}", options.merge(@params_default))
+      Models::Specifications.from_response(response['_links']['specifications'])
+    end
+
+    def specification_supersedes(shortname, options = {})
+      response = get("specifications/#{shortname}/supersedes", options)
+      Models::Specifications.from_response(response['_links']['specifications'])
+    end
+
+    def specification_superseded_by(shortname, options = {})
+      response = get("specifications/#{shortname}/superseded", options)
+      Models::Specifications.from_response(response['_links']['specifications'])
+    end
+
+    # Series methods
+
+    def series(options = {})
+      response = get('specification-series', options.merge(@params_default))
+      Models::Series.from_response(response['_links']['specification-series'])
+    end
+
+    def series_by_shortname(shortname, options = {})
+      response = get("specification-series/#{shortname}", options)
+      Models::Serie.from_response(response)
+    end
+
+    def series_specifications(shortname, options = {})
+      response = get("specification-series/#{shortname}/specifications", options.merge(@params_default))
+      Models::Specifications.from_response(response['_links']['specifications'])
+    end
+
+    # Group methods
+
+    def groups(options = {})
+      response = get('groups', options)
+      Models::Groups.from_response(response['_links']['groups'])
+    end
+
+    def group(id, options = {})
+      response = get("groups/#{id}", options)
+      Models::Group.from_response(response)
+    end
+
+    def group_specifications(id, options = {})
+      response = get("groups/#{id}/specifications", options)
+      Models::Specifications.from_response(response['_links']['specifications'])
+    end
+
+    def group_users(id, options = {})
+      response = get("groups/#{id}/users", options)
+      Models::Users.from_response(response['_links']['users'])
+    end
+
+    def group_charters(id, options = {})
+      response = get("groups/#{id}/charters", options)
+      Models::Charters.from_response(response['_links']['charters'])
+    end
+
+    def group_chairs(id, options = {})
+      response = get("groups/#{id}/chairs", options)
+      Models::Users.from_response(response['_links']['chairs'])
+    rescue NotFoundError
+      # Return empty users collection when endpoint not found
+      Models::Users.from_response([])
+    end
+
+    def group_team_contacts(id, options = {})
+      response = get("groups/#{id}/teamcontacts", options)
+      Models::Users.from_response(response['_links']['team-contacts'])
+    rescue NotFoundError
+      # Return empty users collection when endpoint not found
+      Models::Users.from_response([])
+    end
+
+    def group_participations(id, options = {})
+      response = get("groups/#{id}/participations", options)
+      Models::Participations.from_response(response['_links']['participations'])
+    end
+
+    # User methods
+
+    def users(options = {})
+      raise ArgumentError,
+            'The W3C API does not support fetching all users. You must provide a specific user ID with the user method.'
+    end
+
+    def user(id, options = {})
+      response = get("users/#{id}", options)
+      Models::User.from_response(response)
+    end
+
+    def user_specifications(id, options = {})
+      response = get("users/#{id}/specifications", options)
+      Models::Specifications.from_response(response['_links']['specifications'])
+    rescue NotFoundError
+      # Return empty specifications collection when endpoint not found
+      Models::Specifications.from_response([])
+    end
+
+    def user_groups(id, options = {})
+      response = get("users/#{id}/groups", options)
+      Models::Groups.from_response(response['_links']['groups'])
+    end
+
+    def user_affiliations(id, options = {})
+      response = get("users/#{id}/affiliations", options)
+      Models::Affiliations.from_response(response['_links']['affiliations'])
+    rescue NotFoundError
+      # Return empty affiliations collection when endpoint not found
+      Models::Affiliations.from_response([])
+    end
+
+    def user_participations(id, options = {})
+      response = get("users/#{id}/participations", options)
+      Models::Participations.from_response(response['_links']['participations'])
+    rescue NotFoundError
+      # Return empty participations collection when endpoint not found
+      Models::Participations.from_response([])
+    end
+
+    def user_chair_of_groups(id, options = {})
+      response = get("users/#{id}/chair-of-groups", options)
+      Models::Groups.from_response(response['_links']['groups'])
+    rescue NotFoundError
+      # Return empty groups collection when endpoint not found
+      Models::Groups.from_response([])
+    end
+
+    def user_team_contact_of_groups(id, options = {})
+      response = get("users/#{id}/team-contact-of-groups", options)
+      Models::Groups.from_response(response['_links']['groups'])
+    rescue NotFoundError
+      # Return empty groups collection when endpoint not found
+      Models::Groups.from_response([])
+    end
+
+    # Translation methods
+
+    def translations(options = {})
+      response = get('translations', options.merge(embed: true))
+      Models::Translations.from_response(response['_links']['translations'])
+    end
+
+    def translation(id, options = {})
+      response = get("translations/#{id}", options)
+      Models::Translation.from_response(response)
+    end
+
+    # Affiliation methods
+
+    def affiliations(options = {})
+      response = get('affiliations', options.merge(@params_default))
+      Models::Affiliations.from_response(response['_links']['affiliations'])
+    end
+
+    def affiliation(id, options = {})
+      response = get("affiliations/#{id}", options)
+      Models::Affiliation.from_response(response)
+    end
+
+    def affiliation_participants(id, options = {})
+      response = get("affiliations/#{id}/participants", options)
+      Models::Users.from_response(response['_links']['participants'])
+    end
+
+    def affiliation_participations(id, options = {})
+      response = get("affiliations/#{id}/participations", options)
+      Models::Participations.from_response(response['_links']['participations'])
+    end
+
+    # Ecosystem methods
+
+    def ecosystems(options = {})
+      response = get('ecosystems', options)
+      Models::Ecosystems.from_response(response['_links']['ecosystems'])
+    end
+
+    def ecosystem(shortname, options = {})
+      response = get("ecosystems/#{shortname}", options)
+      Models::Ecosystem.from_response(response)
+    end
+
+    def ecosystem_groups(shortname, options = {})
+      response = get("ecosystems/#{shortname}/groups", options)
+      Models::Groups.from_response(response['_links']['groups'])
+    end
+
+    def ecosystem_evangelists(shortname, options = {})
+      response = get("ecosystems/#{shortname}/evangelists", options)
+      Models::Users.from_response(response['_links']['users'])
+    end
+
+    def ecosystem_member_organizations(shortname, options = {})
+      response = get("ecosystems/#{shortname}/member-organizations", options)
+      Models::Affiliations.from_response(response['_links']['affiliations'])
+    end
+
+    # Participation methods
+
+    def participation(id, options = {})
+      response = get("participations/#{id}", options)
+      Models::Participation.from_response(response)
+    end
+
+    def participation_participants(id, options = {})
+      response = get("participations/#{id}/participants", options)
+      Models::Users.from_response(response['_links']['users'])
+    end
+
+    # Make the get method public for testing
+    def get(url, params = {})
+      @last_response = @connection.get(url, params)
+      handle_response(@last_response, url)
+    end
+
+    private
+
+    def create_connection
+      Faraday.new(url: @api_endpoint) do |conn|
+        conn.use Faraday::FollowRedirects::Middleware
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response, url)
+      debug_log(response, url) if @debug
+
+      case response.status
+      when 200..299
+        response.body
+      when 400
+        raise W3cApi::BadRequestError, response_message(response)
+      when 401
+        raise W3cApi::UnauthorizedError, response_message(response)
+      when 404
+        raise W3cApi::NotFoundError, response_message(response)
+      when 500..599
+        raise W3cApi::ServerError, response_message(response)
+      else
+        raise W3cApi::Error, response_message(response)
+      end
+    end
+
+    def debug_log(response, url)
+      puts "\n===== DEBUG: W3C API REQUEST =====".blue if defined?(Rainbow)
+      puts "\n===== DEBUG: W3C API REQUEST =====" unless defined?(Rainbow)
+      puts "URL: #{url}"
+      puts "Status: #{response.status}"
+
+      # Format headers as JSON
+      puts "\nHeaders:"
+      headers_hash = response.headers.to_h
+      puts JSON.pretty_generate(headers_hash)
+
+      puts "\nResponse body:"
+      if response.body.is_a?(Hash) || response.body.is_a?(Array)
+        puts JSON.pretty_generate(response.body)
+      else
+        puts response.body.inspect
+      end
+      puts "===== END DEBUG OUTPUT =====\n"
+    end
+
+    def response_message(response)
+      message = "Status: #{response.status}"
+      message += ", Error: #{response.body['error']}" if response.body.is_a?(Hash) && response.body['error']
+      message
+    end
+  end # End of Client class
+end # End of W3c module

data/lib/w3c_api/commands/affiliation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'output_formatter'
+require_relative '../client'
+
+module W3cApi
+    module Commands
+      # Thor CLI command for affiliation operations
+      class Affiliation < Thor
+        include OutputFormatter
+
+        desc 'fetch [OPTIONS]', 'Fetch affiliations'
+        option :id, type: :numeric, desc: 'Affiliation ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def fetch
+          client = W3cApi::Client.new
+
+          affiliations = if options[:id]
+                           # Single affiliation
+                           client.affiliation(options[:id])
+                         else
+                           client.affiliations
+                         end
+
+          output_results(affiliations, options[:format])
+        end
+
+        desc 'participants', 'Fetch participants of an affiliation'
+        option :id, type: :numeric, required: true, desc: 'Affiliation ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def participants
+          client = W3cApi::Client.new
+          participants = client.affiliation_participants(options[:id])
+          output_results(participants, options[:format])
+        end
+
+        desc 'participations', 'Fetch participations of an affiliation'
+        option :id, type: :numeric, required: true, desc: 'Affiliation ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def participations
+          client = W3cApi::Client.new
+          participations = client.affiliation_participations(options[:id])
+          output_results(participations, options[:format])
+        end
+      end
+    end
+end

data/lib/w3c_api/commands/ecosystem.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'output_formatter'
+require_relative '../client'
+
+module W3cApi
+    module Commands
+      # Thor CLI command for ecosystem operations
+      class Ecosystem < Thor
+        include OutputFormatter
+
+        desc 'fetch [OPTIONS]', 'Fetch ecosystems'
+        option :shortname, type: :string, desc: 'Ecosystem shortname'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def fetch
+          client = W3cApi::Client.new
+
+          ecosystems = if options[:shortname]
+                         # Single ecosystem
+                         client.ecosystem(options[:shortname])
+                       else
+                         client.ecosystems
+                       end
+
+          output_results(ecosystems, options[:format])
+        end
+
+        desc 'groups', 'Fetch groups in an ecosystem'
+        option :shortname, type: :string, required: true, desc: 'Ecosystem shortname'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def groups
+          client = W3cApi::Client.new
+          groups = client.ecosystem_groups(options[:shortname])
+          output_results(groups, options[:format])
+        end
+
+        desc 'evangelists', 'Fetch evangelists of an ecosystem'
+        option :shortname, type: :string, required: true, desc: 'Ecosystem shortname'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def evangelists
+          client = W3cApi::Client.new
+          evangelists = client.ecosystem_evangelists(options[:shortname])
+          output_results(evangelists, options[:format])
+        end
+
+        desc 'member-organizations', 'Fetch member organizations of an ecosystem'
+        option :shortname, type: :string, required: true, desc: 'Ecosystem shortname'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def member_organizations
+          client = W3cApi::Client.new
+          organizations = client.ecosystem_member_organizations(options[:shortname])
+          output_results(organizations, options[:format])
+        end
+      end
+    end
+end

data/lib/w3c_api/commands/group.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'output_formatter'
+require_relative '../client'
+
+module W3cApi
+    module Commands
+      # Thor CLI command for group operations
+      class Group < Thor
+        include OutputFormatter
+
+        desc 'fetch [OPTIONS]', 'Fetch groups'
+        option :id, type: :string, desc: 'Group ID'
+        option :type, type: :string, desc: 'Group type'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def fetch
+          client = W3cApi::Client.new
+
+          groups = if options[:id]
+                     # Single group
+                     client.group(options[:id])
+                   elsif options[:type]
+                     client.groups(type: options[:type])
+                   else
+                     client.groups
+                   end
+
+          output_results(groups, options[:format])
+        end
+
+        desc 'users', 'Fetch users in a group'
+        option :id, type: :numeric, required: true, desc: 'Group ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def users
+          client = W3cApi::Client.new
+          users = client.group_users(options[:id])
+          output_results(users, options[:format])
+        end
+
+        desc 'specifications', 'Fetch specifications produced by a group'
+        option :id, type: :numeric, required: true, desc: 'Group ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def specifications
+          client = W3cApi::Client.new
+          specifications = client.group_specifications(options[:id])
+          output_results(specifications, options[:format])
+        end
+
+        desc 'charters', 'Fetch charters of a group'
+        option :id, type: :numeric, required: true, desc: 'Group ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def charters
+          client = W3cApi::Client.new
+          charters = client.group_charters(options[:id])
+          output_results(charters, options[:format])
+        end
+
+        desc 'chairs', 'Fetch chairs of a group'
+        option :id, type: :numeric, required: true, desc: 'Group ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def chairs
+          client = W3cApi::Client.new
+          chairs = client.group_chairs(options[:id])
+          output_results(chairs, options[:format])
+        end
+
+        desc 'team-contacts', 'Fetch team contacts of a group'
+        option :id, type: :numeric, required: true, desc: 'Group ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def team_contacts
+          client = W3cApi::Client.new
+          team_contacts = client.group_team_contacts(options[:id])
+          output_results(team_contacts, options[:format])
+        end
+
+        desc 'participations', 'Fetch participations in a group'
+        option :id, type: :numeric, required: true, desc: 'Group ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def participations
+          client = W3cApi::Client.new
+          participations = client.group_participations(options[:id])
+          output_results(participations, options[:format])
+        end
+      end
+    end
+end

data/lib/w3c_api/commands/output_formatter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module W3cApi
+    module Commands
+      module OutputFormatter
+        # Format and output results based on the specified format
+        def output_results(results, format)
+          case format
+          when 'yaml'
+            puts results.to_yaml
+          else
+            # Default to JSON if format is not recognized
+            puts results.to_json
+          end
+        end
+      end
+    end
+end

data/lib/w3c_api/commands/participation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'output_formatter'
+require_relative '../client'
+
+module W3cApi
+    module Commands
+      # Thor CLI command for participation operations
+      class Participation < Thor
+        include OutputFormatter
+
+        desc 'fetch', 'Fetch a participation by ID'
+        option :id, type: :numeric, required: true, desc: 'Participation ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def fetch
+          client = W3cApi::Client.new
+          participation = client.participation(options[:id])
+          # Wrap in a collection for consistent output
+          participations = Models::Participations.new(participations: [participation])
+          output_results(participations, options[:format])
+        end
+
+        desc 'participants', 'Fetch participants in a participation'
+        option :id, type: :numeric, required: true, desc: 'Participation ID'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def participants
+          client = W3cApi::Client.new
+          participants = client.participation_participants(options[:id])
+          output_results(participants, options[:format])
+        end
+      end
+    end
+end

data/lib/w3c_api/commands/series.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'output_formatter'
+require_relative '../client'
+
+module W3cApi
+    module Commands
+      # Thor CLI command for series operations
+      class Series < Thor
+        include OutputFormatter
+
+        desc 'fetch [OPTIONS]', 'Fetch specification series'
+        option :shortname, type: :string, desc: 'Series shortname'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def fetch
+          client = W3cApi::Client.new
+
+          series = if options[:shortname]
+                     # Single series
+                     client.series_by_shortname(options[:shortname])
+                   else
+                     # All series
+                     client.series
+                   end
+
+          output_results(series, options[:format])
+        end
+
+        desc 'specifications', 'Fetch specifications in a series'
+        option :shortname, type: :string, required: true, desc: 'Series shortname'
+        option :format, type: :string, default: 'yaml', enum: %w[json yaml], desc: 'Output format'
+        def specifications
+          client = W3cApi::Client.new
+          specifications = client.series_specifications(options[:shortname])
+          output_results(specifications, options[:format])
+        end
+      end
+    end
+end