step 10 complete: plugin marketplace with catalog, review workflow, and revenue split
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
7
app/marketplace/__init__.py
Normal file
7
app/marketplace/__init__.py
Normal file
@@ -0,0 +1,7 @@
|
||||
"""Plugin marketplace package.
|
||||
|
||||
Three service classes introduced in Step 10:
|
||||
- ``PluginRegistry`` — catalog, submit/approve/reject, install counts
|
||||
- ``ReviewQueue`` — approval workflow + security checklist
|
||||
- ``RevenueShare`` — 70/30 split tracking and Stripe Connect payouts
|
||||
"""
|
||||
211
app/marketplace/plugin_registry.py
Normal file
211
app/marketplace/plugin_registry.py
Normal file
@@ -0,0 +1,211 @@
|
||||
"""Plugin catalog registry.
|
||||
|
||||
Maintains the authoritative list of plugins, their review status, and
|
||||
aggregate install counts. Storage is in-memory until Step 12 migrates to
|
||||
the ``plugins`` PostgreSQL table.
|
||||
|
||||
Module-level singleton::
|
||||
|
||||
from app.marketplace.plugin_registry import registry
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import time
|
||||
import uuid
|
||||
from typing import Any, Literal
|
||||
|
||||
from app.schemas import PluginListResponse, PluginManifest
|
||||
|
||||
# ── Pre-seeded approved plugins (mirrors the Step 8 stub catalog) ─────
|
||||
|
||||
_SEED_PLUGINS: list[dict[str, Any]] = [
|
||||
{
|
||||
"manifest": PluginManifest(
|
||||
id="plugin-github-sync",
|
||||
name="GitHub Sync",
|
||||
description="Sync tasks with GitHub Issues and pull requests.",
|
||||
version="1.0.0",
|
||||
author="Adiuva",
|
||||
permissions=["read:tasks", "write:tasks"],
|
||||
category="productivity",
|
||||
price_cents=0,
|
||||
),
|
||||
"status": "approved",
|
||||
"s3_package_key": "plugins/plugin-github-sync/1.0.0/package.zip",
|
||||
"install_count": 0,
|
||||
"avg_rating": 0.0,
|
||||
"rejection_reason": None,
|
||||
"submitted_at": int(time.time()),
|
||||
},
|
||||
{
|
||||
"manifest": PluginManifest(
|
||||
id="plugin-slack-notify",
|
||||
name="Slack Notifier",
|
||||
description="Post task and checkpoint updates to Slack channels.",
|
||||
version="1.2.0",
|
||||
author="Adiuva",
|
||||
permissions=["read:tasks", "read:checkpoints"],
|
||||
category="communication",
|
||||
price_cents=499,
|
||||
),
|
||||
"status": "approved",
|
||||
"s3_package_key": "plugins/plugin-slack-notify/1.2.0/package.zip",
|
||||
"install_count": 0,
|
||||
"avg_rating": 0.0,
|
||||
"rejection_reason": None,
|
||||
"submitted_at": int(time.time()),
|
||||
},
|
||||
{
|
||||
"manifest": PluginManifest(
|
||||
id="plugin-time-tracker",
|
||||
name="Time Tracker",
|
||||
description="Track time spent on tasks with automatic reporting.",
|
||||
version="0.9.1",
|
||||
author="Third Party",
|
||||
permissions=["read:tasks", "write:tasks"],
|
||||
category="productivity",
|
||||
price_cents=999,
|
||||
),
|
||||
"status": "approved",
|
||||
"s3_package_key": "plugins/plugin-time-tracker/0.9.1/package.zip",
|
||||
"install_count": 0,
|
||||
"avg_rating": 0.0,
|
||||
"rejection_reason": None,
|
||||
"submitted_at": int(time.time()),
|
||||
},
|
||||
]
|
||||
|
||||
_PAGE_SIZE = 20
|
||||
|
||||
|
||||
class PluginRegistry:
|
||||
"""In-process plugin catalog.
|
||||
|
||||
All mutating methods are ``async`` to make the future DB swap transparent
|
||||
to callers.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
# plugin_id → entry dict (deep-copied so each instance is independent)
|
||||
self._catalog: dict[str, dict[str, Any]] = {
|
||||
e["manifest"].id: copy.deepcopy(e) for e in _SEED_PLUGINS
|
||||
}
|
||||
|
||||
# ── Queries ──────────────────────────────────────────────────────
|
||||
|
||||
async def list_plugins(
|
||||
self,
|
||||
category: str | None = None,
|
||||
query: str | None = None,
|
||||
page: int = 1,
|
||||
sort: Literal["rating", "installs", "newest"] = "newest",
|
||||
) -> PluginListResponse:
|
||||
"""Return a page of approved plugins, optionally filtered and sorted."""
|
||||
entries = [e for e in self._catalog.values() if e["status"] == "approved"]
|
||||
|
||||
if category:
|
||||
entries = [e for e in entries if e["manifest"].category == category]
|
||||
|
||||
if query:
|
||||
q_lower = query.lower()
|
||||
entries = [
|
||||
e
|
||||
for e in entries
|
||||
if q_lower in e["manifest"].name.lower()
|
||||
or q_lower in e["manifest"].description.lower()
|
||||
]
|
||||
|
||||
if sort == "installs":
|
||||
entries = sorted(entries, key=lambda e: e["install_count"], reverse=True)
|
||||
elif sort == "rating":
|
||||
entries = sorted(entries, key=lambda e: e["avg_rating"], reverse=True)
|
||||
# "newest" = catalog insertion order (dict preserves insertion in Python 3.7+)
|
||||
|
||||
total = len(entries)
|
||||
start = (page - 1) * _PAGE_SIZE
|
||||
page_entries = entries[start : start + _PAGE_SIZE]
|
||||
|
||||
return PluginListResponse(
|
||||
plugins=[e["manifest"] for e in page_entries],
|
||||
total=total,
|
||||
page=page,
|
||||
)
|
||||
|
||||
async def get_plugin(self, plugin_id: str) -> dict[str, Any] | None:
|
||||
"""Return ``{manifest, status, install_count, avg_rating}`` or ``None``."""
|
||||
entry = self._catalog.get(plugin_id)
|
||||
if entry is None:
|
||||
return None
|
||||
return {
|
||||
"manifest": entry["manifest"],
|
||||
"status": entry["status"],
|
||||
"install_count": entry["install_count"],
|
||||
"avg_rating": entry["avg_rating"],
|
||||
}
|
||||
|
||||
# ── Mutations ────────────────────────────────────────────────────
|
||||
|
||||
async def submit_plugin(
|
||||
self,
|
||||
manifest: PluginManifest,
|
||||
package_s3_key: str,
|
||||
) -> str:
|
||||
"""Add *manifest* to the catalog with ``status='pending_review'``.
|
||||
|
||||
Returns the plugin_id. If a plugin with the same id already exists
|
||||
it is overwritten (re-submission after rejection).
|
||||
"""
|
||||
plugin_id = manifest.id or str(uuid.uuid4())
|
||||
self._catalog[plugin_id] = {
|
||||
"manifest": manifest,
|
||||
"status": "pending_review",
|
||||
"s3_package_key": package_s3_key,
|
||||
"install_count": 0,
|
||||
"avg_rating": 0.0,
|
||||
"rejection_reason": None,
|
||||
"submitted_at": int(time.time()),
|
||||
}
|
||||
return plugin_id
|
||||
|
||||
async def approve_plugin(self, plugin_id: str) -> None:
|
||||
"""Set *plugin_id* status to ``'approved'``.
|
||||
|
||||
Raises ``KeyError`` if the plugin is not found.
|
||||
"""
|
||||
if plugin_id not in self._catalog:
|
||||
raise KeyError(f"Plugin not found: {plugin_id}")
|
||||
self._catalog[plugin_id]["status"] = "approved"
|
||||
self._catalog[plugin_id]["rejection_reason"] = None
|
||||
|
||||
async def reject_plugin(self, plugin_id: str, reason: str) -> None:
|
||||
"""Set *plugin_id* status to ``'rejected'`` and record the reason.
|
||||
|
||||
Raises ``KeyError`` if the plugin is not found.
|
||||
"""
|
||||
if plugin_id not in self._catalog:
|
||||
raise KeyError(f"Plugin not found: {plugin_id}")
|
||||
self._catalog[plugin_id]["status"] = "rejected"
|
||||
self._catalog[plugin_id]["rejection_reason"] = reason
|
||||
|
||||
async def record_install(self, plugin_id: str) -> None:
|
||||
"""Increment the install count for *plugin_id* (no-op if not found)."""
|
||||
if plugin_id in self._catalog:
|
||||
self._catalog[plugin_id]["install_count"] += 1
|
||||
|
||||
async def record_uninstall(self, plugin_id: str) -> None:
|
||||
"""Decrement the install count for *plugin_id*, floored at 0."""
|
||||
if plugin_id in self._catalog:
|
||||
current = self._catalog[plugin_id]["install_count"]
|
||||
self._catalog[plugin_id]["install_count"] = max(0, current - 1)
|
||||
|
||||
# ── Internal helpers used by ReviewQueue ─────────────────────────
|
||||
|
||||
def _get_pending_entries(self) -> list[dict[str, Any]]:
|
||||
"""Return all entries with status='pending_review' (synchronous helper)."""
|
||||
return [e for e in self._catalog.values() if e["status"] == "pending_review"]
|
||||
|
||||
|
||||
# Module-level singleton
|
||||
registry = PluginRegistry()
|
||||
127
app/marketplace/plugin_review.py
Normal file
127
app/marketplace/plugin_review.py
Normal file
@@ -0,0 +1,127 @@
|
||||
"""Plugin review workflow.
|
||||
|
||||
Manages the approval queue for newly submitted plugins and enforces a
|
||||
security checklist before any plugin is made visible in the marketplace.
|
||||
|
||||
Module-level singleton::
|
||||
|
||||
from app.marketplace.plugin_review import review_queue
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import time
|
||||
from typing import Any, Literal
|
||||
|
||||
from app.marketplace.plugin_registry import registry
|
||||
from app.schemas import PluginManifest
|
||||
|
||||
# ── Security policy ───────────────────────────────────────────────────
|
||||
|
||||
ALLOWED_PERMISSIONS: frozenset[str] = frozenset(
|
||||
{
|
||||
"read:tasks",
|
||||
"write:tasks",
|
||||
"read:projects",
|
||||
"write:projects",
|
||||
"read:notes",
|
||||
"write:notes",
|
||||
"read:checkpoints",
|
||||
"write:checkpoints",
|
||||
"read:calendar",
|
||||
"write:calendar",
|
||||
}
|
||||
)
|
||||
|
||||
_PLUGIN_ID_RE = re.compile(r"^[a-z0-9-]+$")
|
||||
|
||||
|
||||
def validate_manifest(manifest: PluginManifest) -> None:
|
||||
"""Enforce the plugin security checklist.
|
||||
|
||||
Raises:
|
||||
``ValueError`` on the first violation found. Callers should catch
|
||||
this and return HTTP 422 / reject the submission.
|
||||
|
||||
Checks:
|
||||
1. Plugin id matches ``^[a-z0-9-]+$``
|
||||
2. All declared permissions are in ``ALLOWED_PERMISSIONS``
|
||||
3. No manifest field contains raw binary data
|
||||
"""
|
||||
if not _PLUGIN_ID_RE.match(manifest.id):
|
||||
raise ValueError(
|
||||
f"Invalid plugin id format: '{manifest.id}'. "
|
||||
"Only lowercase letters, digits, and hyphens are allowed."
|
||||
)
|
||||
|
||||
for perm in manifest.permissions:
|
||||
if perm not in ALLOWED_PERMISSIONS:
|
||||
raise ValueError(
|
||||
f"Unknown permission: '{perm}'. "
|
||||
f"Allowed permissions: {sorted(ALLOWED_PERMISSIONS)}"
|
||||
)
|
||||
|
||||
for field_name, value in manifest.model_dump().items():
|
||||
if isinstance(value, (bytes, bytearray)):
|
||||
raise ValueError(
|
||||
f"Binary content is not allowed in manifest field '{field_name}'."
|
||||
)
|
||||
|
||||
|
||||
class ReviewQueue:
|
||||
"""Approval queue for pending plugin submissions.
|
||||
|
||||
Delegates status changes to the shared ``PluginRegistry`` singleton so
|
||||
there is a single source of truth for plugin state.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
# Completed reviews — Step 12 stores in plugin_reviews table
|
||||
self._reviews: list[dict[str, Any]] = []
|
||||
|
||||
async def get_pending(self) -> list[dict[str, Any]]:
|
||||
"""Return all plugins currently awaiting review.
|
||||
|
||||
Each item is ``{plugin_id, manifest, submitted_at}``.
|
||||
"""
|
||||
entries = registry._get_pending_entries()
|
||||
return [
|
||||
{
|
||||
"plugin_id": e["manifest"].id,
|
||||
"manifest": e["manifest"],
|
||||
"submitted_at": e["submitted_at"],
|
||||
}
|
||||
for e in entries
|
||||
]
|
||||
|
||||
async def submit_review(
|
||||
self,
|
||||
plugin_id: str,
|
||||
reviewer_id: str,
|
||||
decision: Literal["approved", "rejected"],
|
||||
notes: str = "",
|
||||
) -> None:
|
||||
"""Record a review decision and update the plugin's status.
|
||||
|
||||
Raises:
|
||||
``KeyError`` if *plugin_id* is not found in the registry.
|
||||
"""
|
||||
if decision == "approved":
|
||||
await registry.approve_plugin(plugin_id)
|
||||
else:
|
||||
await registry.reject_plugin(plugin_id, reason=notes)
|
||||
|
||||
self._reviews.append(
|
||||
{
|
||||
"plugin_id": plugin_id,
|
||||
"reviewer_id": reviewer_id,
|
||||
"decision": decision,
|
||||
"notes": notes,
|
||||
"reviewed_at": int(time.time()),
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
# Module-level singleton
|
||||
review_queue = ReviewQueue()
|
||||
205
app/marketplace/revenue_share.py
Normal file
205
app/marketplace/revenue_share.py
Normal file
@@ -0,0 +1,205 @@
|
||||
"""Revenue share tracking and Stripe Connect payouts.
|
||||
|
||||
Records every plugin installation as a revenue event and facilitates
|
||||
70 % / 30 % payouts to developers via Stripe Connect. Storage is
|
||||
in-memory until Step 12 migrates to the ``revenue_events`` table.
|
||||
|
||||
Module-level singleton::
|
||||
|
||||
from app.marketplace.revenue_share import revenue_share
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
import stripe as stripe_lib
|
||||
|
||||
from app.config.settings import settings
|
||||
from app.marketplace.plugin_registry import registry
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# ── Revenue split constants ───────────────────────────────────────────
|
||||
|
||||
DEVELOPER_SHARE: float = 0.70
|
||||
PLATFORM_SHARE: float = 0.30
|
||||
|
||||
|
||||
class RevenueShare:
|
||||
"""Records installation revenue events and coordinates developer payouts.
|
||||
|
||||
Stripe Connect calls are gracefully stubbed when ``STRIPE_SECRET_KEY``
|
||||
is not configured, consistent with the rest of the billing layer.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
# Step 12 replaces with revenue_events DB table
|
||||
self._events: list[dict[str, Any]] = []
|
||||
|
||||
# ── Helpers ──────────────────────────────────────────────────────
|
||||
|
||||
@staticmethod
|
||||
def _stripe_configured() -> bool:
|
||||
return bool(settings.STRIPE_SECRET_KEY)
|
||||
|
||||
@staticmethod
|
||||
def _stripe() -> Any:
|
||||
stripe_lib.api_key = settings.STRIPE_SECRET_KEY
|
||||
return stripe_lib
|
||||
|
||||
# ── Core operations ──────────────────────────────────────────────
|
||||
|
||||
async def record_install(
|
||||
self,
|
||||
plugin_id: str,
|
||||
user_id: str,
|
||||
amount_cents: int,
|
||||
) -> None:
|
||||
"""Record a plugin installation and trigger a Stripe Connect charge if paid.
|
||||
|
||||
For free plugins (``amount_cents == 0``) no payment is initiated but
|
||||
the event is still recorded for analytics.
|
||||
|
||||
For paid plugins the developer receives 70 % via a Stripe Connect
|
||||
destination charge. If Stripe is not configured or the charge fails
|
||||
the installation still succeeds (the event is recorded and the install
|
||||
count is incremented) — a warning is logged for monitoring.
|
||||
"""
|
||||
developer_share_cents = int(amount_cents * DEVELOPER_SHARE)
|
||||
stripe_transfer_id: str | None = None
|
||||
|
||||
if amount_cents > 0 and self._stripe_configured():
|
||||
plugin_entry = registry._catalog.get(plugin_id)
|
||||
developer_stripe_account: str | None = None
|
||||
if plugin_entry:
|
||||
# Step 12: look up developer's Stripe account from DB
|
||||
# For now, the author field is used as a placeholder key.
|
||||
developer_stripe_account = None # no real account yet
|
||||
|
||||
if developer_stripe_account:
|
||||
try:
|
||||
s = self._stripe()
|
||||
transfer = s.Transfer.create(
|
||||
amount=developer_share_cents,
|
||||
currency="eur",
|
||||
destination=developer_stripe_account,
|
||||
description=f"Revenue share for plugin {plugin_id}",
|
||||
metadata={"plugin_id": plugin_id, "user_id": user_id},
|
||||
)
|
||||
stripe_transfer_id = transfer["id"]
|
||||
except Exception as exc:
|
||||
logger.warning(
|
||||
"Stripe Connect transfer failed for plugin %s: %s",
|
||||
plugin_id,
|
||||
exc,
|
||||
)
|
||||
else:
|
||||
logger.debug(
|
||||
"No Stripe account on file for plugin %s developer; "
|
||||
"skipping transfer.",
|
||||
plugin_id,
|
||||
)
|
||||
|
||||
self._events.append(
|
||||
{
|
||||
"plugin_id": plugin_id,
|
||||
"user_id": user_id,
|
||||
"amount_cents": amount_cents,
|
||||
"developer_share_cents": developer_share_cents,
|
||||
"stripe_transfer_id": stripe_transfer_id,
|
||||
"paid_at": None,
|
||||
"created_at": int(time.time()),
|
||||
}
|
||||
)
|
||||
|
||||
await registry.record_install(plugin_id)
|
||||
|
||||
async def get_earnings(
|
||||
self,
|
||||
developer_id: str,
|
||||
period: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Return aggregated earnings for *developer_id*.
|
||||
|
||||
``period`` is an optional ``YYYY-MM`` string to restrict the window.
|
||||
|
||||
Returns::
|
||||
|
||||
{
|
||||
"developer_id": str,
|
||||
"period": str | None,
|
||||
"total_installs": int,
|
||||
"total_revenue_cents": int,
|
||||
"developer_share_cents": int,
|
||||
}
|
||||
"""
|
||||
# Find plugin ids belonging to this developer
|
||||
developer_plugin_ids: set[str] = {
|
||||
pid
|
||||
for pid, entry in registry._catalog.items()
|
||||
if entry["manifest"].author == developer_id
|
||||
}
|
||||
|
||||
events = [e for e in self._events if e["plugin_id"] in developer_plugin_ids]
|
||||
|
||||
if period:
|
||||
# Filter by YYYY-MM prefix of the created_at timestamp
|
||||
events = [
|
||||
e
|
||||
for e in events
|
||||
if time.strftime("%Y-%m", time.gmtime(e["created_at"])) == period
|
||||
]
|
||||
|
||||
return {
|
||||
"developer_id": developer_id,
|
||||
"period": period,
|
||||
"total_installs": len(events),
|
||||
"total_revenue_cents": sum(e["amount_cents"] for e in events),
|
||||
"developer_share_cents": sum(e["developer_share_cents"] for e in events),
|
||||
}
|
||||
|
||||
async def payout_developer(self, plugin_id: str, period: str) -> None:
|
||||
"""Aggregate unpaid revenue for *period* and issue a Stripe Transfer.
|
||||
|
||||
Marks processed events with ``paid_at`` timestamp.
|
||||
Stubs gracefully when Stripe is not configured.
|
||||
"""
|
||||
unpaid = [
|
||||
e
|
||||
for e in self._events
|
||||
if e["plugin_id"] == plugin_id
|
||||
and e["paid_at"] is None
|
||||
and time.strftime("%Y-%m", time.gmtime(e["created_at"])) == period
|
||||
]
|
||||
|
||||
total_dev_share = sum(e["developer_share_cents"] for e in unpaid)
|
||||
if total_dev_share <= 0 or not unpaid:
|
||||
logger.debug("Nothing to pay out for plugin %s in period %s", plugin_id, period)
|
||||
return
|
||||
|
||||
if self._stripe_configured():
|
||||
plugin_entry = registry._catalog.get(plugin_id)
|
||||
developer_stripe_account: str | None = None # Step 12: fetch from DB
|
||||
if plugin_entry and developer_stripe_account:
|
||||
try:
|
||||
s = self._stripe()
|
||||
s.Transfer.create(
|
||||
amount=total_dev_share,
|
||||
currency="eur",
|
||||
destination=developer_stripe_account,
|
||||
description=f"Payout for plugin {plugin_id} period {period}",
|
||||
)
|
||||
except Exception as exc:
|
||||
logger.warning("Payout transfer failed for plugin %s: %s", plugin_id, exc)
|
||||
return
|
||||
|
||||
paid_ts = int(time.time())
|
||||
for event in unpaid:
|
||||
event["paid_at"] = paid_ts
|
||||
|
||||
|
||||
# Module-level singleton
|
||||
revenue_share = RevenueShare()
|
||||
Reference in New Issue
Block a user