onetime 0.5.0 → 0.6.0

data/lib/onetime/errors.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Onetime
+  # Base class for every error raised by this library.
+  class Error < StandardError; end
+
+  # Raised when the client is misconfigured (bad base_url, missing
+  # credentials for an authenticated call, unsupported api_version, ...).
+  class ConfigurationError < Error; end
+
+  # Raised when an operation is not available on the configured API
+  # version (e.g. asking the v1 API for a secret's status).
+  class UnsupportedOperationError < Error; end
+
+  # Raised for transport-level failures: DNS, connection refused, reset
+  # connections, TLS errors. Wraps the underlying exception in #cause.
+  class TransportError < Error; end
+
+  # Raised when a request exceeds the configured open/read timeout.
+  class TimeoutError < TransportError; end
+
+  # Base class for errors returned by the API (HTTP status >= 400).
+  #
+  # Carries the structured fields from the ADR-013 wire format
+  # ({ error:, error_type:, ... }) as well as the legacy v1 { message: }
+  # shape, so callers get a consistent interface across API versions.
+  class APIError < Error
+    attr_reader :http_status, :error_type, :code, :field, :error_key,
+                :retry_after, :entitlement, :body, :response
+
+    def initialize(message = nil, http_status: nil, error_type: nil, code: nil,
+                   field: nil, error_key: nil, retry_after: nil, entitlement: nil,
+                   body: nil, response: nil)
+      super(message)
+      @http_status = http_status
+      @error_type  = error_type
+      @code        = code
+      @field       = field
+      @error_key   = error_key
+      @retry_after = retry_after
+      @entitlement = entitlement
+      @body        = body
+      @response    = response
+    end
+  end
+
+  class BadRequestError       < APIError; end # 400 / FormError
+  class AuthenticationError   < APIError; end # 401
+  class ForbiddenError        < APIError; end # 403 / Forbidden, GuestRoutesDisabled
+  class EntitlementError      < ForbiddenError; end # EntitlementRequired
+  class NotFoundError         < APIError; end # 404 / RecordNotFound
+  class ConflictError         < APIError; end # 409
+  class RateLimitError        < APIError; end # 429 / LimitExceeded
+  class ServerError           < APIError; end # 5xx / ServerError
+
+  # The operation is only available to an authenticated account. The server
+  # reports this as a field/key rather than a status of its own (historically
+  # a 400 FormError with field "requires_account"), which made it look like a
+  # malformed request body. It is an authentication problem, so it subclasses
+  # AuthenticationError; #field is preserved for callers that need it.
+  class AccountRequiredError < AuthenticationError; end
+
+  # Builds the appropriate APIError subclass from an HTTP response.
+  module Errors
+    module_function
+
+    # Used only when the server sends no message of its own.
+    ACCOUNT_REQUIRED_MESSAGE =
+      "This operation requires an authenticated account: send your " \
+      "customer extid and API token (see Onetime::Client.new)."
+
+    # Maps the ADR-013 error_type (the machine-readable class name the
+    # server sends) to a client exception class. Falls through to status
+    # code mapping when the type is absent or unrecognized.
+    ERROR_TYPE_MAP = {
+      "FormError"           => BadRequestError,
+      "RequiresAccount"     => AccountRequiredError,
+      "AccountRequired"     => AccountRequiredError,
+      "RecordNotFound"      => NotFoundError,
+      "NotFound"            => NotFoundError,
+      "Forbidden"           => ForbiddenError,
+      "GuestRoutesDisabled" => ForbiddenError,
+      "EntitlementRequired" => EntitlementError,
+      "LimitExceeded"       => RateLimitError,
+      "ServerError"         => ServerError,
+    }.freeze
+
+    # The account requirement can arrive in any of several slots depending on
+    # the endpoint and API version: as the FormError `field`, as the i18n
+    # `error_key`, or as a `code`. Matching all of them keeps the mapping
+    # stable across server versions.
+    ACCOUNT_REQUIRED_KEYS    = %w[error_type field error_key code].freeze
+    # Matches the bare token as well as prefixed codes such as
+    # "GUEST_CONCEAL_REQUIRES_ACCOUNT" (underscores are word characters, so
+    # \b is no help here).
+    ACCOUNT_REQUIRED_PATTERN =
+      /(?:\A|[^a-z0-9])(requires[_-]?account|account[_-]?required)(?:\z|[^a-z0-9])/i
+
+    STATUS_MAP = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => BadRequestError,
+      429 => RateLimitError,
+    }.freeze
+
+    # @param response [Onetime::Response]
+    # @return [Onetime::APIError]
+    def from_response(response)
+      body   = response.data.is_a?(Hash) ? response.data : {}
+      status = response.http_status
+
+      account = account_required?(body)
+      klass   = account ? AccountRequiredError : error_class(body["error_type"], status)
+      message = body["error"] || body["message"] ||
+                (account ? ACCOUNT_REQUIRED_MESSAGE : default_message(status))
+
+      klass.new(
+        message,
+        http_status: status,
+        error_type:  body["error_type"],
+        code:        body["code"],
+        field:       body["field"],
+        error_key:   body["error_key"],
+        retry_after: body["retry_after"],
+        entitlement: body["entitlement"],
+        body:        response.data,
+        response:    response,
+      )
+    end
+
+    # True when the body says the operation needs an authenticated account,
+    # in whichever slot this server version reports it.
+    def account_required?(body)
+      ACCOUNT_REQUIRED_KEYS.any? do |key|
+        ACCOUNT_REQUIRED_PATTERN.match?(body[key].to_s)
+      end
+    end
+
+    def error_class(error_type, status)
+      ERROR_TYPE_MAP[error_type] ||
+        STATUS_MAP[status] ||
+        (status.to_i >= 500 ? ServerError : APIError)
+    end
+
+    def default_message(status)
+      case status
+      when 400 then "Bad request"
+      when 401 then "Authentication failed"
+      when 403 then "Forbidden"
+      when 404 then "Not found"
+      when 429 then "Rate limit exceeded"
+      when 500..599 then "Server error (#{status})"
+      else "Request failed (#{status})"
+      end
+    end
+  end
+end

