fathom-ruby 1.0.0

data/TESTING.md

@@ -0,0 +1,123 @@
+# Testing the Gem
+
+## Running Unit Tests
+
+Run the full test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run specific test files:
+
+```bash
+bundle exec rspec spec/fathom/client_spec.rb
+bundle exec rspec spec/fathom/resources/meeting_spec.rb
+```
+
+Run with coverage:
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+## Testing Against Live API
+
+We've created an integration test script that you can run against your real Fathom account.
+
+### Quick Start
+
+1. Get your API key from [Fathom Settings](https://app.fathom.video/settings/integrations)
+
+2. Run the test script:
+
+```bash
+FATHOM_API_KEY=your_key_here ruby scripts/test_live_api.rb
+```
+
+### Using .env File (Recommended)
+
+For convenience, create a `.env` file (already in `.gitignore`):
+
+```bash
+# Create .env file with your API key
+echo "FATHOM_API_KEY=your_actual_api_key_here" > .env
+
+# Load and run
+source .env
+ruby scripts/test_live_api.rb
+```
+
+### What Gets Tested
+
+The live API test script verifies:
+
+- ✅ **Meetings API**: List, attributes, summaries, transcripts
+- ✅ **Teams API**: List teams and members
+- ✅ **Team Members API**: List all members
+- ✅ **Webhooks API**: Full CRUD (list, create, retrieve, delete)
+- ✅ **Error Handling**: 404 responses
+- ✅ **Rate Limiting**: Header processing
+- ✅ **Pagination**: Limit parameters
+
+### Sample Output
+
+```
+✓ Fathom API Test Suite
+  Testing against live API with your credentials
+
+================================================================================
+  1. Testing Meetings API
+================================================================================
+  Fetch meetings list... ✓ PASS
+    Found 5 meeting(s)
+
+    First meeting details:
+      ID: 123456
+      Title: Weekly Team Sync
+      Created: 2025-01-15T10:00:00Z
+      Recording ID: 789012
+
+  Access meeting attributes... ✓ PASS
+  Fetch meeting summary... ✓ PASS
+  Fetch meeting transcript... ✓ PASS
+
+...
+
+================================================================================
+  Test Results Summary
+================================================================================
+
+  Passed:  15
+  Failed:  0
+  Skipped: 0
+  Total:   15
+
+  Pass Rate: 100.0%
+
+✓ All tests passed!
+```
+
+### Important Notes
+
+- **Mostly Read-Only**: Performs GET requests for meetings, teams, and team members
+- **Webhook Testing**: Creates a temporary test webhook and immediately deletes it
+- **Safe**: Test webhook is automatically cleaned up - run as many times as you want
+- **Rate Limits**: Automatically handled with retries
+
+See `scripts/README.md` for more details.
+
+## Code Quality
+
+Check code style:
+
+```bash
+bundle exec rubocop
+```
+
+Auto-fix issues:
+
+```bash
+bundle exec rubocop -A
+```

data/fathom-ruby.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/fathom/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "fathom-ruby"
+  spec.version = Fathom::VERSION
+  spec.authors = ["Juan Rodriguez"]
+  spec.email = ["jrodriguez@example.com"]
+
+  spec.summary = "Ruby library for the Fathom API"
+  spec.description = "A comprehensive Ruby gem for interacting with the Fathom API, supporting meetings, \
+                      recordings, teams, webhooks, and more."
+  spec.homepage = "https://github.com/yourusername/fathom-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies - none! Using only Ruby stdlib
+  # Development dependencies are specified in Gemfile
+end

data/lib/fathom/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Fathom
+  class Client
+    BASE_URL = "https://api.fathom.ai/external/v1"
+
+    attr_reader :rate_limiter
+
+    def initialize
+      @rate_limiter = RateLimiter.new
+    end
+
+    def get(path, params = {}) = request(:get, path, params:)
+
+    def post(path, body = {}) = request(:post, path, body:)
+
+    def put(path, body = {}) = request(:put, path, body:)
+
+    def patch(path, body = {}) = request(:patch, path, body:)
+
+    def delete(path) = request(:delete, path)
+
+    private
+
+    def request(method, path, params: {}, body: {}, retry_count: 0)
+      uri = build_uri(path, params)
+      http = build_http(uri)
+      request_obj = build_request(method, uri, body)
+
+      Fathom.log_http("#{method.upcase} #{uri}")
+      Fathom.log_http("Headers: #{request_obj.to_hash}") if Fathom.debug_http
+      Fathom.log_http("Body: #{body.to_json}") if Fathom.debug_http && body.present?
+
+      response = http.request(request_obj)
+
+      Fathom.log_http("Response: #{response.code} #{response.message}")
+      @rate_limiter.update_from_headers(response.to_hash)
+
+      handle_response(response, method, path, params, body, retry_count)
+    end
+
+    def build_uri(path, params)
+      # Ensure path starts with /
+      path = "/#{path}" unless path.start_with?("/")
+      uri = URI.parse("#{BASE_URL}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = 60
+      http.open_timeout = 30
+      http
+    end
+
+    def build_request(method, uri, body)
+      request_class =
+        case method
+        in :get then Net::HTTP::Get
+        in :post then Net::HTTP::Post
+        in :put then Net::HTTP::Put
+        in :patch then Net::HTTP::Patch
+        in :delete then Net::HTTP::Delete
+        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+      request = request_class.new(uri)
+      request["X-Api-Key"] = Fathom.api_key
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "fathom-ruby/#{Fathom::VERSION}"
+
+      request.body = body.to_json unless body.empty?
+
+      request
+    end
+
+    def handle_response(response, method, path, params, body, retry_count)
+      case response.code.to_i
+      when 200, 201
+        parse_json(response.body)
+      when 204
+        {} # No content
+      when 400
+        raise BadRequestError.new(parse_error_message(response), response: response, http_status: 400)
+      when 401
+        raise AuthenticationError.new(parse_error_message(response), response: response, http_status: 401)
+      when 403
+        raise ForbiddenError.new(parse_error_message(response), response: response, http_status: 403)
+      when 404
+        raise NotFoundError.new(parse_error_message(response), response: response, http_status: 404)
+      when 429
+        handle_rate_limit(response, method, path, params, body, retry_count)
+      when 500..599
+        raise ServerError.new(parse_error_message(response), response: response, http_status: response.code.to_i)
+      else
+        raise Error.new("Unexpected response: #{response.code}", response: response, http_status: response.code.to_i)
+      end
+    end
+
+    def handle_rate_limit(response, method, path, params, body, retry_count)
+      if Fathom.auto_retry && retry_count < Fathom.max_retries
+        wait_time = calculate_backoff(retry_count)
+        Fathom.log("Rate limited. Retrying in #{wait_time}s (attempt #{retry_count + 1}/#{Fathom.max_retries})")
+        sleep(wait_time)
+        request(method, path, params: params, body: body, retry_count: retry_count + 1)
+      else
+        raise RateLimitError.new(
+          parse_error_message(response),
+          response: response,
+          http_status: 429,
+          headers: response.to_hash
+        )
+      end
+    end
+
+    # Exponential backoff: 2^retry_count seconds, max 60 seconds
+    def calculate_backoff(retry_count) = [2**retry_count, 60].min
+
+    def parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      Fathom.log("Failed to parse JSON: #{e.message}")
+      {}
+    end
+
+    def parse_error_message(response)
+      body = parse_json(response.body)
+      body["error"] || body["message"] || "HTTP #{response.code}: #{response.message}"
+    rescue StandardError
+      "HTTP #{response.code}: #{response.message}"
+    end
+  end
+end

data/lib/fathom/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fathom
+  # Base error class for all Fathom errors
+  class Error < StandardError
+    attr_reader :response, :http_status
+
+    def initialize(message = nil, response: nil, http_status: nil)
+      @response = response
+      @http_status = http_status
+      super(message)
+    end
+  end
+
+  # Raised when API authentication fails (401)
+  class AuthenticationError < Error; end
+
+  # Raised when a resource is not found (404)
+  class NotFoundError < Error; end
+
+  # Raised when rate limit is exceeded (429)
+  class RateLimitError < Error
+    attr_reader :rate_limit_remaining, :rate_limit_reset
+
+    def initialize(message = nil, response: nil, http_status: nil, headers: {})
+      @rate_limit_remaining = headers["RateLimit-Remaining"]&.to_i
+      @rate_limit_reset = headers["RateLimit-Reset"]&.to_i
+      super(message, response: response, http_status: http_status)
+    end
+  end
+
+  # Raised when the server returns a 5xx error
+  class ServerError < Error; end
+
+  # Raised when the API returns a bad request (400)
+  class BadRequestError < Error; end
+
+  # Raised when the API returns a forbidden error (403)
+  class ForbiddenError < Error; end
+end

data/lib/fathom/rate_limiter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Fathom
+  class RateLimiter
+    attr_reader :limit, :remaining, :reset
+
+    def initialize
+      @limit = nil
+      @remaining = nil
+      @reset = nil
+    end
+
+    def update_from_headers(headers)
+      @limit = extract_header_value(headers, "RateLimit-Limit")&.to_i
+      @remaining = extract_header_value(headers, "RateLimit-Remaining")&.to_i
+      @reset = extract_header_value(headers, "RateLimit-Reset")&.to_i
+
+      Fathom.log("Rate limit: #{@remaining}/#{@limit}, resets in #{@reset}s")
+    end
+
+    def should_retry? = Fathom.auto_retry && @remaining&.zero?
+
+    def wait_time
+      return 0 unless @reset
+
+      # Add a small buffer
+      @reset + 1
+    end
+
+    def rate_limited? = @remaining&.zero?
+
+    def to_h = { limit: @limit, remaining: @remaining, reset: @reset }
+
+    private
+
+    def extract_header_value(headers, key)
+      # Net::HTTP lowercases header keys, but direct hash access might not
+      # Try original case first, then lowercase (for Net::HTTP)
+      value = headers[key] || headers[key.downcase]
+      # Handle both string and array formats (Net::HTTP returns arrays)
+      value.is_a?(Array) ? value.first : value
+    end
+  end
+end

data/lib/fathom/resource.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Fathom
+  class Resource
+    attr_reader :attributes, :rate_limit_info
+
+    def initialize(attributes = {}, rate_limit_info: nil)
+      @attributes = attributes
+      @rate_limit_info = rate_limit_info
+    end
+
+    def id = @attributes["id"]
+
+    def [](key) = @attributes[key.to_s]
+
+    def []=(key, value)
+      @attributes[key.to_s] = value
+    end
+
+    def to_h = @attributes
+
+    def to_json(...) = @attributes.to_json(...)
+
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} id=#{id.inspect} #{@attributes.keys.join(", ")}>"
+    end
+
+    # Dynamic attribute access
+    def method_missing(method_name, *args, &)
+      method_str = method_name.to_s
+      if method_str.end_with?("=")
+        @attributes[method_str.chop] = args.first
+      elsif @attributes.key?(method_str)
+        @attributes[method_str]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_str = method_name.to_s
+      method_str.end_with?("=") || @attributes.key?(method_str) || super
+    end
+
+    class << self
+      def client = @client ||= Client.new
+
+      def resource_name = name.split("::").last.downcase
+
+      def resource_path = "#{resource_name}s"
+
+      def all(params = {})
+        response = client.get(resource_path, params)
+        # Fathom API returns items array
+        data = response["items"] || response["data"] || []
+
+        data.map { |attrs| new(attrs, rate_limit_info: client.rate_limiter.to_h) }
+      end
+
+      def retrieve(id)
+        response = client.get("#{resource_path}/#{id}")
+        data = response["data"] || response[resource_name] || response
+
+        new(data, rate_limit_info: client.rate_limiter.to_h)
+      end
+
+      def create(attributes = {})
+        response = client.post(resource_path, attributes)
+        data = response["data"] || response[resource_name] || response
+
+        new(data, rate_limit_info: client.rate_limiter.to_h)
+      end
+
+      def search(query, params = {})
+        search_params = params.merge(q: query)
+        response = client.get("#{resource_path}/search", search_params)
+        data = response["data"] || response[resource_path] || []
+
+        data.map { |attrs| new(attrs, rate_limit_info: client.rate_limiter.to_h) }
+      end
+    end
+
+    def update(attributes = {})
+      response = self.class.client.patch("#{self.class.resource_path}/#{id}", attributes)
+      data = response["data"] || response[self.class.resource_name] || response
+
+      @attributes.merge!(data)
+      @rate_limit_info = self.class.client.rate_limiter.to_h
+
+      self
+    end
+
+    def delete
+      self.class.client.delete("#{self.class.resource_path}/#{id}")
+      @rate_limit_info = self.class.client.rate_limiter.to_h
+
+      true
+    end
+
+    def reload
+      response = self.class.client.get("#{self.class.resource_path}/#{id}")
+      data = response["data"] || response[self.class.resource_name] || response
+
+      @attributes = data
+      @rate_limit_info = self.class.client.rate_limiter.to_h
+
+      self
+    end
+  end
+end

data/lib/fathom/resources/meeting.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Fathom
+  class Meeting < Resource
+    def self.resource_path = "meetings"
+
+    # Get the recording ID for this meeting
+    def recording_id = self["recording_id"]
+
+    # Get the summary for this meeting (use include_summary=true when listing)
+    # Returns the default_summary object or nil
+    def summary = self["default_summary"]
+
+    # Get the transcript for this meeting (use include_transcript=true when listing)
+    # Returns array of transcript segments or nil
+    def transcript = self["transcript"]
+
+    # Fetch the recording summary from the API
+    def fetch_summary(destination_url: nil)
+      return nil unless recording_id
+
+      Recording.get_summary(recording_id, destination_url:)
+    end
+
+    # Fetch the recording transcript from the API
+    def fetch_transcript(destination_url: nil)
+      return nil unless recording_id
+
+      Recording.get_transcript(recording_id, destination_url:)
+    end
+
+    # Check if the meeting has a recording
+    def recording? = !recording_id.nil?
+
+    # Get meeting participants (calendar invitees)
+    def participants = self["calendar_invitees"] || []
+
+    # Get action items for the meeting
+    def action_items = self["action_items"] || []
+  end
+end

data/lib/fathom/resources/recording.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Fathom
+  class Recording < Resource
+    def self.resource_path = "recordings"
+
+    # Get summary for a recording
+    # @param recording_id [Integer] The recording ID
+    # @param destination_url [String, nil] Optional webhook URL for async delivery
+    # @return [Hash] Summary data or destination confirmation
+    def self.get_summary(recording_id, destination_url: nil)
+      params = destination_url ? { destination_url: } : {}
+      response = client.get("#{resource_path}/#{recording_id}/summary", params)
+
+      response["summary"] || response
+    end
+
+    # Get transcript for a recording
+    # @param recording_id [Integer] The recording ID
+    # @param destination_url [String, nil] Optional webhook URL for async delivery
+    # @return [Hash] Transcript data or destination confirmation
+    def self.get_transcript(recording_id, destination_url: nil)
+      params = destination_url ? { destination_url: } : {}
+      response = client.get("#{resource_path}/#{recording_id}/transcript", params)
+
+      response["transcript"] || response
+    end
+
+    # Recordings don't have a standard list endpoint
+    def self.all(_params = {})
+      raise NotImplementedError,
+            "Recording.all is not supported. Recordings are accessed via Meeting#recording_id"
+    end
+
+    # Recordings don't have a standard retrieve endpoint
+    # Use get_summary or get_transcript instead
+    def self.retrieve(_id)
+      raise NotImplementedError,
+            "Recording.retrieve is not supported. Use Recording.get_summary(id) or Recording.get_transcript(id)"
+    end
+  end
+end

data/lib/fathom/resources/team.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Fathom
+  class Team < Resource
+    def self.resource_path = "teams"
+
+    # Get all members of this team by filtering by team name
+    # Note: Requires the team to have a 'name' attribute
+    def members(params = {}) = TeamMember.all(params.merge(team: name))
+
+    # Get the team name
+    def name = self["name"]
+
+    # Get the created_at timestamp
+    def created_at = self["created_at"]
+  end
+end

data/lib/fathom/resources/team_member.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fathom
+  class TeamMember < Resource
+    def self.resource_path = "team_members"
+
+    # List all team members, optionally filtered by team name
+    # @param params [Hash] Query parameters
+    # @option params [String] :team Team name to filter by
+    # @option params [String] :cursor Cursor for pagination
+    # @return [Array<TeamMember>]
+    def self.all(params = {})
+      response = client.get(resource_path, params)
+      data = response["items"] || []
+
+      data.map { |attrs| new(attrs, rate_limit_info: client.rate_limiter.to_h) }
+    end
+
+    # Team members don't have individual retrieve endpoint in the API
+    # Use .all with filters instead
+    def self.retrieve(_id)
+      raise NotImplementedError,
+            "TeamMember.retrieve is not supported by the Fathom API. Use TeamMember.all instead."
+    end
+
+    # Get the member's email
+    def email = self["email"]
+
+    # Get the member's name
+    def name = self["name"]
+
+    # Get the created_at timestamp
+    def created_at = self["created_at"]
+
+    # Team members don't have an ID field in the API
+    def id = nil
+  end
+end

data/lib/fathom/resources/webhook.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Fathom
+  class Webhook < Resource
+    def self.resource_path = "webhooks"
+
+    # Get the webhook URL
+    def url = self["url"]
+
+    # Check if webhook is active
+    def active? = self["active"] == true || self["status"] == "active"
+
+    # Get the webhook secret (if available)
+    def secret = self["secret"]
+
+    # Get triggered_for configuration
+    # Possible values: "my_recordings", "shared_external_recordings",
+    #                  "my_shared_with_team_recordings", "shared_team_recordings"
+    def triggered_for = self["triggered_for"]
+
+    # Check if transcript is included in webhook payload
+    def include_transcript? = self["include_transcript"] == true
+
+    # Check if summary is included in webhook payload
+    def include_summary? = self["include_summary"] == true
+
+    # Check if action items are included in webhook payload
+    def include_action_items? = self["include_action_items"] == true
+
+    # Check if CRM matches are included in webhook payload
+    def include_crm_matches? = self["include_crm_matches"] == true
+  end
+end

data/lib/fathom/version.rb

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