nself Plugins

Version 0.4.8 | Extend nself with third-party integrations

Plugins extend nself with third-party service integrations, providing database schemas, webhook handlers, CLI commands, and more. The plugin system enables seamless integration with payment processors, e-commerce platforms, DevOps tools, and other services.

Available Plugins

Data Sync Coverage

Stripe Plugin

• Customers, Products, Prices
• Subscriptions, Invoices, Payment Intents
• Payment Methods, Charges, Refunds
• Disputes, Balance Transactions, Payouts
• Coupons, Promotion Codes, Tax Rates
• 70+ webhook events

GitHub Plugin

• Repositories, Issues, Pull Requests
• Commits, Releases, Branches, Tags
• Workflow Runs, Jobs, Deployments
• Check Suites, Check Runs
• Teams, Collaborators, Milestones, Labels
• 20+ webhook events

Shopify Plugin

• Products, Variants, Collections
• Customers, Orders, Order Items
• Inventory, Locations, Fulfillments
• Refunds, Transactions, Draft Orders
• Abandoned Checkouts, Discount Codes
• 25+ webhook events

Quick Start

# List available plugins
nself plugin list

# Install a plugin
nself plugin install stripe

# Configure (add required environment variables to .env)
echo "STRIPE_API_KEY=sk_live_xxx" >> .env

# Initialize database schema
nself plugin stripe init

# Sync data from the service
nself plugin stripe sync

# Start webhook server
nself plugin stripe server

Plugin Commands

# List available plugins
nself plugin list

# List installed plugins
nself plugin list --installed

# Check for updates
nself plugin updates

# Update all plugins
nself plugin update

# Remove a plugin
nself plugin remove <name>

# Remove plugin and delete data
nself plugin remove <name> --delete-data

Plugin-Specific Commands

# Initialize database schema
nself plugin <name> init

# Sync all data
nself plugin <name> sync

# Sync specific resources
nself plugin <name> sync --resources customers,orders

# Incremental sync
nself plugin <name> sync --incremental

# Show sync status
nself plugin <name> status

# Start HTTP server
nself plugin <name> server

# Start on custom port
nself plugin <name> server --port 3001

Plugin Architecture

Each plugin provides:

1. Database Schema

Tables for storing synced data:

• Prefixed tables (e.g., stripe_customers, github_repos)
• Migration support for schema updates
• Automatic Hasura tracking

2. Webhook Handlers

Real-time event processing:

• Signature verification
• Event routing
• Error handling and retry
• Event logging

3. CLI Actions

Commands for data management:

• Sync commands
• List and search
• Show details
• Webhook management

4. Analytics Views

Pre-built SQL views for insights:

• Revenue reports
• Activity summaries
• Performance metrics

5. Service Containers

Docker services for plugins:

• Webhook handlers
• Background workers
• API proxies

6. Nginx Routes

URL routing configuration:

• Webhook endpoints
• API proxies
• Custom routes

Environment Variables

Each plugin requires specific environment variables. These should be added to your .env file.

Default Ports

Webhook Configuration

Endpoint Pattern

Plugins use standardized webhook endpoints:

https://your-domain.com/webhooks/<plugin-name>

Examples:

• Stripe: https://example.com/webhooks/stripe
• GitHub: https://example.com/webhooks/github
• Shopify: https://example.com/webhooks/shopify

Webhook Security

Always configure webhook secrets for signature verification:

STRIPE_WEBHOOK_SECRET=whsec_xxxxx
GITHUB_WEBHOOK_SECRET=xxx
SHOPIFY_WEBHOOK_SECRET=xxx

Local Development

For local development, use tunneling:

# Stripe CLI
stripe listen --forward-to localhost/webhooks/stripe

# ngrok
ngrok http 443

Database Integration

Table Prefixes

Each plugin creates prefixed tables:

Viewing Tables

# List plugin tables
nself db tables | grep stripe_
nself db tables | grep github_
nself db tables | grep shopify_

# Query plugin data
nself db query "SELECT COUNT(*) FROM stripe_customers"

Hasura Integration

Plugin tables are automatically:

• Tracked in Hasura
• Configured with relationships
• Available via GraphQL

query {
  stripe_customers(limit: 10) {
    id
    email
    stripe_subscriptions {
      status
      current_period_end
    }
  }
}

Plugin Registry

Architecture

nself uses a two-tier registry system:

Primary: plugins.nself.org

• Cloudflare Worker-based API
• KV storage for caching
• Sub-second response times
• Global edge distribution

Fallback: GitHub

• Raw file access from nself-plugins repo
• Used when primary is unavailable
• Stale cache as last resort

Registry Endpoints

https://plugins.nself.org/registry.json     # Full registry
https://plugins.nself.org/plugins/:name     # Plugin info
https://plugins.nself.org/plugins/:name/:v  # Specific version
https://plugins.nself.org/health            # Health check
https://plugins.nself.org/categories        # Category list

Update Management

Checking for Updates

# Check for plugin updates
nself plugin updates

# JSON output
nself plugin updates --json

Updating Plugins

# Update specific plugin
nself plugin update stripe

# Update all plugins
nself plugin update --all

# Dry run (see what would update)
nself plugin update --dry-run

After Updating

# Rebuild configuration
nself build

# Restart services
nself start

Plugin Categories

Planned Plugins

High Priority

Medium Priority

Next Steps

Ready to use plugins? Start here:

• Plugin Installation - How to install and manage plugins
• Stripe Plugin - Payment processing integration
• GitHub Plugin - Repository and issue sync
• Shopify Plugin - E-commerce integration
• Creating Plugins - Build your own custom plugins

Last Updated: January 2026 | Version 0.4.8