micompress 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bb22286474daaaaa3282785ff4887fa39cc071050e9a90a29834cc2c2d06eb2
-  data.tar.gz: 22e556306149811d188f7e278100898e33400957a2fc6de1c29c6cdb5f567286
+  metadata.gz: d3bcea3dd6d4bbf59978e96584f47451821f2f63b72fd36508057b7cdce962e4
+  data.tar.gz: e3f437b6b225fdceabf5c6b18cdb213aeb26aeba00fe0efa57497f4116c01df1
 SHA512:
-  metadata.gz: f8814ecd628c6ebe11627886effaf7d0b18b3a082787b6b7ed5efd8900b43ed1e3211d4f12ff33b4e8055743a563cfdd8a2726d126e68d46de285563a76c34d0
-  data.tar.gz: c4af22c5e3561ab916574050bb7aa4d7fd32ef8b3b6667291baabc0c1e3127bd47c2fc3ebab99f03d0c4890d09311855153eccfffcae310f24f4327635922638
+  metadata.gz: 0d8314810b0c1f84b0112210f00bdcd2ede98f864cdeac87ae14ec4983918f61dbfd740afddfb014c540b0f0f313feaec1404675d347c4528e0cd4d83e5454a8
+  data.tar.gz: a89bfadabe4f7effa41257fb22a5c6ee7e0c20f48c17060d71dd98de10199085bea9c35afc2100784b440b19f55de6130ce32f354deec82633727466ec340644

data/README.md

@@ -17,6 +17,28 @@ micompress *.png --preset extreme
 micompress report.pdf -o out/
 ```
 
+## API key
+
+Small files work without an account. For bigger files and a monthly allowance, use your personal API key
+(`mc_…`), shown on your [account page](https://micompress.com/account) — creating an account is free.
+
+```bash
+export MICOMPRESS_API_KEY=mc_your_key_here
+micompress big-video.mp4
+micompress big-video.mp4 --api-key mc_your_key_here   # the flag wins over the env var
+```
+
+| Plan | Compressions per month | Notes |
+|------|------------------------|-------|
+| No key (anonymous) | Anonymous limits | Small files only |
+| Free account | 50 via the API | Files up to 100 MB |
+| Plus ($9.99/mo) | 1,000 | Shared with website usage |
+| Pro ($19.99/mo) | 5,000 | Shared with website usage |
+
+When the allowance is used up you get `API_QUOTA_REACHED` (free) or `USAGE_LIMIT_REACHED` (paid) —
+see [micompress.com/plans](https://micompress.com/plans). `--token` is the older login-token option and
+still works. Keep the key secret: anyone who has it can spend your quota.
+
 ## Library
 
 ```ruby
@@ -25,15 +47,16 @@ require "micompress"
 bytes, meta = Micompress.compress_file("photo.jpg", preset: "extreme")
 File.binwrite("photo-min.jpg", bytes)
 puts "#{meta['savedPercent']}% smaller"
+
+# With an API key; errors raise Micompress::Error, whose #code holds the server code
+bytes, meta = Micompress.compress_file("big.pdf", api_key: ENV["MICOMPRESS_API_KEY"])
 ```
 
 ## Build & publish
 
-Requires Ruby (not available on this build server):
-
 ```bash
 gem build micompress.gemspec
