Kortex - NotebookLM Extension

A Chrome extension that enhances NotebookLM with export capabilities, subscription management, and premium features.

🚀 Overview

Kortex is a browser extension that integrates with Google's NotebookLM, allowing users to export notebook sources in various formats (PDF, Markdown, Text) with a flexible subscription model. The extension features a modular architecture designed for easy feature additions and maintenance.

✨ Features

• Export Notebook Sources: Export NotebookLM sources as PDF, Markdown, or Text files with intelligent hierarchy detection
• Export Notes & Artifacts: Export AI-generated notes, study guides, quizzes, and other artifacts
• Chat Export: Export chat conversations with option to include/exclude user messages
• Import to NotebookLM: Import chats from LLMs and Google Docs directly to NotebookLM
• Prompt Holder: Save and organize prompts with folders and tags (cloud-synced)
• Source Views: Custom source viewing and filtering capabilities
• Highlight & Snipe: Right-click to save highlighted text to NotebookLM
• Google Docs Sync: Sync all Google Doc sources at once (Pro-only)
• Smart Search: Search and filter notebooks on dashboard
• Feature Management: Customize which features appear in the interface
• User Authentication: Google OAuth and Email/Password with email verification
• Subscription Management: Customer portal for managing subscriptions via Dodo Payments
• Usage Tracking: Track imports, exports, prompts, and source views with tier-based limits
• In-App Support: Submit support requests directly from the extension
• Modular Architecture: Feature-based code organization for easy extension

📁 Project Structure

├── src/                    # Extension source code
│   ├── background/         # Background script handlers
│   │   └── handlers/      # Feature-specific handlers
│   ├── popup/              # Popup UI components
│   │   ├── views/         # View components
│   │   └── utils/         # UI utilities
│   ├── shared/            # Shared utilities
│   ├── services/          # External service integrations
│   └── upgrade/           # Upgrade popup
├── functions/              # Firebase Functions (backend)
│   ├── handlers/          # Function handlers
│   └── utils/             # Utility functions
├── features/               # Feature modules (future)
├── docs/                   # Documentation
└── dist/                   # Built extension files

📚 Documentation

All documentation is organized in the docs/ directory:

• PERMISSIONS.md - Detailed explanation of all extension permissions and why they are required

Setup & Configuration

• ENVIRONMENT_SETUP.md - Environment variables and configuration setup
• SETUP_SECRETS.md - Setting up Firebase Functions secrets (Dodo Payments API key, live mode)
• WEBHOOK_SETUP.md - Configuring Dodo Payments webhooks for subscription management
• PRODUCTION_MIGRATION.md - Steps to migrate from test to live Dodo Payments
• TESTING_LIVE_MODE.md - Guide for testing live mode without payment
• CUSTOMER_PORTAL_DEBUG.md - Debugging customer portal issues

Development Guides

• FEATURES_ARCHITECTURE.md - Understanding the features directory structure
• UPGRADE_POPUP_GUIDE.md - How to integrate new features with the upgrade popup system

Planning

• TODO.md - Project roadmap, refactoring tasks, and future plans

🛠️ Getting Started

Prerequisites

• Node.js (v16 or higher)
• Firebase CLI
• Chrome/Edge/Brave browser
• Firebase project with Firestore enabled
• Dodo Payments account (for subscriptions)

Installation

1. Clone the repository

   git clone <repository-url>
   cd my-extension-build

2. Install dependencies

   npm install
   cd functions && npm install && cd ..

3. Configure Firebase

   • Set up your Firebase project
   • Enable Firestore
   • Configure Firebase Functions
   • See ENVIRONMENT_SETUP.md for details

4. Set up secrets

   • Configure Dodo Payments API key
   • See SETUP_SECRETS.md for instructions

5. Build the extension

   npm run build

6. Load in Chrome

   • Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select the dist/ directory

🔧 Development

Running in Development Mode

npm run dev

This will start Vite in watch mode, automatically rebuilding when files change.

Project Architecture

The project follows a modular architecture:

