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.
@@ -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
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Shortn
4
+ module SDK
5
+ VERSION = "0.1.0"
6
+ end
7
+ 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: []