yourimageshare 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee8bed4a3f8b3383ae8ca06a4031231c404aa4c843bc65578ff7b2d8b8c1eed4
+  data.tar.gz: 5f7201b52c57bb2d283da2730ef68d79386d2748bb03c99b8fc9348f5e3e1e8c
+SHA512:
+  metadata.gz: 2fa5756c5aa8d1f779301b731b6532e70f0d99ea068d4f0f6baa7b2361fef9c5857a817909c76c54054f6bf554d6b97fa59fbc29f70828ea3011490e7fb9a5e1
+  data.tar.gz: 10571f3b239e22ee6dd9b544a1db000938dde0a7f03110cb64f52c6e0826a586c8e01b4376a7d1934594c3a9c8c5ea9a6b1731b642f9d33b0b91ac5dde283926

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YourImageShare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# yourimageshare-api/ruby
+
+[![Gem Version](https://badge.fury.io/rb/yourimageshare.svg)](https://rubygems.org/gems/yourimageshare)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Ruby SDK for the [YourImageShare](https://yourimageshare.com)
+upload API. Zero gem dependencies (standard library only), Ruby 2.7+.
+
+- **Get an API key:** sign in and open the **API** tab at
+  [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.
+
+## Install
+
+```bash
+gem install yourimageshare
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "yourimageshare"
+```
+
+## Usage
+
+```ruby
+require "yourimageshare"
+
+client = YourImageShare::Client.new("YOUR_API_KEY")
+
+# Upload a file by path
+result = client.upload("photo.jpg")
+puts result.direct # https://yourimageshare.com/ib/aB3xY9qRz1
+
+# Upload with auto-delete after 1 hour
+client.upload("photo.jpg", expires_in: 3600)
+
+# Upload from any IO-like object (a network stream, an in-memory buffer, ...)
+# client.upload_io(io, "photo.jpg")
+
+# List your uploads (paginated, 50 per page)
+listing = client.list
+listing.data.each { |item| puts "#{item.id} #{item.direct}" }
+
+# Delete an upload
+client.delete(result.id)
+```
+
+### Error handling
+
+Unlike the Go SDK's `(result, error)` return style, the Ruby SDK follows
+Ruby convention and raises `YourImageShare::APIError` (`.status` is the
+HTTP status code, `.message` is the server's error text):
+
+```ruby
+begin
+  client.upload("photo.jpg")
+rescue YourImageShare::APIError => e
+  puts "#{e.status}: #{e.message}"
+end
+```
+
+## API
+
+### `YourImageShare::Client.new(api_key, base_url: "https://yourimageshare.com/api", timeout: 30)`
+
+`base_url` and `timeout` are keyword overrides, mainly for testing.
+
+### `client.upload(file_path, expires_in: nil) -> UploadResult`
+
+Streams the file from disk rather than buffering the whole thing in memory
+first - uploads can be up to 200MB. `expires_in` is seconds, 60 to
+2,592,000 (30 days); nil means a permanent upload. Returns an
+`UploadResult` with `id`, `type`, `path`, `src`, `direct`, `expires_at`.
+
+### `client.upload_io(io, filename, expires_in: nil) -> UploadResult`
+
+Same as `upload`, but from any IO-like object instead of a file path.
+
+### `client.list(page = nil) -> ListResult`
+
+Returns a `ListResult` with `data` (an array of `ListedUpload` - `id`,
+`type`, `title`, `path`, `src`, `direct`, `expires_at`, `created_at`) and
+`meta` (`ListMeta` - `current_page`, `last_page`, `total`).
+
+### `client.delete(id) -> nil`
+
+Raises `APIError` on a 404/401.
+
+## Rate limits
+
+20 requests/minute and 500/day per key by default (2,000/day per IP as a
+backstop). Not currently surfaced on the return values from this SDK - read
+the `X-RateLimit-Limit`/`X-RateLimit-Remaining` response headers yourself if
+you need them, or open an issue to request them on the result types.
+
+## License
+
+MIT
+
+## Support
+
+[yourimageshare.com/contact](https://yourimageshare.com/contact)

data/lib/yourimageshare/client.rb

@@ -0,0 +1,97 @@
+require "net/http"
+require "uri"
+require "json"
+
+module YourImageShare
+  DEFAULT_BASE_URL = "https://yourimageshare.com/api"
+
+  # Talks to the YourImageShare upload API. Create one with
+  # YourImageShare::Client.new(api_key). Get a key from the API tab at
+  # https://yourimageshare.com/my-account.
+  class Client
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url
+      @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)
+      File.open(file_path, "rb") do |f|
+        upload_io(f, File.basename(file_path), expires_in: expires_in)
+      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)
+
+      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")
+
+      body = execute(uri, request)
+      UploadResult.from_json(body["data"] || {})
+    end
+
+    # Returns your uploads, newest first, 50 per page. page < 2 fetches the
+    # first page.
+    def list(page = nil)
+      uri = URI(@base_url)
+      uri.query = URI.encode_www_form(page: page) if page && page > 1
+
+      request = Net::HTTP::Get.new(uri)
+      set_common_headers(request)
+
+      ListResult.from_json(execute(uri, request))
+    end
+
+    # Removes one of your uploads by id. Raises APIError on failure.
+    def delete(id)
+      uri = URI("#{@base_url}/#{URI.encode_www_form_component(id)}")
+      request = Net::HTTP::Delete.new(uri)
+      set_common_headers(request)
+
+      execute(uri, request)
+      nil
+    end
+
+    private
+
+    def set_common_headers(request)
+      request["X-API-Key"] = @api_key
+      request["User-Agent"] = "yourimageshare-ruby/#{VERSION}"
+    end
+
+    def execute(uri, request)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                  open_timeout: @timeout, read_timeout: @timeout) do |http|
+        http.request(request)
+      end
+
+      envelope = begin
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        raise APIError.new(response.code.to_i, "unexpected non-JSON response (HTTP #{response.code})")
+      end
+
+      status = response.code.to_i
+      if status < 200 || status >= 300 || envelope["type"] == "error"
+        message = envelope["errors"]
+        message = "request failed (HTTP #{status})" if message.nil? || message.empty?
+        raise APIError.new(status, message)
+      end
+
+      envelope
+    end
+  end
+end

data/lib/yourimageshare/errors.rb

@@ -0,0 +1,15 @@
+module YourImageShare
+  # Raised for any non-2xx response or a `{"type":"error"}` payload -
+  # mirrors the Go/JS/Python/PHP SDKs' error shape (status + message) so
+  # error-handling logic reads the same across every official SDK. Ruby
+  # convention is to raise, not to return an error object like Go does.
+  class APIError < StandardError
+    attr_reader :status, :message
+
+    def initialize(status, message)
+      @status = status
+      @message = message
+      super("yourimageshare: [#{status}] #{message}")
+    end
+  end
+end

data/lib/yourimageshare/types.rb

@@ -0,0 +1,34 @@
+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
+    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"])
+    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
+    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"])
+    end
+  end
+
+  # Pagination info for a #list result.
+  ListMeta = Struct.new(:current_page, :last_page, :total, keyword_init: true) do
+    def self.from_json(h)
+      new(current_page: h["current_page"], last_page: h["last_page"], total: h["total"])
+    end
+  end
+
+  # Response shape for #list.
+  ListResult = Struct.new(:data, :meta, keyword_init: true) do
+    def self.from_json(h)
+      new(data: (h["data"] || []).map { |row| ListedUpload.from_json(row) },
+          meta: ListMeta.from_json(h["meta"] || {}))
+    end
+  end
+end

data/lib/yourimageshare/version.rb

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

data/lib/yourimageshare.rb

@@ -0,0 +1,14 @@
+require_relative "yourimageshare/version"
+require_relative "yourimageshare/errors"
+require_relative "yourimageshare/types"
+require_relative "yourimageshare/client"
+
+# The official Ruby client for the YourImageShare upload API
+# (https://yourimageshare.com/about/api). It mirrors the existing Go, JS
+# (npm), and Python (PyPI) SDKs - same method names, same result shapes,
+# same error semantics - just idiomatic Ruby on top (raises APIError
+# instead of Go's (result, error) return style).
+#
+# Zero gem dependencies - only the Ruby standard library.
+module YourImageShare
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: yourimageshare
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- YourImageShare
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-27 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.
+email:
+- support@yourimageshare.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/yourimageshare.rb
+- lib/yourimageshare/client.rb
+- lib/yourimageshare/errors.rb
+- lib/yourimageshare/types.rb
+- lib/yourimageshare/version.rb
+homepage: https://yourimageshare.com/about/api
+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
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Official Ruby client for the YourImageShare upload API
+test_files: []