orb-billing 2.2.0 → 2.3.0

package/src/resources/prices/prices.ts

@@ -43,6 +43,37 @@ export class Prices extends APIResource {
     return this._client.getAPIList('/prices', PricesPage, { query, ...options });
   }
 
+  /**
+   * This endpoint is used to evaluate the output of a price for a given customer and
+   * time range. It enables filtering and grouping the output using
+   * [computed properties](../guides/extensibility/advanced-metrics#computed-properties),
+   * supporting the following workflows:
+   *
+   * 1. Showing detailed usage and costs to the end customer.
+   * 2. Auditing subtotals on invoice line items.
+   *
+   * For these workflows, the expressiveness of computed properties in both the
+   * filters and grouping is critical. For example, if you'd like to show your
+   * customer their usage grouped by hour and another property, you can do so with
+   * the following `grouping_keys`:
+   * `["hour_floor_timestamp_millis(timestamp_millis)", "my_property"]`. If you'd
+   * like to examine a customer's usage for a specific property value, you can do so
+   * with the following `filter`:
+   * `my_property = 'foo' AND my_other_property = 'bar'`.
+   *
+   * By default, the start of the time range must be no more than 100 days ago and
+   * the length of the results must be no greater than 1000. Note that this is a POST
+   * endpoint rather than a GET endpoint because it employs a JSON body rather than
+   * query parameters.
+   */
+  evaluate(
+    priceId: string,
+    body: PriceEvaluateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PriceEvaluateResponse> {
+    return this._client.post(`/prices/${priceId}/evaluate`, { body, ...options });
+  }
+
   /**
    * This endpoint returns a price given an identifier.
    */
@@ -53,6 +84,23 @@ export class Prices extends APIResource {
 
 export class PricesPage extends Page<Price> {}
 
+export interface EvaluatePriceGroup {
+  /**
+   * The price's output for the group
+   */
+  amount: string;
+
+  /**
+   * The values for the group in the order specified by `grouping_keys`
+   */
+  grouping_values: Array<string | number | boolean>;
+
+  /**
+   * The price's usage quantity for the group
+   */
+  quantity: number;
+}
+
 /**
  * The Price resource represents a price that can be billed on a subscription,
  * resulting in a charge on an invoice in the form of an invoice line item. Prices
@@ -314,6 +362,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: UnitPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -348,6 +398,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -397,6 +453,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: PackagePrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -431,6 +489,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -486,6 +550,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: MatrixPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -520,6 +586,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -595,6 +667,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -629,6 +703,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -697,6 +777,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredBpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -731,6 +813,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -807,6 +895,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: BpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -851,6 +941,12 @@ export namespace Price {
       per_unit_maximum?: string | null;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -895,6 +991,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: BulkBpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -954,6 +1052,12 @@ export namespace Price {
       }
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -998,6 +1102,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: BulkPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1051,6 +1157,12 @@ export namespace Price {
       }
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1093,6 +1205,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: ThresholdTotalAmountPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1127,6 +1241,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1169,6 +1289,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredPackagePrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1203,6 +1325,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1245,6 +1373,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: GroupedTieredPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1279,6 +1409,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1321,6 +1457,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredWithMinimumPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1355,6 +1493,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1397,6 +1541,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredPackageWithMinimumPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1431,6 +1577,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1473,6 +1625,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: PackageWithAllocationPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1507,6 +1661,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1549,6 +1709,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: UnitWithPercentPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1583,6 +1745,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1625,6 +1793,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: MatrixWithAllocationPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1659,6 +1829,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1731,6 +1907,10 @@ export namespace Price {
   }
 }
 
+export interface PriceEvaluateResponse {
+  data: Array<EvaluatePriceGroup>;
+}
+
 export type PriceCreateParams =
   | PriceCreateParams.NewFloatingUnitPrice
   | PriceCreateParams.NewFloatingPackagePrice
@@ -2844,10 +3024,49 @@ export namespace PriceCreateParams {
 
 export interface PriceListParams extends PageParams {}
 
+export interface PriceEvaluateParams {
+  /**
+   * The exclusive upper bound for event timestamps
+   */
+  timeframe_end: string;
+
+  /**
+   * The inclusive lower bound for event timestamps
+   */
+  timeframe_start: string;
+
+  /**
+   * The ID of the customer to which this evaluation is scoped.
+   */
+  customer_id?: string | null;
+
+  /**
+   * The external customer ID of the customer to which this evaluation is scoped.
+   */
+  external_customer_id?: string | null;
+
+  /**
+   * A boolean
+   * [computed property](../guides/extensibility/advanced-metrics#computed-properties)
+   * used to filter the underlying billable metric
+   */
+  filter?: string | null;
+
+  /**
+   * Properties (or
+   * [computed properties](../guides/extensibility/advanced-metrics#computed-properties))
+   * used to group the underlying billable metric
+   */
+  grouping_keys?: Array<string>;
+}
+
 export namespace Prices {
+  export import EvaluatePriceGroup = PricesAPI.EvaluatePriceGroup;
   export import Price = PricesAPI.Price;
+  export import PriceEvaluateResponse = PricesAPI.PriceEvaluateResponse;
   export import PricesPage = PricesAPI.PricesPage;
   export import PriceCreateParams = PricesAPI.PriceCreateParams;
   export import PriceListParams = PricesAPI.PriceListParams;
+  export import PriceEvaluateParams = PricesAPI.PriceEvaluateParams;
   export import ExternalPriceID = ExternalPriceIDAPI.ExternalPriceID;
 }

package/src/resources/shared.ts

@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export type BillingCycleRelativeDate = 'start_of_term' | 'end_of_term';
+
 export type Discount =
   | Discount.PercentageDiscount
   | Discount.TrialDiscount
@@ -82,3 +84,9 @@ export namespace Discount {
     reason?: string | null;
   }
 }
