{"id":46349141,"url":"https://github.com/bitkarrot/thelookup","last_synced_at":"2026-03-04T22:30:58.536Z","repository":{"id":322047946,"uuid":"1081653403","full_name":"bitkarrot/thelookup","owner":"bitkarrot","description":"A self curating nostr directory with nip-57 payments","archived":false,"fork":false,"pushed_at":"2025-11-27T10:19:33.000Z","size":1577,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-28T00:11:43.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://nostrlookup.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitkarrot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T05:06:50.000Z","updated_at":"2025-11-27T10:19:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"4dcadd2a-d9af-4d65-98f3-8676a42ab0d3","html_url":"https://github.com/bitkarrot/thelookup","commit_stats":null,"previous_names":["bitkarrot/thelookup"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bitkarrot/thelookup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitkarrot%2Fthelookup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitkarrot%2Fthelookup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitkarrot%2Fthelookup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitkarrot%2Fthelookup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitkarrot","download_url":"https://codeload.github.com/bitkarrot/thelookup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitkarrot%2Fthelookup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30096721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T21:59:23.547Z","status":"ssl_error","status_checked_at":"2026-03-04T21:57:50.415Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-04T22:30:57.923Z","updated_at":"2026-03-04T22:30:58.523Z","avatar_url":"https://github.com/bitkarrot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TheLookup\n\nA comprehensive Nostr ecosystem explorer and directory for discovering NIPs, applications, repositories, and resources in the decentralized social network.\n\n**Important Note:** The Lookup is a Nostr client that supports flexible directory configurations. You can create either an **open directory** (showing all content from your relay) or a **curated directory** (showing only content tagged with your client tag). For curated directories, it's best used with a relay that automatically removes notes flagged by kind 1984 by relay moderators. Alternatively use an instance from *relay.tools* or *nostr.land* where you can customize the settings in a point-and-click interface. \n\n🌐 **Live Site**: [https://nostrlookup.vercel.app/](https://nostrlookup.vercel.app/)\n\n## Features\n\n### 📱 Application Directory\n- **Discover Nostr Apps**: Browse a comprehensive directory of Nostr applications\n- **Detailed App Profiles**: View screenshots, descriptions, features, and metadata\n- **Category Filtering**: Filter apps by type, platform, and functionality\n- **Community Submissions**: Submit and edit your own applications\n- **Community Moderation**: Report and flag inappropriate content using NIP-1984\n\n### 🏬 Business Listings Directory\n- **NIP-15 Business Stalls**: Discover marketplace stalls and businesses published on Nostr\n- **Client Tag Filtering**: Configurable filtering to show all listings or only those tagged with your client\n- **Search \u0026 Filter**: Search listings by name and description, and filter by tags\n- **Rich Listing Details**: Dedicated detail pages with images, description, Nostr event data, and shipping zones\n- **Owner Controls**: Listing owners can edit their stalls and request deletion via NIP-09\n- **Listing Flagging**: Community members can flag listings with NIP-1984 reports (fraud, spam, scam, duplicate, inappropriate, impersonation)\n- **Profile Integration**: Each listing displays the author's profile name with direct links to their Nostr profile\n- **Author Pages**: View all listings created by a specific author on their profile page\n\n### 📖 NIPs (Nostr Implementation Possibilities)\n- **Official NIPs**: Browse and search through official NIPs from the [nostr-protocol/nips](https://github.com/nostr-protocol/nips) repository\n- **Custom NIPs**: Publish your own custom NIPs on the Nostr network using kind 30817 events\n- **Rich Markdown**: Full markdown rendering with syntax highlighting for code blocks\n- **NIP-19 Support**: Support for naddr identifiers and direct linking\n- **Edit \u0026 Update**: Edit and update your published NIPs\n\n### 🗂️ Repository Explorer\n- **Git Repository Discovery**: Browse Nostr-related repositories and projects\n- **Issue Tracking**: View and create issues for repositories\n- **Patch Management**: Submit and review patches\n- **Repository Announcements**: Announce new repositories to the community\n\n### 🌐 Resources Hub\n- **Essential Tools**: Curated list of Nostr tools, services, and gateways\n- **Community Resources**: Discover relays, clients, and development resources\n- **Categorized Listings**: Organized by type (Official, Relay, Tools, Gateway, etc.)\n\n### 🔧 Developer Tools\n- **DVM Marketplace**: Discover and interact with Data Vending Machines\n- **Event Explorer**: View and analyze Nostr events by kind\n- **Author Profiles**: Explore user profiles and their contributions across all sections\n\n### 👤 Enhanced Profile Pages\n- **Section Configuration**: Configurable sections based on `VITE_SECTIONS` environment variable\n- **Author Listings**: Display business listings created by profile owners\n- **Profile Links**: Direct links to author profiles from listing and app cards\n- **Comprehensive Views**: Shows Custom NIPs, Apps, Repositories, and Listings based on configuration\n- **Owner Controls**: Edit and delete actions for profile owners on their own content\n\n### 🎨 Modern UI/UX\n- **Beautiful Themes**: Support for tweakcn.com themes with OKLCH color spaces\n- **Responsive Design**: Works seamlessly on desktop and mobile devices\n- **Dark/Light Mode**: Automatic theme switching with system preference detection\n- **Smooth Animations**: Polished interactions and transitions\n- **Optimized Images**: Circular avatars with proper cropping using object-fit for professional appearance\n- **Profile Integration**: Seamless profile links throughout listings and app cards\n\n## URL Structure\n\n### Main Sections\n- `/` - Business listings directory (home page)\n- `/resources` - Nostr resources and tools hub\n- `/nips` - NIPs browser and directory\n- `/repositories` - Git repository explorer\n- `/dvm` - Data Vending Machine marketplace\n\n### Business Listings\n- `/listings` - Business directory for NIP-15 marketplace stalls\n- `/listings/submit` - Submit a new business listing\n- `/listings/:stallId` - View business listing details\n- `/listings/:stallId/edit` - Edit an existing business listing (owner only)\n\n### NIPs\n- `/nip/01` - View official NIP-01\n- `/nip/naddr1...` - View custom NIP by naddr (NIP-19 identifier)\n- `/create` - Create a new custom NIP\n- `/edit/naddr1...` - Edit an existing custom NIP (owner only)\n\n### Applications\n- `/apps` - Browse all applications\n- `/apps/t/:tag` - Filter apps by category tag\n- `/apps/submit` - Submit a new application\n- `/apps/edit/:naddr` - Edit an existing application\n\n### Repositories\n- `/repositories` - Browse all repositories\n- `/repositories/create` - Announce a new repository\n- `/repositories/:naddr` - View repository details\n- `/repositories/:naddr/edit` - Edit repository information\n- `/repositories/:naddr/issues/create` - Create new issue\n- `/repositories/:nip19/issues/:issueId` - View specific issue\n- `/repositories/:nip19/patches/:patchId` - View specific patch\n\n### Other\n- `/kind/:k` - View events by Nostr event kind\n- `/:nip19` - Universal NIP-19 identifier resolver\n- `/notifications` - User notifications\n\n## Custom NIP Format\n\nCustom NIPs are published as kind 30817 events with the following structure:\n\n- `content`: The markdown content of the NIP\n- `d` tag: Unique identifier for the NIP\n- `title` tag: The title of the NIP\n- `k` tags: Event kinds that this NIP defines or relates to (optional)\n\n## Technology Stack\n\n### Frontend\n- **React 18** with TypeScript for robust component architecture\n- **Vite** for fast development and optimized builds\n- **React Router** for client-side routing\n- **TanStack Query** for efficient data fetching and caching\n\n### Styling \u0026 UI\n- **TailwindCSS** for utility-first styling\n- **shadcn/ui** for beautiful, accessible UI components\n- **tweakcn.com themes** for customizable color schemes with OKLCH support\n- **Lucide React** for consistent iconography\n- **Radix UI** for headless, accessible component primitives\n\n### Nostr Integration\n- **Nostrify** for Nostr protocol integration and event handling\n- **nostr-tools** for additional Nostr utilities\n- **NIP-07** browser extension support for authentication\n\n### Content \u0026 Media\n- **React Markdown** with **remark-gfm** for GitHub Flavored Markdown\n- **Prism.js** for syntax highlighting in code blocks\n- **QR Code** generation for sharing\n- **Rehype Highlight** for enhanced code highlighting\n\n### Development \u0026 Testing\n- **ESLint** with TypeScript support for code quality\n- **Vitest** for unit testing\n- **Testing Library** for component testing\n- **SWC** for fast compilation\n\n## Environment Variables\n\nThe site can be customized by setting environment variables. Copy `.env.example` to `.env` and customize:\n\n```bash\n# Site Configuration\nVITE_SITE_NAME=lookup-client           # Client tag for filtering listings (optional)\nVITE_SITE_URL=https://thelookup.app    # Full site URL\nVITE_SITE_DISPLAY_NAME=TheLookup       # Display name shown in UI\n\n# Navigation Configuration\nVITE_SECTIONS=listings,apps,nips       # Comma-separated list of visible sections (optional)\n```\n\n### Deployment Customization\n\nWhen deploying your own instance, you can customize:\n\n1. **Site Name**: Changes the client tag in published events and redirect targets\n2. **Site URL**: Used for any absolute URLs that reference the site\n3. **Display Name**: The name shown in the UI and page titles\n\nExample for a custom deployment:\n\n```bash\n# .env\nVITE_SITE_NAME=my-nostr-directory.com\nVITE_SITE_URL=https://my-nostr-directory.com\nVITE_SITE_DISPLAY_NAME=My Nostr Directory\n```\n\n### Client Tag Filtering\n\nThe business listings directory supports **client tag filtering** to create curated directories:\n\n#### How It Works\n- **No `VITE_SITE_NAME` set**: Shows **all** business listings from the relay\n- **`VITE_SITE_NAME` configured**: Shows **only** listings tagged with that client tag\n\n#### Use Cases\n1. **Open Directory**: Don't set `VITE_SITE_NAME` to show all businesses on your relay\n2. **Curated Directory**: Set `VITE_SITE_NAME=my-client` to show only businesses tagged with \"my-client\"\n3. **Multi-Client Relay**: Different instances can show different subsets of the same relay's data\n\n#### Configuration Examples\n\n**Open directory (shows all listings):**\n```bash\n# Don't set VITE_SITE_NAME or leave it empty\n# VITE_SITE_NAME=\n```\n\n**Curated directory (shows only tagged listings):**\n```bash\nVITE_SITE_NAME=my-business-directory\n# Only shows listings tagged with \"my-business-directory\"\n```\n\n#### Technical Details\n- Client tags are added automatically to events published by your instance\n- Filtering happens at the data layer for optimal performance\n- Other instances can use the same relay with different client tags\n- Backward compatible with existing deployments\n\n### Section Configuration\n\nControl which sections appear in the navigation and profile pages using the `VITE_SECTIONS` environment variable:\n\n#### Available Sections\n- `resources` - Nostr resources and tools hub\n- `nips` - NIPs browser and custom NIPs\n- `apps` - Application directory\n- `listings` - Business listings directory\n- `repositories` - Git repository explorer\n- `dvm` - Data Vending Machine marketplace\n\n#### Configuration Examples\n\n**Show all sections (default):**\n```bash\n# Don't set VITE_SECTIONS or leave it empty\n# VITE_SECTIONS=\n```\n\n**Show only specific sections:**\n```bash\nVITE_SECTIONS=listings,apps\n# Only shows listings and apps in navigation and profile pages\n```\n\n**Business-focused directory:**\n```bash\nVITE_SECTIONS=listings,resources\n# Perfect for business directories with supporting resources\n```\n\n#### Profile Page Integration\n- Profile pages automatically respect the section configuration\n- Only configured sections will display author content\n- Maintains consistent user experience across navigation and profiles\n- Authors can only see edit/delete controls for visible sections\n\n## Development\n\n```bash\n# Install dependencies and start development server\nnpm run dev\n\n# Run tests\nnpm run test\n\n# Build for production\nnpm run build\n\n# Deploy\nnpm run deploy\n```\n\n### Development Environment Variables\n\nFor development, you can create `.env.local` to override settings locally without affecting the repository:\n\n```bash\n# .env.local (for development only)\nVITE_SITE_NAME=localhost:5173\nVITE_SITE_URL=http://localhost:5173\nVITE_SITE_DISPLAY_NAME=TheLookup\n```\n\n### Theme Customization\n\nTheLookup supports beautiful themes from [tweakcn.com](https://tweakcn.com). To add a new theme:\n\n```bash\n# Find a theme on tweakcn.com and use the CLI\nnpx shadcn@latest add https://tweakcn.com/r/themes/[theme-id]\n```\n\nThe theme system uses OKLCH color spaces for vibrant, consistent colors across light and dark modes.\n\n### Lightning Payments\n\nTheLookup supports **Lightning payments for submissions** (apps and business listings) to prevent spam and maintain directory quality:\n\n- **NIP-57 Integration**: Uses Lightning Zaps for payment verification\n- **Configurable Fees**: Set custom satoshi amounts for new submissions\n- **Smart Logic**: Only new users pay - existing authors/listing owners can edit for free\n- **Multiple Wallets**: Supports QR codes, WebLN, and manual invoice copying\n- **Anti-Spam**: Helps maintain high-quality directories\n\nKey environment variables:\n\n- **Apps**: `VITE_SUBMIT_APP_PAYMENT_ENABLED`, `VITE_SUBMIT_APP_LIGHTNING_ADDRESS`, `VITE_SUBMIT_APP_FEE`\n- **Business listings**: `VITE_SUBMIT_LISTING_PAYMENT_ENABLED`, `VITE_SUBMIT_LISTING_LIGHTNING_ADDRESS`, `VITE_SUBMIT_LISTING_FEE`\n\nFor detailed setup instructions, configuration options, and troubleshooting, see **[LIGHTNING_PAYMENTS.md](./LIGHTNING_PAYMENTS.md)**.\n\n### Resources Management\n\nThe `/resources` page displays community resources from a **markdown file** for easy editing:\n\n- **Non-Technical Editing**: Resources are stored in `public/RESOURCES.md` \n- **Simple Format**: Each resource uses standard markdown with metadata\n- **No Code Required**: Add, edit, or remove resources without touching code\n- **Automatic Icons**: Choose from predefined Lucide icons\n- **Categories**: Organize resources by type (Official, Relay, Tools, etc.)\n\nTo edit resources, simply modify **[public/RESOURCES.md](./public/RESOURCES.md)** following the documented format.\n\n### Featured Apps Management\n\nThe `/apps` page displays **featured Nostr applications** in an auto-rotating carousel from a markdown file for easy curation:\n\n- **Auto-Rotating Carousel**: 4-second intervals with smooth transitions and infinite loop\n- **Responsive Layout**: Shows 2-4 cards per row based on screen width (mobile: 2, tablet: 3, desktop: 4)\n- **Authentic Icons**: Uses actual website favicons/logos via remote URLs\n- **Community Curation**: Featured apps are stored in `public/FEATURED_APPS.md`\n- **Rich Metadata**: Each app includes category, platform, description, and icon URL\n- **Platform Support**: Tag apps by platform (Web, iOS, Android, Desktop, All)\n- **Categories**: Organize by type (Social, Client, Tools, Media, Gaming, etc.)\n- **Interactive Features**: Manual navigation, hover effects, and click-to-visit functionality\n- **Strategic Placement**: Positioned prominently at the top of `/apps` page above search filters\n\n**Icon Support**: \n- **Remote URLs**: Use `https://website.com/favicon.ico` for actual website icons\n- **Fallback Icons**: Lucide icon names for consistent styling when needed\n\nTo manage featured apps, edit **[public/FEATURED_APPS.md](./public/FEATURED_APPS.md)** following the documented format.\n\n## Content Flagging System\n\nThe app and business listing directories include a community-driven content moderation system using NIP-1984 report events:\n\n### Report Categories\n- **fraud** - Fake information\n- **spam** - Unwanted promotional content\n- **scam** - Malicious/deceptive content\n- **duplicate** - Duplicate entries\n- **inappropriate** - Violates community standards\n- **impersonation** - Fake identity/business\n\n### How Flagging Works\n1. **Signed-in users** can flag any app from the app detail page\n2. **Flag reports** are published as kind 1984 events on Nostr\n3. **Flag counts** are displayed prominently on app detail pages\n4. **Severity indicators** show warning levels based on flag count\n5. **One flag per user** prevents duplicate reports from the same person\n\n### Flag Event Structure\n```json\n{\n  \"kind\": 1984,\n  \"pubkey\": \"flagger_pubkey\",\n  \"content\": \"This directory entry appears to be fraudulent - fake business information\",\n  \"tags\": [\n    [\"e\", \"target_event_id\", \"relay_url\"],\n    [\"p\", \"target_author_pubkey\"],\n    [\"report\", \"fraud\"],\n    [\"l\", \"app-flag\", \"thelookup.app.flags\"],\n    [\"k\", \"31990\"]\n  ]\n}\n```\n\n### Community Guidelines\n- **Only flag apps that violate community standards**\n- **Provide detailed descriptions** for your reports\n- **False reports may result in account suspension**\n- **Flag data is public** and visible to all users\n\n## Contributing\n\nTheLookup welcomes contributions from the Nostr community! Here's how you can help:\n\n### Code Contributions\n- **Report bugs** or suggest features via GitHub issues\n- **Submit pull requests** for improvements and new features\n- **Improve documentation** and help others understand the codebase\n- **Add tests** to ensure reliability and prevent regressions\n\n### Content Contributions\n- **Submit applications** to the directory\n- **Create and share** your own custom NIPs\n- **Announce repositories** and projects\n- **Curate resources** and help maintain quality listings\n\n### Community Contributions\n- **Test new features** and provide feedback\n- **Help moderate content** through the flagging system\n- **Share TheLookup** with other Nostr users and developers\n- **Translate** the interface to other languages (future feature)\n\n### Development Setup\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork** locally\n3. **Install dependencies**: `npm install`\n4. **Start development server**: `npm run dev`\n5. **Make your changes** and test thoroughly\n6. **Submit a pull request** with a clear description\n\n## License\n\nMIT License - see LICENSE file for details.\n\n---\n\n**Built with ❤️ for the Nostr community**\n\n*TheLookup is an open-source project dedicated to making the Nostr ecosystem more discoverable and accessible to everyone.*\n\n The Lookup is based on a fork of nostrhub.io \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitkarrot%2Fthelookup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitkarrot%2Fthelookup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitkarrot%2Fthelookup/lists"}