mythic-beasts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff19b7149b4146959d99412af78e9cc2ffe5b9c7a210faff7ee5fc83dbbcb957
+  data.tar.gz: e200bed772b3a84c4c39ed454ab4f2b957f066d3710d83d0b3fa9e5e77865d51
+SHA512:
+  metadata.gz: bf9e744f9f587ca9ea65d78a5d86b4cb6b20876770ec559667c94b635fc2d04687c510b5b125f8560560e33df4595142d6a2dae9a7307608e668cf082676303d
+  data.tar.gz: f5d16e71f563a97e9c4b570d7b90e7c48a0f546bc1ab3428b570feff147fed6f69453855e46e2de4682137a311a56b9ffcfd6a968f2edb9eded8ec18f75058ec

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-27
+
+### Added
+
+- Initial release by James Inman (@jfi)
+- OAuth2 authentication support with automatic token refresh
+- DNS API v2 client with full CRUD operations
+- VPS provisioning and management API
+- Comprehensive error handling with custom exception classes
+- Retry logic for transient failures
+- Convenience methods for common DNS record types (A, AAAA, CNAME, MX, TXT)
+- Complete test suite with RSpec and WebMock
+- StandardRB compliance for code style

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Otaina Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# Mythic Beasts Ruby Client
+
+A Ruby gem for interacting with [Mythic Beasts](https://www.mythic-beasts.com/) APIs including DNS management, VPS provisioning, and domain management.
+
+[![Gem Version](https://badge.fury.io/rb/mythic-beasts.svg)](https://badge.fury.io/rb/mythic-beasts)
+[![CI](https://github.com/tastybamboo/mythic-beasts/workflows/CI/badge.svg)](https://github.com/tastybamboo/mythic-beasts/actions)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mythic-beasts'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Get your API credentials from the [Mythic Beasts control panel](https://www.mythic-beasts.com/customer/api-keys).
+
+```ruby
+MythicBeasts.configure do |config|
+  config.api_key = 'your_api_key'
+  config.api_secret = 'your_api_secret'
+end
+```
+
+Or create a client directly:
+
+```ruby
+client = MythicBeasts::Client.new(
+  api_key: 'your_api_key',
+  api_secret: 'your_api_secret'
+)
+```
+
+## Usage
+
+### DNS Management
+
+```ruby
+# Get all zones
+zones = MythicBeasts.client.dns.zones
+
+# Get records for a zone
+records = MythicBeasts.client.dns.records('example.com')
+
+# Create an A record
+MythicBeasts.client.dns.create_a_record(
+  'example.com',
+  'www',
+  '1.2.3.4',
+  ttl: 300
+)
+
+# Create multiple records at once
+MythicBeasts.client.dns.create_records('example.com', [
+  { host: 'www', ttl: 300, type: 'A', data: '1.2.3.4' },
+  { host: 'mail', ttl: 300, type: 'A', data: '1.2.3.5' },
+  { host: '@', ttl: 300, type: 'MX', data: '10 mail.example.com' }
+])
+
+# Update records
+MythicBeasts.client.dns.update_records(
+  'example.com',
+  [{ host: 'www', ttl: 600, type: 'A', data: '1.2.3.6' }],
+  host: 'www',
+  type: 'A'
+)
+
+# Delete records
+MythicBeasts.client.dns.delete_records(
+  'example.com',
+  host: 'www',
+  type: 'A'
+)
+
+# Dynamic DNS update (updates to client IP)
+MythicBeasts.client.dns.dynamic_update('home.example.com')
+```
+
+### VPS Management
+
+```ruby
+# List all VPS servers
+servers = MythicBeasts.client.vps.list
+
+# Get server details
+server = MythicBeasts.client.vps.get('my-server')
+
+# Create a new VPS
+MythicBeasts.client.vps.create(
+  name: 'my-new-server',
+  type: 'VPS-2',
+  ssh_key: 'ssh-rsa AAAAB3...'
+)
+
+# Control servers
+MythicBeasts.client.vps.start('my-server')
+MythicBeasts.client.vps.stop('my-server')
+MythicBeasts.client.vps.restart('my-server')
+
+# Get console access
+console = MythicBeasts.client.vps.console('my-server')
+
+# Delete a server
+MythicBeasts.client.vps.delete('my-server')
+```
+
+## Error Handling
+
+The gem provides specific error classes:
+
+```ruby
+begin
+  MythicBeasts.client.dns.records('nonexistent.com')
+rescue MythicBeasts::NotFoundError => e
+  puts "Zone not found: #{e.message}"
+rescue MythicBeasts::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue MythicBeasts::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue MythicBeasts::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+Available error classes:
+- `MythicBeasts::Error` - Base error class
+- `MythicBeasts::AuthenticationError` - Invalid credentials
+- `MythicBeasts::NotFoundError` - Resource not found
+- `MythicBeasts::ValidationError` - Invalid parameters
+- `MythicBeasts::RateLimitError` - Rate limit exceeded
+- `MythicBeasts::ServerError` - Server-side error
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tastybamboo/mythic-beasts.
+
+## Author
+
+**James Inman** ([@jfi](https://github.com/jfi))
+- Email: james@otaina.co.uk
+- GitHub: https://github.com/tastybamboo
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Copyright (c) 2025 Otaina Limited
+
+## Resources
+
+- [Mythic Beasts API Documentation](https://www.mythic-beasts.com/support/api)
+- [DNS API v2 Docs](https://www.mythic-beasts.com/support/api/dnsv2)
+- [VPS API Docs](https://www.mythic-beasts.com/support/api/vps)

data/lib/mythic_beasts/auth.rb

@@ -0,0 +1,52 @@
+module MythicBeasts
+  class Auth
+    AUTH_URL = "https://auth.mythic-beasts.com/login"
+
+    attr_reader :api_key, :api_secret
+
+    def initialize(api_key:, api_secret:)
+      @api_key = api_key
+      @api_secret = api_secret
+      @token = nil
+      @token_expires_at = nil
+    end
+
+    def token
+      return @token if @token && !token_expired?
+
+      fetch_token
+      @token
+    end
+
+    private
+
+    def token_expired?
+      return true unless @token_expires_at
+
+      Time.now >= @token_expires_at
+    end
+
+    def fetch_token
+      response = connection.post do |req|
+        req.body = {grant_type: "client_credentials"}
+        req.options.timeout = 10
+      end
+
+      data = JSON.parse(response.body)
+      @token = data["access_token"]
+      # Expire token 30 seconds before actual expiry to be safe
+      @token_expires_at = Time.now + (data["expires_in"].to_i - 30)
+    rescue Faraday::Error => e
+      raise AuthenticationError, "Failed to authenticate: #{e.message}"
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: AUTH_URL) do |conn|
+        conn.request :authorization, :basic, api_key, api_secret
+        conn.request :url_encoded
+        conn.response :raise_error
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/mythic_beasts/client.rb

@@ -0,0 +1,70 @@
+module MythicBeasts
+  class Client
+    API_BASE_URL = "https://api.mythic-beasts.com"
+
+    attr_reader :auth, :dns, :vps
+
+    def initialize(api_key:, api_secret:)
+      @auth = Auth.new(api_key: api_key, api_secret: api_secret)
+      @dns = DNS.new(self)
+      @vps = VPS.new(self)
+    end
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body: {}, params: {})
+      request(:post, path, body: body, params: params)
+    end
+
+    def put(path, body: {}, params: {})
+      request(:put, path, body: body, params: params)
+    end
+
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    private
+
+    def request(method, path, body: {}, params: {})
+      response = connection.send(method) do |req|
+        req.url path
+        req.params = params if params.any?
+        req.body = body.to_json if body.any?
+      end
+
+      JSON.parse(response.body) if response.body && !response.body.empty?
+    rescue Faraday::UnauthorizedError, Faraday::ClientError => e
+      if e.response&.dig(:status) == 401
+        raise AuthenticationError, "Invalid credentials"
+      elsif e.response&.dig(:status) == 404
+        raise NotFoundError, e.message
+      elsif e.response&.dig(:status) == 400
+        raise ValidationError, e.message
+      elsif e.response&.dig(:status) == 429
+        raise RateLimitError, e.message
+      else
+        raise Error, e.message
+      end
+    rescue Faraday::ServerError => e
+      raise ServerError, e.message
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: API_BASE_URL) do |conn|
+        conn.request :authorization, :bearer, -> { auth.token }
+        conn.request :json
+        conn.request :retry, {
+          max: 3,
+          interval: 0.5,
+          backoff_factor: 2,
+          exceptions: [Faraday::ServerError]
+        }
+        conn.response :raise_error
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/mythic_beasts/dns.rb

@@ -0,0 +1,76 @@
+module MythicBeasts
+  class DNS
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # List all DNS zones
+    def zones
+      client.get("/dns/v2/zones")
+    end
+
+    # Get all records for a zone
+    def records(zone)
+      client.get("/dns/v2/zones/#{zone}/records")
+    end
+
+    # Get specific record(s) by host and type
+    def get_record(zone, host, type)
+      client.get("/dns/v2/zones/#{zone}/records/#{host}/#{type}")
+    end
+
+    # Create new DNS record(s)
+    # records: Array of hashes with keys: host, ttl, type, data
+    # Example: [{ host: 'www', ttl: 300, type: 'A', data: '1.2.3.4' }]
+    def create_records(zone, records)
+      client.post("/dns/v2/zones/#{zone}/records", body: {records: records})
+    end
+
+    # Replace record(s)
+    def update_records(zone, records, host: nil, type: nil)
+      path = "/dns/v2/zones/#{zone}/records"
+      path += "/#{host}" if host
+      path += "/#{type}" if type
+
+      client.put(path, body: {records: records})
+    end
+
+    # Delete record(s)
+    def delete_records(zone, host: nil, type: nil, data: nil)
+      path = "/dns/v2/zones/#{zone}/records"
+      path += "/#{host}" if host
+      path += "/#{type}" if type
+
+      params = data ? {data: data} : {}
+      client.delete(path, params: params)
+    end
+
+    # Dynamic DNS update - updates A/AAAA record to client IP
+    def dynamic_update(host)
+      client.put("/dns/v2/dynamic/#{host}")
+    end
+
+    # Convenience methods for common record types
+    def create_a_record(zone, host, ip, ttl: 300)
+      create_records(zone, [{host: host, ttl: ttl, type: "A", data: ip}])
+    end
+
+    def create_aaaa_record(zone, host, ip, ttl: 300)
+      create_records(zone, [{host: host, ttl: ttl, type: "AAAA", data: ip}])
+    end
+
+    def create_cname_record(zone, host, target, ttl: 300)
+      create_records(zone, [{host: host, ttl: ttl, type: "CNAME", data: target}])
+    end
+
+    def create_mx_record(zone, host, priority, mail_server, ttl: 300)
+      create_records(zone, [{host: host, ttl: ttl, type: "MX", data: "#{priority} #{mail_server}"}])
+    end
+
+    def create_txt_record(zone, host, text, ttl: 300)
+      create_records(zone, [{host: host, ttl: ttl, type: "TXT", data: text}])
+    end
+  end
+end

data/lib/mythic_beasts/errors.rb

@@ -0,0 +1,8 @@
+module MythicBeasts
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class ValidationError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+end

data/lib/mythic_beasts/version.rb

@@ -0,0 +1,3 @@
+module MythicBeasts
+  VERSION = "0.1.0"
+end

data/lib/mythic_beasts/vps.rb

@@ -0,0 +1,61 @@
+module MythicBeasts
+  class VPS
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # List all VPS servers
+    def list
+      client.get("/api/vps")
+    end
+
+    # Get details of a specific VPS
+    def get(server_name)
+      client.get("/api/vps/#{server_name}")
+    end
+
+    # Create a new VPS
+    # Options:
+    #   - name: Server name
+    #   - type: Server type (e.g., 'VPS-1', 'VPS-2')
+    #   - disk: Disk size in GB
+    #   - ssh_key: SSH public key for access
+    def create(name:, type:, ssh_key: nil, **options)
+      body = {
+        name: name,
+        type: type,
+        **options
+      }
+      body[:ssh_key] = ssh_key if ssh_key
+
+      client.post("/api/vps", body: body)
+    end
+
+    # Start a VPS
+    def start(server_name)
+      client.post("/api/vps/#{server_name}/start")
+    end
+
+    # Stop a VPS
+    def stop(server_name)
+      client.post("/api/vps/#{server_name}/stop")
+    end
+
+    # Restart a VPS
+    def restart(server_name)
+      client.post("/api/vps/#{server_name}/restart")
+    end
+
+    # Delete a VPS
+    def delete(server_name)
+      client.delete("/api/vps/#{server_name}")
+    end
+
+    # Get VPS console access
+    def console(server_name)
+      client.get("/api/vps/#{server_name}/console")
+    end
+  end
+end

data/lib/mythic_beasts.rb

@@ -0,0 +1,24 @@
+require "faraday"
+require "faraday/retry"
+require "json"
+
+require_relative "mythic_beasts/version"
+require_relative "mythic_beasts/client"
+require_relative "mythic_beasts/auth"
+require_relative "mythic_beasts/dns"
+require_relative "mythic_beasts/vps"
+require_relative "mythic_beasts/errors"
+
+module MythicBeasts
+  class << self
+    attr_accessor :api_key, :api_secret
+
+    def configure
+      yield self
+    end
+
+    def client
+      @client ||= Client.new(api_key: api_key, api_secret: api_secret)
+    end
+  end
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: mythic-beasts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Inman
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: A Ruby gem for interacting with Mythic Beasts APIs including DNS, VPS
+  provisioning, and domain management
+email:
+- james@otaina.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mythic_beasts.rb
+- lib/mythic_beasts/auth.rb
+- lib/mythic_beasts/client.rb
+- lib/mythic_beasts/dns.rb
+- lib/mythic_beasts/errors.rb
+- lib/mythic_beasts/version.rb
+- lib/mythic_beasts/vps.rb
+homepage: https://github.com/tastybamboo/mythic-beasts
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tastybamboo/mythic-beasts
+  source_code_uri: https://github.com/tastybamboo/mythic-beasts
+  changelog_uri: https://github.com/tastybamboo/mythic-beasts/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby client for Mythic Beasts API
+test_files: []