-gem push micompress-0.1.0.gem
+gem push micompress-0.1.1.gem
 ```
 
 ## License

data/exe/micompress

@@ -10,7 +10,8 @@ parser = OptionParser.new do |o|
   o.on("-o", "--output DIR", "Output directory") { |v| options[:output] = v }
   o.on("-p", "--preset NAME", %w[lossless recommended extreme], "lossless|recommended|extreme") { |v| options[:preset] = v }
   o.on("--max-width PX", Integer, "Resize images to max width") { |v| options[:max_width] = v }
-  o.on("--token JWT", "Auth token for higher limits") { |v| options[:token] = v }
+  o.on("--api-key KEY", "Personal API key from micompress.com/account (default: $MICOMPRESS_API_KEY)") { |v| options[:api_key] = v }
+  o.on("--token JWT", "Legacy login token (JWT); prefer --api-key") { |v| options[:token] = v }
   o.on("--api URL", "API base URL") { |v| options[:base_url] = v }
   o.on("--suffix STR", "Default output suffix (default -min)") { |v| options[:suffix] = v }
   o.on("-q", "--quiet", "Only print errors") { options[:quiet] = true }
@@ -18,6 +19,9 @@ parser = OptionParser.new do |o|
   o.on("-h", "--help", "Show help") { puts o; exit }
 end
 files = parser.parse(ARGV)
+# Flag wins over the environment variable.
+api_key = (options[:api_key] || ENV["MICOMPRESS_API_KEY"]).to_s.strip
+options[:api_key] = api_key.empty? ? nil : api_key
 
 if files.empty?
   puts parser
@@ -53,7 +57,8 @@ files.each do |file|
   begin
     bytes, meta = Micompress.compress_file(
       file, base_url: options[:base_url], preset: options[:preset],
-      max_width: options[:max_width], token: options[:token]
+      max_width: options[:max_width], token: options[:token],
+      api_key: options[:api_key]
     )
     dest = out_path(file, options)
     File.binwrite(dest, bytes)

data/lib/micompress/client.rb

@@ -4,16 +4,33 @@ require "net/http"
 require "uri"
 require "json"
 require_relative "categories"
+# VERSION is used below; requiring it here keeps this file loadable on its own
+# instead of depending on micompress.rb having run first.
+require_relative "version"
 
 module Micompress
   DEFAULT_BASE = "https://micompress.com"
   UTM = "utm_source=rubygems&utm_medium=cli&utm_campaign=extend"
   USER_AGENT = "micompress-ruby/#{VERSION} (+https://micompress.com)"
+  # Where users get a personal API key, and where to upgrade when its quota runs out.
+  ACCOUNT_URL = "#{DEFAULT_BASE}/account"
+  PLANS_URL = "#{DEFAULT_BASE}/plans"
 
-  class Error < StandardError; end
+  class Error < StandardError
+    # Machine-readable server code, e.g. "INVALID_API_KEY" (nil for local errors).
+    attr_reader :code
+
+    def initialize(message = nil, code = nil)
+      super(message)
+      @code = code
+    end
+  end
 
   # Compress a single file. Returns [bytes, meta_hash].
-  def self.compress_file(path, base_url: DEFAULT_BASE, preset: "recommended", max_width: nil, token: nil)
+  # api_key: personal key ("mc_...") from micompress.com/account, sent as X-API-Key.
+  # token:   legacy login JWT, still sent as a Bearer header if given.
+  def self.compress_file(path, base_url: DEFAULT_BASE, preset: "recommended", max_width: nil, token: nil,
+                         api_key: nil)
     base = base_url.chomp("/")
     filename = File.basename(path)
     category = category_for(filename)
@@ -24,6 +41,8 @@ module Micompress
     req = Net::HTTP::Post.new(uri)
     req["Accept"] = "application/json"
     req["User-Agent"] = USER_AGENT
+    req["X-MiCompress-Client"] = "ruby/#{VERSION}"
+    req["X-API-Key"] = api_key if api_key
     req["Authorization"] = "Bearer #{token}" if token
 
     form = [["file", File.open(path, "rb"), { filename: filename, content_type: "application/octet-stream" }],
@@ -32,14 +51,34 @@ module Micompress
     req.set_form(form, "multipart/form-data")
 
     json = request_json(uri, req)
-    unless json["success"] && json["downloadUrl"]
-      raise Error, (json["error"] || "Compression failed")
-    end
+    raise api_error(json, base) unless json["success"] && json["downloadUrl"]
 
     bytes = download("#{base}#{json['downloadUrl']}", token)
     [bytes, json]
   end
 
+  # Append "<lead> <url>" unless the server's message already names the URL.
+  def self.with_hint(message, lead, url)
+    message.include?(url.sub(%r{\Ahttps?://}, "")) ? message : "#{message} #{lead} #{url}"
+  end
+
+  def self.api_error(json, base)
+    code = json["code"]
+    message =
+      case code
+      when "LOGIN_REQUIRED"
+        "File exceeds the anonymous size limit. Pass --api-key <key> (free key at #{ACCOUNT_URL}) " \
+          "or compress it online at #{base}/?#{UTM}"
+      when "INVALID_API_KEY"
+        with_hint(json["error"] || "Invalid API key.", "Check your key at", ACCOUNT_URL)
+      when "API_QUOTA_REACHED", "USAGE_LIMIT_REACHED"
+        with_hint(json["error"] || "Monthly compression quota reached.", "Upgrade for a bigger monthly quota:", PLANS_URL)
+      else
+        json["error"] || "Compression failed"
+      end
+    Error.new(message, code)
+  end
+
   def self.request_json(uri, req)
     res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
       http.read_timeout = 120

data/lib/micompress/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Micompress
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: micompress
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - MiCompress
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-29 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies: []
 description: A tiny command-line client and library for the micompress.com compression
   API.