file_hutch 0.1.0

data/lib/file_hutch/cli.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "optparse"
+
+module FileHutch
+  # `file_hutch` on the command line. Plan/apply a project's config file,
+  # export it, inspect the project, upload a file, dump the manifest.
+  # Reads FILE_HUTCH_API_KEY and FILE_HUTCH_URL like the library does.
+  class CLI
+    DEFAULT_FILE = "file_hutch.yml"
+    MARK = { "create" => "+", "update" => "~", "delete" => "-", "noop" => "=" }.freeze
+
+    USAGE = <<~TEXT
+      Usage: file_hutch <command> [options]
+
+        plan    [FILE] [--prune]          show what apply would change (read-only keys allowed)
+        apply   [FILE] [--prune] [--yes]  make the project match FILE
+        export                            print the project as a config file
+        inspect                           project, environment, storage, plan and usage
+        upload  PATH --policy NAME        direct upload, prints the file id
+        manifest                          every ready file with its object key, as JSON lines
+        version
+
+      FILE defaults to #{DEFAULT_FILE}. Nothing is deleted without --prune; with --prune,
+      apply asks before deleting unless --yes is given.
+      Environment: FILE_HUTCH_API_KEY (required), FILE_HUTCH_URL.
+    TEXT
+
+    def initialize(argv, out: $stdout, err: $stderr, input: $stdin, client: nil)
+      @argv, @out, @err, @input, @client = argv.dup, out, err, input, client
+    end
+
+    # Returns the exit status.
+    def run
+      command = @argv.shift
+      case command
+      when "plan" then plan
+      when "apply" then apply
+      when "export" then export
+      when "inspect" then inspect_project
+      when "upload" then upload
+      when "manifest" then manifest
+      when "version", "--version", "-v" then print_and_succeed("file_hutch #{VERSION}")
+      when nil, "help", "--help", "-h" then print_and_succeed(USAGE)
+      else
+        @err.puts("Unknown command #{command.inspect}\n\n#{USAGE}")
+        2
+      end
+    rescue ConfigurationError => e
+      @err.puts(e.message)
+      2
+    rescue ApiError => e
+      @err.puts("FileHutch said no (#{e.code}): #{e.message}")
+      1
+    rescue ConnectionError => e
+      @err.puts("Could not reach FileHutch: #{e.message}")
+      1
+    end
+
+    private
+
+    def client
+      @client ||= Client.new
+    end
+
+    def print_and_succeed(text)
+      @out.puts(text)
+      0
+    end
+
+    # -- plan / apply -------------------------------------------------------
+
+    def plan
+      options = parse_options
+      config = read_config(options[:file]) or return 2
+      plan = client.plan_config(config, prune: options[:prune])
+      print_changes(plan["changes"])
+      summary = plan["summary"]
+      @out.puts "Plan: #{summary['create']} to create, #{summary['update']} to update, #{summary['delete']} to delete."
+      0
+    end
+
+    def apply
+      options = parse_options
+      config = read_config(options[:file]) or return 2
+
+      if options[:prune] && !options[:yes]
+        plan = client.plan_config(config, prune: true)
+        deletes = plan["changes"].select { |c| c["action"] == "delete" }
+        if deletes.any?
+          print_changes(deletes)
+          @out.print "Delete #{deletes.size} #{deletes.size == 1 ? 'resource' : 'resources'}? [y/N] "
+          @out.flush
+          unless @input.gets.to_s.strip.downcase.start_with?("y")
+            @out.puts "Nothing applied."
+            return 1
+          end
+        end
+      end
+
+      result = client.apply_config(config, prune: options[:prune])
+      result["results"].each do |r|
+        line = "#{MARK.fetch(r['action'], '?')} #{r['resource']} #{r['name']}"
+        line += "  #{describe_diff(r['diff'])}" if r["diff"]
+        line += r["status"] == "applied" ? "  ok" : "  FAILED: #{r['error']}"
+        @out.puts line
+      end
+      summary = result["summary"]
+      @out.puts "Applied #{summary['applied']}, failed #{summary['failed']}, unchanged #{summary['noop']}."
+      summary["failed"].to_i.zero? ? 0 : 1
+    end
+
+    def export
+      @out.puts YAML.dump(client.project_config).sub(/\A---\n/, "")
+      0
+    end
+
+    # -- inspect / upload / manifest ----------------------------------------
+
+    def inspect_project
+      project = client.project
+      env = project["environment"]
+      storage = project.storage_connection
+      plan = project["plan"] || {}
+      usage = project["usage"] || {}
+      @out.puts "#{project['name']} (#{project.id})"
+      @out.puts "  environment: #{env ? env['name'] : 'production'}#{" of #{project['environments'].join(', ')}" if project['environments']}"
+      if storage
+        @out.puts "  storage:     #{storage['provider']} (#{storage['mode']})#{storage['status'] ? ", #{storage['status']}" : ''}"
+      else
+        @out.puts "  storage:     none connected"
+      end
+      if plan["name"]
+        used = usage["storage_bytes_used"].to_i
+        @out.puts "  plan:        #{plan['name']}, #{human_size(used)} of #{human_size(plan['storage_bytes'].to_i)} used, " \
+                  "#{usage['projects_used']} of #{plan['project_limit'] || 'unlimited'} projects"
+      end
+      @out.puts "  policies:    #{project.upload_policies.map { |p| "#{p.name} (#{p.visibility}, #{human_size(p.maximum_size.to_i)})" }.join(', ').then { _1.empty? ? 'none' : _1 }}"
+      @out.puts "  transforms:  #{project.transforms.map(&:name).join(', ').then { _1.empty? ? 'none' : _1 }}"
+      0
+    end
+
+    def upload
+      options = { policy: nil }
+      parser = OptionParser.new do |o|
+        o.on("--policy NAME") { |v| options[:policy] = v }
+        o.on("--content-type TYPE") { |v| options[:content_type] = v }
+      end
+      paths = parser.parse(@argv)
+      path = paths.first
+      if path.nil? || options[:policy].nil?
+        @err.puts "Usage: file_hutch upload PATH --policy NAME"
+        return 2
+      end
+      unless ::File.file?(path)
+        @err.puts "No such file: #{path}"
+        return 2
+      end
+
+      file = client.upload(path, policy: options[:policy], content_type: options[:content_type])
+      @out.puts file.id
+      0
+    end
+
+    def manifest
+      after = nil
+      loop do
+        page = client.manifest(after: after)
+        page.fetch("files").each { |entry| @out.puts JSON.generate(entry) }
+        break unless page["has_more"]
+        after = page["next_after"]
+      end
+      0
+    end
+
+    # -- helpers ------------------------------------------------------------
+
+    def parse_options
+      options = { file: DEFAULT_FILE, prune: false, yes: false }
+      parser = OptionParser.new do |o|
+        o.on("--prune") { options[:prune] = true }
+        o.on("--yes", "-y") { options[:yes] = true }
+      end
+      rest = parser.parse(@argv)
+      options[:file] = rest.first if rest.first
+      options
+    end
+
+    def read_config(path)
+      unless ::File.file?(path)
+        @err.puts "No config file at #{path}. Run `file_hutch export > #{DEFAULT_FILE}` to start from what you have."
+        return nil
+      end
+      data = YAML.safe_load(::File.read(path), aliases: true) || {}
+      unless data.is_a?(Hash)
+        @err.puts "#{path} must be a YAML mapping (uploads:, transforms:, environments:)."
+        return nil
+      end
+      data
+    end
+
+    def print_changes(changes)
+      changes.each do |c|
+        next if c["action"] == "noop"
+
+        line = "#{MARK.fetch(c['action'], '?')} #{c['resource']} #{c['name']}"
+        line += "  #{describe_diff(c['diff'])}" if c["diff"]
+        @out.puts line
+      end
+      unchanged = changes.count { |c| c["action"] == "noop" }
+      @out.puts "= #{unchanged} unchanged" if unchanged.positive?
+    end
+
+    def describe_diff(diff)
+      diff.map { |key, (from, to)| "#{key}: #{from.inspect} → #{to.inspect}" }.join(", ")
+    end
+
+    def human_size(bytes)
+      return "#{bytes} B" if bytes < 1024
+      units = %w[KB MB GB TB]
+      value = bytes.to_f
+      unit = nil
+      units.each do |u|
+        value /= 1024
+        unit = u
+        break if value < 1024
+      end
+      format(value >= 10 ? "%.0f %s" : "%.1f %s", value, unit)
+    end
+  end
+end

