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
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# Endpoints that need no API key. The key, when configured, is not sent.
|
|
6
|
+
#
|
|
7
|
+
# Key-less link creation and the anonymous link preview are left out on
|
|
8
|
+
# purpose: they need a browser human check. Use links.create and
|
|
9
|
+
# analytics.link with an API key instead.
|
|
10
|
+
class PublicResource < Resource
|
|
11
|
+
# GET /validate?url=... Answers `valid`, plus `normalized` or
|
|
12
|
+
# `code`/`error`.
|
|
13
|
+
def validate_url(url)
|
|
14
|
+
raise ArgumentError, "url is required" if url.to_s.strip.empty?
|
|
15
|
+
|
|
16
|
+
get_request("/validate", { url: url.to_s }, auth: false)
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# GET /qr. Params: `url` (required), `format` (png, svg, jpg), `size`,
|
|
20
|
+
# `fg`, `bg`, `qrShape`, `frameTemplate`, `centerLogo`... Returns the
|
|
21
|
+
# image bytes as a binary String. Boolean flags such as `centerLogo` go
|
|
22
|
+
# as "true"/"false", the form this endpoint reads.
|
|
23
|
+
def qr_code(params)
|
|
24
|
+
params = { url: params } if params.is_a?(String)
|
|
25
|
+
query = hash_param(params, "params").transform_values do |value|
|
|
26
|
+
[true, false].include?(value) ? value.to_s : value
|
|
27
|
+
end
|
|
28
|
+
format = (query[:format] || query["format"]).to_s
|
|
29
|
+
accept = { "svg" => "image/svg+xml", "jpg" => "image/jpeg", "jpeg" => "image/jpeg" }.fetch(format, "image/png")
|
|
30
|
+
response = @client.request_raw("GET", "/qr", query: query, auth: false, accept: "#{accept}, */*")
|
|
31
|
+
response[:body].b
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
# GET /plans: the plan catalog under `plans`, keyed by plan id.
|
|
35
|
+
def plans
|
|
36
|
+
get_request("/plans", auth: false)
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
end
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# Report and alert rules: `/reports/rules`.
|
|
6
|
+
class ReportsResource < Resource
|
|
7
|
+
# GET /reports/rules. Query: `workspace_public_id`, `schedule_types`,
|
|
8
|
+
# `link_public_ids`, `team_public_ids` (Arrays are sent comma-separated).
|
|
9
|
+
def list_rules(query = {})
|
|
10
|
+
get_request("/reports/rules", hash_param(query, "query"))
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
# GET /reports/rules/{id}. The rule is under `data`.
|
|
14
|
+
def get_rule(id)
|
|
15
|
+
get_request("/reports/rules/#{segment(id, 'id')}")
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# POST /reports/rules. Params: `workspace_public_id`, `report_type`
|
|
19
|
+
# ("custom_builder_v1"), `schedule_type`, `interval_seconds`,
|
|
20
|
+
# `initial_run_at`, `report_name`, `definition_json`,
|
|
21
|
+
# `destination_public_ids`, `team_public_ids`, `include_unassigned_links`,
|
|
22
|
+
# `link_public_ids`. A new rule is always enabled: the API ignores
|
|
23
|
+
# `enabled` on create, so pause a rule with update_rule(id, enabled: false).
|
|
24
|
+
def create_rule(params)
|
|
25
|
+
post_request("/reports/rules", hash_param(params, "params"))
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
# PATCH /reports/rules/{id}: changes the fields sent, such as
|
|
29
|
+
# `{ enabled: false }`.
|
|
30
|
+
def update_rule(id, params)
|
|
31
|
+
patch_request("/reports/rules/#{segment(id, 'id')}", hash_param(params, "params"))
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
# DELETE /reports/rules/{id}. Answers 204, returned as `{}`.
|
|
35
|
+
def delete_rule(id)
|
|
36
|
+
delete_request("/reports/rules/#{segment(id, 'id')}")
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
end
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# Tags: `/workspaces/{public_id}/tags` and `/tags/{public_id}`.
|
|
6
|
+
# These endpoints answer without a `data` wrapper.
|
|
7
|
+
class TagsResource < Resource
|
|
8
|
+
# GET /workspaces/{workspace_id}/tags. Query: `team_public_ids`
|
|
9
|
+
# (Array or comma-separated), `team` ("none"), `report_scope` ("1").
|
|
10
|
+
# The tags are under `tags` (null when there are none).
|
|
11
|
+
def list(workspace_id, query = {})
|
|
12
|
+
get_request("/workspaces/#{segment(workspace_id, 'workspace_id')}/tags", hash_param(query, "query"))
|
|
13
|
+
end
|
|
14
|
+
|
|
15
|
+
# POST /workspaces/{workspace_id}/tags. Params: `name`, `color`,
|
|
16
|
+
# optional `team_public_ids`.
|
|
17
|
+
def create(workspace_id, params)
|
|
18
|
+
post_request("/workspaces/#{segment(workspace_id, 'workspace_id')}/tags", hash_param(params, "params"))
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# GET /tags/{id}
|
|
22
|
+
def get(id)
|
|
23
|
+
get_request("/tags/#{segment(id, 'id')}")
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# PUT /tags/{id}. Either `name`/`color`, or `team_public_ids`, per request.
|
|
27
|
+
def update(id, params)
|
|
28
|
+
put_request("/tags/#{segment(id, 'id')}", hash_param(params, "params"))
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
# DELETE /tags/{id}: removes the tag from every link.
|
|
32
|
+
def delete(id)
|
|
33
|
+
delete_request("/tags/#{segment(id, 'id')}")
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
end
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# Teams: `/workspaces/{public_id}/teams` and `/teams/{slug}`.
|
|
6
|
+
# These endpoints answer without a `data` wrapper.
|
|
7
|
+
#
|
|
8
|
+
# A slug is unique only within a workspace: pass
|
|
9
|
+
# `{ workspace: "<workspace public id>" }` as the query of get, update and
|
|
10
|
+
# delete when the key reaches several workspaces.
|
|
11
|
+
class TeamsResource < Resource
|
|
12
|
+
# GET /workspaces/{workspace_id}/teams. The teams are under `teams`.
|
|
13
|
+
def list(workspace_id)
|
|
14
|
+
get_request("/workspaces/#{segment(workspace_id, 'workspace_id')}/teams")
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
# POST /workspaces/{workspace_id}/teams. Params: `name`, `description`.
|
|
18
|
+
# Answers `id`, `slug` and `public_id`.
|
|
19
|
+
def create(workspace_id, params)
|
|
20
|
+
post_request("/workspaces/#{segment(workspace_id, 'workspace_id')}/teams", hash_param(params, "params"))
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# GET /teams/{slug}. Query: `workspace`.
|
|
24
|
+
def get(slug, query = {})
|
|
25
|
+
get_request("/teams/#{segment(slug, 'slug')}", hash_param(query, "query"))
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
# PUT /teams/{slug}. Params: `name`, `description`. Query: `workspace`.
|
|
29
|
+
def update(slug, params, query = {})
|
|
30
|
+
put_request("/teams/#{segment(slug, 'slug')}", hash_param(params, "params"), hash_param(query, "query"))
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# DELETE /teams/{slug}: archives the team. Query: `workspace`.
|
|
34
|
+
def delete(slug, query = {})
|
|
35
|
+
delete_request("/teams/#{segment(slug, 'slug')}", hash_param(query, "query"))
|
|
36
|
+
end
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# UTM templates: `/workspaces/{public_id}/utm-templates` and
|
|
6
|
+
# `/utm-templates/{public_id}`.
|
|
7
|
+
class UTMTemplatesResource < Resource
|
|
8
|
+
# GET /workspaces/{workspace_id}/utm-templates. Query:
|
|
9
|
+
# `include_team_scoped` ("1"/true), `team_public_ids`.
|
|
10
|
+
def list(workspace_id, query = {})
|
|
11
|
+
get_request("/workspaces/#{segment(workspace_id, 'workspace_id')}/utm-templates", hash_param(query, "query"))
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
# POST /workspaces/{workspace_id}/utm-templates. Params: `name`,
|
|
15
|
+
# `utm_source`..`utm_id`, `team_public_ids`. The template is under `data`.
|
|
16
|
+
def create(workspace_id, params)
|
|
17
|
+
post_request("/workspaces/#{segment(workspace_id, 'workspace_id')}/utm-templates", hash_param(params, "params"))
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
# PUT /utm-templates/{template_id}. Replaces the template: send every
|
|
21
|
+
# value to keep. Optional `workspace_public_id`, `lost_access_action`.
|
|
22
|
+
def update(template_id, params)
|
|
23
|
+
put_request("/utm-templates/#{segment(template_id, 'template_id')}", hash_param(params, "params"))
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# DELETE /utm-templates/{template_id}. Query: `links` ("keep" or "clear").
|
|
27
|
+
def delete(template_id, query = {})
|
|
28
|
+
delete_request("/utm-templates/#{segment(template_id, 'template_id')}", hash_param(query, "query"))
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
end
|
|
32
|
+
end
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# Workspaces: `/workspaces`.
|
|
6
|
+
class WorkspacesResource < Resource
|
|
7
|
+
# GET /workspaces. The workspaces are under `data`.
|
|
8
|
+
def list
|
|
9
|
+
get_request("/workspaces")
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
# GET /workspaces/{public_id}. The workspace is under `data`.
|
|
13
|
+
def get(public_id)
|
|
14
|
+
get_request("/workspaces/#{segment(public_id, 'public_id')}")
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
end
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Shortn
|
|
4
|
+
module SDK
|
|
5
|
+
# Retry policy.
|
|
6
|
+
#
|
|
7
|
+
# Retries happen on 429 and 503 responses and on transient network errors
|
|
8
|
+
# (timeouts, refused or reset connections, DNS, TLS other than a failed
|
|
9
|
+
# certificate check), and only for requests that are safe to repeat: GET,
|
|
10
|
+
# PUT and DELETE, and live conversion POSTs that carry an idempotency_key.
|
|
11
|
+
# Test-mode conversions (`test_mode: true`) are never retried: the API does
|
|
12
|
+
# not deduplicate test events.
|
|
13
|
+
#
|
|
14
|
+
# max_retries - retries after the first attempt (0 disables retries)
|
|
15
|
+
# initial_delay - seconds before the first retry
|
|
16
|
+
# max_delay - cap for the exponential backoff, in seconds
|
|
17
|
+
# backoff_factor - multiplier per retry
|
|
18
|
+
# jitter - randomise each backoff delay by +/-20%
|
|
19
|
+
# max_retry_after - longest Retry-After (seconds) the client waits for;
|
|
20
|
+
# a longer one raises the error instead of sleeping
|
|
21
|
+
# disabled - turn retries off entirely
|
|
22
|
+
RetryOptions = Struct.new(
|
|
23
|
+
:max_retries,
|
|
24
|
+
:initial_delay,
|
|
25
|
+
:max_delay,
|
|
26
|
+
:backoff_factor,
|
|
27
|
+
:jitter,
|
|
28
|
+
:max_retry_after,
|
|
29
|
+
:disabled,
|
|
30
|
+
keyword_init: true
|
|
31
|
+
) do
|
|
32
|
+
def initialize(max_retries: 2, initial_delay: 0.5, max_delay: 8.0, backoff_factor: 2.0, jitter: true,
|
|
33
|
+
max_retry_after: 60.0, disabled: false)
|
|
34
|
+
super
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# A policy that never retries.
|
|
38
|
+
def self.none
|
|
39
|
+
new(disabled: true)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def enabled?
|
|
43
|
+
!disabled && max_retries.to_i.positive?
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# Backoff delay in seconds before retry number +attempt+ (0-based).
|
|
47
|
+
def backoff(attempt)
|
|
48
|
+
delay = [initial_delay.to_f * (backoff_factor.to_f**attempt), max_delay.to_f].min
|
|
49
|
+
delay *= 0.8 + (rand * 0.4) if jitter && delay.positive?
|
|
50
|
+
delay
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
end
|
|
54
|
+
end
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "net/http"
|
|
4
|
+
require "uri"
|
|
5
|
+
|
|
6
|
+
module Shortn
|
|
7
|
+
module SDK
|
|
8
|
+
# Default transport: one Net::HTTP request per call.
|
|
9
|
+
#
|
|
10
|
+
# Any object responding to `call(method, url, headers, body, timeout)` and
|
|
11
|
+
# returning `[status, headers, body]` can replace it (see Client.new).
|
|
12
|
+
class NetHTTPTransport
|
|
13
|
+
REQUEST_CLASSES = {
|
|
14
|
+
"GET" => Net::HTTP::Get,
|
|
15
|
+
"POST" => Net::HTTP::Post,
|
|
16
|
+
"PUT" => Net::HTTP::Put,
|
|
17
|
+
"PATCH" => Net::HTTP::Patch,
|
|
18
|
+
"DELETE" => Net::HTTP::Delete,
|
|
19
|
+
"HEAD" => Net::HTTP::Head
|
|
20
|
+
}.freeze
|
|
21
|
+
|
|
22
|
+
def call(method, url, headers, body, timeout)
|
|
23
|
+
uri = URI.parse(url)
|
|
24
|
+
request_class = REQUEST_CLASSES.fetch(method) { raise ArgumentError, "unsupported HTTP method #{method}" }
|
|
25
|
+
request = request_class.new(uri, headers)
|
|
26
|
+
request.body = body unless body.nil?
|
|
27
|
+
|
|
28
|
+
http = build_http(uri)
|
|
29
|
+
http.use_ssl = uri.scheme == "https"
|
|
30
|
+
http.open_timeout = timeout
|
|
31
|
+
http.read_timeout = timeout
|
|
32
|
+
http.write_timeout = timeout if http.respond_to?(:write_timeout=)
|
|
33
|
+
# Net::HTTP would otherwise repeat an idempotent request once on its
|
|
34
|
+
# own; the client's retry policy decides about retries.
|
|
35
|
+
http.max_retries = 0
|
|
36
|
+
response = http.start { |connection| connection.request(request) }
|
|
37
|
+
[response.code.to_i, response.each_header.to_h, response.body.to_s]
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
private
|
|
41
|
+
|
|
42
|
+
def build_http(uri)
|
|
43
|
+
Net::HTTP.new(uri.host, uri.port)
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
end
|
data/lib/shortn/sdk.rb
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "sdk/version"
|
|
4
|
+
require_relative "sdk/errors"
|
|
5
|
+
require_relative "sdk/retry_options"
|
|
6
|
+
require_relative "sdk/client"
|
|
7
|
+
|
|
8
|
+
module Shortn
|
|
9
|
+
# Ruby SDK for the Shortn Link API. Start with Shortn::SDK::Client.
|
|
10
|
+
module SDK
|
|
11
|
+
end
|
|
12
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: shortn-sdk
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Jedna Software
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies: []
|
|
12
|
+
description: 'Server-side Ruby client for the Shortn Link public API: links, analytics,
|
|
13
|
+
workspaces, tags, UTM templates, destinations, teams, custom domains, report rules
|
|
14
|
+
and conversions.'
|
|
15
|
+
executables: []
|
|
16
|
+
extensions: []
|
|
17
|
+
extra_rdoc_files: []
|
|
18
|
+
files:
|
|
19
|
+
- CHANGELOG.md
|
|
20
|
+
- LICENSE
|
|
21
|
+
- README.md
|
|
22
|
+
- examples/create_link.rb
|
|
23
|
+
- examples/public_helpers.rb
|
|
24
|
+
- examples/track_conversions.rb
|
|
25
|
+
- lib/shortn/sdk.rb
|
|
26
|
+
- lib/shortn/sdk/client.rb
|
|
27
|
+
- lib/shortn/sdk/errors.rb
|
|
28
|
+
- lib/shortn/sdk/resources/analytics.rb
|
|
29
|
+
- lib/shortn/sdk/resources/base.rb
|
|
30
|
+
- lib/shortn/sdk/resources/conversions.rb
|
|
31
|
+
- lib/shortn/sdk/resources/destinations.rb
|
|
32
|
+
- lib/shortn/sdk/resources/domains.rb
|
|
33
|
+
- lib/shortn/sdk/resources/links.rb
|
|
34
|
+
- lib/shortn/sdk/resources/public.rb
|
|
35
|
+
- lib/shortn/sdk/resources/reports.rb
|
|
36
|
+
- lib/shortn/sdk/resources/tags.rb
|
|
37
|
+
- lib/shortn/sdk/resources/teams.rb
|
|
38
|
+
- lib/shortn/sdk/resources/utm_templates.rb
|
|
39
|
+
- lib/shortn/sdk/resources/workspaces.rb
|
|
40
|
+
- lib/shortn/sdk/retry_options.rb
|
|
41
|
+
- lib/shortn/sdk/transport.rb
|
|
42
|
+
- lib/shortn/sdk/version.rb
|
|
43
|
+
homepage: https://shortn.link
|
|
44
|
+
licenses:
|
|
45
|
+
- MIT
|
|
46
|
+
metadata:
|
|
47
|
+
source_code_uri: https://github.com/jedna-software/shortn-sdk-ruby
|
|
48
|
+
bug_tracker_uri: https://github.com/jedna-software/shortn-sdk-ruby/issues
|
|
49
|
+
changelog_uri: https://github.com/jedna-software/shortn-sdk-ruby/blob/main/CHANGELOG.md
|
|
50
|
+
documentation_uri: https://docs.shortn.link/docs/api/
|
|
51
|
+
rubygems_mfa_required: 'true'
|
|
52
|
+
rdoc_options: []
|
|
53
|
+
require_paths:
|
|
54
|
+
- lib
|
|
55
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
56
|
+
requirements:
|
|
57
|
+
- - ">="
|
|
58
|
+
- !ruby/object:Gem::Version
|
|
59
|
+
version: '3.1'
|
|
60
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
61
|
+
requirements:
|
|
62
|
+
- - ">="
|
|
63
|
+
- !ruby/object:Gem::Version
|
|
64
|
+
version: '0'
|
|
65
|
+
requirements: []
|
|
66
|
+
rubygems_version: 4.0.23
|
|
67
|
+
specification_version: 4
|
|
68
|
+
summary: Ruby SDK for the Shortn Link API.
|
|
69
|
+
test_files: []
|