trimlynk 1.0.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,70 @@
1
+ """TrimLynk Python SDK - Official client library for the TrimLynk Developer API v1."""
2
+
3
+ from .client import TrimLynk
4
+ from .config import TrimLynkConfig
5
+ from .exceptions import (
6
+ APIError,
7
+ AuthenticationError,
8
+ ConflictError,
9
+ IdempotencyConflictError,
10
+ InternalServerError,
11
+ InvalidRequestError,
12
+ NetworkError,
13
+ NotFoundError,
14
+ PermissionError,
15
+ RateLimitError,
16
+ TimeoutError,
17
+ TrimLynkError,
18
+ )
19
+ from .pagination import AutoPagingIterator, PaginatedList
20
+ from .security import verify_webhook_signature
21
+ from .types import (
22
+ AnalyticsSummary,
23
+ Campaign,
24
+ Conversion,
25
+ DeleteResult,
26
+ FunnelAnalytics,
27
+ Link,
28
+ LinkAnalytics,
29
+ PaginationMetadata,
30
+ TestWebhookResult,
31
+ Webhook,
32
+ WebhookDelivery,
33
+ )
34
+
35
+ __version__ = "1.0.0"
36
+
37
+ __all__ = [
38
+ "TrimLynk",
39
+ "TrimLynkConfig",
40
+ "__version__",
41
+ "verify_webhook_signature",
42
+ # Pagination
43
+ "AutoPagingIterator",
44
+ "PaginatedList",
45
+ "PaginationMetadata",
46
+ # Types
47
+ "AnalyticsSummary",
48
+ "Campaign",
49
+ "Conversion",
50
+ "DeleteResult",
51
+ "FunnelAnalytics",
52
+ "Link",
53
+ "LinkAnalytics",
54
+ "TestWebhookResult",
55
+ "Webhook",
56
+ "WebhookDelivery",
57
+ # Exceptions
58
+ "APIError",
59
+ "AuthenticationError",
60
+ "ConflictError",
61
+ "IdempotencyConflictError",
62
+ "InternalServerError",
63
+ "InvalidRequestError",
64
+ "NetworkError",
65
+ "NotFoundError",
66
+ "PermissionError",
67
+ "RateLimitError",
68
+ "TimeoutError",
69
+ "TrimLynkError",
70
+ ]
@@ -0,0 +1,5 @@
1
+ """TrimLynk Command Line Interface package."""
2
+
3
+ from .main import cli_entrypoint, main as run_cli
4
+
5
+ __all__ = ["cli_entrypoint", "run_cli"]
@@ -0,0 +1,61 @@
1
+ """CLI command handlers package."""
2
+
3
+ from .analytics import cmd_analytics_link, cmd_analytics_summary
4
+ from .auth import cmd_login, cmd_logout, cmd_status
5
+ from .campaigns import (
6
+ cmd_campaigns_create,
7
+ cmd_campaigns_delete,
8
+ cmd_campaigns_get,
9
+ cmd_campaigns_list,
10
+ cmd_campaigns_update,
11
+ )
12
+ from .config import cmd_config_get, cmd_config_set
13
+ from .conversions import cmd_conversions_create, cmd_conversions_get, cmd_conversions_list
14
+ from .links import (
15
+ cmd_links_create,
16
+ cmd_links_delete,
17
+ cmd_links_get,
18
+ cmd_links_list,
19
+ cmd_links_update,
20
+ )
21
+ from .webhooks import (
22
+ cmd_webhooks_create,
23
+ cmd_webhooks_delete,
24
+ cmd_webhooks_deliveries,
25
+ cmd_webhooks_get,
26
+ cmd_webhooks_list,
27
+ cmd_webhooks_retry,
28
+ cmd_webhooks_test,
29
+ cmd_webhooks_update,
30
+ )
31
+
32
+ __all__ = [
33
+ "cmd_analytics_link",
34
+ "cmd_analytics_summary",
35
+ "cmd_campaigns_create",
36
+ "cmd_campaigns_delete",
37
+ "cmd_campaigns_get",
38
+ "cmd_campaigns_list",
39
+ "cmd_campaigns_update",
40
+ "cmd_config_get",
41
+ "cmd_config_set",
42
+ "cmd_conversions_create",
43
+ "cmd_conversions_get",
44
+ "cmd_conversions_list",
45
+ "cmd_links_create",
46
+ "cmd_links_delete",
47
+ "cmd_links_get",
48
+ "cmd_links_list",
49
+ "cmd_links_update",
50
+ "cmd_login",
51
+ "cmd_logout",
52
+ "cmd_status",
53
+ "cmd_webhooks_create",
54
+ "cmd_webhooks_delete",
55
+ "cmd_webhooks_deliveries",
56
+ "cmd_webhooks_get",
57
+ "cmd_webhooks_list",
58
+ "cmd_webhooks_retry",
59
+ "cmd_webhooks_test",
60
+ "cmd_webhooks_update",
61
+ ]
@@ -0,0 +1,81 @@
1
+ """Analytics commands for TrimLynk CLI."""
2
+
3
+ from typing import Any, Callable
4
+
5
+ from ..exit_codes import EXIT_SUCCESS
6
+ from ..formatting import output_json, print_details, print_table
7
+
8
+
9
+ def cmd_analytics_summary(args: Any, get_client: Callable[..., Any]) -> int:
10
+ """Retrieve workspace aggregate analytics."""
11
+ client = get_client()
12
+ summary = client.analytics.get(
13
+ start_date=args.start_date,
14
+ end_date=args.end_date,
15
+ url_id=args.url_id,
16
+ )
17
+
18
+ if args.quiet:
19
+ print(summary.total_clicks)
20
+ elif args.json:
21
+ output_json(summary)
22
+ else:
23
+ print("Workspace Analytics Summary\n")
24
+ print_details([
25
+ ("Total Clicks:", f"{summary.total_clicks:,}"),
26
+ ("Unique Visitors:", f"{summary.unique_visitors:,}"),
27
+ ("Request ID:", summary.request_id),
28
+ ])
29
+
30
+ if summary.devices:
31
+ print("\nTop Devices:")
32
+ dev_rows = [[str(k), f"{int(v):,}"] for k, v in summary.devices.items()]
33
+ print_table(["DEVICE", "CLICKS"], dev_rows)
34
+
35
+ if summary.countries:
36
+ print("\nTop Countries:")
37
+ geo_rows = [[str(k), f"{int(v):,}"] for k, v in summary.countries.items()]
38
+ print_table(["COUNTRY", "CLICKS"], geo_rows)
39
+
40
+ return EXIT_SUCCESS
41
+
42
+
43
+ def cmd_analytics_link(args: Any, get_client: Callable[..., Any]) -> int:
44
+ """Retrieve click breakdown for a specific link."""
45
+ client = get_client()
46
+ stats = client.analytics.get_link(
47
+ link_id=args.link_id,
48
+ start_date=args.start_date,
49
+ end_date=args.end_date,
50
+ )
51
+
52
+ if args.quiet:
53
+ print(stats.clicks)
54
+ elif args.json:
55
+ output_json(stats)
56
+ else:
57
+ print(f"Analytics for Link: {stats.link_id}\n")
58
+ print_details([
59
+ ("Link ID:", stats.link_id),
60
+ ("Total Clicks:", f"{stats.clicks:,}"),
61
+ ("Request ID:", stats.request_id),
62
+ ])
63
+
64
+ raw = stats.raw
65
+ if "browsers" in raw:
66
+ browsers_val = raw["browsers"]
67
+ b_rows = []
68
+ if isinstance(browsers_val, list):
69
+ b_rows = [
70
+ [str(b.get("browser", "Unknown")), f"{int(b.get('count', 0)):,}"]
71
+ for b in browsers_val
72
+ if isinstance(b, dict)
73
+ ]
74
+ elif isinstance(browsers_val, dict):
75
+ b_rows = [[str(k), f"{int(v):,}"] for k, v in browsers_val.items()]
76
+
77
+ if b_rows:
78
+ print("\nBrowsers:")
79
+ print_table(["BROWSER", "CLICKS"], b_rows)
80
+
81
+ return EXIT_SUCCESS
@@ -0,0 +1,113 @@
1
+ """Authentication commands for TrimLynk CLI."""
2
+
3
+ import getpass
4
+ import sys
5
+ from typing import Any, Callable
6
+
7
+ from ...exceptions import AuthenticationError, TrimLynkError
8
+ from ..credentials import (
9
+ delete_api_key,
10
+ get_credential_source,
11
+ mask_api_key,
12
+ resolve_api_key,
13
+ save_api_key,
14
+ )
15
+ from ..exit_codes import EXIT_AUTHENTICATION_ERROR, EXIT_GENERAL_ERROR, EXIT_SUCCESS
16
+ from ..formatting import green, output_json, print_details, print_error
17
+
18
+
19
+ def cmd_login(args: Any, get_client: Callable[..., Any]) -> int:
20
+ """Prompt for API key, validate it via SDK, and store it securely."""
21
+ api_key = args.api_key
22
+ if not api_key:
23
+ if not sys.stdin.isatty():
24
+ print_error("Cannot prompt for API key in non-interactive environment. Use TRIMLYNK_API_KEY or --api-key.")
25
+ return EXIT_AUTHENTICATION_ERROR
26
+ try:
27
+ api_key = getpass.getpass("TrimLynk API key: ").strip()
28
+ except (KeyboardInterrupt, EOFError):
29
+ print("\nAborted.")
30
+ return EXIT_GENERAL_ERROR
31
+
32
+ if not api_key:
33
+ print_error("API key cannot be empty.")
34
+ return EXIT_AUTHENTICATION_ERROR
35
+
36
+ # Validate key against Developer API via SDK
37
+ try:
38
+ client = get_client(api_key=api_key)
39
+ client.links.list(limit=1)
40
+ except AuthenticationError as e:
41
+ print_error(f"Authentication failed: {e.message}", code=e.code, request_id=e.request_id)
42
+ return EXIT_AUTHENTICATION_ERROR
43
+ except TrimLynkError as e:
44
+ print_error(f"Failed to verify API key: {e}")
45
+ return EXIT_GENERAL_ERROR
46
+
47
+ save_api_key(api_key)
48
+
49
+ if args.json:
50
+ output_json({
51
+ "authenticated": True,
52
+ "masked_key": mask_api_key(api_key),
53
+ "environment": args.environment or "live",
54
+ })
55
+ elif not args.quiet:
56
+ print(green("✓ Successfully authenticated with TrimLynk"))
57
+ print(f"Stored API Key: {mask_api_key(api_key)}")
58
+
59
+ return EXIT_SUCCESS
60
+
61
+
62
+ def cmd_logout(args: Any, _get_client: Callable[..., Any]) -> int:
63
+ """Remove saved API credentials."""
64
+ removed = delete_api_key()
65
+
66
+ if args.json:
67
+ output_json({"logged_out": True, "credentials_removed": removed})
68
+ elif not args.quiet:
69
+ if removed:
70
+ print(green("✓ Successfully logged out from TrimLynk"))
71
+ else:
72
+ print("No stored credentials found.")
73
+
74
+ return EXIT_SUCCESS
75
+
76
+
77
+ def cmd_status(args: Any, get_client: Callable[..., Any]) -> int:
78
+ """Display current authentication configuration."""
79
+ api_key = resolve_api_key(args.api_key)
80
+ env = args.environment or "live"
81
+ source = get_credential_source(args.api_key)
82
+
83
+ remote_status = "not checked"
84
+ if args.check and api_key:
85
+ try:
86
+ client = get_client(api_key=api_key)
87
+ client.links.list(limit=1)
88
+ remote_status = "valid"
89
+ except AuthenticationError:
90
+ remote_status = "invalid / expired"
91
+ except Exception as e:
92
+ remote_status = f"error checking ({e})"
93
+
94
+ if args.json:
95
+ output_json({
96
+ "authenticated": bool(api_key),
97
+ "environment": env,
98
+ "api_key": mask_api_key(api_key),
99
+ "source": source,
100
+ "remote_status": remote_status,
101
+ "api_version": "1",
102
+ })
103
+ else:
104
+ print_details([
105
+ ("Authenticated:", "yes" if api_key else "no"),
106
+ ("Environment:", env),
107
+ ("API Key:", mask_api_key(api_key)),
108
+ ("Source:", source),
109
+ ("Remote Status:", remote_status),
110
+ ("API Version:", "1"),
111
+ ])
112
+
113
+ return EXIT_SUCCESS
@@ -0,0 +1,204 @@
1
+ """Campaigns commands for TrimLynk CLI."""
2
+
3
+ from typing import Any, Callable
4
+
5
+ from ..exit_codes import EXIT_INVALID_ARGS, EXIT_SUCCESS
6
+ from ..formatting import confirm_action, output_json, print_details, print_error, print_table
7
+
8
+
9
+ def cmd_campaigns_create(args: Any, get_client: Callable[..., Any]) -> int:
10
+ """Create a new marketing campaign."""
11
+ client = get_client()
12
+ campaign = client.campaigns.create(
13
+ name=args.name,
14
+ description=getattr(args, "description", None),
15
+ color=getattr(args, "color", None),
16
+ icon=getattr(args, "icon", None),
17
+ status=getattr(args, "status", None),
18
+ goal=getattr(args, "goal", None),
19
+ budget=getattr(args, "budget", None),
20
+ start_date=getattr(args, "start_date", None),
21
+ end_date=getattr(args, "end_date", None),
22
+ utm_source=getattr(args, "utm_source", None),
23
+ utm_medium=getattr(args, "utm_medium", None),
24
+ utm_campaign=getattr(args, "utm_campaign", None),
25
+ idempotency_key=getattr(args, "idempotency_key", None),
26
+ )
27
+
28
+ if args.quiet:
29
+ print(campaign.id)
30
+ elif args.json:
31
+ output_json(campaign)
32
+ else:
33
+ print(f"✓ Campaign created: {campaign.name}\n")
34
+ print_details([
35
+ ("ID:", campaign.id),
36
+ ("Name:", campaign.name),
37
+ ("Description:", campaign.description or "(none)"),
38
+ ("Status:", campaign.status or "(none)"),
39
+ ("Color:", campaign.color or "(none)"),
40
+ ("Icon:", campaign.icon or "(none)"),
41
+ ("UTM Source:", campaign.utm_source or "(none)"),
42
+ ("UTM Medium:", campaign.utm_medium or "(none)"),
43
+ ("UTM Campaign:", campaign.utm_campaign or "(none)"),
44
+ ("Request ID:", campaign.request_id),
45
+ ])
46
+
47
+ return EXIT_SUCCESS
48
+
49
+
50
+ def cmd_campaigns_list(args: Any, get_client: Callable[..., Any]) -> int:
51
+ """List marketing campaigns."""
52
+ client = get_client()
53
+
54
+ if getattr(args, "all", False):
55
+ items = list(client.campaigns.iter(limit=args.limit or 50))
56
+ if args.quiet:
57
+ for item in items:
58
+ print(item.id)
59
+ elif args.json:
60
+ output_json([item.to_dict() for item in items])
61
+ else:
62
+ rows = [
63
+ [item.id, item.name, item.utm_campaign or "-", item.created_at or "-"]
64
+ for item in items
65
+ ]
66
+ print_table(["ID", "NAME", "UTM CAMPAIGN", "CREATED AT"], rows)
67
+ print(f"\nTotal: {len(items)} campaigns (streamed)")
68
+ return EXIT_SUCCESS
69
+
70
+ page = client.campaigns.list(
71
+ page=args.page or 1,
72
+ limit=args.limit or 50,
73
+ )
74
+
75
+ if args.quiet:
76
+ for item in page:
77
+ print(item.id)
78
+ elif args.json:
79
+ output_json(page)
80
+ else:
81
+ rows = [
82
+ [item.id, item.name, item.utm_campaign or "-", item.created_at or "-"]
83
+ for item in page
84
+ ]
85
+ print_table(["ID", "NAME", "UTM CAMPAIGN", "CREATED AT"], rows)
86
+
87
+ p = page.pagination
88
+ start = (p.page - 1) * p.limit + 1 if p.total > 0 else 0
89
+ end = min(p.page * p.limit, p.total)
90
+ print(f"\nShowing {start}–{end} of {p.total} (Page {p.page} of {p.total_pages})")
91
+
92
+ return EXIT_SUCCESS
93
+
94
+
95
+ def cmd_campaigns_get(args: Any, get_client: Callable[..., Any]) -> int:
96
+ """Retrieve details for a single campaign."""
97
+ client = get_client()
98
+ c = client.campaigns.get(args.campaign_id)
99
+
100
+ if args.quiet:
101
+ print(c.id)
102
+ elif args.json:
103
+ output_json(c)
104
+ else:
105
+ print_details([
106
+ ("ID:", c.id),
107
+ ("Name:", c.name),
108
+ ("Description:", c.description or "(none)"),
109
+ ("Status:", c.status or "(none)"),
110
+ ("Color:", c.color or "(none)"),
111
+ ("Icon:", c.icon or "(none)"),
112
+ ("Goal:", str(c.goal) if c.goal is not None else "(none)"),
113
+ ("Budget:", str(c.budget) if c.budget is not None else "(none)"),
114
+ ("Start Date:", c.start_date or "(none)"),
115
+ ("End Date:", c.end_date or "(none)"),
116
+ ("Link Count:", str(c.link_count) if c.link_count is not None else "0"),
117
+ ("UTM Source:", c.utm_source or "(none)"),
118
+ ("UTM Medium:", c.utm_medium or "(none)"),
119
+ ("UTM Campaign:", c.utm_campaign or "(none)"),
120
+ ("Created At:", c.created_at or "(unknown)"),
121
+ ("Request ID:", c.request_id),
122
+ ])
123
+
124
+ return EXIT_SUCCESS
125
+
126
+
127
+ def cmd_campaigns_update(args: Any, get_client: Callable[..., Any]) -> int:
128
+ """Update campaign properties."""
129
+ has_update = any([
130
+ getattr(args, "name", None) is not None,
131
+ getattr(args, "description", None) is not None,
132
+ getattr(args, "color", None) is not None,
133
+ getattr(args, "icon", None) is not None,
134
+ getattr(args, "status", None) is not None,
135
+ getattr(args, "goal", None) is not None,
136
+ getattr(args, "budget", None) is not None,
137
+ getattr(args, "start_date", None) is not None,
138
+ getattr(args, "end_date", None) is not None,
139
+ getattr(args, "utm_source", None) is not None,
140
+ getattr(args, "utm_medium", None) is not None,
141
+ getattr(args, "utm_campaign", None) is not None,
142
+ ])
143
+ if not has_update:
144
+ print_error("At least one update field must be supplied (e.g. --name, --description).")
145
+ return EXIT_INVALID_ARGS
146
+
147
+ client = get_client()
148
+ c = client.campaigns.update(
149
+ campaign_id=args.campaign_id,
150
+ name=getattr(args, "name", None),
151
+ description=getattr(args, "description", None),
152
+ color=getattr(args, "color", None),
153
+ icon=getattr(args, "icon", None),
154
+ status=getattr(args, "status", None),
155
+ goal=getattr(args, "goal", None),
156
+ budget=getattr(args, "budget", None),
157
+ start_date=getattr(args, "start_date", None),
158
+ end_date=getattr(args, "end_date", None),
159
+ utm_source=getattr(args, "utm_source", None),
160
+ utm_medium=getattr(args, "utm_medium", None),
161
+ utm_campaign=getattr(args, "utm_campaign", None),
162
+ )
163
+
164
+ if args.quiet:
165
+ print(c.id)
166
+ elif args.json:
167
+ output_json(c)
168
+ else:
169
+ print(f"✓ Campaign {c.id} updated successfully\n")
170
+ print_details([
171
+ ("ID:", c.id),
172
+ ("Name:", c.name),
173
+ ("Description:", c.description or "(none)"),
174
+ ("Status:", c.status or "(none)"),
175
+ ("Color:", c.color or "(none)"),
176
+ ("Icon:", c.icon or "(none)"),
177
+ ("Goal:", str(c.goal) if c.goal is not None else "(none)"),
178
+ ("Budget:", str(c.budget) if c.budget is not None else "(none)"),
179
+ ("Start Date:", c.start_date or "(none)"),
180
+ ("End Date:", c.end_date or "(none)"),
181
+ ("Request ID:", c.request_id),
182
+ ])
183
+
184
+ return EXIT_SUCCESS
185
+
186
+
187
+ def cmd_campaigns_delete(args: Any, get_client: Callable[..., Any]) -> int:
188
+ """Delete a campaign."""
189
+ if not args.yes and not args.json and not args.quiet:
190
+ if not confirm_action(f"Delete campaign {args.campaign_id}?", force_yes=False):
191
+ print("Operation cancelled.")
192
+ return EXIT_SUCCESS
193
+
194
+ client = get_client()
195
+ res = client.campaigns.delete(args.campaign_id)
196
+
197
+ if args.quiet:
198
+ print(res.id)
199
+ elif args.json:
200
+ output_json(res)
201
+ else:
202
+ print(f"✓ Campaign {res.id} deleted successfully")
203
+
204
+ return EXIT_SUCCESS
@@ -0,0 +1,56 @@
1
+ """Configuration commands for TrimLynk CLI."""
2
+
3
+ from typing import Any, Callable
4
+
5
+ from ..config_store import get_config_value, read_config, set_config_value
6
+ from ..credentials import mask_api_key, resolve_api_key
7
+ from ..exit_codes import EXIT_SUCCESS
8
+ from ..formatting import output_json, print_details
9
+
10
+
11
+ def cmd_config_get(args: Any, _get_client: Callable[..., Any]) -> int:
12
+ """Retrieve CLI configuration values."""
13
+ if args.key:
14
+ if args.key == "api_key":
15
+ val = mask_api_key(resolve_api_key())
16
+ else:
17
+ val = get_config_value(args.key) or "(not set)"
18
+
19
+ if args.json:
20
+ output_json({args.key: val})
21
+ else:
22
+ print(f"{args.key}: {val}")
23
+ return EXIT_SUCCESS
24
+
25
+ # Display all configuration
26
+ config = read_config()
27
+ api_key_status = mask_api_key(resolve_api_key())
28
+
29
+ display_data = {
30
+ "api_key": api_key_status,
31
+ "environment": config.get("environment", "live"),
32
+ "base_url": config.get("base_url", "https://api.trimlynk.com"),
33
+ }
34
+ for k, v in config.items():
35
+ if k not in display_data:
36
+ display_data[k] = v
37
+
38
+ if args.json:
39
+ output_json(display_data)
40
+ else:
41
+ pairs = [(f"{k}:", v) for k, v in display_data.items()]
42
+ print_details(pairs)
43
+
44
+ return EXIT_SUCCESS
45
+
46
+
47
+ def cmd_config_set(args: Any, _get_client: Callable[..., Any]) -> int:
48
+ """Set a configuration value."""
49
+ set_config_value(args.key, args.value)
50
+
51
+ if args.json:
52
+ output_json({"key": args.key, "value": args.value, "updated": True})
53
+ elif not args.quiet:
54
+ print(f"✓ Configuration updated: {args.key} = {args.value}")
55
+
56
+ return EXIT_SUCCESS