Merge pull request #2 from agencyenterprise/staging

Add Vitest configuration and tests for OAuth and session management

Author: jpatterson933

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor (no functional changes)
+- [ ] Documentation
+- [ ] Other (describe below)
+
+## Testing
+
+<!-- How did you verify this works? Include any of the following: -->
+
+**Video walkthrough (Loom, etc.):**
+<!-- Paste link here -->
+
+**Screenshots:**
+<!-- Drag and drop images here -->
+
+**Manual testing notes:**
+<!-- Describe what you tested manually -->
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123, Relates to #456 -->

.github/workflows/ci.yml

@@ -27,6 +27,23 @@ jobs:
       - name: Type check
         run: npx tsc --noEmit
 
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
   build:
     name: Build
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -21,14 +21,25 @@ Fathom OAuth apps require HTTPS redirect URIs, so you'll need to deploy to test
 
 ### 3. Initialize Database Schema
 
-After adding a PostgreSQL database to your Railway project (step 1.3) and copying `DATABASE_URL` to your local `.env`, create the tables:
+After adding a PostgreSQL database to your Railway project (step 1.3) and copying `DATABASE_URL` to your local `.env`:
 
 ```bash
-npm run db:push
+npm run db:migrate
 ```
 
 This connects to your Railway database and creates the required tables.
 
+### Making Database Schema Changes
+
+If your PR modifies `src/db/schema.ts`:
+
+1. Make your schema changes
+2. Run `npm run db:generate` to create a migration file
+3. Run `npm run db:migrate` to apply it to your Railway database
+4. Commit both the schema change and the new migration file in `drizzle/migrations/`
+
+> **Note**: After your PR is merged, a maintainer will run migrations against staging/production. This may change in the future.
+
 ### 4. Test Your Changes
 
 1. Make changes locally
@@ -59,10 +70,13 @@ src/
 
 ## Pull Requests
 
-1. Create a feature branch from `main`
+1. Create a feature branch from `staging`
 2. Make your changes
 3. Run `npm run ci` to ensure all checks pass
-4. Submit a PR with a clear description of what changed and why
+4. Open a PR **targeting the `staging` branch** (not `main`)
+5. Include a clear description of what changed and why
+
+> **Important**: All PRs should be opened against `staging`. The `main` branch is reserved for production releases.
 
 ## Reporting Issues
 

README.md