data/lib/onetime/resources/receipts.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Onetime
+  module Resources
+    # Receipt operations (creator-facing secret metadata): show, recent,
+    # burn, update.
+    #
+    # "Receipt" is the modern vocabulary; the v1 API also accepts the legacy
+    # /private and /metadata aliases, but this client uses the canonical
+    # /receipt paths that both versions support.
+    class Receipts
+      def initialize(client)
+        @client = client
+      end
+
+      # Show a receipt by its key.
+      def show(key, guest: false)
+        identifier = key.to_s
+        case version
+        when :v1
+          @client.request(:get, "/receipt/#{identifier}")
+        when :v2
+          path = guest ? "/guest/receipt/#{identifier}" : "/receipt/#{identifier}"
+          @client.request(:get, path)
+        end
+      end
+
+      # List the authenticated customer's recent receipts.
+      def recent
+        @client.request(:get, "/receipt/recent")
+      end
+
+      # Burn (destroy) an unread secret by its receipt key.
+      def burn(key, passphrase: nil, continue: true, guest: false)
+        identifier = key.to_s
+        case version
+        when :v1
+          form = compact(passphrase: passphrase, continue: continue)
+          @client.request(:post, "/receipt/#{identifier}/burn", form: form)
+        when :v2
+          path = guest ? "/guest/receipt/#{identifier}/burn" : "/receipt/#{identifier}/burn"
+          @client.request(:post, path, body: compact(passphrase: passphrase, continue: continue))
+        end
+      end
+
+      # Update a receipt's memo. (v2 only)
+      def update(key, memo:)
+        require_version!(:v2, "receipts.update")
+        @client.request(:patch, "/receipt/#{key}", body: { memo: memo })
+      end
+
+      private
+
+      def version
+        @client.api_version
+      end
+
+      def compact(**attrs)
+        attrs.reject { |_, v| v.nil? }
+      end
+
+      def require_version!(expected, operation)
+        return if version == expected
+
+        raise UnsupportedOperationError,
+              "#{operation} is only available on API #{expected}; client is configured for #{version}"
+      end
+    end
+  end
+end

data/lib/onetime/resources/secrets.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Onetime
+  module Resources
+    # Secret operations: conceal, generate, reveal, show, status.
+    #
+    # The request/response contracts differ between API versions:
+    #   - v1 uses flat form-encoded params and legacy endpoint names
+    #     (/share, /generate, POST /secret/:key for reveal).
+    #   - v2 nests create params under a `secret` object, uses JSON bodies,
+    #     and exposes richer REST endpoints (/secret/conceal, /secret/:id, ...).
+    #
+    # The version-specific branches are kept side by side in each method so
+    # the differences are easy to audit.
+    class Secrets
+      def initialize(client)
+        @client = client
+      end
+
+      # Conceal (share) a secret value you already have.
+      #
+      # @param secret [String] the secret content
+      # @param ttl [Integer, nil] time-to-live in seconds
+      # @param passphrase [String, nil] passphrase required to reveal
+      # @param recipient [String, Array<String>, nil] email recipient(s)
+      # @param share_domain [String, nil] custom share domain
+      # @param guest [Boolean] use the anonymous /guest/* endpoint (v2)
+      def conceal(secret:, ttl: nil, passphrase: nil, recipient: nil, share_domain: nil, guest: false)
+        case version
+        when :v1
+          form = compact(secret: secret, ttl: ttl, passphrase: passphrase,
+                         recipient: recipient, share_domain: share_domain)
+          @client.request(:post, "/share", form: form)
+        when :v2
+          path = guest ? "/guest/secret/conceal" : "/secret/conceal"
+          @client.request(:post, path, body: { secret: secret_payload(
+            secret: secret, ttl: ttl, passphrase: passphrase,
+            recipient: recipient, share_domain: share_domain
+          ) })
+        end
+      end
+      alias share conceal
+
+      # Generate a random secret value server-side.
+      def generate(ttl: nil, passphrase: nil, recipient: nil, share_domain: nil, guest: false)
+        case version
+        when :v1
+          form = compact(ttl: ttl, passphrase: passphrase,
+                         recipient: recipient, share_domain: share_domain)
+          @client.request(:post, "/generate", form: form)
+        when :v2
+          path = guest ? "/guest/secret/generate" : "/secret/generate"
+          @client.request(:post, path, body: { secret: secret_payload(
+            ttl: ttl, passphrase: passphrase,
+            recipient: recipient, share_domain: share_domain
+          ) })
+        end
+      end
+
+      # Reveal (consume) a secret by its key. This is a one-time action.
+      #
+      # @param key [String] the secret identifier
+      # @param passphrase [String, nil] passphrase if one was set
+      # @param continue [Boolean] confirm the destructive reveal
+      def reveal(key, passphrase: nil, continue: true, guest: false)
+        identifier = extract_secret_key(key)
+        case version
+        when :v1
+          form = compact(passphrase: passphrase, continue: continue)
+          @client.request(:post, "/secret/#{identifier}", form: form)
+        when :v2
+          path = guest ? "/guest/secret/#{identifier}/reveal" : "/secret/#{identifier}/reveal"
+          @client.request(:post, path, body: compact(passphrase: passphrase, continue: continue))
+        end
+      end
+
+      # Show a secret's metadata without revealing its value. (v2 only)
+      def show(key, guest: false)
+        require_version!(:v2, "secrets.show")
+        identifier = extract_secret_key(key)
+        path = guest ? "/guest/secret/#{identifier}" : "/secret/#{identifier}"
+        @client.request(:get, path)
+      end
+
+      # Check a single secret's status. (v2 only)
+      def status(key)
+        require_version!(:v2, "secrets.status")
+        @client.request(:get, "/secret/#{extract_secret_key(key)}/status")
+      end
+
+      # Check the status of multiple secrets in one call. (v2 only)
+      #
+      # @param keys [Array<String>, String] identifiers (array or CSV string)
+      def status_list(keys)
+        require_version!(:v2, "secrets.status_list")
+        identifiers = keys.is_a?(Array) ? keys.join(",") : keys.to_s
+        @client.request(:post, "/secret/status", body: { identifiers: identifiers })
+      end
+
+      private
+
+      def version
+        @client.api_version
+      end
+
+      # v2 create endpoints expect params nested under a `secret` object.
+      def secret_payload(**attrs)
+        compact(**attrs)
+      end
+
+      def compact(**attrs)
+        attrs.reject { |_, v| v.nil? }
+      end
+
+      # Accept either a bare key or a full secret URL (e.g. the link a user
+      # was given). Mirrors the convenience of the historical CLI.
+      def extract_secret_key(key)
+        str = key.to_s
+        if (match = str.match(%r{/secret/([a-zA-Z0-9]+)}))
+          match[1]
+        else
+          str
+        end
+      end
+
+      def require_version!(expected, operation)
+        return if version == expected
+
+        raise UnsupportedOperationError,
+              "#{operation} is only available on API #{expected}; client is configured for #{version}"
+      end
+    end
+  end
+end

