fathom-ruby 1.0.0

data/lib/fathom.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "fathom/version"
+require_relative "fathom/errors"
+require_relative "fathom/client"
+require_relative "fathom/rate_limiter"
+require_relative "fathom/resource"
+require_relative "fathom/resources/meeting"
+require_relative "fathom/resources/recording"
+require_relative "fathom/resources/team"
+require_relative "fathom/resources/team_member"
+require_relative "fathom/resources/webhook"
+
+module Fathom
+  class << self
+    attr_writer :api_key, :auto_retry, :max_retries, :debug, :debug_http
+
+    def configure
+      yield self
+    end
+
+    def api_key
+      @api_key || raise(Error, "Fathom.api_key is not configured")
+    end
+
+    def auto_retry = @auto_retry.nil? || @auto_retry
+
+    def max_retries = @max_retries || 3
+
+    def debug = @debug || false
+
+    def debug_http = @debug_http || false
+
+    def reset!
+      @api_key = nil
+      @auto_retry = true
+      @max_retries = 3
+      @debug = false
+      @debug_http = false
+    end
+
+    def log(message)
+      return unless debug
+
+      puts "[Fathom] #{message}"
+    end
+
+    def log_http(message)
+      return unless debug_http
+
+      puts "[Fathom HTTP] #{message}"
+    end
+  end
+end

data/scripts/README.md

