Intervals To Freshbooks

Phase 2: Read from Intervals

1. Select the Intervals tab using select_page
2. Run scripts/read-intervals.js using evaluate_script
3. Display the entries to user for review

The script reads from the summary table which has this structure:

• td.col-timesheet-clientproject contains "Client\nProject"
• Following cells contain: Billable, Mon, Tue, Wed, Thu, Fri, Sat, Sun, Total

Output format:

{
  success: true,
  week: "January 05, 2026",
  entries: [
    { client: "Technomic", project: "Ignite App...", billable: true,
      hours: { mon: 7.5, tue: 4.5, wed: 4.5, thu: 0, fri: 4.5, sat: 0, sun: 0 },
      totalHours: 21 }
  ],
  grandTotal: 47.75
}

Phase 3: Map Entries

For each Intervals entry, determine the FreshBooks destination:

• Client is always required for invoicing (defaults to "EXSquared")
• Project is optional - use when work is for a specific project
• If unmapped, ask user for the FreshBooks mapping
• Update references/project-mappings.md with new mappings

Mapping examples:

Phase 4: Create FreshBooks Time Entries via API

Use scripts/freshbooks-api.sh to create time entries:

# List available projects and clients
./scripts/freshbooks-api.sh projects
./scripts/freshbooks-api.sh clients

# Create a time entry
./scripts/freshbooks-api.sh create-time-entry \
  --project "<name>" | --client "<name>" \
  --date <YYYY-MM-DD> \
  --hours <hours> \
  [--note "<note>"]

For each Intervals entry with hours on a given day:

1. Check mapping type (project or client)
2. Call create-time-entry for each day with hours > 0
3. Include a note (e.g., the Intervals project name or work type)

Examples:

# With project (client defaults to EXSquared)
./scripts/freshbooks-api.sh create-time-entry \
  --project "Technomic" \
  --date "2026-01-06" \
  --hours 7.5 \
  --note "Development"

# Client only - no project (e.g., internal meetings)
./scripts/freshbooks-api.sh create-time-entry \
  --date "2026-01-06" \
  --hours 1.0 \
  --note "Meeting"

# Different client (rare)
./scripts/freshbooks-api.sh create-time-entry \
  --client "Rocksauce Studios" \
  --date "2026-01-06" \
  --hours 1.0

Phase 5: Persist to SQLite + Daily Notes

After creating FreshBooks entries, persist them locally for comparison with Intervals data.

Step 1: Read Back Entries from FreshBooks

Use the API to list entries for the synced dates:

./scripts/freshbooks-api.sh list-time-entries --from "YYYY-MM-DD" --to "YYYY-MM-DD"

Also fetch project list to resolve project IDs → names:

./scripts/freshbooks-api.sh projects

Step 2: Insert into SQLite

Insert each entry into the freshbooks_time_entries table:

sqlite3 "$OBSIDIAN_VAULT_PATH/.claude/time-entries.db" <<'SQL'
CREATE TABLE IF NOT EXISTS freshbooks_time_entries (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  date TEXT NOT NULL,
  project TEXT NOT NULL,
  hours REAL NOT NULL,
  description TEXT,
  freshbooks_entry_id TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_fb_entries_unique
  ON freshbooks_time_entries(date, project, description);
INSERT OR REPLACE INTO freshbooks_time_entries (date, project, hours, description, freshbooks_entry_id)
VALUES ('YYYY-MM-DD', 'Project Name', 2.0, 'Description', 'fb_entry_id');
SQL

• For entries with a project_id: use the resolved project name (e.g., "Technomic", "EWG")
• For entries without a project_id (client-only): use "EXSquared" as project, note as description

Step 3: Append FreshBooks Section to Daily Notes

For each date with entries, append a ### FreshBooks section to the daily note:

------
### FreshBooks
| Project | Hours | Description |
|---------|------:|-------------|
| Technomic | 2.0 | Development |
| **Total** | **8.0** | |

• If ### FreshBooks already exists in the note, replace it
• If the daily note doesn't exist, create it with a minimal header
• Right-align the Hours column
• Add a bold Total row

Phase 6: Verify

1. List created entries:

   ./scripts/freshbooks-api.sh list-time-entries --from "2026-01-05" --to "2026-01-11"
   

2. Display summary of entries created

3. Open or refresh FreshBooks in the browser for visual review:

   • Use list_pages to find FreshBooks tab
   • If found: select_page then navigate_page with type: "reload"
   • If not found: new_page with FreshBooks week URL

   URL format: https://my.freshbooks.com/#/time-tracking/week?week=YYYY-MM-DD
   (where YYYY-MM-DD is the Monday of the week)
   

Scripts

read-intervals.js

Reads the Intervals weekly summary table. No configuration needed. Run via evaluate_script - returns structured entry data.

freshbooks-api.sh

Shell script for FreshBooks API operations. Supports 1Password op:// references in credentials.

Commands:

• projects - List all FreshBooks projects
• clients - List all FreshBooks clients
• project-id <name> - Get project ID by name
• client-id <name> - Get client ID by name
• create-time-entry - Create a time entry
  • --client, -c <name> - FreshBooks client (default: EXSquared)
  • --project, -p <name> - FreshBooks project (optional)
  • --date, -d <YYYY-MM-DD> - Date of the entry (required)
  • --hours, -h <hours> - Hours worked (required)
  • --note, -n <note> - Description (optional)
• list-time-entries - List time entries
  • --from, -f <YYYY-MM-DD> - Start date
  • --to, -t <YYYY-MM-DD> - End date

Credentials: ~/.config/freshbooks/credentials.json

{
  "client_id": "op://Private/Freshbooks API/username",
  "client_secret": "op://Private/Freshbooks API/credential",
  "redirect_uri": "https://localhost/callback"
}

First-time setup:

./scripts/freshbooks-oauth.sh authorize   # Get auth URL
./scripts/freshbooks-oauth.sh exchange <code>  # Exchange code for tokens
./scripts/freshbooks-oauth.sh me          # Test connection

Key Technical Details

Intervals Summary Table

• Rows: tr containing td.col-timesheet-clientproject
• Client/Project cell: text split by \n (Client first, Project second)
• Hour cells follow: index 2-8 for Mon-Sun, index 9 for Total

FreshBooks API

Time Entry endpoint: POST /timetracking/business/{business_id}/time_entries

Payload:

{
  "time_entry": {
    "is_logged": true,
    "duration": 27000,
    "note": "Development",
    "started_at": "2026-01-06T09:00:00.000Z",
    "project_id": 12447219,
    "identity_id": 123456
  }
}

• duration is in seconds (7.5 hours = 27000 seconds)
• started_at is the date of the entry
• project_id is looked up by project name
• identity_id is the user's FreshBooks identity

Hour Format

• Intervals: decimal hours (e.g., "7.5")
• API: seconds (multiply by 3600)

Common Issues

1. Project not found: Run ./scripts/freshbooks-api.sh projects to see available project names.

2. Token expired: The script auto-refreshes tokens, but if it fails, run ./scripts/freshbooks-oauth.sh refresh.

3. Week mismatch: Make sure you're reading the correct week from Intervals.

4. 1Password CLI: If using op:// references, ensure you're signed in (op signin).