enki/nostr-poster
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
nostr-poster/CLAUDE.md

8.4 KiB
Raw Blame History

Development Guide for nostr-poster

Build & Run Commands

  • make build: Build application
  • make run: Build and run application
  • make clean: Clean build artifacts
  • make test: Run all tests (go test -v ./...)
  • make lint: Run golangci-lint
  • make fmt: Format code with goimports
  • make tools: Install development tools

Code Style Guidelines

  • Format: Use goimports (run make fmt before commits)
  • Linting: Run make lint to check code quality
  • Error handling: Return errors with context, log with zap
  • Package names: Short, lowercase, singular nouns
  • Functions: CamelCase (e.g., GetBot, CreateBot)
  • Variables: camelCase (e.g., botService, relayManager)
  • Interfaces: End with "-er" (e.g., Manager, Uploader)
  • Imports: Standard library first, then external packages
  • Testing: Write tests for all public functions

Project Organization

  • /cmd: Application entrypoints
  • /internal: Non-public packages
  • /web: Frontend assets and templates
  • Go version: 1.24.0

Nostr Poster

A self-hosted solution for automated content posting to the Nostr network, supporting multiple bots, scheduled posting, and various media upload protocols.

Overview

Nostr Poster is a web application that allows you to create and manage multiple Nostr bots. Each bot can automatically post content from a local directory to the Nostr network on a schedule. The application supports different types of Nostr events, including standard notes (kind:1), picture posts (kind:20), and video posts (kind:21/22).

Features

  • Multiple Bot Management: Create and manage multiple Nostr bots with separate identities
  • Scheduled Posting: Configure each bot to post content on a regular schedule
  • Media Upload Support: Upload media to various services including NIP-94/96 compatible servers and Blossom servers
  • Global Relay Management: Configure global relays for all your bots following the NIP-65 Outbox Model
  • Manual Posting: Create manual posts in addition to scheduled posts
  • Profile Management: Edit bot profiles and publish them to the Nostr network
  • Content Management: Upload and organize content files for your bots
  • Secure Key Storage: Private keys are encrypted and stored securely

Architecture

Backend Components

  • API: RESTful API built with Go and Gin web framework
  • Database: SQLite database for storing bot configurations and metadata
  • Scheduler: Cron-based scheduler for running automated posting jobs
  • Auth Service: Authentication service using NIP-07 compatible signatures
  • Media Upload: Support for NIP-94/96 and Blossom protocols for media uploading
  • Key Store: Secure storage for bot private keys with encryption

Frontend Components

  • Web UI: Bootstrap-based responsive user interface
  • Authentication: NIP-07 compatible authentication with browser extensions
  • Bot Management: Interface for creating and configuring bots
  • Content Management: Interface for uploading and managing content files
  • Manual Posting: Interface for creating manual posts

NIPs Implemented

The project implements the following Nostr Implementation Possibilities (NIPs):

  • NIP-01: Basic protocol flow, events, and client-relay communication
  • NIP-07: Browser extension integration for authentication
  • NIP-19: Bech32-encoded entities for human-friendly display of IDs
  • NIP-55: Android signer application integration (optional)
  • NIP-65: Relay list metadata for the Outbox Model
  • NIP-68: Picture-first feeds
  • NIP-71: Video events
  • NIP-92: Media attachments
  • NIP-94: File metadata
  • NIP-96: HTTP file storage integration
  • NIP-98: HTTP Auth

Setup

Prerequisites

  • Go 1.19 or higher
  • Web browser with NIP-07 compatible extension (like nos2x or Alby)

Installation

  1. Clone the repository:

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

  2. Configure the application by editing config.yaml:

    app_name: "Nostr Poster"
server_port: 8765
log_level: "info"

bot:
  keys_file: "keys.json"
  content_dir: "./content"
  archive_dir: "./archive"
  default_interval: 60

db:
  path: "./nostr-poster.db"

media:
  default_service: "nip94"
  nip94:
    server_url: "https://files.sovbit.host"
    require_auth: true
  blossom:
    server_url: "https://cdn.sovbit.host/upload"

relays:
  - url: "wss://relay.damus.io"
    read: true
    write: true
  - url: "wss://nostr.mutinywallet.com"
    read: true
    write: true
  - url: "wss://relay.nostr.band"
    read: true
    write: true

  3. Build and run the application:

    go build -o nostr-poster
./nostr-poster

  4. Access the web interface at http://localhost:8765

Authentication

  1. The application uses NIP-07 compatible authentication.
  2. Install a NIP-07 compatible browser extension like nos2x or Alby.
  3. Click "Login with Nostr" on the web interface to authenticate.

Creating a Bot

  1. After logging in, click "Create New Bot" on the dashboard.
  2. Fill in the bot details, including name, display name, and bio.
  3. Choose to generate a new keypair or import an existing NSEC key.
  4. Configure posting interval and hashtags.
  5. Add relay information if needed.
  6. Click "Create Bot" to create the bot.

Uploading Content

  1. Go to the "Content" tab in the navigation.
  2. Select a bot from the dropdown menu.
  3. Click "Load Content" to see the bot's content files.
  4. Use the file upload form to upload new content files.
  5. Files will be automatically posted based on the bot's schedule.

Manual Posting

  1. Go to the "Content" tab in the navigation.
  2. Select a bot from the dropdown menu.
  3. Scroll down to the "Create Manual Post" section.
  4. Choose the post type (standard post or picture post).
  5. Fill in the content and upload any media.
  6. Click "Post Now" to publish the post immediately.

Architecture Details

Database Schema

  • bots: Stores bot information (ID, keys, profile data)
  • post_config: Stores posting configuration for each bot
  • media_config: Stores media upload configuration for each bot
  • relays: Stores relay information for each bot
  • global_relays: Stores global relays for the user
  • posts: Stores information about posts made by bots

Key Storage

  • Private keys are encrypted using NaCl secretbox with a password derived from the application configuration.
  • The encrypted keys are stored in a JSON file specified in the configuration.

Scheduler

  • The scheduler uses a cron-based approach to run posting jobs on the configured intervals.
  • Each bot has its own schedule based on its configuration.

Media Upload

  • The application supports two main media upload protocols:
    • NIP-94/96: For uploading to NIP-96 compatible servers with NIP-94 metadata
    • Blossom: For uploading to Blossom protocol servers (BUD-01, BUD-02)
  • The application handles authentication, compression, and metadata extraction automatically.

Development

Adding a New Feature

  1. Fork the repository
  2. Create a new branch for your feature
  3. Implement your changes
  4. Submit a pull request

Code Structure

.
├── internal
│   ├── api           # API handlers and services
│   ├── auth          # Authentication services
│   ├── config        # Configuration handling
│   ├── crypto        # Cryptographic operations and key storage
│   ├── db            # Database access and schema
│   ├── media         # Media handling (upload, prepare)
│   ├── models        # Data models
│   ├── nostr         # Nostr protocol implementation
│   │   ├── events    # Event creation and signing
│   │   ├── nip65     # Outbox model implementation
│   │   └── relay     # Relay management
│   ├── scheduler     # Scheduled posting
│   └── utils         # Utility functions
├── web               # Web interface
│   ├── assets        # Static assets
│   │   ├── css       # CSS files
│   │   └── js        # JavaScript files
│   └── index.html    # Main HTML file

License

MIT License

Acknowledgements