Meterpop macOS agent

Swift source for the Meterpop macOS menu-bar app, with 50 provider integrations for collecting billing data and syncing it to a selected Meterpop workspace. Requires macOS 13 or later; the build supports Apple silicon and Intel Macs.

This repository contains the native agent and its build/packaging scripts, not the hosted Meterpop service, dashboard, or a standalone backend. Pairing and workspace sync depend on the hosted service at api.meterpop.com.

Build from source

Install Xcode with its command-line tools and macOS SDK, and select that developer toolchain. The app uses Apple frameworks (including AppKit, Foundation, Security, and ServiceManagement); no third-party package dependencies are required.

From the repository root:

bash scripts/build.sh
open build/Meterpop.app

The script compiles both architectures and creates build/Meterpop.app with the bundled Meterpop icon. With SIGN_ID unset, this is an ad-hoc-signed developer build, not a notarized release. macOS may restrict opening it. An optional ICON_PATH can override the bundled .icns file.

scripts/package.sh is the publisher's release workflow: it requires the configured Moxitek Developer ID identity and a notarytool Keychain profile. Those credentials are not included or needed for a local build.

Publishing source does not prove that an already-distributed binary was built from it. This repository does not establish an independent security audit or certified reproducible builds.

Connect and sync

1. Open the app and pair it with your intended workspace through Meterpop's Connections page. Check the device name and destination before approving.
2. Choose a provider and read its setup instructions. Supply the required credential and provider account/project scope.
3. Explicitly test/save/sync the connection. Reuse a stable connection ID for the same billing stream to avoid duplicate streams.

Existing connections are bound to their provider scope and workspace. Disconnecting locally is not server-side revocation: revoke the device in workspace Connections, and revoke provider credentials at the provider when appropriate.

Data and permissions

• The app stores provider secrets and its workspace ingestion credential in macOS Keychain. It uses provider credentials to authenticate directly to provider APIs; they are not fields in the Meterpop billing export. This is not a claim that credentials never leave the Mac: authenticated provider requests necessarily use them.
• Non-secret pairing and connection metadata, including workspace/device IDs, provider scope and sync checkpoints, is stored locally under ~/Library/Application Support/Meterpop.
• Pairing sends the chosen device name to Meterpop. It defaults to your Mac's name, which may contain a personal name; edit it before pairing if needed. Sync sends normalized billing events to the paired workspace: event ID, timestamp (occurredAt), provider, category, source (provider-billing), connection ID, source record ID, outcome, currency, and amount in millionths of that currency (costMicros). Period-based events also include periodStart and periodEnd. Source record IDs can be provider identifiers or derived billing-bucket identifiers.
• Collection requests also include provider/connection identifiers, run ID, observation time, and health status, checkpoint, and error code. Dashboard-initiated setup exchanges a setup intent and reports status, connection ID, and an allowlisted error code when applicable. Billing amounts, identifiers and activity timing are sensitive data even without credentials; this is not an offline-only app.

Collection is intended for billing reporting, but credentials are not universally restricted to read-only capabilities. For example, OpenRouter requires a management key and SignalWire requires Management and Voice permissions. Use the narrowest supported scopes, and review each integration before granting access.

Some operations cost money: Google Cloud queries can incur BigQuery charges; Snowflake Test and Sync can incur warehouse charges; Vonage Test and Sync retrieve billable reports, including repeated reconciliation. Review provider pricing before testing.

Coverage varies by provider: reporting windows, delays, invoice versus usage totals, provisional amounts, currencies, and excluded products differ. An integration does not imply complete account spend. Follow the provider instructions in the app and reconcile against the provider's own billing records; provider billing is kept distinct from SDK estimates.

Contribute and report issues

See CONTRIBUTING.md for development guidance and SECURITY.md for private vulnerability reporting. Never post credentials or real billing data in public issues.

License

The source in this repository is licensed under Apache License 2.0. The hosted service and dashboard are not included in this source release; this license does not grant access to those services.