orb-billing/resources/alerts.d.ts

The official TypeScript library for the Orb API

import { APIResource } from "../resource.js";
import * as Core from "../core.js";
import * as Shared from "./shared.js";
import { Page, type PageParams } from "../pagination.js";
export declare class Alerts extends APIResource {
    /**
     * This endpoint retrieves an alert by its ID.
     */
    retrieve(alertId: string, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    /**
     * This endpoint updates the thresholds of an alert.
     */
    update(alertConfigurationId: string, body: AlertUpdateParams, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    /**
     * 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 subscription_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).
     */
    list(query?: AlertListParams, options?: Core.RequestOptions): Core.PagePromise<AlertsPage, Alert>;
    list(options?: Core.RequestOptions): Core.PagePromise<AlertsPage, Alert>;
    /**
     * 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.
     */
    createForCustomer(customerId: string, body: AlertCreateForCustomerParams, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    /**
     * 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.
     */
    createForExternalCustomer(externalCustomerId: string, body: AlertCreateForExternalCustomerParams, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    /**
     * 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.
     */
    createForSubscription(subscriptionId: string, body: AlertCreateForSubscriptionParams, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    /**
     * 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.
     */
    disable(alertConfigurationId: string, params?: AlertDisableParams, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    disable(alertConfigurationId: string, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    /**
     * 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.
     */
    enable(alertConfigurationId: string, params?: AlertEnableParams, options?: Core.RequestOptions): Core.APIPromise<Alert>;
    enable(alertConfigurationId: string, options?: Core.RequestOptions): Core.APIPromise<Alert>;
}
export declare class AlertsPage extends Page<Alert> {
}
/**
 * [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending,
 * usage, or credit balance and trigger webhooks when a threshold is exceeded.
 *
 * Alerts created through the API can be scoped to either customers or
 * subscriptions.
 */
export interface Alert {
    /**
     * Also referred to as alert_id in this documentation.
     */
    id: string;
    /**
     * The creation time of the resource in Orb.
     */
    created_at: string;
    /**
     * The name of the currency the credit balance or invoice cost is denominated in.
     */
    currency: string | null;
    /**
     * The customer the alert applies to.
     */
    customer: Shared.CustomerMinified | null;
    /**
     * Whether the alert is enabled or disabled.
     */
    enabled: boolean;
    /**
     * The metric the alert applies to.
     */
    metric: Alert.Metric | null;
    /**
     * The plan the alert applies to.
     */
    plan: Alert.Plan | null;
    /**
     * The subscription the alert applies to.
     */
    subscription: Shared.SubscriptionMinified | null;
    /**
     * The thresholds that define the conditions under which the alert will be
     * triggered.
     */
    thresholds: Array<Threshold> | null;
    /**
     * The type of alert. This must be a valid alert type.
     */
    type: 'credit_balance_depleted' | 'credit_balance_dropped' | 'credit_balance_recovered' | 'usage_exceeded' | 'cost_exceeded';
    /**
     * The current status of the alert. This field is only present for credit balance
     * alerts.
     */
    balance_alert_status?: Array<Alert.BalanceAlertStatus> | null;
}
export declare namespace Alert {
    /**
     * The metric the alert applies to.
     */
    interface Metric {
        id: string;
    }
    /**
     * The plan the alert applies to.
     */
    interface Plan {
        id: string | null;
        /**
         * An optional user-defined ID for this plan resource, used throughout the system
         * as an alias for this Plan. Use this field to identify a plan by an existing
         * identifier in your system.
         */
        external_plan_id: string | null;
        name: string | null;
        plan_version: string;
    }
    /**
     * Alert status is used to determine if an alert is currently in-alert or not.
     */
    interface BalanceAlertStatus {
        /**
         * Whether the alert is currently in-alert or not.
         */
        in_alert: boolean;
        /**
         * The value of the threshold that defines the alert status.
         */
        threshold_value: number;
    }
}
/**
 * Thresholds are used to define the conditions under which an alert will be
 * triggered.
 */
export interface Threshold {
    /**
     * The value at which an alert will fire. For credit balance alerts, the alert will
     * fire at or below this value. For usage and cost alerts, the alert will fire at
     * or above this value.
     */
    value: number;
}
export interface AlertUpdateParams {
    /**
     * The thresholds that define the values at which the alert will be triggered.
     */
    thresholds: Array<Threshold>;
}
export interface AlertListParams extends PageParams {
    'created_at[gt]'?: string | null;
    'created_at[gte]'?: string | null;
    'created_at[lt]'?: string | null;
    'created_at[lte]'?: string | null;
    /**
     * Fetch alerts scoped to this customer_id
     */
    customer_id?: string | null;
    /**
     * Fetch alerts scoped to this external_customer_id
     */
    external_customer_id?: string | null;
    /**
     * Fetch alerts scoped to this subscription_id
     */
    subscription_id?: string | null;
}
export interface AlertCreateForCustomerParams {
    /**
     * The case sensitive currency or custom pricing unit to use for this alert.
     */
    currency: string;
    /**
     * The type of alert to create. This must be a valid alert type.
     */
    type: 'credit_balance_depleted' | 'credit_balance_dropped' | 'credit_balance_recovered';
    /**
     * The thresholds that define the values at which the alert will be triggered.
     */
    thresholds?: Array<Threshold> | null;
}
export interface AlertCreateForExternalCustomerParams {
    /**
     * The case sensitive currency or custom pricing unit to use for this alert.
     */
    currency: string;
    /**
     * The type of alert to create. This must be a valid alert type.
     */
    type: 'credit_balance_depleted' | 'credit_balance_dropped' | 'credit_balance_recovered';
    /**
     * The thresholds that define the values at which the alert will be triggered.
     */
    thresholds?: Array<Threshold> | null;
}
export interface AlertCreateForSubscriptionParams {
    /**
     * The thresholds that define the values at which the alert will be triggered.
     */
    thresholds: Array<Threshold>;
    /**
     * The type of alert to create. This must be a valid alert type.
     */
    type: 'usage_exceeded' | 'cost_exceeded';
    /**
     * The metric to track usage for.
     */
    metric_id?: string | null;
}
export interface AlertDisableParams {
    /**
     * Used to update the status of a plan alert scoped to this subscription_id
     */
    subscription_id?: string | null;
}
export interface AlertEnableParams {
    /**
     * Used to update the status of a plan alert scoped to this subscription_id
     */
    subscription_id?: string | null;
}
export declare namespace Alerts {
    export { type Alert as Alert, type Threshold as Threshold, AlertsPage as AlertsPage, type AlertUpdateParams as AlertUpdateParams, type AlertListParams as AlertListParams, type AlertCreateForCustomerParams as AlertCreateForCustomerParams, type AlertCreateForExternalCustomerParams as AlertCreateForExternalCustomerParams, type AlertCreateForSubscriptionParams as AlertCreateForSubscriptionParams, type AlertDisableParams as AlertDisableParams, type AlertEnableParams as AlertEnableParams, };
}
//# sourceMappingURL=alerts.d.ts.map