+
+export interface PaginationMetadata {
+  has_more: boolean;
+
+  next_cursor: string | null;
+}

package/src/resources/subscriptions.ts

@@ -4,6 +4,7 @@ import * as Core from "../core";
 import { APIResource } from "../resource";
 import { isRequestOptions } from "../core";
 import * as SubscriptionsAPI from "./subscriptions";
+import * as Shared from "./shared";
 import * as CustomersAPI from "./customers/customers";
 import * as PlansAPI from "./plans/plans";
 import * as PricesAPI from "./prices/prices";
@@ -414,6 +415,28 @@ export class Subscriptions extends APIResource {
     return this._client.post('/subscriptions', { body, ...options });
   }
 
+  /**
+   * This endpoint can be used to update the `metadata`, `net terms`,
+   * `auto_collection`, `invoicing_threshold`, and `default_invoice_memo` properties
+   * on a subscription.
+   */
+  update(
+    subscriptionId: string,
+    body?: SubscriptionUpdateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<Subscription>;
+  update(subscriptionId: string, options?: Core.RequestOptions): Core.APIPromise<Subscription>;
+  update(
+    subscriptionId: string,
+    body: SubscriptionUpdateParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<Subscription> {
+    if (isRequestOptions(body)) {
+      return this.update(subscriptionId, {}, body);
+    }
+    return this._client.put(`/subscriptions/${subscriptionId}`, { body, ...options });
+  }
+
   /**
    * This endpoint returns a list of all subscriptions for an account as a
    * [paginated](../reference/pagination) list, ordered starting from the most
@@ -1670,7 +1693,7 @@ export namespace SubscriptionUsage {
   export interface GroupedSubscriptionUsage {
     data: Array<GroupedSubscriptionUsage.Data>;
 
-    pagination_metadata?: GroupedSubscriptionUsage.PaginationMetadata | null;
+    pagination_metadata?: Shared.PaginationMetadata | null;
   }
 
   export namespace GroupedSubscriptionUsage {
@@ -1705,27 +1728,13 @@ export namespace SubscriptionUsage {
         timeframe_start: string;
       }
     }
-
-    export interface PaginationMetadata {
-      has_more: boolean;
-
-      next_cursor: string | null;
-    }
   }
 }
 
 export interface Subscriptions {
   data: Array<Subscription>;
 
-  pagination_metadata: Subscriptions.PaginationMetadata;
-}
-
-export namespace Subscriptions {
-  export interface PaginationMetadata {
-    has_more: boolean;
-
-    next_cursor: string | null;
-  }
+  pagination_metadata: Shared.PaginationMetadata;
 }
 
 export interface SubscriptionFetchCostsResponse {
@@ -3121,6 +3130,43 @@ export namespace SubscriptionCreateParams {
   }
 }
 
+export interface SubscriptionUpdateParams {
+  /**
+   * 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.
+   */
+  auto_collection?: boolean | null;
+
+  /**
+   * Determines the default memo on this subscription's invoices. Note that if this
+   * is not provided, it is determined by the plan configuration.
+   */
+  default_invoice_memo?: string | null;
+
+  /**
+   * When this subscription's accrued usage reaches this threshold, an invoice will
+   * be issued for the subscription. If not specified, invoices will only be issued
+   * at the end of the billing period.
+   */
+  invoicing_threshold?: string | null;
+
+  /**
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
+   */
+  metadata?: Record<string, string | null> | null;
+
+  /**
+   * Determines the difference between the invoice issue date for subscription
+   * invoices as the date that they are due. A value of `0` here represents that the
+   * invoice is due on issue, whereas a value of `30` represents that the customer
+   * has a month to pay the invoice.
+   */
+  net_terms?: number | null;
+}
+
 export interface SubscriptionListParams extends PageParams {
   'created_at[gt]'?: string | null;
 
@@ -3255,7 +3301,7 @@ export namespace SubscriptionPriceIntervalsParams {
      * The start date of the price interval. This is the date that the price will start
      * billing on the subscription.
      */
-    start_date: (string & {}) | 'start_of_term' | 'end_of_term';
+    start_date: (string & {}) | Shared.BillingCycleRelativeDate;
 
     /**
      * A list of discounts to initialize on the price interval.
@@ -3270,7 +3316,7 @@ export namespace SubscriptionPriceIntervalsParams {
      * The end date of the price interval. This is the date that the price will stop
      * billing on the subscription.
      */
-    end_date?: (string & {}) | 'start_of_term' | 'end_of_term' | null;
+    end_date?: (string & {}) | Shared.BillingCycleRelativeDate | null;
 
     /**
      * The external price id of the price to add to the subscription.
@@ -4473,7 +4519,7 @@ export namespace SubscriptionPriceIntervalsParams {
      * The updated end date of this price interval. If not specified, the start date
      * will not be updated.
      */
-    end_date?: (string & {}) | 'start_of_term' | 'end_of_term' | null;
+    end_date?: (string & {}) | Shared.BillingCycleRelativeDate | null;
 
     /**
      * A list of fixed fee quantity transitions to use for this price interval. Note
@@ -4486,7 +4532,7 @@ export namespace SubscriptionPriceIntervalsParams {
      * The updated start date of this price interval. If not specified, the start date
      * will not be updated.
      */
-    start_date?: (string & {}) | 'start_of_term' | 'end_of_term';
+    start_date?: (string & {}) | Shared.BillingCycleRelativeDate;
   }
 
   export namespace Edit {
@@ -5646,6 +5692,7 @@ export namespace Subscriptions {
   export import SubscriptionsPage = SubscriptionsAPI.SubscriptionsPage;
   export import SubscriptionFetchScheduleResponsesPage = SubscriptionsAPI.SubscriptionFetchScheduleResponsesPage;
   export import SubscriptionCreateParams = SubscriptionsAPI.SubscriptionCreateParams;
+  export import SubscriptionUpdateParams = SubscriptionsAPI.SubscriptionUpdateParams;
   export import SubscriptionListParams = SubscriptionsAPI.SubscriptionListParams;
   export import SubscriptionCancelParams = SubscriptionsAPI.SubscriptionCancelParams;
   export import SubscriptionFetchCostsParams = SubscriptionsAPI.SubscriptionFetchCostsParams;

package/src/resources/webhooks.ts

@@ -2,7 +2,7 @@
 
 import { APIResource } from "../resource";
 import { createHmac } from 'crypto';
-import { getRequiredHeader, HeadersLike } from "../core";
+import { debug, getRequiredHeader, HeadersLike } from "../core";
 
 export class Webhooks extends APIResource {
   /**
@@ -93,7 +93,9 @@ export class Webhooks extends APIResource {
     const msgSignature = getRequiredHeader(headers, 'X-Orb-Signature');
 
     const nowSeconds = Math.floor(Date.now() / 1000);
-    const timestamp = new Date(msgTimestamp);
+    // The timestamp header does not include a timezone (it is UTC by default)
+    const timezoneSuffix = msgTimestamp.includes('Z') || msgTimestamp.includes('+') ? '' : 'Z'
+    const timestamp = new Date(msgTimestamp + timezoneSuffix);
     const timestampSeconds = Math.floor(timestamp.getTime() / 1000);
     if (isNaN(timestampSeconds)) {
       throw new Error('Invalid timestamp header');
@@ -123,7 +125,7 @@ export class Webhooks extends APIResource {
     const encoder = new globalThis.TextEncoder();
     for (const versionedSignature of passedSignatures) {
       const [version, signature] = versionedSignature.split('=');
-      console.log({ version, signature, expectedSignature, computedSignature });
+      debug('verifySignature', { version, signature, expectedSignature, computedSignature });
 
       if (version !== 'v1') {
         continue;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '2.2.0'; // x-release-please-version
+export const VERSION = '2.3.0'; // x-release-please-version

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.2.0";
+export declare const VERSION = "2.3.0";
 //# 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.2.0'; // x-release-please-version
+exports.VERSION = '2.3.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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