Metadata-Version: 2.4
Name: keble-tiktok
Version: 0.6.0
Summary: TikTok Channel Domain layer for the Keble unified e-commerce data platform.
Author-email: norman2015 <changwantao@163.com>
Requires-Python: <3.14,>=3.13
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: keble-data-infra-contract<1,>=0.3.0
Requires-Dist: keble-db<2,>=1.9.0
Requires-Dist: keble-helpers<2,>=1.51.0
Requires-Dist: motor<4,>=3
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: pymongo<5,>=4
Requires-Dist: redis<6,>=5
Requires-Dist: sentry-sdk<3,>=2
Description-Content-Type: text/markdown

# keble-tiktok

The source line requires `keble-helpers>=1.51.0` so FastMoss/EchoTik call and
quantity usage uses the same public contract in development and registry
installs. Provider prices remain outside this package.

Side effects if changes:

- Data Infra transports these usage events through the TikTok manifest.
- Changing the helper floor requires lock and raw API source-graph verification.

TikTok provider package for the Keble raw-data API. It owns FastMoss and
EchoTik native clients, DTOs, channel-domain mappings, framework-free service
classes, and explicit provider manifests.

`FastMossServices` and `EchoTikServices` accept data-infra contract requests
and return normalized contract models. They do not construct FastAPI routers.
`keble-data-infra-api` imports their manifests and owns all HTTP paths,
exception handlers, settings, and lifecycle wiring.

Install the current public provider line with
`pip install "keble-tiktok>=0.6.0,<1"`. Version 0.6.0 requires the released
data-infra contract and `keble-db>=1.9.0`; provider credentials remain runtime
configuration and are never included in the distribution.

Provider-native detail models stay inside this package. Public results expose
only normalized fields; shared monetary values use `keble_helpers.Money`.
Production docstrings follow the split `keble_data_infra_contract` plus concrete
`FastMossServices`/`EchoTikServices` composition; retired monolith and
`ApplicationService` terminology remains only in explicitly historical records.

## Distinct trending resources

Version 0.6 exposes native `TRENDING` operations rather than adapting search:

- FastMoss: products and creators through its dated product/creator boards;
- EchoTik: products, creators, sellers, and channel-wide videos through four
  distinct ranking endpoints and schemas.

The shared adapter maps `lookbackDays` to the latest completed day, ISO week,
or month. Provider cursors are page-local and remain hidden behind Data Infra's
opaque central session. Bare-list EchoTik responses are definitively exhausted
only after an empty page (or a documented reachable product-page cap); a sparse
non-empty page remains `UNKNOWN`, so filtering or dedupe cannot create false
source exhaustion.

Every item retains its genuine resource model and a neutral summary plus typed
metric/board-position evidence explaining why it stands out. Products use
`CommerceListing`, creators use `CommerceCreator`, sellers use `CommerceStore`,
and channel-wide videos use `ShortVideo`. The video board has its own typed
`/api/v3/echotik/video/ranklist` DTO/source and is not the product-linked video
list. Its embedded product references are parsed with typed Pydantic `Json`;
transient playback URLs may cross the raw response but are never stable identity
and the platform does not persist them.

Provider packages emit all source occurrences and usage events. Query-selected
entity/family dedupe, buffered pagination, and fixed-time session invalidation
remain owned by the central Data Infra coordinator.

```bash
uv lock --check
uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
uv run npx --yes pyright .
uv build
```

HTTP transports and environment-proxy behavior are constructor-injected.
Direct clients default to `trust_env=False` for deterministic library tests;
the service builders explicitly enable production environment proxies. The
runtime dependency includes HTTPX's SOCKS transport so a configured SOCKS4/5
proxy is supported rather than failing during client construction.

## Durable provider cache and batches

The API may inject one `ProviderOperationCache` into each service builder. The
cache stores validated contract JSON in an API-owned Mongo collection keyed by
provider, operation, contract version, and the hash of the complete canonical
request. Empty successful responses use a shorter TTL. Redis owner-token leases
ensure concurrent identical misses call upstream once, then all contenders
recheck Mongo before provider I/O.

`ProviderResponseCacheRepository.ensure_indexes()` must run during API startup.
It creates the exact unique compound read index plus `expires_at` TTL index;
`drop_obsolete_indexes()` removes indexes whose query shapes no longer exist.

FastMoss search and EchoTik video services expose service-only `aload_many_*`
methods. They deduplicate exact requests, bound concurrency where no native
batch exists, and reconstruct the caller's original order. No HTTP batch route
is generated.

When the API initializes Sentry, exact cache reads, Redis lease acquisition,
real provider work, and service-only batches emit nested spans. Span data is
limited to stable provider/operation/outcome/count metadata; request keywords,
response payloads, and credentials are never attached.

Each service builder also accepts the package-neutral
`UsageAccountingRecorderProtocol`. One successful real FastMoss/EchoTik
upstream interaction emits one `API_CALL` event with provider, operation, and
duration. The recorder is deliberately invoked inside cache-miss handlers, so
cache hits never replay old billable usage. Prices and currencies remain owned
by the consuming platform; failed calls become host-side unknown attempts.

Real cache tests require isolated Mongo/Redis and use:

```bash
KEBLE_BACKEND_ENV_FILE=/path/to/keble.backend/.env \
RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 \
  uv run pytest -q -m "not live and not container"
```
