Permacast RSS Importer

A CLI tool to import podcasts from RSS feeds into Permacast with proper string encoding handling.

What's New in 1.2.0

• Added --test flag to use test contract (0x2D5e5504C11f39a044b198cEe1336aF1B49F7107)
• Allows testing podcast imports without affecting production contract
• Maintains all existing functionality with test environment support

Previous Release (1.1.0)

• Improved UTF-8 string encoding handling
• Better validation of string lengths using byte-level checks
• Automatic truncation of oversized strings while preserving UTF-8 encoding
• Default category handling to prevent empty categories
• Enhanced logging of string lengths and encoding issues

Installation

npm install -g permacast-rss-importer

Usage

permacast-import -k <privateKey> -u <rssFeedUrl> [options]

Required Arguments

• -k, --key <privateKey>: Private key for the wallet
• -u, --url <rssFeedUrl>: URL of the RSS feed

Options

• -e, --episodes <mode>: Import mode: all or new (default: all)
• -l, --limit <number>: Limit the number of episodes to import
• -f, --force: Force import even if a hidden podcast exists
• -n, --network <url>: Network RPC URL (default: https://alphanet.load.network)
• -r, --retries <number>: Maximum number of retry attempts (default: 3)
• -t, --test: Use test contract (0x2D5e5504C11f39a044b198cEe1336aF1B49F7107)
• -i, --interactive: Enable interactive mode for fixing metadata issues
• --no-validate: Skip media file validation
• --no-config: Do not load or save config file

Features

Interactive Mode

When running with the -i or --interactive flag, the importer will:

1. Validate all podcast metadata fields (title, author, description, etc.)
2. If any fields are missing or invalid, prompt you to provide valid values
3. Show current values and allow you to edit them
4. Provide smart defaults based on available information

This is particularly useful when:

• RSS feed metadata is incomplete or invalid
• You want to customize metadata before import
• You need to fix validation issues without restarting the import

Without interactive mode, the importer will use smart defaults for any invalid fields.

Metadata Validation

The following fields are validated with UTF-8 byte-level checks:

• Title (required, max 100 bytes)
• Author (required, max 100 bytes)
• Description (required, max 10000 bytes)
• Language (required, max 5 bytes)
• Email (required, max 320 bytes, valid email format)
• Categories (optional, max 500 bytes total, defaults to ["podcast"] if empty)

The importer now validates string lengths at the byte level to ensure compatibility with blockchain storage. This means:

• All strings are checked for their UTF-8 encoded length
• Special characters and emojis are properly handled
• Strings are automatically truncated if they exceed byte limits
• Truncation preserves UTF-8 encoding to prevent corruption

Episode Import Modes

• all: Import all episodes (default)
• new: Only import episodes that don't exist in the podcast

Configuration

The importer can save progress and settings in a config file. This helps with:

• Resuming interrupted imports
• Tracking which episodes have been imported
• Maintaining consistent settings across imports

Disable with --no-config if you don't want to use this feature.

Examples

Import a podcast in interactive mode:

permacast-import -k 0x123... -u https://example.com/feed.xml -i

Import to test contract:

permacast-import -k 0x123... -u https://example.com/feed.xml -t

Import only new episodes:

permacast-import -k 0x123... -u https://example.com/feed.xml -e new

Import first 10 episodes only:

permacast-import -k 0x123... -u https://example.com/feed.xml -l 10

Error Handling

The importer provides detailed error messages and validation feedback. In interactive mode, you'll be guided through fixing any issues. Without interactive mode, smart defaults will be used where possible.

Common error scenarios:

• Invalid RSS feed format
• Missing or invalid metadata fields
• Network connectivity issues
• Contract interaction failures

Development

# Install dependencies
npm install

# Run tests
npm test

# Start development
npm start

License

MIT