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.
- trimlynk-1.0.0/LICENSE +19 -0
- trimlynk-1.0.0/PKG-INFO +354 -0
- trimlynk-1.0.0/README.md +318 -0
- trimlynk-1.0.0/pyproject.toml +75 -0
- trimlynk-1.0.0/setup.cfg +4 -0
- trimlynk-1.0.0/tests/test_analytics.py +106 -0
- trimlynk-1.0.0/tests/test_campaigns.py +247 -0
- trimlynk-1.0.0/tests/test_cli.py +622 -0
- trimlynk-1.0.0/tests/test_client.py +70 -0
- trimlynk-1.0.0/tests/test_conversions.py +145 -0
- trimlynk-1.0.0/tests/test_errors.py +209 -0
- trimlynk-1.0.0/tests/test_idempotency.py +93 -0
- trimlynk-1.0.0/tests/test_links.py +202 -0
- trimlynk-1.0.0/tests/test_pagination.py +84 -0
- trimlynk-1.0.0/tests/test_security.py +63 -0
- trimlynk-1.0.0/tests/test_webhooks.py +255 -0
- trimlynk-1.0.0/trimlynk/__init__.py +70 -0
- trimlynk-1.0.0/trimlynk/cli/__init__.py +5 -0
- trimlynk-1.0.0/trimlynk/cli/commands/__init__.py +61 -0
- trimlynk-1.0.0/trimlynk/cli/commands/analytics.py +81 -0
- trimlynk-1.0.0/trimlynk/cli/commands/auth.py +113 -0
- trimlynk-1.0.0/trimlynk/cli/commands/campaigns.py +204 -0
- trimlynk-1.0.0/trimlynk/cli/commands/config.py +56 -0
- trimlynk-1.0.0/trimlynk/cli/commands/conversions.py +132 -0
- trimlynk-1.0.0/trimlynk/cli/commands/links.py +198 -0
- trimlynk-1.0.0/trimlynk/cli/commands/webhooks.py +250 -0
- trimlynk-1.0.0/trimlynk/cli/config_store.py +77 -0
- trimlynk-1.0.0/trimlynk/cli/credentials.py +156 -0
- trimlynk-1.0.0/trimlynk/cli/exit_codes.py +11 -0
- trimlynk-1.0.0/trimlynk/cli/formatting.py +131 -0
- trimlynk-1.0.0/trimlynk/cli/main.py +437 -0
- trimlynk-1.0.0/trimlynk/client.py +85 -0
- trimlynk-1.0.0/trimlynk/config.py +78 -0
- trimlynk-1.0.0/trimlynk/exceptions.py +182 -0
- trimlynk-1.0.0/trimlynk/http.py +181 -0
- trimlynk-1.0.0/trimlynk/pagination.py +102 -0
- trimlynk-1.0.0/trimlynk/py.typed +1 -0
- trimlynk-1.0.0/trimlynk/resources/__init__.py +15 -0
- trimlynk-1.0.0/trimlynk/resources/analytics.py +82 -0
- trimlynk-1.0.0/trimlynk/resources/campaigns.py +193 -0
- trimlynk-1.0.0/trimlynk/resources/conversions.py +133 -0
- trimlynk-1.0.0/trimlynk/resources/links.py +176 -0
- trimlynk-1.0.0/trimlynk/resources/webhooks.py +222 -0
- trimlynk-1.0.0/trimlynk/security.py +107 -0
- trimlynk-1.0.0/trimlynk/types.py +465 -0
- trimlynk-1.0.0/trimlynk.egg-info/PKG-INFO +354 -0
- trimlynk-1.0.0/trimlynk.egg-info/SOURCES.txt +49 -0
- trimlynk-1.0.0/trimlynk.egg-info/dependency_links.txt +1 -0
- trimlynk-1.0.0/trimlynk.egg-info/entry_points.txt +2 -0
- trimlynk-1.0.0/trimlynk.egg-info/requires.txt +8 -0
- 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.
|
trimlynk-1.0.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://python.org)
|
|
44
|
+
[](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.
|
trimlynk-1.0.0/README.md
ADDED
|
@@ -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
|
+
[](https://python.org)
|
|
8
|
+
[](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.
|