@@ -0,0 +1,138 @@
+# Scripts
+
+This directory contains utility scripts for development and testing.
+
+## test_live_api.rb
+
+Integration test script to verify the gem works correctly with the real Fathom API.
+
+### Prerequisites
+
+1. A Fathom account
+2. An API key from your Fathom account (get it at: https://app.fathom.video/settings/integrations)
+
+### Usage
+
+**Option 1: Inline environment variable**
+
+```bash
+FATHOM_API_KEY=your_api_key_here ruby scripts/test_live_api.rb
+```
+
+**Option 2: Export environment variable**
+
+```bash
+export FATHOM_API_KEY=your_api_key_here
+ruby scripts/test_live_api.rb
+```
+
+**Option 3: Use .env file (recommended for development)**
+
+Create a `.env` file in the project root (already in .gitignore):
+
+```bash
+echo "export FATHOM_API_KEY=your_api_key_here" > .env
+```
+
+Then load it and run:
+
+```bash
+source .env
+ruby scripts/test_live_api.rb
+```
+
+### What It Tests
+
+The script performs the following tests against your live Fathom account:
+
+1. **Meetings API**
+   - Fetch meetings list
+   - Access meeting attributes
+   - Fetch meeting summaries (if recordings exist)
+   - Fetch meeting transcripts (if recordings exist)
+
+2. **Teams API**
+   - Fetch teams list
+   - Fetch team members for each team
+
+3. **Team Members API**
+   - Fetch all team members directly
+
+4. **Webhooks API**
+   - Fetch webhooks list
+   - Create a test webhook
+   - Retrieve the created webhook
+   - Delete the test webhook
+   - Verify deletion
+
+5. **Error Handling**
+   - Test 404 responses for invalid IDs
+
+6. **Rate Limiting**
+   - Verify rate limit headers are processed
+
+7. **Pagination**
+   - Test pagination with limit parameter
+
+### 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!
+```
+
+### Notes
+
+- **Mostly read-only**: This script performs read operations for meetings, teams, and team members.
+- **Webhook testing**: Creates a temporary test webhook and immediately deletes it to verify full CRUD operations.
+- **Safe to run**: The test webhook is automatically cleaned up. You can run this script as many times as you want.
+- **Rate limits**: The script respects Fathom's rate limits and will automatically retry if needed.
+
+### Troubleshooting
+
+**Error: FATHOM_API_KEY environment variable not set**
+- Make sure you've set the environment variable before running the script
+
+**401 Authentication Error**
+- Your API key is invalid or has expired
+- Get a new API key from https://app.fathom.video/settings/integrations
+
+**404 Not Found (for meetings/teams)**
+- Your account may not have any meetings or teams yet
+- Try recording a meeting in Fathom first
+
+**Rate Limit Exceeded**
+- Wait a minute and try again
+- The script will automatically retry with exponential backoff
+

data/scripts/test_live_api.rb

@@ -0,0 +1,374 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockNesting
+# Integration test script for fathom-ruby gem against live API
+# Usage: FATHOM_API_KEY=your_key_here ruby scripts/test_live_api.rb
+
+require "bundler/setup"
+require "securerandom"
+require_relative "../lib/fathom"
+
+# ANSI color codes for pretty output
+def green(text)
+  "\e[32m#{text}\e[0m"
+end
+
+def red(text)
+  "\e[31m#{text}\e[0m"
+end
+
+def yellow(text)
+  "\e[33m#{text}\e[0m"
+end
+
+def blue(text)
+  "\e[34m#{text}\e[0m"
+end
+
+def section(title)
+  puts "\n#{blue("=" * 80)}"
+  puts blue("  #{title}")
+  puts blue("=" * 80)
+end
+
+def test(description)
+  print "  #{description}... "
+  result = yield
+  puts green("✓ PASS")
+  result
+rescue StandardError => e
+  puts red("✗ FAIL")
+  puts red("    Error: #{e.class}: #{e.message}")
+  nil
+end
+
+# Check for API key
+api_key = ENV.fetch("FATHOM_API_KEY", nil)
+if api_key.nil? || api_key.empty?
+  puts red("ERROR: FATHOM_API_KEY environment variable not set!")
+  puts "\nUsage:"
+  puts "  FATHOM_API_KEY=your_key_here ruby scripts/test_live_api.rb"
+  puts "\nOr export it first:"
+  puts "  export FATHOM_API_KEY=your_key_here"
+  puts "  ruby scripts/test_live_api.rb"
+  exit 1
+end
+
+# Configure the gem
+Fathom.configure do |config|
+  config.api_key = api_key
+  config.auto_retry = true
+  config.max_retries = 3
+end
+
+puts green("\n✓ Fathom API Test Suite")
+puts "  Testing against live API with your credentials\n"
+
+# Track results
+results = {
+  passed: 0,
+  failed: 0,
+  skipped: 0
+}
+
+# =============================================================================
+# Test: Meetings
+# =============================================================================
+section "1. Testing Meetings API"
+
+meetings = test("Fetch meetings list") do
+  Fathom::Meeting.all(limit: 5)
+end
+
+if meetings
+  results[:passed] += 1
+  puts "    Found #{meetings.count} meeting(s)"
+
+  if meetings.any?
+    meeting = meetings.first
+    puts "\n    First meeting details:"
+    puts "      Recording ID: #{meeting.recording_id || "N/A"}"
+    puts "      Title: #{meeting["title"] || "N/A"}"
+    puts "      Created: #{meeting["created_at"]}"
+    puts "      URL: #{meeting["url"] || "N/A"}"
+
+    # Test meeting attributes
+    test("Access meeting attributes") do
+      raise "Missing attributes" if meeting.attributes.empty?
+
+      true
+    end
+    results[:passed] += 1
+
+    # Test fetching summary if recording exists
+    if meeting.recording_id
+      summary = test("Fetch meeting summary") do
+        meeting.fetch_summary
+      end
+      results[:passed] += 1 if summary
+
+      transcript = test("Fetch meeting transcript") do
+        meeting.fetch_transcript
+      end
+      results[:passed] += 1 if transcript
+    else
+      puts yellow("    ⊘ Skipping summary/transcript tests (no recording_id)")
+      results[:skipped] += 2
+    end
+  else
+    puts yellow("    ⊘ No meetings found - some tests skipped")
+    results[:skipped] += 3
+  end
+else
+  results[:failed] += 1
+end
+
+# =============================================================================
+# Test: Teams
+# =============================================================================
+section "2. Testing Teams API"
+
+teams = test("Fetch teams list") do
+  Fathom::Team.all
+end
+
+if teams
+  results[:passed] += 1
+  puts "    Found #{teams.count} team(s)"
+
+  if teams.any?
+    team = teams.first
+    puts "\n    First team details:"
+    puts "      ID: #{team.id}"
+    puts "      Name: #{team.name}"
+    puts "      Created: #{team.created_at}"
+
+    # Test team members
+    members = test("Fetch team members") do
+      team.members
+    end
+
+    if members
+      results[:passed] += 1
+      puts "    Found #{members.count} member(s) in team '#{team.name}'"
+
+      if members.any?
+        member = members.first
+        puts "\n    First member details:"
+        puts "      Name: #{member.name}"
+        puts "      Email: #{member.email}"
+      end
+    else
+      results[:failed] += 1
+    end
+  else
+    puts yellow("    ⊘ No teams found")
+    results[:skipped] += 1
+  end
+else
+  results[:failed] += 1
+end
+
+# =============================================================================
+# Test: Team Members (Direct API)
+# =============================================================================
+section "3. Testing Team Members API"
+
+team_members = test("Fetch all team members") do
+  Fathom::TeamMember.all(limit: 5)
+end
+
+if team_members
+  results[:passed] += 1
+  puts "    Found #{team_members.count} team member(s)"
+
+  if team_members.any?
+    member = team_members.first
+    puts "\n    Member details:"
+    puts "      Name: #{member.name}"
+    puts "      Email: #{member.email}"
+    puts "      Created: #{member.created_at}"
+  end
+else
+  results[:failed] += 1
+end
+
+# =============================================================================
+# Test: Webhooks API (Full CRUD)
+# =============================================================================
+section "4. Testing Webhooks API"
+
+# Test listing webhooks
+webhooks = test("Fetch webhooks list") do
+  Fathom::Webhook.all
+rescue Fathom::NotFoundError
+  puts yellow("    ⊘ List endpoint returned 404")
+  :not_available
+end
+
+if webhooks && webhooks != :not_available
+  results[:passed] += 1
+  puts "    Found #{webhooks.count} existing webhook(s)"
+
+  if webhooks.any?
+    webhook = webhooks.first
+    puts "\n    First webhook details:"
+    puts "      ID: #{webhook.id}"
+    puts "      URL: #{webhook.url}"
+    puts "      Active: #{webhook.active?}"
+    puts "      Triggered for: #{webhook.triggered_for&.join(", ") || "N/A"}"
+    puts "      Include transcript: #{webhook.include_transcript?}"
+    puts "      Include summary: #{webhook.include_summary?}"
+  end
+elsif webhooks == :not_available
+  results[:skipped] += 1
+else
+  results[:failed] += 1
+end
+
+# Test creating a webhook (independent of list endpoint)
+# Using webhook.site for a valid HTTPS endpoint that accepts webhooks
+created_webhook = test("Create test webhook") do
+  Fathom::Webhook.create(
+    url: "https://webhook.site/28c3ce21-4221-4d89-bab3-1c88d1cb0f0b",
+    triggered_for: ["my_recordings"],
+    include_transcript: true,
+    include_summary: true,
+    include_action_items: false,
+    include_crm_matches: false
+  )
+rescue Fathom::BadRequestError, Fathom::ForbiddenError => e
+  puts yellow("    ⊘ Webhooks not available: #{e.message}")
+  :not_available
+end
+
+if created_webhook && created_webhook != :not_available
+  results[:passed] += 1
+  puts "    Created webhook with ID: #{created_webhook.id}"
+  puts "    URL: #{created_webhook.url}"
+  puts "    Secret: #{created_webhook.secret[0..15]}..." if created_webhook.secret
+
+  # Test retrieving the webhook
+  retrieved_webhook = test("Retrieve created webhook") do
+    Fathom::Webhook.retrieve(created_webhook.id)
+  end
+
+  if retrieved_webhook
+    results[:passed] += 1
+    puts "    Successfully retrieved webhook #{retrieved_webhook.id}"
+  else
+    results[:failed] += 1
+  end
+
+  # Test deleting the webhook
+  deleted = test("Delete test webhook") do
+    created_webhook.delete
+    true
+  end
+
+  if deleted
+    results[:passed] += 1
+    puts "    Successfully deleted webhook #{created_webhook.id}"
+
+    # Verify deletion
+    verify_deleted = test("Verify webhook was deleted") do
+      Fathom::Webhook.retrieve(created_webhook.id)
+      raise "Webhook still exists!"
+    rescue Fathom::NotFoundError
+      true
+    end
+
+    if verify_deleted
+      results[:passed] += 1
+    else
+      results[:failed] += 1
+    end
+  else
+    results[:failed] += 1
+  end
+elsif created_webhook == :not_available
+  results[:skipped] += 4 # Skip create, retrieve, delete, and verify tests
+else
+  results[:failed] += 1
+end
+
+# =============================================================================
+# Test: Error Handling
+# =============================================================================
+section "5. Testing Error Handling"
+
+test("Handle invalid meeting ID (404)") do
+  Fathom::Meeting.retrieve("invalid_id_that_does_not_exist_12345")
+  raise "Should have raised NotFoundError"
+rescue Fathom::NotFoundError
+  true
+end
+results[:passed] += 1
+
+# =============================================================================
+# Test: Rate Limiting
+# =============================================================================
+section "6. Testing Rate Limiting"
+
+test("Check rate limit headers") do
+  Fathom::Meeting.all(limit: 1)
+  rate_limiter = Fathom::Client.new.instance_variable_get(:@rate_limiter)
+  info = rate_limiter.to_h
+
+  puts "\n    Rate limit status:"
+  if info[:limit].nil?
+    puts yellow("      No rate limit headers present in API response")
+  else
+    puts "      Limit: #{info[:limit]}"
+    puts "      Remaining: #{info[:remaining]}"
+    puts "      Reset: #{info[:reset]}s"
+  end
+
+  true
+end
+results[:passed] += 1
+
+# =============================================================================
+# Test: Pagination
+# =============================================================================
+section "7. Testing Pagination"
+
+paginated_meetings = test("Fetch meetings with pagination") do
+  Fathom::Meeting.all(limit: 2)
+end
+
+if paginated_meetings
+  results[:passed] += 1
+  puts "    Retrieved #{paginated_meetings.count} meeting(s) with limit=2"
+
+  if paginated_meetings.respond_to?(:next_cursor)
+    puts "    Next cursor available: #{paginated_meetings.next_cursor ? "Yes" : "No"}"
+  end
+else
+  results[:failed] += 1
+end
+
+# =============================================================================
+# Summary
+# =============================================================================
+section "Test Results Summary"
+
+total = results[:passed] + results[:failed] + results[:skipped]
+pass_rate = total.positive? ? (results[:passed].to_f / total * 100).round(1) : 0
+
+puts "\n  #{green("Passed:")}  #{results[:passed]}"
+puts "  #{red("Failed:")}  #{results[:failed]}"
+puts "  #{yellow("Skipped:")} #{results[:skipped]}"
+puts "  #{blue("Total:")}   #{total}"
+puts "\n  Pass Rate: #{pass_rate}%"
+
+if results[:failed].zero?
+  puts "\n#{green("\u2713 All tests passed!")}"
+  exit 0
+else
+  puts "\n#{red("\u2717 Some tests failed. Please review the output above.")}"
+  exit 1
+end
+
+# rubocop:enable Metrics/BlockNesting

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: fathom-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Juan Rodriguez
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A comprehensive Ruby gem for interacting with the Fathom API, supporting
+  meetings,                       recordings, teams, webhooks, and more.
+email:
+- jrodriguez@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- TESTING.md
+- fathom-ruby.gemspec
+- lib/fathom.rb
+- lib/fathom/client.rb
+- lib/fathom/errors.rb
+- lib/fathom/rate_limiter.rb
+- lib/fathom/resource.rb
+- lib/fathom/resources/meeting.rb
+- lib/fathom/resources/recording.rb
+- lib/fathom/resources/team.rb
+- lib/fathom/resources/team_member.rb
+- lib/fathom/resources/webhook.rb
+- lib/fathom/version.rb
+- scripts/README.md
+- scripts/test_live_api.rb
+homepage: https://github.com/yourusername/fathom-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yourusername/fathom-ruby
+  source_code_uri: https://github.com/yourusername/fathom-ruby
+  changelog_uri: https://github.com/yourusername/fathom-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby library for the Fathom API
+test_files: []