npm package: @fliidotdev/component-registry
Description: Component specifications and standards for FLII.dev marketplace
Author: fliidotdev
Latest version: 0.1.0

```text
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   ██████╗ ██████╗ ███╗   ███╗██████╗  ██████╗ ███╗   ██╗███████╗███╗   ██╗████████╗
║  ██╔════╝██╔═══██╗████╗ ████║██╔══██╗██╔═══██╗████╗  ██║██╔════╝████╗  ██║╚══██╔══╝
║  ██║     ██║   ██║██╔████╔██║██████╔╝██║   ██║██╔██╗ ██║█████╗  ██╔██╗ ██║   ██║   
║  ██║     ██║   ██║██║╚██╔╝██║██╔═══╝ ██║   ██║██║╚██╗██║██╔══╝  ██║╚██╗██║   ██║   
║  ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║     ╚██████╔╝██║ ╚████║███████╗██║ ╚████║   ██║   
║   ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝      ╚═════╝ ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═══╝   ╚═╝   
║                                                                              ║
║                             ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗   ██╗
║                             ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝
║                             ██████╔╝█████╗  ██║  ███╗██║███████╗   ██║   ██████╔╝ ╚████╔╝ 
║                             ██╔══██╗██╔══╝  ██║   ██║██║╚════██║   ██║   ██╔══██╗  ╚██╔╝  
║                             ██║  ██║███████╗╚██████╔╝██║███████║   ██║   ██║  ██║   ██║   
║                             ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   
║                                                                              ║
║                         Solana Blinks Component Registry API                ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](https://github.com/fliidotdev/component-registry/actions)
[![API Status](https://img.shields.io/badge/API-online-brightgreen?style=flat-square)](https://api.flii.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/fliidotdev/component-registry/blob/main/LICENSE)

---

## Overview

**Component Registry** is a centralized API service for managing and discovering Solana Blinks components. It provides a RESTful API for storing, retrieving, and searching reusable Blinks components, enabling developers to share and discover pre-built blockchain interactions.

### Key Features

- **Component Storage**: Store and version Blinks components with metadata
- **Discovery API**: Search and filter components by category, tags, and capabilities
- **Version Management**: Semantic versioning support for component updates
- **Authentication**: JWT-based authentication for component publishers
- **Rate Limiting**: Built-in rate limiting for API protection
- **Caching**: Redis-based caching for high performance
- **Analytics**: Track component usage and popularity
- **Validation**: Schema validation for component definitions

## Installation

### Prerequisites

- Node.js 18+
- PostgreSQL 14+
- Redis 7+
- npm or yarn

### Setup

```bash
# Clone repository
git clone https://github.com/fliidotdev/component-registry.git
cd component-registry

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
npm run migrate

# Seed database (optional)
npm run seed

# Start development server
npm run dev
```

## API Documentation

### Base URL

```
Production: https://api.flii.dev
Development: http://localhost:3000
```

### Authentication

```http
POST /api/auth/register
POST /api/auth/login
POST /api/auth/refresh
```

### Components Endpoints

#### List Components

```http
GET /api/components