data/lib/file_hutch/client.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # HTTP client for the FileHutch v1 API. Stdlib only.
+  #
+  #   client = FileHutch::Client.new(api_key: "fh_…", url: "https://api.filehutch.com")
+  #   client.upload("report.pdf", policy: "documents")        # 3-step direct upload, returns the ready file
+  #   client.file("file_…").signed_url(expires_in: 600)
+  class Client
+    JSON_TYPE = "application/json"
+    NET_ERRORS = [ Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH,
+                   Errno::EPIPE, SocketError, OpenSSL::SSL::SSLError, Net::OpenTimeout, Net::ReadTimeout, EOFError, IOError ].freeze
+
+    attr_reader :config
+
+    # Accepts a Configuration or keyword overrides on top of the global one.
+    def initialize(config = nil, **overrides)
+      @config = (config || FileHutch.configuration).dup
+      overrides.each { |k, v| @config.public_send(:"#{k}=", v) }
+      @config.validate!
+      @base = URI(@config.url.to_s.sub(%r{/+\z}, ""))
+    end
+
+    # -- Resources ---------------------------------------------------------
+
+    def project
+      Project.new(request(:get, "/api/v1/project").fetch("project"), client: self)
+    end
+
+    def file(id)
+      File.new(request(:get, "/api/v1/files/#{path_id(id)}").fetch("file"), client: self)
+    end
+
+    def transforms
+      request(:get, "/api/v1/transforms").fetch("transforms").map { |t| Transform.new(t, client: self) }
+    end
+
+    # -- Declarative configuration (see `file_hutch plan|apply`) -----------
+
+    # The project as a config hash: {"uploads" => {...}, "transforms" => {...}, "environments" => [...]}.
+    # (`config` is the client's own settings.)
+    def project_config
+      request(:get, "/api/v1/config").fetch("config")
+    end
+
+    # What apply would change. Read-only keys may call this.
+    def plan_config(config, prune: false)
+      request(:post, "/api/v1/config/plan", { config: config, prune: prune }).fetch("plan")
+    end
+
+    def apply_config(config, prune: false)
+      request(:post, "/api/v1/config/apply", { config: config, prune: prune }).fetch("apply")
+    end
+
+    # One page of the export: every ready file with its object key.
+    def manifest(after: nil, limit: nil)
+      query = { after: after, limit: limit }.compact
+      path = "/api/v1/manifest"
+      path += "?#{URI.encode_www_form(query)}" unless query.empty?
+      request(:get, path)
+    end
+
+    # URL for one named transform. `expires_at` is nil for public files, which
+    # are delivered from a stable URL and never expire.
+    def transform_url(id, transform:, expires_in: nil)
+      body = { transform: transform.to_s, expires_in: expires_in }.compact
+      data = request(:post, "/api/v1/files/#{path_id(id)}/transform_url", body)
+      expires_at = data["expires_at"]
+      SignedUrl.new(url: data.fetch("url"), expires_at: expires_at && Time.iso8601(expires_at))
+    end
+
+    def create_upload(policy:, filename:, content_type:, byte_size:, metadata: nil, checksum: nil)
+      body = { policy: policy, filename: filename, content_type: content_type, byte_size: byte_size }
+      body[:checksum] = checksum if checksum
+      body[:metadata] = metadata if metadata && !metadata.empty?
+      data = request(:post, "/api/v1/uploads", body)
+      Upload.new(data.fetch("upload"), file: File.new(data.fetch("file"), client: self), client: self)
+    end
+
+    def complete_upload(id)
+      File.new(request(:post, "/api/v1/uploads/#{path_id(id)}/complete").fetch("file"), client: self)
+    end
+
+    def signed_url(id, expires_in: nil, disposition: nil)
+      body = { expires_in: expires_in, disposition: disposition }.compact
+      data = request(:post, "/api/v1/files/#{path_id(id)}/signed_url", body)
+      SignedUrl.new(url: data.fetch("url"), expires_at: Time.iso8601(data.fetch("expires_at")))
+    end
+
+    def delete_file(id)
+      request(:delete, "/api/v1/files/#{path_id(id)}")
+      true
+    end
+
+    # -- The whole upload flow, server side --------------------------------
+    #
+    # source: a path, Pathname, File, Tempfile, StringIO, ActionDispatch::Http::UploadedFile,
+    #         or a String of bytes (pass filename: then).
+    # Returns the ready FileHutch::File. Bytes go straight to storage.
+    # verify: sends an MD5 of the bytes so FileHutch refuses the upload if what
+    # arrives is not what left. Costs one pass over the file; on by default
+    # because a corrupted upload that completes is worse than a slow one.
+    def upload(source, policy:, filename: nil, content_type: nil, metadata: nil, verify: true)
+      io, name, type, size = Source.open(source, filename: filename, content_type: content_type)
+      upload = create_upload(policy: policy, filename: name, content_type: type, byte_size: size,
+        metadata: metadata, checksum: (Source.md5(io) if verify))
+      put_to_storage(upload, io)
+      complete_upload(upload.id)
+    ensure
+      io&.close if io && Source.owned?(io, source)
+    end
+
+    # PUT bytes to the storage URL in an upload authorization. Never hits an FileHutch endpoint.
+    def put_to_storage(upload, source)
+      # The name is irrelevant to a PUT — the object's key is already fixed by the
+      # authorization — but Source needs one to normalize an in-memory source, and
+      # an upload rebuilt from JSON (a browser flow proxied through your app) does
+      # not carry its file.
+      io, _name, _type, size = Source.open(
+        source, filename: upload.file&.filename || "upload", content_type: upload.headers["Content-Type"]
+      )
+      uri = URI(upload.url)
+      req = Net::HTTP.const_get(upload.method.to_s.capitalize).new(uri)
+      upload.headers.each { |k, v| req[k] = v }
+      req["Content-Length"] = size.to_s
+      req.body_stream = io
+      response = http(uri) { |h| h.request(req) }
+      unless response.is_a?(Net::HTTPSuccess)
+        raise UploadError.new("Storage rejected the upload: HTTP #{response.code} #{response.body.to_s[0, 500]}".strip,
+          code: "storage_rejected", status: response.code.to_i)
+      end
+      true
+    ensure
+      io&.close if io && Source.owned?(io, source)
+    end
+
+    # -- Transport ---------------------------------------------------------
+
+    def request(method, path, body = nil)
+      uri = URI.join("#{@base}/", path.sub(%r{\A/}, ""))
+      req = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+      req["Authorization"] = "Bearer #{config.api_key}"
+      req["Accept"] = JSON_TYPE
+      req["User-Agent"] = config.user_agent
+      if body
+        req["Content-Type"] = JSON_TYPE
+        req.body = JSON.generate(body)
+      end
+      response = http(uri) { |h| h.request(req) }
+      log(method, uri, response)
+      parse(response)
+    end
+
+    private
+
+    def http(uri)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: config.open_timeout,
+                      read_timeout: config.read_timeout, write_timeout: config.write_timeout) { |h| yield h }
+    rescue *NET_ERRORS => e
+      raise ConnectionError.new("#{e.class}: #{e.message} (#{uri.host})", e)
+    end
+
+    def parse(response)
+      status = response.code.to_i
+      return nil if status == 204 || response.body.to_s.empty? && response.is_a?(Net::HTTPSuccess)
+
+      data = begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        nil
+      end
+      return data if response.is_a?(Net::HTTPSuccess)
+
+      raise ApiError.build(status, data)
+    end
+
+    def path_id(id)
+      value = id.respond_to?(:id) ? id.id : id.to_s
+      raise ArgumentError, "expected an FileHutch id, got #{id.inspect}" if value.to_s.empty? || value.to_s.include?("/")
+      URI.encode_www_form_component(value)
+    end
+
+    def log(method, uri, response)
+      config.logger&.debug { "[file_hutch] #{method.to_s.upcase} #{uri.path} -> #{response.code}" }
+    end
+
+    # Normalizes the many things Ruby calls "a file" into [io, filename, content_type, byte_size].
+    module Source
+      TYPES = {
+        ".pdf" => "application/pdf", ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
+        ".gif" => "image/gif", ".webp" => "image/webp", ".avif" => "image/avif", ".svg" => "image/svg+xml",
+        ".heic" => "image/heic", ".txt" => "text/plain", ".csv" => "text/csv", ".json" => "application/json",
+        ".zip" => "application/zip", ".mp4" => "video/mp4", ".mp3" => "audio/mpeg", ".webm" => "video/webm",
+        ".doc" => "application/msword", ".xls" => "application/vnd.ms-excel",
+        ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+      }.freeze
+      FALLBACK = "application/octet-stream"
+
+      CHUNK = 1_048_576 # 1 MiB; this gem is stdlib only, so no 1.megabyte
+
+      module_function
+
+      def open(source, filename: nil, content_type: nil)
+        io = to_io(source, filename)
+        name = filename || guess_filename(source, io)
+        raise ArgumentError, "filename is required for #{source.class} sources" if name.nil? || name.to_s.empty?
+        type = content_type || guess_content_type(source, name)
+        io.rewind if io.respond_to?(:rewind)
+        size = io.respond_to?(:size) ? io.size : io.stat.size
+        [ io, ::File.basename(name.to_s), type, size ]
+      end
+
+      # Streamed rather than read whole: an upload can be far larger than the
+      # memory the process has, and rewinding afterwards leaves the IO exactly
+      # as it was found so the PUT still starts at the beginning.
+      def md5(io)
+        digest = Digest::MD5.new
+        io.rewind if io.respond_to?(:rewind)
+        while (chunk = io.read(CHUNK))
+          digest << chunk
+        end
+        io.rewind if io.respond_to?(:rewind)
+        digest.hexdigest
+      end
+
+      # We close IOs we opened ourselves (paths), never the caller's.
+      def owned?(io, source) = path_like?(source) && io.is_a?(::File)
+
+      def path_like?(source) = source.is_a?(Pathname) || (source.is_a?(String) && source.encoding != Encoding::BINARY && ::File.file?(source))
+
+      def to_io(source, filename)
+        return ::File.open(source.to_s, "rb") if path_like?(source)
+        return source.tempfile if source.respond_to?(:tempfile) && source.tempfile
+        return source if source.respond_to?(:read)
+        return StringIO.new(source.b) if source.is_a?(String) && filename
+        raise ArgumentError, "cannot upload #{source.class}; pass a path, IO, or bytes with filename:"
+      end
+
+      def guess_filename(source, io)
+        return source.original_filename if source.respond_to?(:original_filename)
+        return ::File.basename(source.to_s) if path_like?(source)
+        return ::File.basename(io.path) if io.respond_to?(:path) && io.path
+        nil
+      end
+
+      def guess_content_type(source, name)
+        return source.content_type if source.respond_to?(:content_type) && !source.content_type.to_s.empty?
+        return Marcel::MimeType.for(name: name.to_s) if defined?(Marcel::MimeType)
+        TYPES.fetch(::File.extname(name.to_s).downcase, FALLBACK)
+      end
+    end
+  end
+end