@@ -41,27 +41,16 @@ That's it. Ask Claude about your meetings.
 | `search_meetings`   | Search meetings by title with optional filters          | [MCP Custom](#custom-mcp-tools)                                                         |
 | `get_transcript`    | Get full transcript for a recording                     | [Fathom API](https://developers.fathom.ai/api-reference/recordings/get-transcript)      |
 | `get_summary`       | Get AI-generated summary for a recording                | [Fathom API](https://developers.fathom.ai/api-reference/recordings/get-summary)         |
-| `list_teams`        | List all accessible teams                               | [Fathom API](https://developers.fathom.ai/sdks/available-methods)                       |
+| `list_teams`        | List all accessible teams                               | [Fathom API](https://developers.fathom.ai/api-reference/teams/list-teams)               |
 | `list_team_members` | List members of a team                                  | [Fathom API](https://developers.fathom.ai/api-reference/team-members/list-team-members) |
 
 ### Custom MCP Tools
 
-Tools marked as **MCP Custom** are built specifically for this server and don't exist in the Fathom API. See the [/docs](https://www.fathom-mcp-server.com/docs) page for full parameter documentation.
-
 #### `search_meetings`
 
-Search meetings by title. This is an MCP-native tool that performs client-side filtering since Fathom's API doesn't provide a search endpoint.
+Search Fathom meetings by title or meeting_title. This is an MCP-native tool that performs client-side filtering since Fathom's API doesn't provide a search endpoint. For users with many meetings, use `list_meetings` with date filters for better performance.
 
-| Parameter                        | Type     | Required | Description                                        |
-| -------------------------------- | -------- | -------- | -------------------------------------------------- |
-| `query`                          | string   | ✓        | Search term to match against meeting titles        |
-| `limit`                          | number   |          | Max results to return (1-100)                      |
-| `created_after`                  | string   |          | ISO datetime - only meetings created after this    |
-| `created_before`                 | string   |          | ISO datetime - only meetings created before this   |
-| `calendar_invitees_domains`      | string[] |          | Filter by attendee company domains                 |
-| `calendar_invitees_domains_type` | enum     |          | `all` \| `only_internal` \| `one_or_more_external` |
-| `teams`                          | string[] |          | Filter by team names                               |
-| `recorded_by`                    | string[] |          | Filter by recorder email addresses                 |
+See the [Fathom MCP Server documentation](https://www.fathom-mcp-server.com/docs) for full request and response parameters.
 
 ### Example Usage in Claude
 
@@ -94,6 +83,7 @@ The Fathom API itself only provides read access via its `public_api` scope. Writ
 ## Limitations
 
 - `search_meetings` performs client-side filtering since Fathom's API doesn't provide a search endpoint. For users with many meetings, use `list_meetings` with date filters instead.
+- You can always ask the LLM what query params are avaialable.
 
 ## Self-Hosting
 
@@ -138,13 +128,13 @@ Set these in your hosting provider's dashboard (as well as your local .env file
 Run migrations after first deploy:
 
 ```bash
-npm run db:push
+npm run db:migrate
 ```
 
 Or via Railway CLI:
 
 ```bash
-railway run npm run db:push
+railway run npm run db:migrate
 ```
 
 ### 5. Connect Claude
@@ -190,6 +180,21 @@ https://developers.fathom.ai/llms.txt
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
+## Releasing
+
+See [RELEASING.md](RELEASING.md) for version and release instructions.
+
+## Future Development Plans
+
+- **Transcript vectorization** — Enable vectorization of large transcripts so LLMs can parse and understand them more efficiently. Would be implemented as a stateless worker to ensure no user data is persisted.
+- **Action item aggregation** — Aggregate action items across meetings with filters. "Show all my incomplete action items from this week."
+- **Meeting analytics** — Calculate stats like total meeting time, meeting frequency, and top attendees.
+- **Speaker time analysis** — Analyze transcripts to show who spoke most in a meeting.
+- **Meeting comparison** — Compare two meeting summaries to highlight what changed over time.
+- **Fathom API changelog monitoring** — Automated detection of Fathom API changes via GitHub Action that periodically checks their API reference and creates an issue if changes are detected.
+
+Contributions toward these goals are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

RELEASING.md

@@ -0,0 +1,73 @@
+# Releasing a New Version
+
+## Prerequisites
+
+- All changes merged from `staging` → `main`
+- You're on the `main` branch locally
+
+## Steps
+
+### 1. Checkout and pull main
+
+```bash
+git checkout main
+git pull origin main
+```
+
+### 2. Bump the version
+
+Run ONE of these commands in your terminal:
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1 (bug fixes)
+npm version minor   # 1.0.0 → 1.1.0 (new features)
+npm version major   # 1.0.0 → 2.0.0 (breaking changes)
+```
+
+This command does three things automatically:
+- Updates `version` in `package.json`
+- Creates a git commit (e.g., "v1.0.1")
+- Creates a git tag (e.g., `v1.0.1`)
+
+### 3. Push the commit and tag
+
+```bash
+git push origin main --tags
+```
+
+### 4. Create the GitHub Release
+
+1. Go to the repo on GitHub
+2. Click **Releases** (right sidebar)
+3. Click **Draft a new release**
+4. **Choose a tag**: Select the tag you just pushed (e.g., `v1.0.1`)
+5. **Release title**: Same as tag (e.g., `v1.0.1`)
+6. **Description**: Write what changed (see example below)
+7. Click **Publish release**
+
+### Example Release Notes
+
+```markdown
+## What's New
+
+- Added support for X
+- Improved performance of Y
+
+## Bug Fixes
+
+- Fixed issue with Z
+
+## Breaking Changes
+
+- None
+```
+
+> **Tip**: Click "Generate release notes" in GitHub to auto-generate a commit list, then edit it to be human-readable.
+
+## Version Naming
+
+| Type | When to use | Example |
+|------|-------------|---------|
+| **patch** | Bug fixes, minor improvements | 1.0.0 → 1.0.1 |
+| **minor** | New features, backward compatible | 1.0.0 → 1.1.0 |
+| **major** | Breaking changes | 1.0.0 → 2.0.0 |

drizzle/migrations/0000_overjoyed_kulan_gath.sql

@@ -0,0 +1,73 @@
+CREATE TABLE "fathom_oauth_tokens" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"access_token" text NOT NULL,
+	"refresh_token" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "fathom_oauth_tokens_user_id_unique" UNIQUE("user_id")
+);
+--> statement-breakpoint
+CREATE TABLE "mcp_server_access_tokens" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"token" text NOT NULL,
+	"user_id" text NOT NULL,
+	"scope" text DEFAULT 'fathom:read' NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	CONSTRAINT "mcp_server_access_tokens_token_unique" UNIQUE("token")
+);
+--> statement-breakpoint
+CREATE TABLE "mcp_server_authorization_codes" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"code" text NOT NULL,
+	"user_id" text NOT NULL,
+	"client_id" text NOT NULL,
+	"client_redirect_uri" text NOT NULL,
+	"client_code_challenge" text,
+	"client_code_challenge_method" text,
+	"scope" text DEFAULT 'fathom:read' NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"used" timestamp,
+	CONSTRAINT "mcp_server_authorization_codes_code_unique" UNIQUE("code")
+);
+--> statement-breakpoint
+CREATE TABLE "mcp_server_oauth_clients" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"client_id" text NOT NULL,
+	"client_secret" text,
+	"client_name" text,
+	"redirect_uris" json NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "mcp_server_oauth_clients_client_id_unique" UNIQUE("client_id")
+);
+--> statement-breakpoint
+CREATE TABLE "mcp_server_oauth_states" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"state" text NOT NULL,
+	"client_id" text NOT NULL,
+	"client_redirect_uri" text NOT NULL,
+	"client_state" text NOT NULL,
+	"client_code_challenge" text,
+	"client_code_challenge_method" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	CONSTRAINT "mcp_server_oauth_states_state_unique" UNIQUE("state")
+);
+--> statement-breakpoint
+CREATE TABLE "mcp_sessions" (
+	"session_id" uuid PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"terminated_at" timestamp
+);
+--> statement-breakpoint
+CREATE INDEX "fathom_oauth_tokens_expires_at_idx" ON "fathom_oauth_tokens" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "mcp_server_access_tokens_expires_at_idx" ON "mcp_server_access_tokens" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "mcp_server_authorization_codes_expires_at_idx" ON "mcp_server_authorization_codes" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "mcp_server_oauth_states_expires_at_idx" ON "mcp_server_oauth_states" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "mcp_sessions_expires_at_idx" ON "mcp_sessions" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "mcp_sessions_terminated_at_idx" ON "mcp_sessions" USING btree ("terminated_at");