peekapi 0.1.0__tar.gz

peekapi-0.1.0/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true

peekapi-0.1.0/.git

@@ -0,0 +1 @@
+gitdir: ../../.git/modules/packages/sdk-python

peekapi-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: peekapi-dev

peekapi-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug Report
+description: Report a bug
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK Version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: runtime-version
+    attributes:
+      label: Python Version
+      placeholder: "3.13"
+    validations:
+      required: true

peekapi-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature Request
+description: Suggest a feature
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What would you like to see added?
+    validations:
+      required: true
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Why do you need this feature?
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like it to work?
+    validations:
+      required: false

peekapi-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+## Summary
+
+<!-- What does this PR do? -->
+
+## Checklist
+
+- [ ] Tests pass
+- [ ] No breaking changes (or documented in description)

peekapi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install uv
+      - run: uv sync --no-install-project
+      - run: uv run pytest -v
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/

peekapi-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/

peekapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# 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.1.0] - 2025-06-01
+
+- Initial release

peekapi-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Please report unacceptable behavior to **security@peekapi.dev**.

peekapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PeekAPI
+
+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.

peekapi-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: peekapi
+Version: 0.1.0
+Summary: Zero-dependency Python SDK for PeekAPI
+Project-URL: Homepage, https://github.com/peekapi-dev/sdk-python
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,api,dashboard,middleware
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# PeekAPI — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/peekapi)](https://pypi.org/project/peekapi/)
+[![license](https://img.shields.io/pypi/l/peekapi)](./LICENSE)
+[![CI](https://github.com/peekapi-dev/sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/peekapi-dev/sdk-python/actions/workflows/ci.yml)
+
+Zero-dependency Python SDK for [PeekAPI](https://peekapi.dev). Built-in middleware for ASGI (FastAPI, Starlette, Litestar), WSGI (Flask, Bottle), and Django.
+
+## Install
+
+```bash
+pip install peekapi
+```
+
+## Quick Start
+
+### FastAPI / Starlette (ASGI)
+
+```python
+from fastapi import FastAPI
+from peekapi import PeekApiClient
+from peekapi.middleware import PeekApiASGI
+
+client = PeekApiClient({"api_key": "ak_live_xxx"})
+
+app = FastAPI()
+app.add_middleware(PeekApiASGI, client=client)
+```
+
+### Flask (WSGI)
+
+```python
+from flask import Flask
+from peekapi import PeekApiClient
+from peekapi.middleware import PeekApiWSGI
+
+client = PeekApiClient({"api_key": "ak_live_xxx"})
+
+app = Flask(__name__)
+app.wsgi_app = PeekApiWSGI(app.wsgi_app, client=client)
+```
+
+### Django
+
+```python
+# settings.py
+PEEKAPI = {
+    "api_key": "ak_live_xxx",
+}
+
+MIDDLEWARE = [
+    "peekapi.middleware.django.PeekApiMiddleware",
+    # ... other middleware
+]
+```
+
+### Standalone Client
+
+```python
+from peekapi import PeekApiClient
+
+client = PeekApiClient({"api_key": "ak_live_xxx"})
+
+client.track({
+    "method": "GET",
+    "path": "/api/users",
+    "status_code": 200,
+    "response_time_ms": 42,
+})
+
+# Graceful shutdown (flushes remaining events)
+client.shutdown()
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | required | Your PeekAPI key |
+| `endpoint` | PeekAPI cloud | Ingestion endpoint URL |
+| `flush_interval` | `10.0` | Seconds between automatic flushes |
+| `batch_size` | `100` | Events per HTTP POST (triggers flush) |
+| `max_buffer_size` | `10000` | Max events held in memory |
+| `max_storage_bytes` | `5242880` | Max disk fallback file size (5MB) |
+| `max_event_bytes` | `65536` | Per-event size limit (64KB) |
+| `storage_path` | auto | Custom path for JSONL persistence file |
+| `debug` | `False` | Enable debug logging |
+| `on_error` | `None` | Callback `(Exception) -> None` for flush errors |
+
+## How It Works
+
+1. Middleware intercepts every request/response
+2. Captures method, path, status code, response time, request/response sizes, consumer ID
+3. Events are buffered in memory and flushed in batches on a daemon thread
+4. On network failure: exponential backoff with jitter, up to 5 retries
+5. After max retries: events are persisted to a JSONL file on disk
+6. On next startup: persisted events are recovered and re-sent
+7. On SIGTERM/SIGINT: remaining buffer is flushed or persisted to disk
+
+## Consumer Identification
+
+By default, consumers are identified by:
+
+1. `X-API-Key` header — stored as-is
+2. `Authorization` header — hashed with SHA-256 (stored as `hash_<hex>`)
+
+Override with the `identify_consumer` option to use any header or request property:
+
+```python
+client = PeekApiClient({
+    "api_key": "...",
+    "identify_consumer": lambda headers: headers.get("x-tenant-id"),
+})
+```
+
+The callback receives a `dict[str, str]` of lowercase header names and should return a consumer ID string or `None`.
+
+## Features
+
+- **Zero runtime dependencies** — uses only Python stdlib
+- **Background flush** — daemon thread with configurable interval and batch size
+- **Disk persistence** — undelivered events saved to JSONL, recovered on restart
+- **Exponential backoff** — with jitter, max 5 consecutive failures before disk fallback
+- **SSRF protection** — private IP blocking, HTTPS enforcement (HTTP only for localhost)
+- **Input sanitization** — path (2048), method (16), consumer_id (256) truncation
+- **Per-event size limit** — strips metadata first, drops if still too large (default 64KB)
+- **Graceful shutdown** — signal handlers (SIGTERM/SIGINT) with disk persistence
+
+## Requirements
+
+- Python >= 3.10
+
+## Contributing
+
+1. Fork & clone the repo
+2. Install dev dependencies — `uv sync --no-install-project`
+3. Run tests — `uv run pytest -v`
+4. Lint & format — `uv run ruff check src/ tests/` / `uv run ruff format src/ tests/`
+5. Submit a PR
+
+## License
+
+MIT

peekapi-0.1.0/README.md

@@ -0,0 +1,143 @@
+# PeekAPI — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/peekapi)](https://pypi.org/project/peekapi/)
+[![license](https://img.shields.io/pypi/l/peekapi)](./LICENSE)
+[![CI](https://github.com/peekapi-dev/sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/peekapi-dev/sdk-python/actions/workflows/ci.yml)
+
+Zero-dependency Python SDK for [PeekAPI](https://peekapi.dev). Built-in middleware for ASGI (FastAPI, Starlette, Litestar), WSGI (Flask, Bottle), and Django.
+
+## Install
+
+```bash
+pip install peekapi
+```
+
+## Quick Start
+
+### FastAPI / Starlette (ASGI)
+
+```python
+from fastapi import FastAPI
+from peekapi import PeekApiClient
+from peekapi.middleware import PeekApiASGI
+
+client = PeekApiClient({"api_key": "ak_live_xxx"})
+
+app = FastAPI()
+app.add_middleware(PeekApiASGI, client=client)
+```
+
+### Flask (WSGI)
+
+```python
+from flask import Flask
+from peekapi import PeekApiClient
+from peekapi.middleware import PeekApiWSGI
+
+client = PeekApiClient({"api_key": "ak_live_xxx"})
+
+app = Flask(__name__)
+app.wsgi_app = PeekApiWSGI(app.wsgi_app, client=client)
+```
+
+### Django
+
+```python
+# settings.py
+PEEKAPI = {
+    "api_key": "ak_live_xxx",
+}
+
+MIDDLEWARE = [
+    "peekapi.middleware.django.PeekApiMiddleware",
+    # ... other middleware
+]
+```
+
+### Standalone Client
+
+```python
+from peekapi import PeekApiClient
+
+client = PeekApiClient({"api_key": "ak_live_xxx"})
+
+client.track({
+    "method": "GET",
+    "path": "/api/users",
+    "status_code": 200,
+    "response_time_ms": 42,
+})
+
+# Graceful shutdown (flushes remaining events)
+client.shutdown()
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | required | Your PeekAPI key |
+| `endpoint` | PeekAPI cloud | Ingestion endpoint URL |
+| `flush_interval` | `10.0` | Seconds between automatic flushes |
+| `batch_size` | `100` | Events per HTTP POST (triggers flush) |
+| `max_buffer_size` | `10000` | Max events held in memory |
+| `max_storage_bytes` | `5242880` | Max disk fallback file size (5MB) |
+| `max_event_bytes` | `65536` | Per-event size limit (64KB) |
+| `storage_path` | auto | Custom path for JSONL persistence file |
+| `debug` | `False` | Enable debug logging |
+| `on_error` | `None` | Callback `(Exception) -> None` for flush errors |
+
+## How It Works
+
+1. Middleware intercepts every request/response
+2. Captures method, path, status code, response time, request/response sizes, consumer ID
+3. Events are buffered in memory and flushed in batches on a daemon thread
+4. On network failure: exponential backoff with jitter, up to 5 retries
+5. After max retries: events are persisted to a JSONL file on disk
+6. On next startup: persisted events are recovered and re-sent
+7. On SIGTERM/SIGINT: remaining buffer is flushed or persisted to disk
+
+## Consumer Identification
+
+By default, consumers are identified by:
+
+1. `X-API-Key` header — stored as-is
+2. `Authorization` header — hashed with SHA-256 (stored as `hash_<hex>`)
+
+Override with the `identify_consumer` option to use any header or request property:
+
+```python
+client = PeekApiClient({
+    "api_key": "...",
+    "identify_consumer": lambda headers: headers.get("x-tenant-id"),
+})
+```
+
+The callback receives a `dict[str, str]` of lowercase header names and should return a consumer ID string or `None`.
+
+## Features
+
+- **Zero runtime dependencies** — uses only Python stdlib
+- **Background flush** — daemon thread with configurable interval and batch size
+- **Disk persistence** — undelivered events saved to JSONL, recovered on restart
+- **Exponential backoff** — with jitter, max 5 consecutive failures before disk fallback
+- **SSRF protection** — private IP blocking, HTTPS enforcement (HTTP only for localhost)
+- **Input sanitization** — path (2048), method (16), consumer_id (256) truncation
+- **Per-event size limit** — strips metadata first, drops if still too large (default 64KB)
+- **Graceful shutdown** — signal handlers (SIGTERM/SIGINT) with disk persistence
+
+## Requirements
+
+- Python >= 3.10
+
+## Contributing
+
+1. Fork & clone the repo
+2. Install dev dependencies — `uv sync --no-install-project`
+3. Run tests — `uv run pytest -v`
+4. Lint & format — `uv run ruff check src/ tests/` / `uv run ruff format src/ tests/`
+5. Submit a PR
+
+## License
+
+MIT

peekapi-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities to **security@peekapi.dev**.
+
+Do not open a public issue. We will acknowledge your report within 48 hours and aim to release a fix within 7 days for critical issues.

peekapi-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "peekapi"
+dynamic = ["version"]
+description = "Zero-dependency Python SDK for PeekAPI"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["api", "analytics", "middleware", "dashboard"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Framework :: Django",
+  "Framework :: FastAPI",
+  "Framework :: Flask",
+]
+
+[project.urls]
+Homepage = "https://github.com/peekapi-dev/sdk-python"
+
+[tool.hatch.version]
+path = "src/peekapi/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/peekapi"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.25", "ruff>=0.11"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]

peekapi-0.1.0/src/peekapi/__init__.py

@@ -0,0 +1,17 @@
+"""PeekAPI — Python SDK."""
+
+from ._consumer import default_identify_consumer, hash_consumer_id
+from .client import PeekApiClient
+from .middleware import PeekApiASGI, PeekApiMiddleware, PeekApiWSGI
+from .types import Options, RequestEvent
+
+__all__ = [
+    "Options",
+    "PeekApiASGI",
+    "PeekApiClient",
+    "PeekApiMiddleware",
+    "PeekApiWSGI",
+    "RequestEvent",
+    "default_identify_consumer",
+    "hash_consumer_id",
+]

peekapi-0.1.0/src/peekapi/_consumer.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import hashlib
+
+
+def hash_consumer_id(raw: str) -> str:
+    """SHA-256 hash truncated to 12 hex chars, prefixed with 'hash_'."""
+    digest = hashlib.sha256(raw.encode()).hexdigest()[:12]
+    return f"hash_{digest}"
+
+
+def default_identify_consumer(headers: dict[str, str]) -> str | None:
+    """Identify consumer from request headers.
+
+    Priority:
+      1. x-api-key (stored as-is)
+      2. Authorization (hashed — contains credentials)
+    """
+    api_key = headers.get("x-api-key")
+    if api_key:
+        return api_key
+
+    auth = headers.get("authorization")
+    if auth:
+        return hash_consumer_id(auth)
+
+    return None

peekapi-0.1.0/src/peekapi/_ssrf.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import ipaddress
+import re
+from urllib.parse import urlparse
+
+# Matches private/reserved IPv4 ranges (fast path)
+_PRIVATE_IP_RE = re.compile(
+    r"^(?:"
+    r"10\.\d{1,3}\.\d{1,3}\.\d{1,3}"
+    r"|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}"
+    r"|192\.168\.\d{1,3}\.\d{1,3}"
+    r"|0\.0\.0\.0"
+    r")$"
+)
+
+# CGNAT range not covered by ipaddress.is_private in all Python versions
+_CGNAT_NETWORK = ipaddress.IPv4Network("100.64.0.0/10")
+
+
+def is_private_ip(host: str) -> bool:
+    """Check if a hostname/IP is a private or reserved address.
+
+    Covers: RFC 1918, CGNAT (100.64/10), loopback, link-local,
+    IPv6 ULA/link-local, IPv4-mapped IPv6.
+    """
+    # Fast path regex
+    if _PRIVATE_IP_RE.match(host):
+        return True
+
+    try:
+        addr = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+
+    if isinstance(addr, ipaddress.IPv6Address):
+        # Check IPv4-mapped IPv6 (::ffff:x.x.x.x)
+        mapped = addr.ipv4_mapped
+        if mapped is not None:
+            return mapped.is_private or mapped.is_loopback or mapped.is_link_local
+        return addr.is_private or addr.is_loopback or addr.is_link_local
+
+    # IPv4 — is_private covers RFC 1918 + loopback + link-local; add CGNAT explicitly
+    return addr.is_private or addr.is_loopback or addr.is_link_local or addr in _CGNAT_NETWORK
+
+
+def validate_endpoint(endpoint: str) -> str:
+    """Validate and normalize the ingestion endpoint URL.
+
+    Raises ValueError for:
+      - Non-HTTPS URLs (except localhost)
+      - Private/reserved IP addresses (SSRF protection)
+      - Embedded credentials in URL
+      - Malformed URLs
+    """
+    if not endpoint:
+        raise ValueError("endpoint is required")
+
+    parsed = urlparse(endpoint)
+
+    if not parsed.scheme or not parsed.hostname:
+        raise ValueError(f"Invalid endpoint URL: {endpoint}")
+
+    hostname = parsed.hostname.lower()
+
+    # Allow HTTP only for localhost
+    is_localhost = hostname in ("localhost", "127.0.0.1", "::1")
+
+    if parsed.scheme != "https" and not is_localhost:
+        raise ValueError(f"HTTPS required for non-localhost endpoint: {endpoint}")
+
+    # Reject embedded credentials
+    if parsed.username or parsed.password:
+        raise ValueError("Endpoint URL must not contain credentials")
+
+    # SSRF check — skip for localhost
+    if not is_localhost and is_private_ip(hostname):
+        raise ValueError(f"Endpoint resolves to private/reserved IP: {hostname}")
+
+    return endpoint

peekapi-0.1.0/src/peekapi/_version.py

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