• Background Script: Handles all extension logic, message routing, and API calls
• Popup UI: User interface for authentication, status, and upgrade
• Firebase Functions: Backend API for user management, credit checking, and webhooks
• Feature Modules: Self-contained feature implementations (in progress)

Adding New Features

1. Create feature handler in src/background/handlers/
2. Add to message router in src/background/messageRouter.js
3. Update UI if needed in src/popup/
4. Add backend function in functions/handlers/ if required
5. Integrate upgrade popup - See UPGRADE_POPUP_GUIDE.md

🔐 Authentication

The extension supports multiple authentication methods:

• Google OAuth: OAuth 2.0 flow via Chrome Identity API
• Email/Password: Email and password sign-up with email verification
• Firebase Authentication: User management via Firebase
• Email Verification: Required for new email/password accounts
• Welcome Page: Shown on first installation with dual authentication options
• Automatic User Creation: User documents created in Firestore on first sign-in

💳 Subscription Tiers

Basic (Free)

• Exports: 10 per month
• Imports: 15 per month
• Prompts: 15 total (lifetime)
• Source Views: 10 total (lifetime)

Lite ($3.99/month)

• Exports: 80 per month
• Imports: 60 per month
• Prompts: 30 total (lifetime)
• Source Views: 30 total (lifetime)

Pro ($6.99/month)

• Exports: Unlimited
• Imports: Unlimited
• Prompts: Unlimited
• Source Views: Unlimited
• Google Docs Sync: Enabled
• Support: 24-Hour Priority Response

Lifetime Pro ($99.00 one-time - Limited Time)

• Exports: Unlimited forever
• Imports: Unlimited forever
• Prompts: Unlimited
• Source Views: Unlimited
• Google Docs Sync: Enabled
• Never expires - Pay once, use forever
• 67% OFF original $300 price

Prepaid Credits (Pay-as-you-go)

• Best for: Occasional users or one-off projects
• Pricing: $0.03 per credit (minimum 1000 credits = $3.00 with 10x bonus)
• Usage: 1 credit = 1 export or 1 import
• Never expire - Use anytime
• Works with any plan - Use alongside subscriptions

Subscription management is handled via Dodo Payments webhooks. See WEBHOOK_SETUP.md for configuration.

🧪 Testing

Manual Testing

1. Sign In/Out: Test authentication flow
2. Export Sources: Test export functionality with different formats
3. Subscription: Test upgrade flow and webhook processing
4. Limit Testing: Verify export limits are enforced correctly

Debug Features

• Manual Upgrade: Double-click settings icon (⚙️) 3 times in popup to upgrade to Lite tier
• Console Logging: Check browser console for detailed logs (prefixed with emojis for easy filtering)
• Firebase Logs: Check Firebase Functions logs for backend issues
• Customer Portal Testing: Use manual upgrade to test customer portal without payment

📦 Building for Production

npm run build

The built extension will be in the dist/ directory, ready for Chrome Web Store submission.

🚢 Deployment

Firebase Functions

firebase deploy --only functions

Extension

1. Build the extension: npm run build
2. Zip the dist/ directory
3. Submit to Chrome Web Store

🐛 Troubleshooting

Common Issues

Extension not loading:

• Check manifest.json for errors
• Verify all dependencies are installed
• Check browser console for errors

Authentication failing:

• Verify OAuth client ID in manifest
• Check Firebase project configuration
• Ensure redirect URI is configured in Google Cloud Console

Webhooks not working:

• Verify webhook URL in Dodo Payments dashboard
• Check Firebase Functions logs
• See WEBHOOK_SETUP.md for detailed troubleshooting

Subscription not updating:

• Check webhook configuration
• Verify user ID is being passed in checkout URL
• Check Firebase Functions logs for webhook payload

📝 License

[Your License Here]

🤝 Contributing

[Contributing guidelines]

📧 Support

For issues and questions, please create an issue or contact support.

---

Note: This project is actively being refactored for better modularity. See TODO.md for current progress and planned improvements.