diff --git a/.bolt/config.json b/.bolt/config.json deleted file mode 100644 index dcbccdcc..00000000 --- a/.bolt/config.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "template": "vite-vue" -} diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 2b18f0ec..495e7620 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -18,7 +18,28 @@ "WebFetch(domain:thebitcoinmanual.com)", "Bash(ls:*)", "Bash(npm install:*)", - "Bash(node:*)" + "Bash(node:*)", + "Bash(grep:*)", + "Bash(wc:*)", + "Bash(npx vite:*)", + "Bash(npm ls:*)", + "Bash(for f:*)", + "Bash(for file:*)", + "Bash(cat:*)", + "Bash(echo:*)", + "Bash(npm info:*)", + "Read(//Users/drshift/projects/nostr-core/**)", + "Bash(find /Users/drshift/projects/zap_dashboard_hackathon/src -name main.js -o -name *router* -o -name *route*)", + "Bash(while read:*)", + "Bash(do basename:*)", + "Bash(done)", + "Bash(do echo:*)", + "Read(//Users/drshift/projects/zap_dashboard_hackathon/**)", + "WebFetch(domain:nostr-core.netlify.app)", + "Bash(npm view:*)", + "Bash(npm pack:*)", + "Bash(npx vitest:*)", + "Bash(do sed:*)" ] } } diff --git a/.gitignore b/.gitignore index 882a17ee..4989883c 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,4 @@ dist-ssr output .env +.claude diff --git a/README.md b/README.md index cb3294e5..7b2f6bb8 100644 --- a/README.md +++ b/README.md @@ -1,213 +1,157 @@ -

⚡ Zap Tracker - All-in-One Dashboard

-

- Hackathon Winner - OpenSats Grant -

- - - - -### Project Overview -Zap Tracker revolutionizes how creators and users interact with Bitcoin Lightning & Nostr by providing a unified dashboard experience. In today's fragmented ecosystem, managing Zap payments, analytics, and community engagement requires juggling multiple platforms and tools. Zap Tracker eliminates this complexity by bringing everything together in one comprehensive interface. - -The platform serves as a central hub for Lightning Network payment management, offering real-time visibility into your Zap ecosystem. Users can monitor their complete payment history, track supporter engagement, and analyze performance metrics through intuitive visualizations. + ZapTracker +

-### Documentation +

ZapTracker

