onetime 0.6.0 → 0.7.0

data/lib/onetime/configuration.rb

@@ -1,156 +0,0 @@
-# frozen_string_literal: true
-
-require "uri"
-
-module Onetime
-  # Immutable-ish configuration for a Client instance.
-  #
-  # Authentication uses HTTP Basic, where the username slot carries the
-  # *customer external id* (extid) — the identifier that begins with "ur" and
-  # is shown (with a copy button) at the bottom of the user menu when signed
-  # in. The password slot carries your API token.
-  #
-  # #validate! checks the extid's format, so a value of the wrong kind fails
-  # at construction rather than as an opaque 401.
-  #
-  # Values fall back to environment variables:
-  #   ONETIME_BASE_URL        -> base_url
-  #   ONETIME_CUSTOMER_EXTID  -> customer
-  #   ONETIME_API_TOKEN       -> api_token
-  class Configuration
-    DEFAULT_API_VERSION  = :v2
-    SUPPORTED_VERSIONS   = %i[v1 v2].freeze
-    DEFAULT_TIMEOUT      = 30  # read timeout, seconds
-    DEFAULT_OPEN_TIMEOUT = 10  # connect timeout, seconds
-    DEFAULT_MAX_RETRIES  = 2   # retries for idempotent requests
-
-    # A customer extid is a short, opaque, case-insensitive identifier that
-    # always begins with "ur" — e.g. "ur1abc23def".
-    CUSTOMER_EXTID_PATTERN = /\Aur[a-z0-9]+\z/i
-
-    # Included in the rejection message: an invalid-format error is only
-    # actionable if it says where the valid value lives.
-    CUSTOMER_EXTID_HINT =
-      'Your customer extid is the "ur…" identifier at the bottom of the ' \
-      "user menu when you are signed in (there is a copy button next to it). " \
-      "Pass it as customer: or set ONETIME_CUSTOMER_EXTID."
-
-    # The apex domain and its www host serve the company website, not the
-    # API. Regional deployments each have their own host.
-    APEX_HOSTS = %w[onetimesecret.com www.onetimesecret.com].freeze
-
-    # Known regional API hosts (per the API's published server list),
-    # surfaced in error messages. Self-hosted and custom domains are also
-    # valid base URLs.
-    EXAMPLE_REGIONAL_HOSTS = %w[
-      us.onetimesecret.com eu.onetimesecret.com uk.onetimesecret.com
-      ca.onetimesecret.com nz.onetimesecret.com
-    ].freeze
-
-    attr_accessor :base_url, :api_version, :customer, :api_token,
-                  :timeout, :open_timeout, :max_retries,
-                  :user_agent, :logger, :transport, :default_headers
-
-    def initialize(base_url: nil, api_version: nil, customer: nil,
-                   api_token: nil, timeout: nil, open_timeout: nil, max_retries: nil,
-                   user_agent: nil, logger: nil, transport: nil, default_headers: nil)
-      @base_url        = base_url || ENV["ONETIME_BASE_URL"]
-      @api_version     = normalize_version(api_version || DEFAULT_API_VERSION)
-      @customer    = customer || ENV["ONETIME_CUSTOMER_EXTID"]
-      @api_token       = api_token || ENV["ONETIME_API_TOKEN"]
-      @timeout         = timeout || DEFAULT_TIMEOUT
-      @open_timeout    = open_timeout || DEFAULT_OPEN_TIMEOUT
-      @max_retries     = max_retries.nil? ? DEFAULT_MAX_RETRIES : max_retries
-      @user_agent      = user_agent
-      @logger          = logger
-      @transport       = transport
-      @default_headers = default_headers || {}
-    end
-
-    # True when no credentials are configured. Anonymous clients can still
-    # use public and /guest/* endpoints.
-    def anonymous?
-      customer.to_s.empty? && api_token.to_s.empty?
-    end
-
-    # The mount prefix for the configured API version, e.g. "/api/v2".
-    def api_path_prefix
-      "/api/#{api_version}"
-    end
-
-    def validate!
-      validate_api_version!
-      validate_base_url!
-      validate_credentials!
-      self
-    end
-
-    private
-
-    def validate_api_version!
-      return if SUPPORTED_VERSIONS.include?(api_version)
-
-      raise ConfigurationError,
-            "Unsupported api_version #{api_version.inspect}; supported: #{SUPPORTED_VERSIONS.join(', ')}"
-    end
-
-    def validate_base_url!
-      if base_url.to_s.empty?
-        examples = EXAMPLE_REGIONAL_HOSTS.first(3).map { |h| "https://#{h}" }.join(", ")
-        raise ConfigurationError,
-              "base_url is required. Use your region's API host " \
-              "(e.g. #{examples}), your self-hosted domain, or your custom " \
-              "domain. Set it via the base_url: option or the ONETIME_BASE_URL " \
-              "environment variable."
-      end
-
-      begin
-        uri = URI.parse(base_url)
-      rescue URI::InvalidURIError => e
-        raise ConfigurationError, "Invalid base_url #{base_url.inspect}: #{e.message}"
-      end
-
-      unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
-        raise ConfigurationError, "base_url must be an absolute http(s) URL, got #{base_url.inspect}"
-      end
-
-      return unless APEX_HOSTS.include?(uri.host.downcase)
-
-      raise ConfigurationError,
-            "#{uri.host} is the OneTimeSecret company website, not an API host. " \
-            "Use a regional subdomain (e.g. https://#{EXAMPLE_REGIONAL_HOSTS.first}), " \
-            "your self-hosted domain, or your custom domain."
-    end
-
-    def validate_credentials!
-      validate_customer_format! unless customer.to_s.empty?
-
-      # Partial credentials are almost always a mistake; fail loudly.
-      return unless customer.to_s.empty? ^ api_token.to_s.empty?
-
-      missing = customer.to_s.empty? ? "customer" : "api_token"
-      raise ConfigurationError, "Incomplete credentials: #{missing} is missing"
-    end
-
-    # Catch an identifier of the wrong kind at construction time rather than
-    # as a 401 several calls later.
-    def validate_customer_format!
-      value = customer.to_s
-      return if CUSTOMER_EXTID_PATTERN.match?(value)
-
-      raise ConfigurationError,
-            "customer #{value.inspect} is not a customer extid: extids begin " \
-            'with "ur" (e.g. "ur1abc23def"). ' \
-            "#{CUSTOMER_EXTID_HINT}"
-    end
-
-    def normalize_version(version)
-      case version
-      when Symbol then version
-      when String then version.start_with?("v") ? version.to_sym : :"v#{version}"
-      when Integer then :"v#{version}"
-      else version
-      end
-    end
-  end
-end

data/lib/onetime/errors.rb

@@ -1,160 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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

@@ -1,134 +0,0 @@
-# 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

@@ -1,72 +0,0 @@
-# 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