data/lib/file_hutch/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # Global settings. Every value can come from the environment so a deploy
+  # (or an AI agent) can configure the gem without touching Ruby.
+  class Configuration
+    DEFAULT_URL = "https://api.filehutch.com"
+
+    attr_accessor :api_key, :url, :open_timeout, :read_timeout, :write_timeout, :logger, :user_agent
+
+    # Rails direct uploads (see FileHutch::Engine).
+    #   authorize_direct_upload = ->(controller, policy) { controller.current_user.present? }
+    attr_accessor :authorize_direct_upload, :direct_upload_parent_controller
+
+    def initialize
+      @api_key = ENV["FILE_HUTCH_API_KEY"]
+      @url = ENV.fetch("FILE_HUTCH_URL", DEFAULT_URL)
+      @open_timeout = 5
+      @read_timeout = 30
+      @write_timeout = 120
+      @logger = nil
+      @user_agent = "file_hutch-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
+      @authorize_direct_upload = nil
+      @direct_upload_parent_controller = "ApplicationController"
+    end
+
+    def validate!
+      raise ConfigurationError, "FileHutch.config.api_key is missing (set FILE_HUTCH_API_KEY)" if api_key.nil? || api_key.to_s.strip.empty?
+      raise ConfigurationError, "FileHutch.config.url is missing (set FILE_HUTCH_URL)" if url.nil? || url.to_s.strip.empty?
+      self
+    end
+  end
+end

