# 🌐 Community Marketplace Integration

The Neode UI now includes a **Community Marketplace** tab that connects to the real Start9 app ecosystem!

## Features

### 📑 Two-Tab Interface

**Local Apps Tab:**
- Your custom local apps (k484, atob, amin)
- Sideload packages from URLs
- Quick install for development apps

**Community Marketplace Tab:**
- **Real Start9 packages** from the community registry
- Search functionality
- Bitcoin Core, Lightning Network, BTCPay, Nextcloud, and more!
- GitHub repository links
- Author information

### 🔍 Search & Filter

Search across:
- App names
- Descriptions
- Package IDs
- Author names

### 🎨 Beautiful UI

- Glass-morphism design (matching Neode aesthetic)
- Responsive grid layout
- Loading states
- Error handling with retry
- Install progress indicators

## How It Works

### 1. **Fetches Real Data**

Connects to Start9's community registry:
```
https://registry.start9.com/api/v1/packages
```

### 2. **Smart Multi-Level Fallback System**

If the Start9 registry is unavailable, the system automatically tries multiple sources:

**Level 1:** Start9 Registry API (primary)
```
https://registry.start9.com/api/v1/packages
```

**Level 2:** GitHub API (dynamic)
```
https://api.github.com/users/Start9Labs/repos
```
- Fetches all `-startos` repositories from Start9Labs
- Dynamically builds app list from actual packages
- Shows real-time ecosystem

**Level 3:** Curated App List (ultimate fallback)
Shows 20+ popular Start9 ecosystem apps including:

**Bitcoin & Lightning:**
- Bitcoin Core, Bitcoin Knots
- Core Lightning (CLN), LND  
- BTCPay Server
- Ride The Lightning, ThunderHub
- Electrs, Mempool Explorer
- Specter Desktop

**Communication & Social:**
- Synapse (Matrix)
- Nostr Relay
- CUPS Messenger

**Productivity & Storage:**
- Nextcloud
- Vaultwarden (password manager)
- File Browser

**Media:**
- Jellyfin (media server)
- PhotoPrism (AI photos)
- Immich (photo backup)

**Smart Home:**
- Home Assistant

**You'll see a blue info banner:** "📚 Community Apps: Showing X Start9 ecosystem applications."

### 3. **Installation Flow**

When you click "Install" on a community app:
1. Calls `package.install` RPC method with the `.s9pk` URL
2. Backend downloads and extracts the package
3. Polls for installation completion
4. Redirects to Apps page when done

## Usage

### Access the Marketplace

1. Navigate to **Dashboard > Marketplace**
2. Click **"Community Marketplace"** tab
3. Browse or search for apps
4. Click **"Install"** on any app with a manifest URL

### Search for Apps

Type in the search bar:
- "bitcoin" - finds Bitcoin Core
- "lightning" - finds Lightning Network
- "payment" - finds BTCPay Server
- etc.

### Install Community Apps

Apps with green "Install" buttons:
- ✅ Have downloadable `.s9pk` packages
- ✅ Can be installed directly

Apps with "Not Available" buttons:
- ⚠️ Don't have packages yet
- 🔗 Can view GitHub repo for more info

## Technical Details

### API Integration

```typescript
// Fetches community packages
const response = await fetch('https://registry.start9.com/api/v1/packages')
const data = await response.json()

// Transforms to our format
communityApps.value = Object.entries(data).map(([id, pkg]) => ({
  id,
  title: pkg.title || id,
  version: latestVersion,
  description: pkg.description,
  icon: pkg.icon,
  author: pkg.author,
  manifestUrl: pkg.manifest,
  repoUrl: pkg.repository
}))
```

### Installation

```typescript
// Installs community app
await rpcClient.call({
  method: 'package.install',
  params: {
    id: app.id,
    url: app.manifestUrl,  // .s9pk URL from registry
    version: app.version
  }
})
```

## App Card Features

Each community app card shows:
- **Icon** - App logo (with fallback to Neode logo)
- **Title** - App name
- **Version** - Latest available version
- **Author** - Package maintainer
- **Description** - Truncated to 3 lines
- **Install Button** - If manifest available
- **GitHub Link** - Repository access

## States

### Loading
```
🔄 Loading Start9 Community Marketplace...
```

### Error
```
❌ Failed to load marketplace
[Error message]
[Retry Button]
```

### Empty Search
```
No apps found matching "[query]"
```

## Backend Requirements

The mock backend needs to support:

1. **package.install** - Install from `.s9pk` URL
2. **Docker** - Extract and run containers
3. **Networking** - Download from registry URLs

## Future Enhancements

- [ ] **Categories** - Filter by Bitcoin, Storage, Communication, etc.
- [ ] **Ratings** - Show community ratings
- [ ] **Dependencies** - Show required apps
- [ ] **Updates** - Notify when app updates available
- [ ] **Reviews** - User reviews and comments
- [ ] **Screenshots** - App previews
- [ ] **Detailed Views** - Full app pages with more info

## Development

### Test the Feature

1. Start dev server:
   ```bash
   npm start
   ```

2. Navigate to Marketplace

3. Switch to "Community Marketplace" tab

4. Should see apps load (or fallback list)

### Mock Data (Development Fallback)

If registry is unavailable, shows:
- Bitcoin Core v27.0.0
- Core Lightning v24.02.2
- BTCPay Server v1.13.1
- Nextcloud v29.0.0

### Adding More Mock Apps

Edit `loadCommunityMarketplace()` function in `Marketplace.vue`:

```typescript
communityApps.value = [
  // ... existing apps ...
  {
    id: 'fedimint',
    title: 'Fedimint',
    version: '0.3.0',
    description: 'Federated Chaumian e-cash',
    icon: '/assets/img/fedimint.png',
    author: 'Fedimint Developers',
    manifestUrl: 'https://example.com/fedimint.s9pk',
    repoUrl: 'https://github.com/fedimint/fedimint'
  }
]
```

## Troubleshooting

### Registry Not Loading

**Problem**: Community tab shows error

**Solutions**:
1. Check internet connection
2. Verify registry URL is accessible
3. Check browser console for CORS errors
4. Fallback mock data will still show

### Apps Won't Install

**Problem**: Install button doesn't work

**Check**:
1. App has `manifestUrl` (not null)
2. Backend is running
3. Docker is available (for real installs)
4. Check backend logs for errors

### Search Not Working

**Problem**: Search doesn't filter apps

**Check**:
1. Type in search box
2. Should filter in real-time
3. Search is case-insensitive
4. Searches title, description, ID, author

## Benefits

✅ **Real Apps** - Access actual Start9 packages  
✅ **Easy Discovery** - Browse full ecosystem  
✅ **One-Click Install** - Direct installation from registry  
✅ **Stay Updated** - See latest versions  
✅ **Community Driven** - Access community-maintained apps  
✅ **Transparent** - GitHub links for every app  

## Security Note

Apps from the community marketplace are:
- Open source (GitHub repos linked)
- Community maintained
- Same packages used by StartOS
- Verified by signature (in production)

Always review an app's repository before installing!

---

🎉 **You can now browse and install real Start9 community apps directly from Neode!**