argoshot 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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 9709672437cc7de961329710faf63aefcb45b5d4e786489b4e592a300e05dbd9
4
+ data.tar.gz: af96ba0398a8ca9fdb2837a8bc0f172865672aff663faa623cba30fde5ae9eda
5
+ SHA512:
6
+ metadata.gz: 656f24c87079901d8775e3ec11391aa5034b365e1c9b016ddf0c3dd102aa62c238b0a346644e9091366fd276d28ea03c5c7a6bcde1f050569a2822f59ac14dcb
7
+ data.tar.gz: b7847ba8a93f3688e9fde2ccfafe7fc908ac12f84b3a10cc1b4c653b40e93081d59af79d4c4f55437c8502b2928425c39ba323dfa3dd0307f63c81a24ca99eab
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 RRLabs
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,99 @@
1
+ # argoshot
2
+
3
+ The official Ruby client for [Argoshot](https://argoshot.com), the screenshot API: screenshots, PDFs and signed
4
+ `og:image` URLs of any web page or HTML. **Free to start.** Docs: https://argoshot.com/docs
5
+
6
+ Standard library only (`net/http`, `openssl`, `json`). Ruby 2.6+.
7
+
8
+ ## Install
9
+
10
+ ```sh
11
+ gem install argoshot
12
+ ```
13
+
14
+ or in your Gemfile: `gem "argoshot"`. Get your access key (and secret key, for signed URLs) from the dashboard's API
15
+ keys page.
16
+
17
+ ## Screenshot to a file
18
+
19
+ ```ruby
20
+ require "argoshot"
21
+
22
+ client = Argoshot::Client.new(ENV.fetch("ARGOSHOT_ACCESS_KEY"))
23
+
24
+ png = client.take(url: "https://example.com", format: "png", full_page: true, block_cookie_banners: true)
25
+ File.binwrite("example.png", png)
26
+ ```
27
+
28
+ ## Signed og:image URL
29
+
30
+ `url` builds a `GET /take` link for `<img src>` or `<meta property="og:image">`. With a secret key it is signed
31
+ (HMAC-SHA256 of the query string), so nobody can change its options. Set the key to **signed requests only** in the
32
+ dashboard before you put its links in public pages.
33
+
34
+ ```ruby
35
+ client = Argoshot::Client.new(ENV.fetch("ARGOSHOT_ACCESS_KEY"), secret_key: ENV.fetch("ARGOSHOT_SECRET_KEY"))
36
+
37
+ og_image = client.url(
38
+ url: "https://example.com/blog/my-post",
39
+ viewport_width: 1200,
40
+ viewport_height: 630,
41
+ format: "png",
42
+ cache: true,
43
+ cache_ttl: 86_400
44
+ )
45
+ # <meta property="og:image" content="<%= og_image %>">
46
+ ```
47
+
48
+ ## HTML to PNG
49
+
50
+ When `html` (or `markdown`) is given, `take` sends a JSON `POST` instead of a long query string.
51
+
52
+ ```ruby
53
+ card = client.take(
54
+ html: '<div style="font: 64px system-ui; padding: 80px">Hello from Argoshot</div>',
55
+ format: "png",
56
+ viewport_width: 1200,
57
+ viewport_height: 630
58
+ )
59
+ File.binwrite("card.png", card)
60
+ ```
61
+
62
+ ## Options
63
+
64
+ Options are the API's own names (https://argoshot.com/docs/options), as keyword arguments or a hash: `url`, `html`,
65
+ `format`, `viewport_width`, `viewport_height`, `viewport_device`, `full_page`, `block_cookie_banners`, `block_ads`,
66
+ `dark_mode`, `selector`, `cache`, `cache_ttl` and 140 more. Lists are arrays: `hide_selectors: [".banner", "#chat"]`.
67
+
68
+ ## Errors
69
+
70
+ A failed request raises `Argoshot::Error` with the API's `code` (e.g. `selector_not_found`,
71
+ `screenshots_limit_reached`), `message`, HTTP `status`, `documentation_url`, and `upgrade_url` / `retry_after` when the
72
+ API gives them. All codes: https://argoshot.com/docs/errors
73
+
74
+ ```ruby
75
+ begin
76
+ client.take(url: "https://example.com", selector: "#missing", error_on_selector_not_found: true)
77
+ rescue Argoshot::Error => e
78
+ warn "#{e.code}: #{e.message}"
79
+ end
80
+ ```
81
+
82
+ ## Usage
83
+
84
+ ```ruby
85
+ client.usage # => {"total"=>..., "available"=>..., "used"=>..., ...}
86
+ ```
87
+
88
+ ## Configuration
89
+
90
+ ```ruby
91
+ Argoshot::Client.new(access_key, secret_key: nil, base_url: "https://api.argoshot.com", timeout: 120)
92
+ ```
93
+
94
+ Note: a key set to *signed requests only* cannot send JSON `POST` requests (the API refuses them), so `take(html: ...)`
95
+ needs a key that permits unsigned requests.
96
+
97
+ ## Licence
98
+
99
+ MIT
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Argoshot
4
+ VERSION = "0.1.0"
5
+ end
data/lib/argoshot.rb ADDED
@@ -0,0 +1,177 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "net/http"
5
+ require "openssl"
6
+ require "uri"
7
+
8
+ require_relative "argoshot/version"
9
+
10
+ # A small client for the Argoshot screenshot API (https://argoshot.com/docs). Standard library only.
11
+ #
12
+ # client = Argoshot::Client.new("ACCESS_KEY", secret_key: "SECRET_KEY")
13
+ # File.binwrite("example.png", client.take(url: "https://example.com", format: "png"))
14
+ # og_image = client.url(url: "https://example.com", viewport_width: 1200, viewport_height: 630)
15
+ module Argoshot
16
+ DEFAULT_BASE_URL = "https://api.argoshot.com"
17
+ CLIENT_OWN = %w[access_key signature].freeze
18
+
19
+ # An error the API answered (its error_code and error_message), or a response that was not the API's
20
+ # (code "http_error").
21
+ class Error < StandardError
22
+ attr_reader :code, :status, :documentation_url, :upgrade_url, :returned_status_code, :matched_string,
23
+ :retry_after, :body
24
+
25
+ def initialize(code:, message:, status: 0, documentation_url: nil, upgrade_url: nil,
26
+ returned_status_code: nil, matched_string: nil, retry_after: nil, body: nil)
27
+ super(message)
28
+ @code = code
29
+ @status = status
30
+ @documentation_url = documentation_url
31
+ @upgrade_url = upgrade_url
32
+ @returned_status_code = returned_status_code
33
+ @matched_string = matched_string
34
+ @retry_after = retry_after
35
+ @body = body
36
+ end
37
+ end
38
+
39
+ class Client
40
+ attr_reader :access_key, :secret_key, :base_url, :timeout
41
+
42
+ def initialize(access_key, secret_key: nil, base_url: DEFAULT_BASE_URL, timeout: 120)
43
+ raise ArgumentError, "Argoshot: an access key is required" if access_key.nil? || access_key.to_s.empty?
44
+
45
+ @access_key = access_key.to_s
46
+ @secret_key = secret_key.nil? || secret_key.to_s.empty? ? nil : secret_key.to_s
47
+ @base_url = (base_url || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, "")
48
+ @timeout = timeout
49
+ end
50
+
51
+ # A GET /take URL for these options (for <img src> or og:image), signed when a secret key is set.
52
+ # The access key is in the URL: for public pages, use a key set to "signed requests only".
53
+ def url(options = nil, **kwargs)
54
+ query = Argoshot.build_query(merge(options, kwargs))
55
+ query += "&" unless query.empty?
56
+ query += "access_key=#{Argoshot.encode(access_key)}"
57
+ query += "&signature=#{Argoshot.sign(secret_key, query)}" if secret_key
58
+ "#{base_url}/take?#{query}"
59
+ end
60
+
61
+ # Render and return the file's bytes (a binary String). Raises Argoshot::Error on failure.
62
+ # GET for url captures (signed when a secret key is set); a JSON POST when html or markdown is given.
63
+ def take(options = nil, **kwargs)
64
+ opts = Argoshot.clean(merge(options, kwargs))
65
+ if opts.key?("html") || opts.key?("markdown")
66
+ uri = URI("#{base_url}/take")
67
+ request = Net::HTTP::Post.new(uri)
68
+ request["Content-Type"] = "application/json"
69
+ request.body = JSON.generate(opts)
70
+ else
71
+ query = Argoshot.build_query(opts)
72
+ query += "&signature=#{Argoshot.sign(secret_key, query)}" if secret_key
73
+ uri = URI("#{base_url}/take?#{query}")
74
+ request = Net::HTTP::Get.new(uri)
75
+ end
76
+ send_request(uri, request)
77
+ end
78
+
79
+ # GET /usage: renders total, available and used, and the plan's limits. Costs nothing.
80
+ def usage
81
+ uri = URI("#{base_url}/usage")
82
+ JSON.parse(send_request(uri, Net::HTTP::Get.new(uri)))
83
+ end
84
+
85
+ private
86
+
87
+ def merge(options, kwargs)
88
+ merged = {}
89
+ (options || {}).each { |k, v| merged[k.to_s] = v }
90
+ kwargs.each { |k, v| merged[k.to_s] = v }
91
+ merged
92
+ end
93
+
94
+ def send_request(uri, request)
95
+ request["X-Access-Key"] = access_key
96
+ request["User-Agent"] = "argoshot-ruby/#{VERSION}"
97
+ request["Accept-Encoding"] = "identity"
98
+ response = perform(uri, request)
99
+ status = response.code.to_i
100
+ body = response.body.to_s
101
+ raise Argoshot.parse_error(status, body, response["Retry-After"]) unless status >= 200 && status < 300
102
+
103
+ body
104
+ end
105
+
106
+ def perform(uri, request)
107
+ Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
108
+ open_timeout: timeout, read_timeout: timeout) do |http|
109
+ http.request(request)
110
+ end
111
+ end
112
+ end
113
+
114
+ module_function
115
+
116
+ # The query string of these options: names sorted, lists repeated, nil left out (no access key).
117
+ def build_query(options)
118
+ opts = clean(options)
119
+ parts = []
120
+ opts.keys.sort.each do |name|
121
+ Array(opts[name]).each do |v|
122
+ next if v.nil?
123
+
124
+ parts << "#{encode(name)}=#{encode(text(v))}"
125
+ end
126
+ end
127
+ parts.join("&")
128
+ end
129
+
130
+ # The signature the API checks: lowercase hex HMAC-SHA256 of the query string, under the secret key.
131
+ def sign(secret_key, query)
132
+ OpenSSL::HMAC.hexdigest("SHA256", secret_key.to_s, query.to_s)
133
+ end
134
+
135
+ # An Argoshot::Error from an error response's status, body and Retry-After header.
136
+ def parse_error(status, body, retry_after = nil)
137
+ retry_seconds = retry_after.to_s.strip =~ /\A\d+\z/ ? retry_after.to_i : nil
138
+ data = begin
139
+ JSON.parse(body.to_s)
140
+ rescue JSON::ParserError
141
+ nil
142
+ end
143
+ if data.is_a?(Hash) && data["error_code"].is_a?(String)
144
+ return Error.new(code: data["error_code"], message: data["error_message"] || data["error_code"], status: status,
145
+ documentation_url: data["documentation_url"], upgrade_url: data["upgrade_url"],
146
+ returned_status_code: data["returned_status_code"], matched_string: data["matched_string"],
147
+ retry_after: retry_seconds, body: body)
148
+ end
149
+ snippet = body.to_s[0, 200]
150
+ Error.new(code: "http_error", message: "HTTP #{status}#{snippet.empty? ? '' : ": #{snippet}"}", status: status,
151
+ retry_after: retry_seconds, body: body)
152
+ end
153
+
154
+ def clean(options)
155
+ out = {}
156
+ (options || {}).each do |k, v|
157
+ name = k.to_s
158
+ next if v.nil? || CLIENT_OWN.include?(name)
159
+
160
+ out[name] = v
161
+ end
162
+ out
163
+ end
164
+
165
+ def text(value)
166
+ case value
167
+ when true then "true"
168
+ when false then "false"
169
+ else value.to_s
170
+ end
171
+ end
172
+
173
+ # RFC 3986: everything but A-Z a-z 0-9 - . _ ~ is percent-encoded (a space is %20, a + is %2B).
174
+ def encode(value)
175
+ value.to_s.dup.force_encoding(Encoding::BINARY).gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) }
176
+ end
177
+ end
metadata ADDED
@@ -0,0 +1,51 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: argoshot
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Argoshot
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-18 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description: Screenshots, PDFs and signed og:image URLs of any web page or HTML, from
14
+ the Argoshot API. Standard library only.
15
+ email:
16
+ executables: []
17
+ extensions: []
18
+ extra_rdoc_files: []
19
+ files:
20
+ - LICENSE
21
+ - README.md
22
+ - lib/argoshot.rb
23
+ - lib/argoshot/version.rb
24
+ homepage: https://argoshot.com
25
+ licenses:
26
+ - MIT
27
+ metadata:
28
+ homepage_uri: https://argoshot.com
29
+ documentation_uri: https://argoshot.com/docs
30
+ source_code_uri: https://github.com/rrlabs-io/argoshot-ruby
31
+ rubygems_mfa_required: 'true'
32
+ post_install_message:
33
+ rdoc_options: []
34
+ require_paths:
35
+ - lib
36
+ required_ruby_version: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - ">="
39
+ - !ruby/object:Gem::Version
40
+ version: '2.6'
41
+ required_rubygems_version: !ruby/object:Gem::Requirement
42
+ requirements:
43
+ - - ">="
44
+ - !ruby/object:Gem::Version
45
+ version: '0'
46
+ requirements: []
47
+ rubygems_version: 3.0.3.1
48
+ signing_key:
49
+ specification_version: 4
50
+ summary: Official client for the Argoshot screenshot API.
51
+ test_files: []