data/lib/file_hutch/errors.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module FileHutch
+  class Error < StandardError; end
+
+  # Client-side problems: missing API key, bad arguments.
+  class ConfigurationError < Error; end
+
+  # A webhook body was not signed by FileHutch with your endpoint's secret.
+  class SignatureVerificationError < Error; end
+
+  # Could not reach FileHutch or storage (DNS, timeout, TLS, reset).
+  class ConnectionError < Error
+    attr_reader :cause_error
+
+    def initialize(message, cause_error = nil)
+      super(message)
+      @cause_error = cause_error
+    end
+  end
+
+  # FileHutch answered with {"error": {"code", "message", "details"}}.
+  class ApiError < Error
+    attr_reader :code, :status, :details
+
+    def initialize(message, code: nil, status: nil, details: nil)
+      super(message)
+      @code = code&.to_s
+      @status = status
+      @details = details
+    end
+
+    CODE_CLASSES = {
+      "unauthorized" => :AuthenticationError,
+      "not_found" => :NotFoundError,
+      "invalid" => :InvalidRequestError,
+      "policy_violation" => :PolicyError,
+      "policy_not_found" => :PolicyError,
+      "storage_not_ready" => :StorageNotReadyError,
+      "invalid_state" => :InvalidStateError,
+      "not_ready" => :InvalidStateError,
+      "already_deleted" => :InvalidStateError,
+      "not_public" => :InvalidStateError,
+      "no_public_base_url" => :InvalidStateError,
+      "upload_expired" => :UploadError,
+      "upload_incomplete" => :UploadError,
+      "size_mismatch" => :UploadError,
+      "transform_not_found" => :TransformError,
+      "not_transformable" => :TransformError,
+      "transforms_unsupported" => :TransformsUnsupportedError,
+      "plan_limit" => :PlanLimitError,
+      "read_only_key" => :PermissionError,
+      "invalid_config" => :ConfigError,
+      "environment_not_found" => :InvalidRequestError,
+      "not_verified" => :InvalidStateError,
+      "storage_error" => :StorageError,
+      "verification_failed" => :StorageError
+    }.freeze
+
+    STATUS_CLASSES = { 401 => :AuthenticationError, 403 => :PermissionError, 404 => :NotFoundError,
+                       402 => :PlanLimitError, 409 => :InvalidStateError, 410 => :InvalidStateError, 422 => :InvalidRequestError,
+                       429 => :RateLimitError, 502 => :StorageError }.freeze
+
+    # Picks the most specific subclass for an error payload.
+    def self.build(status, body)
+      error = body.is_a?(Hash) && body["error"].is_a?(Hash) ? body["error"] : {}
+      code = error["code"]&.to_s
+      message = error["message"] || (status >= 500 ? "FileHutch returned HTTP #{status}" : "Request failed with HTTP #{status}")
+      klass_name = CODE_CLASSES[code] || STATUS_CLASSES[status] || (status >= 500 ? :ServerError : :ApiError)
+      FileHutch.const_get(klass_name).new(message, code: code, status: status, details: error["details"])
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  # The key is valid but may not do this: a read-only key calling a write endpoint.
+  class PermissionError < AuthenticationError; end
+  class NotFoundError < ApiError; end
+  class InvalidRequestError < ApiError; end
+  class PolicyError < InvalidRequestError; end
+  # A declarative config the API refused: unknown key, bad size, bad name.
+  class ConfigError < InvalidRequestError; end
+  class StorageNotReadyError < ApiError; end
+  class InvalidStateError < ApiError; end
+  # A named transform is unknown, or the file is not an image.
+  class TransformError < InvalidRequestError; end
+  # The project's storage cannot render transforms. The message says what to set up.
+  class TransformsUnsupportedError < TransformError; end
+  # The team's plan is out of storage or projects. The message names the plan and what to do.
+  class PlanLimitError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+  class StorageError < ApiError; end
+
+  # The direct PUT to storage failed, or FileHutch could not verify it.
+  class UploadError < ApiError; end
+end

