moderation_api 2.41.0 → 3.0.0

data/README.md

@@ -1,237 +0,0 @@
-# Moderation API Ruby library
-
-The Moderation API Ruby library provides convenient access to the Moderation API REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/moderation-api/sdk-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
-
-## Documentation
-
-Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/moderation_api).
-
-The REST API documentation can be found on [docs.moderationapi.com](https://docs.moderationapi.com).
-
-## Installation
-
-To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
-
-<!-- x-release-please-start-version -->
-
-```ruby
-gem "moderation_api", "~> 2.41.0"
-```
-
-<!-- x-release-please-end -->
-
-## Usage
-
-```ruby
-require "bundler/setup"
-require "moderation_api"
-
-moderation_api = ModerationAPI::Client.new(
-  secret_key: ENV["MODAPI_SECRET_KEY"] # This is the default and can be omitted
-)
-
-response = moderation_api.content.submit(content: {text: "text", type: "text"})
-
-puts(response.recommendation)
-```
-
-### Handling errors
-
-When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `ModerationAPI::Errors::APIError` will be thrown:
-
-```ruby
-begin
-  content = moderation_api.content.submit(content: {text: "text", type: "text"})
-rescue ModerationAPI::Errors::APIConnectionError => e
-  puts("The server could not be reached")
-  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
-rescue ModerationAPI::Errors::RateLimitError => e
-  puts("A 429 status code was received; we should back off a bit.")
-rescue ModerationAPI::Errors::APIStatusError => e
-  puts("Another non-200-range status code was received")
-  puts(e.status)
-end
-```
-
-Error codes are as follows:
-
-| Cause            | Error Type                 |
-| ---------------- | -------------------------- |
-| HTTP 400         | `BadRequestError`          |
-| HTTP 401         | `AuthenticationError`      |
-| HTTP 403         | `PermissionDeniedError`    |
-| HTTP 404         | `NotFoundError`            |
-| HTTP 409         | `ConflictError`            |
-| HTTP 422         | `UnprocessableEntityError` |
-| HTTP 429         | `RateLimitError`           |
-| HTTP >= 500      | `InternalServerError`      |
-| Other HTTP error | `APIStatusError`           |
-| Timeout          | `APITimeoutError`          |
-| Network error    | `APIConnectionError`       |
-
-### Retries
-
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
-
-You can use the `max_retries` option to configure or disable this:
-
-```ruby
-# Configure the default for all requests:
-moderation_api = ModerationAPI::Client.new(
-  max_retries: 0 # default is 2
-)
-
-# Or, configure per-request:
-moderation_api.content.submit(content: {text: "text", type: "text"}, request_options: {max_retries: 5})
-```
-
-### Timeouts
-
-By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
-
-```ruby
-# Configure the default for all requests:
-moderation_api = ModerationAPI::Client.new(
-  timeout: nil # default is 60
-)
-
-# Or, configure per-request:
-moderation_api.content.submit(content: {text: "text", type: "text"}, request_options: {timeout: 5})
-```
-
-On timeout, `ModerationAPI::Errors::APITimeoutError` is raised.
-
-Note that requests that time out are retried by default.
-
-## Advanced concepts
-
-### BaseModel
-
-All parameter and response objects inherit from `ModerationAPI::Internal::Type::BaseModel`, which provides several conveniences, including:
-
-1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
-
-2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
-
-3. Both instances and the classes themselves can be pretty-printed.
-
-4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
-
-### Making custom or undocumented requests
-
-#### Undocumented properties
-
-You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
-
-Note: the `extra_` parameters of the same name overrides the documented parameters.
-
-```ruby
-response =
-  moderation_api.content.submit(
-    content: {text: "text", type: "text"},
-    request_options: {
-      extra_query: {my_query_parameter: value},
-      extra_body: {my_body_parameter: value},
-      extra_headers: {"my-header": value}
-    }
-  )
-
-puts(response[:my_undocumented_property])
-```
-
-#### Undocumented request params
-
-If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
-
-#### Undocumented endpoints
-
-To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
-
-```ruby
-response = client.request(
-  method: :post,
-  path: '/undocumented/endpoint',
-  query: {"dog": "woof"},
-  headers: {"useful-header": "interesting-value"},
-  body: {"hello": "world"}
-)
-```
-
-### Concurrency & connection pooling
-
-The `ModerationAPI::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
-
-Each instance of `ModerationAPI::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
-
-When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
-
-Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
-
-## Sorbet
-
-This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
-
-You can provide typesafe request parameters like so:
-
-```ruby
-moderation_api.content.submit(
-  content: ModerationAPI::ContentSubmitParams::Content::Text.new(text: "text")
-)
-```
-
-Or, equivalently:
-
-```ruby
-# Hashes work, but are not typesafe:
-moderation_api.content.submit(content: {text: "text", type: "text"})
-
-# You can also splat a full Params class:
-params = ModerationAPI::ContentSubmitParams.new(
-  content: ModerationAPI::ContentSubmitParams::Content::Text.new(text: "text")
-)
-moderation_api.content.submit(**params)
-```
-
-### Enums
-
-Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
-
-```ruby
-# :trustLevel
-puts(ModerationAPI::AuthorListParams::SortBy::TRUST_LEVEL)
-
-# Revealed type: `T.all(ModerationAPI::AuthorListParams::SortBy, Symbol)`
-T.reveal_type(ModerationAPI::AuthorListParams::SortBy::TRUST_LEVEL)
-```
-
-Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
-
-```ruby
-# Using the enum constants preserves the tagged type information:
-moderation_api.authors.list(
-  sort_by: ModerationAPI::AuthorListParams::SortBy::TRUST_LEVEL,
-  # …
-)
-
-# Literal values are also permissible:
-moderation_api.authors.list(
-  sort_by: :trustLevel,
-  # …
-)
-```
-
-## Versioning
-
-This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
-
-This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
-
-## Requirements
-
-Ruby 3.2.0 or higher.
-
-## Contributing
-
-See [the contributing documentation](https://github.com/moderation-api/sdk-ruby/tree/main/CONTRIBUTING.md).

data/SECURITY.md

@@ -1,27 +0,0 @@
-# Security Policy
-
-## Reporting Security Issues
-
-This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
-
-To report a security issue, please contact the Stainless team at security@stainless.com.
-
-## Responsible Disclosure
-
-We appreciate the efforts of security researchers and individuals who help us maintain the security of
-SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
-disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
-before making any information public.
-
-## Reporting Non-SDK Related Security Issues
-
-If you encounter security issues that are not directly related to SDKs but pertain to the services
-or products provided by Moderation API, please follow the respective company's security reporting guidelines.
-
-### Moderation API Terms and Policies
-
-Please contact support@moderationapi.com for any questions or concerns regarding the security of our services.
-
----
-
-Thank you for helping us keep the SDKs and systems they interact with secure.

data/lib/moderation_api/client.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-module ModerationAPI
-  class Client < ModerationAPI::Internal::Transport::BaseClient
-    # Default max number of retries to attempt after a failed retryable request.
-    DEFAULT_MAX_RETRIES = 2
-
-    # Default per-request timeout.
-    DEFAULT_TIMEOUT_IN_SECONDS = 60.0
-
-    # Default initial retry delay in seconds.
-    # Overall delay is calculated using exponential backoff + jitter.
-    DEFAULT_INITIAL_RETRY_DELAY = 0.5
-
-    # Default max retry delay in seconds.
-    DEFAULT_MAX_RETRY_DELAY = 8.0
-
-    # @return [String]
-    attr_reader :secret_key
-
-    # @return [ModerationAPI::Resources::Authors]
-    attr_reader :authors
-
-    # @return [ModerationAPI::Resources::Queue]
-    attr_reader :queue
-
-    # @return [ModerationAPI::Resources::Actions]
-    attr_reader :actions
-
-    # @return [ModerationAPI::Resources::Content]
-    attr_reader :content
-
-    # @return [ModerationAPI::Resources::Account]
-    attr_reader :account
-
-    # @return [ModerationAPI::Resources::Auth]
-    attr_reader :auth
-
-    # @return [ModerationAPI::Resources::Wordlist]
-    attr_reader :wordlist
-
-    # @return [ModerationAPI::Resources::Webhooks]
-    attr_reader :webhooks
-
-    # @return [ModerationAPI::Resources::WebhookSecret]
-    attr_reader :webhook_secret
-
-    # @api private
-    #
-    # @return [Hash{String=>String}]
-    private def auth_headers
-      return {} if @secret_key.nil?
-
-      {"authorization" => "Bearer #{@secret_key}"}
-    end
-
-    # @api private
-    #
-    # @return [Boolean]
-    def base_url_overridden? = @base_url_overridden
-
-    # Creates and returns a new client for interacting with the API.
-    #
-    # @param secret_key [String, nil] Defaults to `ENV["MODAPI_SECRET_KEY"]`
-    #
-    # @param base_url [String, nil] Override the default base URL for the API, e.g.,
-    # `"https://api.example.com/v2/"`. Defaults to `ENV["MODERATION_API_BASE_URL"]`
-    #
-    # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
-    #
-    # @param timeout [Float]
-    #
-    # @param initial_retry_delay [Float]
-    #
-    # @param max_retry_delay [Float]
-    def initialize(
-      secret_key: ENV["MODAPI_SECRET_KEY"],
-      base_url: ENV["MODERATION_API_BASE_URL"],
-      max_retries: self.class::DEFAULT_MAX_RETRIES,
-      timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
-    )
-      @base_url_overridden = !base_url.nil?
-
-      base_url ||= "https://api.moderationapi.com/v1"
-
-      if secret_key.nil?
-        raise ArgumentError.new("secret_key is required, and can be set via environ: \"MODAPI_SECRET_KEY\"")
-      end
-
-      headers = {}
-      custom_headers_env = ENV["MODERATION_API_CUSTOM_HEADERS"]
-      unless custom_headers_env.nil?
-        parsed = {}
-        custom_headers_env.split("\n").each do |line|
-          colon = line.index(":")
-          unless colon.nil?
-            parsed[line[0...colon].strip] = line[(colon + 1)..].strip
-          end
-        end
-        headers = parsed.merge(headers)
-      end
-
-      @secret_key = secret_key.to_s
-
-      super(
-        base_url: base_url,
-        timeout: timeout,
-        max_retries: max_retries,
-        initial_retry_delay: initial_retry_delay,
-        max_retry_delay: max_retry_delay,
-        headers: headers
-      )
-
-      @authors = ModerationAPI::Resources::Authors.new(client: self)
-      @queue = ModerationAPI::Resources::Queue.new(client: self)
-      @actions = ModerationAPI::Resources::Actions.new(client: self)
-      @content = ModerationAPI::Resources::Content.new(client: self)
-      @account = ModerationAPI::Resources::Account.new(client: self)
-      @auth = ModerationAPI::Resources::Auth.new(client: self)
-      @wordlist = ModerationAPI::Resources::Wordlist.new(client: self)
-      @webhooks = ModerationAPI::Resources::Webhooks.new(client: self)
-      @webhook_secret = ModerationAPI::Resources::WebhookSecret.new(client: self)
-    end
-  end
-end

data/lib/moderation_api/errors.rb

@@ -1,228 +0,0 @@
-# frozen_string_literal: true
-
-module ModerationAPI
-  module Errors
-    class Error < StandardError
-      # @!attribute cause
-      #
-      #   @return [StandardError, nil]
-    end
-
-    class ConversionError < ModerationAPI::Errors::Error
-      # @return [StandardError, nil]
-      def cause = @cause.nil? ? super : @cause
-
-      # @api private
-      #
-      # @param on [Class<StandardError>]
-      # @param method [Symbol]
-      # @param target [Object]
-      # @param value [Object]
-      # @param cause [StandardError, nil]
-      def initialize(on:, method:, target:, value:, cause: nil)
-        cls = on.name.split("::").last
-
-        message = [
-          "Failed to parse #{cls}.#{method} from #{value.class} to #{target.inspect}.",
-          "To get the unparsed API response, use #{cls}[#{method.inspect}].",
-          cause && "Cause: #{cause.message}"
-        ].filter(&:itself).join(" ")
-
-        @cause = cause
-        super(message)
-      end
-    end
-
-    class APIError < ModerationAPI::Errors::Error
-      # @return [URI::Generic]
-      attr_accessor :url
-
-      # @return [Integer, nil]
-      attr_accessor :status
-
-      # @return [Hash{String=>String}, nil]
-      attr_accessor :headers
-
-      # @return [Object, nil]
-      attr_accessor :body
-
-      # @api private
-      #
-      # @param url [URI::Generic]
-      # @param status [Integer, nil]
-      # @param headers [Hash{String=>String}, nil]
-      # @param body [Object, nil]
-      # @param request [nil]
-      # @param response [nil]
-      # @param message [String, nil]
-      def initialize(url:, status: nil, headers: nil, body: nil, request: nil, response: nil, message: nil)
-        @url = url
-        @status = status
-        @headers = headers
-        @body = body
-        @request = request
-        @response = response
-        super(message)
-      end
-    end
-
-    class APIConnectionError < ModerationAPI::Errors::APIError
-      # @!attribute status
-      #
-      #   @return [nil]
-
-      # @!attribute body
-      #
-      #   @return [nil]
-
-      # @api private
-      #
-      # @param url [URI::Generic]
-      # @param status [nil]
-      # @param headers [Hash{String=>String}, nil]
-      # @param body [nil]
-      # @param request [nil]
-      # @param response [nil]
-      # @param message [String, nil]
-      def initialize(
-        url:,
-        status: nil,
-        headers: nil,
-        body: nil,
-        request: nil,
-        response: nil,
-        message: "Connection error."
-      )
-        super
-      end
-    end
-
-    class APITimeoutError < ModerationAPI::Errors::APIConnectionError
-      # @api private
-      #
-      # @param url [URI::Generic]
-      # @param status [nil]
-      # @param headers [Hash{String=>String}, nil]
-      # @param body [nil]
-      # @param request [nil]
-      # @param response [nil]
-      # @param message [String, nil]
-      def initialize(
-        url:,
-        status: nil,
-        headers: nil,
-        body: nil,
-        request: nil,
-        response: nil,
-        message: "Request timed out."
-      )
-        super
-      end
-    end
-
-    class APIStatusError < ModerationAPI::Errors::APIError
-      # @api private
-      #
-      # @param url [URI::Generic]
-      # @param status [Integer]
-      # @param headers [Hash{String=>String}, nil]
-      # @param body [Object, nil]
-      # @param request [nil]
-      # @param response [nil]
-      # @param message [String, nil]
-      #
-      # @return [self]
-      def self.for(url:, status:, headers:, body:, request:, response:, message: nil)
-        kwargs =
-          {
-            url: url,
-            status: status,
-            headers: headers,
-            body: body,
-            request: request,
-            response: response,
-            message: message
-          }
-
-        case status
-        in 400
-          ModerationAPI::Errors::BadRequestError.new(**kwargs)
-        in 401
-          ModerationAPI::Errors::AuthenticationError.new(**kwargs)
-        in 403
-          ModerationAPI::Errors::PermissionDeniedError.new(**kwargs)
-        in 404
-          ModerationAPI::Errors::NotFoundError.new(**kwargs)
-        in 409
-          ModerationAPI::Errors::ConflictError.new(**kwargs)
-        in 422
-          ModerationAPI::Errors::UnprocessableEntityError.new(**kwargs)
-        in 429
-          ModerationAPI::Errors::RateLimitError.new(**kwargs)
-        in (500..)
-          ModerationAPI::Errors::InternalServerError.new(**kwargs)
-        else
-          ModerationAPI::Errors::APIStatusError.new(**kwargs)
-        end
-      end
-
-      # @!parse
-      #   # @return [Integer]
-      #   attr_accessor :status
-
-      # @api private
-      #
-      # @param url [URI::Generic]
-      # @param status [Integer]
-      # @param headers [Hash{String=>String}, nil]
-      # @param body [Object, nil]
-      # @param request [nil]
-      # @param response [nil]
-      # @param message [String, nil]
-      def initialize(url:, status:, headers:, body:, request:, response:, message: nil)
-        message ||= {url: url.to_s, status: status, body: body}
-        super(
-          url: url,
-          status: status,
-          headers: headers,
-          body: body,
-          request: request,
-          response: response,
-          message: message&.to_s
-        )
-      end
-    end
-
-    class BadRequestError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 400
-    end
-
-    class AuthenticationError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 401
-    end
-
-    class PermissionDeniedError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 403
-    end
-
-    class NotFoundError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 404
-    end
-
-    class ConflictError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 409
-    end
-
-    class UnprocessableEntityError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 422
-    end
-
-    class RateLimitError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = 429
-    end
-
-    class InternalServerError < ModerationAPI::Errors::APIStatusError
-      HTTP_STATUS = (500..)
-    end
-  end
-end

data/lib/moderation_api/file_part.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module ModerationAPI
-  class FilePart
-    # @return [Pathname, StringIO, IO, String]
-    attr_reader :content
-
-    # @return [String, nil]
-    attr_reader :content_type
-
-    # @return [String, nil]
-    attr_reader :filename
-
-    # @api private
-    #
-    # @return [String]
-    private def read
-      case content
-      in Pathname
-        content.read(binmode: true)
-      in StringIO
-        content.string
-      in IO
-        content.read
-      in String
-        content
-      end
-    end
-
-    # @param a [Object]
-    #
-    # @return [String]
-    def to_json(*a) = read.to_json(*a)
-
-    # @param a [Object]
-    #
-    # @return [String]
-    def to_yaml(*a) = read.to_yaml(*a)
-
-    # @param content [Pathname, StringIO, IO, String]
-    # @param filename [Pathname, String, nil]
-    # @param content_type [String, nil]
-    def initialize(content, filename: nil, content_type: nil)
-      @content_type = content_type
-      @filename =
-        case [filename, (@content = content)]
-        in [String | Pathname, _]
-          ::File.basename(filename)
-        in [nil, Pathname]
-          content.basename.to_path
-        in [nil, IO]
-          content.to_path
-        else
-          filename
-        end
-    end
-  end
-end