Feat/perplexity plugin

[garanda21]

Description

This pull request adds support for Perplexity usage tracking to the project. It introduces a new Perplexity plugin that reads local session data from the Perplexity macOS app cache, queries the REST API for balance and usage analytics, and displays usage information in the menu bar. The implementation includes robust handling of local cache formats, authentication, and fallback logic for reading SQLite databases. Comprehensive documentation and tests are also provided.

Perplexity Plugin Implementation:

• Added a new Perplexity plugin (plugin.js, plugin.json) that:

  • Reads the user's bearer token and app headers from the Perplexity macOS app's local cache DB.
  • Queries the Perplexity REST API for balance and usage analytics using extracted credentials.
  • Outputs a progress bar showing AI usage against the user's balance, with support for detecting "Pro" plan status.
  • Handles edge cases like missing sessions, cache format changes, and Cloudflare protection. [1] [2]

• Added a test suite (plugin.test.js) to cover:

  • Successful usage retrieval from both primary and fallback cache paths.
  • Error handling for missing or malformed cache/session.
  • Correct parsing of bearer tokens and headers from the cache.
  • Ensuring no environment variables are read.

Documentation:

• Added a detailed documentation page for Perplexity usage tracking, including protocol, authentication, data sources, output format, and limitations.
• Updated the main README.md to include Perplexity as a supported provider.

SQLite Access Improvements:

• Improved SQLite database access in the host API:
  • Now tries a standard read-only open first (to ensure WAL contents are visible), with a fallback to immutable=1 if WAL/SHM locks are encountered (common after macOS sleep).
  • Enhanced error reporting to show both primary and fallback errors for easier debugging. [1] [2]

Related Issue

Link to the issue this PR addresses: Fixes #122

Type of Change

• Bug fix
• New feature
• New provider plugin
• Documentation
• Performance improvement
• Other (describe below)

Testing

• I ran bun run build and it succeeded
• I ran bun run test and all tests pass
• I tested the change locally with bun tauri dev

Screenshots

Checklist

• [ x ] I read CONTRIBUTING.md
• [ x ] My PR targets the main branch
• [ x ] I did not introduce new dependencies without justification

---

Summary by cubic

Adds a Perplexity provider that shows balance and spend in the menu bar using the macOS app’s local session. Improves SQLite reads to handle WAL/SHM locks with clearer errors and avoids false $0 usage when analytics are blocked; fixes #122.

• New Features

  • Reads bearer token + app-like headers from CFNetwork Cache.db (no env), with container and fallback paths.
  • Calls groups, group, and usage-analytics; shows a dollars progress bar and detects Pro plan.
  • Clear errors for missing session, cache changes, or Cloudflare; strips bplist marker; docs and tests added.
  • Corrected plugin brand color and icon fill.

• Refactors

  • SQLite host API tries normal read-only first, then immutable=1 on WAL/SHM locks.
  • Error reporting now shows both primary and fallback failures.

^{Written for commit 5a44815. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 7 files

[robinebers]

Thanks for the contribution - this plugin is a strong start, and docs/tests are clear. I’m an AI code reviewer helping with this PR, and I found one important fix before merge:

1. In plugin.js, when usage analytics cannot be fetched, the code falls back to used = 0 (sumUsageCostUsd(...) || 0). This can show a false "$0 used" value when data is actually unavailable (for example, Cloudflare or API errors). Please handle this as "usage unavailable" (or throw a clear message) instead of defaulting to zero.

[garanda21]

The changes have been applied: unavailable usage data is now handled explicitly instead of defaulting to $0, with tests added to cover this case.

[robinebers]

One last thing, the plugins/perplexity/icon.svg must be currentColor and the brandColor must be set to the Perplexity accent color #20808D

then I think we're ready to merge (subject to final review and test)

[garanda21]

I think is done now, let me know if wee need any other improvements!

[robinebers]

Tested and verified, thank you!