orb-billing 2.1.1 → 2.2.0

package/src/index.ts

@@ -14,6 +14,11 @@ export interface ClientOptions {
    */
   apiKey?: string | undefined;
 
+  /**
+   * Defaults to process.env['ORB_WEBHOOK_SECRET'].
+   */
+  webhookSecret?: string | null | undefined;
+
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
@@ -74,6 +79,7 @@ export interface ClientOptions {
 /** API Client for interfacing with the Orb API. */
 export class Orb extends Core.APIClient {
   apiKey: string;
+  webhookSecret: string | null;
 
   private _options: ClientOptions;
 
@@ -81,6 +87,7 @@ export class Orb extends Core.APIClient {
    * API Client for interfacing with the Orb API.
    *
    * @param {string | undefined} [opts.apiKey=process.env['ORB_API_KEY'] ?? undefined]
+   * @param {string | null | undefined} [opts.webhookSecret=process.env['ORB_WEBHOOK_SECRET'] ?? null]
    * @param {string} [opts.baseURL=process.env['ORB_BASE_URL'] ?? https://api.withorb.com/v1] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
@@ -92,6 +99,7 @@ export class Orb extends Core.APIClient {
   constructor({
     baseURL = Core.readEnv('ORB_BASE_URL'),
     apiKey = Core.readEnv('ORB_API_KEY'),
+    webhookSecret = Core.readEnv('ORB_WEBHOOK_SECRET') ?? null,
     ...opts
   }: ClientOptions = {}) {
     if (apiKey === undefined) {
@@ -102,6 +110,7 @@ export class Orb extends Core.APIClient {
 
     const options: ClientOptions = {
       apiKey,
+      webhookSecret,
       ...opts,
       baseURL: baseURL || `https://api.withorb.com/v1`,
     };
@@ -117,6 +126,7 @@ export class Orb extends Core.APIClient {
     this.idempotencyHeader = 'Idempotency-Key';
 
     this.apiKey = apiKey;
+    this.webhookSecret = webhookSecret;
   }
 
   topLevel: API.TopLevel = new API.TopLevel(this);
@@ -132,6 +142,7 @@ export class Orb extends Core.APIClient {
   prices: API.Prices = new API.Prices(this);
   subscriptions: API.Subscriptions = new API.Subscriptions(this);
   beta: API.Beta = new API.Beta(this);
+  webhooks: API.Webhooks = new API.Webhooks(this);
 
   protected override defaultQuery(): Core.DefaultQuery | undefined {
     return this._options.defaultQuery;

package/src/resources/customers/credits/ledger.ts

@@ -2084,8 +2084,8 @@ export namespace LedgerCreateEntryParams {
     metadata?: Record<string, string | null> | null;
 
     /**
-     * Can only be specified when entry_type=increment. How much, in USD, a customer
-     * paid for a single credit in this block
+     * Can only be specified when entry_type=increment. How much, in the customer's
+     * currency, a customer paid for a single credit in this block
      */
     per_unit_cost_basis?: string | null;
   }
@@ -2329,8 +2329,8 @@ export namespace LedgerCreateEntryByExternalIDParams {
     metadata?: Record<string, string | null> | null;
 
     /**
-     * Can only be specified when entry_type=increment. How much, in USD, a customer
-     * paid for a single credit in this block
+     * Can only be specified when entry_type=increment. How much, in the customer's
+     * currency, a customer paid for a single credit in this block
      */
     per_unit_cost_basis?: string | null;
   }

package/src/resources/index.ts

@@ -71,3 +71,4 @@ export {
   SubscriptionFetchScheduleResponsesPage,
 } from './subscriptions';
 export { TopLevelPingResponse, TopLevel } from './top-level';
+export { Webhooks } from './webhooks';

package/src/resources/invoices.ts

@@ -273,6 +273,8 @@ export interface Invoice {
    */
   invoice_pdf: string | null;
 
+  invoice_source: 'subscription' | 'partial' | 'one_off';
+
   /**
    * If the invoice failed to issue, this will be the last time it failed to issue
    * (even if it is now in a different state.)
@@ -1353,6 +1355,8 @@ export interface InvoiceFetchUpcomingResponse {
    */
   invoice_pdf: string | null;
 
+  invoice_source: 'subscription' | 'partial' | 'one_off';
+
   /**
    * If the invoice failed to issue, this will be the last time it failed to issue
    * (even if it is now in a different state.)

package/src/resources/prices/prices.ts

@@ -297,7 +297,9 @@ export type Price =
   | Price.BulkPrice
   | Price.ThresholdTotalAmountPrice
   | Price.TieredPackagePrice
+  | Price.GroupedTieredPrice
   | Price.TieredWithMinimumPrice
+  | Price.TieredPackageWithMinimumPrice
   | Price.PackageWithAllocationPrice
   | Price.UnitWithPercentPrice
   | Price.MatrixWithAllocationPrice;
@@ -1234,6 +1236,82 @@ export namespace Price {
     }
   }
 
+  export interface GroupedTieredPrice {
+    id: string;
+
+    billable_metric: GroupedTieredPrice.BillableMetric | null;
+
+    cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+
+    created_at: string;
+
+    currency: string;
+
+    discount: Shared.Discount | null;
+
+    external_price_id: string | null;
+
+    fixed_price_quantity: number | null;
+
+    grouped_tiered_config: Record<string, unknown>;
+
+    item: GroupedTieredPrice.Item;
+
+    maximum: GroupedTieredPrice.Maximum | null;
+
+    maximum_amount: string | null;
+
+    minimum: GroupedTieredPrice.Minimum | null;
+
+    minimum_amount: string | null;
+
+    model_type: 'grouped_tiered';
+
+    name: string;
+
+    plan_phase_order: number | null;
+
+    price_type: 'usage_price' | 'fixed_price';
+  }
+
+  export namespace GroupedTieredPrice {
+    export interface BillableMetric {
+      id: string;
+    }
+
+    export interface Item {
+      id: string;
+
+      name: string;
+    }
+
+    export interface Maximum {
+      /**
+       * List of price_ids that this maximum amount applies to. For plan/plan phase
+       * maximums, this can be a subset of prices.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * Maximum amount applied
+       */
+      maximum_amount: string;
+    }
+
+    export interface Minimum {
+      /**
+       * List of price_ids that this minimum amount applies to. For plan/plan phase
+       * minimums, this can be a subset of prices.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * Minimum amount applied
+       */
+      minimum_amount: string;
+    }
+  }
+
   export interface TieredWithMinimumPrice {
     id: string;
 
@@ -1310,6 +1388,82 @@ export namespace Price {
     }
   }
 
+  export interface TieredPackageWithMinimumPrice {
+    id: string;
+
+    billable_metric: TieredPackageWithMinimumPrice.BillableMetric | null;
+
+    cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+
+    created_at: string;
+
+    currency: string;
+
+    discount: Shared.Discount | null;
+
+    external_price_id: string | null;
+
+    fixed_price_quantity: number | null;
+
+    item: TieredPackageWithMinimumPrice.Item;
+
+    maximum: TieredPackageWithMinimumPrice.Maximum | null;
+
+    maximum_amount: string | null;
+
+    minimum: TieredPackageWithMinimumPrice.Minimum | null;
+
+    minimum_amount: string | null;
+
+    model_type: 'tiered_package_with_minimum';
+
+    name: string;
+
+    plan_phase_order: number | null;
+
+    price_type: 'usage_price' | 'fixed_price';
+
+    tiered_package_with_minimum_config: Record<string, unknown>;
+  }
+
+  export namespace TieredPackageWithMinimumPrice {
+    export interface BillableMetric {
+      id: string;
+    }
+
+    export interface Item {
+      id: string;
+
+      name: string;
+    }
+
+    export interface Maximum {
+      /**
+       * List of price_ids that this maximum amount applies to. For plan/plan phase
+       * maximums, this can be a subset of prices.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * Maximum amount applied
+       */
+      maximum_amount: string;
+    }
+
+    export interface Minimum {
+      /**
+       * List of price_ids that this minimum amount applies to. For plan/plan phase
+       * minimums, this can be a subset of prices.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * Minimum amount applied
+       */
+      minimum_amount: string;
+    }
+  }
+
   export interface PackageWithAllocationPrice {
     id: string;
 
@@ -1589,6 +1743,7 @@ export type PriceCreateParams =
   | PriceCreateParams.NewFloatingBulkPrice
   | PriceCreateParams.NewFloatingThresholdTotalAmountPrice
   | PriceCreateParams.NewFloatingTieredPackagePrice
+  | PriceCreateParams.NewFloatingGroupedTieredPrice
   | PriceCreateParams.NewFloatingTieredWithMinimumPrice
   | PriceCreateParams.NewFloatingPackageWithAllocationPrice
   | PriceCreateParams.NewFloatingTieredPackageWithMinimumPrice
@@ -2416,6 +2571,60 @@ export namespace PriceCreateParams {
     invoice_grouping_key?: string | null;
   }
 
+  export interface NewFloatingGroupedTieredPrice {
+    /**
+     * The cadence to bill for this price on.
+     */
+    cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+
+    /**
+     * An ISO 4217 currency string for which this price is billed in.
+     */
+    currency: string;
+
+    grouped_tiered_config: Record<string, unknown>;
+
+    /**
+     * The id of the item the plan will be associated with.
+     */
+    item_id: string;
+
+    model_type: 'grouped_tiered';
+
+    /**
+     * The name of the price.
+     */
+    name: string;
+
+    /**
+     * The id of the billable metric for the price. Only needed if the price is
+     * usage-based.
+     */
+    billable_metric_id?: string | null;
+
+    /**
+     * If the Price represents a fixed cost, the price will be billed in-advance if
+     * this is true, and in-arrears if this is false.
+     */
+    billed_in_advance?: boolean | null;
+
+    /**
+     * An alias for the price.
+     */
+    external_price_id?: string | null;
+
+    /**
+     * If the Price represents a fixed cost, this represents the quantity of units
+     * applied.
+     */
+    fixed_price_quantity?: number | null;
+
+    /**
+     * The property used to group this price on an invoice
+     */
+    invoice_grouping_key?: string | null;
+  }
+
   export interface NewFloatingTieredWithMinimumPrice {
     /**
      * The cadence to bill for this price on.

package/src/resources/subscriptions.ts

@@ -3309,6 +3309,7 @@ export namespace SubscriptionPriceIntervalsParams {
       | Add.NewFloatingBulkPrice
       | Add.NewFloatingThresholdTotalAmountPrice
       | Add.NewFloatingTieredPackagePrice
+      | Add.NewFloatingGroupedTieredPrice
       | Add.NewFloatingTieredWithMinimumPrice
       | Add.NewFloatingPackageWithAllocationPrice
       | Add.NewFloatingTieredPackageWithMinimumPrice
@@ -4184,6 +4185,60 @@ export namespace SubscriptionPriceIntervalsParams {
       invoice_grouping_key?: string | null;
     }
 
+    export interface NewFloatingGroupedTieredPrice {
+      /**
+       * The cadence to bill for this price on.
+       */
+      cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+
+      /**
+       * An ISO 4217 currency string for which this price is billed in.
+       */
+      currency: string;
+
+      grouped_tiered_config: Record<string, unknown>;
+
+      /**
+       * The id of the item the plan will be associated with.
+       */
+      item_id: string;
+
+      model_type: 'grouped_tiered';
+
+      /**
+       * The name of the price.
+       */
+      name: string;
+
+      /**
+       * The id of the billable metric for the price. Only needed if the price is
+       * usage-based.
+       */
+      billable_metric_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, the price will be billed in-advance if
+       * this is true, and in-arrears if this is false.
+       */
+      billed_in_advance?: boolean | null;
+
+      /**
+       * An alias for the price.
+       */
+      external_price_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, this represents the quantity of units
+       * applied.
+       */
+      fixed_price_quantity?: number | null;
+
+      /**
+       * The property used to group this price on an invoice
+       */
+      invoice_grouping_key?: string | null;
+    }
+
     export interface NewFloatingTieredWithMinimumPrice {
       /**
        * The cadence to bill for this price on.

package/src/resources/webhooks.ts

@@ -0,0 +1,140 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import { APIResource } from "../resource";
+import { createHmac } from 'crypto';
+import { getRequiredHeader, HeadersLike } from "../core";
+
+export class Webhooks extends APIResource {
+  /**
+   * Validates that the given payload was sent by Orb and parses the payload.
+   *
+   * An error will be raised if the webhook payload was not sent by Orb.
+   */
+  unwrap(
+    payload: string,
+    headers: HeadersLike,
+    secret: string | undefined | null = this._client.webhookSecret,
+  ): Object {
+    this.verifySignature(payload, headers, secret);
+    return JSON.parse(payload);
+  }
+
+  private parseSecret(secret: string | null | undefined): Uint8Array {
+    if (!secret) {
+      throw new Error(
+        "The webhook secret must either be set using the env var, ORB_WEBHOOK_SECRET, on the client class, Orb({ webhookSecret: '123' }), or passed to this function",
+      );
+    }
+
+    const buf = Buffer.from(secret, 'utf-8');
+    if (buf.toString('utf-8') !== secret) {
+      throw new Error(`Given secret is not valid`);
+    }
+
+    return new Uint8Array(buf);
+  }
+
+  private signPayload(payload: string, { timestamp, secret }: { timestamp: string; secret: Uint8Array }) {
+    const encoder = new TextEncoder();
+    const toSign = encoder.encode(`v1:${timestamp}:${payload}`);
+
+    const hmac = createHmac('sha256', secret);
+    hmac.update(toSign);
+
+    return `v1=${hmac.digest('hex')}`;
+  }
+
+  /** Make an assertion, if not `true`, then throw. */
+  private assert(expr: unknown, msg = ''): asserts expr {
+    if (!expr) {
+      throw new Error(msg);
+    }
+  }
+
+  /** Compare to array buffers or data views in a way that timing based attacks
+   * cannot gain information about the platform. */
+  private timingSafeEqual(
+    a: ArrayBufferView | ArrayBufferLike | DataView,
+    b: ArrayBufferView | ArrayBufferLike | DataView,
+  ): boolean {
+    if (a.byteLength !== b.byteLength) {
+      return false;
+    }
+    if (!(a instanceof DataView)) {
+      a = new DataView(ArrayBuffer.isView(a) ? a.buffer : a);
+    }
+    if (!(b instanceof DataView)) {
+      b = new DataView(ArrayBuffer.isView(b) ? b.buffer : b);
+    }
+    this.assert(a instanceof DataView);
+    this.assert(b instanceof DataView);
+    const length = a.byteLength;
+    let out = 0;
+    let i = -1;
+    while (++i < length) {
+      out |= a.getUint8(i) ^ b.getUint8(i);
+    }
+    return out === 0;
+  }
+
+  /**
+   * Validates whether or not the webhook payload was sent by Orb.
+   *
+   * An error will be raised if the webhook payload was not sent by Orb.
+   */
+  verifySignature(
+    body: string,
+    headers: HeadersLike,
+    secret: string | undefined | null = this._client.webhookSecret,
+  ): void {
+    const whsecret = this.parseSecret(secret);
+
+    const msgTimestamp = getRequiredHeader(headers, 'X-Orb-Timestamp');
+    const msgSignature = getRequiredHeader(headers, 'X-Orb-Signature');
+
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const timestamp = new Date(msgTimestamp);
+    const timestampSeconds = Math.floor(timestamp.getTime() / 1000);
+    if (isNaN(timestampSeconds)) {
+      throw new Error('Invalid timestamp header');
+    }
+
+    const webhookToleranceInSeconds = 5 * 60; // 5 minutes
+    if (nowSeconds - timestampSeconds > webhookToleranceInSeconds) {
+      throw new Error('Webhook timestamp is too old');
+    }
+
+    if (timestampSeconds > nowSeconds + webhookToleranceInSeconds) {
+      console.warn({ timestampSeconds, nowSeconds, webhookToleranceInSeconds });
+      throw new Error('Webhook timestamp is too new');
+    }
+
+    if (typeof body !== 'string') {
+      throw new Error(
+        'Webhook body must be passed as the raw JSON string sent from the server (do not parse it first).',
+      );
+    }
+
+    const computedSignature = this.signPayload(body, { timestamp: msgTimestamp, secret: whsecret });
+    const expectedSignature = computedSignature.split('=')[1];
+
+    const passedSignatures = msgSignature.split(' ');
+
+    const encoder = new globalThis.TextEncoder();
+    for (const versionedSignature of passedSignatures) {
+      const [version, signature] = versionedSignature.split('=');
+      console.log({ version, signature, expectedSignature, computedSignature });
+
+      if (version !== 'v1') {
+        continue;
+      }
+
+      if (this.timingSafeEqual(encoder.encode(signature), encoder.encode(expectedSignature))) {
+        // valid!
+        return;
+      }
+    }
+
+    throw new Error('None of the given webhook signatures match the expected signature');
+  }
+}

package/src/version.ts

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

package/version.d.ts

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

package/version.mjs

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