-| Document | Description | -|----------|-------------| -| [GUIDE.md](GUIDE.md) | Comprehensive user guide with step-by-step instructions | -| [use_cases.md](use_cases.md) | Real-world scenarios for creators, merchants, communities | -| [STRUCTURE.md](STRUCTURE.md) | Technical codebase organization for contributors | -| [nip07.md](nip07.md) | NIP-07 browser extension specification | -| [Docs](https://docs-zaptracker.netlify.app) | Documentation for ZapTracker | - -### Getting Started -A modern, real-time dashboard for managing and analyzing Lightning Network zaps (tips) with Nostr Wallet Connect integration. - -Dashboard OverviewBildschirmfoto 2026-03-01 um 16 28 06 - -> **🔒 Privacy First**: We don't store any of your data on our servers. All data is stored locally in your browser's local storage, ensuring your privacy and data sovereignty. - -[//]: # (### 📈 **Content Analytics**) +

+ Your all-in-one Bitcoin Lightning & Nostr dashboard +

-[//]: # (- Content performance metrics) +

+ Hackathon Winner + OpenSats Grant + Vue 3 + MIT License +

-[//]: # (- Revenue analytics per content) +

+ Live App • + Features • + User Guide • + Use Cases • + Contributing +

-[//]: # (- Engagement tracking) +--- -[//]: # (- Creator insights dashboard) +ZapTracker brings everything a Nostr creator needs into one place: SocialDesk, Zap analytics, wallet management, content publishing, audience growth, and fundraising campaigns. No server, no sign-up -- your data stays in your browser. + +## Features at a Glance + + + + + + + + + + + + + + + + + + + + + +
+ Dashboard +
Dashboard
+ Real-time zap metrics, activity charts, and recent supporters + 		+ Analytics +
Analytics
+ Deep insights into zap performance, top supporters, and trends +
+ Zap Feed +
Zap Feed
+ Live activity stream with time filters and compact view + 		+ Chat +
Chat + Zaps
+ Message your community and request payments inline +
+ Content +
Content Studio
+ Publish long-form articles (NIP-23) and track revenue per post + 		+ Notes +
Notes
+ Short-form posts with engagement metrics and revenue tracking +
+ Campaigns +
Campaigns
+ Kickstarter-style fundraising powered by Bitcoin zaps + 		+ Audience +
Audience
+ Manage followers, discover people, and curate Follow Packs +
+ Calendar +
Calendar
+ Schedule and manage your zap-related events +
+ +> See the full [Features Guide](docs/FEATURES.md) for wallet, media library, MiniPoS, and more. ## Quick Start ### Prerequisites -- Node.js 18+ -- npm or yarn -- A Nostr Wallet Connect enabled wallet (e.g., Alby, Buho, Coinos, LNBits) -- A Nostr Identity - -### Installation -1. **Clone the repository** - ```bash - git clone - cd zap_dashboard - ``` +- Node.js 18+ +- A Nostr identity (browser extension like [Alby](https://getalby.com) or nos2x) +- A [Nostr Wallet Connect](https://nwc.dev) enabled wallet -2. **Install dependencies** - ```bash - npm install - ``` +### Install & Run -3. **Start development server** - ```bash - npm run dev - ``` +```bash +git clone https://github.com/DoktorShift/zap_dashboard_hackathon.git +cd zap_dashboard_hackathon +npm install +npm run dev +``` -4. **Open your browser** - Navigate to `http://localhost:5173` +Open [http://localhost:5173](http://localhost:5173) and connect your wallet. -### Building for Production +### Build for Production ```bash npm run build npm run preview ``` -## 🔌 Setup ZapTracker - -> **Need detailed instructions?** See the [complete setup guide](GUIDE.md#first-steps) for troubleshooting and tips. - -### Get your NWC URL -- Open your NWC Provider -- Go to Settings → Connect Apps -- Copy your Nostr Wallet Connect URL - -![Connect_NWC](https://storage.googleapis.com/geyser-images-distribution-prod-us/7effb1e8-904b-4d1d-9234-4c13c646fce5_nwc-connect-preview/image_large.webp) - -### Main Dashboard -- **Total Zaps**: Real-time count of received zaps -- **Total Sats**: Cumulative zap amount in satoshis -- **Average Zap**: Mean zap amount -- **Unique Supporters**: Number of unique zap senders -- **Wallet Balance**: Current Lightning wallet balance -- **Activity Chart**: 30-day zap activity visualization - -Dashboard OverviewBildschirmfoto 2026-03-01 um 16 28 06 - -### Zap Feed -- Real-time zap notifications -- Content performance tracking -- Supporter analytics - -Zap Feed -Bildschirmfoto 2026-03-01 um 16 54 55 - - -### Chat -- Interactive chat -- Community connection -- Request Payments +## Privacy First -Chat Interface -Bildschirmfoto 2026-03-01 um 15 55 05 +ZapTracker stores **zero data on any server**. Everything lives in your browser's local storage. Your keys, your data, your sovereignty. +## Tech Stack -### Wallet -- Nostr Wallet Connect (NWC) integration -- Real-time balance monitoring -- Send and receive Lightning payments -- QR code generation and scanning -- Transaction history +| Layer | Technology | +|-------|-----------| +| Framework | Vue 3 (Composition API) | +| Build | Vite + PWA | +| Styling | TailwindCSS | +| Nostr | [nostr-core](https://www.npmjs.com/package/nostr-core) | +| Charts | ECharts via vue-echarts | +| Media | Blossom protocol | +| Calendar | FullCalendar | -> Learn more about [wallet operations](GUIDE.md#wallet-operations) or see [merchant use cases](use_cases.md#merchants--freelancers). +## Documentation +| Document | What's inside | +|----------|--------------| +| **[Features](docs/FEATURES.md)** | Detailed walkthrough of every feature with screenshots | +| **[User Guide](GUIDE.md)** | Step-by-step setup, wallet ops, content creation, troubleshooting | +| **[Use Cases](use_cases.md)** | Real-world scenarios for creators, merchants, communities | +| **[Architecture](STRUCTURE.md)** | Codebase organization for contributors | +| **[Contributing](docs/CONTRIBUTING.md)** | How to contribute, dev guidelines, PR process | -### Content Management -- Create and manage content posts -- Track content performance and engagement -- Content monetization with zaps -- Content analytics and insights +## Support -> See [use cases for content creators](use_cases.md#content-creators) for monetization strategies. - -![Content Management](https://storage.googleapis.com/geyser-images-distribution-prod-us/bdc7adfe-fd7c-43d4-a348-30ffd5f3ad99_new_content_ui_2/image_large.webp) - -[See Blog Post on Geyser](https://geyser.fund/project/zaptracker/posts/view/4860?hero=drshift) - -### Media Library -- Upload and manage media via decentralized Blossom servers -- Grid and list views with type filtering (images, video, audio) -- Fullscreen preview with keyboard navigation -- Copy URL, download, and bulk delete operations -- Drag-and-drop upload with multi-server support - -> See [GUIDE.md - Media Management](GUIDE.md#media-management) for details. - -Bildschirmfoto 2026-03-01 um 16 54 30 - - -### Analytics -- Live zap tracking and statistics -- Interactive charts and visualizations -- Performance metrics and insights -- Daily, weekly, and monthly activity views - -> Dive deeper into [analytics interpretation](GUIDE.md#analytics-deep-dive) for actionable insights. - -Analytics Dashboard -Bildschirmfoto 2026-03-01 um 16 55 13 - -### Audience -- Build your community with [Follow Packs](https://github.com/callebtc/following.space) -- Engage & grow your supporter base - -> Learn how to [build and curate Follow Lists](GUIDE.md#growing-your-audience) or see [community builder use cases](use_cases.md#community-builders). - -![Audience](https://storage.googleapis.com/geyser-images-distribution-prod-us/cd595b5c-2807-46f4-91f7-f8e722cea04f_Audience_2/image_large.webp) -[See Blog Post on Geyser](https://geyser.fund/project/zaptracker/posts/view/4926?hero=drshift) - -### ZapGoals -- Set funding goals like Kickstarter - but with Bitcoin zaps -- Track progress, motivate supporters, unlock milestones - -> See how to [run successful campaigns](GUIDE.md#running-campaigns) or explore [event organizer](use_cases.md#event-organizers) and [open source funding](use_cases.md#open-source-developers) use cases. - -![ZapGoals](https://storage.googleapis.com/geyser-images-distribution-prod-us/2069d1d6-edfb-4b78-b291-4de2b849c86a_sneak_peek_campaigns_4/image_large.webp) - -[See Blog Post on Geyser](https://geyser.fund/project/zaptracker/posts/view/4831?hero=drshift) - -## 🤝 Contributing - -> **First time contributing?** Check out [STRUCTURE.md](STRUCTURE.md) to understand the codebase organization. - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - -[//]: # (### Development Guidelines) - -[//]: # (- Use Vue 3 Composition API) - -[//]: # (- Follow Tailwind CSS conventions) - -[//]: # (- Write meaningful commit messages) - -[//]: # (- Test thoroughly before submitting PRs) - -## 📞 Support - -- **Issues**: [GitHub Issues](https://github.com/pratik227/zap_dashboard/issues) -- **Discussions**: [GitHub Discussions](https://github.com/pratik227/zap_dashboard/discussions) +- **Issues**: [GitHub Issues](https://github.com/DoktorShift/zap_dashboard_hackathon/issues) +- **Discussions**: [GitHub Discussions](https://github.com/DoktorShift/zap_dashboard_hackathon/discussions) +- **Docs**: [docs-zaptracker.netlify.app](https://docs-zaptracker.netlify.app) --- -**Made with ⚡ by the [Pratik](https://github.com/pratik227) and [DoktorShift](https://github.com/DoktorShift)** - -## 📄 License - -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +

+ Made with zap by + Pratik & + DoktorShift + • Licensed under MIT +

diff --git a/STRUCTURE.md b/STRUCTURE.md index e55bf0ed..ff4d68d4 100644 --- a/STRUCTURE.md +++ b/STRUCTURE.md @@ -237,12 +237,24 @@ General-purpose utilities used across the application. - `timeFilter.js` - Time filtering utilities ### Network Utilities (`utils/network/`) -Nostr relay and Lightning Network utilities. +Lightning Network utilities. **Files:** - `lightningNetworkService.js` - Lightning Network service - `lightningStatsService.js` - Lightning stats fetching -- `nostrRelayManager.js` - Nostr relay connection management + +### Nostr Service Layer (`services/nostr/`) +Centralized Nostr protocol abstraction powered by nostr-core v0.6.0. + +**Files:** +- `NostrService.js` - Relay pool management, subscriptions, publishing, health checks, backoff +- `nostrImports.js` - Single source of truth for all nostr-core re-exports and compatibility shims +- `CacheManager.js` - Centralized cache with namespaces (events, profiles, contacts, search, badges) +- `ProfileService.js` - Profile fetching with dedup, batch support, and cache integration +- `WalletService.js` - NWC wallet abstraction (connect, pay, balance, transactions) +- `SignerService.js` - Signer abstraction (NIP-07 extension, encrypt/decrypt) +- `errors.js` - Typed error classes (RelayError, SignerError, SubscriptionError) +- `index.js` - Barrel export for all services ### Core Composables (`composables/core/`) Core application-wide composables. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..03503731 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,124 @@ +# Contributing to ZapTracker + +Thanks for your interest in contributing! ZapTracker is an open-source Nostr dashboard backed by an OpenSats grant. Every contribution — bug fix, feature, docs, tests — moves the needle for creators on the Bitcoin/Nostr stack. + +> **First time?** Read the [Architecture Guide](../STRUCTURE.md) to understand the codebase layout. + +--- + +## Why Your Contribution Matters + +ZapTracker has no server and no sign-up. That means reliability and UX quality are entirely in the codebase. A contribution that fixes a relay reconnect bug or adds a missing retry button directly impacts every creator using the tool. The code you ship is the product. + +The project just completed a major revamp (outbox model activation, unified publishing, typed errors, storage abstraction, subscription lifecycle fixes). The foundation is now solid — and there's a clear backlog of improvements ready for new contributors to pick up. + +--- + +## Good First Issues + +We maintain open issues specifically designed to make onboarding smooth. Look for: + +- **`good first issue`** — self-contained, well-scoped, no deep context needed +- **`help wanted`** — higher impact, documented context in the issue + +Browse them at: [GitHub Issues](https://github.com/DoktorShift/zap_dashboard_hackathon/issues) + +These issues typically cover: +- UI polish and empty states +- Missing test coverage +- NIP feature completions (e.g. NIP-17 gift wrap, NIP-75 progress helpers) +- Accessibility improvements +- Documentation gaps + +--- + +## Getting Started + +1. **Fork** the repository +2. **Clone** your fork + ```bash + git clone https://github.com//zap_dashboard_hackathon.git + cd zap_dashboard_hackathon + ``` +3. **Install** dependencies + ```bash + npm install + ``` +4. **Create** a feature branch + ```bash + git checkout -b feature/your-feature-name + ``` +5. **Start** the dev server + ```bash + npm run dev + ``` + +You'll need a Nostr browser extension (Alby or nos2x) to log in during development. + +--- + +## Development Guidelines + +### Stack conventions +- **Vue 3 Composition API** — use `