psf-bch-api/dev-docs/rest2nostr-poxy-api.plan.md

# REST2NOSTR Proxy API Implementation Plan

## Overview

Build a REST API server in `/app` that proxies Nostr WebSocket protocol to REST endpoints, enabling JavaScript developers to interact with Nostr relays via familiar REST APIs instead of WebSockets.

## Architecture

Follow Clean Architecture pattern with these layers:

- **Entities** (`src/entities/`): Domain models (Event, Subscription, etc.)
- **Use Cases** (`src/use-cases/`): Business logic (PublishEvent, QueryEvents, ManageSubscription)
- **Adapters** (`src/adapters/`): External interfaces (NostrRelay WebSocket client, logger)
- **Controllers** (`src/controllers/rest-api/`): Express.js route handlers

## Directory Structure

```
/app
├── src/
│   ├── entities/
│   │   └── event.js
│   ├── use-cases/
│   │   ├── index.js
│   │   ├── publish-event.js
│   │   ├── query-events.js
│   │   └── manage-subscription.js
│   ├── adapters/
│   │   ├── index.js
│   │   ├── nostr-relay.js
│   │   └── wlogger.js
│   ├── controllers/
│   │   ├── index.js
│   │   └── rest-api/
│   │       ├── index.js
│   │       ├── event/
│   │       │   ├── controller.js
│   │       │   └── index.js
│   │       └── req/
│   │           ├── controller.js
│   │           └── index.js
│   └── config/
│       ├── index.js
│       └── env/
│           ├── common.js
│           ├── development.js
│           └── production.js
├── examples/
│   └── [refactored sandbox examples]
├── bin/
│   └── server.js
├── .env.example
├── .env
├── index.js
├── package.json
└── apidoc.json
```

## Core Endpoints

### POST /event

- Maps to: `["EVENT", <event>]`
- Publish a signed Nostr event to relay
- Body: JSON event object
- Response: `{"accepted": true/false, "message": ""}` (maps to `["OK", ...]`)

### GET /req/:subId

- Maps to: `["REQ", <sub_id>, <filters>]`
- Stateless query - returns events immediately
- Query params: filters (JSON encoded or separate params)
- Response: Array of events

### POST /req/:subId

- Maps to: `["REQ", <sub_id>, <filters>]`
- Establish subscription for Server-Sent Events (SSE)
- Body: filters object
- Response: SSE stream of events

### DELETE /req/:subId

- Maps to: `["CLOSE", <sub_id>]`
- Close an existing subscription
- Response: Confirmation

## Implementation Details

### 1. Package Dependencies

- `express`: REST API framework
- `dotenv`: Environment variable management
- `apidoc`: API documentation generation
- `ws` or `nostr-tools`: WebSocket client for Nostr relays
- `winston`: Logging (following example pattern)

### 2. Adapter Layer (`src/adapters/`)

- **nostr-relay.js**: WebSocket client wrapper
  - Connect to configured relay(s)
  - Send `EVENT`, `REQ`, `CLOSE` messages
  - Handle relay responses (`EVENT`, `OK`, `EOSE`, `CLOSED`, `NOTICE`)
  - Manage connection pooling for multiple relays
- **wlogger.js**: Winston-based logger

### 3. Use Cases (`src/use-cases/`)

- **publish-event.js**: Validate event, send to relay, return OK response
- **query-events.js**: Stateless query - send REQ, collect events until EOSE, return results
- **manage-subscription.js**: Create/close subscriptions, handle SSE streaming

### 4. Controllers (`src/controllers/rest-api/`)

- **event/controller.js**: Handle POST /event
- **req/controller.js**: Handle GET/POST/DELETE /req/:subId
- Express middleware for validation, error handling
- SSE support for subscription endpoint

### 5. Configuration (`src/config/`)

- Environment-based config (development, production, test)
- Default relay URL(s) from environment variables
- Port, logging level, etc.

### 6. Subscription Management

- Store active subscriptions in memory (Map with subId as key)
- Map subscription IDs to WebSocket connections
- Handle cleanup on DELETE /req/:subId
- Support SSE streaming for POST /req/:subId

### 7. Examples (`examples/`)

Refactor sandbox examples to use REST API:

- `01-create-account/` - Use REST API to publish kind 0 event
- `02-read-posts/` - Use GET /req/:subId for stateless query
- `03-write-post/` - Use POST /event
- `04-read-alice-posts/` - Use GET /req/:subId with author filter
- `14-get-follow-list/` - Use GET /req/:subId with kind 3 filter
- Additional examples as needed

### 8. API Documentation

- Use api-doc annotations in controller files
- Generate docs with `npm run docs`
- Follow pattern from clean-architecture example

## Environment Variables

- `NOSTR_RELAY_URL`: Default relay WebSocket URL (e.g., `wss://nostr-relay.psfoundation.info`)
- `PORT`: Server port (default: 3000)
- `NODE_ENV`: Environment (development, production, test)
- `LOG_LEVEL`: Logging level (info, debug, error)

## Key Implementation Notes

- WebSocket connections: Maintain persistent connections to relay(s) in adapter
- Error handling: Map Nostr relay errors to appropriate HTTP status codes
- Validation: Validate Nostr events before forwarding (event structure, signature)
- SSE: Use Express response.write() for Server-Sent Events in subscription endpoint
- Stateless queries: For GET /req/:subId, collect events until EOSE, then close subscription automatically