diff --git a/.stats.yml b/.stats.yml index 339e187..e1458a6 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 90 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb-513711d9c7ecfa388704769b0eacdfaef1752c88942b061c28f4239260089651.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb-0b1c2d4534e85da8966d80448ccc6bf4db184f0d5642478af14ba4c9eeadafed.yml diff --git a/src/resources/alerts.ts b/src/resources/alerts.ts index 60a3f0b..3675f09 100644 --- a/src/resources/alerts.ts +++ b/src/resources/alerts.ts @@ -15,18 +15,17 @@ export class Alerts extends APIResource { } /** - * This endpoint returns a list of all - * [`alerts`](https://docs.withorb.com/guides/product-catalog/configuring-alerts). + * This endpoint returns a list of alerts within Orb. * - * The list of alerts is ordered starting from the most recently created alert. - * This endpoint follows Orb's - * [standardized pagination format](../reference/pagination). - * - * The request must specify one of customer_id, external_customer_id, - * subscription_id, or plan_id + * 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; list(options?: Core.RequestOptions): Core.PagePromise; @@ -86,11 +85,12 @@ export class Alerts extends APIResource { * * Plan level alerts can be 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 a predefined thresholds during the current - * invoice cycle. A `cost_exceeded` alert is triggered when the total cost of the - * subscription on the plan surpasses predefined thresholds in the current invoice - * cycle.Each plan can have one `cost_exceeded` alert and one `usage_exceeded` - * alert per metric that is apart of the plan. + * 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 + * plan can have one `cost_exceeded` alert and one `usage_exceeded` alert per + * metric that is a part of the plan. */ createForPlan( planId: string, @@ -105,13 +105,13 @@ export class Alerts extends APIResource { * * 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 a predefined thresholds - * during the current invoice cycle. A `cost_exceeded` alert is triggered when the - * total cost of the subscription surpasses predefined thresholds in the current - * invoice cycle. Each subscription can have one `cost_exceeded` alert and one - * `usage_exceeded` alert per metric that is apart of the subscription. Alerts are - * triggered based on usage or cost conditions met during the current invoice - * cycle. + * 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, @@ -123,11 +123,6 @@ export class Alerts extends APIResource { /** * This endpoint can be used to disable an alert. - * - * By default, disabling a plan level alert will apply to all subscriptions on that - * plan. In order to toggle a plan level alert for a specific subscription, the - * client must provide the plan level alert id as well as the subscription_id - * parameter. */ disable( alertConfigurationId: string, @@ -152,11 +147,6 @@ export class Alerts extends APIResource { /** * This endpoint can be used to enable an alert. - * - * By default, enabling a plan level alert will apply to all subscriptions on that - * plan. In order to toggle a plan level alert for a specific subscription, the - * client must provide the plan level alert id as well as the subscription_id - * parameter. */ enable( alertConfigurationId: string, @@ -183,25 +173,17 @@ export class Alerts extends APIResource { export class AlertsPage extends Page {} /** - * 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 { /** @@ -215,7 +197,7 @@ 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; @@ -268,8 +250,9 @@ 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; } @@ -334,8 +317,9 @@ export namespace AlertCreateForCustomerParams { */ 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; } @@ -365,8 +349,9 @@ export namespace AlertCreateForExternalCustomerParams { */ 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; } @@ -389,7 +374,8 @@ export interface AlertCreateForPlanParams { metric_id?: string | null; /** - * The plan version to create alerts for. If not specified, the default will be the plan's active plan version. + * The plan version to create alerts for. If not specified, the default will be the + * plan's active plan version. */ plan_version?: number | null; } @@ -401,8 +387,9 @@ export namespace AlertCreateForPlanParams { */ 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; } @@ -432,8 +419,9 @@ export namespace AlertCreateForSubscriptionParams { */ 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; } diff --git a/src/resources/customers/costs.ts b/src/resources/customers/costs.ts index aa6373f..b6b9028 100644 --- a/src/resources/customers/costs.ts +++ b/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 diff --git a/src/resources/events/backfills.ts b/src/resources/events/backfills.ts index 573f04c..5234725 100644 --- a/src/resources/events/backfills.ts +++ b/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 { return this._client.post('/events/backfills', { body, ...options }); diff --git a/src/resources/events/events.ts b/src/resources/events/events.ts index dd125d1..77e71b6 100644 --- a/src/resources/events/events.ts +++ b/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.