# Filevine Plugin - Cursor AI Rules

## Project Context
This is a Chrome extension (Manifest V3) that interfaces with Filevine, a legal case management platform. The extension allows users to browse and download files from their Filevine projects and view them with specialized viewers (like DICOM medical images).

## Key Technical Context

### Filevine API Quirks (IMPORTANT!)
These requirements are NOT in Filevine's public docs and were discovered through testing:

1. **Base URL**: Always use `https://api.filevineapp.com/fv-app/v2` (NOT api.filevine.io)
2. **User ID**: Must be NUMERIC from GetUserOrgsWithToken, NOT the UUID `sub` from JWT
3. **Endpoint casing**: PascalCase required (`/Projects`, `/Contacts`, not `/projects`)
4. **Required headers**: All API calls need ALL THREE:
   - `x-fv-userid` (numeric)
   - `x-fv-orgid`
   - `x-fv-sessionid` (JWT `jti` claim)

### Extension Architecture
- **Background (Service Worker)**: Handles all API calls, auth, downloads
- **Content Script**: Runs on Filevine pages, extracts auth tokens
- **Popup**: User interface for browsing/downloading
- **Viewers**: Specialized file viewers (DICOM, etc.)

### Chrome Extension MV3 Rules
- Service workers are ephemeral (no persistent state except chrome.storage)
- Use ES modules (`type: "module"` in manifest)
- Content scripts run in isolated world (need postMessage for page access)
- All external API calls must go through background service worker

## Code Style

- Use vanilla JS (no framework for now)
- ES6+ features (async/await, modules, etc.)
- JSDoc comments for functions
- Console.log prefixed with `[Filevine Plugin]`

## When Making Changes

1. Always check `src/lib/constants.js` for API URLs and message types
2. Auth flow is in `src/background/auth.js` - test changes carefully
3. Token extraction in `src/content/extractor.js` may need tuning per Filevine version
4. The DICOM viewer needs cornerstone.js to actually render images

## Common Tasks

### Adding a new API endpoint
1. Add endpoint to `ENDPOINTS` in `src/lib/constants.js`
2. Add convenience method in `src/background/api.js`
3. Add message handler in `src/background/index.js`
4. Call from popup via chrome.runtime.sendMessage

### Adding a new viewer
1. Create folder in `src/viewers/{type}/`
2. Register in `src/viewers/registry.js`
3. Add to `VIEWER_TYPES` in constants.js
4. Update `getViewerUrl()` in downloads.js

### Debugging auth issues
1. Check content script is detecting Filevine page
2. Verify token extraction methods in extractor.js
3. Check background logs for API errors
4. Verify all 3 x-fv-* headers are being sent

## Testing
Load as unpacked extension in chrome://extensions with Developer Mode on.
Background logs: Click "service worker" link in extension card.
Content script logs: DevTools console on Filevine page.
