@bobfrankston/gcards 0.1.2 → 0.1.5

package/.claude/settings.local.json

@@ -13,7 +13,15 @@
       "Bash(gh repo create:*)",
       "Bash(gh repo edit:*)",
       "Bash(git push:*)",
-      "Bash(npm view:*)"
+      "Bash(npm view:*)",
+      "Bash(npx tsc:*)",
+      "Bash(grep:*)",
+      "Bash(node gfix.ts:*)",
+      "Bash(node --import tsx gcards.ts:*)",
+      "Bash(npm install:*)",
+      "Bash(npx tsx:*)",
+      "WebFetch(domain:lh3.googleusercontent.com)",
+      "Bash(curl:*)"
     ],
     "deny": [],
     "ask": []

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/.vscode/settings.json

@@ -1,3 +1,23 @@
-{
-    "workbench.colorTheme": "Visual Studio 2019 Dark"
+{
+    "workbench.colorTheme": "Visual Studio 2019 Dark",
+    "workbench.colorCustomizations": {
+        "activityBar.activeBackground": "#0ae04a",
+        "activityBar.background": "#0ae04a",
+        "activityBar.foreground": "#15202b",
+        "activityBar.inactiveForeground": "#15202b99",
+        "activityBarBadge.background": "#9266f8",
+        "activityBarBadge.foreground": "#15202b",
+        "commandCenter.border": "#e7e7e799",
+        "sash.hoverBorder": "#0ae04a",
+        "statusBar.background": "#08af3a",
+        "statusBar.foreground": "#e7e7e7",
+        "statusBarItem.hoverBackground": "#0ae04a",
+        "statusBarItem.remoteBackground": "#08af3a",
+        "statusBarItem.remoteForeground": "#e7e7e7",
+        "titleBar.activeBackground": "#08af3a",
+        "titleBar.activeForeground": "#e7e7e7",
+        "titleBar.inactiveBackground": "#08af3a99",
+        "titleBar.inactiveForeground": "#e7e7e799"
+    },
+    "peacock.color": "#08af3a"
 }

package/README.md

@@ -1,61 +1,229 @@
-# Google Contacts Cleanup Tool (gcards)
-
-## Goal
-Intelligent cleanup and merging of Google Contacts using the People API.
-
-## Roadmap
-- **Current**: CLI tool
-- **Future**: GUI interface
-- **Eventually**: Own contacts database (vcf as intermediate format)
-
-## Features
-- Fetch contacts via Google People API (preserves `resourceName` for reconciliation)
-- Convert to simplified JSON structure for analysis
-- Identify duplicates: **exact match first** (many blatant dupes), fuzzy matching optional/later
-- Flag test entries (pattern: `m-\d+@bob\.ma` for "Bob Frankston")
-- Generate merge candidates with confidence scores
-- Apply changes back via API using `resourceName`
-- Export to vCard format (`vcf/` directory)
-
-## Approach
-1. **Auth**: OAuth2 with Google People API scope
-2. **Fetch**: Full fetch first, save `syncToken` for incremental updates
-3. **Transform**: Convert `GooglePerson[]` → `LocalContact[]` (see `types.ts`)
-4. **Analyze**: Exact duplicate detection first, test entry flagging
-5. **Review**: Output candidates for user review
-6. **Apply**: Update/delete via API using `resourceName`
-7. **Export**: Save to `vcf/` as vCards for local backup/future DB
-8. **Log**: Track deletions in `deletion-log.json` to detect re-additions
-
-## Sync Token Usage
-- After full fetch, save `nextSyncToken`
-- Subsequent fetches: pass `syncToken` → get only new/changed/deleted
-- Deleted entries appear with `metadata.deleted: true`
-- Token expires ~30 days → fall back to full fetch (410 GONE error)
-
-## Deletion Logging
-Maintain `deletion-log.json` with:
-- `resourceName`, `displayName`, `reason`, `deletedAt`, `originalData`
-- Allows detecting if cleaned-up contact reappears (re-synced, re-added)
-
-## Setup
-1. Create Google Cloud project
-2. Enable People API
-3. Create OAuth2 credentials (Desktop app)
-4. Download `credentials.json` to this directory
-
-## Directory Structure
-```
-gcards/
-├── README.md
-├── types.ts           # TypeScript definitions
-├── credentials.json   # OAuth2 credentials (gitignored)
-├── token.json         # OAuth tokens (gitignored)
-├── sync-token.json    # Sync token for incremental fetch
-├── deletion-log.json  # Track deleted contacts
-└── vcf/               # vCard exports for future DB
-```
-
-## Test Entry Pattern
-
-Emails matching `m-[2506|2512]+@bob\.ma` with name "Bob Frankston" are test business cards to be flagged/removed. 
+# gcards - Google Contacts Management Tool
+
+A CLI tool for syncing, managing, and cleaning up Google Contacts.
+
+## Installation
+
+```bash
+npm install -g @bobfrankston/gcards
+```
+
+## Quick Start
+
+```bash
+# First time - specify your Gmail username
+gcards sync --user yourname
+
+# Subsequent runs remember the user
+gcards sync
+gcards push
+```
+
+## Commands
+
+### gcards
+
+Main sync and push operations (Google API):
+
+```bash
+gcards sync [-u user] [-a]    # Download contacts from Google
+gcards push [-u user] [-a]    # Push local changes to Google
+gcards -a                     # Process all users
+```
+
+### gfix
+
+One-time cleanup operations (local files only):
+
+```bash
+gfix inspect -u user          # Preview all standard fixes (no changes)
+gfix apply -u user            # Apply all standard fixes
+
+gfix names -u user            # Preview name parsing + dup phone/email removal
+gfix names -u user --apply    # Parse names, remove dup phones/emails
+
+gfix birthday -u user         # Preview birthday extraction
+gfix birthday -u user --apply # Extract to CSV and remove
+
+gfix undup -u user            # Find duplicate contacts -> merger.json
+gfix merge -u user            # Merge duplicates locally (then use gcards push)
+```
+
+## Google People API Fields
+
+### Identity (Names)
+
+| Field | Read/Write | Description |
+|-------|------------|-------------|
+| `names[].givenName` | Write | First name |
+| `names[].familyName` | Write | Last name |
+| `names[].middleName` | Write | Middle name |
+| `names[].honorificPrefix` | Write | Prefix (Dr., Prof., etc.) |
+| `names[].honorificSuffix` | Write | Suffix (Jr., III, PhD, etc.) |
+| `names[].displayName` | Read-only | Full name (Google generates from above) |
+| `names[].displayNameLastFirst` | Read-only | Sorting form "Last, First" (Google generates) |
+| `names[].unstructuredName` | Write | Free-form name when structured fields not available |
+
+### Sorting
+
+| Field | Read/Write | Description |
+|-------|------------|-------------|
+| `fileAses[].value` | Write | Custom sort override (e.g., "Home Depot" instead of "The Home Depot") |
+
+If blank, Google sorts by `familyName` automatically.
+
+### Contact Information
+
+| Field | Read/Write | Description |
+|-------|------------|-------------|
+| `emailAddresses[].value` | Write | Email address |
+| `emailAddresses[].type` | Write | Label: home, work, other |
+| `phoneNumbers[].value` | Write | Phone number |
+| `phoneNumbers[].type` | Write | Label: mobile, work, home, main |
+
+### Business
+
+| Field | Read/Write | Description |
+|-------|------------|-------------|
+| `organizations[].name` | Write | Company name |
+| `organizations[].title` | Write | Job title |
+
+### Dates
+
+| Field | Read/Write | Description |
+|-------|------------|-------------|
+| `birthdays[].date.year` | Write | Birth year (optional) |
+| `birthdays[].date.month` | Write | Birth month (1-12) |
+| `birthdays[].date.day` | Write | Birth day (1-31) |
+
+### Management (Required for Updates)
+
+| Field | Read/Write | Description |
+|-------|------------|-------------|
+| `resourceName` | Read-only | Unique contact ID (e.g., `people/c12345`) |
+| `etag` | Read-only | Version key - must match when updating |
+
+The `etag` prevents conflicts: if Google's version changed since you downloaded, your update will fail. Run `gcards sync` to get the latest version.
+
+## Data Directory
+
+- **Windows**: `%APPDATA%\gcards\` (app directory)
+- **Linux/Mac**: `~/.config/gcards/` (app directory)
+- **Development**: `./data/` symlink to app directory's `data/` folder
+
+### Directory Structure
+
+```
+gcards/                   # App directory (%APPDATA%\gcards or ~/.config/gcards)
+  config.json             # Last user, settings
+  data/                   # User data directory
+    <username>/
+      contacts/           # Active contacts (*.json)
+      deleted/            # Backup of deleted contact files
+      _delete/            # User requests to delete (move files here)
+      _add/               # User requests to add new contacts
+      fix-logs/           # Logs from gfix operations
+      index.json          # Active contact index (hasPhoto, starred flags)
+      deleted.json        # Deleted contacts index
+      notdeleted.json     # Contacts skipped due to photo/starred
+      token.json          # OAuth token (read-only)
+      token-write.json    # OAuth token (read-write)
+      changes.log         # Log from gfix names
+      birthdays.csv       # Extracted birthdays
+      merger.json         # Duplicates to merge (from gfix undup)
+      merged.json         # Processed merges (history)
+```
+
+## Fixes Applied by `gfix inspect/apply`
+
+- Remove leading/trailing dashes, quotes, spaces from name fields
+- Extract repeated honorific prefixes (Dr., Prof.) to `honorificPrefix`
+- Remove duplicate phone numbers (normalized comparison)
+- Remove duplicate email addresses (case-insensitive)
+
+## Name Parsing (`gfix names`)
+
+When a contact has a full name in `givenName` but no `familyName`:
+- Parses "First Middle Last" into separate fields
+- Updates `displayNameLastFirst` to proper "Last, First" format
+- Cleans up `fileAses` entries (strips junk characters)
+- Creates `changes.log` with all modifications
+
+## Workflow
+
+1. **Initial sync**: `gcards sync -u yourname`
+2. **Review fixes**: `gfix inspect -u yourname`
+3. **Apply fixes**: `gfix apply -u yourname`
+4. **Parse names**: `gfix names -u yourname --apply`
+5. **Push to Google**: `gcards push -u yourname`
+
+## Deleting Contacts
+
+Three ways to mark contacts for deletion:
+
+1. **In index.json**: Add `"_delete": true` to an entry
+2. **In contact JSON**: Add `"_delete": true` to the contact file
+3. **Move to _delete/**: Move the contact file to the `_delete/` folder
+
+Then run `gcards push` to apply deletions.
+
+### Photo/Starred Protection
+
+Contacts with photos or starred status are **not deleted** from Google to prevent data loss:
+- Contacts with non-default photos: `_delete` set to `"photo"`
+- Starred/favorite contacts: `_delete` set to `"starred"`
+
+These remain in Google and `index.json` with the skip reason. Review `notdeleted.json` after push.
+
+### Backup
+
+All deleted contact files are moved to `deleted/` folder as backup (not permanently deleted).
+Index entries move to `deleted.json`.
+
+## Duplicate Contact Merging
+
+1. **Find duplicates**: `gfix undup -u yourname`
+   - Creates `merger.json` with contacts having same name + overlapping email
+2. **Review**: Edit `merger.json`:
+   - Remove entries you don't want to merge
+   - Add `"_delete": true` to delete all contacts in a group instead of merging
+3. **Merge locally**: `gfix merge -u yourname`
+   - Updates target contact files with merged data
+   - Marks source contacts with `_delete: true`
+   - Moves processed entries to `merged.json`
+4. **Push to Google**: `gcards push -u yourname`
+5. **Resync**: `gcards sync -u yourname --full`
+
+Example `merger.json`:
+```json
+[
+  { "name": "John Smith", "emails": ["john@work.com"], "resourceNames": ["people/c1", "people/c2"] },
+  { "name": "Spam Contact", "emails": ["spam@x.com"], "resourceNames": ["people/c3", "people/c4"], "_delete": true }
+]
+```
+
+## ESC Key
+
+Press ESC during sync/push to stop safely after the current operation.
+
+## Multiple Users
+
+```bash
+# Process specific user
+gcards sync -u alice
+
+# Process all users
+gcards sync -a
+gcards push -a
+```
+
+## Setup
+
+1. Create Google Cloud project
+2. Enable People API
+3. Create OAuth2 credentials (Desktop app type)
+4. Download `credentials.json` to the gcards directory
+
+## License
+
+MIT