insion 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58f1b1643f098dbdd6b3ddfeccabc56390e1b68d4be312f14b2ae527c1d49c6e
+  data.tar.gz: 3458f14402789bb47e7cf75b61768c2da8d44cb35800572ca61b16513e4a47a1
+SHA512:
+  metadata.gz: 3f10319da44058b286b19c46e0bcbda2e48a50ea524182f44de0f474b3996266b4d36a864be8bb737b329f2fc4f4aa5281709e7dda8d05b4b13a6e34fa136681
+  data.tar.gz: eddecbc7b2858ee70c63ec6d81745d1f80e287a4c99dd5f8b0921cb8d1eeae6ddc355bb81ee177aaf97dff73ed682a430b3b4b1b91b2faba4d40382fe45d1ed2

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Insion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# Insion Ruby Library
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Insion%2FRuby)
+
+The Insion Ruby library provides convenient access to the Insion APIs from Ruby.
+
+## Table of Contents
+
+- [Reference](#reference)
+- [Usage](#usage)
+- [Environments](#environments)
+- [Errors](#errors)
+- [Advanced](#advanced)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+  - [Additional Headers](#additional-headers)
+  - [Additional Query Parameters](#additional-query-parameters)
+- [Contributing](#contributing)
+
+## Reference
+
+A full reference for this library is available [here](./reference.md).
+
+## Usage
+
+Instantiate and use the client with the following:
+
+```ruby
+require "insion"
+
+client = Insion::Client.new(token: "<token>")
+
+client.moderate_a_record(
+  client_id: "clientId",
+  name: "name",
+  entity: "entity",
+  content: "content"
+)
+```
+
+## Environments
+
+This SDK allows you to configure different environments or custom URLs for API requests. You can either use the predefined environments or specify your own custom URL.
+### Environments
+```ruby
+require "Insion"
+
+Insion = Insion::Client.new(
+    base_url: Insion::Environment::DEFAULT
+)
+```
+
+### Custom URL
+```ruby
+require "Insion"
+
+client = Insion::Client.new(
+    base_url: "https://example.com"
+)
+```
+
+## Errors
+
+Failed API calls will raise errors that can be rescued from granularly.
+
+```ruby
+require "Insion"
+
+client = Insion::Client.new(
+    base_url: "https://example.com"
+)
+
+begin
+    result = client.moderate_a_record
+rescue Insion::Errors::TimeoutError
+    puts "API didn't respond before our timeout elapsed"
+rescue Insion::Errors::ServiceUnavailableError
+    puts "API returned status 503, is probably overloaded, try again later"
+rescue Insion::Errors::ServerError
+    puts "API returned some other 5xx status, this is probably a bug"
+rescue Insion::Errors::ResponseError => e
+    puts "API returned an unexpected status other than 5xx: #{e.code} #{e.message}"
+rescue Insion::Errors::ApiError => e
+    puts "Some other error occurred when calling the API: #{e.message}"
+end
+```
+
+## Advanced
+
+### Retries
+
+The SDK is instrumented with automatic retries. A request will be retried as long as the request is deemed
+retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (Internal Server Error)
+
+The `retryStatusCodes` configuration controls which [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) status codes are retried:
+
+- `legacy` (default): Retries `408`, `429`, `500`, `502`, `503`, `504`, `521`, `522`, `524`
+- `recommended`: Retries `408`, `429`, `502`, `503`, `504` only (excludes `500 Internal Server Error` to avoid retrying non-idempotent failures)
+
+Use the `max_retries` option to configure this behavior.
+
+```ruby
+require "Insion"
+
+client = Insion::Client.new(
+    base_url: "https://example.com",
+    max_retries: 3  # Configure max retries (default is 2)
+)
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. Use the `timeout` option to configure this behavior.
+
+```ruby
+require "Insion"
+
+response = client.moderate_a_record(
+    ...,
+    timeout: 30  # 30 second timeout
+)
+```
+
+### Additional Headers
+
+If you would like to send additional headers as part of the request, use the `additional_headers` request option.
+
+```ruby
+require "Insion"
+
+response = client.moderate_a_record(
+    ...,
+    request_options: {
+        additional_headers: {
+            "X-Custom-Header" => "custom-value"
+        }
+    }
+)
+```
+
+### Additional Query Parameters
+
+If you would like to send additional query parameters as part of the request, use the `additional_query_parameters` request option.
+
+```ruby
+require "Insion"
+
+response = client.moderate_a_record(
+    ...,
+    request_options: {
+        additional_query_parameters: {
+            "custom_param" => "custom-value"
+        }
+    }
+)
+```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

data/changelog.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## [1.0.1] - 2026-07-31
+

data/lib/Insion/client.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+module Insion
+  class Client
+    # Create or update a record and return its moderation result immediately.
+    #
+    # @param request_options [Hash]
+    # @param params [Insion::Types::ModerateRequest]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    #
+    # @example
+    #   client.moderate_a_record(
+    #     client_id: "clientId",
+    #     name: "name",
+    #     entity: "entity",
+    #     content: "content"
+    #   )
+    #
+    # @return [Insion::Types::ModerateResponse]
+    def moderate_a_record(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "POST",
+        path: "api/v1/moderate",
+        body: Insion::Types::ModerateRequest.new(params).to_h,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::ModerateResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # Create or update a content record for asynchronous moderation. Results are delivered through webhook events when
+    # moderation is performed.
+    #
+    # @param request_options [Hash]
+    # @param params [Insion::Types::IngestRecordRequest]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    #
+    # @example
+    #   client.ingest_a_record(
+    #     client_id: "clientId",
+    #     name: "name",
+    #     entity: "entity",
+    #     content: "content"
+    #   )
+    #
+    # @return [Insion::Types::IngestRecordResponse]
+    def ingest_a_record(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "POST",
+        path: "api/v1/ingest",
+        body: Insion::Types::RecordInput.new(params).to_h,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::IngestRecordResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # Remove a record from the moderation system by its client ID.
+    #
+    # @param request_options [Hash]
+    # @param params [Insion::Types::DeleteAPIV1IngestRequest]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    #
+    # @example
+    #   client.delete_a_record(client_id: "clientId")
+    #
+    # @return [Insion::Types::SuccessResponse]
+    def delete_a_record(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "DELETE",
+        path: "api/v1/ingest",
+        body: Insion::Types::DeleteAPIV1IngestRequest.new(params).to_h,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::SuccessResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # Create or update a user without ingesting a record.
+    #
+    # @param request_options [Hash]
+    # @param params [Insion::Types::UserInput]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    #
+    # @example
+    #   client.ingest_a_user(client_id: "clientId")
+    #
+    # @return [Insion::Types::IngestUserResponse]
+    def ingest_a_user(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "POST",
+        path: "api/v1/ingest/user",
+        body: Insion::Types::UserInput.new(params).to_h,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::IngestUserResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # List the records belonging to the authenticated organization.
+    #
+    # @param request_options [Hash]
+    # @param params [Hash]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    # @option params [Integer, nil] :limit
+    # @option params [String, nil] :starting_after
+    # @option params [String, nil] :ending_before
+    # @option params [String, nil] :client_id
+    # @option params [String, nil] :user
+    # @option params [String, nil] :entity
+    # @option params [Insion::Types::GetAPIV1RecordsRequestStatus, nil] :status
+    #
+    # @example
+    #   client.list_records
+    #
+    # @return [Insion::Types::ListRecordsResponse]
+    def list_records(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      query_params = {}
+      query_params["limit"] = params[:limit] if params.key?(:limit)
+      query_params["starting_after"] = params[:starting_after] if params.key?(:starting_after)
+      query_params["ending_before"] = params[:ending_before] if params.key?(:ending_before)
+      query_params["clientId"] = params[:client_id] if params.key?(:client_id)
+      query_params["user"] = params[:user] if params.key?(:user)
+      query_params["entity"] = params[:entity] if params.key?(:entity)
+      query_params["status"] = params[:status] if params.key?(:status)
+
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "GET",
+        path: "api/v1/records",
+        query: query_params,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::ListRecordsResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # Retrieve one record by its Insion record ID.
+    #
+    # @param request_options [Hash]
+    # @param params [Hash]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    # @option params [String] :record_id
+    #
+    # @example
+    #   client.retrieve_a_record(record_id: "recordId")
+    #
+    # @return [Insion::Types::RecordResponse]
+    def retrieve_a_record(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "GET",
+        path: "api/v1/records/#{URI.encode_uri_component(params[:record_id].to_s)}",
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::RecordResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # List the users belonging to the authenticated organization.
+    #
+    # @param request_options [Hash]
+    # @param params [Hash]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    # @option params [Integer, nil] :limit
+    # @option params [String, nil] :starting_after
+    # @option params [String, nil] :ending_before
+    # @option params [String, nil] :client_id
+    # @option params [String, nil] :email
+    # @option params [Insion::Types::GetAPIV1UsersRequestStatus, nil] :status
+    # @option params [String, nil] :user
+    #
+    # @example
+    #   client.list_users
+    #
+    # @return [Insion::Types::ListUsersResponse]
+    def list_users(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      query_params = {}
+      query_params["limit"] = params[:limit] if params.key?(:limit)
+      query_params["starting_after"] = params[:starting_after] if params.key?(:starting_after)
+      query_params["ending_before"] = params[:ending_before] if params.key?(:ending_before)
+      query_params["clientId"] = params[:client_id] if params.key?(:client_id)
+      query_params["email"] = params[:email] if params.key?(:email)
+      query_params["status"] = params[:status] if params.key?(:status)
+      query_params["user"] = params[:user] if params.key?(:user)
+
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "GET",
+        path: "api/v1/users",
+        query: query_params,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::ListUsersResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # Retrieve one user by its Insion user ID.
+    #
+    # @param request_options [Hash]
+    # @param params [Hash]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    # @option params [String] :user_id
+    #
+    # @example
+    #   client.retrieve_a_user(user_id: "userId")
+    #
+    # @return [Insion::Types::UserResponse]
+    def retrieve_a_user(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "GET",
+        path: "api/v1/users/#{URI.encode_uri_component(params[:user_id].to_s)}",
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::UserResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # Create an appeal for a suspended user. Appeals must be enabled for the organization.
+    #
+    # @param request_options [Hash]
+    # @param params [Insion::Types::PostAPIV1UsersUserIDCreateAppealRequest]
+    # @option request_options [String] :base_url
+    # @option request_options [Hash{String => Object}] :additional_headers
+    # @option request_options [Hash{String => Object}] :additional_query_parameters
+    # @option request_options [Hash{String => Object}] :additional_body_parameters
+    # @option request_options [Integer] :timeout_in_seconds
+    # @option params [String] :user_id
+    #
+    # @example
+    #   client.create_an_appeal(
+    #     user_id: "userId",
+    #     text: "text"
+    #   )
+    #
+    # @return [Insion::Types::CreateAppealResponse]
+    def create_an_appeal(request_options: {}, **params)
+      params = Insion::Internal::Types::Utils.normalize_keys(params)
+      request_data = Insion::Types::PostAPIV1UsersUserIDCreateAppealRequest.new(params).to_h
+      non_body_param_names = %w[userId]
+      body = request_data.except(*non_body_param_names)
+
+      request = Insion::Internal::JSON::Request.new(
+        base_url: request_options[:base_url],
+        method: "POST",
+        path: "api/v1/users/#{URI.encode_uri_component(params[:user_id].to_s)}/create_appeal",
+        body: body,
+        request_options: request_options
+      )
+      begin
+        response = @client.send(request)
+      rescue Net::HTTPRequestTimeout
+        raise Insion::Errors::TimeoutError
+      end
+      code = response.code.to_i
+      if code.between?(200, 299)
+        Insion::Types::CreateAppealResponse.load(response.body)
+      else
+        error_class = Insion::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+
+    # @param token [String]
+    # @param base_url [String, nil]
+    # @param max_retries [Integer]
+    #
+    # @return [void]
+    def initialize(token:, base_url: nil, max_retries: 2)
+      @raw_client = Insion::Internal::Http::RawClient.new(
+        base_url: base_url || Insion::Environment::DEFAULT,
+        headers: {
+          Authorization: "Bearer #{token}"
+        },
+        max_retries: max_retries
+      )
+    end
+  end
+end

data/lib/Insion/environment.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Insion
+  class Environment
+    DEFAULT = "https://api.insion.co"
+  end
+end

data/lib/Insion/errors/api_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Insion
+  module Errors
+    class ApiError < StandardError
+    end
+  end
+end

data/lib/Insion/errors/client_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Insion
+  module Errors
+    class ClientError < ResponseError
+    end
+
+    class UnauthorizedError < ClientError
+    end
+
+    class ForbiddenError < ClientError
+    end
+
+    class NotFoundError < ClientError
+    end
+  end
+end

data/lib/Insion/errors/redirect_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Insion
+  module Errors
+    class RedirectError < ResponseError
+    end
+  end
+end

data/lib/Insion/errors/response_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Insion
+  module Errors
+    class ResponseError < ApiError
+      attr_reader :code
+
+      def initialize(msg, code:)
+        @code = code
+        super(msg)
+      end
+
+      def inspect
+        "#<#{self.class.name} @code=#{code} @body=#{message}>"
+      end
+
+      # Returns the most appropriate error class for the given code.
+      #
+      # @return [Class]
+      def self.subclass_for_code(code)
+        case code
+        when 300..399
+          RedirectError
+        when 401
+          UnauthorizedError
+        when 403
+          ForbiddenError
+        when 404
+          NotFoundError
+        when 400..499
+          ClientError
+        when 503
+          ServiceUnavailableError
+        when 500..599
+          ServerError
+        else
+          ResponseError
+        end
+      end
+    end
+  end
+end