Metadata-Version: 2.4
Name: condor-retl-tiktok-ads
Version: 0.1.0
Summary: TikTok Ads destination connector package for RETL Custom Audience contracts.
Project-URL: Homepage, https://condorgraph.com/
Project-URL: Documentation, https://docs.condorgraph.com/reference/connector-packages/
Project-URL: Repository, https://github.com/condorgraph/condor-retl
Project-URL: Issues, https://github.com/condorgraph/condor-retl/issues
Author-email: "Dataration LLC (Condor)" <info@condorgraph.com>
Maintainer-email: Chris Morin <chris@condorgraph.com>
License-Expression: Apache-2.0
License-File: LICENSE-Apache-2.0.txt
Keywords: custom-audiences,data-activation,destination-connector,retl,reverse-etl,tiktok-ads
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.12
Requires-Dist: condor-retl<0.2,>=0.1.0
Requires-Dist: requests<3,>=2.32
Description-Content-Type: text/markdown

# TikTok Ads Destination Connector

This package exposes the first-party `retl/tiktok-ads` destination connector.

## Surfaces

- `custom_audiences`: State surface for TikTok Ads Custom Audience membership.
  Supports `upsert` and `remove`, requires a Target audience, and supports
  managed target creation.

RETL accepts `email`, `phone_e164`, and `mobile_advertising_id` identifiers.
The connector hashes values with SHA-256 unless they are already SHA-256 hex.
Email and phone values are trimmed and lowercased before hashing; mobile
advertising IDs are trimmed and lowercased before hashing.

## Auth

The connector uses TikTok's `Access-Token` header:

```python
destination = retl.destinations.load(
    "retl/tiktok-ads",
    binding_name="tiktok_ads_primary",
    credential_namespace="destinations.tiktok_ads",
    config_namespace="destinations.tiktok_ads",
)
```

Environment-backed names:

```text
DESTINATIONS__TIKTOK_ADS__ACCESS_TOKEN
DESTINATIONS__TIKTOK_ADS__ADVERTISER_ID
DESTINATIONS__TIKTOK_ADS__API_VERSION
DESTINATIONS__TIKTOK_ADS__MOBILE_ADVERTISING_ID_TYPE
```

## Config

Required public config:

- `advertiser_id`: TikTok Ads advertiser ID.

Optional public config:

- `api_version`: defaults to TikTok Business API version 1.3, including the
  TikTok path prefix used by the Business API.
- `mobile_advertising_id_type`: defaults to `MAID_SHA256`; may be
  `IDFA_SHA256` or `GAID_SHA256` when the source column is platform-specific.

The connector owns the production API origin `https://business-api.tiktok.com`
in package code. Tests use injected transports to capture requests without
changing that origin.

## API Notes

This connector uses TikTok Business API version 1.3 DMP Custom Audience
endpoints. Membership data is rendered as an in-memory text file, uploaded to
TikTok, and then referenced by the create/update request:

- `POST /open_api/{api_version}/dmp/custom_audience/file/upload/`
- `POST /open_api/{api_version}/dmp/custom_audience/create/`
- `POST /open_api/{api_version}/dmp/custom_audience/update/`

Managed target lookup uses:

- `GET /open_api/{api_version}/dmp/custom_audience/list/`

TikTok audience processing can be asynchronous; submission evidence is therefore
reported as `accepted`.

## Proof

Default package tests are deterministic and offline. They use injected
transports to verify request paths, headers, bodies, target mapping, dry-run
behavior, response classification, and managed target lookup/create behavior.

The opt-in live sandbox test reads `local/env/.env.tiktok_ads-sandbox` when
present and runs with:

```bash
make test-sandbox-tiktok-ads
```

It creates a disposable Custom Audience through file upload, submits one
synthetic `upsert` and one synthetic `remove`, asserts TikTok acceptance
evidence, and best-effort deletes the audience through the DMP Custom Audience
delete endpoint.