data/lib/onetime/response.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Onetime
+  # A thin, indifferent-access wrapper around a parsed API response.
+  #
+  # The parsed JSON body is exposed via #[], #dig, #fetch and #to_h, all of
+  # which accept either String or Symbol keys. The raw body string and HTTP
+  # status are also available.
+  #
+  #   res = client.secrets.conceal(secret: "hi")
+  #   res[:record][:receipt]["identifier"]
+  #   res.dig("record", "secret", "secret_value")
+  #   res.success?
+  class Response
+    attr_reader :http_status, :headers, :raw_body, :data
+
+    def initialize(http_status:, headers:, raw_body:, data:)
+      @http_status = http_status
+      @headers     = headers || {}
+      @raw_body    = raw_body
+      @data        = data
+    end
+
+    # Indifferent key access. Returns nil for non-Hash bodies.
+    def [](key)
+      return nil unless data.is_a?(Hash)
+
+      data[normalize(key)]
+    end
+
+    # Indifferent, deep access mirroring Hash#dig.
+    def dig(*keys)
+      keys.reduce(data) do |memo, key|
+        case memo
+        when Hash  then memo[normalize(key)]
+        when Array then memo[key]
+        end
+      end
+    end
+
+    def fetch(key, *default, &block)
+      raise TypeError, "response body is not a Hash" unless data.is_a?(Hash)
+
+      data.fetch(normalize(key), *default, &block)
+    end
+
+    def key?(key)
+      data.is_a?(Hash) && data.key?(normalize(key))
+    end
+
+    # 2xx status.
+    def success?
+      (200..299).cover?(http_status.to_i)
+    end
+
+    # Alias used by the legacy Onetime::API compatibility shim.
+    def code
+      http_status
+    end
+
+    def to_h
+      data
+    end
+
+    private
+
+    # Bodies are parsed with string keys; coerce symbol lookups to strings.
+    def normalize(key)
+      key.is_a?(Symbol) ? key.to_s : key
+    end
+  end
+end

