Realign Python SDK with TS SDK#13
Open
nick434434 wants to merge 8 commits into
Open
Conversation
This is not yet including the changes merged to it from #33 and #34
Aligns with TS SDK PR #34 (capture-v2). Emits the richer spoof-detection signals on the analytics event as schema_version 2; the warehouse keeps doing classification at query time — the SDK emits raw signals only. - Portable header signals (read from the httpx Request): sec_fetch_*, sec_ch_ua*, accept, host, has_cookies, and header_names (lowercased, deduped, sorted; edge-injected cf-*/fastly-*/cloudfront-*/x-forwarded-*/ x-real-ip/x-original-request-url stripped — plus the synthesized Host, which httpx adds on construction but the JS fetch Request hides, so the cross-SDK header-name set stays consistent). - Query-string derived signals: query_length, query_param_count, query_suspicious. The raw query is never stored. - CDN plumbing not derivable from the portable Request is supplied by the caller via a new CdnRequestSignals object threaded through HandleRequestContext.cdn_signals (mirrors TS's cdnSignals handler-context field; Python takes the signals from the caller rather than porting the edge handlers). - 512-char truncation on accept / sec_ch_ua / as_organization. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Aligns with TS SDK PR #33 (FastlyLogTransport / logEndpoint). The native Fastly Compute logging transport is intentionally not ported: Python does not run on Fastly Compute (no fastly:logger equivalent), and the Python SDK does not embed CDN edge handlers — it receives CDN signals via HandleRequestContext. Documents the gap and points to the AnalyticsTransport protocol for custom, non-relay delivery. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document the schema_version 2 analytics fields added in the previous commit: the portable header signals (sec_fetch_*, client hints, header_names, …), the query-string derived signals, and the CdnRequestSignals plumbing passed through HandleRequestContext.cdn_signals — mirroring TS SDK PR #34's README. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR realigns the Python SDK’s enforcement semantics and request/analytics behavior with the TypeScript SDK by renaming enforcement modes, adding relay analytics emission (schema v2), and standardizing SDK User-Agent headers across outbound HTTP calls.
Changes:
- Renames merchant enforcement modes to
OBSERVE/ENFORCEand updates handling logic + tests/examples/docs accordingly. - Adds a new
supertab_connect.analyticsmodule (event schema, event builder, IP normalization, transports) and wires analytics emission intoSupertabConnect.handle_request(...)behindanalytics_enabled. - Ensures SDK
User-Agentis sent for JWKS/customer/token/analytics HTTP clients (with added tests).
Reviewed changes
Copilot reviewed 21 out of 22 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/merchant/test_jwks.py | Adds coverage to ensure JWKS fetch requests include SDK User-Agent. |
| tests/merchant/test_client.py | Updates tests for renamed enforcement modes. |
| tests/merchant/test_client_analytics.py | New tests validating analytics emission from SupertabConnect.handle_request. |
| tests/customer/test_tokens.py | Adds coverage to ensure customer HTTP client includes SDK User-Agent. |
| tests/analytics/test_transport.py | New tests for analytics HTTP/noop transports and fire-and-forget behavior. |
| tests/analytics/test_ip.py | New tests for client-IP normalization logic. |
| tests/analytics/test_build_analytics_event.py | New tests for analytics event construction and schema v2 capture rules. |
| tests/analytics/conftest.py | Adds autouse fixture to reset analytics module-level HTTP client between tests. |
| tests/analytics/init.py | Initializes analytics test package. |
| supertab_connect/types.py | Renames enforcement modes; adds analytics config fields and HandleRequestContext. |
| supertab_connect/merchant/jwks.py | Sets SDK User-Agent on the shared JWKS AsyncClient. |
| supertab_connect/merchant/client.py | Wires analytics transport + event emission into handle_request, adds context support. |
| supertab_connect/customer/token.py | Sets SDK User-Agent on the customer AsyncClient used for license.xml/token calls. |
| supertab_connect/analytics/types.py | Defines analytics event schema, transport protocol, and token-outcome mapping. |
| supertab_connect/analytics/transport.py | Implements noop + HTTP relay transports with background task handling. |
| supertab_connect/analytics/ip.py | Adds client-IP normalization helper. |
| supertab_connect/analytics/build_analytics_event.py | Implements request→event builder including capture-v2 signals and truncation rules. |
| supertab_connect/analytics/init.py | Exposes analytics public surface and re-exports key symbols. |
| supertab_connect/init.py | Re-exports analytics types and HandleRequestContext from package root. |
| README.md | Documents updated handle_request semantics and the new analytics feature/configuration. |
| examples/merchant_verify_and_record_event.py | Updates example to use EnforcementMode.OBSERVE. |
| examples/merchant_handle_request.py | Updates example to use EnforcementMode.ENFORCE. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.