orb-billing 0.1.0.pre.alpha.33

data/rbi/lib/orb/resources/alerts.rbi

@@ -0,0 +1,216 @@
+# typed: strong
+
+module Orb
+  module Resources
+    class Alerts
+      # This endpoint retrieves an alert by its ID.
+      sig do
+        params(alert_id: String, request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash)))
+          .returns(Orb::Models::Alert)
+      end
+      def retrieve(alert_id, request_options: {})
+      end
+
+      # This endpoint updates the thresholds of an alert.
+      sig do
+        params(
+          alert_configuration_id: String,
+          thresholds: T::Array[T.any(Orb::Models::AlertUpdateParams::Threshold, Orb::Util::AnyHash)],
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Alert)
+      end
+      def update(
+        alert_configuration_id,
+        # The thresholds that define the values at which the alert will be triggered.
+        thresholds:,
+        request_options: {}
+      )
+      end
+
+      # This endpoint returns a list of alerts within Orb.
+      #
+      #   The request must specify one of `customer_id`, `external_customer_id`, or
+      #   `subscription_id`.
+      #
+      #   If querying by subscripion_id, the endpoint will return the subscription level
+      #   alerts as well as the plan level alerts associated with the subscription.
+      #
+      #   The list of alerts is ordered starting from the most recently created alert.
+      #   This endpoint follows Orb's
+      #   [standardized pagination format](/api-reference/pagination).
+      sig do
+        params(
+          created_at_gt: T.nilable(Time),
+          created_at_gte: T.nilable(Time),
+          created_at_lt: T.nilable(Time),
+          created_at_lte: T.nilable(Time),
+          cursor: T.nilable(String),
+          customer_id: T.nilable(String),
+          external_customer_id: T.nilable(String),
+          limit: Integer,
+          subscription_id: T.nilable(String),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Page[Orb::Models::Alert])
+      end
+      def list(
+        created_at_gt: nil,
+        created_at_gte: nil,
+        created_at_lt: nil,
+        created_at_lte: nil,
+        # Cursor for pagination. This can be populated by the `next_cursor` value returned
+        #   from the initial request.
+        cursor: nil,
+        # Fetch alerts scoped to this customer_id
+        customer_id: nil,
+        # Fetch alerts scoped to this external_customer_id
+        external_customer_id: nil,
+        # The number of items to fetch. Defaults to 20.
+        limit: nil,
+        # Fetch alerts scoped to this subscription_id
+        subscription_id: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint creates a new alert to monitor a customer's credit balance. There
+      #   are three types of alerts that can be scoped to customers:
+      #   `credit_balance_depleted`, `credit_balance_dropped`, and
+      #   `credit_balance_recovered`. Customers can have a maximum of one of each type of
+      #   alert per [credit balance currency](/product-catalog/prepurchase).
+      #   `credit_balance_dropped` alerts require a list of thresholds to be provided
+      #   while `credit_balance_depleted` and `credit_balance_recovered` alerts do not
+      #   require thresholds.
+      sig do
+        params(
+          customer_id: String,
+          currency: String,
+          type: Orb::Models::AlertCreateForCustomerParams::Type::OrSymbol,
+          thresholds: T.nilable(T::Array[T.any(Orb::Models::AlertCreateForCustomerParams::Threshold, Orb::Util::AnyHash)]),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Alert)
+      end
+      def create_for_customer(
+        customer_id,
+        # The case sensitive currency or custom pricing unit to use for this alert.
+        currency:,
+        # The type of alert to create. This must be a valid alert type.
+        type:,
+        # The thresholds that define the values at which the alert will be triggered.
+        thresholds: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint creates a new alert to monitor a customer's credit balance. There
+      #   are three types of alerts that can be scoped to customers:
+      #   `credit_balance_depleted`, `credit_balance_dropped`, and
+      #   `credit_balance_recovered`. Customers can have a maximum of one of each type of
+      #   alert per [credit balance currency](/product-catalog/prepurchase).
+      #   `credit_balance_dropped` alerts require a list of thresholds to be provided
+      #   while `credit_balance_depleted` and `credit_balance_recovered` alerts do not
+      #   require thresholds.
+      sig do
+        params(
+          external_customer_id: String,
+          currency: String,
+          type: Orb::Models::AlertCreateForExternalCustomerParams::Type::OrSymbol,
+          thresholds: T.nilable(
+            T::Array[T.any(Orb::Models::AlertCreateForExternalCustomerParams::Threshold, Orb::Util::AnyHash)]
+          ),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Alert)
+      end
+      def create_for_external_customer(
+        external_customer_id,
+        # The case sensitive currency or custom pricing unit to use for this alert.
+        currency:,
+        # The type of alert to create. This must be a valid alert type.
+        type:,
+        # The thresholds that define the values at which the alert will be triggered.
+        thresholds: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint is used to create alerts at the subscription level.
+      #
+      #   Subscription level alerts can be one of two types: `usage_exceeded` or
+      #   `cost_exceeded`. A `usage_exceeded` alert is scoped to a particular metric and
+      #   is triggered when the usage of that metric exceeds predefined thresholds during
+      #   the current billing cycle. A `cost_exceeded` alert is triggered when the total
+      #   amount due during the current billing cycle surpasses predefined thresholds.
+      #   `cost_exceeded` alerts do not include burndown of pre-purchase credits. Each
+      #   subscription can have one `cost_exceeded` alert and one `usage_exceeded` alert
+      #   per metric that is a part of the subscription. Alerts are triggered based on
+      #   usage or cost conditions met during the current billing cycle.
+      sig do
+        params(
+          subscription_id: String,
+          thresholds: T::Array[T.any(Orb::Models::AlertCreateForSubscriptionParams::Threshold, Orb::Util::AnyHash)],
+          type: Orb::Models::AlertCreateForSubscriptionParams::Type::OrSymbol,
+          metric_id: T.nilable(String),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Alert)
+      end
+      def create_for_subscription(
+        subscription_id,
+        # The thresholds that define the values at which the alert will be triggered.
+        thresholds:,
+        # The type of alert to create. This must be a valid alert type.
+        type:,
+        # The metric to track usage for.
+        metric_id: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint allows you to disable an alert. To disable a plan-level alert for
+      #   a specific subscription, you must include the `subscription_id`. The
+      #   `subscription_id` is not required for customer or subscription level alerts.
+      sig do
+        params(
+          alert_configuration_id: String,
+          subscription_id: T.nilable(String),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Alert)
+      end
+      def disable(
+        alert_configuration_id,
+        # Used to update the status of a plan alert scoped to this subscription_id
+        subscription_id: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint allows you to enable an alert. To enable a plan-level alert for a
+      #   specific subscription, you must include the `subscription_id`. The
+      #   `subscription_id` is not required for customer or subscription level alerts.
+      sig do
+        params(
+          alert_configuration_id: String,
+          subscription_id: T.nilable(String),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Alert)
+      end
+      def enable(
+        alert_configuration_id,
+        # Used to update the status of a plan alert scoped to this subscription_id
+        subscription_id: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Orb::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/lib/orb/resources/coupons/subscriptions.rbi

@@ -0,0 +1,38 @@
+# typed: strong
+
+module Orb
+  module Resources
+    class Coupons
+      class Subscriptions
+        # This endpoint returns a list of all subscriptions that have redeemed a given
+        #   coupon as a [paginated](/api-reference/pagination) list, ordered starting from
+        #   the most recently created subscription. For a full discussion of the
+        #   subscription resource, see [Subscription](/core-concepts#subscription).
+        sig do
+          params(
+            coupon_id: String,
+            cursor: T.nilable(String),
+            limit: Integer,
+            request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+          )
+            .returns(Orb::Page[Orb::Models::Subscription])
+        end
+        def list(
+          coupon_id,
+          # Cursor for pagination. This can be populated by the `next_cursor` value returned
+          #   from the initial request.
+          cursor: nil,
+          # The number of items to fetch. Defaults to 20.
+          limit: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Orb::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/lib/orb/resources/coupons.rbi

@@ -0,0 +1,96 @@
+# typed: strong
+
+module Orb
+  module Resources
+    class Coupons
+      sig { returns(Orb::Resources::Coupons::Subscriptions) }
+      attr_reader :subscriptions
+
+      # This endpoint allows the creation of coupons, which can then be redeemed at
+      #   subscription creation or plan change.
+      sig do
+        params(
+          discount: T.any(
+            Orb::Models::CouponCreateParams::Discount::NewCouponPercentageDiscount,
+            Orb::Util::AnyHash,
+            Orb::Models::CouponCreateParams::Discount::NewCouponAmountDiscount
+          ),
+          redemption_code: String,
+          duration_in_months: T.nilable(Integer),
+          max_redemptions: T.nilable(Integer),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::Coupon)
+      end
+      def create(
+        discount:,
+        # This string can be used to redeem this coupon for a given subscription.
+        redemption_code:,
+        # This allows for a coupon's discount to apply for a limited time (determined in
+        #   months); a `null` value here means "unlimited time".
+        duration_in_months: nil,
+        # The maximum number of redemptions allowed for this coupon before it is
+        #   exhausted;`null` here means "unlimited".
+        max_redemptions: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint returns a list of all coupons for an account in a list format.
+      #
+      #   The list of coupons is ordered starting from the most recently created coupon.
+      #   The response also includes `pagination_metadata`, which lets the caller retrieve
+      #   the next page of results if they exist. More information about pagination can be
+      #   found in the Pagination-metadata schema.
+      sig do
+        params(
+          cursor: T.nilable(String),
+          limit: Integer,
+          redemption_code: T.nilable(String),
+          show_archived: T.nilable(T::Boolean),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Page[Orb::Models::Coupon])
+      end
+      def list(
+        # Cursor for pagination. This can be populated by the `next_cursor` value returned
+        #   from the initial request.
+        cursor: nil,
+        # The number of items to fetch. Defaults to 20.
+        limit: nil,
+        # Filter to coupons matching this redemption code.
+        redemption_code: nil,
+        # Show archived coupons as well (by default, this endpoint only returns active
+        #   coupons).
+        show_archived: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint allows a coupon to be archived. Archived coupons can no longer be
+      #   redeemed, and will be hidden from lists of active coupons. Additionally, once a
+      #   coupon is archived, its redemption code can be reused for a different coupon.
+      sig do
+        params(coupon_id: String, request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash)))
+          .returns(Orb::Models::Coupon)
+      end
+      def archive(coupon_id, request_options: {})
+      end
+
+      # This endpoint retrieves a coupon by its ID. To fetch coupons by their redemption
+      #   code, use the [List coupons](list-coupons) endpoint with the redemption_code
+      #   parameter.
+      sig do
+        params(coupon_id: String, request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash)))
+          .returns(Orb::Models::Coupon)
+      end
+      def fetch(coupon_id, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Orb::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/lib/orb/resources/credit_notes.rbi

@@ -0,0 +1,74 @@
+# typed: strong
+
+module Orb
+  module Resources
+    class CreditNotes
+      # This endpoint is used to create a single
+      #   [`Credit Note`](/invoicing/credit-notes).
+      sig do
+        params(
+          line_items: T::Array[T.any(Orb::Models::CreditNoteCreateParams::LineItem, Orb::Util::AnyHash)],
+          memo: T.nilable(String),
+          reason: T.nilable(Orb::Models::CreditNoteCreateParams::Reason::OrSymbol),
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::CreditNote)
+      end
+      def create(
+        line_items:,
+        # An optional memo to attach to the credit note.
+        memo: nil,
+        # An optional reason for the credit note.
+        reason: nil,
+        request_options: {}
+      )
+      end
+
+      # Get a paginated list of CreditNotes. Users can also filter by customer_id,
+      #   subscription_id, or external_customer_id. The credit notes will be returned in
+      #   reverse chronological order by `creation_time`.
+      sig do
+        params(
+          created_at_gt: T.nilable(Time),
+          created_at_gte: T.nilable(Time),
+          created_at_lt: T.nilable(Time),
+          created_at_lte: T.nilable(Time),
+          cursor: T.nilable(String),
+          limit: Integer,
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Page[Orb::Models::CreditNote])
+      end
+      def list(
+        created_at_gt: nil,
+        created_at_gte: nil,
+        created_at_lt: nil,
+        created_at_lte: nil,
+        # Cursor for pagination. This can be populated by the `next_cursor` value returned
+        #   from the initial request.
+        cursor: nil,
+        # The number of items to fetch. Defaults to 20.
+        limit: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes)
+      #   given an identifier.
+      sig do
+        params(
+          credit_note_id: String,
+          request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+        )
+          .returns(Orb::Models::CreditNote)
+      end
+      def fetch(credit_note_id, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Orb::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/lib/orb/resources/customers/balance_transactions.rbi

@@ -0,0 +1,92 @@
+# typed: strong
+
+module Orb
+  module Resources
+    class Customers
+      class BalanceTransactions
+        # Creates an immutable balance transaction that updates the customer's balance and
+        #   returns back the newly created transaction.
+        sig do
+          params(
+            customer_id: String,
+            amount: String,
+            type: Orb::Models::Customers::BalanceTransactionCreateParams::Type::OrSymbol,
+            description: T.nilable(String),
+            request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+          )
+            .returns(Orb::Models::Customers::BalanceTransactionCreateResponse)
+        end
+        def create(
+          customer_id,
+          amount:,
+          type:,
+          # An optional description that can be specified around this entry.
+          description: nil,
+          request_options: {}
+        )
+        end
+
+        # ## The customer balance
+        #
+        #   The customer balance is an amount in the customer's currency, which Orb
+        #   automatically applies to subsequent invoices. This balance can be adjusted
+        #   manually via Orb's webapp on the customer details page. You can use this balance
+        #   to provide a fixed mid-period credit to the customer. Commonly, this is done due
+        #   to system downtime/SLA violation, or an adhoc adjustment discussed with the
+        #   customer.
+        #
+        #   If the balance is a positive value at the time of invoicing, it represents that
+        #   the customer has credit that should be used to offset the amount due on the next
+        #   issued invoice. In this case, Orb will automatically reduce the next invoice by
+        #   the balance amount, and roll over any remaining balance if the invoice is fully
+        #   discounted.
+        #
+        #   If the balance is a negative value at the time of invoicing, Orb will increase
+        #   the invoice's amount due with a positive adjustment, and reset the balance to 0.
+        #
+        #   This endpoint retrieves all customer balance transactions in reverse
+        #   chronological order for a single customer, providing a complete audit trail of
+        #   all adjustments and invoice applications.
+        #
+        #   ## Eligibility
+        #
+        #   The customer balance can only be applied to invoices or adjusted manually if
+        #   invoices are not synced to a separate invoicing provider. If a payment gateway
+        #   such as Stripe is used, the balance will be applied to the invoice before
+        #   forwarding payment to the gateway.
+        sig do
+          params(
+            customer_id: String,
+            cursor: T.nilable(String),
+            limit: Integer,
+            operation_time_gt: T.nilable(Time),
+            operation_time_gte: T.nilable(Time),
+            operation_time_lt: T.nilable(Time),
+            operation_time_lte: T.nilable(Time),
+            request_options: T.nilable(T.any(Orb::RequestOptions, Orb::Util::AnyHash))
+          )
+            .returns(Orb::Page[Orb::Models::Customers::BalanceTransactionListResponse])
+        end
+        def list(
+          customer_id,
+          # Cursor for pagination. This can be populated by the `next_cursor` value returned
+          #   from the initial request.
+          cursor: nil,
+          # The number of items to fetch. Defaults to 20.
+          limit: nil,
+          operation_time_gt: nil,
+          operation_time_gte: nil,
+          operation_time_lt: nil,
+          operation_time_lte: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Orb::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end