reeln-plugin-meta 0.4.0__tar.gz

reeln_plugin_meta-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv
+        run: uv venv --python ${{ matrix.python-version }}
+
+      - name: Install reeln-cli
+        run: uv pip install "git+https://github.com/StreamnDad/reeln-cli"
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy reeln_meta_plugin/
+
+      - name: Test
+        run: uv run python -m pytest tests/ -n auto --cov=reeln_meta_plugin --cov-branch --cov-fail-under=100 -q

reeln_plugin_meta-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Create venv
+        run: uv venv --python 3.11
+
+      - name: Install reeln-cli
+        run: uv pip install "git+https://github.com/StreamnDad/reeln-cli"
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy reeln_meta_plugin/
+
+      - name: Test
+        run: uv run python -m pytest tests/ -n auto --cov=reeln_meta_plugin --cov-branch --cov-fail-under=100 -q
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

reeln_plugin_meta-0.4.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+venv/
+*.whl
+
+# Testing / Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+.tox/
+
+# Media — prevent accidental video commits
+*.mkv
+*.mp4
+*.mov
+*.avi
+*.webm
+*.ts
+
+# Project artifacts
+secrets/
+output/
+.tmp/
+
+# AI dev docs — dev-only, not tracked
+CLAUDE.md
+AGENTS.md
+.claude/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*

reeln_plugin_meta-0.4.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.4.0] - 2026-03-09
+
+### Added
+
+- `graph_api.py` module — shared HTTP helpers (`http_post`, `format_meta_error`, `GraphAPIError`)
+- Cached authentication via `_ensure_auth()` — token read once per game session
+- `ON_GAME_FINISH` hook handler — resets cached auth and game info between sessions
+- `dry_run` config field (default `false`) — logs API calls without executing them
+
+### Changed
+
+- `livestream.py` now delegates HTTP to `graph_api.py`; `LivestreamError` subclasses `GraphAPIError`
+- Plugin registers both `ON_GAME_INIT` and `ON_GAME_FINISH` hooks
+
+## [0.3.0] - 2026-03-05
+
+### Added
+
+- Feature flag system: each capability gated behind a boolean config field (default `false`)
+- `create_livestream` feature flag for Facebook Live Video creation
+
+## [0.2.0] - 2026-03-05
+
+### Added
+
+- Facebook Live Video settings: `status`, `privacy`, `content_category`, `game_id`,
+  `save_vod`, `published`, `stop_on_delete_stream`
+- All settings configurable via plugin config and overridable via named profiles
+
+## [0.1.0] - 2026-03-04
+
+### Added
+
+- Initial plugin scaffolding with `MetaPlugin` class
+- Token-based auth module (`auth.py`) with file-based Page Access Token
+- Facebook Live Video creation (`livestream.py`) via Graph API
+- `ON_GAME_INIT` hook handler — creates Facebook Live Video, writes URL to shared context
+- Plugin config schema with `page_access_token_file`, `page_id`, `graph_api_version` fields
+- 100% line + branch test coverage

reeln_plugin_meta-0.4.0/Makefile

@@ -0,0 +1,26 @@
+PLUGIN_PKG := reeln_meta_plugin
+
+.PHONY: dev-install reeln-install test lint format check
+
+VENV := .venv/bin
+
+dev-install:
+	uv venv --clear
+	uv pip install -e ../reeln-cli
+	uv pip install -e ".[dev]"
+
+reeln-install:
+	uv pip install --python ../reeln-cli/.venv/bin/python -e .
+
+test:
+	$(VENV)/python -m pytest tests/ -n auto --cov=$(PLUGIN_PKG) --cov-branch --cov-fail-under=100 -q
+
+lint:
+	$(VENV)/ruff check .
+
+format:
+	$(VENV)/ruff format .
+
+check: lint
+	$(VENV)/mypy $(PLUGIN_PKG)/
+	$(MAKE) test

