Interledger Owncast Monetization Plugin

Go-based Owncast plugin that adds Web Monetization and Open Payments support to Owncast streams, enabling viewers to send tips using their Interledger-enabled wallets.

Features

• 💰 Open Payments Integration – Complete tip/gift flow using Open Payments SDK with grant-based authorization
• 🎨 Gamified Tip Tiers – AI-powered themed tip tiers from the Creator WM Tools core (10 themes including fantasy, sci-fi, gaming, space, etc.)
• 📊 Payment Analytics – Track support events, cumulative totals, and unique supporters with time-windowed aggregation
• 🔐 Session Management – Secure viewer wallet tracking with 30-minute TTL and automatic cleanup
• 🎭 Interactive Widgets – Embeddable tip panel widget with modal-based grant authorization flow
• ⚙️ Admin Configuration UI – Simple interface for wallet setup and plugin configuration
• 💾 BoltDB Persistence – Stores wallet configuration, grants, and session data in embedded database
• 🔗 Webhook Integration – Receives Owncast events (stream lifecycle, chat, viewer activity) for future analytics

Architecture

This plugin is part of a two-component system:

1. Owncast Plugin (Go) – This repository

   • Runs as a standalone HTTP service (port 8085)
   • Manages Open Payments flows (grants, quotes, payments)
   • Stores wallet configuration and grants in BoltDB
   • Serves admin UI and embeddable widgets
   • Receives Owncast webhooks for event tracking

2. Creator WM Tools Core (TypeScript/Fastify) – ../core

   • Provides tip tier generation endpoints
   • Pure domain logic for analytics, leaderboards, and gifter paths
   • Platform-agnostic, storage-free service

Documentation

• OPEN_PAYMENTS.md – Complete Open Payments integration overview including session management, payment creation flow, and API endpoints
• OPEN_PAYMENTS_SDK_INTEGRATION.md – Technical details on correct usage of the Open Payments Go SDK with proper types and methods
• GRANT_CONTINUATION_FLOW.md – Implementation guide for modal-based grant authorization flow including frontend widget and backend continuation endpoint

Quick Overview

The plugin enables viewers to tip creators during Owncast streams:

1. Viewer registers wallet – Browser detects Web Monetization or viewer manually enters wallet address
2. Viewer selects tip tier – Themed tiers (e.g. "Coffee Shot ☕ €1") fetched from Creator WM Tools core
3. Grant authorization – Modal iframe displays wallet authorization page; viewer approves
4. Payment execution – Plugin creates quote and payment using Open Payments SDK
5. Confirmation – Widget shows success message and updates support analytics

High-level architecture

• Owncast plugin (Go)
  • Runs inside Owncast.
  • Uses Owncast plugin APIs for events, DB, and admin UI.
  • Talks to the Creator WM Tools core over HTTP.
• Creator WM Tools core (Node/TS)
  • Provides /tips/suggest and /tips endpoints.
  • Returns themed gamified tip tiers that the plugin uses to power overlays and admin forms.

Project layout (proposed)

• cmd/owncast-wm-plugin/
  • main.go – plugin entrypoint and wiring.
• internal/owncast/
  • events.go – map Owncast events/webhooks → internal event structs.
  • api.go – minimal Owncast HTTP client (send chat messages, etc.).
  • storage.go – helpers to persist plugin config and monetization data in Owncast DB.
• internal/wmcore/
  • models.go – Go models mirroring Creator WM Tools types (e.g. TipTier, TipTierSet).
  • client.go – HTTP client for the core service (tips now, more later).
• internal/monetization/
  • service.go – orchestrates Owncast events + wmcore client + storage.
• internal/analytics/
  • models.go – stored analytics models (support events, timeframes, summaries).
  • service.go – analytics service and in-memory store; production adapters should back this with Owncast DB.
• internal/http/
  • admin_handlers.go – HTTP handlers backing the plugin admin UI.
  • overlay_handlers.go – HTTP handlers returning JSON for overlays (tip tiers, etc.).
• ui/admin/
  • Static assets for the plugin admin page (served inside Owncast admin).
• ui/overlays/
  • HTML/JS overlays embedding widgets like <wm-tip-panel>.
• config/plugin.yml
  • Owncast plugin manifest.

Configuration

The plugin needs to know how to reach the Creator WM Tools core service.

Environment/config values (example):

• WM_CORE_BASE_URL – base URL of the core service, e.g. http://localhost:3000.
• WM_CORE_API_KEY – optional API key for authenticating to the core.

These can be stored in Owncast's configuration storage through the plugin admin UI.

When running this adapter as a standalone service, you will also configure Owncast to talk to it via:

• Webhooks – Owncast sends events to this adapter.
• External API access tokens – this adapter can call Owncast's admin/external APIs if needed.

Core HTTP contract

For tips, the plugin calls:

• GET {WM_CORE_BASE_URL}/tips/suggest?streamId={id}&theme=fun&currency=EUR
• POST {WM_CORE_BASE_URL}/tips

Example POST /tips request body:

{
  "streamId": "stream-123",
  "viewerSegment": "all-viewers",
  "theme": "fun",
  "currency": "EUR",
  "minAmount": 0.5,
  "maxAmount": 100
}

Example response (TipTierSet):

{
  "theme": "fun",
  "currency": "EUR",
  "tiers": [
    {
      "id": "fun-spark",
      "theme": "fun",
      "amount": 0.5,
      "currency": "EUR",
      "emoji": "✨",
      "name": "Spark",
      "perk": "You lit the flame!"
    }
  ]
}

Overlay integration (tip panel)

• Overlays request tiers from the plugin, e.g.:
  • GET /plugins/wm/overlay/tip-tiers?streamId={id}
• Plugin:
  • Reads stream/plugin config from Owncast DB.
  • Calls Creator WM Tools core to obtain TipTierSet.
  • Returns JSON for the frontend overlay, which renders buttons and triggers Open Payments flows per tier.

Development

1. Run the Creator WM Tools core

From the core/ directory:

cd ../core
npm install
npm run dev

This starts the Fastify service on http://localhost:3000 with /tips/suggest and /tips enabled.

2. Build the Owncast plugin binary

From the repository root, change into the Owncast plugin directory and build:

cd owncast-wm-plugin
go build -o owncast-wm-plugin ./cmd/owncast-wm-plugin

This produces a plugin binary named owncast-wm-plugin inside the owncast-wm-plugin/ directory.

3. Install the plugin into an Owncast instance

The exact plugin directory layout can vary; the following is a common pattern for local development. See the Owncast plugin documentation for the latest details.

1. Locate your Owncast install directory, e.g. ~/owncast.
2. Create a plugin folder inside it:

mkdir -p ~/owncast/plugins/interledger-owncast-monetization-plugin

3. Copy the built binary, manifest, and UI assets into that folder (run these from inside owncast-wm-plugin/):

cp owncast-wm-plugin config/plugin.yml \
  ~/owncast/plugins/interledger-owncast-monetization-plugin/

cp -R ui \
  ~/owncast/plugins/interledger-owncast-monetization-plugin/

At this point the Owncast directory should contain something like:

owncast/
  owncast          # Owncast server binary
  config.yaml      # Owncast config
  plugins/
   interledger-owncast-monetization-plugin/
    owncast-wm-plugin
    plugin.yml
    ui/
      admin/
      overlays/

4. Run the plugin stub and access the Monetization admin

The current implementation runs as a standalone HTTP service; it does not yet integrate with Owncast's internal plugin APIs. This is enough to iterate on the admin UI and analytics API.

1. From the owncast-wm-plugin/ directory, start the stub server:

cd owncast-wm-plugin
./owncast-wm-plugin

This listens on http://localhost:8085 by default.

2. Open the Monetization admin UI directly in your browser:

• http://localhost:8085/plugins/wm/admin

3. (Optional) Call the analytics summary endpoint:

• http://localhost:8085/plugins/wm/analytics/summary?streamId=demo&timeframe=last_24h

5. Connect Owncast using webhooks and access tokens

You don't need to modify the Owncast codebase. Instead, use the built‑in webhooks and external API features.

1. Configure a webhook in Owncast

   • In the Owncast admin UI, go to Integrations → Webhooks.

   • Add a new webhook pointing to this adapter, for example:

     http://localhost:8085/webhooks/owncast
     

   • Select the events you want to forward (e.g. stream start/stop, chat messages) so the adapter can observe activity and, later, feed its analytics engine.

   The endpoint /webhooks/owncast is handled by OwncastWebhookHandler and currently logs all incoming payloads along with the X-Owncast-Event header.

2. (Optional) Create an external API access token

   • In Owncast admin, create an External API user/access token with the scopes you need.

   • Expose that token and the Owncast base URL to this adapter via environment variables, for example:

     export OWNCAST_BASE_URL="http://localhost:8080"
     export OWNCAST_ACCESS_TOKEN="<your-token>"

   • Future versions of this adapter can use those values to call back into Owncast (e.g. to send chat messages, query viewer stats, or trigger overlays) using Owncast's documented external APIs.

In a future iteration, this binary should be wired into Owncast's real plugin system so that the Monetization section appears as part of the Owncast admin navigation.

Payment Analytics Engine in the Owncast adapter

• The plugin should record monetization events (Web Monetization receipts, one-time tips/gifts, redemptions) into its own storage via internal/analytics:
  • Use analytics.SupportEventRecord to normalize what gets stored.
  • Call analytics.Service.RecordSupportEvent from your monetization pipeline.
• To serve widgets and dashboards, expose a small REST API from the plugin, for example:
  • GET /plugins/wm/analytics/summary?streamId={id}&timeframe=last_24h
  • GET /plugins/wm/analytics/summary?streamId={id}&timeframe=last_7d
• These endpoints should:
  • Use analytics.Service.GetSummary to compute totals, event counts, and unique supporters.
  • Return analytics.Summary as JSON for use by dashboards, overlays, and leaderboards.

Implementation details (Owncast plugin API integration and concrete database wiring) will be added as the project evolves, but the analytics models and service in internal/analytics define the contract.