data/lib/file_hutch/file.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # A stored file. `id` ("file_…") is the only thing your app should persist.
+  class File < Resource
+    ID_PATTERN = /\Afile_[0-9A-Za-z]{20}\z/
+    STATUSES = %w[pending ready failed deleted].freeze
+
+    attribute :filename, :content_type, :byte_size, :checksum, :visibility, :status, :metadata,
+              :policy, :storage_connection_id, :url
+    time_attribute :created_at, :updated_at
+
+    def self.id?(value) = value.is_a?(String) && value.match?(ID_PATTERN)
+
+    def self.find(id, client: FileHutch.client) = client.file(id)
+
+    STATUSES.each { |s| define_method(:"#{s}?") { status == s } }
+
+    def public? = visibility == "public"
+    def private? = visibility == "private"
+    def image? = content_type.to_s.start_with?("image/")
+    def pdf? = content_type == "application/pdf"
+    def metadata = self["metadata"] || {}
+
+    # Named transform URLs, keyed by name. Filled for ready public images on
+    # storage that can render them; empty otherwise.
+    def transforms = self["transforms"] || {}
+
+    # URL for one named transform. Free for public images (the URL is already
+    # on the payload); one request for private ones, which get a signed source.
+    def transform_url(name, expires_in: nil)
+      transforms[name.to_s] || client!.transform_url(id, transform: name, expires_in: expires_in).url
+    end
+
+    # Short-lived URL that works for private and public files alike.
+    def signed_url(expires_in: nil, disposition: nil)
+      client!.signed_url(id, expires_in: expires_in, disposition: disposition).url
+    end
+
+    # Public URL when the file is public and ready, otherwise a signed URL.
+    def url_or_signed_url(expires_in: nil, disposition: nil)
+      url || signed_url(expires_in: expires_in, disposition: disposition)
+    end
+
+    def reload = client!.file(id)
+
+    # Deletes the bytes; the id keeps resolving with status "deleted".
+    def delete
+      client!.delete_file(id)
+      reload
+    end
+  end
+
+  SignedUrl = Struct.new(:url, :expires_at, keyword_init: true) do
+    def to_s = url
+  end
+end