orb-apiamtic-sdk 0.0.1

data/lib/api_reference/apis/event_api.rb

@@ -0,0 +1,776 @@
+# api_reference
+#
+# This file was automatically generated by APIMATIC v3.0 (
+# https://www.apimatic.io ).
+
+module ApiReference
+  # EventApi
+  class EventApi < BaseApi
+    # This endpoint returns a list of all backfills in a list format.
+    # The list of backfills is ordered starting from the most recently created
+    # backfill. The response also includes
+    # [`pagination_metadata`](/api-reference/pagination), which lets the caller
+    # retrieve the next page of results if they
+    # exist.
+    # @param [Integer] limit Optional parameter: Example:20
+    # @param [String] cursor Optional parameter: TODO: type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def list_backfills(limit: 20,
+                       cursor: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/events/backfills',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(limit, key: 'limit'))
+                   .query_param(new_parameter(cursor, key: 'cursor'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Backfills.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # Creating the backfill enables adding or replacing past events, even those
+    # that are older than the ingestion grace
+    # period. Performing a backfill in Orb involves 3 steps:
+    # 1. Create the backfill, specifying its parameters.
+    # 2. [Ingest](/api-reference/event/ingest-events) usage events, referencing
+    # the backfill (query parameter `backfill_id`).
+    # 3. [Close](close-backfill) the
+    # backfill, propagating the update in past usage throughout Orb.
+    # Changes from a backfill are not reflected until the
+    # backfill is closed, so you won’t need to worry about your customers seeing
+    # partially updated usage data. Backfills are
+    # also reversible, so you’ll be able to revert a backfill if you’ve made a
+    # mistake.
+    # This endpoint will return a
+    # backfill object, which contains an `id`. That `id` can then be used as the
+    # `backfill_id` query parameter to the event
+    # ingestion endpoint to associate ingested events with this backfill. The
+    # effects (e.g. updated usage graphs) of this
+    # backfill will not take place until the backfill is closed.
+    # If the `replace_existing_events` is `true`, existing
+    # events in the backfill's timeframe will be replaced with the newly
+    # ingested events associated with the backfill. If
+    # `false`, newly ingested events will be added to the existing events.
+    # If a `customer_id` or `external_customer_id` is specified, the backfill
+    # will only affect events for that customer.
+    # If neither is specified, the backfill will affect all customers.
+    # When `replace_existing_events` is `true`, this indicates that existing
+    # events in the timeframe should no longer be counted
+    # towards invoiced usage. In this scenario, the parameter
+    # `deprecation_filter` can be optionally added which enables filtering
+    # using [computed
+    # properties](/extensibility/advanced-metrics#computed-properties). The
+    # expressiveness of computed properties
+    # allows you to deprecate existing events based on both a period of time and
+    # specific property values.
+    # You may not have multiple backfills in a pending or pending_revert state
+    # with overlapping timeframes.
+    # @param [NewBackfill] body Required parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def create_backfill(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/events/backfills',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Backfill.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # This endpoint is used to fetch a backfill given an identifier.
+    # @param [String] backfill_id Required parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def fetch_backfill(backfill_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/events/backfills/{backfill_id}',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(backfill_id, key: 'backfill_id')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Backfill.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # Closing a backfill makes the updated usage visible in Orb. Upon closing a
+    # backfill, Orb will asynchronously reflect
+    # the updated usage in invoice amounts and usage graphs. Once all of the
+    # updates are complete, the backfill's status
+    # will transition to `reflected`.
+    # @param [String] backfill_id Required parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def close_backfill(backfill_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/events/backfills/{backfill_id}/close',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(backfill_id, key: 'backfill_id')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Backfill.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # Reverting a backfill undoes all the effects of closing the backfill. If
+    # the backfill is reflected, the status will
+    # transition to `pending_revert` while the effects of the backfill are
+    # undone. Once all effects are undone, the
+    # backfill will transition to `reverted`.
+    # If a backfill is reverted before its closed, no usage will be updated as a
+    # result of the backfill and it will
+    # immediately transition to `reverted`.
+    # @param [String] backfill_id Required parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def revert_backfill(backfill_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/events/backfills/{backfill_id}/revert',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(backfill_id, key: 'backfill_id')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Backfill.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # This endpoint returns a filtered set of events for an account in a
+    # [paginated list format](/api-reference/pagination).
+    # Note that this is a `POST` endpoint rather than a `GET` endpoint because
+    # it employs a JSON body for search criteria
+    # rather than query parameters, allowing for a more flexible search syntax.
+    # Note that a search criteria _must_ be specified. Currently, Orb supports
+    # the following criteria:
+    # - `event_ids`: This is an explicit array of IDs to filter by. Note that an
+    # event's ID is the `idempotency_key` that
+    #   was originally used for ingestion.
+    # By default, Orb will not throw a `404` if no events matched, Orb will
+    # return an empty array for `data` instead.
+    # @param [EventSearchCriteria] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def search_events(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/events/search',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Events.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # This endpoint returns the event volume for an account in a [paginated list
+    # format](/api-reference/pagination).
+    # The event volume is aggregated by the hour and the
+    # [timestamp](/api-reference/event/ingest-events)
+    # field is used to determine which hour an event is associated with. Note,
+    # this means that late-arriving events
+    # increment the volume count for the hour window the timestamp is in, not
+    # the latest hour window.
+    # Each item in the response contains the count of events aggregated by the
+    # hour
+    # where the start and end time are hour-aligned and in UTC. When a specific
+    # timestamp is passed
+    # in for either start or end time, the response includes the hours the
+    # timestamp falls in.
+    # @param [DateTime] timeframe_start Required parameter: TODO: type
+    # description here
+    # @param [Integer] limit Optional parameter: Example:20
+    # @param [String] cursor Optional parameter: TODO: type description here
+    # @param [DateTime] timeframe_end Optional parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_event_volume(timeframe_start,
+                         limit: 20,
+                         cursor: nil,
+                         timeframe_end: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/events/volume',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(timeframe_start, key: 'timeframe_start')
+                                 .is_required(true))
+                   .query_param(new_parameter(limit, key: 'limit'))
+                   .query_param(new_parameter(cursor, key: 'cursor'))
+                   .query_param(new_parameter(timeframe_end, key: 'timeframe_end'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(EventVolumes.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # This endpoint is used to amend a single usage event with a given
+    # `event_id`. `event_id` refers to the
+    # `idempotency_key` passed in during ingestion. The event will maintain its
+    # existing `event_id` after the amendment.
+    # This endpoint will mark the existing event as ignored, and Orb will only
+    # use the new event passed in the body of
+    # this request as the source of truth for that `event_id`. Note that a
+    # single event can be amended any number of
+    # times, so the same event can be overwritten in subsequent calls to this
+    # endpoint. Only a single event with a given
+    # `event_id` will be considered the source of truth at any given time.
+    # This is a powerful and audit-safe mechanism to retroactively update a
+    # single event in cases where you need to:
+    # * update an event with new metadata as you iterate on your pricing model
+    # * update an event based on the result of an external API call (e.g. call
+    # to a payment gateway succeeded or failed)
+    # This amendment API is always audit-safe. The process will still retain the
+    # original event, though it will be
+    # ignored for billing calculations. For auditing and data fidelity purposes,
+    # Orb never overwrites or permanently
+    # deletes ingested usage data.
+    # ## Request validation
+    # * The `timestamp` of the new event must match the `timestamp` of the
+    # existing event already ingested. As with
+    #   ingestion, all timestamps must be sent in ISO8601 format with UTC
+    # timezone offset.
+    # * The `customer_id` or `external_customer_id` of the new event must match
+    # the `customer_id` or
+    #   `external_customer_id` of the existing event already ingested. Exactly
+    # one of `customer_id` and
+    #   `external_customer_id` should be specified, and similar to ingestion,
+    # the ID must identify a Customer resource
+    #   within Orb. Unlike ingestion, for event amendment, we strictly enforce
+    # that the Customer must be in the Orb
+    #   system, even during the initial integration period. We do not allow
+    # updating the `Customer` an event is
+    #   associated with.
+    # * Orb does not accept an `idempotency_key` with the event in this
+    # endpoint, since this request is by design
+    #   idempotent. On retryable errors, you should retry the request and assume
+    # the amendment operation has not
+    #   succeeded until receipt of a 2xx.
+    # * The event's `timestamp` must fall within the customer's current
+    # subscription's billing period, or within the
+    #   grace period of the customer's current subscription's previous billing
+    # period.
+    # * By default, no more than 100 events can be amended for a single customer
+    # in a 100 day period. For higher volume
+    #   updates, consider using the [event backfill](create-backfill) endpoint.
+    # @param [String] event_id Required parameter: TODO: type description here
+    # @param [AmendedEvent] body Required parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def amend_event(event_id,
+                    body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/events/{event_id}',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(event_id, key: 'event_id')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(AmendEventResult.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # This endpoint is used to deprecate a single usage event with a given
+    # `event_id`. `event_id` refers to the
+    # `idempotency_key` passed in during ingestion.
+    # This endpoint will mark the existing event as ignored. Note that if you
+    # attempt to re-ingest an event with the same
+    # `event_id` as a deprecated event, Orb will return an error.
+    # This is a powerful and audit-safe mechanism to retroactively deprecate a
+    # single event in cases where you need to:
+    # * no longer bill for an event that was improperly reported
+    # * no longer bill for an event based on the result of an external API call
+    # (e.g. call to a payment gateway failed and
+    #   the user should not be billed)
+    # If you want to only change specific properties of an event, but keep the
+    # event as part of the billing calculation,
+    # use the [Amend event](amend-event) endpoint instead.
+    # This API is always audit-safe. The process will still retain the
+    # deprecated event, though it will be ignored for
+    # billing calculations. For auditing and data fidelity purposes, Orb never
+    # overwrites or permanently deletes ingested
+    # usage data.
+    # ## Request validation
+    # * Orb does not accept an `idempotency_key` with the event in this
+    # endpoint, since this request is by design
+    #   idempotent. On retryable errors, you should retry the request and assume
+    # the deprecation operation has not
+    #   succeeded until receipt of a 2xx.
+    # * The event's `timestamp` must fall within the customer's current
+    # subscription's billing period, or within the
+    #   grace period of the customer's current subscription's previous billing
+    # period. Orb does not allow deprecating
+    #   events for billing periods that have already invoiced customers.
+    # * The `customer_id` or the `external_customer_id` of the original event
+    # ingestion request must identify a Customer
+    #   resource within Orb, even if this event was ingested during the initial
+    # integration period. We do not allow
+    #   deprecating events for customers not in the Orb system.
+    # * By default, no more than 100 events can be deprecated for a single
+    # customer in a 100 day period. For higher volume
+    #   updates, consider using the [event backfill](create-backfill) endpoint.
+    # @param [String] event_id Required parameter: TODO: type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def deprecate_event(event_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/events/{event_id}/deprecate',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(event_id, key: 'event_id')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(DeprecatedEventResult.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+
+    # Orb's event ingestion model and API is designed around two core
+    # principles:
+    # 1. **Data fidelity**: The accuracy of your billing model depends on a
+    # robust foundation of events. Orb's API protocol
+    # encourages usage patterns that ensure that your data is consistently
+    # complete and correct.
+    # 2. **Fast integration**: Sending events into Orb requires no tedious setup
+    # steps or explicit field schema for your event
+    # shape, making it instant to start streaming in usage in real-time.
+    # ## Event shape
+    # Events are the starting point for all usage calculations in the system,
+    # and are simple at their core:
+    # ```ts
+    # {
+    #   // customer_id and external_customer_id are used to
+    #   // attribute usage to a given Customer. Exactly one of these
+    #   // should be specified in a given ingestion event.
+    #   // `customer_id` is the Orb generated identifier for the Customer,
+    #   // which is returned from the Create customer API call.
+    #   customer_id: string,
+    #   // external_customer_id is an alternate identifier which is associated
+    #   // with a Customer at creation time. This is treated as an alias for
+    #   // customer_id, and is usually set to an identifier native to your
+    # system.
+    #   external_customer_id: string,
+    #   // A string name identifying the event, usually a usage
+    #   // action. By convention, this should not contain any whitespace.
+    #   event_name: string,
+    #   // An ISO 8601 format date with no timezone offset.
+    #   // This should represent the time that usage occurred
+    #   // and is important to attribute usage to a given
+    #   // billing period. See the notes below on determining the timestamp.
+    #   // e.g. 2020-12-09T16:09:53Z
+    #   timestamp: string,
+    #   // A unique value, generated by the client, that is
+    #   // used to de-duplicate events.
+    #   // Exactly one event with a given
+    #   // idempotency key will be ingested, which allows for
+    #   // safe request retries.
+    #   idempotency_key: string
+    #   // Optional custom metadata to attach to the event.
+    #   // This might include a numeric value used for aggregation,
+    #   // or a string/boolean value used for filtering.
+    #   // The schema of this dictionary need not be pre-declared, and
+    #   // properties can be added at any time.
+    #   properties: {
+    #     [key: string]?: string | number | boolean,
+    #   },
+    # }
+    # ```
+    # ## Required fields
+    # Because events streamed to Orb are meant to be as flexible as possible,
+    # there are only a few required fields in every
+    # event.
+    # - We recommend that `idempotency_key` are unique strings that you
+    # generated with V4 UUIDs, but only require that they
+    # uniquely identify an event (i.e. don’t collide).
+    # - The `timestamp` field in the event body will be used to determine which
+    # billable period a given event falls into. For
+    # example, with a monthly billing cycle starting from the first of December,
+    # Orb will calculate metrics based on events
+    # that fall into the range `12-01 00:00:00 <= timestamp < 01-01 00:00:00`.
+    # ## Logging metadata
+    # Orb allows tagging events with metadata using a flexible properties
+    # dictionary. Since Orb does not enforce a rigid
+    # schema for this field-set, key-value pairs can be added dynamically as
+    # your events evolve.
+    # This dictionary can be helpful for a wide variety of use cases:
+    # - Numeric properties on events like `compute_time_ms` can later be inputs
+    # to our flexible query engine to determine
+    # usage.
+    # - Logging a region or cluster with each event can help you provide
+    # customers more granular visibility into their usage.
+    # - If you are using matrix pricing and matching a matrix price key with a
+    # property,
+    # you should ensure the value for that property is sent as a string.
+    # We encourage logging this metadata with an eye towards future use cases to
+    # ensure full coverage for historical data. The
+    # datatype of the value in the properties dictionary is important for metric
+    # creation from an event source. Values that
+    # you wish to numerically aggregate should be of numeric type in the event.
+    # ## Determining event timestamp
+    # For cases where usage is being reported in real time as it is occurring,
+    # timestamp should correspond to the time that
+    # usage occurred.
+    # In cases where usage is reported in aggregate for a historical timeframe
+    # at a regular interval, we recommend setting the
+    # event `timestamp` to the midpoint of the interval. As an example, if you
+    # have an hourly reporter that sends data once an
+    # hour for the previous hour of usage, setting the `timestamp` to the
+    # half-hour mark will ensure that the usage is counted
+    # within the correct period.
+    # Note that other time-related fields (e.g. time elapsed) can be added to
+    # the properties dictionary as necessary.
+    # In cases where usage is reported in aggregate for a historical timeframe,
+    # the timestamp must be within the grace period
+    # set for your account. Events with `timestamp < current_time -
+    # grace_period` will not be accepted as a valid event, and
+    # will throw validation errors. Enforcing the grace period enables Orb to
+    # accurately map usage to the correct billing
+    # cycle and ensure that all usage is billed for in the corresponding billing
+    # period.
+    # In general, Orb does not expect events with future dated timestamps. In
+    # cases where the timestamp is 5 minutes ahead
+    # of the current time, the event will not be accepted as a valid event, and
+    # will throw validation errors.
+    # ## Event validation
+    # Orb’s validation ensures that you recognize errors in your events as
+    # quickly as possible, and the API provides
+    # informative error messages to help you fix problems quickly.
+    # We validate the following:
+    # - Exactly one of `customer_id` and `external_customer_id` should be
+    # specified.
+    # - If the `customer_id` is specified, the customer in Orb must exist.
+    # - If the `external_customer_id` is specified, the customer in Orb does not
+    # need to exist. Events will be attributed to any
+    # future customers with the `external_customer_id` on subscription creation.
+    # - `timestamp` must conform to ISO 8601 and represent a timestamp at most 5
+    # minutes in the future. This timestamp should be
+    # sent in UTC timezone (no timezone offset).
+    # ## Idempotency and retry semantics
+    # Orb's idempotency guarantees allow you to implement safe retry logic in
+    # the event of network or machine failures,
+    # ensuring data fidelity. Each event in the request payload is associated
+    # with an idempotency key, and Orb guarantees that
+    # a single idempotency key will be successfully ingested at most once. Note
+    # that when Orb encounters events with duplicate
+    # idempotency keys and differing event bodies in a batch of events, the
+    # entire batch will be rejected.
+    # - Successful responses return a 200 HTTP status code. The response
+    # contains information about previously processed
+    # events.
+    # - Requests that return a `4xx` HTTP status code indicate a payload error
+    # and contain at least one event with a
+    # validation failure. An event with a validation failure can be re-sent to
+    # the ingestion endpoint (after the payload is
+    # fixed) with the original idempotency key since that key is not marked as
+    # processed.
+    # - Requests that return a `5xx` HTTP status code indicate a server-side
+    # failure. These requests should be retried in
+    # their entirety.
+    # ## API usage and limits
+    # The ingestion API is designed made for real-time streaming ingestion and
+    # architected for high throughput. Even if events
+    # are later deemed unnecessary or filtered out, we encourage you to log them
+    # to Orb if they may be relevant to billing
+    # calculations in the future.
+    # To take advantage of the real-time features of the Orb platform and avoid
+    # any chance of dropped events by producers, we
+    # recommend reporting events to Orb frequently. Optionally, events can also
+    # be briefly aggregated at the source, as this
+    # API accepts an array of event bodies.
+    # Orb does not currently enforce a hard rate-limit for API usage or a
+    # maximum request payload size, but please give us a
+    # heads up if you’re changing either of these factors by an order of
+    # magnitude from initial setup.
+    # #### Example: ingestion response
+    # ```json
+    # {
+    #   "validation_failed": []
+    # }
+    # ```
+    # @param [IngestRequestBody] body Required parameter: TODO: type description
+    # here
+    # @param [TrueClass | FalseClass] debug Optional parameter: Example:false
+    # @param [String] backfill_id Optional parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def ingest(body,
+               debug: false,
+               backfill_id: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/ingest',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .query_param(new_parameter(debug, key: 'debug'))
+                   .query_param(new_parameter(backfill_id, key: 'backfill_id'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('APIKeyAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(IngestionResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 APIException)
+                    .local_error('401',
+                                 'Unauthorized',
+                                 AuthorizationErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 APIException)
+                    .local_error('409',
+                                 'Conflict',
+                                 IdempotencyRequestMismatchException)
+                    .local_error('413',
+                                 'Content Too Large',
+                                 APIException)
+                    .local_error('429',
+                                 'Too Many Requests',
+                                 TooManyRequestsException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ServerErrorException))
+        .execute
+    end
+  end
+end