growth-loop-sdk 0.1.0__tar.gz

growth_loop_sdk-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+build/
+.next/
+.turbo/
+out/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+.env.development
+.env.production
+!.env.example
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+
+# Coverage
+coverage/
+.nyc_output/
+
+# Archives — never commit zipped exports of repo content
+*.zip
+*.tar
+*.tar.gz
+*.tgz

growth_loop_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 growth-loop.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

growth_loop_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: growth-loop-sdk
+Version: 0.1.0
+Summary: Growth Python SDK — drop-in product analytics for vibe-coded SaaS. Pairs with the Growth MCP server to give Claude Code an AI growth engineer for your Python app.
+Project-URL: Homepage, https://growth-loop.dev
+Project-URL: Repository, https://gitlab.com/AKnyaZP/metrics
+Project-URL: Issues, https://gitlab.com/AKnyaZP/metrics/-/issues
+Author: growth-loop.dev
+License: MIT
+License-File: LICENSE
+Keywords: analytics,claude,claude-code,decorators,fastapi,flask,growth-loop,indie-hackers,instrumentation,product-analytics,saas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# growth-loop-sdk
+
+Python SDK for [growth-loop.dev](https://growth-loop.dev) — Claude
+Code-native product analytics for vibe-coded SaaS. The Python module name
+is `growth`; the PyPI distribution is `growth-loop-sdk`.
+
+Pairs with [`@growth-loop/mcp-server`](https://www.npmjs.com/package/@growth-loop/mcp-server)
+so Claude Code can ask your funnels, retention, and revenue questions
+directly with citations.
+
+## Install
+
+```sh
+pip install growth-loop-sdk
+# or
+uv add growth-loop-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import os
+from growth import Growth, GrowthOptions
+
+growth = Growth(GrowthOptions(
+    api_key=os.environ["GROWTH_KEY"],
+    host=os.environ.get("GROWTH_HOST", "https://api.growth-loop.dev"),
+    environment=os.environ.get("APP_ENV", "production"),
+    release=os.environ.get("GIT_COMMIT_SHA"),
+))
+
+# Anywhere in your app:
+growth.track("signup_completed", {"plan": "pro"})
+```
+
+The SDK runs a background worker thread; on `atexit` it flushes pending
+events automatically. On serverless platforms (Lambda, Cloud Run) call
+`growth.flush()` before the request handler returns.
+
+## FastAPI
+
+```python
+from fastapi import APIRouter
+from growth import growth_span, growth_step
+from growth_setup import growth      # the singleton from above
+
+router = APIRouter()
+
+@router.post("/checkout")
+@growth_span(growth, "checkout", distinct_id=lambda body: body.user_id)
+async def checkout(body: CheckoutBody):
+    # automatically emits checkout.started / .completed / .failed
+    # with duration_ms and error metadata
+    return await stripe.charge(body)
+
+@router.post("/signup")
+@growth_step(growth, "signup_completed", distinct_id=lambda body: body.user_id)
+async def signup(body: SignupBody):
+    return await create_user(body)
+```
+
+## Flask
+
+```python
+from flask import Blueprint
+from growth import growth_span
+from growth_setup import growth
+
+bp = Blueprint("checkout", __name__)
+
+@bp.route("/checkout", methods=["POST"])
+@growth_span(growth, "checkout", distinct_id=lambda: g.user.id)
+def checkout():
+    return stripe.charge(request.json)
+```
+
+## Core API
+
+### `Growth(options: GrowthOptions)`
+
+```python
+@dataclass
+class GrowthOptions:
+    api_key: str                       # required
+    host: str = "https://api.growth-loop.dev"
+    flush_interval: float = 5.0        # seconds
+    batch_size: int = 50
+    environment: str | None = None     # "production" | "preview" | "development"
+    release: str | None = None         # git SHA — used by /diagnose for commit-level attribution
+    timeout: float = 5.0               # HTTP timeout
+```
+
+| Method | What it does |
+|---|---|
+| `track(name, properties=None, options=None)` | Enqueue one event. Non-blocking. |
+| `identify(IdentifyOptions(distinct_id=..., properties=...))` | Set the current distinct ID + emit `$identify`. |
+| `set_distinct_id(id)` | Set the ID without emitting `$identify`. |
+| `flush()` | Force-send queued events. **Always call before request returns on serverless.** |
+| `shutdown()` | Flush + stop the worker. Called automatically on process exit. |
+
+### `TrackOptions`
+
+```python
+@dataclass
+class TrackOptions:
+    distinct_id: str | None = None     # override the client's default
+    timestamp: datetime | None = None  # override the auto-set UTC now
+    context: EventContext | None = None
+```
+
+## Decorators
+
+The three decorators auto-applied by `claude /init` (the MCP slash-prompt).
+Each preserves your function signature; types and docs flow through `@functools.wraps`.
+
+### `@growth_span(client, name, *, properties=None, distinct_id=None)`
+
+Emits `<name>.started`, `<name>.completed` (with `duration_ms`), or
+`<name>.failed` (with `error_message`, `error_name`). Works on sync **and**
+async functions automatically. Use on anything > 500ms or with non-trivial
+failure rate.
+
+```python
+@growth_span(growth, "ai.generate", distinct_id=lambda req: req.user_id)
+async def generate(req: GenerateRequest):
+    return await anthropic.messages.create(...)
+```
+
+`distinct_id` may be a literal string or a callable that receives the
+wrapped function's args/kwargs and returns the ID.
+
+### `@growth_step(client, funnel_step, *, properties=None, distinct_id=None)`
+
+Single-event funnel marker. Drop on whatever step represents
+*progress through your activation*.
+
+```python
+@growth_step(growth, "onboarding.invited_team")
+def invite_team(team_id: str):
+    ...
+```
+
+### `growth_track(client, name, properties=None)`
+
+Imperative one-off track. Equivalent to `client.track(name, properties)`,
+provided for symmetry with the decorator helpers.
+
+```python
+growth_track(growth, "pricing_viewed", {"tier": "pro"})
+```
+
+## Recommended event taxonomy
+
+The MCP server's `/diagnose`, `/weekly`, and `/pmf` prompts know these names natively:
+
+| Stage | Events |
+|---|---|
+| Identity | `signup_completed`, `login_completed`, `$identify` |
+| Activation | `onboarding.started`, `onboarding.completed`, `first_<thing>_created` |
+| Revenue | `checkout_started`, `checkout_completed`, `subscription_created`, `subscription_canceled`, `payment_failed` |
+| Performance | `growth_span(growth, "checkout", ...)`, `growth_span(growth, "ai.generate", ...)` |
+
+## Privacy
+
+- **Never put PII** (email, raw IP, full address, payment details) in
+  `properties`. Use `distinct_id` for identity. Backend ClickHouse never
+  decrypts or displays `properties` as identity.
+- ClickHouse TTL is 12 months by default — events older than that are
+  dropped automatically.
+
+## Going deeper
+
+The SDK is the ingest layer. The agent layer (Claude Code + MCP) is what
+makes growth-loop different — install the MCP server too:
+
+```sh
+claude mcp add growth-loop -- npx -y @growth-loop/mcp-server \
+  -e GROWTH_API_KEY=pk_live_<your-key>
+```
+
+Then in Claude Code: `/init` (auto-instrument), `/diagnose <metric>`,
+`/weekly`, `/pmf`, `/icp`, `/strategy`, `/pivot`.
+
+## License
+
+MIT

growth_loop_sdk-0.1.0/README.md

@@ -0,0 +1,188 @@
+# growth-loop-sdk
+
+Python SDK for [growth-loop.dev](https://growth-loop.dev) — Claude
+Code-native product analytics for vibe-coded SaaS. The Python module name
+is `growth`; the PyPI distribution is `growth-loop-sdk`.
+
+Pairs with [`@growth-loop/mcp-server`](https://www.npmjs.com/package/@growth-loop/mcp-server)
+so Claude Code can ask your funnels, retention, and revenue questions
+directly with citations.
+
+## Install
+
+```sh
+pip install growth-loop-sdk
+# or
+uv add growth-loop-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import os
+from growth import Growth, GrowthOptions
+
+growth = Growth(GrowthOptions(
+    api_key=os.environ["GROWTH_KEY"],
+    host=os.environ.get("GROWTH_HOST", "https://api.growth-loop.dev"),
+    environment=os.environ.get("APP_ENV", "production"),
+    release=os.environ.get("GIT_COMMIT_SHA"),
+))
+
+# Anywhere in your app:
+growth.track("signup_completed", {"plan": "pro"})
+```
+
+The SDK runs a background worker thread; on `atexit` it flushes pending
+events automatically. On serverless platforms (Lambda, Cloud Run) call
+`growth.flush()` before the request handler returns.
+
+## FastAPI
+
+```python
+from fastapi import APIRouter
+from growth import growth_span, growth_step
+from growth_setup import growth      # the singleton from above
+
+router = APIRouter()
+
+@router.post("/checkout")
+@growth_span(growth, "checkout", distinct_id=lambda body: body.user_id)
+async def checkout(body: CheckoutBody):
+    # automatically emits checkout.started / .completed / .failed
+    # with duration_ms and error metadata
+    return await stripe.charge(body)
+
+@router.post("/signup")
+@growth_step(growth, "signup_completed", distinct_id=lambda body: body.user_id)
+async def signup(body: SignupBody):
+    return await create_user(body)
+```
+
+## Flask
+
+```python
+from flask import Blueprint
+from growth import growth_span
+from growth_setup import growth
+
+bp = Blueprint("checkout", __name__)
+
+@bp.route("/checkout", methods=["POST"])
+@growth_span(growth, "checkout", distinct_id=lambda: g.user.id)
+def checkout():
+    return stripe.charge(request.json)
+```
+
+## Core API
+
+### `Growth(options: GrowthOptions)`
+
+```python
+@dataclass
+class GrowthOptions:
+    api_key: str                       # required
+    host: str = "https://api.growth-loop.dev"
+    flush_interval: float = 5.0        # seconds
+    batch_size: int = 50
+    environment: str | None = None     # "production" | "preview" | "development"
+    release: str | None = None         # git SHA — used by /diagnose for commit-level attribution
+    timeout: float = 5.0               # HTTP timeout
+```
+
+| Method | What it does |
+|---|---|
+| `track(name, properties=None, options=None)` | Enqueue one event. Non-blocking. |
+| `identify(IdentifyOptions(distinct_id=..., properties=...))` | Set the current distinct ID + emit `$identify`. |
+| `set_distinct_id(id)` | Set the ID without emitting `$identify`. |
+| `flush()` | Force-send queued events. **Always call before request returns on serverless.** |
+| `shutdown()` | Flush + stop the worker. Called automatically on process exit. |
+
+### `TrackOptions`
+
+```python
+@dataclass
+class TrackOptions:
+    distinct_id: str | None = None     # override the client's default
+    timestamp: datetime | None = None  # override the auto-set UTC now
+    context: EventContext | None = None
+```
+
+## Decorators
+
+The three decorators auto-applied by `claude /init` (the MCP slash-prompt).
+Each preserves your function signature; types and docs flow through `@functools.wraps`.
+
+### `@growth_span(client, name, *, properties=None, distinct_id=None)`
+
+Emits `<name>.started`, `<name>.completed` (with `duration_ms`), or
+`<name>.failed` (with `error_message`, `error_name`). Works on sync **and**
+async functions automatically. Use on anything > 500ms or with non-trivial
+failure rate.
+
+```python
+@growth_span(growth, "ai.generate", distinct_id=lambda req: req.user_id)
+async def generate(req: GenerateRequest):
+    return await anthropic.messages.create(...)
+```
+
+`distinct_id` may be a literal string or a callable that receives the
+wrapped function's args/kwargs and returns the ID.
+
+### `@growth_step(client, funnel_step, *, properties=None, distinct_id=None)`
+
+Single-event funnel marker. Drop on whatever step represents
+*progress through your activation*.
+
+```python
+@growth_step(growth, "onboarding.invited_team")
+def invite_team(team_id: str):
+    ...
+```
+
+### `growth_track(client, name, properties=None)`
+
+Imperative one-off track. Equivalent to `client.track(name, properties)`,
+provided for symmetry with the decorator helpers.
+
+```python
+growth_track(growth, "pricing_viewed", {"tier": "pro"})
+```
+
+## Recommended event taxonomy
+
+The MCP server's `/diagnose`, `/weekly`, and `/pmf` prompts know these names natively:
+
+| Stage | Events |
+|---|---|
+| Identity | `signup_completed`, `login_completed`, `$identify` |
+| Activation | `onboarding.started`, `onboarding.completed`, `first_<thing>_created` |
+| Revenue | `checkout_started`, `checkout_completed`, `subscription_created`, `subscription_canceled`, `payment_failed` |
+| Performance | `growth_span(growth, "checkout", ...)`, `growth_span(growth, "ai.generate", ...)` |
+
+## Privacy
+
+- **Never put PII** (email, raw IP, full address, payment details) in
+  `properties`. Use `distinct_id` for identity. Backend ClickHouse never
+  decrypts or displays `properties` as identity.
+- ClickHouse TTL is 12 months by default — events older than that are
+  dropped automatically.
+
+## Going deeper
+
+The SDK is the ingest layer. The agent layer (Claude Code + MCP) is what
+makes growth-loop different — install the MCP server too:
+
+```sh
+claude mcp add growth-loop -- npx -y @growth-loop/mcp-server \
+  -e GROWTH_API_KEY=pk_live_<your-key>
+```
+
+Then in Claude Code: `/init` (auto-instrument), `/diagnose <metric>`,
+`/weekly`, `/pmf`, `/icp`, `/strategy`, `/pivot`.
+
+## License
+
+MIT

growth_loop_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "growth-loop-sdk"
+version = "0.1.0"
+description = "Growth Python SDK — drop-in product analytics for vibe-coded SaaS. Pairs with the Growth MCP server to give Claude Code an AI growth engineer for your Python app."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "growth-loop.dev" }]
+keywords = [
+  "analytics",
+  "product-analytics",
+  "saas",
+  "indie-hackers",
+  "claude",
+  "claude-code",
+  "growth-loop",
+  "decorators",
+  "instrumentation",
+  "fastapi",
+  "flask",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Monitoring",
+]
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+  "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://growth-loop.dev"
+Repository = "https://gitlab.com/AKnyaZP/metrics"
+Issues = "https://gitlab.com/AKnyaZP/metrics/-/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/growth"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"

growth_loop_sdk-0.1.0/src/growth/__init__.py

@@ -0,0 +1,18 @@
+from growth.client import Growth, GrowthOptions, IdentifyOptions, TrackOptions
+from growth.decorators import growth_span, growth_step, growth_track
+from growth.types import EventContext, Properties, TrackEvent
+
+__all__ = [
+    "Growth",
+    "GrowthOptions",
+    "IdentifyOptions",
+    "TrackOptions",
+    "EventContext",
+    "Properties",
+    "TrackEvent",
+    "growth_span",
+    "growth_step",
+    "growth_track",
+]
+
+__version__ = "0.0.1"

growth_loop_sdk-0.1.0/src/growth/client.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import atexit
+import logging
+import threading
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from queue import Empty, Queue
+from typing import Any
+
+import httpx
+
+from growth.types import EventContext, Properties, TrackEvent
+
+_DEFAULT_HOST = "https://api.growth-loop.dev"
+_INGEST_PATH = "/v1/ingest"
+_DEFAULT_FLUSH_INTERVAL = 5.0
+_DEFAULT_BATCH_SIZE = 50
+_SDK_NAME = "growth-py"
+_SDK_VERSION = "0.0.1"
+
+logger = logging.getLogger("growth")
+
+
+@dataclass(slots=True)
+class GrowthOptions:
+    api_key: str
+    host: str = _DEFAULT_HOST
+    flush_interval: float = _DEFAULT_FLUSH_INTERVAL
+    batch_size: int = _DEFAULT_BATCH_SIZE
+    environment: str | None = None
+    release: str | None = None
+    timeout: float = 5.0
+
+
+@dataclass(slots=True)
+class TrackOptions:
+    distinct_id: str | None = None
+    timestamp: datetime | None = None
+    context: EventContext | None = None
+
+
+@dataclass(slots=True)
+class IdentifyOptions:
+    distinct_id: str
+    properties: Properties | None = None
+    context: EventContext | None = None
+
+
+class Growth:
+    def __init__(self, options: GrowthOptions) -> None:
+        if not options.api_key:
+            raise ValueError("api_key is required")
+        self._options = options
+        self._queue: Queue[TrackEvent] = Queue()
+        self._stopping = threading.Event()
+        self._distinct_id = str(uuid.uuid4())
+        self._client = httpx.Client(timeout=options.timeout)
+        self._worker = threading.Thread(target=self._run, name="growth-flush", daemon=True)
+        self._worker.start()
+        atexit.register(self.shutdown)
+
+    def set_distinct_id(self, distinct_id: str) -> None:
+        self._distinct_id = distinct_id
+
+    def track(
+        self,
+        name: str,
+        properties: Properties | None = None,
+        options: TrackOptions | None = None,
+    ) -> None:
+        if self._stopping.is_set():
+            return
+
+        ts = (options.timestamp if options and options.timestamp else datetime.now(timezone.utc))
+        event = TrackEvent(
+            name=name,
+            distinct_id=(options.distinct_id if options and options.distinct_id else self._distinct_id),
+            timestamp=ts.astimezone(timezone.utc).isoformat().replace("+00:00", "Z"),
+            properties=properties,
+            context=self._build_context(options.context if options else None),
+        )
+        self._queue.put_nowait(event)
+
+    def identify(self, options: IdentifyOptions) -> None:
+        self._distinct_id = options.distinct_id
+        self.track(
+            "$identify",
+            options.properties,
+            TrackOptions(distinct_id=options.distinct_id, context=options.context),
+        )
+
+    def alias(self, distinct_id: str, previous_id: str) -> None:
+        self.track(
+            "$alias",
+            {"previous_id": previous_id},
+            TrackOptions(distinct_id=distinct_id),
+        )
+        self._distinct_id = distinct_id
+
+    def flush(self) -> None:
+        events = self._drain()
+        if events:
+            self._send(events)
+
+    def shutdown(self) -> None:
+        if self._stopping.is_set():
+            return
+        self._stopping.set()
+        self.flush()
+        self._client.close()
+
+    def _run(self) -> None:
+        while not self._stopping.is_set():
+            try:
+                event = self._queue.get(timeout=self._options.flush_interval)
+            except Empty:
+                self.flush()
+                continue
+            batch: list[TrackEvent] = [event]
+            while len(batch) < self._options.batch_size:
+                try:
+                    batch.append(self._queue.get_nowait())
+                except Empty:
+                    break
+            self._send(batch)
+
+    def _drain(self) -> list[TrackEvent]:
+        out: list[TrackEvent] = []
+        while True:
+            try:
+                out.append(self._queue.get_nowait())
+            except Empty:
+                return out
+
+    def _send(self, events: list[TrackEvent]) -> None:
+        if not events:
+            return
+        payload: dict[str, Any] = {
+            "api_key": self._options.api_key,
+            "sdk": {"name": _SDK_NAME, "version": _SDK_VERSION},
+            "sent_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "events": [e.to_dict() for e in events],
+        }
+        url = self._options.host.rstrip("/") + _INGEST_PATH
+        try:
+            response = self._client.post(
+                url,
+                json=payload,
+                headers={"x-growth-sdk": f"{_SDK_NAME}/{_SDK_VERSION}"},
+            )
+            response.raise_for_status()
+        except httpx.HTTPError as exc:
+            logger.warning("growth ingest failed: %s", exc)
+
+    def _build_context(self, context: EventContext | None) -> dict[str, Any]:
+        merged: dict[str, Any] = {}
+        if self._options.release:
+            merged["release"] = self._options.release
+        if self._options.environment:
+            merged["environment"] = self._options.environment
+        if context:
+            merged.update(context.to_dict())
+        return merged

growth_loop_sdk-0.1.0/src/growth/decorators.py

@@ -0,0 +1,163 @@
+"""
+Higher-level instrumentation: spans, steps, tracked events.
+
+These wrap the low-level `track()` API in patterns the agent (and a human)
+can drop into existing code with minimal change. Designed to be applied
+automatically by `claude /growth init`.
+
+Usage:
+
+    from growth import Growth, GrowthOptions
+
+    growth = Growth(GrowthOptions(api_key="pk_live_…", host="https://api.growth-loop.dev"))
+
+    @growth_span(growth, "checkout")
+    def run_checkout(user_id: str): ...
+
+    @growth_step(growth, "activation.invited_team")
+    def invite_team(team_id: str): ...
+
+    growth_track(growth, "login_clicked")
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar, cast, overload
+
+from growth.client import Growth, TrackOptions
+from growth.types import Properties
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+def growth_span(
+    client: Growth,
+    name: str,
+    *,
+    properties: Properties | None = None,
+    distinct_id: Callable[..., str | None] | str | None = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator that emits `<name>.started`, `<name>.completed`, `<name>.failed`
+    events with duration_ms. Works on sync and async functions.
+
+    `distinct_id` may be a string (literal user id) or a callable that receives
+    the wrapped function's args/kwargs and returns the id.
+    """
+
+    def _resolve_id(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str | None:
+        if callable(distinct_id):
+            try:
+                return distinct_id(*args, **kwargs)
+            except Exception:
+                return None
+        return distinct_id
+
+    def decorator(fn: Callable[P, T]) -> Callable[P, T]:
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                started_at = time.monotonic()
+                base = dict(properties or {})
+                opts = TrackOptions(distinct_id=_resolve_id(args, kwargs))
+                client.track(f"{name}.started", base, opts)
+                try:
+                    result = await cast(Awaitable[T], fn(*args, **kwargs))
+                    client.track(
+                        f"{name}.completed",
+                        {**base, "duration_ms": int((time.monotonic() - started_at) * 1000)},
+                        opts,
+                    )
+                    return result
+                except Exception as exc:
+                    client.track(
+                        f"{name}.failed",
+                        {
+                            **base,
+                            "duration_ms": int((time.monotonic() - started_at) * 1000),
+                            "error_message": str(exc)[:500],
+                            "error_name": type(exc).__name__,
+                        },
+                        opts,
+                    )
+                    raise
+
+            return cast(Callable[P, T], async_wrapper)
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            started_at = time.monotonic()
+            base = dict(properties or {})
+            opts = TrackOptions(distinct_id=_resolve_id(args, kwargs))
+            client.track(f"{name}.started", base, opts)
+            try:
+                result = fn(*args, **kwargs)
+                client.track(
+                    f"{name}.completed",
+                    {**base, "duration_ms": int((time.monotonic() - started_at) * 1000)},
+                    opts,
+                )
+                return result
+            except Exception as exc:
+                client.track(
+                    f"{name}.failed",
+                    {
+                        **base,
+                        "duration_ms": int((time.monotonic() - started_at) * 1000),
+                        "error_message": str(exc)[:500],
+                        "error_name": type(exc).__name__,
+                    },
+                    opts,
+                )
+                raise
+
+        return sync_wrapper
+
+    return decorator
+
+
+def growth_step(
+    client: Growth,
+    funnel_step: str,
+    *,
+    properties: Properties | None = None,
+    distinct_id: Callable[..., str | None] | str | None = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator that emits a single funnel-step event when the wrapped function runs."""
+
+    def decorator(fn: Callable[P, T]) -> Callable[P, T]:
+        @functools.wraps(fn)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            opts: TrackOptions | None = None
+            if callable(distinct_id):
+                try:
+                    opts = TrackOptions(distinct_id=distinct_id(*args, **kwargs))
+                except Exception:
+                    opts = None
+            elif distinct_id is not None:
+                opts = TrackOptions(distinct_id=distinct_id)
+            client.track(funnel_step, dict(properties or {}), opts)
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+@overload
+def growth_track(client: Growth, name: str) -> None: ...
+@overload
+def growth_track(
+    client: Growth, name: str, properties: Properties | None
+) -> None: ...
+
+
+def growth_track(
+    client: Growth, name: str, properties: Properties | None = None
+) -> None:
+    """Synchronous one-off track. Equivalent to `client.track(name, properties)`."""
+    client.track(name, properties)

growth_loop_sdk-0.1.0/src/growth/types.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+Properties = dict[str, Any]
+
+
+@dataclass(slots=True)
+class EventContext:
+    page_url: str | None = None
+    page_path: str | None = None
+    page_title: str | None = None
+    referrer: str | None = None
+    user_agent: str | None = None
+    ip: str | None = None
+    locale: str | None = None
+    timezone: str | None = None
+    utm_source: str | None = None
+    utm_medium: str | None = None
+    utm_campaign: str | None = None
+    release: str | None = None
+    commit_sha: str | None = None
+    deploy_id: str | None = None
+    environment: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+@dataclass(slots=True)
+class TrackEvent:
+    name: str
+    distinct_id: str
+    timestamp: str
+    source: str = "server"
+    properties: Properties | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+    session_id: str | None = None
+    anonymous_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "name": self.name,
+            "distinct_id": self.distinct_id,
+            "timestamp": self.timestamp,
+            "source": self.source,
+        }
+        if self.properties:
+            out["properties"] = self.properties
+        if self.context:
+            out["context"] = self.context
+        if self.session_id:
+            out["session_id"] = self.session_id
+        if self.anonymous_id:
+            out["anonymous_id"] = self.anonymous_id
+        return out