Query Parameters:
- page: number (default: 1)
- limit: number (default: 20, max: 100)
- category: string
- tags: string[] (comma-separated)
- search: string
- sort: 'popular' | 'recent' | 'name'
```

**Response:**

```json
{
  "data": [
    {
      "id": "uuid",
      "name": "Transfer SOL Button",
      "description": "A button component for SOL transfers",
      "category": "payment",
      "tags": ["transfer", "sol", "payment"],
      "version": "1.0.0",
      "author": {
        "id": "uuid",
        "name": "Developer Name"
      },
      "downloads": 1234,
      "rating": 4.5,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}
```

#### Get Component

```http
GET /api/components/:id
```

**Response:**

```json
{
  "id": "uuid",
  "name": "Transfer SOL Button",
  "description": "A button component for SOL transfers",
  "category": "payment",
  "tags": ["transfer", "sol", "payment"],
  "version": "1.0.0",
  "schema": {
    "type": "button",
    "action": "transfer",
    "params": {
      "recipient": {
        "type": "string",
        "required": true,
        "description": "Recipient wallet address"
      },
      "amount": {
        "type": "number",
        "required": true,
        "description": "Amount in SOL"
      }
    }
  },
  "code": {
    "typescript": "...",
    "javascript": "..."
  },
  "documentation": "...",
  "examples": [...],
  "dependencies": {
    "@solana/web3.js": "^1.87.0"
  },
  "author": {
    "id": "uuid",
    "name": "Developer Name",
    "avatar": "https://..."
  },
  "stats": {
    "downloads": 1234,
    "stars": 567,
    "forks": 89
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

#### Create Component

```http
POST /api/components
Authorization: Bearer <token>

{
  "name": "Component Name",
  "description": "Component description",
  "category": "payment",
  "tags": ["tag1", "tag2"],
  "version": "1.0.0",
  "schema": {...},
  "code": {...},
  "documentation": "...",
  "examples": [...],
  "dependencies": {...}
}
```

#### Update Component

```http
PUT /api/components/:id
Authorization: Bearer <token>

{
  "description": "Updated description",
  "version": "1.0.1",
  ...
}
```

#### Delete Component

```http
DELETE /api/components/:id
Authorization: Bearer <token>
```

### Search Endpoints

#### Search Components

```http
GET /api/search

Query Parameters:
- q: string (search query)
- filters: object (JSON string)
- page: number
- limit: number
```

#### Get Categories

```http
GET /api/categories
```

**Response:**

```json
[
  {
    "id": "payment",
    "name": "Payment",
    "description": "Payment and transfer components",
    "count": 45
  },
  {
    "id": "defi",
    "name": "DeFi",
    "description": "Decentralized finance components",
    "count": 78
  }
]
```

#### Get Popular Tags

```http
GET /api/tags
```

### User Endpoints

#### Get User Profile

```http
GET /api/users/:id
```

#### Get User Components

```http
GET /api/users/:id/components
```

#### Update Profile

```http
PUT /api/users/profile
Authorization: Bearer <token>
```

### Analytics Endpoints

#### Track Download

```http
POST /api/analytics/download
{
  "component_id": "uuid"
}
```

#### Get Component Stats

```http
GET /api/analytics/components/:id
```

## Database Schema

### Components Table

```sql
CREATE TABLE components (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  category VARCHAR(100),
  tags TEXT[],
  version VARCHAR(50),
  schema JSONB,
  code JSONB,
  documentation TEXT,
  examples JSONB,
  dependencies JSONB,
  author_id UUID REFERENCES users(id),
  downloads INTEGER DEFAULT 0,
  stars INTEGER DEFAULT 0,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);
```

### Users Table

```sql
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  username VARCHAR(100) UNIQUE NOT NULL,
  password_hash VARCHAR(255),
  avatar_url VARCHAR(500),
  bio TEXT,
  github_username VARCHAR(100),
  twitter_username VARCHAR(100),
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);
```

## Configuration

### Environment Variables

```env
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/component_registry

# Redis
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

# API
PORT=3000
NODE_ENV=production

# Rate Limiting
RATE_LIMIT_WINDOW=15m
RATE_LIMIT_MAX=100

# Storage
AWS_S3_BUCKET=component-registry
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx

# Monitoring
SENTRY_DSN=https://...
```

## Deployment

### Docker

```bash
# Build image
docker build -t component-registry .

# Run container
docker run -p 3000:3000 --env-file .env component-registry
```

### Docker Compose

```yaml
version: '3.8'
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/registry
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
  
  db:
    image: postgres:14
    environment:
      - POSTGRES_DB=registry
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis:
    image: redis:7
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:
```

### Production Deployment

```bash
# Install PM2
npm install -g pm2

# Start application
pm2 start ecosystem.config.js

# Setup nginx reverse proxy
sudo nano /etc/nginx/sites-available/api.flii.dev
```

## Testing

```bash
# Run all tests
npm test

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Coverage report
npm run test:coverage
```

## Monitoring

### Health Check

```http
GET /health
```

### Metrics

```http
GET /metrics
```

## Rate Limiting

Default rate limits:
- Anonymous: 100 requests per 15 minutes
- Authenticated: 1000 requests per 15 minutes
- Component creation: 10 per hour

## Security

- JWT-based authentication
- Input validation and sanitization
- SQL injection prevention via parameterized queries
- XSS protection
- CORS configuration
- Rate limiting
- Request size limits

## Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

### Development

```bash
# Run in development mode
npm run dev

# Run linter
npm run lint

# Format code
npm run format

# Check types
npm run type-check
```

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Links

- [Documentation](https://flii.dev/docs)
- [API Reference](https://flii.dev/docs)
- [Status Page](https://status.flii.dev)
- [GitHub](https://github.com/fliidotdev)

---

Built by the FLII.dev team