shortn-sdk 0.1.0
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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +34 -0
- data/LICENSE +21 -0
- data/README.md +350 -0
- data/examples/create_link.rb +24 -0
- data/examples/public_helpers.rb +18 -0
- data/examples/track_conversions.rb +37 -0
- data/lib/shortn/sdk/client.rb +333 -0
- data/lib/shortn/sdk/errors.rb +84 -0
- data/lib/shortn/sdk/resources/analytics.rb +16 -0
- data/lib/shortn/sdk/resources/base.rb +54 -0
- data/lib/shortn/sdk/resources/conversions.rb +83 -0
- data/lib/shortn/sdk/resources/destinations.rb +37 -0
- data/lib/shortn/sdk/resources/domains.rb +30 -0
- data/lib/shortn/sdk/resources/links.rb +47 -0
- data/lib/shortn/sdk/resources/public.rb +40 -0
- data/lib/shortn/sdk/resources/reports.rb +40 -0
- data/lib/shortn/sdk/resources/tags.rb +37 -0
- data/lib/shortn/sdk/resources/teams.rb +39 -0
- data/lib/shortn/sdk/resources/utm_templates.rb +32 -0
- data/lib/shortn/sdk/resources/workspaces.rb +18 -0
- data/lib/shortn/sdk/retry_options.rb +54 -0
- data/lib/shortn/sdk/transport.rb +47 -0
- data/lib/shortn/sdk/version.rb +7 -0
- data/lib/shortn/sdk.rb +12 -0
- metadata +69 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: c77216813bc7952e2c88ab57ab49c9a3414f1d1fd8e7150a96d0c71c507f76ad
|
|
4
|
+
data.tar.gz: 2122d62c2b85ac3cc0cb114f3d6c7ae549f0b81c4bd345d5becfdc6577a3a017
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 52592744f854e2d4080511fba9b8c96373b2c16ade67e401484abac7edb40f321d6248327173f42b2f9cb349365f2e7c26cd3e1222b09343ee3b8c2ca8e0deb0
|
|
7
|
+
data.tar.gz: dff07f439d9649a440c8359c42ad45bb2fc18733e486998f130a385617fe340d649ab02d4fff2638d0cad5ba7def44b5601a9badc0c9330d465500db83b71058
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 - 2026-11-22
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- `Shortn::SDK::Client` for the public API at `<base_url>/api/v1`, with API-key
|
|
8
|
+
authentication (`Authorization: Bearer`), configurable base URL, timeout,
|
|
9
|
+
retry policy, user agent suffix and HTTP transport.
|
|
10
|
+
- 50 methods covering the API: `links` (list, get, create, update, delete,
|
|
11
|
+
enable, set_ab_winner), `analytics.link`, `workspaces`, `tags`,
|
|
12
|
+
`utm_templates`, `destinations`, `teams`, `domains`, `reports` rules,
|
|
13
|
+
`conversions` (track and validate leads, sales and refunds; summary,
|
|
14
|
+
attribution, timeline, events) and the key-less `public` helpers
|
|
15
|
+
(validate_url, qr_code, plans).
|
|
16
|
+
- Responses are the API's JSON as plain Hashes, so new fields need no release.
|
|
17
|
+
- `APIError` carries status, code, message, hint, field, details, request id,
|
|
18
|
+
parsed and raw body, and headers.
|
|
19
|
+
- Request bodies are encoded in the forms the API parses: `Time`/`DateTime`
|
|
20
|
+
as UTC RFC 3339 (`2026-01-01T00:00:00Z`), `Date` as midnight UTC,
|
|
21
|
+
`BigDecimal`/`Rational` as plain decimal Strings, and a numeric `amount` as a
|
|
22
|
+
decimal String (`19.99` => `"19.99"`). Times are
|
|
23
|
+
converted without mutating the caller's object, so frozen Times work.
|
|
24
|
+
- Query booleans are sent as `1`/`0` (the QR endpoint keeps `true`/`false`).
|
|
25
|
+
- `base_url` is validated in `Client.new` (http or https with a host;
|
|
26
|
+
`ConfigurationError` otherwise).
|
|
27
|
+
- Retries on 429, 503 and transient network errors (timeouts, refused or reset
|
|
28
|
+
connections, DNS, TLS other than certificate failures) for GET, PUT, DELETE
|
|
29
|
+
and live conversion POSTs with an `idempotency_key`, honouring `Retry-After`
|
|
30
|
+
and raising when it exceeds `max_retry_after`. Test-mode conversions are
|
|
31
|
+
never retried, other exceptions propagate unchanged and unretried, and
|
|
32
|
+
Net::HTTP's own automatic retry is off, so `retry_options: false` sends each
|
|
33
|
+
request once.
|
|
34
|
+
- Offline unit tests for every method and an opt-in live smoke test.
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jedna Software
|
|
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.
|
data/README.md
ADDED
|
@@ -0,0 +1,350 @@
|
|
|
1
|
+
# Shortn Link Ruby SDK
|
|
2
|
+
|
|
3
|
+
Ruby client for the [Shortn Link](https://shortn.link) public API
|
|
4
|
+
(`https://app.shortn.link/api/v1`): links, link analytics, workspaces, tags, UTM
|
|
5
|
+
templates, report destinations, teams, custom domains, report and alert rules,
|
|
6
|
+
conversions, and the key-less public helpers.
|
|
7
|
+
|
|
8
|
+
Use it from trusted server-side code only. Never ship a Shortn API key to a
|
|
9
|
+
browser, mobile app or any other client-controlled code.
|
|
10
|
+
|
|
11
|
+
- Ruby 3.1 or newer, no runtime dependencies (Net::HTTP and JSON from the
|
|
12
|
+
standard library).
|
|
13
|
+
- Responses are plain Hashes and Arrays with string keys, exactly as the API
|
|
14
|
+
sends them, so new API fields are available without an SDK release.
|
|
15
|
+
- API reference: [docs.shortn.link/docs/api](https://docs.shortn.link/docs/api/).
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
gem install shortn-sdk
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
or in a Gemfile:
|
|
24
|
+
|
|
25
|
+
```ruby
|
|
26
|
+
gem "shortn-sdk"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```ruby
|
|
30
|
+
require "shortn/sdk"
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
```ruby
|
|
36
|
+
require "shortn/sdk"
|
|
37
|
+
|
|
38
|
+
shortn = Shortn::SDK::Client.new(api_key: ENV.fetch("SHORTN_API_KEY"))
|
|
39
|
+
|
|
40
|
+
workspace = shortn.workspaces.list["data"].first
|
|
41
|
+
link = shortn.links.create(
|
|
42
|
+
url: "https://example.com/spring",
|
|
43
|
+
title: "Spring campaign",
|
|
44
|
+
workspace_public_id: workspace["public_id"],
|
|
45
|
+
utm_source: "newsletter",
|
|
46
|
+
utm_medium: "email"
|
|
47
|
+
)
|
|
48
|
+
puts link["short_url"]
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Create a key under **Profile → API keys** in the app. Each key has scopes
|
|
52
|
+
(`links:read`, `links:write`, `conversions:write`, ...) and is either
|
|
53
|
+
account-wide or limited to one workspace; see
|
|
54
|
+
[authentication](https://docs.shortn.link/docs/api/authentication/).
|
|
55
|
+
|
|
56
|
+
## Configuration
|
|
57
|
+
|
|
58
|
+
```ruby
|
|
59
|
+
shortn = Shortn::SDK::Client.new(
|
|
60
|
+
api_key: ENV.fetch("SHORTN_API_KEY"), # optional only for client.public
|
|
61
|
+
base_url: "https://app.shortn.link", # "/api/v1" is appended
|
|
62
|
+
timeout: 10, # seconds (open, read, write)
|
|
63
|
+
retry_options: Shortn::SDK::RetryOptions.new(max_retries: 3),
|
|
64
|
+
user_agent: "my-app/1.4" # appended to shortn-sdk-ruby/0.1.0
|
|
65
|
+
)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`transport:` replaces the HTTP layer (for tests or a different HTTP client).
|
|
69
|
+
It is any object with `call(method, url, headers, body, timeout)` returning
|
|
70
|
+
`[status, headers, body]`.
|
|
71
|
+
|
|
72
|
+
`base_url` must be an `http` or `https` URL with a host; anything else raises
|
|
73
|
+
`Shortn::SDK::ConfigurationError` from `Client.new`.
|
|
74
|
+
|
|
75
|
+
Methods take ids as positional arguments and request fields as a Hash, with
|
|
76
|
+
symbol or string keys, named as in the API docs (snake_case). The Hash is sent
|
|
77
|
+
with the same fields; the API refuses fields it doesn't know with
|
|
78
|
+
`400 unsupported_fields`. Values are converted to the forms the API parses:
|
|
79
|
+
|
|
80
|
+
- `Time` and `DateTime` become UTC RFC 3339 (`"2026-01-01T09:30:00Z"`), `Date`
|
|
81
|
+
becomes midnight UTC (`"2026-01-01T00:00:00Z"`), for fields such as
|
|
82
|
+
`occurred_at`, `starts_at` and `expires_at`.
|
|
83
|
+
- `BigDecimal` and `Rational` become plain decimal Strings (`"19.99"`).
|
|
84
|
+
- `amount` is a String such as `"19.99"`; an Integer, Float or BigDecimal
|
|
85
|
+
given for `amount` is converted to one (`19.99` =>
|
|
86
|
+
`"19.99"`, `20` => `"20"`). Other numeric fields are sent as numbers.
|
|
87
|
+
|
|
88
|
+
Query parameters you leave out (or set to `nil`) are not sent; Arrays are sent
|
|
89
|
+
comma-separated, `true`/`false` as `1`/`0`, and a `Time` as UTC RFC 3339.
|
|
90
|
+
|
|
91
|
+
## Resources
|
|
92
|
+
|
|
93
|
+
| Group | Methods |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `links` | `list(query)`, `get(id)`, `create(params)`, `update(id, params)`, `delete(id)`, `enable(id)`, `set_ab_winner(id, params)` |
|
|
96
|
+
| `analytics` | `link(id, query)` |
|
|
97
|
+
| `workspaces` | `list`, `get(public_id)` |
|
|
98
|
+
| `tags` | `list(workspace_id, query)`, `create(workspace_id, params)`, `get(id)`, `update(id, params)`, `delete(id)` |
|
|
99
|
+
| `utm_templates` | `list(workspace_id, query)`, `create(workspace_id, params)`, `update(template_id, params)`, `delete(template_id, query)` |
|
|
100
|
+
| `destinations` | `list(workspace_id)`, `create(workspace_id, params)`, `update(workspace_id, destination_id, params)`, `delete(workspace_id, destination_id)` |
|
|
101
|
+
| `teams` | `list(workspace_id)`, `create(workspace_id, params)`, `get(slug, query)`, `update(slug, params, query)`, `delete(slug, query)` |
|
|
102
|
+
| `domains` | `list`, `create(params)`, `verify(id)`, `delete(id)` |
|
|
103
|
+
| `reports` | `list_rules(query)`, `get_rule(id)`, `create_rule(params)`, `update_rule(id, params)`, `delete_rule(id)` |
|
|
104
|
+
| `conversions` | `track_lead`, `validate_lead`, `track_sale`, `validate_sale`, `track_refund`, `validate_refund` (each `(params)`), `summary(query)`, `attribution(query)`, `timeline(query)`, `events(query)` |
|
|
105
|
+
| `public` (no key) | `validate_url(url)`, `qr_code(params)`, `plans` |
|
|
106
|
+
|
|
107
|
+
`query` arguments are optional everywhere.
|
|
108
|
+
|
|
109
|
+
### Links
|
|
110
|
+
|
|
111
|
+
```ruby
|
|
112
|
+
links = shortn.links.list(limit: 50, offset: 0)
|
|
113
|
+
links["data"].each { |l| puts "#{l['short_code']} #{l['clicks']}" }
|
|
114
|
+
next_offset = links["pagination"]["next_offset"]
|
|
115
|
+
|
|
116
|
+
link = shortn.links.get(public_id)["data"]
|
|
117
|
+
shortn.links.update(public_id, title: "Spring sale", url: "https://example.com/sale")
|
|
118
|
+
shortn.links.delete(public_id) # suspends the link; history is kept
|
|
119
|
+
shortn.links.enable(public_id)
|
|
120
|
+
shortn.links.set_ab_winner(public_id, variant: "B")
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Analytics
|
|
124
|
+
|
|
125
|
+
```ruby
|
|
126
|
+
totals = shortn.analytics.link(public_id)
|
|
127
|
+
totals["total_clicks"] # => 1280
|
|
128
|
+
totals["clicks_by_country"] # => {"Germany" => 512, ...}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The endpoint reads no query parameters; `query` has no effect today.
|
|
132
|
+
|
|
133
|
+
### Workspaces
|
|
134
|
+
|
|
135
|
+
```ruby
|
|
136
|
+
shortn.workspaces.list["data"]
|
|
137
|
+
shortn.workspaces.get(workspace_id)["data"]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Tags
|
|
141
|
+
|
|
142
|
+
```ruby
|
|
143
|
+
tag = shortn.tags.create(workspace_id, name: "Spring", color: "#14b8a6")
|
|
144
|
+
shortn.tags.list(workspace_id)["tags"] # nil when there are none
|
|
145
|
+
shortn.tags.update(tag["public_id"], name: "Spring 2027")
|
|
146
|
+
shortn.tags.delete(tag["public_id"])
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### UTM templates
|
|
150
|
+
|
|
151
|
+
```ruby
|
|
152
|
+
template = shortn.utm_templates.create(workspace_id, name: "Newsletter", utm_source: "newsletter", utm_medium: "email")["data"]
|
|
153
|
+
shortn.utm_templates.list(workspace_id, include_team_scoped: 1)["data"]
|
|
154
|
+
shortn.utm_templates.update(template["public_id"], name: "Newsletter", utm_source: "newsletter", utm_medium: "email", utm_campaign: "dec")
|
|
155
|
+
shortn.utm_templates.delete(template["public_id"], links: "keep")
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Destinations
|
|
159
|
+
|
|
160
|
+
```ruby
|
|
161
|
+
destination = shortn.destinations.create(workspace_id, name: "Ops inbox", type: "email", config: { to: ["ops@example.com"] })
|
|
162
|
+
shortn.destinations.list(workspace_id) # an Array
|
|
163
|
+
shortn.destinations.update(workspace_id, destination["public_id"], name: "Ops", type: "email")
|
|
164
|
+
shortn.destinations.delete(workspace_id, destination["public_id"])
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Teams
|
|
168
|
+
|
|
169
|
+
```ruby
|
|
170
|
+
team = shortn.teams.create(workspace_id, name: "Paid Social")
|
|
171
|
+
shortn.teams.list(workspace_id)["teams"]
|
|
172
|
+
shortn.teams.get(team["slug"], workspace: workspace_id)
|
|
173
|
+
shortn.teams.update(team["slug"], { description: "Paid social links" }, workspace: workspace_id)
|
|
174
|
+
shortn.teams.delete(team["slug"], workspace: workspace_id) # archives the team
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
A slug is unique only within its workspace; pass `workspace:` when the key
|
|
178
|
+
reaches several workspaces.
|
|
179
|
+
|
|
180
|
+
### Custom domains
|
|
181
|
+
|
|
182
|
+
```ruby
|
|
183
|
+
shortn.domains.list["data"]
|
|
184
|
+
domain = shortn.domains.create(domain: "go.example.com")["domain"]
|
|
185
|
+
shortn.domains.verify(domain["id"])
|
|
186
|
+
shortn.domains.delete(domain["id"])
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Adding, verifying and deleting a domain need an account-wide key.
|
|
190
|
+
|
|
191
|
+
### Reports and alerts
|
|
192
|
+
|
|
193
|
+
```ruby
|
|
194
|
+
rules = shortn.reports.list_rules(workspace_public_id: workspace_id, schedule_types: ["every_x"])["data"]
|
|
195
|
+
rule = shortn.reports.get_rule(rules.first["public_id"])["data"]
|
|
196
|
+
shortn.reports.update_rule(rule["public_id"], enabled: false)
|
|
197
|
+
created = shortn.reports.create_rule(
|
|
198
|
+
workspace_public_id: workspace_id,
|
|
199
|
+
report_type: "custom_builder_v1",
|
|
200
|
+
interval_seconds: 604_800,
|
|
201
|
+
report_name: "Weekly traffic",
|
|
202
|
+
destination_public_ids: [destination_id],
|
|
203
|
+
definition_json: rule["definition"]
|
|
204
|
+
)["data"]
|
|
205
|
+
shortn.reports.delete_rule(created["public_id"])
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
A new rule is always enabled: `create_rule` ignores `enabled`. To create a
|
|
209
|
+
paused rule, create it and then call `update_rule(id, enabled: false)`.
|
|
210
|
+
|
|
211
|
+
### Conversions
|
|
212
|
+
|
|
213
|
+
Send events from your backend, with the click id the
|
|
214
|
+
[capture script](https://docs.shortn.link/docs/conversion-tracking/install-capture-script/)
|
|
215
|
+
stored on your site:
|
|
216
|
+
|
|
217
|
+
```ruby
|
|
218
|
+
shortn.conversions.track_lead(
|
|
219
|
+
click_id: params[:snt_click_id],
|
|
220
|
+
event_name: "Sign up",
|
|
221
|
+
lead_category: "signup",
|
|
222
|
+
idempotency_key: "signup_#{user.id}"
|
|
223
|
+
)
|
|
224
|
+
|
|
225
|
+
shortn.conversions.track_sale(
|
|
226
|
+
click_id: params[:snt_click_id],
|
|
227
|
+
amount_cents: 4900, # hundredths of the main unit, whatever the currency
|
|
228
|
+
currency: "EUR",
|
|
229
|
+
invoice_id: invoice.number
|
|
230
|
+
)
|
|
231
|
+
|
|
232
|
+
shortn.conversions.track_refund(invoice_id: invoice.number, refund_id: refund.id, amount_cents: 1900)
|
|
233
|
+
|
|
234
|
+
# Or a decimal amount: a String such as "19.99" (numeric types are converted).
|
|
235
|
+
shortn.conversions.track_sale(click_id: params[:snt_click_id], amount: "19.99", currency: "EUR",
|
|
236
|
+
invoice_id: invoice.number, occurred_at: invoice.paid_at)
|
|
237
|
+
|
|
238
|
+
# Same checks, nothing recorded:
|
|
239
|
+
shortn.conversions.validate_sale(click_id: "clk_...", amount_cents: 4900, currency: "EUR", invoice_id: "inv_1")
|
|
240
|
+
|
|
241
|
+
shortn.conversions.summary["data"]
|
|
242
|
+
shortn.conversions.attribution(from: "2026-11-01", to: "2026-11-30", limit: 20)
|
|
243
|
+
shortn.conversions.timeline(interval: "week")
|
|
244
|
+
shortn.conversions.events(event_type: "sale", environment: "test")
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Add `test_mode: true` to record test events, and read them back with
|
|
248
|
+
`environment: "test"`. Test events are never deduplicated: each request
|
|
249
|
+
records a new event, even with a repeated `idempotency_key`, and a test-mode
|
|
250
|
+
refund finds only live sales. Conversion events hold no customer profile; keep
|
|
251
|
+
personal data out of `event_name` and `metadata`.
|
|
252
|
+
|
|
253
|
+
### Public helpers (no API key)
|
|
254
|
+
|
|
255
|
+
```ruby
|
|
256
|
+
shortn = Shortn::SDK::Client.new # no key needed
|
|
257
|
+
|
|
258
|
+
shortn.public.validate_url("example.com/menu")
|
|
259
|
+
# => {"valid" => true, "normalized" => "https://example.com/menu"}
|
|
260
|
+
|
|
261
|
+
png = shortn.public.qr_code(url: "https://shtnl.ink/abC12x9", format: "png", size: "download")
|
|
262
|
+
File.binwrite("menu-qr.png", png) # a binary String
|
|
263
|
+
|
|
264
|
+
shortn.public.plans["plans"].keys # => ["free", "starter", ...]
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
The client never sends its API key to these endpoints. Creating a link without
|
|
268
|
+
a key and the anonymous link preview are not in the SDK: they need a browser
|
|
269
|
+
human check. Use `links.create` and `analytics.link` with a key instead.
|
|
270
|
+
|
|
271
|
+
## Errors
|
|
272
|
+
|
|
273
|
+
Every non-2xx response raises `Shortn::SDK::APIError`:
|
|
274
|
+
|
|
275
|
+
```ruby
|
|
276
|
+
begin
|
|
277
|
+
shortn.links.create(url: "https://example.com", title: "Example", custom_code: "spring")
|
|
278
|
+
rescue Shortn::SDK::APIError => e
|
|
279
|
+
e.status # => 409
|
|
280
|
+
e.code # => "custom_code_conflict" (nil for the few errors without one)
|
|
281
|
+
e.message # the API's "error" text
|
|
282
|
+
e.hint # extra guidance, when sent
|
|
283
|
+
e.field # details["field"], when sent
|
|
284
|
+
e.details # the details Hash, when sent
|
|
285
|
+
e.request_id # conversion intake errors (also the Shortn-Request-Id header)
|
|
286
|
+
e.data # the whole parsed body, e.g. e.data["feature"] on plan limits
|
|
287
|
+
e.body # the raw body
|
|
288
|
+
e.headers # response headers, lower-case names
|
|
289
|
+
e.retry_after # seconds from Retry-After, if any
|
|
290
|
+
end
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
Other errors, all subclasses of `Shortn::SDK::Error`:
|
|
294
|
+
|
|
295
|
+
- `Shortn::SDK::NetworkError`: no response arrived (connection, DNS, TLS,
|
|
296
|
+
timeout); the original exception is `#cause`.
|
|
297
|
+
- `Shortn::SDK::ConfigurationError`: `base_url` is not an http(s) URL, or an
|
|
298
|
+
endpoint that needs a key was called on a client without one. Nothing is
|
|
299
|
+
sent.
|
|
300
|
+
|
|
301
|
+
Any other exception a transport raises (an `ArgumentError`, a bug in a custom
|
|
302
|
+
transport) propagates unchanged and is not retried.
|
|
303
|
+
|
|
304
|
+
## Retries
|
|
305
|
+
|
|
306
|
+
The client retries on `429` and `503` responses and on transient network
|
|
307
|
+
errors (timeouts, refused or reset connections, DNS failures, TLS errors other
|
|
308
|
+
than a failed certificate check), waiting for `Retry-After` when the API sends
|
|
309
|
+
it and backing off exponentially otherwise. It retries only requests that are
|
|
310
|
+
safe to repeat:
|
|
311
|
+
|
|
312
|
+
- `GET`, `PUT` and `DELETE`;
|
|
313
|
+
- live conversion `POST`s that carry an `idempotency_key`, which the API
|
|
314
|
+
records once per key.
|
|
315
|
+
|
|
316
|
+
Other `POST`s and `PATCH`es (creating a link, a tag, a rule...) are never
|
|
317
|
+
retried, and neither are test-mode conversions (`test_mode: true`): the API
|
|
318
|
+
doesn't deduplicate test events, so a retry would record a second one.
|
|
319
|
+
Net::HTTP's own automatic retry is switched off, so `retry_options: false`
|
|
320
|
+
sends every request exactly once. Defaults: 2 retries, 0.5 s initial delay,
|
|
321
|
+
factor 2, 8 s cap, ±20% jitter, and a `Retry-After` longer than 60 s raises
|
|
322
|
+
instead of waiting.
|
|
323
|
+
|
|
324
|
+
```ruby
|
|
325
|
+
Shortn::SDK::RetryOptions.new(max_retries: 4, initial_delay: 1, max_delay: 10, max_retry_after: 30)
|
|
326
|
+
Shortn::SDK::Client.new(api_key: key, retry_options: false) # no retries
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
## Development
|
|
330
|
+
|
|
331
|
+
```sh
|
|
332
|
+
bundle config set --local path vendor/bundle
|
|
333
|
+
bundle install
|
|
334
|
+
bundle exec rake test # offline unit tests
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
The smoke test runs against a live instance and is skipped unless
|
|
338
|
+
`SHORTN_API_KEY` and `SHORTN_BASE_URL` are set. It creates resources with a
|
|
339
|
+
random suffix in `SHORTN_SMOKE_WORKSPACE` and removes them again (the smoke
|
|
340
|
+
link is suspended, since links can't be deleted through the API). Point it at
|
|
341
|
+
a test instance, never at production:
|
|
342
|
+
|
|
343
|
+
```sh
|
|
344
|
+
SHORTN_API_KEY=... SHORTN_BASE_URL=https://test.example SHORTN_SMOKE_WORKSPACE=... \
|
|
345
|
+
SHORTN_SMOKE_CLICK_ID=clk_... bundle exec rake smoke
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
## License
|
|
349
|
+
|
|
350
|
+
MIT
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# Create a link in your first workspace, read it back and print its clicks.
|
|
4
|
+
#
|
|
5
|
+
# SHORTN_API_KEY=sk_live_... ruby examples/create_link.rb
|
|
6
|
+
|
|
7
|
+
require "shortn/sdk"
|
|
8
|
+
|
|
9
|
+
shortn = Shortn::SDK::Client.new(api_key: ENV.fetch("SHORTN_API_KEY"))
|
|
10
|
+
|
|
11
|
+
workspace = shortn.workspaces.list.fetch("data").first
|
|
12
|
+
link = shortn.links.create(
|
|
13
|
+
url: "https://example.com/pricing",
|
|
14
|
+
title: "Pricing",
|
|
15
|
+
workspace_public_id: workspace.fetch("public_id"),
|
|
16
|
+
utm_source: "newsletter",
|
|
17
|
+
utm_medium: "email",
|
|
18
|
+
utm_campaign: "spring_launch"
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
details = shortn.links.get(link.fetch("public_id")).fetch("data")
|
|
22
|
+
clicks = shortn.analytics.link(link.fetch("public_id"))
|
|
23
|
+
|
|
24
|
+
puts "#{link['short_url']} -> #{details['original_url']} (#{clicks['total_clicks']} clicks)"
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# The key-less helpers: validate a URL, draw its QR code, list the plans.
|
|
4
|
+
#
|
|
5
|
+
# ruby examples/public_helpers.rb
|
|
6
|
+
|
|
7
|
+
require "shortn/sdk"
|
|
8
|
+
|
|
9
|
+
shortn = Shortn::SDK::Client.new
|
|
10
|
+
|
|
11
|
+
validation = shortn.public.validate_url("example.com/pricing")
|
|
12
|
+
raise(validation["error"] || "URL is not valid") unless validation["valid"]
|
|
13
|
+
|
|
14
|
+
png = shortn.public.qr_code(url: validation.fetch("normalized"), format: "png")
|
|
15
|
+
File.binwrite("pricing-qr.png", png)
|
|
16
|
+
|
|
17
|
+
plans = shortn.public.plans.fetch("plans")
|
|
18
|
+
puts "#{validation['normalized']}: QR code saved (#{png.bytesize} bytes); plans: #{plans.keys.join(', ')}"
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# Record a test lead and sale for a click, then read the test events back.
|
|
4
|
+
#
|
|
5
|
+
# SHORTN_API_KEY=sk_live_... SHORTN_CLICK_ID=clk_... ruby examples/track_conversions.rb
|
|
6
|
+
|
|
7
|
+
require "securerandom"
|
|
8
|
+
require "shortn/sdk"
|
|
9
|
+
|
|
10
|
+
shortn = Shortn::SDK::Client.new(api_key: ENV.fetch("SHORTN_API_KEY"))
|
|
11
|
+
click_id = ENV.fetch("SHORTN_CLICK_ID")
|
|
12
|
+
order = "order_#{SecureRandom.hex(4)}"
|
|
13
|
+
|
|
14
|
+
begin
|
|
15
|
+
shortn.conversions.track_lead(
|
|
16
|
+
click_id: click_id,
|
|
17
|
+
event_name: "Sign up",
|
|
18
|
+
lead_category: "signup",
|
|
19
|
+
idempotency_key: "signup_#{order}",
|
|
20
|
+
test_mode: true
|
|
21
|
+
)
|
|
22
|
+
sale = shortn.conversions.track_sale(
|
|
23
|
+
click_id: click_id,
|
|
24
|
+
amount_cents: 4900,
|
|
25
|
+
currency: "EUR",
|
|
26
|
+
invoice_id: order,
|
|
27
|
+
test_mode: true
|
|
28
|
+
)
|
|
29
|
+
puts "sale #{sale.dig('event', 'public_id')}"
|
|
30
|
+
rescue Shortn::SDK::APIError => e
|
|
31
|
+
warn "#{e.status} #{e.code}: #{e.message} #{e.hint}"
|
|
32
|
+
exit 1
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
shortn.conversions.events(environment: "test", limit: 5).fetch("data").each do |event|
|
|
36
|
+
puts "#{event['event_type']} #{event['event_name']} #{event['occurred_at']}"
|
|
37
|
+
end
|