orb-billing 2.5.1 → 2.6.1

package/src/resources/alerts.ts

@@ -2,9 +2,109 @@
 
 import * as Core from "../core";
 import { APIResource } from "../resource";
+import { isRequestOptions } from "../core";
 import * as AlertsAPI from "./alerts";
+import { Page, type PageParams } from "../pagination";
 
 export class Alerts extends APIResource {
+  /**
+   * This endpoint retrieves an alert by its ID.
+   */
+  retrieve(alertId: string, options?: Core.RequestOptions): Core.APIPromise<Alert> {
+    return this._client.get(`/alerts/${alertId}`, options);
+  }
+
+  /**
+   * 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](../reference/pagination).
+   */
+  list(query?: AlertListParams, options?: Core.RequestOptions): Core.PagePromise<AlertsPage, Alert>;
+  list(options?: Core.RequestOptions): Core.PagePromise<AlertsPage, Alert>;
+  list(
+    query: AlertListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AlertsPage, Alert> {
+    if (isRequestOptions(query)) {
+      return this.list({}, query);
+    }
+    return this._client.getAPIList('/alerts', AlertsPage, { query, ...options });
+  }
+
+  /**
+   * 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](https://docs.withorb.com/guides/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> {
+    return this._client.post(`/alerts/customer_id/${customerId}`, { body, ...options });
+  }
+
+  /**
+   * 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](https://docs.withorb.com/guides/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> {
+    return this._client.post(`/alerts/external_customer_id/${externalCustomerId}`, { body, ...options });
+  }
+
+  /**
+   * 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> {
+    return this._client.post(`/alerts/subscription_id/${subscriptionId}`, { body, ...options });
+  }
+
+  /**
+   * This endpoint can be used to disable an alert.
+   */
+  disable(alertConfigurationId: string, options?: Core.RequestOptions): Core.APIPromise<Alert> {
+    return this._client.post(`/alerts/${alertConfigurationId}/disable`, options);
+  }
+
   /**
    * This endpoint can be used to enable an alert.
    */
@@ -13,26 +113,20 @@ export class Alerts extends APIResource {
   }
 }
 
+export class AlertsPage extends Page<Alert> {}
+
 /**
- * An
- * [Alert within Orb](https://docs.withorb.com/guides/product-catalog/configuring-alerts)
- * monitors a customer's spending, usage, or credit balance and triggers a webhook
- * when a threshold is exceeded.
- *
- * Alerts can be configured to monitor usage, cost, or credit balance. Alerts can
- * be scoped to either a customer, a plan, or a subscription.
- *
- * Customer scoped alerts track a customer's credit balance. Valid customer alert
- * types are "credit_balance_depleted", "credit_balance_recovered", and
- * "credit_balance_dropped".
+ * [Alerts within Orb](https://docs.withorb.com/guides/product-catalog/configuring-alerts)
+ * monitor spending, usage, or credit balance and trigger webhooks when a threshold
+ * is exceeded.
  *
- * Subscription scoped alerts track a subscriptions's usage or cost. Valid plan
- * alert types are "usage_exceeded" or "cost_exceeded".
+ * Alerts created through the API can be scoped to either customers or
+ * subscriptions.
  *
- * Plan scoped alerts are similar to subscriptions alerts but when a plan alert is
- * created, it is propagated to all subscriptions associated with the plan.
- * Disabling a plan alert will disable the alert for all subscriptions. Valid plan
- * alert types are "usage_exceeded" or "cost_exceeded".
+ * | Scope        | Monitors                       | Vaild Alert Types                                                                   |
+ * | ------------ | ------------------------------ | ----------------------------------------------------------------------------------- |
+ * | Customer     | A customer's credit balance    | `credit_balance_depleted`, `credit_balance_recovered`, and `credit_balance_dropped` |
+ * | Subscription | A subscription's usage or cost | `usage_exceeded` and `cost_exceeded`                                                |
  */
 export interface Alert {
   /**
@@ -46,12 +140,12 @@ export interface Alert {
   created_at: string;
 
   /**
-   * The name of the currency the credit balance for this alert is denominated in.
+   * The name of the currency the credit balance or invoice cost is denominated in.
    */
   currency: string | null;
 
   /**
-   * The customer that the alert is scoped to.
+   * The customer the alert applies to.
    */
   customer: Record<string, string | null> | null;
 
@@ -60,13 +154,19 @@ export interface Alert {
    */
   enabled: boolean;
 
+  /**
+   * The metric the alert applies to.
+   */
   metric: Record<string, string | null> | null;
 
   /**
-   * The plan that the alert is scoped to.
+   * The plan the alert applies to.
    */
   plan: Record<string, string | null> | null;
 
+  /**
+   * The subscription the alert applies to.
+   */
   subscription: Record<string, string | null> | null;
 
   /**
@@ -78,7 +178,12 @@ export interface Alert {
   /**
    * The type of alert. This must be a valid alert type.
    */
-  type: 'credit_balance_depleted' | 'credit_balance_dropped' | 'credit_balance_recovered';
+  type:
+    | 'usage_exceeded'
+    | 'cost_exceeded'
+    | 'credit_balance_depleted'
+    | 'credit_balance_dropped'
+    | 'credit_balance_recovered';
 }
 
 export namespace Alert {
@@ -88,8 +193,130 @@ export namespace Alert {
    */
   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.
+     * 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 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 thresholds that define the values at which the alert will be triggered.
+   */
+  type: string;
+
+  /**
+   * The thresholds for the alert.
+   */
+  thresholds?: Array<AlertCreateForCustomerParams.Threshold> | null;
+}
+
+export namespace AlertCreateForCustomerParams {
+  /**
+   * 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 AlertCreateForExternalCustomerParams {
+  /**
+   * The case sensitive currency or custom pricing unit to use for this alert.
+   */
+  currency: string;
+
+  /**
+   * The thresholds that define the values at which the alert will be triggered.
+   */
+  type: string;
+
+  /**
+   * The thresholds for the alert.
+   */
+  thresholds?: Array<AlertCreateForExternalCustomerParams.Threshold> | null;
+}
+
+export namespace AlertCreateForExternalCustomerParams {
+  /**
+   * 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 AlertCreateForSubscriptionParams {
+  /**
+   * The thresholds for the alert.
+   */
+  thresholds: Array<AlertCreateForSubscriptionParams.Threshold>;
+
+  /**
+   * The thresholds that define the values at which the alert will be triggered.
+   */
+  type: string;
+
+  /**
+   * The metric to track usage for.
+   */
+  metric_id?: string | null;
+}
+
+export namespace AlertCreateForSubscriptionParams {
+  /**
+   * 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;
   }
@@ -97,4 +324,9 @@ export namespace Alert {
 
 export namespace Alerts {
   export import Alert = AlertsAPI.Alert;
+  export import AlertsPage = AlertsAPI.AlertsPage;
+  export import AlertListParams = AlertsAPI.AlertListParams;
+  export import AlertCreateForCustomerParams = AlertsAPI.AlertCreateForCustomerParams;
+  export import AlertCreateForExternalCustomerParams = AlertsAPI.AlertCreateForExternalCustomerParams;
+  export import AlertCreateForSubscriptionParams = AlertsAPI.AlertCreateForSubscriptionParams;
 }

package/src/resources/customers/costs.ts

@@ -86,11 +86,11 @@ export class Costs extends APIResource {
    *
    * ## Timeframe bounds
    *
-   * If no timeframe bounds are specified, the response will default to the current
-   * billing period for the customer's subscription. For subscriptions that have
-   * ended, this will be the billing period when they were last active. If the
-   * subscription starts or ends within the timeframe, the response will only include
-   * windows where the subscription is active.
+   * For an active subscription, both timeframes should be specified in the request.
+   * If a subscription starts or ends within the timeframe, the response will only
+   * include windows where the subscription is active. If a subscription has ended,
+   * no timeframe bounds need to be specified and the response will default to the
+   * billing period when the subscription was last active.
    *
    * As noted above, `timeframe_start` for a given cumulative datapoint is always the
    * beginning of the billing period, and `timeframe_end` is incremented one day at a
@@ -239,11 +239,11 @@ export class Costs extends APIResource {
    *
    * ## Timeframe bounds
    *
-   * If no timeframe bounds are specified, the response will default to the current
-   * billing period for the customer's subscription. For subscriptions that have
-   * ended, this will be the billing period when they were last active. If the
-   * subscription starts or ends within the timeframe, the response will only include
-   * windows where the subscription is active.
+   * For an active subscription, both timeframes should be specified in the request.
+   * If a subscription starts or ends within the timeframe, the response will only
+   * include windows where the subscription is active. If a subscription has ended,
+   * no timeframe bounds need to be specified and the response will default to the
+   * billing period when the subscription was last active.
    *
    * As noted above, `timeframe_start` for a given cumulative datapoint is always the
    * beginning of the billing period, and `timeframe_end` is incremented one day at a

package/src/resources/events/backfills.ts

@@ -33,6 +33,10 @@ export class Backfills extends APIResource {
    * 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.
    */
   create(body: BackfillCreateParams, options?: Core.RequestOptions): Core.APIPromise<BackfillCreateResponse> {
     return this._client.post('/events/backfills', { body, ...options });

package/src/resources/events/events.ts

@@ -241,7 +241,9 @@ export class Events extends APIResource {
    * 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.
+   * 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.

package/src/resources/index.ts

@@ -1,7 +1,15 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export * from './shared';
-export { Alert, Alerts } from './alerts';
+export {
+  Alert,
+  AlertListParams,
+  AlertCreateForCustomerParams,
+  AlertCreateForExternalCustomerParams,
+  AlertCreateForSubscriptionParams,
+  AlertsPage,
+  Alerts,
+} from './alerts';
 export { Coupon, CouponCreateParams, CouponListParams, CouponsPage, Coupons } from './coupons/coupons';
 export { CreditNote, CreditNoteListParams, CreditNotesPage, CreditNotes } from './credit-notes';
 export {

package/src/resources/subscriptions.ts

@@ -1074,7 +1074,7 @@ export interface Subscription {
   /**
    * Determines whether issued invoices for this subscription will automatically be
    * charged with the saved payment method on the due date. This property defaults to
-   * the plan's behavior.
+   * the plan's behavior. If null, defaults to the customer's setting.
    */
   auto_collection: boolean | null;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '2.5.1'; // x-release-please-version
+export const VERSION = '2.6.1'; // x-release-please-version

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.5.1";
+export declare const VERSION = "2.6.1";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '2.5.1'; // x-release-please-version
+exports.VERSION = '2.6.1'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '2.5.1'; // x-release-please-version
+export const VERSION = '2.6.1'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map