tapcub 0.1.0__tar.gz

tapcub-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,133 @@
+# 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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tapcub"
+version = "0.1.0"
+description = "TapCub server-side SDK for Python: events, sign-ups, identities, user profiles, items and accounts"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "TapCub", email = "hello@tapcub.com" }]
+requires-python = ">=3.8"
+dependencies = []
+keywords = ["tapcub", "analytics", "server-side", "events", "tracking", "product-analytics"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://tapcub.com"
+Documentation = "https://docs.tapcub.com/en/sdk/server#python"
+Source = "https://github.com/tapcub/tapcub-sdk/tree/main/packages/sdk-server/python"
+Issues = "https://github.com/tapcub/tapcub-sdk/issues"
+Changelog = "https://github.com/tapcub/tapcub-sdk/blob/main/packages/sdk-server/python/CHANGELOG.md"
+
+[tool.setuptools]
+packages = ["tapcub"]
+
+[tool.setuptools.package-data]
+tapcub = ["py.typed"]

tapcub-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tapcub-0.1.0/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-0.1.0/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}