Skip to content

README.md

Latest commit

 

History

History
292 lines (218 loc) · 7.81 KB

README.md

File metadata and controls

292 lines (218 loc) · 7.81 KB

Bundled Notes to Microsoft To-Do Migrator

A TypeScript-based migration tool to convert your Bundled Notes export to Microsoft To-Do task lists.

Note: This project was created with the assistance of Warp AI Agent Mode, an AI-powered development assistant integrated into the Warp terminal. Agent Mode helped with code generation, project structure, and documentation creation.

Overview

This tool parses your Bundled Notes export data and migrates it to Microsoft To-Do, converting:

  • Bundles → Task Lists
  • Entries → Tasks
  • Tags → Task Categories

Features

  • 🔄 Complete Migration: Converts all active (non-archived) entries from your Bundled Notes export
  • 📋 Smart Organization: Creates separate To-Do lists for each bundle category
  • 🏷️ Tag Preservation: Maintains tag information and relationships
  • 🔒 Secure Authentication: Uses Microsoft Graph API with proper OAuth2 flow
  • 🚀 Simple Mode: Quick migration using access tokens from Graph Explorer
  • 📊 Progress Tracking: Real-time migration progress and detailed reporting
  • ⚡ Rate Limiting: Built-in delays to respect Microsoft Graph API limits

Prerequisites

  • Node.js 16+ and npm
  • Microsoft account with access to Microsoft To-Do
  • Bundled Notes export file

Installation

  1. Clone or download this repository
  2. Install dependencies: 
    npm install

Quick Start (Simple Mode)

The easiest way to migrate your data is using the simple mode with an access token:

1. Get Your Access Token

  1. Go to Microsoft Graph Explorer
  2. Sign in with your Microsoft account
  3. Click on the "Access Token" tab
  4. Copy the access token

2. Configure Environment

Create a .env file in the project root:

# Microsoft Graph API Configuration
AZURE_CLIENT_ID=your_client_id
AZURE_CLIENT_SECRET=your_client_secret
AZURE_TENANT_ID=your_tenant_id

# Microsoft Graph API URLs
GRAPH_API_URL=https://graph.microsoft.com/v1.0
AUTHORITY_URL=https://login.microsoftonline.com/common

# Access Token for Simple Migration
GRAPH_ACCESS_TOKEN=your_access_token_here

3. Add Your Bundled Notes Export

Place your Bundled Notes export folder in the project root. The tool expects a directory structure like:

Bundled Notes Export - YYYY-MM-DD HHMMSS/
├── bundles/
│   ├── shopping/
│   ├── books/
│   ├── videos/
│   └── ...
└── templates/

4. Run the Migration

npm run simple-migrate

Advanced Setup (Full OAuth2 Flow)

For production use or automated scenarios, you can set up full OAuth2 authentication:

1. Register Azure Application

  1. Go to Azure Portal
  2. Navigate to "Azure Active Directory" > "App registrations"
  3. Click "New registration"
  4. Configure:
    • Name: "Bundled Notes Migrator"
    • Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
    • Redirect URI: http://localhost:3000/auth/callback (Web)

2. Configure API Permissions

Add these Microsoft Graph permissions:

  • Tasks.ReadWrite (Delegated)
  • User.Read (Delegated)

3. Update Configuration

Update your .env file with your Azure app credentials:

AZURE_CLIENT_ID=your_app_client_id
AZURE_CLIENT_SECRET=your_app_client_secret
AZURE_TENANT_ID=your_tenant_id

4. Run Full Migration

npm run dev -- --migrate

Project Structure

src/
├── api/
│   ├── microsoft-graph-client.ts    # Full OAuth2 Graph API client
│   └── simple-auth.ts              # Simple access token client
├── converters/
│   └── todo-converter.ts           # Converts Bundled Notes to To-Do format
├── parsers/
│   └── bundled-notes-parser.ts     # Parses Bundled Notes export
├── types/
│   ├── bundled-notes.ts            # Bundled Notes type definitions
│   └── microsoft-todo.ts           # Microsoft To-Do type definitions
├── index.ts                        # Main migration script (OAuth2)
└── simple-migrate.ts               # Simple migration script (access token)

Migration Process

Data Conversion

  1. Bundle Parsing: Reads all bundle directories from your export
  2. Entry Filtering: Excludes archived entries, processes only active ones
  3. Tag Resolution: Maps tag IDs to tag names and metadata
  4. Task Creation: Converts entries to Microsoft To-Do task format

Microsoft To-Do Integration

  1. Authentication: Establishes connection to Microsoft Graph API
  2. List Management: Creates task lists for each bundle category
  3. Task Creation: Populates lists with converted tasks
  4. Error Handling: Provides detailed feedback on any failures

Example Conversion

Bundled Notes Bundle:

{
  "name": "Shopping",
  "entries": [
    {
      "id": "entry-1",
      "text": "Buy groceries",
      "created": "2024-01-15T10:30:00Z",
      "tags": ["urgent"],
      "archived": false
    }
  ]
}

Microsoft To-Do Task:

{
  "title": "Buy groceries",
  "status": "notStarted",
  "createdDateTime": "2024-01-15T10:30:00Z",
  "body": {
    "content": "Buy groceries",
    "contentType": "text"
  }
}

Supported Bundle Types

The tool automatically detects and migrates these common bundle types:

  • 📝 General Notes → "General" task list
  • 🛒 Shopping → "Shopping" task list
  • 📚 Books → "Books" task list
  • 🎮 Video Games → "Video Games" task list
  • 🔗 Links → "Links" task list
  • 🎬 Videos → "Videos" task list
  • 📅 Recurring → "Recurring" task list

Scripts

Script Description
npm run build Compile TypeScript to JavaScript
npm run dev Run with TypeScript directly (preview mode)
npm run dev -- --migrate Run full migration with OAuth2
npm run simple-migrate Run simple migration with access token
npm start Run compiled JavaScript version

Troubleshooting

Common Issues

Access Token Expired:

❌ Failed to connect to Microsoft Graph
  • Solution: Get a new access token from Graph Explorer

Missing Bundle Export:

❌ Export path not found
  • Solution: Ensure your Bundled Notes export is in the project root

Rate Limiting:

❌ Too many requests
  • Solution: The tool includes automatic delays, but you may need to wait and retry

Permission Errors:

❌ Insufficient privileges
  • Solution: Ensure your Azure app has proper Microsoft Graph permissions

Debug Mode

Enable verbose logging by setting:

DEBUG=true

Development

Building

npm run build

Adding New Converters

  1. Create a new converter in src/converters/
  2. Implement the conversion logic
  3. Update the main migration script to use your converter

Extending API Support

  1. Add new API clients in src/api/
  2. Implement the required interface methods
  3. Update the migration scripts

Security Notes

  • 🔐 Tokens: Never commit access tokens to version control
  • 🔒 Environment: Use environment variables for sensitive data
  • 🛡️ Permissions: Request only necessary Microsoft Graph permissions
  • 📱 Scope: Access tokens have limited lifetime and scope

License

ISC License - See LICENSE file for details

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

For issues or questions:

  1. Check the troubleshooting section
  2. Review Microsoft Graph API documentation
  3. Open an issue with detailed error information

Note: This tool is designed for personal use and migration of your own Bundled Notes data. Ensure you have proper permissions for any data you're migrating.