yourimageshare 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee8bed4a3f8b3383ae8ca06a4031231c404aa4c843bc65578ff7b2d8b8c1eed4
-  data.tar.gz: 5f7201b52c57bb2d283da2730ef68d79386d2748bb03c99b8fc9348f5e3e1e8c
+  metadata.gz: 1b5d4188f0b04cf69a8275bc809330e30bd0e5d9b7451a81b5080c5db3b26696
+  data.tar.gz: 3c03786f86644591965adce714cb982b6c3ba5b354041c4b1275704e88d8ffa0
 SHA512:
-  metadata.gz: 2fa5756c5aa8d1f779301b731b6532e70f0d99ea068d4f0f6baa7b2361fef9c5857a817909c76c54054f6bf554d6b97fa59fbc29f70828ea3011490e7fb9a5e1
-  data.tar.gz: 10571f3b239e22ee6dd9b544a1db000938dde0a7f03110cb64f52c6e0826a586c8e01b4376a7d1934594c3a9c8c5ea9a6b1731b642f9d33b0b91ac5dde283926
+  metadata.gz: 8befda17710e2812ae563cfc8c903566975dee700a5186b7d2688b0166bed3253aae8b477c05d3d54e67e3f345c9d81a0efda88be8223b5295e167748c36e857
+  data.tar.gz: eb6ac978baf41b1d186213862490160ba005a2dc5f2eaad5fdb812e6e60c1f8e09328c4a2530abd545f2799ff1945e8635b6ccbc584457b52671767e386de8f4

data/README.md