data/lib/onetime/transport.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "version"
+require_relative "response"
+require_relative "errors"
+
+module Onetime
+  # Zero-dependency HTTP transport built on stdlib Net::HTTP.
+  #
+  # Responsibilities:
+  #   - build the request URL, headers and body (form for v1, JSON for v2)
+  #   - apply HTTP Basic auth when credentials are configured
+  #   - retry idempotent requests with exponential backoff
+  #   - parse the JSON response and map error statuses to exceptions
+  #
+  # It intentionally has no knowledge of API versions or resources; callers
+  # pass fully-qualified paths (e.g. "/api/v2/secret/conceal").
+  class Transport
+    IDEMPOTENT_METHODS = %i[get head].freeze
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    RETRYABLE_ERRORS   = [
+      Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT, EOFError, SocketError, IOError,
+      Net::OpenTimeout, Net::ReadTimeout
+    ].freeze
+
+    METHOD_CLASSES = {
+      get:    Net::HTTP::Get,
+      post:   Net::HTTP::Post,
+      patch:  Net::HTTP::Patch,
+      put:    Net::HTTP::Put,
+      delete: Net::HTTP::Delete,
+      head:   Net::HTTP::Head,
+    }.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Execute an HTTP request.
+    #
+    # @param method [Symbol] :get, :post, :patch, ...
+    # @param path [String] fully-qualified path including the /api/vN prefix
+    # @param query [Hash, nil] query-string parameters
+    # @param body [Hash, nil] request body serialized as JSON
+    # @param form [Hash, nil] request body serialized as form-urlencoded
+    # @param headers [Hash] extra request headers
+    # @param raise_on_error [Boolean] raise APIError for status >= 400
+    # @return [Onetime::Response]
+    def request(method, path, query: nil, body: nil, form: nil, headers: {}, raise_on_error: true)
+      uri = build_uri(path, query)
+      attempt = 0
+
+      begin
+        response = perform(method, uri, body: body, form: form, headers: headers)
+
+        if response.http_status >= 400
+          if retryable_status?(response.http_status) && retry_allowed?(method, attempt)
+            attempt += 1
+            backoff(attempt)
+            raise Retry
+          end
+          raise Errors.from_response(response) if raise_on_error
+        end
+
+        response
+      rescue Retry
+        retry
+      rescue *RETRYABLE_ERRORS => e
+        if retry_allowed?(method, attempt)
+          attempt += 1
+          backoff(attempt)
+          retry
+        end
+        raise wrap_transport_error(e)
+      end
+    end
+
+    # Encodes a Hash as application/x-www-form-urlencoded, expanding Array
+    # values into repeated `key[]=` pairs (Rack's array convention, which
+    # the v1 API relies on for `recipient`).
+    def self.encode_form(hash)
+      pairs = []
+      hash.each do |key, value|
+        next if value.nil?
+
+        if value.is_a?(Array)
+          value.each { |v| pairs << ["#{key}[]", v.to_s] }
+        else
+          pairs << [key.to_s, value.to_s]
+        end
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    private
+
+    # Sentinel used to trigger a retry from within the begin/rescue.
+    Retry = Class.new(StandardError)
+    private_constant :Retry
+
+    def perform(method, uri, body:, form:, headers:)
+      request = build_request(method, uri, body: body, form: form, headers: headers)
+      log(:debug) { "#{method.to_s.upcase} #{uri}" }
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+
+      raw = http.request(request)
+      build_response(raw)
+    end
+
+    def build_request(method, uri, body:, form:, headers:)
+      klass = METHOD_CLASSES.fetch(method) do
+        raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+      end
+      request = klass.new(uri)
+
+      default_headers.merge(headers).each { |k, v| request[k] = v }
+
+      unless @config.anonymous?
+        # HTTP Basic: the customer extid occupies the username slot,
+        # the API token occupies the password slot.
+        request.basic_auth(@config.customer, @config.api_token)
+      end
+
+      if form
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+        request.body = self.class.encode_form(form)
+      elsif body
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def build_response(raw)
+      status = raw.code.to_i
+      raw_body = raw.body.to_s
+      data = parse_body(raw, raw_body)
+
+      Response.new(
+        http_status: status,
+        headers: raw.to_hash,
+        raw_body: raw_body,
+        data: data,
+      )
+    end
+
+    def parse_body(raw, raw_body)
+      return nil if raw_body.empty?
+
+      content_type = raw["content-type"].to_s
+      return raw_body unless content_type.include?("json")
+
+      JSON.parse(raw_body)
+    rescue JSON::ParserError
+      # A non-JSON body on an otherwise-JSON endpoint: surface it raw rather
+      # than blowing up, so callers can still inspect it.
+      raw_body
+    end
+
+    def build_uri(path, query)
+      uri = URI.join(ensure_trailing_slash(@config.base_url), path.sub(%r{\A/}, ""))
+      if query && !query.empty?
+        uri.query = self.class.encode_form(query)
+      end
+      uri
+    end
+
+    # URI.join treats the base as a directory only when it ends in "/".
+    def ensure_trailing_slash(url)
+      url.end_with?("/") ? url : "#{url}/"
+    end
+
+    def default_headers
+      {
+        "Accept"           => "application/json",
+        "User-Agent"       => @config.user_agent || default_user_agent,
+        "X-Onetime-Client" => "ruby:#{RUBY_VERSION}/#{Onetime::VERSION}",
+      }.merge(@config.default_headers)
+    end
+
+    # Identifies the SDK, not the gem: "onetime-ruby" tells the service which
+    # of the per-language clients is calling. The gem itself is `onetime`.
+    def default_user_agent
+      "onetime-ruby/#{Onetime::VERSION} (Ruby/#{RUBY_VERSION})"
+    end
+
+    def retry_allowed?(method, attempt)
+      IDEMPOTENT_METHODS.include?(method) && attempt < @config.max_retries
+    end
+
+    def retryable_status?(status)
+      RETRYABLE_STATUSES.include?(status)
+    end
+
+    # Exponential backoff: 0.5s, 1s, 2s, ...
+    def backoff(attempt)
+      sleep(0.5 * (2**(attempt - 1)))
+    end
+
+    def wrap_transport_error(error)
+      if error.is_a?(Net::OpenTimeout) || error.is_a?(Net::ReadTimeout)
+        TimeoutError.new("Request timed out: #{error.message}")
+      else
+        TransportError.new("Transport failure: #{error.message}")
+      end
+    end
+
+    def log(level)
+      return unless @config.logger
+
+      @config.logger.public_send(level, "[onetime] #{yield}")
+    end
+  end
+end

data/lib/onetime/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Onetime
+  # Library version. Source of truth for the gemspec, the release workflow's
+  # tag check, and the X-Onetime-Client / User-Agent request headers.
+  #
+  # Note for anyone comparing against RubyGems: 0.5.1 (2013) and earlier are
+  # the command-line tool that shipped under this gem name. 0.6.0 is the
+  # cleaned-up client library.
+  VERSION = "0.6.0"
+end