clikgate 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- clikgate-2.0.0/.gitignore +41 -0
- clikgate-2.0.0/CHANGELOG.md +109 -0
- clikgate-2.0.0/LICENSE +21 -0
- clikgate-2.0.0/PKG-INFO +305 -0
- clikgate-2.0.0/README.md +264 -0
- clikgate-2.0.0/SECURITY.md +35 -0
- clikgate-2.0.0/pyproject.toml +97 -0
- clikgate-2.0.0/src/clikgate/__init__.py +176 -0
- clikgate-2.0.0/src/clikgate/_addon.py +52 -0
- clikgate-2.0.0/src/clikgate/_ads_hashing.py +98 -0
- clikgate-2.0.0/src/clikgate/_click_ids.py +564 -0
- clikgate-2.0.0/src/clikgate/_client.py +838 -0
- clikgate-2.0.0/src/clikgate/_config.py +134 -0
- clikgate-2.0.0/src/clikgate/_core.py +173 -0
- clikgate-2.0.0/src/clikgate/_enums.py +70 -0
- clikgate-2.0.0/src/clikgate/_errors.py +304 -0
- clikgate-2.0.0/src/clikgate/_goals.py +858 -0
- clikgate-2.0.0/src/clikgate/_guard.py +69 -0
- clikgate-2.0.0/src/clikgate/_http.py +359 -0
- clikgate-2.0.0/src/clikgate/_identity.py +140 -0
- clikgate-2.0.0/src/clikgate/_money.py +59 -0
- clikgate-2.0.0/src/clikgate/_payments.py +705 -0
- clikgate-2.0.0/src/clikgate/_resources.py +332 -0
- clikgate-2.0.0/src/clikgate/_types.py +282 -0
- clikgate-2.0.0/src/clikgate/_user_agent.py +35 -0
- clikgate-2.0.0/src/clikgate/_version.py +3 -0
- clikgate-2.0.0/src/clikgate/api.py +28010 -0
- clikgate-2.0.0/src/clikgate/django.py +184 -0
- clikgate-2.0.0/src/clikgate/fastapi.py +11 -0
- clikgate-2.0.0/src/clikgate/flask.py +134 -0
- clikgate-2.0.0/src/clikgate/py.typed +0 -0
- clikgate-2.0.0/src/clikgate/starlette.py +140 -0
- clikgate-2.0.0/src/clikgate/webhooks.py +135 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Shared
|
|
2
|
+
.DS_Store
|
|
3
|
+
node_modules/
|
|
4
|
+
|
|
5
|
+
# server/ (server SDKs)
|
|
6
|
+
server/node/dist/
|
|
7
|
+
server/node/.test-dist/
|
|
8
|
+
server/node/sbom.cdx.json
|
|
9
|
+
server/node/*.tgz
|
|
10
|
+
server/node/examples/nextjs/.next/
|
|
11
|
+
server/node/examples/nextjs/next-env.d.ts
|
|
12
|
+
server/codegen/.cache/
|
|
13
|
+
server/python/.venv/
|
|
14
|
+
server/python/dist/
|
|
15
|
+
server/python/sbom.cdx.json
|
|
16
|
+
server/python/.mypy_cache/
|
|
17
|
+
server/python/.pytest_cache/
|
|
18
|
+
server/python/.ruff_cache/
|
|
19
|
+
**/__pycache__/
|
|
20
|
+
server/php/vendor/
|
|
21
|
+
server/php/composer.lock
|
|
22
|
+
server/php/.php-cs-fixer.cache
|
|
23
|
+
server/php/.phpstan-cache/
|
|
24
|
+
server/php/.phpunit.cache/
|
|
25
|
+
server/php/sbom.cdx.json
|
|
26
|
+
server/php-laravel/vendor/
|
|
27
|
+
server/php-laravel/composer.lock
|
|
28
|
+
server/php-laravel/.phpunit.cache/
|
|
29
|
+
server/java/**/target/
|
|
30
|
+
server/java/sbom.cdx.json
|
|
31
|
+
|
|
32
|
+
# ai-guides/ (AI guides)
|
|
33
|
+
ai-guides/dist/
|
|
34
|
+
ai-guides/clikgate-setup/references/api-surface.md.new
|
|
35
|
+
ai-guides/.blocks/
|
|
36
|
+
server/dotnet/**/bin/
|
|
37
|
+
server/dotnet/**/obj/
|
|
38
|
+
server/dotnet/artifacts/
|
|
39
|
+
server/java-spring-boot-starter/target/
|
|
40
|
+
server/php-laravel/.phpstan-cache/
|
|
41
|
+
server/php-laravel/.php-cs-fixer.cache
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Changelog: clikgate (Python)
|
|
2
|
+
|
|
3
|
+
All notable changes to this package. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses [semantic versioning](https://semver.org/). Deprecations are announced at least 6 months ahead, and Python versions are dropped only after their end of life.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
## [2.0.0] - unreleased
|
|
7
|
+
|
|
8
|
+
### Breaking: track() removed in favour of goal()
|
|
9
|
+
|
|
10
|
+
- **Removed:** `track()` and app events are gone from Clikgate in favour of one method, `goal()`, for anything that happens in an app, website or server. A name that isn't set up as a goal yet still arrives (status `received`) and shows in the dashboard under "Seen from your app and website", ready to be counted. In this SDK that removes the generated app events resource (details under "Identity tokens, one goal() method" below): send `goal()` instead.
|
|
11
|
+
|
|
12
|
+
### Strict goal names
|
|
13
|
+
- With the organisation's "Allow unknown goal names" off, the API refuses a goal name that isn't set up with `422 unknown_goal`, and an archived goal with `422 goal_archived`. Both are `InvalidRequestError` (`ClikgateError.code` is the reason) and final: never retried, never re-queued; background `goal()` passes them to `onError` as dropped. The SDK never checks names itself and never remembers the refusal.
|
|
14
|
+
- A `422` answered with the refusal body `{"status": "refused", "reason": ...}` (no error envelope) now maps to that reason instead of `http_422`; the body is the error's raw object.
|
|
15
|
+
- With debug logging on (the `clikgate` logger at `DEBUG`), each refusal logs "Goal `{name}` isn't set up in Clikgate" with the goal name only.
|
|
16
|
+
|
|
17
|
+
### Identity tokens, one goal() method
|
|
18
|
+
|
|
19
|
+
- **Added:** `clikgate.create_identity_token(customer_id, *, app_id=None, secret=None, issued_at=None)` (no API key needed) and `Clikgate.create_identity_token(customer_id, *, app_id=None, issued_at=None)` (also a plain method on `AsyncClikgate`): `base64url_nopad(HMAC_SHA256(secret, customer_id + "." + issued_at)) + "." + issued_at`, the signer Clikgate verifies with, with no network call. The secret comes from `secret`, else (with `app_id`) that app's entry in the `identity_secrets` option / `CLIKGATE_IDENTITY_SECRETS` (a JSON object), else the `identity_secret` option / `CLIKGATE_IDENTITY_SECRET`. Errors: `ConfigurationError` (`missing_identity_secret`, `invalid_identity_secrets`), `InvalidRequestError` (`invalid_customer_id`: 1-255 characters; never echoed), and the new `ClikgateServerOnlyError` (`server_only`) in browser or mobile Python builds (Pyodide / Emscripten / WASI, CPython on iOS or Android). Tested against the shared vectors in `server/conformance/vectors/identity-token-vectors.json`. Guide: https://clikgate.com/docs/identify-users.
|
|
20
|
+
- **Docs:** `identify_user()` documents path B (no secret or token): your server calls `identify_user(app_id=…, installation_id=…, customer_id=…, label=…)` with the installation ID the app sends at sign-in and at every signed-in app open, and skips the call when there is none.
|
|
21
|
+
- **Added:** `GoalStatus.RECEIVED` `received`: `goal()` / `goals.send` with a name that isn't ticked as a goal yet (or an archived goal) answers `200` with `status: "received"` and `reason` `not_counted_yet` (or `goal_archived`). It is a result, like `waiting` and `refused`: never an error and never retried.
|
|
22
|
+
- **Removed (generated API):** the app events resource (`clikgate.api.app_events` and `AppEventsApi`): List App Events (`GET /v1/app-events`), Report App Events (`POST /v1/apps/{app_id}/events`) and the Event rules operations (`/v1/apps/{app_id}/event-rules`). Clikgate has one method for anything that happens in an app, website or server, `goal()`; names not ticked as goals yet show in the dashboard's "Seen from your app and website". No released version ever had them (the generator drops them through `server/codegen/removed.mjs` until the backend's public document no longer lists them).
|
|
23
|
+
|
|
24
|
+
### Hashed email and phone for ad network matching
|
|
25
|
+
|
|
26
|
+
- **Added:** `hash_for_ads(email=None, phone=None)` → `HashedIdentifiers` (`hashed_email`, `hashed_phone_e164`, `hashed_phone_digits`; only the fields given), to pass as `**kwargs` to `goal()`. Pure and offline: the email is trimmed and lowercased (must contain `@`); the phone must start with `+` or `00` and be 7-15 digits starting with 1-9 (E.164). Bad input is a local `invalid_argument` (`param` `email` / `phone`, never echoed).
|
|
27
|
+
- **Added:** goal options `hashed_email`, `hashed_phone_e164` and `hashed_phone_digits` (`goal()`, `goals.send`, batch events; sync and async); `conversions.create` takes the same fields. A value that isn't 64 lowercase hex characters is a local `invalid_hashed_identifier` (`param` = the field; the value is never echoed). The private-mode guard allows the three fields on goals and conversions; hashed values are never logged.
|
|
28
|
+
|
|
29
|
+
### Keep the click ID longer
|
|
30
|
+
|
|
31
|
+
- **Added:** `clikgate.click_ids.keep_route(days=30, secure=True, domain=None)`, the `/cg/keep` route for the web script's `data-server-endpoint="/cg/keep"`: the framework-neutral `handle_keep(method, headers, body)`, plus `clikgate.django.keep_view()`, `clikgate.flask.keep_view()` and `clikgate.starlette.keep_endpoint()` / `clikgate.fastapi.keep_endpoint()` (also as `route.django_view`, `route.flask_view`, `route.starlette_endpoint`). Same-origin `POST` only, a valid click ID matching the page URL's, `no-store`, empty bodies, never a redirect. `days` outside 1-400 is `invalid_argument`.
|
|
32
|
+
- **Added:** `clikgate.click_ids.context(request)` → `{"click_id", "kept_by", "browser_engine", "platform"}` for a goal's options (the User-Agent is parsed in the SDK, never sent).
|
|
33
|
+
- **Added:** goal options `kept_by`, `browser_engine` and `platform` (`goal()`, `goals.send`, batch events; sync and async; unknown values are a local `invalid_argument`), allowed by the private-mode guard.
|
|
34
|
+
- **Changed:** `persist()` and the Django, Flask and Starlette/FastAPI add-ons also write the `_cg_kept=s` marker cookie (same `Path`, `Max-Age`, `Domain`, `SameSite`, `Secure`), so the web script reports `kept_by: server_cookie`.
|
|
35
|
+
|
|
36
|
+
### identifyUser, goal labels, App banners
|
|
37
|
+
|
|
38
|
+
- **Added:** `clikgate.identify_user(click_id=… | app_id=… + installation_id=… | customer_id=…, label=…)` (sync and async) → `POST /v1/people/identify`: at least one reference (a click, an app installation or a customer ID; with a click or installation the customer ID links it). Always verified, so it also satisfies a referral program's `require_identity_token`. Local `invalid_request` without a reference or with half an installation. In private mode the guard refuses the customer ID; `label` passes (the API needs "Allow labels in private mode", else `422 labels_off_in_private_mode`).
|
|
39
|
+
- **Added:** goals take `label` (the person's label, 1-80 characters; Growth and up), allowed by the private-mode guard.
|
|
40
|
+
- **Removed (generated API):** the app server-identify operation (`POST /v1/apps/{app_id}/identify`); use `identifyUser`. The Journeys API is now the App banners API (`AppBannersApi`, `app_banner_id`, `AppBanner*` types, type `full_screen`, webhooks `app_banner.published` / `app_banner.paused`); IDs keep the `jrn_` prefix.
|
|
41
|
+
- **Regenerated** from the current public OpenAPI (523 operations), including the share events, QR, referral map, single sign-on, people, customer cost).
|
|
42
|
+
|
|
43
|
+
### Breaking
|
|
44
|
+
- **Goal results carry the goal call's outcome.** `GoalEvent["status"]` is now the `GoalStatus`: `counted`,
|
|
45
|
+
`waiting` (a Payment goal waiting for its confirmation, or an event waiting for its click) or `refused` (with
|
|
46
|
+
`reason`). The conversion state that `status` held before (`attributed`, `unattributed`, `rejected_bot`, …) is in
|
|
47
|
+
the new `event_status`. Code that compared `status` with `"attributed"` must read `event_status`, or test
|
|
48
|
+
`status == GoalStatus.COUNTED`.
|
|
49
|
+
- `goals.send` and `goals.send_batch` (sync and async) return `status` and `goal_kind` as `GoalStatus` / `GoalKind`
|
|
50
|
+
members when the value is known (they are `str`, so JSON and string comparisons keep working).
|
|
51
|
+
- Goal management (`api.goals.*`): the goal object has `kind` (`GoalKind`) and `suggest_payment` instead of
|
|
52
|
+
`confirmation`; `update_goal` takes `kind` and `confirm_kind_change`.
|
|
53
|
+
- There is no separate payment method in the web script or the app SDKs any more: a website or app reports a payment
|
|
54
|
+
with `goal()` on a Payment goal. The server helpers below are unchanged.
|
|
55
|
+
- Payment confirmations need the Starter plan or above: Free gets `403 plan_feature_unavailable` (was
|
|
56
|
+
`plan_upgrade_required`).
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
- **Private mode allows `consent`** (the four-purpose consent object) on goals, batch items and conversions, as the API does; it was refused locally before. Payment confirmations also allow the API's structural `refund_id` and `source_plugin` (through `extra`).
|
|
60
|
+
- `conversions.create` is typed `Conversion | GoalEvent`: on a Payment goal the API answers with the goal event (`object == "goal_event"`). Send `provider` and the payment reference there; a server Payment goal has no default provider (`422 payment_goal_needs_confirmation` with `missing`).
|
|
61
|
+
- `GoalKind`, `GoalStatus` and `Provider` enums (`from clikgate import GoalKind, GoalStatus, Provider`), generated
|
|
62
|
+
from the API's OpenAPI document. `Provider` lists every payment gateway, plus `shopify`, `woocommerce` and `custom`.
|
|
63
|
+
- `provider` on `goal()`, `goals.send` and batch events: a `Provider` or a provider-key string (a newer gateway). A
|
|
64
|
+
malformed one raises `InvalidRequestError` `invalid_provider` locally. Private mode allows it.
|
|
65
|
+
- `payments.confirm(provider=...)` takes a `Provider` or a string.
|
|
66
|
+
- `GoalEvent` keys `goal_kind`, `value_ignored`, `event_status` and `payment` (`GoalPaymentInfo`: a Payment goal sent
|
|
67
|
+
by your server becomes a trusted confirmation).
|
|
68
|
+
- Conformance suite `compat`: unknown response fields and enum values are ignored and kept.
|
|
69
|
+
- **Payments confirmed by your server (SPEC section 22).** `payments.confirm(...)` posts
|
|
70
|
+
`POST /v1/payments/confirmations`. `payments.from_paystack`, `from_flutterwave`, `from_monnify` and `from_stripe` (sync and async) read
|
|
71
|
+
only the reference, status, amount, currency, time and `cg_click_id` from the gateway's verified response, and
|
|
72
|
+
send them.
|
|
73
|
+
- `build_from_*` (also exported as functions) return the body without sending it.
|
|
74
|
+
- Amounts are exact decimals.
|
|
75
|
+
- The private-mode guard has a new kind, `payment_confirmation`.
|
|
76
|
+
- New warning code: `unrecognised_payment_response`.
|
|
77
|
+
- New types: the `PaymentConfirmation` and `PaymentConfirmationBody` TypedDicts.
|
|
78
|
+
- Conformance suite `payments`.
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
- **Fraud rules and the fraud test lab (2026-10-28):** the generated `api.*` layer is regenerated (757 operations; 461 kept). New `api.ad_fraud.fetch_fraud_rules()` (`GET /v1/fraud/rules`, `FraudRulesDetailResponse`, plans with fraud insights). `FraudSampleResponse` (`create_fraud_sample`) no longer has `score` or `threshold`, `reasons` is `{rule, name}[]` (`FraudSampleReason`) and `FraudSamplePlanOutcome` has no `threshold`. These are removals from a response type.
|
|
82
|
+
|
|
83
|
+
## [1.1.0] - unreleased
|
|
84
|
+
|
|
85
|
+
### Added
|
|
86
|
+
- **Metadata filters:** `metadata` on the typed `api.links.list_links`, `api.analytics.analytics_summary`, `analytics_timeseries`, `top_links` and `open_in_app_analytics` methods and on `links.list` / `links.list_page`. A map such as `{"seller_id": "sel_ada"}` is sent as `metadata[seller_id]=sel_ada` (SPEC section 21). The API reads these from the raw query string, so the codegen adds the parameter (`codegen/filter.mjs`).
|
|
87
|
+
- **Webhook `subscription.updated`:** documented on the webhook event type; it carries the subscription with `add_ons`, `change` and `add_on_key`. `type` stays a plain string, so nothing else changes. Conformance `webhooks.valid.subscription_updated`.
|
|
88
|
+
- The generated `api.*` layer is regenerated from the final `openapi.json` (756 operations; 460 kept). `AnalyticsRowResponse.end_goal_value` is `Dict[str, str]` (decimal strings per currency) next to `end_goal_value_minor`.
|
|
89
|
+
- `GoalEvent["value_minor"]` and `["reversed_value_minor"]` (`int`): the amounts in minor units next to `value` and `reversed_value` (decimal strings), as the API returns them.
|
|
90
|
+
|
|
91
|
+
### Changed
|
|
92
|
+
- `goals.send` and `goal()` in sync mode send a random UUID v4 `Idempotency-Key` per call, reused across that call's retries, instead of `sha256(goal + ":" + reference)`. The API dedupes goal events by goal and reference itself, so a resend still never counts twice. The `idempotency_key` request option still overrides the key.
|
|
93
|
+
|
|
94
|
+
## [1.0.0] - unreleased (first release)
|
|
95
|
+
|
|
96
|
+
### Added
|
|
97
|
+
- `Clikgate` (sync, thread-safe) and `AsyncClikgate` (asyncio) clients:
|
|
98
|
+
- `goal()` (background queue with batching on a daemon thread or event-loop task; never raises);
|
|
99
|
+
- `goals.send`, `goals.send_batch` and `goals.reverse`;
|
|
100
|
+
- `flush()`, `close()`, and flush at exit (`atexit`).
|
|
101
|
+
- `conversions.create` and `conversions.reverse` (older API).
|
|
102
|
+
- `links.create`, `get`, `update` (`202` → `{"applied": False, "change_request": …}`; `409 link_locked` → `LinkLockedError`), `list` (lazy iterator), `list_page` and `qr`.
|
|
103
|
+
- `clicks.get`.
|
|
104
|
+
- Click IDs: `click_ids.from_request`, `is_valid`, `cookie_header`, `persist` and `from_payment_metadata`.
|
|
105
|
+
- Webhooks: `clikgate.webhooks.verify` and `verify_any` (also without a client).
|
|
106
|
+
- The private-mode guard (`private_mode="auto" | True | False`), failing closed.
|
|
107
|
+
- Typed errors, money as decimal strings (`format_value`; `float` raises `TypeError`), retries with full jitter and `Retry-After`, deterministic goal idempotency keys.
|
|
108
|
+
- `clikgate.api.*`: every API-key operation, generated from openapi.json (sync and async).
|
|
109
|
+
- Add-ons (extras, no core dependencies): `clikgate.django`, `clikgate.flask`, `clikgate.fastapi` / `clikgate.starlette`.
|
clikgate-2.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Clikgate
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
clikgate-2.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: clikgate
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: The official Clikgate server SDK for Python: send goals in three lines, keep the click ID, verify webhooks, with private mode built in.
|
|
5
|
+
Project-URL: Homepage, https://clikgate.com/docs/sdks/python
|
|
6
|
+
Project-URL: Documentation, https://clikgate.com/docs/sdks/python
|
|
7
|
+
Project-URL: Source, https://github.com/clikgate/clikgate-sdks/tree/main/server/python
|
|
8
|
+
Project-URL: Issues, https://github.com/clikgate/clikgate-sdks/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/clikgate/clikgate-sdks/blob/main/server/python/CHANGELOG.md
|
|
10
|
+
Author-email: Clikgate <sdk@clikgate.com>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: attribution,clikgate,conversions,deep-linking,django,fastapi,flask,goals,webhooks
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Framework :: Django
|
|
16
|
+
Classifier: Framework :: FastAPI
|
|
17
|
+
Classifier: Framework :: Flask
|
|
18
|
+
Classifier: Intended Audience :: Developers
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
28
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
29
|
+
Classifier: Typing :: Typed
|
|
30
|
+
Requires-Python: >=3.9
|
|
31
|
+
Requires-Dist: httpx<1,>=0.27
|
|
32
|
+
Provides-Extra: django
|
|
33
|
+
Requires-Dist: django>=4.2; extra == 'django'
|
|
34
|
+
Provides-Extra: fastapi
|
|
35
|
+
Requires-Dist: starlette>=0.37; extra == 'fastapi'
|
|
36
|
+
Provides-Extra: flask
|
|
37
|
+
Requires-Dist: flask>=2.3; extra == 'flask'
|
|
38
|
+
Provides-Extra: starlette
|
|
39
|
+
Requires-Dist: starlette>=0.37; extra == 'starlette'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# clikgate (Python)
|
|
43
|
+
|
|
44
|
+
The official Clikgate server SDK for Python. It:
|
|
45
|
+
|
|
46
|
+
- sends goals in three lines;
|
|
47
|
+
- keeps the click ID;
|
|
48
|
+
- verifies webhooks;
|
|
49
|
+
- has private mode built in.
|
|
50
|
+
|
|
51
|
+
It supports Python 3.9+, has one dependency (`httpx`), ships full type hints (`py.typed`, mypy strict), and offers a sync `Clikgate` and an async `AsyncClikgate`.
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install clikgate
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
from decimal import Decimal
|
|
59
|
+
from clikgate import Clikgate
|
|
60
|
+
|
|
61
|
+
clikgate = Clikgate() # reads CLIKGATE_API_KEY (cg_live_… or cg_test_…)
|
|
62
|
+
clikgate.goal("account_opened", click_id=click_id, reference="APP-55231", value=Decimal("2000000"))
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Create one client and reuse it. It is thread-safe.
|
|
66
|
+
|
|
67
|
+
- **`goal()`** is the one method for goals and payments. It never raises: it queues the event, and a daemon thread sends it in batches with safe retries.
|
|
68
|
+
- **`goals.send()`** waits for the API and returns the result: `status` is `GoalStatus.COUNTED`, `WAITING`, `RECEIVED` or `REFUSED` (with `reason`), plus `goal_kind`, `attributed_to`, … `received` means the name isn't ticked as a goal in the dashboard yet (or the goal is archived): it is stored, not counted, and shows in "Seen from your app and website". Every status is a result, never an error, and none is retried. Goals work on every plan, up to the plan's allowance.
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
from clikgate import GoalKind, GoalStatus, Provider
|
|
72
|
+
|
|
73
|
+
event = clikgate.goals.send("order_paid", reference="T123456", value="7500", currency="NGN", provider=Provider.PAYSTACK, click_id=click_id)
|
|
74
|
+
if event["status"] == GoalStatus.COUNTED: # members are str: == "counted" works too
|
|
75
|
+
...
|
|
76
|
+
elif event["goal_kind"] == GoalKind.PAYMENT and event["status"] == GoalStatus.WAITING:
|
|
77
|
+
... # a Payment goal waiting for its confirmation
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`GoalKind`, `GoalStatus` and `Provider` are `str` enums generated from the API. A value this release doesn't know (a newer status, or a gateway added later) stays a plain `str`, and `provider` also takes a provider-key string such as `"acme_pay"`.
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
### Match by hashed email or phone (ad networks)
|
|
84
|
+
|
|
85
|
+
When the business has turned on matching by hashed email or phone for an ad network destination, a goal can carry your own SHA-256 hashes: `hashed_email`, `hashed_phone_e164` and `hashed_phone_digits`. `hash_for_ads` makes them on your server (offline, no client needed) and returns only the fields for the values you give, ready to pass to `goal()` or `goals.send()`:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from clikgate import hash_for_ads
|
|
89
|
+
|
|
90
|
+
clikgate.goal(
|
|
91
|
+
"account_opened",
|
|
92
|
+
reference="APP-55231",
|
|
93
|
+
click_id=click_id,
|
|
94
|
+
**hash_for_ads(email="ada.obi@example.com", phone="+234 803 123 4567"),
|
|
95
|
+
)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The email is trimmed and lowercased. The phone must include its country code (`+234…` or `00234…`); a national number such as `0803 123 4567` is an `InvalidRequestError` (`invalid_argument`), and the SDK never guesses the country. A hashed value that isn't 64 lowercase hex characters is refused before sending (`invalid_hashed_identifier`). `conversions.create` takes the same fields. Hashed values are never logged.
|
|
99
|
+
|
|
100
|
+
In private mode, hash on your own server: Clikgate never hashes for you there.
|
|
101
|
+
|
|
102
|
+
## Identify your users
|
|
103
|
+
|
|
104
|
+
Two ways to tell Clikgate which of your users is using the app. Full guide: https://clikgate.com/docs/identify-users. The customer ID is your own user ID from your database, never an email, phone number or ID number. Anonymous users don't need either path.
|
|
105
|
+
|
|
106
|
+
**Path A (default): identity token.** Create the identity secret in Apps › your app › Identity secret and store it as `CLIKGATE_IDENTITY_SECRET` on your server only. `create_identity_token(customer_id, app_id=None)` (also `clikgate.create_identity_token()`, with the `identity_secret` / `identity_secrets` options) signs a token with no network call; return it in the responses the app already calls, and the app passes it to the mobile SDK's `identifyUser()`. Tokens last 30 days by default and are never force-refreshed. Throws `ClikgateServerOnlyError` in browser or mobile Python builds (Pyodide, WASI, iOS, Android).
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from clikgate import create_identity_token
|
|
110
|
+
# sign-in and "current user" responses: one extra field
|
|
111
|
+
return {"user": user, "clikgate_identity_token": create_identity_token(str(user.id))} # reads CLIKGATE_IDENTITY_SECRET
|
|
112
|
+
create_identity_token(str(user.id), app_id="app_…") # several apps: CLIKGATE_IDENTITY_SECRETS
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Path B: installation ID, no secret or token.** The app reads `getInstallationId()` and includes it in its sign-in request; your server calls `identifyUser` with the app ID, installation ID and customer ID, after sign-in and at every signed-in app open. Clikgate accepts installations active in the last 7 days.
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
# The app sends Clikgate.getInstallationId() with its sign-in request (None when tracking is off: skip)
|
|
119
|
+
if installation_id:
|
|
120
|
+
clikgate.identify_user(app_id="app_…", installation_id=installation_id, customer_id=str(user.id))
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## People: identify a user and label them
|
|
124
|
+
|
|
125
|
+
Link a click, an app installation or your customer ID to a person, and give them a label your team sees instead of the click ID (1-80 characters; Growth and up). From your server this is always verified. Goals take the same `label`, and `isFirst` from your server is what counts a new customer. Don't put information in labels that your customers wouldn't expect you to keep.
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
clikgate.identify_user(click_id=order.click_id, customer_id="user_42", label="Ada (VIP)")
|
|
129
|
+
clikgate.goal("account_opened", click_id=click_id, reference="APP-55231", is_first=True, label="Ada (VIP)")
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Keep the click ID
|
|
133
|
+
|
|
134
|
+
The pattern is: capture it on landing, save it with your own record, then send the goal later from any job.
|
|
135
|
+
|
|
136
|
+
| Framework | Install | Usage | Read it |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| Django | `pip install "clikgate[django]"` | add `"clikgate.django.ClikgateMiddleware"` to `MIDDLEWARE` | `request.clikgate_click_id` |
|
|
139
|
+
| Flask | `pip install "clikgate[flask]"` | `from clikgate.flask import Clikgate; Clikgate(app)` | `g.clikgate_click_id` |
|
|
140
|
+
| FastAPI / Starlette | `pip install "clikgate[fastapi]"` | `app.add_middleware(ClikgateMiddleware, client=clikgate)` from `clikgate.fastapi` | `Depends(click_id)` |
|
|
141
|
+
|
|
142
|
+
Each add-on keeps a click ID that arrives as `?cgid=…` in the first-party `_cg_cgid` cookie, which the web script also reads. The extras add no dependencies to the core package.
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
# Django: save it with your record…
|
|
146
|
+
Application.objects.create(reference="APP-55231", click_id=request.clikgate_click_id)
|
|
147
|
+
|
|
148
|
+
# …and days later, when the account is approved, from any job:
|
|
149
|
+
from clikgate.django import get_client
|
|
150
|
+
get_client().goal("account_opened", click_id=app.click_id, reference=app.reference, value=Decimal("2000000"), currency="NGN")
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- **Without a framework:** `clikgate.click_ids.from_request(request)` and `clikgate.click_ids.persist(response, click_id, request=request)`.
|
|
154
|
+
- **From payment payloads** (Paystack, Flutterwave, Shopify, WooCommerce): `clikgate.click_ids.from_payment_metadata(payload)`.
|
|
155
|
+
|
|
156
|
+
## Keep the click ID longer (Safari)
|
|
157
|
+
|
|
158
|
+
Safari, and every browser on iPhone, keeps a click ID saved by a script for up to 7 days (sometimes less). When your server saves it, it lasts as long as you choose, up to the browser's limit.
|
|
159
|
+
|
|
160
|
+
Add a `/cg/keep` route to your server and tell the web script about it with `data-server-endpoint="/cg/keep"`. When a click ID arrives in the page URL, the script makes one `POST` to that route, and your server sets the `_cg_<param>` cookie (30 days by default, `days` up to 400) plus a small `_cg_kept=s` marker, so goals report `kept_by="server_cookie"`.
|
|
161
|
+
|
|
162
|
+
- **Same server:** the route must be served by the same host as the website (the page's own origin, e.g. `https://shop.example.com/cg/keep`), not by another domain or subdomain. A cookie set by another host doesn't get the longer lifetime.
|
|
163
|
+
- **Readable by the page on purpose:** both cookies are not `HttpOnly`, because the web script reads them. They are `SameSite=Lax` and `Secure` (default `True` here; pass `secure=False` only for local `http://` development).
|
|
164
|
+
- **Locked down:** only a same-origin `POST` (`Sec-Fetch-Site: same-origin`, or an `Origin` equal to the request's host) with a valid click ID that matches the page URL's is accepted. Every answer is `Cache-Control: no-store, private` with an empty body; it never redirects, and the input is never echoed or logged. The cookie name comes from your configuration (`click_id_param`, else `cgid`), never from the request.
|
|
165
|
+
|
|
166
|
+
```html
|
|
167
|
+
<script src="https://sdk.clikgate.com/v1/static/clikgate.js" data-web-key="cgw_live_…" data-server-endpoint="/cg/keep" async></script>
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**Django** (the view is CSRF-exempt on purpose: it checks the origin itself and only sets the cookie):
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
# urls.py
|
|
174
|
+
from clikgate.django import keep_view
|
|
175
|
+
|
|
176
|
+
urlpatterns = [
|
|
177
|
+
path("cg/keep", keep_view()), # or keep_view(days=90)
|
|
178
|
+
# …
|
|
179
|
+
]
|
|
180
|
+
|
|
181
|
+
# settings.py: the middleware also keeps ?cgid=… from the query on any page (and writes the marker)
|
|
182
|
+
MIDDLEWARE = [..., "clikgate.django.ClikgateMiddleware"]
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**Flask:** `app.add_url_rule("/cg/keep", "clikgate_keep", keep_view(), methods=["POST"])` with `from clikgate.flask import keep_view`.
|
|
186
|
+
|
|
187
|
+
**FastAPI / Starlette:** `app.add_api_route("/cg/keep", keep_endpoint(client=clikgate), methods=["POST"])` with `from clikgate.fastapi import keep_endpoint` (Starlette: `Route("/cg/keep", keep_endpoint(client=clikgate), methods=["POST"])`).
|
|
188
|
+
|
|
189
|
+
**Anything else:** `route = clikgate.click_ids.keep_route()`, then `route.handle_keep(method, headers, body)` returns `(status, headers, body)` to send as is (read at most 1025 bytes of the body).
|
|
190
|
+
|
|
191
|
+
Then send what you know about how it was kept with the goal. `click_ids.context(request)` returns `{"click_id", "kept_by", "browser_engine", "platform"}`; the engine and platform are worked out from the `User-Agent` in the SDK (the User-Agent itself is never sent), and all three are allowed in private mode:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
clikgate.goal("account_opened", reference=application.reference, **clikgate.click_ids.context(request))
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`kept_by` is `server_cookie` (your server set the cookie), `script_cookie` (the web script did), `form` (the `Clikgate-Click-Id` header) or `None`; you can also pass `"payment_metadata"` or `"unknown"` yourself. `persist()` and the framework add-ons also write the `_cg_kept=s` marker.
|
|
198
|
+
|
|
199
|
+
## Money
|
|
200
|
+
|
|
201
|
+
- `value` is in **normal units** (₦2,000,000 is `2000000`, never kobo) and is always sent as a decimal string.
|
|
202
|
+
- It accepts `Decimal`, `int` or `str`. A `float` raises `TypeError`, because floats can't hold exact amounts.
|
|
203
|
+
|
|
204
|
+
## Payment goals
|
|
205
|
+
|
|
206
|
+
A goal is **Standard** or **Payment** (`GoalKind`), set in the goal's settings, never in the call. A Payment goal counts only when a trusted source confirms it:
|
|
207
|
+
|
|
208
|
+
- Your website or app **reports** the payment with `goal()` on the Payment goal, with `provider` and `reference` (never an amount). It waits for the confirmation (`status: waiting`).
|
|
209
|
+
- Your server **confirms** it, either with the payments helpers below, or by sending the same Payment goal with the confirmed value: `clikgate.goals.send("order_paid", reference="T123456", value="7500", currency="NGN", provider=Provider.PAYSTACK)`. It is counted at once with a `click_id`, and otherwise waits for the report.
|
|
210
|
+
|
|
211
|
+
Call the helper **right after your own server has verified the payment with
|
|
212
|
+
the gateway**, with the gateway's verified response. Never pass data from the browser or the app. The helper sends
|
|
213
|
+
only the reference, status, amount, currency, time and `cg_click_id`. It never sends customer details, and it
|
|
214
|
+
never needs your gateway key.
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
# Paystack: after your own GET /transaction/verify/{reference}
|
|
218
|
+
clikgate.payments.from_paystack(verify_response, goal="order_paid")
|
|
219
|
+
# Flutterwave: after your own GET /v3/transactions/{id}/verify
|
|
220
|
+
clikgate.payments.from_flutterwave(verify_response)
|
|
221
|
+
# Monnify: after your own GET /api/v2/transactions/{transactionReference}
|
|
222
|
+
clikgate.payments.from_monnify(status_response)
|
|
223
|
+
# Stripe: a PaymentIntent you retrieved, or the Checkout Session from a webhook you verified
|
|
224
|
+
clikgate.payments.from_stripe(payment_intent)
|
|
225
|
+
|
|
226
|
+
# Any other gateway, or a refund:
|
|
227
|
+
clikgate.payments.confirm(provider=Provider.PAYSTACK, reference="T_ref_001", status="refunded", amount="2500.00", currency="NGN")
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- Amounts are exact decimals, never floats: Paystack's `750000` kobo becomes `"7500"`.
|
|
231
|
+
- Raw JSON text is parsed with `Decimal`.
|
|
232
|
+
- The helpers return `None` (and send nothing) when the response has no reference or no known status.
|
|
233
|
+
`build_from_paystack(...)` and the other builders return the body without sending it.
|
|
234
|
+
- `AsyncClikgate` has the same methods (`await`).
|
|
235
|
+
- Private mode allows every field these send.
|
|
236
|
+
- Payments need the Starter plan or above: on Free the API answers `403 plan_feature_unavailable` (`PermissionError`, `required_plan == "starter"`).
|
|
237
|
+
- `provider` and `reference` are required on a Payment goal (`422 payment_goal_needs_confirmation`, with `missing`); the SDK can't check it, because the kind lives only in the goal's settings. `conversions.create(goal=...)` on a Payment goal is the same confirmation and returns the goal event (`result["object"] == "goal_event"`).
|
|
238
|
+
|
|
239
|
+
## Webhooks
|
|
240
|
+
|
|
241
|
+
```python
|
|
242
|
+
from clikgate import webhooks, SignatureVerificationError
|
|
243
|
+
|
|
244
|
+
event = webhooks.verify(request.body, request.headers.get("Clikgate-Signature"), os.environ["CLIKGATE_WEBHOOK_SECRET"])
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
- Pass the **raw** body (`request.body` in Django, `request.get_data()` in Flask, `await request.body()` in Starlette).
|
|
248
|
+
- Deliveries are at-least-once: dedupe on `event["id"]`.
|
|
249
|
+
- Use `webhooks.verify_any(body, header, [new_secret, old_secret])` while you rotate your own secrets.
|
|
250
|
+
|
|
251
|
+
## Async
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
from clikgate import AsyncClikgate
|
|
255
|
+
|
|
256
|
+
clikgate = AsyncClikgate()
|
|
257
|
+
event = await clikgate.goals.send("account_opened", click_id=click_id, reference="APP-55231", value="2000000")
|
|
258
|
+
clikgate.goal("signup", reference=user.id) # non-blocking; needs a running event loop
|
|
259
|
+
await clikgate.close() # in your lifespan shutdown
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
## Short-lived processes
|
|
263
|
+
|
|
264
|
+
In a serverless function, a Celery task or a management command, call `clikgate.flush()` before returning (`atexit` also flushes at a normal exit). Alternatively use `Clikgate(send_mode="sync")` with `clikgate.goals.send(…)`.
|
|
265
|
+
|
|
266
|
+
## Private mode
|
|
267
|
+
|
|
268
|
+
- With `private_mode="auto"` (the default), the SDK reads your organisation's setting from `GET /v1/server-sdk/config` and caches it for 10 minutes.
|
|
269
|
+
- When private mode is on, only `goal`, `click_id`, `code`, `reference`, `value`, `currency`, `is_first`, `occurred_at`, `provider` and `consent` are sent. Anything else (`metadata`, emails, customer IDs, …) is refused **before sending** with `PrivateModeFieldRejectedError`, which names the field, never its value.
|
|
270
|
+
- References are redacted in logs.
|
|
271
|
+
- If the setting can't be loaded, the SDK assumes private mode is on.
|
|
272
|
+
|
|
273
|
+
## Links
|
|
274
|
+
|
|
275
|
+
```python
|
|
276
|
+
link = clikgate.links.create(destination_url="https://example.com/spring", og_title="Spring sale", og_image_url="https://example.com/og.png")
|
|
277
|
+
result = clikgate.links.update(link["id"], destination_url="https://example.com/summer")
|
|
278
|
+
if not result["applied"]:
|
|
279
|
+
print("waiting for a second person:", result["change_request"]["id"])
|
|
280
|
+
for link in clikgate.links.list(limit=100):
|
|
281
|
+
print(link["short_url"])
|
|
282
|
+
|
|
283
|
+
# Filter by your own link metadata (sent as metadata[seller_id]=sel_ada); analytics take it too.
|
|
284
|
+
for link in clikgate.links.list(metadata={"seller_id": "sel_ada"}):
|
|
285
|
+
print(link["metadata"]["seller_id"])
|
|
286
|
+
ada = clikgate.api.analytics.analytics_summary(var_from="2026-10-01T00:00:00Z", to="2026-11-01T00:00:00Z", metadata={"seller_id": "sel_ada"})
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
A locked link raises `LinkLockedError`. `clikgate.api.<resource>.<operation>()` exposes every other API-key operation ("advanced"), generated from the OpenAPI document and sent through the same pipeline.
|
|
290
|
+
|
|
291
|
+
## Errors
|
|
292
|
+
|
|
293
|
+
Every error extends `ClikgateError` (`code`, `http_status`, `request_id`, `param`, `type`, `raw`): `ConfigurationError`, `AuthenticationError`, `PermissionError`, `InvalidRequestError`, `PrivateModeFieldRejectedError`, `NotFoundError`, `ConflictError`, `LinkLockedError`, `IdempotencyError`, `RateLimitError` (`retry_after`), `ServerError`, `NetworkError`, `TimeoutError` and `SignatureVerificationError`. `PermissionError` and `TimeoutError` are Clikgate's own classes (import them from `clikgate`); they don't extend the built-ins of the same name.
|
|
294
|
+
|
|
295
|
+
Network errors, timeouts and HTTP 429, 500, 502, 503 and 504 are retried up to `max_retries` (3) with full-jitter backoff, honouring `Retry-After`. Each call sends a random `Idempotency-Key`, reused across its retries; the API ignores a second goal event with the same goal and reference, so a retry never double counts.
|
|
296
|
+
|
|
297
|
+
## Options
|
|
298
|
+
|
|
299
|
+
`Clikgate(api_key=None, *, base_url, timeout=10.0, max_retries=3, send_mode="background", private_mode="auto", click_id_param, logger, on_error, http_client, proxy, batch_size=100, flush_interval=1.0, max_queue_size=10_000, shutdown_hooks=True, clock, random)`.
|
|
300
|
+
|
|
301
|
+
- `logger` is `logging.getLogger("clikgate")` by default; warnings carry `extra={"clikgate_code": …}`.
|
|
302
|
+
- `proxy` takes an `http(s)://user:pass@host:port` URL, or `False` to ignore `HTTPS_PROXY`/`NO_PROXY`. `http_client` takes your own `httpx.Client` (mTLS, corporate CAs).
|
|
303
|
+
- An unknown option raises `ConfigurationError`.
|
|
304
|
+
|
|
305
|
+
Licence: MIT. Security: see [SECURITY.md](SECURITY.md).
|