Nostr Post Scheduler & Private Message API

A Node.js API for scheduling Nostr posts and sending private messages using the Nostr protocol.

Features

• Schedule public Nostr posts (kind: 1) at a future time
• Reschedule or cancel scheduled posts
• Send encrypted private messages (kind: 4)
• Auto-managing the database, including table creation and indexing
• Efficient background job processing to send scheduled posts just-in-time
• API key authentication for secure access
• Swagger UI documentation available at /docs for easy API exploration

Technology Stack

• Programming Language: JavaScript (Node.js)
• Framework: Express.js
• Database: SQLite (default) or PostgreSQL/MySQL (via .env configuration)
• Queue System: Background tasks with node-cron
• Security: API key authentication, proper key handling, and rate limiting
• Documentation: Swagger UI (/docs) and Redoc (/redoc)
• Nostr Libraries: Nostr-NDK and nostr-tools

Getting Started

Prerequisites

• Node.js (v14 or higher)
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/yourusername/nostr-scheduler-api.git
cd nostr-scheduler-api

2. Install dependencies:

npm install

3. Create a .env file based on the .env.example:

cp .env.example .env

4. Edit the .env file with your configuration:

cp .env.example .env

5. Start the server:

npm start

For development with auto-reload:

npm run dev

API Documentation

Once the server is running, you can access the API documentation at:

• Swagger UI: http://localhost:3000/docs

API Endpoints

Schedule a Nostr Post

• Method: POST /schedule/post
• Description: Schedules a new Nostr post at a future time.
• Request Parameters:
  • content: Content of the Nostr post
  • Either timestamp (Unix format) or both date (DD/MM/YY or DD/MM/YYYY) and hour (HH:MM or HHMM)
  • Optional relays (otherwise defaults from .env)

Reschedule a Nostr Post

• Method: PATCH /schedule/post/{post_id}
• Description: Updates the scheduled time of an existing post.
• Request Parameters:
  • post_id: ID of the post to reschedule
  • Either new timestamp or new date + hour

Retrieve a Scheduled Post

• Method: GET /schedule/post/{post_id}
• Description: Returns details of a scheduled post.

Delete a Scheduled Post

• Method: DELETE /schedule/post/{post_id}
• Description: Cancels a scheduled post before it is sent.

List All Scheduled Posts

• Method: GET /schedule/posts
• Description: Returns all pending scheduled posts.

Send a Private Message

• Method: POST /messages/send
• Description: Immediately sends an encrypted private message.
• Request Parameters:
  • recipient_pubkey: Public key of the recipient
  • content: Message content
  • Optional relays (otherwise defaults from .env)

Retrieve Sent Messages

• Method: GET /messages/sent
• Description: Returns a history of sent private messages.

Webhook for External Triggers

• Method: POST /webhook/trigger
• Description: Allows an external service to trigger a scheduled post immediately.
• Request Parameters:
  • post_id: ID of the post to send immediately

Authentication & Security

All API requests require an Admin API Key in the request headers:

• Header: Authorization: Bearer <ADMIN_API_KEY>
• If missing or incorrect, the API returns 401 Unauthorized.

Private Key Handling:

• The private key (in nsec or hex format) is stored in .env and never in the database.
• It is only loaded when necessary for signing events.

Rate Limiting:

• Prevents spam and excessive API usage.
• Limited to X requests per minute (configurable).

Database Schema

Table: scheduled_posts

Column	Type	Description
id	INTEGER	Unique ID of the scheduled post (PK)
content	TEXT	The content of the scheduled note
timestamp	INTEGER	Auto-saved Unix timestamp
date	TEXT	Human-readable date (YYYY-MM-DD)
hour	TEXT	Human-readable time (HH:MM)
relays	TEXT	Comma-separated list of relays
status	TEXT	"pending", "sent", or "failed"
created_at	INTEGER	Creation timestamp
updated_at	INTEGER	Last update timestamp

Table: sent_messages

Column	Type	Description
id	INTEGER	Unique ID of the message (PK)
recipient_pubkey	TEXT	The recipient's public key
message	TEXT	The message content
timestamp	INTEGER	Unix timestamp of when it was sent
relays	TEXT	Comma-separated list of relays
event_id	TEXT	Event ID of the sent message
created_at	INTEGER	Creation timestamp

License

This project is licensed under the MIT License - see the LICENSE file for details.