reeln_plugin_meta-0.4.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: reeln-plugin-meta
+Version: 0.4.0
+Summary: reeln-cli plugin for Meta platform integration (Facebook Live, Instagram, Threads)
+Project-URL: Homepage, https://streamn.dad
+Project-URL: Repository, https://github.com/StreamnDad/reeln-plugin-meta
+Project-URL: Changelog, https://github.com/StreamnDad/reeln-plugin-meta/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/StreamnDad/reeln-plugin-meta/issues
+License-Expression: AGPL-3.0-only
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# reeln-plugin-meta
+
+A [reeln-cli](https://github.com/StreamnDad/reeln-cli) plugin for Meta platform integration (Facebook Live, Instagram, Threads).
+
+## Install
+
+```bash
+pip install reeln-plugin-meta
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/StreamnDad/reeln-plugin-meta
+cd reeln-plugin-meta
+make dev-install
+```
+
+## Features
+
+- **Facebook Live Video** — creates a live video on your Facebook Page during `ON_GAME_INIT`
+- Writes the livestream embed URL to `context.shared["livestreams"]["meta"]`
+- All features are opt-in via boolean feature flags (default `false`)
+
+## Facebook Developer Setup
+
+### 1. Create a Facebook Developer Account
+
+Go to [developers.facebook.com](https://developers.facebook.com/) and register as a developer.
+
+### 2. Create an App
+
+1. Go to **My Apps** → **Create App**
+2. Select a use case (e.g. **Other** → **Business**)
+3. Choose **Business** app type
+4. Fill in app name, contact email, and select a Business portfolio
+5. Click **Create App**
+
+### 3. Get a Page Access Token
+
+1. Go to the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
+2. Select your app from the **Meta App** dropdown
+3. Click **Generate Access Token**
+4. Grant the following permissions:
+   - `pages_show_list`
+   - `pages_manage_posts`
+   - `pages_read_engagement`
+   - `publish_video`
+5. Select your Page from the **User or Page** dropdown
+6. Copy the **Page Access Token**
+
+> **Note:** The default token expires in ~1 hour. For a long-lived token
+> (60 days), exchange it via the
+> [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/)
+> or the token exchange endpoint:
+> ```
+> GET /oauth/access_token?grant_type=fb_exchange_token
+>   &client_id=APP_ID&client_secret=APP_SECRET
+>   &fb_exchange_token=SHORT_LIVED_TOKEN
+> ```
+
+### 4. Save the Token to a File
+
+```bash
+mkdir -p secrets
+echo "YOUR_PAGE_ACCESS_TOKEN" > secrets/meta_page_token.txt
+```
+
+### 5. Get Your Page ID
+
+Find your Page ID in **Page Settings → About → Page ID**, or query it via the API:
+
+```bash
+curl "https://graph.facebook.com/v24.0/me?access_token=YOUR_TOKEN"
+```
+
+### 6. Configure the Plugin
+
+```bash
+reeln config set meta.page_access_token_file ./secrets/meta_page_token.txt
+reeln config set meta.page_id YOUR_PAGE_ID
+reeln config set meta.create_livestream true
+```
+
+Or edit your reeln config JSON directly:
+
+```json
+{
+  "plugins": {
+    "enabled": ["meta"],
+    "settings": {
+      "meta": {
+        "page_access_token_file": "./secrets/meta_page_token.txt",
+        "page_id": "123456789",
+        "create_livestream": true
+      }
+    }
+  }
+}
+```
+
+### 7. App Review
+
+The `publish_video` permission may require App Review for production use.
+During development, you can use the token with your own Pages without review.
+
+## Configuration
+
+### Feature Flags
+
+Each capability is gated behind a boolean flag (default `false`):
+
+| Field | Default | Description |
+|---|---|---|
+| `create_livestream` | `false` | Enable Facebook Live Video creation on `ON_GAME_INIT` |
+| `dry_run` | `false` | Log API calls without executing them |
+
+### Required Settings
+
+| Field | Type | Description |
+|---|---|---|
+| `page_access_token_file` | str | Path to Facebook Page access token file |
+| `page_id` | str | Facebook Page ID |
+
+### Livestream Settings
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `graph_api_version` | str | `v24.0` | Graph API version |
+| `status` | str | `LIVE_NOW` | Broadcast status (`LIVE_NOW` or `UNPUBLISHED`) |
+| `privacy` | str | `EVERYONE` | Privacy setting (`EVERYONE` or `SELF`) |
+| `content_category` | str | `SPORTS` | Content category (`SPORTS`, `VIDEO_GAMING`, etc.) |
+| `game_id` | str | `""` | Facebook game ID to tag the broadcast with |
+| `save_vod` | bool | `true` | Save a VOD recording after broadcast ends |
+| `published` | bool | `true` | Publish VOD to Page timeline after broadcast ends |
+| `stop_on_delete_stream` | bool | `false` | Auto-end broadcast when RTMP stream disconnects |
+
+All settings can be overridden per [named profile](https://reeln-cli.readthedocs.io/en/latest/guide/configuration.html#named-profiles).
+For example, a `config.testing.json` profile could set `"privacy": "SELF"` for test broadcasts
+while your default config stays `"EVERYONE"` for game day.
+
+## Development
+
+```bash
+make dev-install      # uv venv + editable install with dev deps
+make reeln-install    # install into sibling reeln-cli venv
+make test             # pytest with 100% coverage
+make lint             # ruff check
+make format           # ruff format
+make check            # lint + mypy + test
+```
+
+## License
+
+AGPL-3.0-only

reeln_plugin_meta-0.4.0/README.md

@@ -0,0 +1,155 @@
+# reeln-plugin-meta
+
+A [reeln-cli](https://github.com/StreamnDad/reeln-cli) plugin for Meta platform integration (Facebook Live, Instagram, Threads).
+
+## Install
+
+```bash
+pip install reeln-plugin-meta
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/StreamnDad/reeln-plugin-meta
+cd reeln-plugin-meta
+make dev-install
+```
+
+## Features
+
+- **Facebook Live Video** — creates a live video on your Facebook Page during `ON_GAME_INIT`
+- Writes the livestream embed URL to `context.shared["livestreams"]["meta"]`
+- All features are opt-in via boolean feature flags (default `false`)
+
+## Facebook Developer Setup
+
+### 1. Create a Facebook Developer Account
+
+Go to [developers.facebook.com](https://developers.facebook.com/) and register as a developer.
+
+### 2. Create an App
+
+1. Go to **My Apps** → **Create App**
+2. Select a use case (e.g. **Other** → **Business**)
+3. Choose **Business** app type
+4. Fill in app name, contact email, and select a Business portfolio
+5. Click **Create App**
+
+### 3. Get a Page Access Token
+
+1. Go to the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
+2. Select your app from the **Meta App** dropdown
+3. Click **Generate Access Token**
+4. Grant the following permissions:
+   - `pages_show_list`
+   - `pages_manage_posts`
+   - `pages_read_engagement`
+   - `publish_video`
+5. Select your Page from the **User or Page** dropdown
+6. Copy the **Page Access Token**
+
+> **Note:** The default token expires in ~1 hour. For a long-lived token
+> (60 days), exchange it via the
+> [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/)
+> or the token exchange endpoint:
+> ```
+> GET /oauth/access_token?grant_type=fb_exchange_token
+>   &client_id=APP_ID&client_secret=APP_SECRET
+>   &fb_exchange_token=SHORT_LIVED_TOKEN
+> ```
+
+### 4. Save the Token to a File
+
+```bash
+mkdir -p secrets
+echo "YOUR_PAGE_ACCESS_TOKEN" > secrets/meta_page_token.txt
+```
+
+### 5. Get Your Page ID
+
+Find your Page ID in **Page Settings → About → Page ID**, or query it via the API:
+
+```bash
+curl "https://graph.facebook.com/v24.0/me?access_token=YOUR_TOKEN"
+```
+
+### 6. Configure the Plugin
+
+```bash
+reeln config set meta.page_access_token_file ./secrets/meta_page_token.txt
+reeln config set meta.page_id YOUR_PAGE_ID
+reeln config set meta.create_livestream true
+```
+
+Or edit your reeln config JSON directly:
+
+```json
+{
+  "plugins": {
+    "enabled": ["meta"],
+    "settings": {
+      "meta": {
+        "page_access_token_file": "./secrets/meta_page_token.txt",
+        "page_id": "123456789",
+        "create_livestream": true
+      }
+    }
+  }
+}
+```
+
+### 7. App Review
+
+The `publish_video` permission may require App Review for production use.
+During development, you can use the token with your own Pages without review.
+
+## Configuration
+
+### Feature Flags
+
+Each capability is gated behind a boolean flag (default `false`):
+
+| Field | Default | Description |
+|---|---|---|
+| `create_livestream` | `false` | Enable Facebook Live Video creation on `ON_GAME_INIT` |
+| `dry_run` | `false` | Log API calls without executing them |
+
+### Required Settings
+
+| Field | Type | Description |
+|---|---|---|
+| `page_access_token_file` | str | Path to Facebook Page access token file |
+| `page_id` | str | Facebook Page ID |
+
+### Livestream Settings
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `graph_api_version` | str | `v24.0` | Graph API version |
+| `status` | str | `LIVE_NOW` | Broadcast status (`LIVE_NOW` or `UNPUBLISHED`) |
+| `privacy` | str | `EVERYONE` | Privacy setting (`EVERYONE` or `SELF`) |
+| `content_category` | str | `SPORTS` | Content category (`SPORTS`, `VIDEO_GAMING`, etc.) |
+| `game_id` | str | `""` | Facebook game ID to tag the broadcast with |
+| `save_vod` | bool | `true` | Save a VOD recording after broadcast ends |
+| `published` | bool | `true` | Publish VOD to Page timeline after broadcast ends |
+| `stop_on_delete_stream` | bool | `false` | Auto-end broadcast when RTMP stream disconnects |
+
+All settings can be overridden per [named profile](https://reeln-cli.readthedocs.io/en/latest/guide/configuration.html#named-profiles).
+For example, a `config.testing.json` profile could set `"privacy": "SELF"` for test broadcasts
+while your default config stays `"EVERYONE"` for game day.
+
+## Development
+
+```bash
+make dev-install      # uv venv + editable install with dev deps
+make reeln-install    # install into sibling reeln-cli venv
+make test             # pytest with 100% coverage
+make lint             # ruff check
+make format           # ruff format
+make check            # lint + mypy + test
+```
+
+## License
+
+AGPL-3.0-only

reeln_plugin_meta-0.4.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reeln-plugin-meta"
+dynamic = ["version"]
+description = "reeln-cli plugin for Meta platform integration (Facebook Live, Instagram, Threads)"
+readme = "README.md"
+license = "AGPL-3.0-only"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Homepage = "https://streamn.dad"
+Repository = "https://github.com/StreamnDad/reeln-plugin-meta"
+Changelog = "https://github.com/StreamnDad/reeln-plugin-meta/blob/main/CHANGELOG.md"
+Issues = "https://github.com/StreamnDad/reeln-plugin-meta/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pytest-xdist",
+    "ruff",
+    "mypy",
+]
+
+[project.entry-points."reeln.plugins"]
+meta = "reeln_meta_plugin:MetaPlugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["reeln_meta_plugin"]
+
+[tool.hatch.version]
+path = "reeln_meta_plugin/__init__.py"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = "reeln.*"
+ignore_missing_imports = true

reeln_plugin_meta-0.4.0/reeln_meta_plugin/__init__.py

@@ -0,0 +1,9 @@
+"""reeln-cli plugin for Meta platform integration (Facebook Live, Instagram, Threads)."""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"
+
+from reeln_meta_plugin.plugin import MetaPlugin
+
+__all__ = ["MetaPlugin", "__version__"]

reeln_plugin_meta-0.4.0/reeln_meta_plugin/auth.py

@@ -0,0 +1,38 @@
+"""Token-based authentication for Meta APIs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from reeln.core.config import data_dir
+
+
+class AuthError(Exception):
+    """Raised when authentication fails."""
+
+
+def default_token_path() -> Path:
+    """Return the default Page Access Token file path."""
+    return Path(data_dir() / "meta" / "page_token.txt")
+
+
+def read_token(path: Path) -> str:
+    """Read and validate a token from a file.
+
+    Args:
+        path: Path to the token file.
+
+    Returns:
+        The token string (stripped of whitespace).
+
+    Raises:
+        AuthError: If the file is missing or empty.
+    """
+    if not path.exists():
+        raise AuthError(f"Token file not found: {path}")
+
+    token = path.read_text().strip()
+    if not token:
+        raise AuthError(f"Token file is empty: {path}")
+
+    return token