tapcub 0.1.0__py3-none-any.whl

tapcub/__init__.py

@@ -0,0 +1,12 @@
+"""TapCub server-side SDK for Python: events, sign-ups, identities, user profiles, items and accounts.
+
+    from tapcub import TapCub
+    tc = TapCub("wck_…")
+    tc.track("purchase", login_id="user-1", insert_id="order-1", properties={"revenue": 19.9})
+    tc.close()
+"""
+from .client import DEFAULT_ENDPOINT, TapCub, TapCubError, from_request_headers, normalize_endpoint
+from .version import VERSION
+
+__version__ = VERSION
+__all__ = ["TapCub", "TapCubError", "from_request_headers", "normalize_endpoint", "DEFAULT_ENDPOINT", "VERSION", "__version__"]

tapcub/_normalize.py

@@ -0,0 +1,254 @@
+"""Event normalization shared by every TapCub server SDK.
+
+Rules: packages/shared/test-vectors/track/README.md (same limits as the server's request schema).
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+import json
+import math
+import re
+import time as _time
+from typing import Any, Dict, List, Mapping, Optional
+
+LOGIN_ID_TYPES = ("login", "email", "mobile", "unionid", "openid", "custom")
+PLATFORMS = (
+    "web", "mp_weixin", "mp_alipay", "mp_bytedance", "mp_baidu", "mp_kuaishou", "mp_qq",
+    "android", "ios", "harmony", "tvos", "watchos", "macos", "windows", "linux", "server", "import",
+)
+_GROUP_KEY_RE = re.compile(r"^[a-z][a-z0-9_]{0,23}:[A-Za-z0-9_@.\-]{1,80}$")
+_GROUP_TYPE_RE = re.compile(r"^[a-z][a-z0-9_]{0,23}$")
+_HEX64 = re.compile(r"^[a-fA-F0-9]{64}$")
+_COUNTRY = re.compile(r"^[A-Za-z]{2}$")
+_CAMPAIGN_LIMITS = (
+    ("source", 100), ("medium", 100), ("name", 100), ("term", 100), ("content", 100),
+    ("ref", 64), ("click_id", 1000), ("landing_url", 2000), ("referrer", 2000),
+)
+
+
+def sha256(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def utf16_len(s: str) -> int:
+    """服务端 zod 的 max 按 JS .length（UTF-16 码元）计"""
+    return len(s) + sum(1 for ch in s if ord(ch) > 0xFFFF)
+
+
+def cut(s: str, n: int) -> str:
+    """截到 ≤n 个 UTF-16 码元，不拆开代理对"""
+    if len(s) <= n // 2 or utf16_len(s) <= n:
+        return s
+    units = 0
+    for i, ch in enumerate(s):
+        units += 2 if ord(ch) > 0xFFFF else 1
+        if units > n:
+            return s[:i]
+    return s
+
+
+def _text(v: Any) -> str:
+    return v if isinstance(v, str) else str(v)
+
+
+def require_text(name: str, v: Any, max_len: Optional[int] = None) -> str:
+    s = _text(v).strip() if v is not None else ""
+    if not s:
+        raise ValueError(f"TapCub: {name} is required")
+    if max_len is not None and utf16_len(s) > max_len:
+        raise ValueError(f"TapCub: {name} must be at most {max_len} characters")
+    return s
+
+
+def optional_text(name: str, v: Any, max_len: int) -> Optional[str]:
+    if v is None:
+        return None
+    s = _text(v).strip()
+    if not s:
+        return None
+    if utf16_len(s) > max_len:
+        raise ValueError(f"TapCub: {name} must be at most {max_len} characters")
+    return s
+
+
+def event_name(v: Any) -> str:
+    s = _text(v).strip() if v is not None else ""
+    if not s:
+        raise ValueError("TapCub: event is required")
+    return cut(s, 100)
+
+
+def login_id_type(v: Any) -> Optional[str]:
+    if v is None:
+        return None
+    if v not in LOGIN_ID_TYPES:
+        raise ValueError(f"TapCub: login_id_type must be one of {', '.join(LOGIN_ID_TYPES)}")
+    return v
+
+
+def identity_value(kind: str, value: Any) -> str:
+    v = _text(value).strip() if value is not None else ""
+    if kind in ("email", "mobile"):
+        n = v.lower() if kind == "email" else re.sub(r"[\s-]", "", v)
+        return n.lower() if _HEX64.match(n) else sha256(n)
+    return v
+
+
+def identities(v: Optional[Mapping[str, Any]]) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for k, raw in (v or {}).items():
+        if k not in LOGIN_ID_TYPES:
+            raise ValueError(f'TapCub: unknown identity type "{k}"')
+        if raw is None or _text(raw).strip() == "":
+            continue
+        out[k] = identity_value(k, raw)
+    return out
+
+
+def group(v: Any) -> Optional[str]:
+    if v is None:
+        return None
+    s = _text(v)
+    if not _GROUP_KEY_RE.match(s):
+        raise ValueError('TapCub: group must look like "type:id" (type: a-z, 0-9, _)')
+    return s
+
+
+def group_key(kind: Any, gid: Any) -> str:
+    t = require_text("group_type", kind)
+    if not _GROUP_TYPE_RE.match(t):
+        raise ValueError("TapCub: group_type must start with a-z and contain only a-z, 0-9 and _ (at most 24)")
+    return group(f"{t}:{require_text('group_id', gid)}")  # type: ignore[return-value]
+
+
+def timestamp(v: Any) -> int:
+    """毫秒时间戳；datetime 按自身时区（naive 视为本地时间，同 datetime.timestamp()）"""
+    if v is None:
+        return int(_time.time() * 1000)
+    if isinstance(v, _dt.datetime):
+        return int(v.timestamp() * 1000)
+    if isinstance(v, bool) or not isinstance(v, (int, float)) or (isinstance(v, float) and not math.isfinite(v)):
+        raise ValueError("TapCub: time must be milliseconds since the epoch or a datetime")
+    return int(v)
+
+
+def _json_text(v: Any) -> str:
+    return json.dumps(v, separators=(",", ":"), ensure_ascii=False, default=_json_default)
+
+
+def _json_default(o: Any) -> Any:
+    if isinstance(o, (_dt.datetime, _dt.date)):
+        return o.isoformat()
+    if isinstance(o, (set, frozenset, tuple)):
+        return list(o)
+    return str(o)
+
+
+def _scalar(v: Any) -> Any:
+    """返回 None 表示丢弃"""
+    if v is None:
+        return None
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, int):
+        return v
+    if isinstance(v, float):
+        return v if math.isfinite(v) else None
+    if isinstance(v, str):
+        return cut(v, 1000)
+    if isinstance(v, (_dt.datetime, _dt.date)):
+        return v.isoformat()
+    if isinstance(v, (Mapping, list, tuple, set, frozenset)):
+        return cut(_json_text(v), 1000)
+    return cut(str(v), 1000)
+
+
+def properties(p: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    if not p:
+        return None
+    out: Dict[str, Any] = {}
+    for k, v in p.items():
+        key = cut(_text(k), 50)
+        if isinstance(v, (list, tuple)) and v and all(isinstance(x, Mapping) for x in v):
+            rows = []
+            for o in list(v)[:100]:
+                row = {}
+                for ik, iv in o.items():
+                    s = _scalar(iv)
+                    if s is not None:
+                        row[cut(_text(ik), 50)] = s
+                rows.append(row)
+            out[key] = rows
+            continue
+        s = _scalar(v)
+        if s is not None:
+            out[key] = s
+    return out or None
+
+
+def increment(p: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    for k, v in (p or {}).items():
+        if isinstance(v, bool) or not isinstance(v, (int, float)):
+            continue
+        if isinstance(v, float) and not math.isfinite(v):
+            continue
+        out[cut(_text(k), 50)] = v
+    return out
+
+
+def append(p: Optional[Mapping[str, Any]]) -> Dict[str, List[Any]]:
+    out: Dict[str, List[Any]] = {}
+    for k, v in (p or {}).items():
+        items = list(v) if isinstance(v, (list, tuple)) else [v]
+        keep = [x for x in items if isinstance(x, (str, bool)) or (isinstance(x, (int, float)) and math.isfinite(x))]
+        if keep:
+            out[cut(_text(k), 50)] = keep[:20]
+    return out
+
+
+def unset_keys(keys: Any) -> List[str]:
+    if isinstance(keys, (str, bytes)) or not isinstance(keys, (list, tuple)):
+        raise ValueError("TapCub: keys must be a list of property names")
+    return [cut(_text(k), 50) for k in keys if k is not None and _text(k) != ""][:50]
+
+
+def campaign(c: Any) -> Optional[Dict[str, Any]]:
+    if not isinstance(c, Mapping):
+        return None
+    out: Dict[str, Any] = {}
+    for k, lim in _CAMPAIGN_LIMITS:
+        v = c.get(k)
+        if v is not None and _text(v) != "":
+            out[k] = cut(_text(v), lim)
+    t = c.get("touched_at")
+    if not isinstance(t, bool) and isinstance(t, (int, float)) and math.isfinite(t):
+        out["touched_at"] = int(t)
+    return out or None
+
+
+def context(c: Any) -> Optional[Dict[str, Any]]:
+    if not isinstance(c, Mapping):
+        return None
+    out: Dict[str, Any] = {}
+    for k, lim in (("ip", 45), ("user_agent", 1000), ("url", 2000)):
+        v = c.get(k)
+        if v is not None and _text(v) != "":
+            out[k] = cut(_text(v), lim)
+    if c.get("platform") in PLATFORMS:
+        out["platform"] = c["platform"]
+    country = c.get("country")
+    if isinstance(country, str) and _COUNTRY.match(country):
+        out["country"] = country.upper()
+    lang = c.get("lang")
+    if lang is not None and _text(lang) != "":
+        out["lang"] = cut(_text(lang), 12)
+    camp = campaign(c.get("campaign"))
+    if camp:
+        out["campaign"] = camp
+    return out or None
+
+
+def compact(ev: Mapping[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in ev.items() if v is not None}

tapcub/client.py

@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+import atexit
+import gzip as _gzip
+import json
+import logging
+import random
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+import weakref
+from collections import deque
+from typing import Any, Callable, Deque, Dict, List, Mapping, Optional, Tuple
+
+from . import _normalize as n
+from .version import VERSION
+
+DEFAULT_ENDPOINT = "https://api.pathclue.com"
+MAX_BODY_BYTES = 1_000_000
+_log = logging.getLogger("tapcub")
+
+
+class TapCubError(Exception):
+    """A batch that could not be delivered, or events the server rejected.
+
+    code: server code (``NO_API_KEY``, ``BAD_API_KEY``, ``VALIDATION`` …), ``HTTP_<status>``, ``NETWORK``,
+    ``EVENT_REJECTED`` or ``QUEUE_FULL``. ``events`` are the events that were not stored.
+    """
+
+    def __init__(self, message: str, code: str, status: Optional[int] = None, events: Optional[List[dict]] = None, results: Optional[List[dict]] = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.events = events or []
+        self.results = results
+        self.retry_after: Optional[float] = None
+
+
+def normalize_endpoint(endpoint: Optional[str]) -> str:
+    e = (endpoint or DEFAULT_ENDPOINT).strip().rstrip("/")
+    e = re.sub(r"/api/v1(/track)?$", "", e)
+    if not re.match(r"^https?://", e):
+        raise ValueError("TapCub: endpoint must start with http:// or https://")
+    return e
+
+
+def from_request_headers(headers: Mapping[str, Any]) -> Dict[str, Optional[str]]:
+    """Read the device and session IDs a TapCub client put on a request to your backend
+    (``X-Tc-Device`` / ``X-Tc-Session``). Works with Django / Flask / Starlette ``request.headers``,
+    a WSGI ``environ`` or a plain dict. Returns ``{"device_id": …, "session_id": …}``."""
+
+    def get(name: str) -> Optional[str]:
+        v = None
+        if hasattr(headers, "get"):
+            v = headers.get(name) or headers.get(name.lower()) or headers.get("HTTP_" + name.upper().replace("-", "_"))
+        if isinstance(v, (list, tuple)):
+            v = v[0] if v else None
+        return v.strip() or None if isinstance(v, str) else None
+
+    return {"device_id": get("X-Tc-Device"), "session_id": get("X-Tc-Session")}
+
+
+class TapCub:
+    """TapCub server-side client.
+
+    consumer:
+      ``"batch"`` (default) queue in memory and send from a background thread every ``flush_interval`` seconds or
+      when ``max_batch`` events are queued; flushed again when the interpreter exits.
+      ``"sync"`` send on every call and raise ``TapCubError`` on failure.
+      ``"debug"`` like ``sync``, against ``?debug=1`` (validated, nothing stored), every result is logged.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: Optional[str] = None,
+        *,
+        consumer: str = "batch",
+        max_batch: int = 200,
+        flush_interval: float = 3.0,
+        max_queue_size: int = 10_000,
+        max_retries: int = 5,
+        timeout: float = 10.0,
+        gzip: bool = False,
+        on_error: Optional[Callable[[TapCubError], None]] = None,
+        logger: Optional[logging.Logger] = None,
+        _retry_base: float = 0.5,
+    ):
+        if not api_key or not str(api_key).strip():
+            raise ValueError("TapCub: api_key is required")
+        if consumer not in ("batch", "sync", "debug"):
+            raise ValueError("TapCub: consumer must be batch, sync or debug")
+        self.api_key = str(api_key).strip()
+        self.endpoint = normalize_endpoint(endpoint)
+        self.consumer = consumer
+        self.max_batch = max(1, min(1000, int(max_batch)))
+        self.max_queue_size = max(1, int(max_queue_size))
+        self.max_retries = max(0, int(max_retries))
+        self.timeout = timeout
+        self.gzip = bool(gzip)
+        self.logger = logger or _log
+        self.on_error = on_error or (lambda e: self.logger.error("[tapcub] %s", e))
+        self._retry_base = _retry_base
+        self._queue: Deque[Tuple[dict, int]] = deque()
+        self._dropped = 0
+        self._lock = threading.Lock()
+        self._send_lock = threading.Lock()
+        self._wake = threading.Event()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._flush_interval = max(0.01, float(flush_interval))
+        if consumer == "batch":
+            self._thread = threading.Thread(target=self._run, name="tapcub-sender", daemon=True)
+            self._thread.start()
+            ref = weakref.ref(self)
+            self._atexit = lambda: ref() and ref()._shutdown()  # type: ignore[union-attr]
+            atexit.register(self._atexit)
+
+    # ---------------- events ----------------
+
+    def track(
+        self,
+        event: str,
+        *,
+        login_id: Optional[str] = None,
+        login_id_type: Optional[str] = None,
+        device_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        insert_id: Optional[str] = None,
+        time: Any = None,
+        group: Optional[str] = None,
+        properties: Optional[Mapping[str, Any]] = None,
+        context: Optional[Mapping[str, Any]] = None,
+    ) -> Optional[dict]:
+        """A business event. ``insert_id`` (≤36) is the idempotency key; it is not generated for you."""
+        kind = n.login_id_type(login_id_type)
+        raw = n.optional_text("login_id", login_id, 200)
+        return self._enqueue({
+            "type": "track",
+            "event": n.event_name(event),
+            "login_id": n.identity_value(kind, raw) if raw and kind in ("email", "mobile") else raw,
+            "login_id_type": kind,
+            "device_id": n.optional_text("device_id", device_id, 72),
+            "session_id": n.optional_text("session_id", session_id, 32),
+            "insert_id": n.optional_text("insert_id", insert_id, 36),
+            "time": n.timestamp(time),
+            "group": n.group(group),
+            "properties": n.properties(properties),
+            "context": n.context(context),
+        })
+
+    def track_signup(
+        self,
+        login_id: str,
+        *,
+        device_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        insert_id: Optional[str] = None,
+        time: Any = None,
+        properties: Optional[Mapping[str, Any]] = None,
+        invited_by: Optional[str] = None,
+        context: Optional[Mapping[str, Any]] = None,
+    ) -> Optional[dict]:
+        """Sign-up: links the anonymous device (if any) to the new login ID and records ``sign_up``.
+        ``invited_by`` is the inviter's login ID (sent as ``properties.$invited_by``)."""
+        props = dict(properties or {})
+        if invited_by is not None and str(invited_by).strip():
+            props["$invited_by"] = str(invited_by).strip()
+        return self._enqueue({
+            "type": "track_signup",
+            "event": "sign_up",
+            "login_id": n.require_text("login_id", login_id, 200),
+            "device_id": n.optional_text("device_id", device_id, 72),
+            "session_id": n.optional_text("session_id", session_id, 32),
+            "insert_id": n.optional_text("insert_id", insert_id, 36),
+            "time": n.timestamp(time),
+            "properties": n.properties(props),
+            "context": n.context(context),
+        })
+
+    def track_update(self, event: str, insert_id: str, properties: Mapping[str, Any]) -> Optional[dict]:
+        """Merge properties into the stored event with this ``insert_id``."""
+        return self._enqueue({"type": "track_update", "event": n.event_name(event), "insert_id": n.require_text("insert_id", insert_id, 36), "time": n.timestamp(None), "properties": n.properties(properties)})
+
+    def track_overwrite(self, event: str, insert_id: str, properties: Mapping[str, Any]) -> Optional[dict]:
+        """Replace the properties of the stored event with this ``insert_id``."""
+        return self._enqueue({"type": "track_overwrite", "event": n.event_name(event), "insert_id": n.require_text("insert_id", insert_id, 36), "time": n.timestamp(None), "properties": n.properties(properties)})
+
+    # ---------------- identity ----------------
+
+    def bind(self, login_id: str, identities: Mapping[str, str]) -> Optional[dict]:
+        """Attach more identities (``email``, ``mobile``, ``unionid``, ``openid``, ``custom``). Email and mobile are SHA-256 hashed first."""
+        return self._enqueue({"type": "bind", "login_id": n.require_text("login_id", login_id, 200), "time": n.timestamp(None), "identities": n.identities(identities)})
+
+    def unbind(self, login_id: str, identity_type: str, value: str) -> Optional[dict]:
+        """Remove one identity from the user."""
+        return self._enqueue({"type": "unbind", "login_id": n.require_text("login_id", login_id, 200), "time": n.timestamp(None), "identities": n.identities({identity_type: n.require_text("value", value)})})
+
+    # ---------------- profiles ----------------
+
+    def profile_set(self, login_id: str, properties: Mapping[str, Any]) -> Optional[dict]:
+        return self._profile("profile_set", login_id, properties=n.properties(properties))
+
+    def profile_set_once(self, login_id: str, properties: Mapping[str, Any]) -> Optional[dict]:
+        """Set only the properties that are not set yet."""
+        return self._profile("profile_set_once", login_id, properties=n.properties(properties))
+
+    def profile_increment(self, login_id: str, increment: Mapping[str, Any]) -> Optional[dict]:
+        return self._profile("profile_increment", login_id, increment=n.increment(increment))
+
+    def profile_append(self, login_id: str, append: Mapping[str, Any]) -> Optional[dict]:
+        return self._profile("profile_append", login_id, append=n.append(append))
+
+    def profile_unset(self, login_id: str, keys: List[str]) -> Optional[dict]:
+        return self._profile("profile_unset", login_id, unset=n.unset_keys(keys))
+
+    # ---------------- items / accounts ----------------
+
+    def item_set(self, item_type: str, item_id: str, properties: Mapping[str, Any]) -> Optional[dict]:
+        """Upsert a dimension row (product, article, store …)."""
+        return self._enqueue({"type": "item_set", "item_type": n.require_text("item_type", item_type, 40), "item_id": n.require_text("item_id", item_id, 80), "time": n.timestamp(None), "properties": n.properties(properties)})
+
+    def item_delete(self, item_type: str, item_id: str) -> Optional[dict]:
+        return self._enqueue({"type": "item_delete", "item_type": n.require_text("item_type", item_type, 40), "item_id": n.require_text("item_id", item_id, 80), "time": n.timestamp(None)})
+
+    def group_set(self, group_type: str, group_id: str, properties: Mapping[str, Any]) -> Optional[dict]:
+        """Set account (group) traits for ``group_type:group_id``."""
+        return self._enqueue({"type": "group_set", "group": n.group_key(group_type, group_id), "time": n.timestamp(None), "properties": n.properties(properties)})
+
+    # ---------------- sending ----------------
+
+    def flush(self) -> None:
+        """Send everything queued now. Raises the first ``TapCubError`` if a batch could not be delivered."""
+        errors = self._drain()
+        if errors:
+            raise errors[0]
+
+    def close(self) -> None:
+        """Stop the background thread and send what is queued (raises like ``flush``)."""
+        self._stop.set()
+        self._wake.set()
+        if self._thread and self._thread is not threading.current_thread():
+            self._thread.join(timeout=self.timeout * (self.max_retries + 1) + 5)
+        if getattr(self, "_atexit", None):
+            atexit.unregister(self._atexit)
+            self._atexit = None
+        self.flush()
+
+    def __enter__(self) -> "TapCub":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    @property
+    def queued(self) -> int:
+        return len(self._queue)
+
+    def _profile(self, kind: str, login_id: str, **body: Any) -> Optional[dict]:
+        return self._enqueue({"type": kind, "login_id": n.require_text("login_id", login_id, 200), "time": n.timestamp(None), **body})
+
+    def _enqueue(self, raw: Mapping[str, Any]) -> Optional[dict]:
+        ev = n.compact(raw)
+        if self.consumer != "batch":
+            return self._send([ev], self.consumer == "debug")
+        size = len(json.dumps(ev, separators=(",", ":"), ensure_ascii=False).encode("utf-8")) + 1
+        with self._lock:
+            self._queue.append((ev, size))
+            over = len(self._queue) - self.max_queue_size
+            for _ in range(max(0, over)):
+                self._queue.popleft()
+                self._dropped += 1
+            full = len(self._queue) >= self.max_batch
+        if full:
+            self._wake.set()
+        return None
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self._wake.wait(self._flush_interval)
+            self._wake.clear()
+            if self._stop.is_set():
+                break
+            for e in self._drain():
+                self._report(e)
+
+    def _shutdown(self) -> None:
+        try:
+            self.close()
+        except TapCubError as e:
+            self._report(e)
+
+    def _report(self, err: TapCubError) -> None:
+        try:
+            self.on_error(err)
+        except Exception:  # noqa: BLE001
+            self.logger.exception("[tapcub] on_error raised")
+
+    def _take(self) -> List[dict]:
+        with self._lock:
+            batch: List[dict] = []
+            size = 0
+            while self._queue and len(batch) < self.max_batch:
+                ev, b = self._queue[0]
+                if batch and size + b > MAX_BODY_BYTES:
+                    break
+                self._queue.popleft()
+                batch.append(ev)
+                size += b
+            return batch
+
+    def _drain(self) -> List[TapCubError]:
+        errors: List[TapCubError] = []
+        with self._send_lock:
+            with self._lock:
+                dropped, self._dropped = self._dropped, 0
+            if dropped:
+                errors.append(TapCubError(f"TapCub: queue full, dropped {dropped} oldest event(s)", "QUEUE_FULL"))
+            while True:
+                batch = self._take()
+                if not batch:
+                    break
+                try:
+                    self._send(batch, False)
+                except TapCubError as e:
+                    errors.append(e)
+        return errors
+
+    def _post(self, url: str, body: bytes, headers: Dict[str, str]) -> Tuple[int, Dict[str, str], bytes]:
+        """One HTTP request. Returns (status, headers, body); raises OSError on network errors."""
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:  # noqa: S310 (endpoint is configured by the caller)
+                return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read()
+        except urllib.error.HTTPError as e:
+            return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, e.read() or b""
+
+    def _send(self, events: List[dict], debug: bool) -> dict:
+        url = f"{self.endpoint}/api/v1/track" + ("?debug=1" if debug else "")
+        body = json.dumps({"events": events}, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        headers = {"Content-Type": "application/json", "Authorization": f"Bearer {self.api_key}", "User-Agent": f"tapcub-python/{VERSION}"}
+        if self.gzip:
+            body = _gzip.compress(body)
+            headers["Content-Encoding"] = "gzip"
+        last: Optional[TapCubError] = None
+        for attempt in range(self.max_retries + 1):
+            if attempt:
+                time.sleep(self._backoff(attempt, last))
+            try:
+                status, res_headers, raw = self._post(url, body, headers)
+            except (OSError, ValueError) as e:
+                last = TapCubError(f"TapCub: request failed: {e}", "NETWORK", events=events)
+                continue
+            try:
+                data = json.loads(raw.decode("utf-8")) if raw else {}
+            except ValueError:
+                data = {}
+            if not isinstance(data, dict):
+                data = {}
+            if 200 <= status < 300:
+                results = data.get("results") or []
+                if debug:
+                    for r in results:
+                        w = r.get("warnings") or []
+                        self.logger.warning("[tapcub] debug #%s %s%s", r.get("index"), "ok" if r.get("ok") else "rejected", f" warnings={','.join(w)}" if w else "")
+                bad = [r for r in results if not r.get("ok")]
+                if bad:
+                    raise TapCubError(
+                        "TapCub: %d event(s) rejected: %s" % (len(bad), "; ".join(f"#{r.get('index')} {','.join(r.get('warnings') or []) or 'rejected'}" for r in bad)),
+                        "EVENT_REJECTED", status, [events[r["index"]] for r in bad if isinstance(r.get("index"), int) and r["index"] < len(events)], bad,
+                    )
+                data.setdefault("results", [])
+                return data
+            code = data.get("code") if isinstance(data.get("code"), str) else f"HTTP_{status}"
+            msg = data.get("message") if isinstance(data.get("message"), str) else raw[:200].decode("utf-8", "replace")
+            issues = data.get("issues")
+            detail = f" ({'; '.join(str(i) for i in issues[:3])})" if isinstance(issues, list) and issues else ""
+            last = TapCubError(f"TapCub: HTTP {status} {code}: {msg}{detail}", code, status, events)
+            try:
+                last.retry_after = float(res_headers.get("retry-after", "") or 0) or None
+            except ValueError:
+                last.retry_after = None
+            if status != 429 and status < 500:
+                raise last
+        assert last is not None
+        raise last
+
+    def _backoff(self, attempt: int, last: Optional[TapCubError]) -> float:
+        if last is not None and last.retry_after:
+            return min(60.0, last.retry_after)
+        base = min(30.0, self._retry_base * 2 ** (attempt - 1))
+        return base / 2 + random.random() * base / 2

tapcub/version.py

@@ -0,0 +1,2 @@
+# 与 pyproject.toml 的 version 一致（tests/test_client.py 核对）
+VERSION = "0.1.0"

tapcub-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: tapcub
+Version: 0.1.0
+Summary: TapCub server-side SDK for Python: events, sign-ups, identities, user profiles, items and accounts
+Author-email: TapCub <hello@tapcub.com>
+License-Expression: MIT
+Project-URL: Homepage, https://tapcub.com
+Project-URL: Documentation, https://docs.tapcub.com/en/sdk/server#python
+Project-URL: Source, https://github.com/tapcub/tapcub-sdk/tree/main/packages/sdk-server/python
+Project-URL: Issues, https://github.com/tapcub/tapcub-sdk/issues
+Project-URL: Changelog, https://github.com/tapcub/tapcub-sdk/blob/main/packages/sdk-server/python/CHANGELOG.md
+Keywords: tapcub,analytics,server-side,events,tracking,product-analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tapcub
+
+Server-side SDK for [TapCub](https://tapcub.com) on Python: business events, sign-ups, identities, user profiles, items and accounts, sent to `POST /api/v1/track`. Standard library only, typed (`py.typed`).
+
+- Batches in memory and sends from a background thread (or sends on every call)
+- Retries network errors, 5xx and 429 with exponential backoff, without changing the batch
+- Cleans each event before it is queued, so one bad value never rejects a whole batch
+- Hashes email and mobile identities (SHA-256) before they leave your server
+
+Requires Python 3.8 or newer.
+
+## Install
+
+```bash
+pip install tapcub
+```
+
+## Quick start
+
+```python
+import os
+from tapcub import TapCub
+
+tc = TapCub(os.environ["TAPCUB_API_KEY"])  # a wck_… key with the track:write scope
+
+tc.track(
+    "purchase",
+    login_id=user.id,
+    insert_id=order.id,  # idempotency key: retries of the same order are counted once
+    properties={"revenue": 99, "currency": "USD", "items": [{"item_id": "sku-1", "price": 99, "quantity": 1}]},
+)
+
+tc.close()  # also runs automatically when the interpreter exits
+```
+
+Create the key in the TapCub console under **Configuration › Settings › API keys** with the **Server track** scope. It is shown once; keep it on the server.
+
+## Configuration
+
+`TapCub(api_key, endpoint=None, *, …)`
+
+| Argument | Default | Description |
+|---|---|---|
+| `api_key` | — | Required. Project key with the `track:write` (Server track) scope |
+| `endpoint` | built in | Leave unset. Set it only when TapCub gives you a dedicated address (private deployment). A trailing `/api/v1/track` is removed |
+| `consumer` | `"batch"` | `"batch"`: queue and send from a daemon thread. `"sync"`: send on every call and raise `TapCubError` on failure (calls return the server response). `"debug"`: like `"sync"` against `?debug=1` (validated, nothing stored), every result is logged |
+| `max_batch` | `200` | Events per request (at most 1000). Requests are also kept under 1 MB |
+| `flush_interval` | `3.0` | Seconds between sends |
+| `max_queue_size` | `10000` | Queued events kept in memory; the oldest are dropped beyond this |
+| `max_retries` | `5` | Retries for network errors, 5xx and 429 (honours `Retry-After`) |
+| `timeout` | `10.0` | Seconds per request |
+| `gzip` | `False` | Send `Content-Encoding: gzip` |
+| `on_error` | log to the `tapcub` logger | Called with a `TapCubError` for every background failure |
+| `logger` | `logging.getLogger("tapcub")` | |
+
+## API
+
+Invalid arguments raise `ValueError` and queue nothing. The client is thread-safe; create one per process.
+
+| Method | Event |
+|---|---|
+| `track(event, *, login_id=None, login_id_type=None, device_id=None, session_id=None, insert_id=None, time=None, group=None, properties=None, context=None)` | A business event |
+| `track_signup(login_id, *, device_id=None, invited_by=None, properties=None, context=None, …)` | `sign_up`; links the anonymous device to the new login ID |
+| `bind(login_id, {"email": …, "mobile": …, "unionid": …})` | Attach more identities (email / mobile hashed in the SDK) |
+| `unbind(login_id, identity_type, value)` | Remove one identity |
+| `profile_set(login_id, props)` / `profile_set_once(login_id, props)` | Set profile properties (`$name`, `$email`, `$phone`, `$avatar` are display fields) |
+| `profile_increment(login_id, {key: delta})` / `profile_append(login_id, {key: [values]})` / `profile_unset(login_id, [keys])` | Change profile properties |
+| `item_set(item_type, item_id, props)` / `item_delete(item_type, item_id)` | Dimension rows (products, articles, stores) |
+| `track_update(event, insert_id, props)` / `track_overwrite(event, insert_id, props)` | Merge into / replace the properties of a stored event |
+| `group_set(group_type, group_id, props)` | Account (B2B group) traits; attach events with `track(…, group="company:acme")` |
+| `flush()` | Send the queue now; raises the first `TapCubError` |
+| `close()` | Stop the thread and `flush()`; `with TapCub(…) as tc:` does this for you |
+| `from_request_headers(headers)` | `{"device_id", "session_id"}` from `X-Tc-Device` / `X-Tc-Session` (Django, Flask, Starlette, WSGI environ) |
+
+`time` is milliseconds since the epoch or a `datetime` and defaults to the time of the call. Properties are flat: strings (cut to 1000 characters), numbers and booleans; dates become ISO-8601 strings; a list of dicts such as `items` is kept one level deep; other nested values are sent as JSON strings.
+
+### Record where a sign-up came from
+
+The browser script already knows the visit source (`tapcub.getAttribution()`). Send it to your backend with the sign-up form and pass it through unchanged:
+
+```python
+# Django view
+def signup(request):
+    data = json.loads(request.body)
+    user = create_user(data)
+    tc.track_signup(
+        user.id,
+        device_id=data.get("tapcubDeviceId"),   # optional: links the anonymous visits
+        invited_by=data.get("inviterId"),       # optional: referral program → properties.$invited_by
+        context={
+            "campaign": data.get("attribution"),  # {source, medium, name, term, content, ref, click_id, landing_url, referrer, touched_at}
+            "ip": request.META.get("REMOTE_ADDR"),  # ip + user_agent let TapCub infer the source when there is no cookie
+            "user_agent": request.headers.get("User-Agent"),
+        },
+    )
+    return JsonResponse({"ok": True})
+```
+
+## Idempotency
+
+The SDK resends a failed batch unchanged, but it does **not** generate `insert_id` for you. Pass a natural key (order ID, payment ID, ≤36 characters) for events that must not be counted twice; the server stores one event per `insert_id`.
+
+## Errors
+
+```python
+from tapcub import TapCub, TapCubError
+
+def report(err: TapCubError) -> None:
+    log.warning("tapcub %s (%s): %d events lost", err.code, err.status, len(err.events))
+
+tc = TapCub(api_key, on_error=report)
+```
+
+`err.code` is the server code (`NO_API_KEY`, `BAD_API_KEY`, `VALIDATION`, …), `HTTP_<status>`, `NETWORK`, `EVENT_REJECTED` (the request succeeded but some events were rejected; see `err.results`) or `QUEUE_FULL`. 4xx responses other than 429 are not retried.
+
+## Short-lived processes and workers
+
+Scripts, Lambda handlers and Celery tasks should call `tc.flush()` before returning, or use `consumer="sync"`. With forking servers (gunicorn `--preload`, uWSGI) create the client after the fork, because the sender thread does not survive it.
+
+## Check your integration
+
+```python
+TapCub(api_key, consumer="debug").track("purchase", login_id="u1", properties={"revenue": 1})
+# logs "debug #0 ok" (or the warnings) and stores nothing
+```
+
+## Documentation
+
+[docs.tapcub.com → Server SDKs](https://docs.tapcub.com/en/sdk/server#python). Behaviour shared by every TapCub server SDK is specified by the conformance vectors in [`packages/shared/test-vectors/track`](https://github.com/tapcub/tapcub-sdk/tree/main/packages/shared/test-vectors/track).
+
+## License
+
+MIT

tapcub-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tapcub/__init__.py,sha256=TXJjsc9XvslAewXdiJkML7JcDWgJsSp2Nux3bml1vSo,555
+tapcub/_normalize.py,sha256=gJUjfhNYwzW_qUMLxpo5EkwPvNRqHi7VINdf0RH4rGU,8313
+tapcub/client.py,sha256=kaGF5MRw2tk-UdTq7EoAqgMX2R74WkNwufqrUedCJkI,18176
+tapcub/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tapcub/version.py,sha256=7A1L6aMdetMdBEyE0CrEW421HDdf4mSPmJ6Nf2hC0lc,91
+tapcub-0.1.0.dist-info/licenses/LICENSE,sha256=90A_5sifmt1zqDMduHCaUvIJLVzx6XWjwbeqe8aW_OA,1063
+tapcub-0.1.0.dist-info/METADATA,sha256=Jg3GC6rnXyswOugQqN7P_Ft402QoO23XWW2apxSeeZg,8418
+tapcub-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tapcub-0.1.0.dist-info/top_level.txt,sha256=LfmhldBVVDkOOg9vKkA64NROyLn1u7H-0r8p18WOS2I,7
+tapcub-0.1.0.dist-info/RECORD,,

tapcub-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tapcub-0.1.0.dist-info/licenses/LICENSE

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

tapcub-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tapcub