makea-cli 0.1.14__tar.gz → 0.1.16__tar.gz

{makea_cli-0.1.14 → makea_cli-0.1.16}/.gitignore

@@ -22,3 +22,4 @@ creds_*.json
 
 # Random-name temp drop from sandbox uploads (e.g. zi1zLQLi).
 zi1zLQLi
+.release-venv/

{makea_cli-0.1.14 → makea_cli-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: makea-cli
-Version: 0.1.14
+Version: 0.1.16
 Summary: Makea admin CLI (browser login + Makea admin HTTP API)
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27

makea_cli-0.1.16/makea_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.16"

{makea_cli-0.1.14 → makea_cli-0.1.16}/makea_cli/commands/__init__.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import typer
 
+from makea_cli.commands.analytics.cmd import register as register_analytics
 from makea_cli.commands.auth.cmd import register as register_auth
 from makea_cli.commands.designer.cmd import register as register_designer
 from makea_cli.commands.directory.cmd import register as register_directory
@@ -22,4 +23,5 @@ def register_all(app: typer.Typer) -> None:
     register_product(app)
     register_designer(app)
     register_metrics(app)
+    register_analytics(app)
     register_email(app)

makea_cli-0.1.16/makea_cli/commands/analytics/cmd.py

@@ -0,0 +1,169 @@
+"""`makea-cli analytics ...` — PostHog product-analytics queries.
+
+Behavioural metrics (feature usage, clicks, page/feature time, active users)
+backed by PostHog HogQL. Distinct from the `metrics` group, which reads the
+Makea backend for financial figures.
+
+Requires env: POSTHOG_API_KEY, POSTHOG_PROJECT_ID (see config.py).
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from makea_cli.commands._util import print_json_or_exit
+from makea_cli.posthog_client import run_hogql, rows_as_dicts
+
+console = Console()
+
+
+def _sql_str(value: str) -> str:
+    """Escape a string for safe inlining into a HogQL single-quoted literal."""
+    return value.replace("'", "''")
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "analytics-feature-usage",
+        help=(
+            "How many distinct users used a feature recently, plus event volume. "
+            "Matches $pageview path and feature_time_spent events. "
+            "Example: analytics-feature-usage --feature tech-pack-builder --days 30"
+        ),
+    )
+    def feature_usage(
+        feature: str = typer.Option(
+            ...,
+            "--feature",
+            "-f",
+            help=(
+                "Feature key — matched against the pageview path (substring) and "
+                "feature_time_spent.feature (exact). E.g. tech-pack-builder."
+            ),
+        ),
+        days: int = typer.Option(30, "--days", "-d", help="Look-back window in days. Default: 30."),
+    ) -> None:
+        """Distinct users + event count for a feature over the last N days."""
+        f = _sql_str(feature.strip())
+        query = f"""
+            SELECT
+                count(DISTINCT person_id) AS users,
+                count() AS events,
+                min(timestamp) AS first_seen,
+                max(timestamp) AS last_seen
+            FROM events
+            WHERE timestamp >= now() - INTERVAL {days} DAY
+              AND (
+                (event = '$pageview' AND properties.path LIKE '%{f}%')
+                OR (event = 'feature_time_spent' AND properties.feature = '{f}')
+              )
+        """
+        print_json_or_exit(
+            console,
+            lambda: {
+                "feature": feature,
+                "days": days,
+                "result": rows_as_dicts(run_hogql(query)),
+            },
+        )
+
+    @app.command(
+        "analytics-top-features",
+        help=(
+            "Rank pageview paths by distinct users over the last N days — a quick "
+            "map of which features get used most."
+        ),
+    )
+    def top_features(
+        days: int = typer.Option(30, "--days", "-d", help="Look-back window. Default: 30."),
+        limit: int = typer.Option(20, "--limit", "-l", help="Rows to return. Default: 20."),
+    ) -> None:
+        """Top pageview paths by distinct users."""
+        query = f"""
+            SELECT
+                properties.path AS path,
+                count(DISTINCT person_id) AS users,
+                count() AS views
+            FROM events
+            WHERE event = '$pageview'
+              AND timestamp >= now() - INTERVAL {days} DAY
+              AND properties.path IS NOT NULL
+            GROUP BY path
+            ORDER BY users DESC
+            LIMIT {limit}
+        """
+        print_json_or_exit(
+            console,
+            lambda: {"days": days, "result": rows_as_dicts(run_hogql(query))},
+        )
+
+    @app.command(
+        "analytics-top-clicks",
+        help=(
+            "Rank autocaptured click targets by count over the last N days — "
+            "which buttons/elements get clicked most."
+        ),
+    )
+    def top_clicks(
+        days: int = typer.Option(30, "--days", "-d", help="Look-back window. Default: 30."),
+        limit: int = typer.Option(20, "--limit", "-l", help="Rows to return. Default: 20."),
+    ) -> None:
+        """Top autocaptured click targets (by element text)."""
+        query = f"""
+            SELECT
+                properties.$el_text AS element_text,
+                properties.$event_type AS event_type,
+                count() AS clicks,
+                count(DISTINCT person_id) AS users
+            FROM events
+            WHERE event = '$autocapture'
+              AND properties.$event_type = 'click'
+              AND timestamp >= now() - INTERVAL {days} DAY
+              AND properties.$el_text IS NOT NULL
+            GROUP BY element_text, event_type
+            ORDER BY clicks DESC
+            LIMIT {limit}
+        """
+        print_json_or_exit(
+            console,
+            lambda: {"days": days, "result": rows_as_dicts(run_hogql(query))},
+        )
+
+    @app.command(
+        "analytics-active-users",
+        help="Distinct active users per day over the last N days (DAU series).",
+    )
+    def active_users(
+        days: int = typer.Option(30, "--days", "-d", help="Look-back window. Default: 30."),
+    ) -> None:
+        """Daily active users series."""
+        query = f"""
+            SELECT
+                toDate(timestamp) AS day,
+                count(DISTINCT person_id) AS users
+            FROM events
+            WHERE timestamp >= now() - INTERVAL {days} DAY
+            GROUP BY day
+            ORDER BY day
+        """
+        print_json_or_exit(
+            console,
+            lambda: {"days": days, "result": rows_as_dicts(run_hogql(query))},
+        )
+
+    @app.command(
+        "analytics-query",
+        help=(
+            "Run an arbitrary HogQL query (escape hatch). "
+            'Example: analytics-query "SELECT count() FROM events"'
+        ),
+    )
+    def query(
+        hogql: str = typer.Argument(..., help="HogQL query string."),
+    ) -> None:
+        """Run a raw HogQL query and return columns + rows as dicts."""
+        print_json_or_exit(
+            console,
+            lambda: {"result": rows_as_dicts(run_hogql(hogql))},
+        )

makea_cli-0.1.16/makea_cli/commands/metrics/cmd.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import math
+
+import httpx
+import typer
+from rich.console import Console
+
+from makea_cli import api_client
+from makea_cli.commands._util import print_json_or_exit
+
+console = Console()
+
+_GRANULARITIES = ("day", "week", "month")
+_ORDER_TYPES = ("all", "sampling", "production")
+
+# Same free FX source the backend uses (FreeCurrencyService), so converted
+# amounts match the platform's revenue metrics.
+_FX_PRIMARY = (
+    "https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/{base}.json"
+)
+_FX_FALLBACK = "https://latest.currency-api.pages.dev/v1/currencies/{base}.json"
+
+
+def _fx_rate(base: str, target: str) -> float:
+    """Exchange rate base -> target, rounded UP to 2dp exactly like the backend
+    (math.ceil(raw * 100) / 100) so totals reconcile with revenue metrics."""
+    base, target = base.lower(), target.lower()
+    if base == target:
+        return 1.0
+    last_err: Exception | None = None
+    for url in (_FX_PRIMARY.format(base=base), _FX_FALLBACK.format(base=base)):
+        try:
+            with httpx.Client(timeout=10) as client:
+                resp = client.get(url)
+                resp.raise_for_status()
+                data = resp.json()
+            raw = data.get(base, {}).get(target)
+            if raw is not None:
+                return math.ceil(float(raw) * 100) / 100
+        except Exception as e:  # noqa: BLE001 - try fallback URL
+            last_err = e
+            continue
+    raise RuntimeError(
+        f"FX rate {base.upper()}->{target.upper()} unavailable"
+        + (f": {last_err}" if last_err else "")
+    )
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "get-cumulative-payment-and-platform-revenue",
+        help=(
+            "GET /admin/business-metrics/cumulative-payment-and-platform-revenue — "
+            "platform-wide payment received and platform revenue (service fee + "
+            "transaction fee) bucketed over a date range."
+        ),
+    )
+    def get_cumulative_payment_and_platform_revenue(
+        start_date: str = typer.Option(
+            ...,
+            "--start-date",
+            help="Start date (inclusive), ISO format YYYY-MM-DD.",
+        ),
+        end_date: str = typer.Option(
+            ...,
+            "--end-date",
+            help="End date (inclusive), ISO format YYYY-MM-DD.",
+        ),
+        granularity: str = typer.Option(
+            "day",
+            "--granularity",
+            "-g",
+            help="Time bucket: day, week, or month. Default: day.",
+        ),
+        currency: str = typer.Option(
+            "GBP",
+            "--currency",
+            "-c",
+            help="Target currency for conversion. Default: GBP.",
+        ),
+        order_type: str = typer.Option(
+            "all",
+            "--order-type",
+            "-t",
+            help="Filter: all, sampling, or production. Default: all.",
+        ),
+    ) -> None:
+        """
+        Platform-wide cumulative payment received and platform revenue over a date range.
+
+        Calls GET /admin/business-metrics/cumulative-payment-and-platform-revenue.
+
+        Platform revenue = service fee + transaction fee (the 2.8% transaction fee is
+        applied by the server). The response contains two siblings under ``result``:
+
+        - ``payment_received``: cumulative/period amounts per bucket, plus a
+          ``payment_breakdown`` (sampling / production_deposit / production_final).
+        - ``platform_revenue``: cumulative/period amounts per bucket.
+
+        Input: required --start-date and --end-date (YYYY-MM-DD); optional
+        --granularity (day|week|month), --currency, --order-type (all|sampling|production).
+
+        Output: raw JSON body from the admin business-metrics endpoint.
+
+        This endpoint is **platform-wide only** and does not support filtering by
+        user_id, product, or category. For per-user / per-product drill-downs, use
+        list-product-orders / list-sampling-orders-by-product /
+        list-production-orders-by-product and aggregate client-side.
+        """
+        g = granularity.strip().lower()
+        if g not in _GRANULARITIES:
+            console.print(f"[red]--granularity must be one of: {', '.join(_GRANULARITIES)}.[/red]")
+            raise typer.Exit(1)
+        ot = order_type.strip().lower()
+        if ot not in _ORDER_TYPES:
+            console.print(f"[red]--order-type must be one of: {', '.join(_ORDER_TYPES)}.[/red]")
+            raise typer.Exit(1)
+
+        print_json_or_exit(
+            console,
+            lambda: api_client.get_cumulative_payment_and_platform_revenue(
+                start_date=start_date,
+                end_date=end_date,
+                granularity=g,
+                currency=currency,
+                order_type=ot,
+            ),
+        )
+
+    @app.command(
+        "convert-currency",
+        help=(
+            "Convert money between currencies using the same free FX source and "
+            "rounding as the platform's revenue metrics. Pass several source "
+            "currencies via --from (comma-separated) to get a full rate table in "
+            "one call, then convert locally — avoids repeated lookups."
+        ),
+    )
+    def convert_currency(
+        to: str = typer.Option(..., "--to", "-t", help="Target currency, e.g. GBP."),
+        from_: str = typer.Option(
+            ...,
+            "--from",
+            "-f",
+            help="Source currency code, or comma-separated list (e.g. usd,eur,cny,gbp).",
+        ),
+        amount: float = typer.Option(
+            None,
+            "--amount",
+            "-a",
+            help="Optional amount to convert (only meaningful with a single --from).",
+        ),
+    ) -> None:
+        """Return source->target rates (rounded like the backend), and optionally a
+        converted amount.
+
+        Use it to collapse a mixed-currency set into one currency: collect the
+        distinct currencies, call once with --from a,b,c to get every rate, then
+        multiply locally. Rates use math.ceil(raw * 100) / 100, matching the
+        platform's FreeCurrencyService, so totals reconcile with revenue metrics.
+
+        Output JSON: {"to", "rates": {CUR: rate, ...}, "rounding", "source"} plus
+        {"from", "rate", "amount", "converted"} when a single --from and --amount
+        are given.
+        """
+        sources = [s.strip() for s in from_.split(",") if s.strip()]
+        if not sources:
+            console.print("[red]--from must contain at least one currency code.[/red]")
+            raise typer.Exit(1)
+
+        def _do() -> dict:
+            rates = {s.upper(): _fx_rate(s, to) for s in sources}
+            out: dict = {
+                "to": to.upper(),
+                "rates": rates,
+                "rounding": "ceil_2dp",
+                "source": "fawazahmed0/currency-api",
+            }
+            if amount is not None and len(sources) == 1:
+                rate = rates[sources[0].upper()]
+                out.update(
+                    {
+                        "from": sources[0].upper(),
+                        "rate": rate,
+                        "amount": amount,
+                        "converted": round(amount * rate, 2),
+                    }
+                )
+            return out
+
+        print_json_or_exit(console, _do)

{makea_cli-0.1.14 → makea_cli-0.1.16}/makea_cli/config.py

@@ -46,6 +46,29 @@ def redirect_uri() -> str:
     return _env("MAKEA_REDIRECT_URI", DEFAULT_REDIRECT_URI) or DEFAULT_REDIRECT_URI
 
 
+# PostHog product-analytics (behavioural metrics: clicks, page/feature time,
+# funnels, retention). Distinct from the financial `metrics` command group,
+# which reads the Makea backend. Configured purely via environment so no key is
+# ever committed:
+#   POSTHOG_API_KEY     personal API key (phx_...), read-only is enough
+#   POSTHOG_PROJECT_ID  numeric project id
+#   POSTHOG_HOST        defaults to the EU cloud query host
+DEFAULT_POSTHOG_HOST = "https://eu.posthog.com"
+
+
+def posthog_host() -> str:
+    h = _env("POSTHOG_HOST", DEFAULT_POSTHOG_HOST) or DEFAULT_POSTHOG_HOST
+    return h.rstrip("/")
+
+
+def posthog_api_key() -> str | None:
+    return _env("POSTHOG_API_KEY")
+
+
+def posthog_project_id() -> str | None:
+    return _env("POSTHOG_PROJECT_ID")
+
+
 def load_credentials() -> dict[str, Any] | None:
     if not CREDENTIALS_PATH.is_file():
         return None

makea_cli-0.1.16/makea_cli/posthog_client.py

@@ -0,0 +1,64 @@
+"""Minimal PostHog query client (HogQL over the Query API).
+
+This talks to PostHog's cloud directly, not the Makea backend, so it has its
+own auth (a personal API key from env) rather than the Cognito token used by
+api_client.
+
+Docs: POST {host}/api/projects/{project_id}/query/ with a HogQLQuery body.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from makea_cli.config import posthog_api_key, posthog_host, posthog_project_id
+
+
+class PostHogNotConfigured(RuntimeError):
+    """Raised when the required PostHog env vars are missing."""
+
+
+def _require_config() -> tuple[str, str, str]:
+    key = posthog_api_key()
+    project = posthog_project_id()
+    if not key or not project:
+        raise PostHogNotConfigured(
+            "PostHog is not configured. Set POSTHOG_API_KEY (personal API key, "
+            "phx_...) and POSTHOG_PROJECT_ID, optionally POSTHOG_HOST "
+            "(default https://eu.posthog.com)."
+        )
+    return posthog_host(), project, key
+
+
+def run_hogql(query: str, *, timeout: float = 60.0) -> dict[str, Any]:
+    """Run a HogQL query and return the raw result.
+
+    The result has ``columns`` (list of names) and ``results`` (list of rows);
+    callers usually want to zip them into dicts for display.
+    """
+    host, project, key = _require_config()
+    url = f"{host}/api/projects/{project}/query/"
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    body = {"query": {"kind": "HogQLQuery", "query": query}}
+    with httpx.Client(timeout=timeout) as client:
+        r = client.post(url, headers=headers, json=body)
+    if r.status_code >= 400:
+        try:
+            detail = r.json()
+        except json.JSONDecodeError:
+            detail = r.text
+        raise RuntimeError(f"HTTP {r.status_code}: {detail}")
+    return r.json()
+
+
+def rows_as_dicts(result: dict[str, Any]) -> list[dict[str, Any]]:
+    """Zip ``columns`` + ``results`` from a HogQL response into row dicts."""
+    columns = result.get("columns") or []
+    return [dict(zip(columns, row)) for row in result.get("results") or []]

{makea_cli-0.1.14 → makea_cli-0.1.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "makea-cli"
-version = "0.1.14"
+version = "0.1.16"
 description = "Makea admin CLI (browser login + Makea admin HTTP API)"
 readme = "README.md"
 requires-python = ">=3.10"

makea_cli-0.1.14/.release-venv/.gitignore

@@ -1,2 +0,0 @@
-# Created by venv; see https://docs.python.org/3/library/venv.html
-*