@@ -10,7 +10,7 @@ upload API. Zero gem dependencies (standard library only), Ruby 2.7+.
   [yourimageshare.com/my-account](https://yourimageshare.com/my-account).
 - **Full HTTP reference:** [yourimageshare.com/about/api](https://yourimageshare.com/about/api)
   or [API.md in this repo](../API.md).
-- Same API, same result shapes, in [JavaScript/TypeScript](https://www.npmjs.com/package/yourimageshare), [Python](https://pypi.org/project/yourimageshare/), [PHP](https://packagist.org/packages/yourimageshare/yourimageshare-php), and [Go](https://pkg.go.dev/github.com/MediaShareORG/yourimageshare/go) too.
+- Same API, same result shapes, in [JavaScript/TypeScript](https://www.npmjs.com/package/yourimageshare), [Python](https://pypi.org/project/yourimageshare/), [PHP](https://packagist.org/packages/yourimageshare/yourimageshare-php), and [Go](https://pkg.go.dev/github.com/yourimageshare/yourimageshare/go) too.
 
 ## Install
 
@@ -49,6 +49,33 @@ listing.data.each { |item| puts "#{item.id} #{item.direct}" }
 client.delete(result.id)
 ```
 
+### Large files, duplicates, links and thumbnails
+
+Files up to 200 MB are supported. Anything over 90 MB is sent in 5 MB pieces automatically (one request can carry at most 100 MB). If your account already uploaded the exact same file, the existing upload is returned with `duplicate` set - opt out with the allow-duplicate option. Results also carry `thumb` (a 280 px WebP thumbnail), `width`, `height`, `size` and `locked`. Store `src`, not `path`: `path` can change shortly after upload when the file is converted (WebP/MP4).
+
+```ruby
+result = client.upload("video.mp4") { |sent, total| puts "#{sent * 100 / total}%" }
+puts result.src, result.thumb, result.width, result.duplicate
+
+# a fresh copy even if this exact file is already on your account
+client.upload("photo.jpg", allow_duplicate: true)
+
+# let the server download a public link (up to 200 MB)
+client.upload_url("https://example.com/photo.jpg")
+```
+
+### Visibility, titles and changing an upload
+
+Each upload has a `visibility`: `unlisted` (the default - file and page work for anyone with the link, not listed anywhere), `private` (file only - the page link sends everyone but you to the file) or `public` (listed on the site). Uploads can carry a `title` (90 characters) and `description` (500). New uploads return a one-time `delete_url` that deletes the upload without an API key. `get`/`update` need the full API key.
+
+```ruby
+result = client.upload("photo.jpg", visibility: "private", title: "Sunset")
+puts result.delete_url # shown once - keep it if you need it
+
+one = client.get(result.id)
+client.update(result.id, visibility: "public", description: "Lake at dusk")
+```
+
 ### Error handling
 
 Unlike the Go SDK's `(result, error)` return style, the Ruby SDK follows

data/lib/yourimageshare/client.rb

@@ -1,9 +1,15 @@
 require "net/http"
 require "uri"
 require "json"
+require "securerandom"
+require "stringio"
 
 module YourImageShare
   DEFAULT_BASE_URL = "https://yourimageshare.com/api"
+  # Files above this size are sent in pieces (one request can carry at most 100 MB).
+  CHUNK_THRESHOLD = 90 * 1024 * 1024
+  # Size of one piece of a chunked upload (the API accepts at most 5 MB).
+  CHUNK_SIZE = 5 * 1024 * 1024
 
   # Talks to the YourImageShare upload API. Create one with
   # YourImageShare::Client.new(api_key). Get a key from the API tab at
@@ -17,30 +23,60 @@ module YourImageShare
       @timeout = timeout
     end
 
-    # Uploads a local file by path. expires_in (seconds, 60 to 2,592,000 =
-    # 30 days) auto-deletes the upload later; nil means a permanent upload.
-    def upload(file_path, expires_in: nil)
+    # Uploads a local file by path (up to 200 MB). expires_in (seconds, 60 to
+    # 2,592,000 = 30 days) auto-deletes the upload later; nil means a
+    # permanent upload. If your account already uploaded this exact file,
+    # that upload is returned with duplicate = true - pass
+    # allow_duplicate: true to store a new copy. Files over 90 MB are sent in
+    # 5 MB pieces automatically; the block, if given, is called with
+    # (bytes_sent, total) after each piece.
+    def upload(file_path, expires_in: nil, allow_duplicate: false, visibility: nil, title: nil, description: nil, &on_progress)
       File.open(file_path, "rb") do |f|
-        upload_io(f, File.basename(file_path), expires_in: expires_in)
+        upload_io(f, File.basename(file_path), expires_in: expires_in, allow_duplicate: allow_duplicate,
+                                             visibility: visibility, title: title, description: description, &on_progress)
       end
     end
 
     # Uploads from any IO-like object (must respond to #read). filename
     # should include a real extension so the server can infer content type.
-    def upload_io(io, filename, expires_in: nil)
-      uri = URI(@base_url)
-      request = Net::HTTP::Post.new(uri)
-      set_common_headers(request)
+    def upload_io(io, filename, expires_in: nil, allow_duplicate: false, visibility: nil, title: nil, description: nil, &on_progress)
+      size = io_size(io)
+      if size && size > CHUNK_THRESHOLD
+        upload_id = send_chunks(io, size, &on_progress)
+        return post_upload([["upload_id", upload_id], ["filename", filename]], expires_in, allow_duplicate,
+                           visibility, title, description)
+      end
 
-      form = [["uploads", io, { filename: filename }]]
-      form << ["expires_in", expires_in.to_s] if expires_in && expires_in > 0
       # Net::HTTP streams IO form values in chunks rather than buffering
-      # the whole file into memory - important since uploads can be up to
-      # 200MB (video).
-      request.set_form(form, "multipart/form-data")
+      # the whole file into memory.
+      post_upload([["uploads", io, { filename: filename }]], expires_in, allow_duplicate, visibility, title, description)
+    end
 
-      body = execute(uri, request)
-      UploadResult.from_json(body["data"] || {})
+    # Uploads from a public http(s) link: the server downloads the file
+    # itself (up to 200 MB).
+    def upload_url(url, expires_in: nil, allow_duplicate: false, visibility: nil, title: nil, description: nil)
+      post_upload([["url", url]], expires_in, allow_duplicate, visibility, title, description)
+    end
+
+    # One of your uploads (needs the full API key).
+    def get(id)
+      uri = URI("#{@base_url.chomp("/")}/#{URI.encode_www_form_component(id)}")
+      request = Net::HTTP::Get.new(uri)
+      set_common_headers(request)
+      ListedUpload.from_json(execute(uri, request)["data"] || {})
+    end
+
+    # Changes the visibility ("private", "unlisted", "public"), title or
+    # description of one of your uploads (needs the full API key). Only the
+    # arguments you pass change; an empty string clears a title/description.
+    def update(id, visibility: nil, title: nil, description: nil)
+      changes = { visibility: visibility, title: title, description: description }.compact
+      uri = URI("#{@base_url.chomp("/")}/#{URI.encode_www_form_component(id)}")
+      request = Net::HTTP::Patch.new(uri)
+      set_common_headers(request)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(changes)
+      ListedUpload.from_json(execute(uri, request)["data"] || {})
     end
 
     # Returns your uploads, newest first, 50 per page. page < 2 fetches the
@@ -67,14 +103,64 @@ module YourImageShare
 
     private
 
+    def post_upload(form, expires_in, allow_duplicate, visibility = nil, title = nil, description = nil)
+      uri = URI(@base_url)
+      request = Net::HTTP::Post.new(uri)
+      set_common_headers(request)
+      form << ["expires_in", expires_in.to_s] if expires_in && expires_in > 0
+      form << ["allow_duplicate", "1"] if allow_duplicate
+      form << ["visibility", visibility.to_s] if visibility
+      form << ["title", title] unless title.nil?
+      form << ["description", description] unless description.nil?
+      request.set_form(form, "multipart/form-data")
+
+      body = execute(uri, request, [@timeout, 180].max)
+      UploadResult.from_json(body["data"] || {})
+    end
+
+    def send_chunks(io, size)
+      upload_id = SecureRandom.hex(16)
+      total = (size + CHUNK_SIZE - 1) / CHUNK_SIZE
+      sent = 0
+      uri = URI("#{@base_url.chomp("/")}/chunk")
+      total.times do |index|
+        piece = io.read(CHUNK_SIZE)
+        attempt = 0
+        begin
+          attempt += 1
+          request = Net::HTTP::Post.new(uri)
+          set_common_headers(request)
+          request.set_form([["upload_id", upload_id], ["index", index.to_s], ["total", total.to_s],
+                            ["chunk", StringIO.new(piece), { filename: "piece" }]], "multipart/form-data")
+          execute(uri, request)
+        rescue APIError, IOError, SystemCallError, Timeout::Error => e
+          # network errors and 5xx are retried; anything the server refused (4xx) is final
+          status = e.respond_to?(:status) ? e.status.to_i : 0
+          retry if attempt < 3 && !(status >= 400 && status < 500)
+          raise
+        end
+        sent += piece.bytesize
+        yield(sent, size) if block_given?
+      end
+      upload_id
+    end
+
+    def io_size(io)
+      return io.size - io.pos if io.respond_to?(:size) && io.respond_to?(:pos)
+      return File.size(io.path) - io.pos if io.respond_to?(:path) && io.respond_to?(:pos)
+      nil
+    rescue StandardError
+      nil
+    end
+
     def set_common_headers(request)
       request["X-API-Key"] = @api_key
       request["User-Agent"] = "yourimageshare-ruby/#{VERSION}"
     end
 
-    def execute(uri, request)
+    def execute(uri, request, read_timeout = @timeout)
       response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                  open_timeout: @timeout, read_timeout: @timeout) do |http|
+                                  open_timeout: @timeout, read_timeout: read_timeout, write_timeout: read_timeout) do |http|
         http.request(request)
       end
 

data/lib/yourimageshare/types.rb

@@ -1,19 +1,35 @@
 module YourImageShare
   # Response shape for a successful upload - same fields as the
   # Go/JS/Python/PHP SDKs' UploadResult.
-  UploadResult = Struct.new(:id, :type, :path, :src, :direct, :expires_at, keyword_init: true) do
+  #
+  # path is the storage URL as uploaded and can change shortly afterwards
+  # when the file is converted (WebP/MP4) - store src, the permanent link.
+  # thumb is a 280 px WebP thumbnail (or nil); size is in bytes; duplicate is
+  # true when your account already had this exact file and that upload was
+  # returned.
+  # visibility is "private" (file only), "unlisted" (page for anyone with the
+  # link) or "public" (listed); delete_url (new uploads only) deletes the
+  # upload without an API key and is shown once.
+  UploadResult = Struct.new(:id, :type, :path, :src, :direct, :thumb, :width, :height, :size, :locked,
+                            :visibility, :title, :description, :expires_at, :duplicate, :delete_url,
+                            keyword_init: true) do
     def self.from_json(h)
-      new(id: h["id"], type: h["type"], path: h["path"], src: h["src"],
-          direct: h["direct"], expires_at: h["expires_at"])
+      new(id: h["id"], type: h["type"], path: h["path"], src: h["src"], direct: h["direct"],
+          thumb: h["thumb"], width: h["width"], height: h["height"], size: h["size"],
+          locked: h["locked"] == true, visibility: h["visibility"], title: h["title"],
+          description: h["description"], expires_at: h["expires_at"], duplicate: h["duplicate"] == true,
+          delete_url: h["delete_url"])
     end
   end
 
   # One row of a #list result.
-  ListedUpload = Struct.new(:id, :type, :title, :path, :src, :direct, :expires_at, :created_at, keyword_init: true) do
+  ListedUpload = Struct.new(:id, :type, :title, :path, :src, :direct, :thumb, :width, :height, :size, :locked,
+                            :visibility, :description, :expires_at, :created_at, keyword_init: true) do
     def self.from_json(h)
       new(id: h["id"], type: h["type"], title: h["title"], path: h["path"],
-          src: h["src"], direct: h["direct"], expires_at: h["expires_at"],
-          created_at: h["created_at"])
+          src: h["src"], direct: h["direct"], thumb: h["thumb"], width: h["width"], height: h["height"],
+          size: h["size"], locked: h["locked"] == true, visibility: h["visibility"],
+          description: h["description"], expires_at: h["expires_at"], created_at: h["created_at"])
     end
   end
 

data/lib/yourimageshare/version.rb

@@ -1,3 +1,3 @@
 module YourImageShare
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yourimageshare
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - YourImageShare
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies: []
 description: Upload, list, and delete files through the YourImageShare (https://yourimageshare.com)
   JSON/REST API. Zero gem dependencies - standard library only.
@@ -30,8 +30,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://yourimageshare.com/about/api
-  source_code_uri: https://github.com/MediaShareORG/yourimageshare/tree/main/ruby
-  changelog_uri: https://github.com/MediaShareORG/yourimageshare/tree/main/ruby/README.md
+  source_code_uri: https://github.com/yourimageshare/yourimageshare/tree/main/ruby
+  changelog_uri: https://github.com/yourimageshare/yourimageshare/tree/main/ruby/README.md
 post_install_message:
 rdoc_options: []
 require_paths: