trimlynk 1.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.
Files changed (51) hide show
  1. trimlynk-1.0.0/LICENSE +19 -0
  2. trimlynk-1.0.0/PKG-INFO +354 -0
  3. trimlynk-1.0.0/README.md +318 -0
  4. trimlynk-1.0.0/pyproject.toml +75 -0
  5. trimlynk-1.0.0/setup.cfg +4 -0
  6. trimlynk-1.0.0/tests/test_analytics.py +106 -0
  7. trimlynk-1.0.0/tests/test_campaigns.py +247 -0
  8. trimlynk-1.0.0/tests/test_cli.py +622 -0
  9. trimlynk-1.0.0/tests/test_client.py +70 -0
  10. trimlynk-1.0.0/tests/test_conversions.py +145 -0
  11. trimlynk-1.0.0/tests/test_errors.py +209 -0
  12. trimlynk-1.0.0/tests/test_idempotency.py +93 -0
  13. trimlynk-1.0.0/tests/test_links.py +202 -0
  14. trimlynk-1.0.0/tests/test_pagination.py +84 -0
  15. trimlynk-1.0.0/tests/test_security.py +63 -0
  16. trimlynk-1.0.0/tests/test_webhooks.py +255 -0
  17. trimlynk-1.0.0/trimlynk/__init__.py +70 -0
  18. trimlynk-1.0.0/trimlynk/cli/__init__.py +5 -0
  19. trimlynk-1.0.0/trimlynk/cli/commands/__init__.py +61 -0
  20. trimlynk-1.0.0/trimlynk/cli/commands/analytics.py +81 -0
  21. trimlynk-1.0.0/trimlynk/cli/commands/auth.py +113 -0
  22. trimlynk-1.0.0/trimlynk/cli/commands/campaigns.py +204 -0
  23. trimlynk-1.0.0/trimlynk/cli/commands/config.py +56 -0
  24. trimlynk-1.0.0/trimlynk/cli/commands/conversions.py +132 -0
  25. trimlynk-1.0.0/trimlynk/cli/commands/links.py +198 -0
  26. trimlynk-1.0.0/trimlynk/cli/commands/webhooks.py +250 -0
  27. trimlynk-1.0.0/trimlynk/cli/config_store.py +77 -0
  28. trimlynk-1.0.0/trimlynk/cli/credentials.py +156 -0
  29. trimlynk-1.0.0/trimlynk/cli/exit_codes.py +11 -0
  30. trimlynk-1.0.0/trimlynk/cli/formatting.py +131 -0
  31. trimlynk-1.0.0/trimlynk/cli/main.py +437 -0
  32. trimlynk-1.0.0/trimlynk/client.py +85 -0
  33. trimlynk-1.0.0/trimlynk/config.py +78 -0
  34. trimlynk-1.0.0/trimlynk/exceptions.py +182 -0
  35. trimlynk-1.0.0/trimlynk/http.py +181 -0
  36. trimlynk-1.0.0/trimlynk/pagination.py +102 -0
  37. trimlynk-1.0.0/trimlynk/py.typed +1 -0
  38. trimlynk-1.0.0/trimlynk/resources/__init__.py +15 -0
  39. trimlynk-1.0.0/trimlynk/resources/analytics.py +82 -0
  40. trimlynk-1.0.0/trimlynk/resources/campaigns.py +193 -0
  41. trimlynk-1.0.0/trimlynk/resources/conversions.py +133 -0
  42. trimlynk-1.0.0/trimlynk/resources/links.py +176 -0
  43. trimlynk-1.0.0/trimlynk/resources/webhooks.py +222 -0
  44. trimlynk-1.0.0/trimlynk/security.py +107 -0
  45. trimlynk-1.0.0/trimlynk/types.py +465 -0
  46. trimlynk-1.0.0/trimlynk.egg-info/PKG-INFO +354 -0
  47. trimlynk-1.0.0/trimlynk.egg-info/SOURCES.txt +49 -0
  48. trimlynk-1.0.0/trimlynk.egg-info/dependency_links.txt +1 -0
  49. trimlynk-1.0.0/trimlynk.egg-info/entry_points.txt +2 -0
  50. trimlynk-1.0.0/trimlynk.egg-info/requires.txt +8 -0
  51. trimlynk-1.0.0/trimlynk.egg-info/top_level.txt +1 -0
trimlynk-1.0.0/LICENSE ADDED
@@ -0,0 +1,19 @@
1
+ TrimLynk Software Development Kit (SDK) End-User License Agreement
2
+
3
+ Copyright (c) 2026 Vivek Gaur, Ashish Kumar Dwivedi / TrimLynk. All rights reserved.
4
+
5
+ 1. GRANT OF USE
6
+ TrimLynk hereby grants you a personal, worldwide, non-exclusive, non-transferable, revocable license to install, import, and execute this software package in your applications solely for the purpose of integrating with and consuming TrimLynk APIs and services.
7
+
8
+ 2. RESTRICTIONS
9
+ Except as expressly permitted by applicable law, you may not:
10
+ (a) Modify, adapt, translate, reverse engineer, decompile, or disassemble any portion of the software;
11
+ (b) Create derivative works based on the software;
12
+ (c) Rent, lease, loan, resell, sublicense, or distribute modified copies of the software to any third party;
13
+ (d) Remove or obscure any proprietary notices, labels, or marks on the software.
14
+
15
+ 3. INTELLECTUAL PROPERTY
16
+ The software, including its architecture, interfaces, and documentation, constitutes proprietary intellectual property of TrimLynk. No ownership rights are transferred to you.
17
+
18
+ 4. DISCLAIMER OF WARRANTIES
19
+ 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 NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE THEREOF.
@@ -0,0 +1,354 @@
1
+ Metadata-Version: 2.4
2
+ Name: trimlynk
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for the TrimLynk Developer API v1
5
+ Author-email: TrimLynk <support@trimlynk.com>, Vivek Gaur <ankygaur9972@gmail.com>, Ashish Kumar Dwivedi <adpassward709@gmail.com>
6
+ License-Expression: LicenseRef-Proprietary
7
+ Project-URL: Homepage, https://trimlynk.com
8
+ Project-URL: Documentation, https://trimlynk.com/developers/sdks
9
+ Project-URL: API Reference, https://trimlynk.com/api-docs
10
+ Project-URL: Support, https://trimlynk.com/contact
11
+ Keywords: trimlynk,url-shortener,link-management,analytics,webhooks,attribution,developer-api
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Programming Language :: Python :: 3.15
23
+ Classifier: Topic :: Internet :: WWW/HTTP
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.9
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Provides-Extra: dev
30
+ Requires-Dist: pytest>=8.4.0; extra == "dev"
31
+ Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
32
+ Requires-Dist: pip-audit>=2.8.0; extra == "dev"
33
+ Provides-Extra: keyring
34
+ Requires-Dist: keyring>=25.0.0; extra == "keyring"
35
+ Dynamic: license-file
36
+
37
+ # TrimLynk Official Python SDK
38
+
39
+ The official Python client library for the **TrimLynk Developer API v1**.
40
+
41
+ TrimLynk is a modern, privacy-first URL shortening, link intelligence, and attribution platform. This SDK provides programmatic access to link creation, analytics telemetry, conversion funnel tracking, marketing campaigns, and real-time webhook management.
42
+
43
+ [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
44
+ [![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](https://trimlynk.com/terms)
45
+
46
+ ---
47
+
48
+ ## Features
49
+
50
+ * **Zero External Dependencies**: Implemented using the Python standard library. No bloated dependency trees or version conflicts.
51
+ * **Production-Grade Idempotency**: Safe mutations with `idempotency_key` on link, campaign, and webhook operations.
52
+ * **Complete Resource Coverage**: Links, Workspace Analytics, Link Telemetry, Conversion Funnels, Marketing Campaigns, and Webhook Subscriptions.
53
+ * **Automatic Paging**: Stream effortlessly through thousands of records using `resource.iter()` without manual pagination logic.
54
+ * **Strong Type Hints**: Full type annotations and dataclass models throughout for IDE autocompletion and safety.
55
+ * **Transparent Request Tracing**: Access `request_id` directly on every returned model and caught exception.
56
+ * **Structured Error Taxonomy**: Typed exceptions mapping cleanly to HTTP 400, 401, 403, 404, 409, 429, and 500 status codes.
57
+ * **Strict Security**: API keys, credentials, and Authorization headers are masked and never exposed in logs or exception messages.
58
+ * **Official CLI Included**: Installs the production-ready `trimlynk` command-line interface.
59
+
60
+ ---
61
+
62
+ ## Installation
63
+
64
+ ```bash
65
+ pip install trimlynk
66
+ ```
67
+
68
+ Or using `python -m pip`:
69
+
70
+ ```bash
71
+ python -m pip install trimlynk
72
+ ```
73
+
74
+ Installing the package exposes both the Python client library and the `trimlynk` command-line executable. For complete CLI documentation, see [CLI Reference](https://trimlynk.com/developers/sdks).
75
+
76
+ ---
77
+
78
+ ## Quickstart
79
+
80
+ ```python
81
+ from trimlynk import TrimLynk
82
+
83
+ # 1. Initialize with an API key
84
+ client = TrimLynk(api_key="tl_live_your_api_key_here")
85
+
86
+ # 2. Or initialize from the TRIMLYNK_API_KEY environment variable
87
+ # client = TrimLynk()
88
+
89
+ # 3. Create a shortened link
90
+ link = client.links.create(
91
+ original_url="https://example.com/summer-launch?sku=123",
92
+ custom_slug="summer-launch-2026",
93
+ title="Summer Launch 2026",
94
+ tags=["promo", "summer"],
95
+ utm_source="newsletter",
96
+ utm_medium="email",
97
+ utm_campaign="summer_2026",
98
+ )
99
+
100
+ print(f"Short URL: {link.short_url}")
101
+ print(f"Request ID: {link.request_id}")
102
+ ```
103
+
104
+ ---
105
+
106
+ ## Client Configuration
107
+
108
+ ```python
109
+ client = TrimLynk(
110
+ api_key="tl_live_xxx", # Or set via TRIMLYNK_API_KEY
111
+ base_url="https://api.trimlynk.com", # Optional custom endpoint
112
+ environment="live", # "live" or "test"
113
+ timeout=30.0, # Network timeout in seconds (default: 30)
114
+ )
115
+ ```
116
+
117
+ ---
118
+
119
+ ## Resources & Examples
120
+
121
+ ### 1. Links
122
+
123
+ ```python
124
+ # Create a link
125
+ link = client.links.create(
126
+ original_url="https://example.com",
127
+ title="Homepage",
128
+ idempotency_key="unique-op-key-001",
129
+ )
130
+
131
+ # Retrieve a single link
132
+ link = client.links.get(link.id)
133
+
134
+ # Update a link
135
+ updated = client.links.update(
136
+ link.id,
137
+ title="Updated Title",
138
+ is_active=True,
139
+ )
140
+
141
+ # List links with filtering and sorting
142
+ page = client.links.list(page=1, limit=50, tag="promo", sort="latest")
143
+ for l in page:
144
+ print(l.short_url, l.clicks)
145
+
146
+ # Delete a link
147
+ client.links.delete(link.id)
148
+ ```
149
+
150
+ ### 2. Analytics
151
+
152
+ ```python
153
+ # Workspace aggregate metrics
154
+ analytics = client.analytics.get(
155
+ start_date="2026-09-01T00:00:00Z",
156
+ end_date="2026-09-24T00:00:00Z",
157
+ )
158
+ print("Total clicks:", analytics.total_clicks)
159
+ print("Top devices:", analytics.devices)
160
+ print("Top countries:", analytics.countries)
161
+
162
+ # Link-specific telemetry
163
+ link_stats = client.analytics.get_link("clk_link_id")
164
+ print("Clicks for link:", link_stats.clicks)
165
+
166
+ # Conversion funnel metrics (Click -> Lead -> Sale)
167
+ funnel = client.analytics.conversions(url_id="clk_link_id")
168
+ print("Attributed revenue:", funnel.revenue)
169
+ print("Funnel steps:", funnel.metrics)
170
+ ```
171
+
172
+ ### 3. Conversions
173
+
174
+ ```python
175
+ # Ingest an e-commerce or lead conversion event
176
+ conv = client.conversions.create(
177
+ url_id="clk_link_id",
178
+ event_name="purchase",
179
+ event_value=79.99,
180
+ currency="USD",
181
+ customer_id="cust_9876",
182
+ order_id="ord_12345",
183
+ metadata={"plan": "pro"},
184
+ )
185
+
186
+ # List recent conversions
187
+ history = client.conversions.list(page=1, limit=20, event_name="purchase")
188
+ for event in history:
189
+ print(event.event_name, event.event_value, event.created_at)
190
+ ```
191
+
192
+ ### 4. Campaigns
193
+
194
+ ```python
195
+ # Create a marketing campaign with idempotency
196
+ campaign = client.campaigns.create(
197
+ name="Q4 Growth",
198
+ description="Q4 Marketing acquisition drive",
199
+ utm_source="google",
200
+ utm_medium="cpc",
201
+ utm_campaign="q4_growth",
202
+ idempotency_key="camp-q4-growth-01",
203
+ )
204
+
205
+ # List campaigns
206
+ campaigns = client.campaigns.list(page=1, limit=50)
207
+
208
+ # Update campaign
209
+ client.campaigns.update(campaign.id, description="Updated Q4 strategy")
210
+
211
+ # Delete campaign
212
+ client.campaigns.delete(campaign.id)
213
+ ```
214
+
215
+ ### 5. Webhooks
216
+
217
+ ```python
218
+ # Register a webhook endpoint
219
+ hook = client.webhooks.create(
220
+ url="https://api.example.com/trimlynk/webhooks",
221
+ events=["link.created", "link.updated", "click.created", "conversion.created"],
222
+ description="Primary production webhook",
223
+ idempotency_key="whk-setup-01",
224
+ )
225
+
226
+ # NOTE: The signing secret is revealed once upon creation
227
+ print("Webhook signing secret:", hook.secret)
228
+
229
+ # Dispatch a test ping
230
+ test_result = client.webhooks.test(hook.id)
231
+ print("Ping status:", test_result.success)
232
+
233
+ # Inspect delivery logs
234
+ deliveries = client.webhooks.deliveries(hook.id, page=1, limit=10)
235
+ for attempt in deliveries:
236
+ print(attempt.event, attempt.status_code, attempt.duration_ms)
237
+
238
+ # Manually retry a failed delivery
239
+ client.webhooks.retry(hook.id, deliveries[0].id)
240
+ ```
241
+
242
+ ---
243
+
244
+ ## Automatic Pagination
245
+
246
+ All list resources support convenient auto-paging via `.iter()`:
247
+
248
+ ```python
249
+ # Seamlessly streams across all pages (max 100 items per batch)
250
+ for link in client.links.iter(limit=100, tag="summer"):
251
+ print(link.short_url)
252
+
253
+ for conversion in client.conversions.iter():
254
+ print(conversion.event_name, conversion.event_value)
255
+
256
+ for webhook in client.webhooks.iter():
257
+ print(webhook.url)
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Idempotency
263
+
264
+ Mutating endpoints (`POST /links`, `POST /campaigns`, `POST /webhooks`) accept an optional `idempotency_key`.
265
+
266
+ ```python
267
+ # Sending the initial request
268
+ link = client.links.create(
269
+ original_url="https://example.com/checkout",
270
+ idempotency_key="order_98124_link",
271
+ )
272
+ print("Replayed:", link.idempotent_replay) # None or False
273
+
274
+ # Retrying with the identical key returns the cached response
275
+ replayed = client.links.create(
276
+ original_url="https://example.com/checkout",
277
+ idempotency_key="order_98124_link",
278
+ )
279
+ print("Replayed:", replayed.idempotent_replay) # True
280
+ assert link.id == replayed.id
281
+ ```
282
+
283
+ If an existing key is reused with a different request body, the SDK raises `IdempotencyConflictError` (HTTP 409).
284
+
285
+ ---
286
+
287
+ ## Error Handling
288
+
289
+ The SDK maps all HTTP and network errors into a clean, typed hierarchy:
290
+
291
+ ```text
292
+ TrimLynkError
293
+ ├── APIError
294
+ │ ├── InvalidRequestError (HTTP 400)
295
+ │ ├── AuthenticationError (HTTP 401)
296
+ │ ├── PermissionError (HTTP 403)
297
+ │ ├── NotFoundError (HTTP 404)
298
+ │ ├── ConflictError (HTTP 409)
299
+ │ │ └── IdempotencyConflictError
300
+ │ ├── RateLimitError (HTTP 429)
301
+ │ └── InternalServerError (HTTP 500)
302
+ ├── NetworkError
303
+ └── TimeoutError
304
+ ```
305
+
306
+ ### Example:
307
+
308
+ ```python
309
+ from trimlynk import (
310
+ TrimLynk,
311
+ InvalidRequestError,
312
+ AuthenticationError,
313
+ RateLimitError,
314
+ IdempotencyConflictError,
315
+ TrimLynkError,
316
+ )
317
+
318
+ client = TrimLynk()
319
+
320
+ try:
321
+ client.links.create(original_url="https://example.com")
322
+
323
+ except InvalidRequestError as e:
324
+ print(f"Validation error ({e.code}): {e.message}")
325
+ print("Field violation:", e.details)
326
+ print("Request ID:", e.request_id)
327
+
328
+ except RateLimitError as e:
329
+ print(f"Rate limited: retry after {e.retry_after} seconds")
330
+ print("Request ID:", e.request_id)
331
+
332
+ except IdempotencyConflictError as e:
333
+ print(f"Idempotency key collision: {e.message}")
334
+
335
+ except AuthenticationError as e:
336
+ print("Invalid or revoked API key.")
337
+
338
+ except TrimLynkError as e:
339
+ print(f"General error: {e}")
340
+ ```
341
+
342
+ ---
343
+
344
+ ## Security
345
+
346
+ * **HTTPS Enforcement**: Default connection uses TLS (`https://api.trimlynk.com`).
347
+ * **Secret Protection**: API keys and Authorization headers are masked in `repr()` and omitted from all serialized dictionaries and error messages.
348
+ * **Zero Dependency Risk**: Built exclusively on standard Python modules to guarantee supply chain integrity.
349
+
350
+ ---
351
+
352
+ ## License
353
+
354
+ Proprietary License (All Rights Reserved). See the bundled [LICENSE](LICENSE) file for complete terms of use.
@@ -0,0 +1,318 @@
1
+ # TrimLynk Official Python SDK
2
+
3
+ The official Python client library for the **TrimLynk Developer API v1**.
4
+
5
+ TrimLynk is a modern, privacy-first URL shortening, link intelligence, and attribution platform. This SDK provides programmatic access to link creation, analytics telemetry, conversion funnel tracking, marketing campaigns, and real-time webhook management.
6
+
7
+ [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
8
+ [![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](https://trimlynk.com/terms)
9
+
10
+ ---
11
+
12
+ ## Features
13
+
14
+ * **Zero External Dependencies**: Implemented using the Python standard library. No bloated dependency trees or version conflicts.
15
+ * **Production-Grade Idempotency**: Safe mutations with `idempotency_key` on link, campaign, and webhook operations.
16
+ * **Complete Resource Coverage**: Links, Workspace Analytics, Link Telemetry, Conversion Funnels, Marketing Campaigns, and Webhook Subscriptions.
17
+ * **Automatic Paging**: Stream effortlessly through thousands of records using `resource.iter()` without manual pagination logic.
18
+ * **Strong Type Hints**: Full type annotations and dataclass models throughout for IDE autocompletion and safety.
19
+ * **Transparent Request Tracing**: Access `request_id` directly on every returned model and caught exception.
20
+ * **Structured Error Taxonomy**: Typed exceptions mapping cleanly to HTTP 400, 401, 403, 404, 409, 429, and 500 status codes.
21
+ * **Strict Security**: API keys, credentials, and Authorization headers are masked and never exposed in logs or exception messages.
22
+ * **Official CLI Included**: Installs the production-ready `trimlynk` command-line interface.
23
+
24
+ ---
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pip install trimlynk
30
+ ```
31
+
32
+ Or using `python -m pip`:
33
+
34
+ ```bash
35
+ python -m pip install trimlynk
36
+ ```
37
+
38
+ Installing the package exposes both the Python client library and the `trimlynk` command-line executable. For complete CLI documentation, see [CLI Reference](https://trimlynk.com/developers/sdks).
39
+
40
+ ---
41
+
42
+ ## Quickstart
43
+
44
+ ```python
45
+ from trimlynk import TrimLynk
46
+
47
+ # 1. Initialize with an API key
48
+ client = TrimLynk(api_key="tl_live_your_api_key_here")
49
+
50
+ # 2. Or initialize from the TRIMLYNK_API_KEY environment variable
51
+ # client = TrimLynk()
52
+
53
+ # 3. Create a shortened link
54
+ link = client.links.create(
55
+ original_url="https://example.com/summer-launch?sku=123",
56
+ custom_slug="summer-launch-2026",
57
+ title="Summer Launch 2026",
58
+ tags=["promo", "summer"],
59
+ utm_source="newsletter",
60
+ utm_medium="email",
61
+ utm_campaign="summer_2026",
62
+ )
63
+
64
+ print(f"Short URL: {link.short_url}")
65
+ print(f"Request ID: {link.request_id}")
66
+ ```
67
+
68
+ ---
69
+
70
+ ## Client Configuration
71
+
72
+ ```python
73
+ client = TrimLynk(
74
+ api_key="tl_live_xxx", # Or set via TRIMLYNK_API_KEY
75
+ base_url="https://api.trimlynk.com", # Optional custom endpoint
76
+ environment="live", # "live" or "test"
77
+ timeout=30.0, # Network timeout in seconds (default: 30)
78
+ )
79
+ ```
80
+
81
+ ---
82
+
83
+ ## Resources & Examples
84
+
85
+ ### 1. Links
86
+
87
+ ```python
88
+ # Create a link
89
+ link = client.links.create(
90
+ original_url="https://example.com",
91
+ title="Homepage",
92
+ idempotency_key="unique-op-key-001",
93
+ )
94
+
95
+ # Retrieve a single link
96
+ link = client.links.get(link.id)
97
+
98
+ # Update a link
99
+ updated = client.links.update(
100
+ link.id,
101
+ title="Updated Title",
102
+ is_active=True,
103
+ )
104
+
105
+ # List links with filtering and sorting
106
+ page = client.links.list(page=1, limit=50, tag="promo", sort="latest")
107
+ for l in page:
108
+ print(l.short_url, l.clicks)
109
+
110
+ # Delete a link
111
+ client.links.delete(link.id)
112
+ ```
113
+
114
+ ### 2. Analytics
115
+
116
+ ```python
117
+ # Workspace aggregate metrics
118
+ analytics = client.analytics.get(
119
+ start_date="2026-09-01T00:00:00Z",
120
+ end_date="2026-09-24T00:00:00Z",
121
+ )
122
+ print("Total clicks:", analytics.total_clicks)
123
+ print("Top devices:", analytics.devices)
124
+ print("Top countries:", analytics.countries)
125
+
126
+ # Link-specific telemetry
127
+ link_stats = client.analytics.get_link("clk_link_id")
128
+ print("Clicks for link:", link_stats.clicks)
129
+
130
+ # Conversion funnel metrics (Click -> Lead -> Sale)
131
+ funnel = client.analytics.conversions(url_id="clk_link_id")
132
+ print("Attributed revenue:", funnel.revenue)
133
+ print("Funnel steps:", funnel.metrics)
134
+ ```
135
+
136
+ ### 3. Conversions
137
+
138
+ ```python
139
+ # Ingest an e-commerce or lead conversion event
140
+ conv = client.conversions.create(
141
+ url_id="clk_link_id",
142
+ event_name="purchase",
143
+ event_value=79.99,
144
+ currency="USD",
145
+ customer_id="cust_9876",
146
+ order_id="ord_12345",
147
+ metadata={"plan": "pro"},
148
+ )
149
+
150
+ # List recent conversions
151
+ history = client.conversions.list(page=1, limit=20, event_name="purchase")
152
+ for event in history:
153
+ print(event.event_name, event.event_value, event.created_at)
154
+ ```
155
+
156
+ ### 4. Campaigns
157
+
158
+ ```python
159
+ # Create a marketing campaign with idempotency
160
+ campaign = client.campaigns.create(
161
+ name="Q4 Growth",
162
+ description="Q4 Marketing acquisition drive",
163
+ utm_source="google",
164
+ utm_medium="cpc",
165
+ utm_campaign="q4_growth",
166
+ idempotency_key="camp-q4-growth-01",
167
+ )
168
+
169
+ # List campaigns
170
+ campaigns = client.campaigns.list(page=1, limit=50)
171
+
172
+ # Update campaign
173
+ client.campaigns.update(campaign.id, description="Updated Q4 strategy")
174
+
175
+ # Delete campaign
176
+ client.campaigns.delete(campaign.id)
177
+ ```
178
+
179
+ ### 5. Webhooks
180
+
181
+ ```python
182
+ # Register a webhook endpoint
183
+ hook = client.webhooks.create(
184
+ url="https://api.example.com/trimlynk/webhooks",
185
+ events=["link.created", "link.updated", "click.created", "conversion.created"],
186
+ description="Primary production webhook",
187
+ idempotency_key="whk-setup-01",
188
+ )
189
+
190
+ # NOTE: The signing secret is revealed once upon creation
191
+ print("Webhook signing secret:", hook.secret)
192
+
193
+ # Dispatch a test ping
194
+ test_result = client.webhooks.test(hook.id)
195
+ print("Ping status:", test_result.success)
196
+
197
+ # Inspect delivery logs
198
+ deliveries = client.webhooks.deliveries(hook.id, page=1, limit=10)
199
+ for attempt in deliveries:
200
+ print(attempt.event, attempt.status_code, attempt.duration_ms)
201
+
202
+ # Manually retry a failed delivery
203
+ client.webhooks.retry(hook.id, deliveries[0].id)
204
+ ```
205
+
206
+ ---
207
+
208
+ ## Automatic Pagination
209
+
210
+ All list resources support convenient auto-paging via `.iter()`:
211
+
212
+ ```python
213
+ # Seamlessly streams across all pages (max 100 items per batch)
214
+ for link in client.links.iter(limit=100, tag="summer"):
215
+ print(link.short_url)
216
+
217
+ for conversion in client.conversions.iter():
218
+ print(conversion.event_name, conversion.event_value)
219
+
220
+ for webhook in client.webhooks.iter():
221
+ print(webhook.url)
222
+ ```
223
+
224
+ ---
225
+
226
+ ## Idempotency
227
+
228
+ Mutating endpoints (`POST /links`, `POST /campaigns`, `POST /webhooks`) accept an optional `idempotency_key`.
229
+
230
+ ```python
231
+ # Sending the initial request
232
+ link = client.links.create(
233
+ original_url="https://example.com/checkout",
234
+ idempotency_key="order_98124_link",
235
+ )
236
+ print("Replayed:", link.idempotent_replay) # None or False
237
+
238
+ # Retrying with the identical key returns the cached response
239
+ replayed = client.links.create(
240
+ original_url="https://example.com/checkout",
241
+ idempotency_key="order_98124_link",
242
+ )
243
+ print("Replayed:", replayed.idempotent_replay) # True
244
+ assert link.id == replayed.id
245
+ ```
246
+
247
+ If an existing key is reused with a different request body, the SDK raises `IdempotencyConflictError` (HTTP 409).
248
+
249
+ ---
250
+
251
+ ## Error Handling
252
+
253
+ The SDK maps all HTTP and network errors into a clean, typed hierarchy:
254
+
255
+ ```text
256
+ TrimLynkError
257
+ ├── APIError
258
+ │ ├── InvalidRequestError (HTTP 400)
259
+ │ ├── AuthenticationError (HTTP 401)
260
+ │ ├── PermissionError (HTTP 403)
261
+ │ ├── NotFoundError (HTTP 404)
262
+ │ ├── ConflictError (HTTP 409)
263
+ │ │ └── IdempotencyConflictError
264
+ │ ├── RateLimitError (HTTP 429)
265
+ │ └── InternalServerError (HTTP 500)
266
+ ├── NetworkError
267
+ └── TimeoutError
268
+ ```
269
+
270
+ ### Example:
271
+
272
+ ```python
273
+ from trimlynk import (
274
+ TrimLynk,
275
+ InvalidRequestError,
276
+ AuthenticationError,
277
+ RateLimitError,
278
+ IdempotencyConflictError,
279
+ TrimLynkError,
280
+ )
281
+
282
+ client = TrimLynk()
283
+
284
+ try:
285
+ client.links.create(original_url="https://example.com")
286
+
287
+ except InvalidRequestError as e:
288
+ print(f"Validation error ({e.code}): {e.message}")
289
+ print("Field violation:", e.details)
290
+ print("Request ID:", e.request_id)
291
+
292
+ except RateLimitError as e:
293
+ print(f"Rate limited: retry after {e.retry_after} seconds")
294
+ print("Request ID:", e.request_id)
295
+
296
+ except IdempotencyConflictError as e:
297
+ print(f"Idempotency key collision: {e.message}")
298
+
299
+ except AuthenticationError as e:
300
+ print("Invalid or revoked API key.")
301
+
302
+ except TrimLynkError as e:
303
+ print(f"General error: {e}")
304
+ ```
305
+
306
+ ---
307
+
308
+ ## Security
309
+
310
+ * **HTTPS Enforcement**: Default connection uses TLS (`https://api.trimlynk.com`).
311
+ * **Secret Protection**: API keys and Authorization headers are masked in `repr()` and omitted from all serialized dictionaries and error messages.
312
+ * **Zero Dependency Risk**: Built exclusively on standard Python modules to guarantee supply chain integrity.
313
+
314
+ ---
315
+
316
+ ## License
317
+
318
+ Proprietary License (All Rights Reserved). See the bundled [LICENSE](LICENSE) file for complete terms of use.