orb-billing 2.1.2 → 2.3.0

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.
@@ -3309,6 +3355,7 @@ export namespace SubscriptionPriceIntervalsParams {
       | Add.NewFloatingBulkPrice
       | Add.NewFloatingThresholdTotalAmountPrice
       | Add.NewFloatingTieredPackagePrice
+      | Add.NewFloatingGroupedTieredPrice
       | Add.NewFloatingTieredWithMinimumPrice
       | Add.NewFloatingPackageWithAllocationPrice
       | Add.NewFloatingTieredPackageWithMinimumPrice
@@ -4184,6 +4231,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.
@@ -4418,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
@@ -4431,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 {
@@ -5591,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

@@ -0,0 +1,142 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import { APIResource } from "../resource";
+import { createHmac } from 'crypto';
+import { debug, 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);
+    // 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');
+    }
+
+    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('=');
+      debug('verifySignature', { 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.2'; // 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.1.2";
+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.1.2'; // 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.1.2'; // x-release-please-version
+export const VERSION = '2.3.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map